man3/ctime.3

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