lib/libc/time/ctime.3

   1 .\" $NetBSD: ctime.3,v 1.48 2013/09/20 19:06:54 christos Exp $
   2 .\"
   3 .\" XXX: License missing?
   4 .\"
   5 .Dd September 20, 2013
   6 .Dt CTIME 3
   7 .Os
   8 .Sh NAME
   9 .Nm asctime ,
  10 .Nm asctime_r ,
  11 .Nm ctime ,
  12 .Nm ctime_r ,
  13 .Nm ctime_rz ,
  14 .Nm difftime ,
  15 .Nm gmtime ,
  16 .Nm gmtime_r ,
  17 .Nm localtime ,
  18 .Nm localtime_r ,
  19 .Nm localtime_rz ,
  20 .Nm mktime ,
  21 .Nm mktime_z ,
  22 .Nm tzalloc ,
  23 .Nm tzgetname ,
  24 .Nm tzfree ,
  25 .Nd convert date and time to ASCII
  26 .Sh LIBRARY
  27 .Lb libc
  28 .Sh SYNOPSIS
  29 .In time.h
  30 .Vt extern char *tzname[2];
  31 .Ft char *
  32 .Fn asctime "const struct tm *tm"
  33 .Ft char *
  34 .Fn asctime_r "const struct tm restrict tm" "char * restrict buf"
  35 .Ft char *
  36 .Fn ctime "const time_t *clock"
  37 .Ft char *
  38 .Fn ctime_r "const time_t *clock"  "char *buf"
  39 .Ft char *
  40 .Fn ctime_rz "const timezone_t tz" "const time_t *clock"  "char *buf"
  41 .Ft double
  42 .Fn difftime "time_t time1" "time_t time0"
  43 .Ft struct tm *
  44 .Fn gmtime "const time_t *clock"
  45 .Ft struct tm *
  46 .Fn gmtime_r "const time_t * restrict clock" "struct tm * restrict result"
  47 .Ft struct tm *
  48 .Fn localtime "const time_t *clock"
  49 .Ft struct tm *
  50 .Fn localtime_r "const time_t * restrict clock" "struct tm * restrict result"
  51 .Ft struct tm *
  52 .Fn localtime_rz "const timezone_t tz" "const time_t * restrict clock" "struct tm * restrict result"
  53 .Ft time_t
  54 .Fn mktime "struct tm *tm"
  55 .Ft time_t
  56 .Fn mktime_z "const timezone_t tz" "struct tm *tm"
  57 .Ft timezone_t
  58 .Fn tzalloc "const char *zone"
  59 .Ft void
  60 .Fn tzfree "const timezone_t tz"
  61 .Ft const char *
  62 .Fn tzgetname "const timezone_t tz" "int isdst"
  63 .Sh DESCRIPTION
  64 The
  65 .Nm
  66 family of functions provide various standard library routines
  67 to operate with time and conversions related to time.
  68 .Sh FUNCTIONS
  69 .Bl -tag -width abcd
  70 .It Fn asctime "tm"
  71 The
  72 .Fn asctime
  73 function converts a time value contained in the
  74 .Fa tm
  75 structure to a string with the following general format:
  76 .Bd -literal -offset indent
  77 .D1 Thu Nov 24 18:22:48 1986\en\e0
  78 .Ed
  79 .Pp
  80 The
  81 .Fa tm
  82 structure is described in
  83 .Xr tm 3 .
  84 .It Fn asctime_r "tm" "buf"
  85 The
  86 .Fn asctime_r
  87 has the same behavior as
  88 .Fn asctime ,
  89 but the result is stored to
  90 .Fa buf ,
  91 which should have a size of at least 26 bytes.
  92 .It Fn ctime "clock"
  93 The
  94 .Fn ctime
  95 function converts a
  96 .Vt time_t ,
  97 pointed to by
  98 .Fa clock ,
  99 and returns a pointer to a string with the format described above.
 100 Years requiring fewer than four characters are padded with leading zeroes.
 101 For years longer than four characters, the string is of the form
 102 .Bd -literal -offset indent
 103 .D1 "Thu Nov 24 18:22:48     81986\en\e0"
 104 .Ed
 105 .Pp
 106 with five spaces before the year.
 107 These unusual formats are designed to make it less likely that older
 108 software that expects exactly 26 bytes of output will mistakenly output
 109 misleading values for out-of-range years.
 110 .Pp
 111 The
 112 .Fa clock
 113 time stamp represents the time in seconds since 1970-01-01 00:00:00
 114 Coordinated Universal Time (UTC).
 115 The POSIX standard says that time stamps must be nonnegative
 116 and must ignore leap seconds.
 117 Many implementations extend POSIX by allowing negative time stamps,
 118 and can therefore represent time stamps that predate the
 119 introduction of UTC and are some other flavor of Universal Time (UT).
 120 Some implementations support leap seconds, in contradiction to POSIX.
 121 .It Fn ctime_r "clock" "buf"
 122 The
 123 .Fn ctime_r
 124 is similar to
 125 .Fn ctime ,
 126 except it places the result of the conversion on the
 127 .Fa buf
 128 argument, which should be 26 or more bytes long,
 129 instead of using a global static buffer.
 130 .It Fn ctime_rz "tz" "clock" "buf"
 131 The
 132 .Fn ctime_rz
 133 function is similar to
 134 .Fn ctime_r ,
 135 but it also takes a
 136 .Ft "const timezone_t"
 137 argument, as returned by a previous call to
 138 .Fn tzalloc ,
 139 or a null pointer denoting
 140 Coordinated Universal Time
 141 .Pq Tn UTC .
 142 .It Fn difftime "time1" "time2"
 143 The
 144 .Fn difftime
 145 function returns the difference between two calendar times,
 146 .Fa ( time1 No - Fa time0 ) ,
 147 expressed in seconds.
 148 .It Fn gmtime "clock"
 149 The
 150 .Fn gmtime
 151 function converts to Coordinated Universal Time
 152 .Pq Tn UTC
 153 and returns a pointer to the
 154 .Va tm
 155 structure described in
 156 .Xr tm 3 .
 157 .It Fn gmtime_r "clock" "result"
 158 The
 159 .Fn gmtime_r
 160 provides the same functionality as
 161 .Fn gmtime ,
 162 differing in that the caller must supply a buffer area
 163 .Fa result
 164 to which the result is stored.
 165 .It Fn localtime "clock"
 166 Also
 167 .Fn localtime
 168 is comparable to
 169 .Fn gmtime .
 170 However,
 171 .Fn localtime
 172 corrects for the time zone and any time zone adjustments
 173 (such as Daylight Saving Time in the U.S.A.).
 174 After filling in the
 175 .Va tm
 176 structure, the function sets the
 177 .Fa tm_isdst Ns 'th
 178 element of
 179 .Fa tzname
 180 to a pointer to an
 181 ASCII string that is the time zone abbreviation to be used with
 182 .Fn localtime Ns 's
 183 return value.
 184 .It Fn localtime_r "clock" "result"
 185 As
 186 .Fn gmtime_r ,
 187 the
 188 .Fn localtime_r
 189 takes an additional buffer
 190 .Fa result
 191 as a parameter and stores the result to it.
 192 Note however that
 193 .Fn localtime_r
 194 does not imply initialization of the local time conversion information;
 195 the application may need to do so by calling
 196 .Xr tzset 3 .
 197 .It Fn localtime_rz "tz" "clock" "result"
 198 The
 199 .Fn localtime_rz
 200 function is similar to
 201 .Fn localtime_r ,
 202 but it also takes a
 203 .Ft "const timezone_t"
 204 argument, returned by a previous call to
 205 .Fn tzalloc ,
 206 or a null pointer denoting
 207 Coordinated Universal Time
 208 .Pq Tn UTC .
 209 .It Fn mktime "tm"
 210 The
 211 .Fn mktime
 212 function converts the broken-down time,
 213 expressed as local time in the
 214 .Xr tm 3
 215 structure, into a calendar time value with
 216 the same encoding as that of the values returned by the
 217 .Xr time 3
 218 function.
 219 The following remarks should be taken into account.
 220 .Bl -bullet
 221 .It
 222 The original values of the
 223 .Fa tm_wday
 224 and
 225 .Fa tm_yday
 226 components of the structure are ignored,
 227 and the original values of the other components are not restricted
 228 to their normal ranges.
 229 (A positive or zero value for
 230 .Fa tm_isdst
 231 causes
 232 .Fn mktime
 233 to presume initially that summer time (for example, Daylight Saving Time
 234 in the U.S.A.) respectively,
 235 is or is not in effect for the specified time.
 236 .It
 237 A negative value for
 238 .Fa tm_isdst
 239 causes the
 240 .Fn mktime
 241 function to attempt to divine whether summer time is in effect
 242 for the specified time; in this case it does not use a consistent
 243 rule and may give a different answer when later
 244 presented with the same argument.
 245 .It
 246 On successful completion, the values of the
 247 .Fa tm_wday
 248 and
 249 .Fa tm_yday
 250 components of the structure are set appropriately,
 251 and the other components are set to represent the specified calendar time,
 252 but with their values forced to their normal ranges; the final value of
 253 .Fa tm_mday
 254 is not set until
 255 .Fa tm_mon
 256 and
 257 .Fa tm_year
 258 are determined.
 259 .El
 260 .Pp
 261 The function returns the specified calendar time;
 262 if the calendar time cannot be represented, it returns
 263 .Va "(time_t)-1" .
 264 This can happen either because the resulting conversion would not fit
 265 in a
 266 .Vt time_t
 267 variable, or because the time specified happens to be in the daylight
 268 savings gap and
 269 .Fa tm_isdst
 270 was set to
 271 .Dv \-1 .
 272 Other
 273 .Fn mktime
 274 implementations do not return an error in the second case and return
 275 the appropriate time offset after the daylight savings gap.
 276 There is code to mimick this behavior, but it is not enabled by default.
 277 .It Fn mktime_z "tz" "tm"
 278 The
 279 .Fn mktime_z
 280 function is similar to
 281 .Fn mktime
 282 but it also takes a
 283 .Ft "const timezone_t"
 284 argument, returned by a previous call to
 285 .Fn tzalloc ,
 286 or a null pointer denoting
 287 Coordinated Universal Time
 288 .Pq Tn UTC .
 289 .It Fn tzalloc "zone"
 290 The
 291 .Fn tzalloc
 292 function takes as an argument a timezone name and returns a
 293 .Ft timezone_t
 294 object suitable to be used in the
 295 .Fn ctime_rz ,
 296 .Fn localtime_rz ,
 297 and
 298 .Fn mktime_z
 299 functions.
 300 .Pp
 301 A null pointer may be passed to
 302 .Fn tzalloc
 303 instead of a timezone name, to refer to
 304 Coordinated Universal Time
 305 .Pq Tn UTC .
 306 .Pp
 307 Note that instead of setting the environment variable
 308 .Va TZ ,
 309 and globally changing the behavior of the calling program, one can use
 310 multiple timezones at the same time by using separate
 311 .Ft timezone_t
 312 objects allocated by
 313 .Fn tzalloc
 314 and calling the
 315 .Dq z
 316 variants of the functions.
 317 .It Fn tzfree "tz"
 318 The
 319 .Fn tzfree
 320 function deallocates
 321 .Fa tz ,
 322 which was previously allocated by
 323 .Fn tzalloc .
 324 .It Fn "tzgetname"
 325 Finally,
 326 .Fn tzgetname
 327 returns the name for the given
 328 .Fa tz .
 329 If
 330 .Fa isdst
 331 is
 332 .Va 0 ,
 333 the call is equivalent to
 334 .Va tzname[0] .
 335 If
 336 .Fa isdst
 337 is set to
 338 .Va 1
 339 the call is equivalent to
 340 .Va tzname[1] .
 341 .El
 342 .Pp
 343 Declarations of all the functions and externals, and the
 344 .Ft tm
 345 structure, are in the
 346 .In time.h
 347 header file.
 348 The structure (of type)
 349 .Ft struct tm
 350 includes the following fields:
 351 .Bd -literal
 352        int tm_sec;      /* seconds (0 - 60) */
 353        int tm_min;      /* minutes (0 - 59) */
 354        int tm_hour;     /* hours (0 - 23) */
 355        int tm_mday;     /* day of month (1 - 31) */
 356        int tm_mon;      /* month of year (0 - 11) */
 357        int tm_year;     /* year - 1900 */
 358        int tm_wday;     /* day of week (Sunday = 0) */
 359        int tm_yday;     /* day of year (0 - 365) */
 360        int tm_isdst;    /* is summer time in effect? */
 361        char *tm_zone;   /* abbreviation of timezone name */
 362        long tm_gmtoff;  /* offset from UT in seconds */
 363 .Ed
 364 .Pp
 365 The
 366 .Fa tm_zone
 367 and
 368 .Fa tm_gmtoff
 369 fields exist, and are filled in, only if
 370 arrangements to do so were made when the library containing these functions
 371 was created.
 372 There is no guarantee that these fields  will  continue to exist in this form
 373 in future releases of this code.
 374 .Bl -bullet
 375 .It
 376 .Va tm_isdst
 377 is non-zero if summer time is in effect.
 378 .It
 379 .Va tm_gmtoff
 380 is the offset (in seconds) of the time represented from UT,
 381 with positive values indicating east of the Prime Meridian.
 382 The field's name is derived from Greenwich Mean Time, a precursor of UT.
 383 .El
 384 .Sh RETURN VALUES
 385 .Bl -bullet
 386 .It
 387 On success the
 388 .Fn asctime
 389 and
 390 .Fn ctime
 391 functions return a pointer to a static character buffer, and the
 392 .Fn asctime_r ,
 393 .Fn ctime_r ,
 394 and
 395 .Fn ctime_rz
 396 function return a pointer to the user-supplied buffer.
 397 On failure they all return
 398 .Dv NULL
 399 and no errors are defined for them.
 400 .It
 401 On success the
 402 .Fn gmtime ,
 403 and
 404 .Fn localtime
 405 functions return a pointer to a statically allocated
 406 .Va "struct tm"
 407 whereas the
 408 .Fn gmtime_r ,
 409 .Fn localtime_r ,
 410 and
 411 .Fn localtime_rz ,
 412 functions return a pointer to the user-supplied
 413 .Va "struct tm" .
 414 On failure they all return
 415 .Dv NULL
 416 and the global variable
 417 .Va errno
 418 is set to indicate the error.
 419 .It
 420 The
 421 .Fn mktime
 422 and
 423 .Fn mktime_z
 424 function returns the specified time since the Epoch as a
 425 .Vt time_t
 426 type value.
 427 If the time cannot be represented, then
 428 .Fn mktime
 429 and
 430 .Fn mktime_z
 431 return
 432 .Va "(time_t)-1"
 433 setting the global variable
 434 .Va errno
 435 to indicate the error.
 436 .It
 437 The
 438 .Fn tzalloc
 439 function returns a pointer to a
 440 .Ft timezone_t
 441 object or
 442 .Dv NULL
 443 on failure, setting
 444 .Va errno
 445 to indicate the error.
 446 It may also return
 447 .Dv NULL
 448 when the
 449 .Fa name
 450 argument is
 451 .Dv NULL ,
 452 and this is not an error, but a way of referring to
 453 Coordinated Universal Time
 454 .Pq Tn UTC .
 455 .It
 456 .Fn tzgetzone
 457 function returns string containing the name of the timezone given in
 458 .Fa tz .
 459 .El
 460 .Sh FILES
 461 .Bl -tag -width /usr/share/zoneinfo/posixrules -compact
 462 .It Pa /etc/localtime
 463 local time zone file
 464 .It Pa /usr/share/zoneinfo
 465 time zone information directory
 466 .It Pa /usr/share/zoneinfo/posixrules
 467 used with POSIX-style TZ's
 468 .It Pa /usr/share/zoneinfo/GMT
 469 for UTC leap seconds
 470 .El
 471 .Pp
 472 If
 473 .Pa /usr/share/zoneinfo/GMT
 474 is absent, UTC leap seconds are loaded from
 475 .Pa /usr/share/zoneinfo/posixrules .
 476 .Sh ERRORS
 477 The described functions may fail with
 478 .Bl -tag -width Er
 479 .It Bq Er EINVAL
 480 The result cannot be represented because a parameter is incorrect, or
 481 the conversion failed because no such time exists (for example a time
 482 in the DST gap).
 483 .It Bq Er EOVERFLOW
 484 The result cannot be represented because the time requested is out of bounds
 485 and the time calculation resulted in overflow.
 486 .El
 487 .Pp
 488 All functions that return values, except their
 489 .Dq z
 490 variants, can also return the same errors as
 491 .Xr open 2
 492 and
 493 .Xr malloc 3 .
 494 .Sh SEE ALSO
 495 .Xr getenv 3 ,
 496 .Xr strftime 3 ,
 497 .Xr time 3 ,
 498 .Xr tm 3 ,
 499 .Xr tzset 3 ,
 500 .Xr tzfile 5
 501 .Sh STANDARDS
 502 The
 503 .Fn ctime ,
 504 .Fn difftime ,
 505 .Fn asctime ,
 506 .Fn localtime ,
 507 .Fn gmtime
 508 and
 509 .Fn mktime
 510 functions conform to
 511 .St -ansiC .
 512 Rest of the functions conform to
 513 .St -p1003.1-2008 .
 514 .Sh CAVEATS
 515 The functions that do not take an explicit
 516 .Ft timezone_t
 517 argument return values point to static data; the data is overwritten by
 518 each call.
 519 For the above functions the
 520 .Fa tm_zone
 521 field of a returned
 522 .Va "struct tm"
 523 points to a static array of characters, which
 524 will also be overwritten at the next call
 525 (and by calls to
 526 .Xr tzset 3 ) .
 527 The functions that do take an explicit
 528 .Ft timezone_t
 529 argument and set the fields of a supplied
 530 .Va "struct tm"
 531 should not call
 532 .Fn tzfree
 533 since the
 534 .Fa tm_zone
 535 field of the
 536 .Va "struct tm"
 537 points to data allocated by
 538 .Fn tzalloc .
 539 .Pp
 540 The
 541 .Fn asctime
 542 and
 543 .Fn ctime
 544 functions behave strangely for years before 1000 or after 9999.
 545 The 1989 and 1999 editions of the C Standard say
 546 that years from \-99 through 999 are converted without
 547 extra spaces, but this conflicts with longstanding
 548 tradition and with this implementation.
 549 Traditional implementations of these two functions are
 550 restricted to years in the range 1900 through 2099.
 551 To avoid this portability mess, new programs should use
 552 .Fn strftime
 553 instead.
 554 .Pp
 555 Avoid using out-of-range values with
 556 .Fn mktime
 557 when setting up lunch with promptness sticklers in Riyadh.
 558 .\" @(#)newctime.3      8.3
 559 .\" This file is in the public domain, so clarified as of
 560 .\" 2009-05-17 by Arthur David Olson.