original/man3/ctime.3

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