man3/ctime.3

   1 .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" References consulted:
   6 .\"     Linux libc source code
   7 .\"     Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
   8 .\"     386BSD man pages
   9 .\" Modified Sat Jul 24 19:49:27 1993 by Rik Faith (faith@cs.unc.edu)
  10 .\" Modified Fri Apr 26 12:38:55 MET DST 1996 by Martin Schulze (joey@linux.de)
  11 .\" Modified 2001-11-13, aeb
  12 .\" Modified 2001-12-13, joey, aeb
  13 .\" Modified 2004-11-16, mtk
  14 .\"
  15 .TH CTIME 3 2021-03-22 GNU "Linux Programmer's Manual"
  16 .SH NAME
  17 asctime, ctime, gmtime, localtime, mktime, asctime_r, ctime_r, gmtime_r,
  18 localtime_r \- transform date and time to broken-down time or ASCII
  19 .SH LIBRARY
  20 Standard C library
  21 .RI ( libc ", " \-lc )
  22 .SH SYNOPSIS
  23 .nf
  24 .B #include <time.h>
  25 .PP
  26 .BI "char *asctime(const struct tm *" tm );
  27 .BI "char *asctime_r(const struct tm *restrict " tm ", char *restrict " buf );
  28 .PP
  29 .BI "char *ctime(const time_t *" timep );
  30 .BI "char *ctime_r(const time_t *restrict " timep ", char *restrict " buf );
  31 .PP
  32 .BI "struct tm *gmtime(const time_t *" timep );
  33 .BI "struct tm *gmtime_r(const time_t *restrict " timep ,
  34 .BI "                    struct tm *restrict " result );
  35 .PP
  36 .BI "struct tm *localtime(const time_t *" timep );
  37 .BI "struct tm *localtime_r(const time_t *restrict " timep ,
  38 .BI "                    struct tm *restrict " result );
  39 .PP
  40 .BI "time_t mktime(struct tm *" tm );
  41 .fi
  42 .PP
  43 .RS -4
  44 Feature Test Macro Requirements for glibc (see
  45 .BR feature_test_macros (7)):
  46 .RE
  47 .PP
  48 .BR asctime_r (),
  49 .BR ctime_r (),
  50 .BR gmtime_r (),
  51 .BR localtime_r ():
  52 .nf
  53     _POSIX_C_SOURCE
  54         || /* Glibc <= 2.19: */ _BSD_SOURCE || _SVID_SOURCE
  55 .fi
  56 .SH DESCRIPTION
  57 The
  58 .BR ctime (),
  59 .BR gmtime (),
  60 and
  61 .BR localtime ()
  62 functions all take
  63 an argument of data type \fItime_t\fP, which represents calendar time.
  64 When interpreted as an absolute time value, it represents the number of
  65 seconds elapsed since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
  66 .PP
  67 The
  68 .BR asctime ()
  69 and
  70 .BR mktime ()
  71 functions both take an argument
  72 representing broken-down time, which is a representation
  73 separated into year, month, day, and so on.
  74 .PP
  75 Broken-down time is stored
  76 in the structure \fItm\fP, which is defined in \fI<time.h>\fP as follows:
  77 .PP
  78 .in +4n
  79 .EX
  80 struct tm {
  81     int tm_sec;    /* Seconds (0\-60) */
  82     int tm_min;    /* Minutes (0\-59) */
  83     int tm_hour;   /* Hours (0\-23) */
  84     int tm_mday;   /* Day of the month (1\-31) */
  85     int tm_mon;    /* Month (0\-11) */
  86     int tm_year;   /* Year \- 1900 */
  87     int tm_wday;   /* Day of the week (0\-6, Sunday = 0) */
  88     int tm_yday;   /* Day in the year (0\-365, 1 Jan = 0) */
  89     int tm_isdst;  /* Daylight saving time */
  90 };
  91 .EE
  92 .in
  93 .PP
  94 The members of the \fItm\fP structure are:
  95 .TP 10
  96 .I tm_sec
  97 The number of seconds after the minute, normally in the range 0 to 59,
  98 but can be up to 60 to allow for leap seconds.
  99 .TP
 100 .I tm_min
 101 The number of minutes after the hour, in the range 0 to 59.
 102 .TP
 103 .I tm_hour
 104 The number of hours past midnight, in the range 0 to 23.
 105 .TP
 106 .I tm_mday
 107 The day of the month, in the range 1 to 31.
 108 .TP
 109 .I tm_mon
 110 The number of months since January, in the range 0 to 11.
 111 .TP
 112 .I tm_year
 113 The number of years since 1900.
 114 .TP
 115 .I tm_wday
 116 The number of days since Sunday, in the range 0 to 6.
 117 .TP
 118 .I tm_yday
 119 The number of days since January 1, in the range 0 to 365.
 120 .TP
 121 .I tm_isdst
 122 A flag that indicates whether daylight saving time is in effect at the
 123 time described.
 124 The value is positive if daylight saving time is in
 125 effect, zero if it is not, and negative if the information is not
 126 available.
 127 .PP
 128 The call
 129 .BI ctime( t )
 130 is equivalent to
 131 .BI asctime(localtime( t )) \fR.
 132 It converts the calendar time \fIt\fP into a
 133 null-terminated string of the form
 134 .PP
 135 .in +4n
 136 .EX
 137 "Wed Jun 30 21:49:08 1993\en"
 138 .EE
 139 .in
 140 .PP
 141 The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed",
 142 "Thu", "Fri", and "Sat".
 143 The abbreviations for the months are "Jan",
 144 "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and
 145 "Dec".
 146 The return value points to a statically allocated string which
 147 might be overwritten by subsequent calls to any of the date and time
 148 functions.
 149 The function also sets the external
 150 variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP (see
 151 .BR tzset (3))
 152 with information about the current timezone.
 153 The reentrant version
 154 .BR ctime_r ()
 155 does the same, but stores the
 156 string in a user-supplied buffer
 157 which should have room for at least 26 bytes.
 158 It need not
 159 set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
 160 .PP
 161 The
 162 .BR gmtime ()
 163 function converts the calendar time \fItimep\fP to
 164 broken-down time representation, expressed in Coordinated Universal Time
 165 (UTC).
 166 It may return NULL when the year does not fit into an integer.
 167 The return value points to a statically allocated struct which might be
 168 overwritten by subsequent calls to any of the date and time functions.
 169 The
 170 .BR gmtime_r ()
 171 function does the same, but stores the data in a
 172 user-supplied struct.
 173 .PP
 174 The
 175 .BR localtime ()
 176 function converts the calendar time \fItimep\fP to
 177 broken-down time representation,
 178 expressed relative to the user's specified timezone.
 179 The function acts as if it called
 180 .BR tzset (3)
 181 and sets the external variables \fItzname\fP with
 182 information about the current timezone, \fItimezone\fP with the difference
 183 between Coordinated Universal Time (UTC) and local standard time in
 184 seconds, and \fIdaylight\fP to a nonzero value if daylight savings
 185 time rules apply during some part of the year.
 186 The return value points to a statically allocated struct which might be
 187 overwritten by subsequent calls to any of the date and time functions.
 188 The
 189 .BR localtime_r ()
 190 function does the same, but stores the data in a
 191 user-supplied struct.
 192 It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
 193 .PP
 194 The
 195 .BR asctime ()
 196 function converts the broken-down time value
 197 \fItm\fP into a null-terminated string with the same format as
 198 .BR ctime ().
 199 The return value points to a statically allocated string which might be
 200 overwritten by subsequent calls to any of the date and time functions.
 201 The
 202 .BR asctime_r ()
 203 function does the same, but stores the string in
 204 a user-supplied buffer which should have room for at least 26 bytes.
 205 .PP
 206 The
 207 .BR mktime ()
 208 function converts a broken-down time structure, expressed
 209 as local time, to calendar time representation.
 210 The function ignores
 211 the values supplied by the caller in the
 212 .I tm_wday
 213 and
 214 .I tm_yday
 215 fields.
 216 The value specified in the
 217 .I tm_isdst
 218 field informs
 219 .BR mktime ()
 220 whether or not daylight saving time (DST)
 221 is in effect for the time supplied in the
 222 .I tm
 223 structure:
 224 a positive value means DST is in effect;
 225 zero means that DST is not in effect;
 226 and a negative value means that
 227 .BR mktime ()
 228 should (use timezone information and system databases to)
 229 attempt to determine whether DST is in effect at the specified time.
 230 .PP
 231 The
 232 .BR mktime ()
 233 function modifies the fields of the
 234 .I tm
 235 structure as follows:
 236 .I tm_wday
 237 and
 238 .I tm_yday
 239 are set to values determined from the contents of the other fields;
 240 if structure members are outside their valid interval, they will be
 241 normalized (so that, for example, 40 October is changed into 9 November);
 242 .I tm_isdst
 243 is set (regardless of its initial value)
 244 to a positive value or to 0, respectively,
 245 to indicate whether DST is or is not in effect at the specified time.
 246 Calling
 247 .BR mktime ()
 248 also sets the external variable \fItzname\fP with
 249 information about the current timezone.
 250 .PP
 251 If the specified broken-down
 252 time cannot be represented as calendar time (seconds since the Epoch),
 253 .BR mktime ()
 254 returns
 255 .I (time_t)\ \-1
 256 and does not alter the
 257 members of the broken-down time structure.
 258 .SH RETURN VALUE
 259 On success,
 260 .BR gmtime ()
 261 and
 262 .BR localtime ()
 263 return a pointer to a
 264 .IR "struct\ tm" .
 265 .PP
 266 On success,
 267 .BR gmtime_r ()
 268 and
 269 .BR localtime_r ()
 270 return the address of the structure pointed to by
 271 .IR result .
 272 .PP
 273 On success,
 274 .BR asctime ()
 275 and
 276 .BR ctime ()
 277 return a pointer to a string.
 278 .PP
 279 On success,
 280 .BR asctime_r ()
 281 and
 282 .BR ctime_r ()
 283 return a pointer to the string pointed to by
 284 .IR buf .
 285 .PP
 286 On success,
 287 .BR mktime ()
 288 returns the calendar time (seconds since the Epoch),
 289 expressed as a value of type
 290 .IR time_t .
 291 .PP
 292 On error,
 293 .BR mktime ()
 294 returns the value
 295 .IR "(time_t)\ \-1" .
 296 The remaining functions return NULL on error.
 297 On error,
 298 .I errno
 299 is set to indicate the error.
 300 .SH ERRORS
 301 .TP
 302 .B EOVERFLOW
 303 The result cannot be represented.
 304 .SH ATTRIBUTES
 305 For an explanation of the terms used in this section, see
 306 .BR attributes (7).
 307 .ad l
 308 .nh
 309 .TS
 310 allbox;
 311 lb lb lbx
 312 l l l.
 313 Interface       Attribute       Value
 314 T{
 315 .BR asctime ()
 316 T}      Thread safety   T{
 317 MT-Unsafe race:asctime locale
 318 T}
 319 T{
 320 .BR asctime_r ()
 321 T}      Thread safety   T{
 322 MT-Safe locale
 323 T}
 324 T{
 325 .BR ctime ()
 326 T}      Thread safety   T{
 327 MT-Unsafe race:tmbuf
 328 race:asctime env locale
 329 T}
 330 T{
 331 .BR ctime_r (),
 332 .BR gmtime_r (),
 333 .BR localtime_r (),
 334 .BR mktime ()
 335 T}      Thread safety   T{
 336 MT-Safe env locale
 337 T}
 338 T{
 339 .BR gmtime (),
 340 .BR localtime ()
 341 T}      Thread safety   T{
 342 MT-Unsafe race:tmbuf env locale
 343 T}
 344 .TE
 345 .hy
 346 .ad
 347 .sp 1
 348 .SH CONFORMING TO
 349 POSIX.1-2001.
 350 C89 and C99 specify
 351 .BR asctime (),
 352 .BR ctime (),
 353 .BR gmtime (),
 354 .BR localtime (),
 355 and
 356 .BR mktime ().
 357 POSIX.1-2008 marks
 358 .BR asctime (),
 359 .BR asctime_r (),
 360 .BR ctime (),
 361 and
 362 .BR ctime_r ()
 363 as obsolete,
 364 recommending the use of
 365 .BR strftime (3)
 366 instead.
 367 .PP
 368 POSIX doesn't specify the parameters of
 369 .BR ctime_r ()
 370 to be
 371 .IR restrict ;
 372 that is specific to glibc.
 373 .SH NOTES
 374 The four functions
 375 .BR asctime (),
 376 .BR ctime (),
 377 .BR gmtime (),
 378 and
 379 .BR localtime ()
 380 return a pointer to static data and hence are not thread-safe.
 381 The thread-safe versions,
 382 .BR asctime_r (),
 383 .BR ctime_r (),
 384 .BR gmtime_r (),
 385 and
 386 .BR localtime_r (),
 387 are specified by SUSv2.
 388 .PP
 389 POSIX.1-2001 says:
 390 "The
 391 .BR asctime (),
 392 .BR ctime (),
 393 .BR gmtime (),
 394 and
 395 .BR localtime ()
 396 functions shall return values in one of two static objects:
 397 a broken-down time structure and an array of type
 398 .IR char .
 399 Execution of any of the functions may overwrite the information returned
 400 in either of these objects by any of the other functions."
 401 This can occur in the glibc implementation.
 402 .PP
 403 In many implementations, including glibc, a 0 in
 404 .I tm_mday
 405 is interpreted as meaning the last day of the preceding month.
 406 .PP
 407 The glibc version of \fIstruct tm\fP has additional fields
 408 .PP
 409 .in +4n
 410 .EX
 411 long tm_gmtoff;           /* Seconds east of UTC */
 412 const char *tm_zone;      /* Timezone abbreviation */
 413 .EE
 414 .in
 415 .PP
 416 defined when
 417 .B _BSD_SOURCE
 418 was set before including
 419 .IR <time.h> .
 420 This is a BSD extension, present in 4.3BSD-Reno.
 421 .PP
 422 According to POSIX.1-2001,
 423 .BR localtime ()
 424 is required to behave as though
 425 .BR tzset (3)
 426 was called, while
 427 .BR localtime_r ()
 428 does not have this requirement.
 429 .\" See http://thread.gmane.org/gmane.comp.time.tz/2034/
 430 For portable code,
 431 .BR tzset (3)
 432 should be called before
 433 .BR localtime_r ().
 434 .SH SEE ALSO
 435 .BR date (1),
 436 .BR gettimeofday (2),
 437 .BR time (2),
 438 .BR utime (2),
 439 .BR clock (3),
 440 .BR difftime (3),
 441 .BR strftime (3),
 442 .BR strptime (3),
 443 .BR timegm (3),
 444 .BR tzset (3),
 445 .BR time (7)