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 2010-02-25 "" "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 the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
  82 .PP
  83 The
  84 .BR asctime ()
  85 and
  86 .BR mktime ()
  87 functions both take an argument
  88 representing broken-down time which is a representation
  89 separated into year, month, day, etc.
  90 .PP
  91 Broken-down time is stored
  92 in the structure \fItm\fP which is defined in \fI<time.h>\fP as follows:
  93 .sp
  94 .in +4n
  95 .nf
  96 struct tm {
  97     int tm_sec;         /* seconds */
  98     int tm_min;         /* minutes */
  99     int tm_hour;        /* hours */
 100     int tm_mday;        /* day of the month */
 101     int tm_mon;         /* month */
 102     int tm_year;        /* year */
 103     int tm_wday;        /* day of the week */
 104     int tm_yday;        /* day in the year */
 105     int tm_isdst;       /* daylight saving time */
 106 };
 107 .fi
 108 .in
 109 .PP
 110 The members of the \fItm\fP structure are:
 111 .TP 10
 112 .I tm_sec
 113 The number of seconds after the minute, normally in the range 0 to 59,
 114 but can be up to 60 to allow for leap seconds.
 115 .TP
 116 .I tm_min
 117 The number of minutes after the hour, in the range 0 to 59.
 118 .TP
 119 .I tm_hour
 120 The number of hours past midnight, in the range 0 to 23.
 121 .TP
 122 .I tm_mday
 123 The day of the month, in the range 1 to 31.
 124 .TP
 125 .I tm_mon
 126 The number of months since January, in the range 0 to 11.
 127 .TP
 128 .I tm_year
 129 The number of years since 1900.
 130 .TP
 131 .I tm_wday
 132 The number of days since Sunday, in the range 0 to 6.
 133 .TP
 134 .I tm_yday
 135 The number of days since January 1, in the range 0 to 365.
 136 .TP
 137 .I tm_isdst
 138 A flag that indicates whether daylight saving time is in effect at the
 139 time described.
 140 The value is positive if daylight saving time is in
 141 effect, zero if it is not, and negative if the information is not
 142 available.
 143 .PP
 144 The call
 145 .BI ctime( t )
 146 is equivalent to
 147 .BI asctime(localtime( t )) \fR.
 148 It converts the calendar time \fIt\fP into a
 149 null-terminated string of the form
 150 .sp
 151 .RS
 152 "Wed Jun 30 21:49:08 1993\\n"
 153 .RE
 154 .sp
 155 The abbreviations for the days of the week are "Sun", "Mon", "Tue", "Wed",
 156 "Thu", "Fri", and "Sat".
 157 The abbreviations for the months are "Jan",
 158 "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", and
 159 "Dec".
 160 The return value points to a statically allocated string which
 161 might be overwritten by subsequent calls to any of the date and time
 162 functions.
 163 The function also sets the external
 164 variables \fItzname\fP, \fItimezone\fP, and \fIdaylight\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
 171 which should have room for at least 26 bytes.
 172 It need not
 173 set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
 174 .PP
 175 The
 176 .BR gmtime ()
 177 function converts the calendar time \fItimep\fP to
 178 broken-down time representation, expressed in Coordinated Universal Time
 179 (UTC).
 180 It may return NULL when the year does not fit into an integer.
 181 The return value points to a statically allocated struct which might be
 182 overwritten by subsequent calls to any of the date and time functions.
 183 The
 184 .BR gmtime_r ()
 185 function does the same, but stores the data in a
 186 user-supplied struct.
 187 .PP
 188 The
 189 .BR localtime ()
 190 function converts the calendar time \fItimep\fP to
 191 broken-time representation, expressed relative to the user's specified
 192 timezone.
 193 The function acts as if it called
 194 .BR tzset (3)
 195 and sets the external variables \fItzname\fP with
 196 information about the current timezone, \fItimezone\fP with the difference
 197 between Coordinated Universal Time (UTC) and local standard time in
 198 seconds, and \fIdaylight\fP to a nonzero value if daylight savings
 199 time rules apply during some part of the year.
 200 The return value points to a statically allocated struct which might be
 201 overwritten by subsequent calls to any of the date and time functions.
 202 The
 203 .BR localtime_r ()
 204 function does the same, but stores the data in a
 205 user-supplied struct.
 206 It need not set \fItzname\fP, \fItimezone\fP, and \fIdaylight\fP.
 207 .PP
 208 The
 209 .BR asctime ()
 210 function converts the broken-down time value
 211 \fItm\fP into a null-terminated string with the same format as
 212 .BR ctime ().
 213 The return value points to a statically allocated string which might be
 214 overwritten by subsequent calls to any of the date and time functions.
 215 The
 216 .BR asctime_r ()
 217 function does the same, but stores the string in
 218 a user-supplied buffer which should have room for at least 26 bytes.
 219 .PP
 220 The
 221 .BR mktime ()
 222 function converts a broken-down time structure, expressed
 223 as local time, to calendar time representation.
 224 The function ignores
 225 the values supplied by the caller in the
 226 .I tm_wday
 227 and
 228 .I tm_yday
 229 fields.
 230 The value specified in the
 231 .I tm_isdst
 232 field informs
 233 .BR mktime ()
 234 whether or not daylight saving time (DST)
 235 is in effect for the time supplied in the
 236 .I tm
 237 structure:
 238 a positive value means DST is in effect;
 239 zero means that DST is not in effect;
 240 and a negative value means that
 241 .BR mktime ()
 242 should (use timezone information and system databases to)
 243 attempt to determine whether DST is in effect at the specified time.
 244
 245 The
 246 .BR mktime ()
 247 function modifies the fields of the
 248 .IR tm
 249 structure as follows:
 250 .I tm_wday
 251 and
 252 .I tm_yday
 253 are set to values determined from the contents of the other fields;
 254 if structure members are outside their valid interval, they will be
 255 normalized (so that, for example, 40 October is changed into 9 November);
 256 .I tm_isdst
 257 is set (regardless of its initial value)
 258 to a positive value or to 0, respectively,
 259 to indicate whether DST is or is not in effect at the specified time.
 260 Calling
 261 .BR mktime ()
 262 also sets the external variable \fItzname\fP with
 263 information about the current timezone.
 264
 265 If the specified broken-down
 266 time cannot be represented as calendar time (seconds since the Epoch),
 267 .BR mktime ()
 268 returns a value of
 269 .I (time_t)\ \-1
 270 and does not alter the
 271 members of the broken-down time structure.
 272 .SH "RETURN VALUE"
 273 Each of these functions returns the value described, or NULL
 274 (\-1 in case of
 275 .BR mktime ())
 276 in case an error was detected.
 277 .SH "CONFORMING TO"
 278 POSIX.1-2001.
 279 C89 and C99 specify
 280 .BR asctime (),
 281 .BR ctime (),
 282 .BR gmtime (),
 283 .BR localtime (),
 284 and
 285 .BR mktime ().
 286 POSIX.1-2008 marks
 287 .BR asctime (),
 288 .BR asctime_r (),
 289 .BR ctime (),
 290 and
 291 .BR ctime_r ()
 292 as obsolete,
 293 recommending the use of
 294 .BR strftime (3)
 295 instead.
 296 .SH NOTES
 297 The four functions
 298 .BR asctime (),
 299 .BR ctime (),
 300 .BR gmtime ()
 301 and
 302 .BR localtime ()
 303 return a pointer to static data and hence are not thread-safe.
 304 Thread-safe versions
 305 .BR asctime_r (),
 306 .BR ctime_r (),
 307 .BR gmtime_r ()
 308 and
 309 .BR localtime_r ()
 310 are specified by SUSv2, and available since libc 5.2.5.
 311
 312 POSIX.1-2001 says:
 313 "The
 314 .BR asctime (),
 315 .BR ctime (),
 316 .BR gmtime (),
 317 and
 318 .BR localtime ()
 319 functions shall return values in one of two static objects:
 320 a broken-down time structure and an array of type
 321 .IR char .
 322 Execution of any of the functions may overwrite the information returned
 323 in either of these objects by any of the other functions."
 324 This can occur in the glibc implementation.
 325 .LP
 326 In many implementations, including glibc, a 0 in
 327 .I tm_mday
 328 is interpreted as meaning the last day of the preceding month.
 329 .LP
 330 The glibc version of \fIstruct tm\fP has additional fields
 331 .sp
 332 .RS
 333 .nf
 334 long tm_gmtoff;           /* Seconds east of UTC */
 335 const char *tm_zone;      /* Timezone abbreviation */
 336 .fi
 337 .RE
 338 .sp
 339 defined when
 340 .B _BSD_SOURCE
 341 was set before including
 342 .IR <time.h> .
 343 This is a BSD extension, present in 4.3BSD-Reno.
 344
 345 According to POSIX.1-2004,
 346 .BR localtime ()
 347 is required to behave as though
 348 .BR tzset ()
 349 was called, while
 350 .BR localtime_r ()
 351 does not have this requirement.
 352 .\" See http://thread.gmane.org/gmane.comp.time.tz/2034/
 353 For portable code
 354 .BR tzset ()
 355 should be called before
 356 .BR localtime_r ().
 357 .SH "SEE ALSO"
 358 .BR date (1),
 359 .BR gettimeofday (2),
 360 .BR time (2),
 361 .BR utime (2),
 362 .BR clock (3),
 363 .BR difftime (3),
 364 .BR strftime (3),
 365 .BR strptime (3),
 366 .BR timegm (3),
 367 .BR tzset (3),
 368 .BR time (7)