contrib/tzcode/newctime.3

   1 .\" This file is in the public domain, so clarified as of
   2 .\" 2009-05-17 by Arthur David Olson.
   3 .TH newctime 3 "" "Time Zone Database"
   4 .SH NAME
   5 asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time
   6 .SH SYNOPSIS
   7 .nf
   8 .ie \n(.g .ds - \f(CR-\fP
   9 .el .ds - \-
  10 .B #include <time.h>
  11 .PP
  12 .BR "extern char *tzname[];" " /\(** (optional) \(**/"
  13 .PP
  14 .B [[deprecated]] char *ctime(time_t const *clock);
  15 .PP
  16 .B char *ctime_r(time_t const *clock, char *buf);
  17 .PP
  18 .B double difftime(time_t time1, time_t time0);
  19 .PP
  20 .B [[deprecated]] char *asctime(struct tm const *tm);
  21 .PP
  22 .B "char *asctime_r(struct tm const *restrict tm,"
  23 .B "    char *restrict result);"
  24 .PP
  25 .B struct tm *localtime(time_t const *clock);
  26 .PP
  27 .B "struct tm *localtime_r(time_t const *restrict clock,"
  28 .B "    struct tm *restrict result);"
  29 .PP
  30 .B "struct tm *localtime_rz(timezone_t restrict zone,"
  31 .B "    time_t const *restrict clock,"
  32 .B "    struct tm *restrict result);"
  33 .PP
  34 .B struct tm *gmtime(time_t const *clock);
  35 .PP
  36 .B "struct tm *gmtime_r(time_t const *restrict clock,"
  37 .B "    struct tm *restrict result);"
  38 .PP
  39 .B time_t mktime(struct tm *tm);
  40 .PP
  41 .B "time_t mktime_z(timezone_t restrict zone,"
  42 .B "    struct tm *restrict tm);"
  43 .PP
  44 .B cc ... \*-ltz
  45 .fi
  46 .SH DESCRIPTION
  47 .ie '\(en'' .ds en \-
  48 .el .ds en \(en
  49 .ie '\(lq'' .ds lq \&"\"
  50 .el .ds lq \(lq\"
  51 .ie '\(rq'' .ds rq \&"\"
  52 .el .ds rq \(rq\"
  53 .de q
  54 \\$3\*(lq\\$1\*(rq\\$2
  55 ..
  56 The
  57 .B ctime
  58 function
  59 converts a long integer, pointed to by
  60 .IR clock ,
  61 and returns a pointer to a
  62 string of the form
  63 .br
  64 .ce
  65 .eo
  66 Thu Nov 24 18:22:48 1986\n\0
  67 .br
  68 .ec
  69 Years requiring fewer than four characters are padded with leading zeroes.
  70 For years longer than four characters, the string is of the form
  71 .br
  72 .ce
  73 .eo
  74 Thu Nov 24 18:22:48     81986\n\0
  75 .ec
  76 .br
  77 with five spaces before the year.
  78 These unusual formats are designed to make it less likely that older
  79 software that expects exactly 26 bytes of output will mistakenly output
  80 misleading values for out-of-range years.
  81 .PP
  82 The
  83 .BI * clock
  84 timestamp represents the time in seconds since 1970-01-01 00:00:00
  85 Coordinated Universal Time (UTC).
  86 The POSIX standard says that timestamps must be nonnegative
  87 and must ignore leap seconds.
  88 Many implementations extend POSIX by allowing negative timestamps,
  89 and can therefore represent timestamps that predate the
  90 introduction of UTC and are some other flavor of Universal Time (UT).
  91 Some implementations support leap seconds, in contradiction to POSIX.
  92 .PP
  93 The
  94 .B ctime
  95 function is deprecated starting in C23.
  96 Callers can use
  97 .B localtime_r
  98 and
  99 .B strftime
 100 instead.
 101 .PP
 102 The
 103 .B localtime
 104 and
 105 .B gmtime
 106 functions
 107 return pointers to
 108 .q "tm"
 109 structures, described below.
 110 The
 111 .B localtime
 112 function
 113 corrects for the time zone and any time zone adjustments
 114 (such as Daylight Saving Time in the United States).
 115 After filling in the
 116 .q "tm"
 117 structure,
 118 .B localtime
 119 sets the
 120 .BR tm_isdst 'th
 121 element of
 122 .B tzname
 123 to a pointer to a string that's the time zone abbreviation to be used with
 124 .BR localtime 's
 125 return value.
 126 .PP
 127 The
 128 .B gmtime
 129 function
 130 converts to Coordinated Universal Time.
 131 .PP
 132 The
 133 .B asctime
 134 function
 135 converts a time value contained in a
 136 .q "tm"
 137 structure to a string,
 138 as shown in the above example,
 139 and returns a pointer to the string.
 140 This function is deprecated starting in C23.
 141 Callers can use
 142 .B strftime
 143 instead.
 144 .PP
 145 The
 146 .B mktime
 147 function
 148 converts the broken-down time,
 149 expressed as local time,
 150 in the structure pointed to by
 151 .I tm
 152 into a calendar time value with the same encoding as that of the values
 153 returned by the
 154 .B time
 155 function.
 156 The original values of the
 157 .B tm_wday
 158 and
 159 .B tm_yday
 160 components of the structure are ignored,
 161 and the original values of the other components are not restricted
 162 to their normal ranges.
 163 (A positive or zero value for
 164 .B tm_isdst
 165 causes
 166 .B mktime
 167 to presume initially that daylight saving time
 168 respectively,
 169 is or is not in effect for the specified time.
 170 A negative value for
 171 .B tm_isdst
 172 causes the
 173 .B mktime
 174 function to attempt to divine whether daylight saving time is in effect
 175 for the specified time; in this case it does not use a consistent
 176 rule and may give a different answer when later
 177 presented with the same argument.)
 178 On successful completion, the values of the
 179 .B tm_wday
 180 and
 181 .B tm_yday
 182 components of the structure are set appropriately,
 183 and the other components are set to represent the specified calendar time,
 184 but with their values forced to their normal ranges; the final value of
 185 .B tm_mday
 186 is not set until
 187 .B tm_mon
 188 and
 189 .B tm_year
 190 are determined.
 191 The
 192 .B mktime
 193 function
 194 returns the specified calendar time;
 195 If the calendar time cannot be represented,
 196 it returns \-1.
 197 .PP
 198 The
 199 .B difftime
 200 function
 201 returns the difference between two calendar times,
 202 .RI ( time1
 203 \-
 204 .IR time0 ),
 205 expressed in seconds.
 206 .PP
 207 The
 208 .BR ctime_r ,
 209 .BR localtime_r ,
 210 .BR gmtime_r ,
 211 and
 212 .B asctime_r
 213 functions
 214 are like their unsuffixed counterparts, except that they accept an
 215 additional argument specifying where to store the result if successful.
 216 .PP
 217 The
 218 .B localtime_rz
 219 and
 220 .B mktime_z
 221 functions
 222 are like their unsuffixed counterparts, except that they accept an
 223 extra initial
 224 .B zone
 225 argument specifying the timezone to be used for conversion.
 226 If
 227 .B zone
 228 is null, UT is used; otherwise,
 229 .B zone
 230 should be have been allocated by
 231 .B tzalloc
 232 and should not be freed until after all uses (e.g., by calls to
 233 .BR strftime )
 234 of the filled-in
 235 .B tm_zone
 236 fields.
 237 .PP
 238 Declarations of all the functions and externals, and the
 239 .q "tm"
 240 structure,
 241 are in the
 242 .B <time.h>
 243 header file.
 244 The structure (of type)
 245 .B struct tm
 246 includes the following fields:
 247 .RS
 248 .PP
 249 .nf
 250 .ta 2n +\w'long tm_gmtoff;nn'u
 251         int tm_sec;     /\(** seconds (0\*(en60) \(**/
 252         int tm_min;     /\(** minutes (0\*(en59) \(**/
 253         int tm_hour;    /\(** hours (0\*(en23) \(**/
 254         int tm_mday;    /\(** day of month (1\*(en31) \(**/
 255         int tm_mon;     /\(** month of year (0\*(en11) \(**/
 256         int tm_year;    /\(** year \- 1900 \(**/
 257         int tm_wday;    /\(** day of week (Sunday = 0) \(**/
 258         int tm_yday;    /\(** day of year (0\*(en365) \(**/
 259         int tm_isdst;   /\(** is daylight saving time in effect? \(**/
 260         char \(**tm_zone;       /\(** time zone abbreviation (optional) \(**/
 261         long tm_gmtoff; /\(** offset from UT in seconds (optional) \(**/
 262 .fi
 263 .RE
 264 .PP
 265 The
 266 .B tm_isdst
 267 field
 268 is non-zero if daylight saving time is in effect.
 269 .PP
 270 The
 271 .B tm_gmtoff
 272 field
 273 is the offset (in seconds) of the time represented
 274 from UT, with positive values indicating east
 275 of the Prime Meridian.
 276 The field's name is derived from Greenwich Mean Time, a precursor of UT.
 277 .PP
 278 In
 279 .B "struct tm"
 280 the
 281 .B tm_zone
 282 and
 283 .B tm_gmtoff
 284 fields exist, and are filled in, only if arrangements to do
 285 so were made when the library containing these functions was
 286 created.
 287 Similarly, the
 288 .B tzname
 289 variable is optional; also, there is no guarantee that
 290 .B tzname
 291 will
 292 continue to exist in this form in future releases of this code.
 293 .SH FILES
 294 .ta \w'/usr/share/zoneinfo/posixrules\0\0'u
 295 /usr/share/zoneinfo     timezone information directory
 296 .br
 297 /usr/share/zoneinfo/localtime   local timezone file
 298 .br
 299 /usr/share/zoneinfo/posixrules  default DST rules (obsolete,
 300         and can cause bugs if present)
 301 .br
 302 /usr/share/zoneinfo/GMT for UTC leap seconds
 303 .sp
 304 If
 305 .B /usr/share/zoneinfo/GMT
 306 is absent,
 307 UTC leap seconds are loaded from
 308 .BR /usr/share/zoneinfo/posixrules .
 309 .SH SEE ALSO
 310 getenv(3),
 311 newstrftime(3),
 312 newtzset(3),
 313 time(2),
 314 tzfile(5)
 315 .SH NOTES
 316 The return values of
 317 .BR asctime ,
 318 .BR ctime ,
 319 .BR gmtime ,
 320 and
 321 .B localtime
 322 point to static data
 323 overwritten by each call.
 324 The
 325 .B tzname
 326 variable (once set) and the
 327 .B tm_zone
 328 field of a returned
 329 .B "struct tm"
 330 both point to an array of characters that
 331 can be freed or overwritten by later calls to the functions
 332 .BR localtime ,
 333 .BR tzfree ,
 334 and
 335 .BR tzset ,
 336 if these functions affect the timezone information that specifies the
 337 abbreviation in question.
 338 The remaining functions and data are thread-safe.
 339 .PP
 340 The
 341 .BR asctime ,
 342 .BR asctime_r ,
 343 .BR ctime ,
 344 and
 345 .B ctime_r
 346 functions
 347 behave strangely for years before 1000 or after 9999.
 348 The 1989 and 1999 editions of the C Standard say
 349 that years from \-99 through 999 are converted without
 350 extra spaces, but this conflicts with longstanding
 351 tradition and with this implementation.
 352 The 2011 edition says that the behavior
 353 is undefined if the year is before 1000 or after 9999.
 354 Traditional implementations of these two functions are
 355 restricted to years in the range 1900 through 2099.
 356 To avoid this portability mess, new programs should use
 357 .B strftime
 358 instead.