man3/ctime.3

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