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  2007-07-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 || _XOPEN_SOURCE || _BSD_SOURCE || _SVID_SOURCE
  71 .SH DESCRIPTION
  72 The
  73 .BR ctime (),
  74 .BR gmtime ()
  75 and
  76 .BR localtime ()
  77 functions all take
  78 an argument of data type \fItime_t\fP which represents calendar time.
  79 When interpreted as an absolute time value, it represents the number of
  80 seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal
  81 Time (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 .RS
  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 .RE
 109 .PP
 110 The members of the \fItm\fP structure are:
 111 .TP
 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 string of the form
 149 .sp
 150 .RS
 151 "Wed Jun 30 21:49:08 1993\\n"
 152 .RE
 153 .sp
 154 The abbreviations for the days of the week are `Sun', `Mon', `Tue', `Wed',
 155 `Thu', `Fri', and `Sat'.
 156 The abbreviations for the months are `Jan',
 157 `Feb', `Mar', `Apr', `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and
 158 `Dec'.
 159 The return value points to a statically allocated string which
 160 might be overwritten by subsequent calls to any of the date and time
 161 functions.
 162 The function also sets the external variable \fItzname\fP (see
 163 .BR tzset (3))
 164 with information about the current time zone.
 165 The re-entrant version
 166 .BR ctime_r ()
 167 does the same, but stores the
 168 string in a user-supplied buffer of length at least 26.
 169 It need not
 170 set \fItzname\fP.
 171 .PP
 172 The
 173 .BR gmtime ()
 174 function converts the calendar time \fItimep\fP to
 175 broken-down time representation, expressed in Coordinated Universal Time
 176 (UTC).
 177 It may return NULL when the year does not fit into an integer.
 178 The return value points to a statically allocated struct which might be
 179 overwritten by subsequent calls to any of the date and time functions.
 180 The
 181 .BR gmtime_r ()
 182 function does the same, but stores the data in a
 183 user-supplied struct.
 184 .PP
 185 The
 186 .BR localtime ()
 187 function converts the calendar time \fItimep\fP to
 188 broken-time representation, expressed relative to the user's specified
 189 time zone.
 190 The function acts as if it called
 191 .BR tzset (3)
 192 and sets the external variables \fItzname\fP with
 193 information about the current time zone, \fItimezone\fP with the difference
 194 between Coordinated Universal Time (UTC) and local standard time in
 195 seconds, and \fIdaylight\fP to a non-zero value if daylight savings
 196 time rules apply during some part of the year.
 197 The return value points to a statically allocated struct which might be
 198 overwritten by subsequent calls to any of the date and time functions.
 199 The
 200 .BR localtime_r ()
 201 function does the same, but stores the data in a
 202 user-supplied struct.
 203 It need not set \fItzname\fP.
 204 .PP
 205 The
 206 .BR asctime ()
 207 function converts the broken-down time value
 208 \fItm\fP into a string with the same format as
 209 .BR ctime ().
 210 The return value points to a statically allocated string which might be
 211 overwritten by subsequent calls to any of the date and time functions.
 212 The
 213 .BR asctime_r ()
 214 function does the same, but stores the string in
 215 a user-supplied buffer of length at least 26.
 216 .PP
 217 The
 218 .BR mktime ()
 219 function converts a broken-down time structure, expressed
 220 as local time, to calendar time representation.
 221 The function ignores
 222 the specified contents of the structure members \fItm_wday\fP and \fItm_yday\fP
 223 and recomputes them from the other information in the broken-down time
 224 structure.
 225 If structure members are outside their legal interval, they will be
 226 normalized (so that, for example, 40 October is changed into 9 November).
 227 Calling
 228 .BR mktime ()
 229 also sets the external variable \fItzname\fP with
 230 information about the current time zone.
 231 If the specified broken-down
 232 time cannot be represented as calendar time (seconds since the epoch),
 233 .BR mktime ()
 234 returns a value of
 235 .I (time_t)(\-1)
 236 and does not alter the
 237 \fItm_wday\fP and \fItm_yday\fP members of the broken-down time structure.
 238 .SH "RETURN VALUE"
 239 Each of these functions returns the value described, or NULL
 240 (\-1 in case of
 241 .BR mktime ())
 242 in case an error was detected.
 243 .SH "CONFORMING TO"
 244 POSIX.1-2001.
 245 C89 and C99 specify
 246 .BR asctime (),
 247 .BR ctime (),
 248 .BR gmtime (),
 249 .BR localtime (),
 250 and
 251 .BR mktime ()
 252 .SH NOTES
 253 The four functions
 254 .BR asctime (),
 255 .BR ctime (),
 256 .BR gmtime ()
 257 and
 258 .BR localtime ()
 259 return a pointer to static data and hence are not thread-safe.
 260 Thread-safe versions
 261 .BR asctime_r (),
 262 .BR ctime_r (),
 263 .BR gmtime_r ()
 264 and
 265 .BR localtime_r ()
 266 are specified by SUSv2, and available since libc 5.2.5.
 267 .LP
 268 In many implementations, including
 269 .IR glibc ,
 270 a 0 in
 271 .I tm_mday
 272 is interpreted as meaning the last day of the preceding month.
 273 .LP
 274 The glibc version of \fIstruct tm\fP has additional fields
 275 .sp
 276 .RS
 277 .nf
 278 long tm_gmtoff;           /* Seconds east of UTC */
 279 const char *tm_zone;      /* Timezone abbreviation */
 280 .fi
 281 .RE
 282 .sp
 283 defined when
 284 .B _BSD_SOURCE
 285 was set before including
 286 .IR <time.h> .
 287 This is a BSD extension, present in 4.3BSD-Reno.
 288 .SH "SEE ALSO"
 289 .BR date (1),
 290 .BR gettimeofday (2),
 291 .BR time (2),
 292 .BR utime (2),
 293 .BR clock (3),
 294 .BR difftime (3),
 295 .BR strftime (3),
 296 .BR strptime (3),
 297 .BR timegm (3),
 298 .BR tzset (3),
 299 .BR time (7)