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