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