1.\" Copyright (c) 1989, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" This code is derived from software contributed to Berkeley by 5.\" Arthur Olson. 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.Dd September 23, 2025 31.Dt CTIME 3 32.Os 33.Sh NAME 34.Nm asctime , 35.Nm asctime_r , 36.Nm ctime , 37.Nm ctime_r , 38.Nm difftime , 39.Nm gmtime , 40.Nm gmtime_r , 41.Nm localtime , 42.Nm localtime_r , 43.Nm mktime , 44.Nm offtime , 45.Nm offtime_r , 46.Nm timegm 47.Nd transform binary date and time values 48.Sh LIBRARY 49.Lb libc 50.Sh SYNOPSIS 51.In time.h 52.Vt extern char *tzname[2] ; 53.Ft char * 54.Fn asctime "const struct tm *tm" 55.Ft char * 56.Fn asctime_r "const struct tm *tm" "char *buf" 57.Ft char * 58.Fn ctime "const time_t *clock" 59.Ft char * 60.Fn ctime_r "const time_t *clock" "char *buf" 61.Ft double 62.Fn difftime "time_t time1" "time_t time0" 63.Ft struct tm * 64.Fn gmtime "const time_t *clock" 65.Ft struct tm * 66.Fn gmtime_r "const time_t *clock" "struct tm *result" 67.Ft struct tm * 68.Fn localtime "const time_t *clock" 69.Ft struct tm * 70.Fn localtime_r "const time_t *clock" "struct tm *result" 71.Ft time_t 72.Fn mktime "struct tm *tm" 73.Ft struct tm * 74.Fn offtime "const time_t *clock" "long offset" 75.Ft struct tm * 76.Fn offtime_r "const time_t *clock" "long offset" "struct tm *result" 77.Ft time_t 78.Fn timegm "struct tm *tm" 79.Sh DESCRIPTION 80The 81.Fn ctime , 82.Fn gmtime , 83.Fn localtime , 84and 85.Fn offtime 86functions all take as argument a pointer to a time value representing 87the time in seconds since the Epoch (00:00:00 UTC on January 1, 1970; 88see 89.Xr time 3 ) . 90.Pp 91The 92.Fn localtime 93function converts the time value pointed to by 94.Fa clock , 95and returns a pointer to a 96.Vt struct tm 97(described below) which contains 98the broken-out time information for the value after adjusting for the current 99time zone (see 100.Xr tzset 3 ) . 101When the specified time translates to a year that will not fit in an 102.Vt int , 103.Fn localtime 104returns 105.Dv NULL . 106The 107.Fn localtime 108function uses 109.Xr tzset 3 110to initialize time conversion information if 111.Xr tzset 3 112has not already been called by the process. 113.Pp 114After filling in the 115.Vt struct tm , 116.Fn localtime 117sets the 118.Va tm_isdst Ns 'th 119element of 120.Va tzname 121to a pointer to an ASCII string that is the time zone abbreviation to be 122used with 123.Fn localtime Ns 's 124return value. 125.Pp 126The 127.Fn gmtime 128function similarly converts the time value, but without any time zone 129adjustment, and returns a pointer to a 130.Vt struct tm . 131.Pp 132The 133.Fn offtime 134function similarly converts the time value with a time zone adjustment 135corresponding to the provided 136.Fa offset , 137which is expressed in seconds, with positive values indicating a time 138zone ahead of UTC (east of the Prime Meridian). 139It does not call 140.Xr tzset 3 141or modify 142.Va tzname . 143.Pp 144The 145.Fn ctime 146function 147adjusts the time value for the current time zone in the same manner as 148.Fn localtime , 149and returns a pointer to a 26-character string of the form: 150.Bd -literal -offset indent 151Thu Nov 24 18:22:48 1986\en\e0 152.Ed 153.Pp 154All the fields have constant width. 155.Pp 156The 157.Fn asctime 158function converts the broken down time in the 159.Vt struct tm 160pointed to by 161.Fa tm 162to the form shown in the example above. 163.Pp 164The 165.Fn ctime_r 166and 167.Fn asctime_r 168functions 169provide the same functionality as 170.Fn ctime 171and 172.Fn asctime 173except the caller must provide the output buffer 174.Fa buf , 175which must be at least 26 characters long, to store the result in. 176The 177.Fn localtime_r , 178.Fn gmtime_r , 179and 180.Fn offtime_r 181functions provide the same functionality as 182.Fn localtime , 183.Fn gmtime , 184and 185.Fn offtime 186respectively, except the caller must provide the output buffer 187.Fa result . 188.Pp 189The functions 190.Fn mktime 191and 192.Fn timegm 193convert the broken-down time in the 194.Vt struct tm 195pointed to by 196.Fa tm 197into a time value with the same encoding as that of the values 198returned by the 199.Xr time 3 200function (that is, seconds from the Epoch, UTC). 201The 202.Fn mktime 203function interprets the input structure according to the current 204timezone setting (see 205.Xr tzset 3 ) 206while the 207.Fn timegm 208function interprets the input structure as representing Universal 209Coordinated Time 210.Pq UTC . 211.Pp 212The original values of the 213.Fa tm_wday 214and 215.Fa tm_yday 216components of the structure are ignored, and the original values of the 217other components are not restricted to their normal ranges, and will be 218normalized if needed. 219For example, 220October 40 is changed into November 9, 221a 222.Fa tm_hour 223of \-1 means 1 hour before midnight, 224.Fa tm_mday 225of 0 means the day preceding the current month, and 226.Fa tm_mon 227of \-2 means 2 months before January of 228.Fa tm_year . 229(A positive or zero value for 230.Fa tm_isdst 231causes 232.Fn mktime 233to presume initially that summer time (for example, Daylight Saving Time) 234is or is not in effect for the specified time, respectively. 235A negative value for 236.Fa tm_isdst 237causes the 238.Fn mktime 239function to attempt to guess whether summer time is in effect for the 240specified time. 241The 242.Fa tm_isdst 243and 244.Fa tm_gmtoff 245members are forced to zero by 246.Fn timegm . ) 247.Pp 248On successful completion, the values of the 249.Fa tm_wday 250and 251.Fa tm_yday 252components of the structure are set appropriately, and the other components 253are set to represent the specified calendar time, but with their values 254forced to their normal ranges; the final value of 255.Fa tm_mday 256is not set until 257.Fa tm_mon 258and 259.Fa tm_year 260are determined. 261The 262.Fn mktime 263function 264returns the specified calendar time; if the calendar time cannot be 265represented, it returns \-1 and sets 266.Xr errno 3 267to an appropriate value. 268.Pp 269Note that \-1 is a valid result (representing one second before 270midnight UTC on the evening of 31 December 1969), so this cannot be 271relied upon to indicate success or failure; instead, 272.Fa tm_wday 273and / or 274.Fa tm_yday 275should be set to an out-of-bounds value (e.g. \-1) prior to calling 276.Fn mktime 277or 278.Fn timegm 279and checked after the call. 280.Pp 281The 282.Fn difftime 283function returns the difference in seconds between two time values, 284.Fa time1 285\- 286.Fa time0 . 287.Pp 288External declarations as well as the definition of 289.Vt struct tm 290are in the 291.In time.h 292header. 293The 294.Vt tm 295structure includes at least the following fields: 296.Bd -literal -offset indent 297int tm_sec; /* seconds (0 - 60) */ 298int tm_min; /* minutes (0 - 59) */ 299int tm_hour; /* hours (0 - 23) */ 300int tm_mday; /* day of month (1 - 31) */ 301int tm_mon; /* month of year (0 - 11) */ 302int tm_year; /* year \- 1900 */ 303int tm_wday; /* day of week (Sunday = 0) */ 304int tm_yday; /* day of year (0 - 365) */ 305int tm_isdst; /* is summer time in effect? */ 306char *tm_zone; /* abbreviation of timezone name */ 307long tm_gmtoff; /* offset from UTC in seconds */ 308.Ed 309.Pp 310The 311.Fa tm_isdst 312field is non-zero if summer time is in effect. 313.Pp 314The 315.Fa tm_gmtoff 316field is the offset in seconds of the time represented from UTC, 317with positive values indicating a time zone ahead of UTC (east of the 318Prime Meridian). 319.Sh SEE ALSO 320.Xr date 1 , 321.Xr clock_gettime 2 , 322.Xr gettimeofday 2 , 323.Xr getenv 3 , 324.Xr time 3 , 325.Xr tzset 3 , 326.Xr tzfile 5 327.Sh STANDARDS 328The 329.Fn asctime , 330.Fn ctime , 331.Fn difftime , 332.Fn gmtime , 333.Fn localtime , 334and 335.Fn mktime 336functions conform to 337.St -isoC , 338and conform to 339.St -p1003.1-96 340provided the selected local timezone does not contain a leap-second table 341(see 342.Xr zic 8 ) . 343.Pp 344The 345.Fn asctime_r , 346.Fn ctime_r , 347.Fn gmtime_r , 348and 349.Fn localtime_r 350functions are expected to conform to 351.St -p1003.1-96 352(again provided the selected local timezone does not contain a leap-second 353table). 354.Pp 355The 356.Fn timegm 357function is not specified by any standard; its function cannot be 358completely emulated using the standard functions described above. 359.Sh HISTORY 360This manual page is derived from 361the time package contributed to Berkeley by 362.An Arthur Olson 363and which appeared in 364.Bx 4.3 . 365.Pp 366The functions 367.Fn asctime , 368.Fn gmtime , 369and 370.Fn localtime 371first appeared in 372.At v5 , 373.Fn difftime 374and 375.Fn mktime 376in 377.Bx 4.3 Reno , 378and 379.Fn timegm 380and 381.Fn timelocal 382in SunOS 4.0. 383.Pp 384The 385.Fn asctime_r , 386.Fn ctime_r , 387.Fn gmtime_r 388and 389.Fn localtime_r 390functions have been available since 391.Fx 8.0 . 392The 393.Fn offtime 394and 395.Fn offtime_r 396functions were added in 397.Fx 15.0 . 398.Sh BUGS 399Except for 400.Fn difftime , 401.Fn mktime , 402and the 403.Fn \&_r 404variants of the other functions, 405these functions leave their result in an internal static object and return 406a pointer to that object. 407Subsequent calls to these 408function will modify the same object. 409.Pp 410The C Standard provides no mechanism for a program to modify its current 411local timezone setting, and the POSIX-standard 412method is not reentrant. 413(However, thread-safe implementations are provided 414in the POSIX threaded environment.) 415.Pp 416The 417.Va tm_zone 418field of a returned 419.Vt tm 420structure points to a static array of characters, 421which will also be overwritten by any subsequent calls (as well as by 422subsequent calls to 423.Xr tzset 3 ) . 424.Pp 425Use of the external variable 426.Fa tzname 427is discouraged; the 428.Fa tm_zone 429entry in the tm structure is preferred. 430