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  2004-11-16 "" "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 .SH DESCRIPTION
  60 The \fBctime\fP(), \fBgmtime\fP() and \fBlocaltime\fP() functions all take
  61 an argument of data type \fItime_t\fP which represents calendar time.
  62 When interpreted as an absolute time value, it represents the number of
  63 seconds elapsed since 00:00:00 on January 1, 1970, Coordinated Universal
  64 Time (UTC).
  65 .PP
  66 The \fBasctime\fP() and \fBmktime\fP() functions both take an argument
  67 representing broken-down time which is a representation
  68 separated into year, month, day, etc.
  69 .PP
  70 Broken-down time is stored
  71 in the structure \fItm\fP which is defined in \fI<time.h>\fP as follows:
  72 .sp
  73 .RS
  74 .nf
  75 struct tm {
  76     int tm_sec;         /* seconds */
  77     int tm_min;         /* minutes */
  78     int tm_hour;        /* hours */
  79     int tm_mday;        /* day of the month */
  80     int tm_mon;         /* month */
  81     int tm_year;        /* year */
  82     int tm_wday;        /* day of the week */
  83     int tm_yday;        /* day in the year */
  84     int tm_isdst;       /* daylight saving time */
  85 };
  86 .fi
  87 .RE
  88 .PP
  89 The members of the \fItm\fP structure are:
  90 .TP
  91 .I tm_sec
  92 The number of seconds after the minute, normally in the range 0 to 59,
  93 but can be up to 60 to allow for leap seconds.
  94 .TP
  95 .I tm_min
  96 The number of minutes after the hour, in the range 0 to 59.
  97 .TP
  98 .I tm_hour
  99 The number of hours past midnight, in the range 0 to 23.
 100 .TP
 101 .I tm_mday
 102 The day of the month, in the range 1 to 31.
 103 .TP
 104 .I tm_mon
 105 The number of months since January, in the range 0 to 11.
 106 .TP
 107 .I tm_year
 108 The number of years since 1900.
 109 .TP
 110 .I tm_wday
 111 The number of days since Sunday, in the range 0 to 6.
 112 .TP
 113 .I tm_yday
 114 The number of days since January 1, in the range 0 to 365.
 115 .TP
 116 .I tm_isdst
 117 A flag that indicates whether daylight saving time is in effect at the
 118 time described.
 119 The value is positive if daylight saving time is in
 120 effect, zero if it is not, and negative if the information is not
 121 available.
 122 .PP
 123 The call
 124 .BI ctime( t )
 125 is equivalent to
 126 .BI asctime(localtime( t )) \fR.
 127 It converts the calendar time \fIt\fP into a string of the form
 128 .sp
 129 .RS
 130 "Wed Jun 30 21:49:08 1993\\n"
 131 .RE
 132 .sp
 133 The abbreviations for the days of the week are `Sun', `Mon', `Tue', `Wed',
 134 `Thu', `Fri', and `Sat'.
 135 The abbreviations for the months are `Jan',
 136 `Feb', `Mar', `Apr', `May', `Jun', `Jul', `Aug', `Sep', `Oct', `Nov', and
 137 `Dec'.
 138 The return value points to a statically allocated string which
 139 might be overwritten by subsequent calls to any of the date and time
 140 functions.
 141 The function also sets the external variable \fItzname\fP (see
 142 .BR tzset (3))
 143 with information about the current time zone.
 144 The re-entrant version \fBctime_r\fP() does the same, but stores the
 145 string in a user-supplied buffer of length at least 26.
 146 It need not
 147 set \fItzname\fP.
 148 .PP
 149 The \fBgmtime\fP() function converts the calendar time \fItimep\fP to
 150 broken-down time representation, expressed in Coordinated Universal Time
 151 (UTC).
 152 It may return NULL when the year does not fit into an integer.
 153 The return value points to a statically allocated struct which might be
 154 overwritten by subsequent calls to any of the date and time functions.
 155 The \fBgmtime_r\fP() function does the same, but stores the data in a
 156 user-supplied struct.
 157 .PP
 158 The \fBlocaltime\fP() function converts the calendar time \fItimep\fP to
 159 broken-time representation, expressed relative to the user's specified
 160 time zone.
 161 The function acts as if it called
 162 .BR tzset (3)
 163 and sets the external variables \fItzname\fP with
 164 information about the current time zone, \fItimezone\fP with the difference
 165 between Coordinated Universal Time (UTC) and local standard time in
 166 seconds, and \fIdaylight\fP to a non-zero value if daylight savings
 167 time rules apply during some part of the year.
 168 The return value points to a statically allocated struct which might be
 169 overwritten by subsequent calls to any of the date and time functions.
 170 The \fBlocaltime_r\fP() function does the same, but stores the data in a
 171 user-supplied struct.
 172 It need not set \fItzname\fP.
 173 .PP
 174 The \fBasctime\fP() function converts the broken-down time value
 175 \fItm\fP into a string with the same format as \fBctime\fP().
 176 The return value points to a statically allocated string which might be
 177 overwritten by subsequent calls to any of the date and time functions.
 178 The \fBasctime_r\fP() function does the same, but stores the string in
 179 a user-supplied buffer of length at least 26.
 180 .PP
 181 The \fBmktime\fP() function converts a broken-down time structure, expressed
 182 as local time, to calendar time representation.
 183 The function ignores
 184 the specified contents of the structure members \fItm_wday\fP and \fItm_yday\fP
 185 and recomputes them from the other information in the broken-down time
 186 structure.
 187 If structure members are outside their legal interval, they will be
 188 normalized (so that, e.g., 40 October is changed into 9 November).
 189 Calling \fBmktime\fP() also sets the external variable \fItzname\fP with
 190 information about the current time zone.
 191 If the specified broken-down
 192 time cannot be represented as calendar time (seconds since the epoch),
 193 \fBmktime\fP() returns a value of (time_t)(\-1) and does not alter the
 194 \fItm_wday\fP and \fItm_yday\fP members of the broken-down time structure.
 195 .SH "RETURN VALUE"
 196 Each of these functions returns the value described, or NULL
 197 (\-1 in case of \fBmktime\fP()) in case an error was detected.
 198 .SH NOTES
 199 The four functions
 200 .BR asctime (),
 201 .BR ctime (),
 202 .BR gmtime ()
 203 and
 204 .BR localtime ()
 205 return a pointer to static data and hence are not thread-safe.
 206 Thread-safe versions
 207 .BR asctime_r (),
 208 .BR ctime_r (),
 209 .BR gmtime_r ()
 210 and
 211 .BR localtime_r ()
 212 are specified by SUSv2, and available since libc 5.2.5.
 213 .LP
 214 In many implementations, including
 215 .IR glibc ,
 216 a 0 in
 217 .I tm_mday
 218 is interpreted as meaning the last day of the preceding month.
 219 .LP
 220 The glibc version of struct tm has additional fields
 221 .sp
 222 .RS
 223 .nf
 224 long tm_gmtoff;           /* Seconds east of UTC */
 225 const char *tm_zone;      /* Timezone abbreviation */
 226 .fi
 227 .RE
 228 .sp
 229 defined when _BSD_SOURCE was set before including
 230 .IR <time.h> .
 231 This is a BSD extension, present in 4.3BSD-Reno.
 232 .SH "CONFORMING TO"
 233 POSIX.1-2001.
 234 C89 and C99 specify
 235 .BR asctime (),
 236 .BR ctime (),
 237 .BR gmtime (),
 238 .BR localtime (),
 239 and
 240 .BR mktime ()
 241 .SH "SEE ALSO"
 242 .BR date (1),
 243 .BR gettimeofday (2),
 244 .BR time (2),
 245 .BR utime (2),
 246 .BR clock (3),
 247 .BR difftime (3),
 248 .BR strftime (3),
 249 .BR strptime (3),
 250 .BR tzset (3),
 251 .BR time (7)