newctime.3

   1 .TH NEWCTIME 3
   2 .SH NAME
   3 asctime, ctime, difftime, gmtime, localtime, mktime \- convert date and time
   4 .SH SYNOPSIS
   5 .nf
   6 .ie \n(.g .ds - \f(CW-\fP
   7 .el ds - \-
   8 .B #include <time.h>
   9 .PP
  10 .BR "extern char *tzname[];" " /\(** (optional) \(**/"
  11 .PP
  12 .B char *ctime(time_t const *clock);
  13 .PP
  14 .B char *ctime_r(time_t const *clock, char *buf);
  15 .PP
  16 .B double difftime(time_t time1, time_t time0);
  17 .PP
  18 .B char *asctime(struct tm const *tm);
  19 .PP
  20 .B "char *asctime_r(struct tm const *restrict tm,"
  21 .B "    char *restrict result);"
  22 .PP
  23 .B struct tm *localtime(time_t const *clock);
  24 .PP
  25 .B "struct tm *localtime_r(time_t const *restrict clock,"
  26 .B "    struct tm *restrict result);"
  27 .PP
  28 .B "struct tm *localtime_rz(timezone_t restrict zone,"
  29 .B "    time_t const *restrict clock,"
  30 .B "    struct tm *restrict result);"
  31 .PP
  32 .B struct tm *gmtime(time_t const *clock);
  33 .PP
  34 .B "struct tm *gmtime_r(time_t const *restrict clock,"
  35 .B "    struct tm *restrict result);"
  36 .PP
  37 .B time_t mktime(struct tm *tm);
  38 .PP
  39 .B "time_t mktime_z(timezone_t restrict zone,"
  40 .B "    struct tm *restrict tm);"
  41 .PP
  42 .B cc ... \*-ltz
  43 .fi
  44 .SH DESCRIPTION
  45 .ie '\(en'' .ds en \-
  46 .el .ds en \(en
  47 .ie '\(lq'' .ds lq \&"\"
  48 .el .ds lq \(lq\"
  49 .ie '\(rq'' .ds rq \&"\"
  50 .el .ds rq \(rq\"
  51 .de q
  52 \\$3\*(lq\\$1\*(rq\\$2
  53 ..
  54 .I Ctime
  55 converts a long integer, pointed to by
  56 .IR clock ,
  57 and returns a pointer to a
  58 string of the form
  59 .br
  60 .ce
  61 .eo
  62 Thu Nov 24 18:22:48 1986\n\0
  63 .br
  64 .ec
  65 Years requiring fewer than four characters are padded with leading zeroes.
  66 For years longer than four characters, the string is of the form
  67 .br
  68 .ce
  69 .eo
  70 Thu Nov 24 18:22:48     81986\n\0
  71 .ec
  72 .br
  73 with five spaces before the year.
  74 These unusual formats are designed to make it less likely that older
  75 software that expects exactly 26 bytes of output will mistakenly output
  76 misleading values for out-of-range years.
  77 .PP
  78 The
  79 .BI * clock
  80 timestamp represents the time in seconds since 1970-01-01 00:00:00
  81 Coordinated Universal Time (UTC).
  82 The POSIX standard says that timestamps must be nonnegative
  83 and must ignore leap seconds.
  84 Many implementations extend POSIX by allowing negative timestamps,
  85 and can therefore represent timestamps that predate the
  86 introduction of UTC and are some other flavor of Universal Time (UT).
  87 Some implementations support leap seconds, in contradiction to POSIX.
  88 .PP
  89 .I Localtime
  90 and
  91 .I gmtime
  92 return pointers to
  93 .q "tm"
  94 structures, described below.
  95 .I Localtime
  96 corrects for the time zone and any time zone adjustments
  97 (such as Daylight Saving Time in the United States).
  98 After filling in the
  99 .q "tm"
 100 structure,
 101 .I localtime
 102 sets the
 103 .BR tm_isdst 'th
 104 element of
 105 .B tzname
 106 to a pointer to a string that's the time zone abbreviation to be used with
 107 .IR localtime 's
 108 return value.
 109 .PP
 110 .I Gmtime
 111 converts to Coordinated Universal Time.
 112 .PP
 113 .I Asctime
 114 converts a time value contained in a
 115 .q "tm"
 116 structure to a string,
 117 as shown in the above example,
 118 and returns a pointer to the string.
 119 .PP
 120 .I Mktime
 121 converts the broken-down time,
 122 expressed as local time,
 123 in the structure pointed to by
 124 .I tm
 125 into a calendar time value with the same encoding as that of the values
 126 returned by the
 127 .I time
 128 function.
 129 The original values of the
 130 .B tm_wday
 131 and
 132 .B tm_yday
 133 components of the structure are ignored,
 134 and the original values of the other components are not restricted
 135 to their normal ranges.
 136 (A positive or zero value for
 137 .B tm_isdst
 138 causes
 139 .I mktime
 140 to presume initially that summer time (for example, Daylight Saving Time
 141 in the U.S.A.)
 142 respectively,
 143 is or is not in effect for the specified time.
 144 A negative value for
 145 .B tm_isdst
 146 causes the
 147 .I mktime
 148 function to attempt to divine whether summer time is in effect
 149 for the specified time; in this case it does not use a consistent
 150 rule and may give a different answer when later
 151 presented with the same argument.)
 152 On successful completion, the values of the
 153 .B tm_wday
 154 and
 155 .B tm_yday
 156 components of the structure are set appropriately,
 157 and the other components are set to represent the specified calendar time,
 158 but with their values forced to their normal ranges; the final value of
 159 .B tm_mday
 160 is not set until
 161 .B tm_mon
 162 and
 163 .B tm_year
 164 are determined.
 165 .I Mktime
 166 returns the specified calendar time;
 167 If the calendar time cannot be represented,
 168 it returns \-1.
 169 .PP
 170 .I Difftime
 171 returns the difference between two calendar times,
 172 .RI ( time1
 173 \-
 174 .IR time0 ),
 175 expressed in seconds.
 176 .PP
 177 .IR Ctime_r ,
 178 .IR localtime_r ,
 179 .IR gmtime_r ,
 180 and
 181 .I asctime_r
 182 are like their unsuffixed counterparts, except that they accept an
 183 additional argument specifying where to store the result if successful.
 184 .PP
 185 .IR Localtime_rz
 186 and
 187 .I mktime_z
 188 are like their unsuffixed counterparts, except that they accept an
 189 extra initial
 190 .B zone
 191 argument specifying the time zone to be used for conversion.
 192 If
 193 .B zone
 194 is null, UTC is used; otherwise,
 195 .B zone
 196 should be have been allocated by
 197 .I tzalloc
 198 and should not be freed until after all uses (e.g., by calls to
 199 .IR strftime )
 200 of the filled-in
 201 .B tm_zone
 202 fields.
 203 .PP
 204 Declarations of all the functions and externals, and the
 205 .q "tm"
 206 structure,
 207 are in the
 208 .B <time.h>
 209 header file.
 210 The structure (of type)
 211 .B struct tm
 212 includes the following fields:
 213 .RS
 214 .PP
 215 .nf
 216 .ta 2n +\w'long tm_gmtoff;nn'u
 217         int tm_sec;     /\(** seconds (0\*(en60) \(**/
 218         int tm_min;     /\(** minutes (0\*(en59) \(**/
 219         int tm_hour;    /\(** hours (0\*(en23) \(**/
 220         int tm_mday;    /\(** day of month (1\*(en31) \(**/
 221         int tm_mon;     /\(** month of year (0\*(en11) \(**/
 222         int tm_year;    /\(** year \- 1900 \(**/
 223         int tm_wday;    /\(** day of week (Sunday = 0) \(**/
 224         int tm_yday;    /\(** day of year (0\*(en365) \(**/
 225         int tm_isdst;   /\(** is summer time in effect? \(**/
 226         char \(**tm_zone;       /\(** time zone abbreviation (optional) \(**/
 227         long tm_gmtoff; /\(** offset from UT in seconds (optional) \(**/
 228 .fi
 229 .RE
 230 .PP
 231 .I Tm_isdst
 232 is non-zero if summer time is in effect.
 233 .PP
 234 .I Tm_gmtoff
 235 is the offset (in seconds) of the time represented
 236 from UT, with positive values indicating east
 237 of the Prime Meridian.
 238 The field's name is derived from Greenwich Mean Time, a precursor of UT.
 239 .PP
 240 In
 241 .B struct tm
 242 the
 243 .I tm_zone
 244 and
 245 .I tm_gmtoff
 246 fields exist, and are filled in, only if arrangements to do
 247 so were made when the library containing these functions was
 248 created.
 249 Similarly, the
 250 .B tzname
 251 variable is optional.
 252 There is no guarantee that these fields and this variable will
 253 continue to exist in this form in future releases of this code.
 254 .SH FILES
 255 .ta \w'/usr/local/etc/zoneinfo/posixrules\0\0'u
 256 /usr/local/etc/zoneinfo time zone information directory
 257 .br
 258 /usr/local/etc/zoneinfo/localtime       local time zone file
 259 .br
 260 /usr/local/etc/zoneinfo/posixrules      used with POSIX-style TZ's
 261 .br
 262 /usr/local/etc/zoneinfo/GMT     for UTC leap seconds
 263 .sp
 264 If
 265 .B /usr/local/etc/zoneinfo/GMT
 266 is absent,
 267 UTC leap seconds are loaded from
 268 .BR /usr/local/etc/zoneinfo/posixrules .
 269 .SH SEE ALSO
 270 getenv(3),
 271 newstrftime(3),
 272 newtzset(3),
 273 time(2),
 274 tzfile(5)
 275 .SH NOTES
 276 The return values of
 277 .IR asctime ,
 278 .IR ctime ,
 279 .IR gmtime ,
 280 and
 281 .I localtime
 282 point to static data
 283 overwritten by each call.
 284 The
 285 .B tzname
 286 variable (once set) and the
 287 .B tm_zone
 288 field of a returned
 289 .B "struct tm"
 290 both point to an array of characters that
 291 can be freed or overwritten by later calls to the functions
 292 .IR localtime ,
 293 .IR tzfree ,
 294 and
 295 .IR tzset ,
 296 if these functions affect the time zone information that specifies the
 297 abbreviation in question.
 298 The remaining functions and data are thread-safe.
 299 .PP
 300 .IR Asctime ,
 301 .IR asctime_r ,
 302 .IR ctime ,
 303 and
 304 .I ctime_r
 305 behave strangely for years before 1000 or after 9999.
 306 The 1989 and 1999 editions of the C Standard say
 307 that years from \-99 through 999 are converted without
 308 extra spaces, but this conflicts with longstanding
 309 tradition and with this implementation.
 310 The 2011 edition says that the behavior
 311 is undefined if the year is before 1000 or after 9999.
 312 Traditional implementations of these two functions are
 313 restricted to years in the range 1900 through 2099.
 314 To avoid this portability mess, new programs should use
 315 .I strftime
 316 instead.
 317 .\" This file is in the public domain, so clarified as of
 318 .\" 2009-05-17 by Arthur David Olson.