stdtime/FreeBSD/ctime.3.patch

   1 --- _SB/Libc/stdtime/FreeBSD/ctime.3    2004-11-25 11:38:44.000000000 -0800
   2 +++ _SB/Libc/stdtime/FreeBSD/ctime.3.edit       2006-06-28 16:55:53.000000000 -0700
   3 @@ -56,31 +56,31 @@
   4  .In time.h
   5  .Vt extern char *tzname[2] ;
   6  .Ft char *
   7 +.Fn asctime "const struct tm *timeptr"
   8 +.Ft char *
   9 +.Fn asctime_r "const struct tm *restrict timeptr" "char *restrict buf"
  10 +.Ft char *
  11  .Fn ctime "const time_t *clock"
  12 +.Ft char *
  13 +.Fn ctime_r "const time_t *clock" "char *buf"
  14  .Ft double
  15  .Fn difftime "time_t time1" "time_t time0"
  16 -.Ft char *
  17 -.Fn asctime "const struct tm *tm"
  18 +.Ft struct tm *
  19 +.Fn gmtime "const time_t *clock"
  20 +.Ft struct tm *
  21 +.Fn gmtime_r "const time_t *clock" "struct tm *result"
  22  .Ft struct tm *
  23  .Fn localtime "const time_t *clock"
  24  .Ft struct tm *
  25 -.Fn gmtime "const time_t *clock"
  26 +.Fn localtime_r "const time_t *clock" "struct tm *result"
  27  .Ft time_t
  28 -.Fn mktime "struct tm *tm"
  29 +.Fn mktime "struct tm *timeptr"
  30  .Ft time_t
  31 -.Fn timegm "struct tm *tm"
  32 -.Ft char *
  33 -.Fn ctime_r "const time_t *clock" "char *buf"
  34 -.Ft struct tm *
  35 -.Fn localtime_r "const time_t *clock" "struct tm *result"
  36 -.Ft struct tm *
  37 -.Fn gmtime_r "const time_t *clock" "struct tm *result"
  38 -.Ft char *
  39 -.Fn asctime_r "const struct tm *tm" "char *buf"
  40 +.Fn timegm "struct tm *timeptr"
  41  .Sh DESCRIPTION
  42  The functions
  43  .Fn ctime ,
  44 -.Fn gmtime
  45 +.Fn gmtime ,
  46  and
  47  .Fn localtime
  48  all take as an argument a time value representing the time in seconds since
  49 @@ -92,10 +92,10 @@
  50  The function
  51  .Fn localtime
  52  converts the time value pointed at by
  53 -.Fa clock ,
  54 -and returns a pointer to a
  55 +.Fa clock .
  56 +It returns a pointer to a
  57  .Dq Fa struct tm
  58 -(described below) which contains
  59 +(described below), which contains
  60  the broken-out time information for the value after adjusting for the current
  61  time zone (and any other factors such as Daylight Saving Time).
  62  Time zone adjustments are performed as specified by the
  63 @@ -106,7 +106,7 @@
  64  .Fn localtime
  65  uses
  66  .Xr tzset 3
  67 -to initialize time conversion information if
  68 +to initialize time conversion information, if
  69  .Xr tzset 3
  70  has not already been called by the process.
  71  .Pp
  72 @@ -118,36 +118,36 @@
  73  .Fa tzname
  74  to a pointer to an
  75  .Tn ASCII
  76 -string that's the time zone abbreviation to be
  77 +string containing the time zone abbreviation to be
  78  used with
  79  .Fn localtime Ns 's
  80  return value.
  81  .Pp
  82  The function
  83  .Fn gmtime
  84 -similarly converts the time value, but without any time zone adjustment,
  85 -and returns a pointer to a tm structure (described below).
  86 +also converts the time value, but makes no time zone adjustment.
  87 +It returns a pointer to a tm structure (described below).
  88  .Pp
  89  The
  90  .Fn ctime
  91  function
  92 -adjusts the time value for the current time zone in the same manner as
  93 -.Fn localtime ,
  94 -and returns a pointer to a 26-character string of the form:
  95 +adjusts the time value for the current time zone, in the same manner as
  96 +.Fn localtime .
  97 +It returns a pointer to a 26-character string of the form:
  98  .Bd -literal -offset indent
  99  Thu Nov 24 18:22:48 1986\en\e0
 100  .Ed
 101  .Pp
 102 -All the fields have constant width.
 103 +All of the fields have constant width.
 104  .Pp
 105  The
 106  .Fn ctime_r
 107  function
 108  provides the same functionality as
 109 -.Fn ctime
 110 -except the caller must provide the output buffer
 111 +.Fn ctime ,
 112 +except that the caller must provide the output buffer
 113  .Fa buf
 114 -to store the result, which must be at least 26 characters long.
 115 +(which must be at least 26 characters long) to store the result.
 116  The
 117  .Fn localtime_r
 118  and
 119 @@ -156,17 +156,17 @@
 120  provide the same functionality as
 121  .Fn localtime
 122  and
 123 -.Fn gmtime
 124 +.Fn gmtime ,
 125  respectively, except the caller must provide the output buffer
 126  .Fa result .
 127  .Pp
 128  The
 129  .Fn asctime
 130  function
 131 -converts the broken down time in the structure
 132 +converts the broken-out time in the structure
 133  .Fa tm
 134 -pointed at by
 135 -.Fa *tm
 136 +(pointed at by
 137 +.Fa *timeptr )
 138  to the form
 139  shown in the example above.
 140  .Pp
 141 @@ -174,17 +174,19 @@
 142  .Fn asctime_r
 143  function
 144  provides the same functionality as
 145 -.Fn asctime
 146 -except the caller provide the output buffer
 147 +.Fn asctime ,
 148 +except that the caller provides the output buffer
 149  .Fa buf
 150 -to store the result, which must be at least 26 characters long.
 151 +(which must be at least 26 characters long) to store the result.
 152  .Pp
 153  The functions
 154  .Fn mktime
 155  and
 156  .Fn timegm
 157 -convert the broken-down time in the structure
 158 -pointed to by tm into a time value with the same encoding as that of the
 159 +convert the broken-out time
 160 +(in the structure pointed to by
 161 +.Fa *timeptr )
 162 +into a time value with the same encoding as that of the
 163  values returned by the
 164  .Xr time 3
 165  function (that is, seconds from the Epoch,
 166 @@ -197,17 +199,17 @@
 167  .Xr tzset 3 ) .
 168  The
 169  .Fn timegm
 170 -function
 171 -interprets the input structure as representing Universal Coordinated Time
 172 +function interprets the input structure
 173 +as representing Universal Coordinated Time
 174  .Pq Tn UTC .
 175  .Pp
 176  The original values of the
 177  .Fa tm_wday
 178  and
 179  .Fa tm_yday
 180 -components of the structure are ignored, and the original values of the
 181 -other components are not restricted to their normal ranges, and will be
 182 -normalized if needed.
 183 +components of the structure are ignored. The original values of the
 184 +other components are not restricted to their normal ranges and will be
 185 +normalized, if need be.
 186  For example,
 187  October 40 is changed into November 9,
 188  a
 189 @@ -223,7 +225,7 @@
 190  causes
 191  .Fn mktime
 192  to presume initially that summer time (for example, Daylight Saving Time)
 193 -is or is not in effect for the specified time, respectively.
 194 +is or is not (respectively) in effect for the specified time.
 195  A negative value for
 196  .Fa tm_isdst
 197  causes the
 198 @@ -265,7 +267,8 @@
 199  .Fa time0 ) ,
 200  expressed in seconds.
 201  .Pp
 202 -External declarations as well as the tm structure definition are in the
 203 +External declarations, as well as the tm structure definition,
 204 +are contained in the
 205  .In time.h
 206  include file.
 207  The tm structure includes at least the following fields:
 208 @@ -286,14 +289,14 @@
 209  The
 210  field
 211  .Fa tm_isdst
 212 -is non-zero if summer time is in effect.
 213 +is non-zero if summer (i.e., Daylight Saving) time is in effect.
 214  .Pp
 215  The field
 216  .Fa tm_gmtoff
 217  is the offset (in seconds) of the time represented from
 218  .Tn UTC ,
 219  with positive
 220 -values indicating east of the Prime Meridian.
 221 +values indicating locations east of the Prime Meridian.
 222  .Sh SEE ALSO
 223  .Xr date 1 ,
 224  .Xr gettimeofday 2 ,