lib/libc/stdtime/ctime.3

   1 .\" Copyright (c) 1989, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" Arthur Olson.
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. All advertising materials mentioning features or use of this software
  15 .\"    must display the following acknowledgement:
  16 .\"     This product includes software developed by the University of
  17 .\"     California, Berkeley and its contributors.
  18 .\" 4. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\" @(#)newctime.3      8.2
  35 .\" $FreeBSD: src/lib/libc/stdtime/ctime.3,v 1.11.2.7 2003/05/23 23:53:40 keramida Exp $
  36 .\" $DragonFly: src/lib/libc/stdtime/ctime.3,v 1.4 2008/10/19 20:15:58 swildner Exp $
  37 .\"
  38 .Dd October 19, 2008
  39 .Dt CTIME 3
  40 .Os
  41 .Sh NAME
  42 .Nm asctime ,
  43 .Nm asctime_r ,
  44 .Nm ctime ,
  45 .Nm ctime_r ,
  46 .Nm difftime ,
  47 .Nm gmtime ,
  48 .Nm gmtime_r ,
  49 .Nm localtime ,
  50 .Nm localtime_r ,
  51 .Nm mktime ,
  52 .Nm timegm
  53 .Nd transform binary date and time values
  54 .Sh LIBRARY
  55 .Lb libc
  56 .Sh SYNOPSIS
  57 .In time.h
  58 .Vt extern char *tzname[2] ;
  59 .Ft char *
  60 .Fn ctime "const time_t *clock"
  61 .Ft double
  62 .Fn difftime "time_t time1" "time_t time0"
  63 .Ft char *
  64 .Fn asctime "const struct tm *tm"
  65 .Ft struct tm *
  66 .Fn localtime "const time_t *clock"
  67 .Ft struct tm *
  68 .Fn gmtime "const time_t *clock"
  69 .Ft time_t
  70 .Fn mktime "struct tm *tm"
  71 .Ft time_t
  72 .Fn timegm "struct tm *tm"
  73 .Ft char *
  74 .Fn ctime_r "const time_t *clock" "char *buf"
  75 .Ft struct tm *
  76 .Fn localtime_r "const time_t *clock" "struct tm *result"
  77 .Ft struct tm *
  78 .Fn gmtime_r "const time_t *clock" "struct tm *result"
  79 .Ft char *
  80 .Fn asctime_r "const struct tm *tm" "char *buf"
  81 .Sh DESCRIPTION
  82 The functions
  83 .Fn ctime ,
  84 .Fn gmtime
  85 and
  86 .Fn localtime
  87 all take as an argument a time value representing the time in seconds since
  88 the Epoch (00:00:00
  89 .Tn UTC ,
  90 1970-01-01; see
  91 .Xr time 3 ) .
  92 .Pp
  93 The function
  94 .Fn localtime
  95 converts the time value pointed at by
  96 .Fa clock ,
  97 and returns a pointer to a
  98 .Dq Fa struct tm
  99 (described below) which contains
 100 the broken-out time information for the value after adjusting for the current
 101 time zone and any time zone adjustments.
 102 Time zone adjustments are performed as specified by the
 103 .Ev TZ
 104 environment variable (see
 105 .Xr tzset 3 ) .
 106 .Pp
 107 After filling in the tm structure,
 108 .Fn localtime
 109 sets the
 110 .Fa tm_isdst Ns 'th
 111 element of
 112 .Fa tzname
 113 to a pointer to an
 114 .Tn ASCII
 115 string that's the time zone abbreviation to be
 116 used with
 117 .Fn localtime Ns 's
 118 return value.
 119 .Pp
 120 The function
 121 .Fn gmtime
 122 similarly converts the time value, but without any time zone adjustment,
 123 and returns a pointer to a tm structure (described below).
 124 .Pp
 125 The
 126 .Fn ctime
 127 function
 128 adjusts the time value for the current time zone in the same manner as
 129 .Fn localtime ,
 130 and returns a pointer to a string of the form:
 131 .Bd -literal -offset indent
 132 Thu Nov 24 18:22:48 1986\en\e0
 133 .Ed
 134 .Pp
 135 Years requiring fewer than four characters are padded with leading zeroes.
 136 For years longer than four characters, the string is of the form
 137 .Bd -literal -offset indent
 138 Thu Nov 24 18:22:48     81986\en\e0
 139 .Ed
 140 .Pp
 141 with five spaces before the year.
 142 These unusual formats are designed to make it less likely that older
 143 software that expects exactly 26 bytes of output will mistakenly output
 144 misleading values for out-of-range years.
 145 .Pp
 146 The
 147 .Fn ctime_r
 148 function
 149 provides the same functionality as
 150 .Fn ctime
 151 except the caller must provide the output buffer
 152 .Fa buf
 153 to store the result, which must be at least 26 characters long.
 154 The
 155 .Fn localtime_r
 156 and
 157 .Fn gmtime_r
 158 functions
 159 provide the same functionality as
 160 .Fn localtime
 161 and
 162 .Fn gmtime
 163 respectively, except the caller must provide the output buffer
 164 .Fa result .
 165 .Pp
 166 The
 167 .Fn asctime
 168 function
 169 converts the broken down time in the structure
 170 .Fa tm
 171 pointed at by
 172 .Fa *tm
 173 to the form
 174 shown in the example above.
 175 .Pp
 176 The
 177 .Fn asctime_r
 178 function
 179 provides the same functionality as
 180 .Fn asctime
 181 except the caller provide the output buffer
 182 .Fa buf
 183 to store the result, which must be at least 26 characters long.
 184 .Pp
 185 The functions
 186 .Fn mktime
 187 and
 188 .Fn timegm
 189 convert the broken-down time in the structure
 190 pointed to by tm into a time value with the same encoding as that of the
 191 values returned by the
 192 .Xr time 3
 193 function (that is, seconds from the Epoch,
 194 .Tn UTC ) .
 195 The
 196 .Fn mktime
 197 function
 198 interprets the input structure according to the current timezone setting
 199 (see
 200 .Xr tzset 3 ) .
 201 The
 202 .Fn timegm
 203 function
 204 interprets the input structure as representing Universal Coordinated Time
 205 .Pq Tn UTC .
 206 .Pp
 207 The original values of the
 208 .Fa tm_wday
 209 and
 210 .Fa tm_yday
 211 components of the structure are ignored, and the original values of the
 212 other components are not restricted to their normal ranges, and will be
 213 normalized if needed.
 214 For example,
 215 October 40 is changed into November 9,
 216 a
 217 .Fa tm_hour
 218 of \-1 means 1 hour before midnight,
 219 .Fa tm_mday
 220 of 0 means the day preceding the current month, and
 221 .Fa tm_mon
 222 of \-2 means 2 months before January of
 223 .Fa tm_year .
 224 (A positive or zero value for
 225 .Fa tm_isdst
 226 causes
 227 .Fn mktime
 228 to presume initially that summer time (for example, Daylight Saving Time)
 229 is or is not in effect for the specified time, respectively.
 230 A negative value for
 231 .Fa tm_isdst
 232 causes the
 233 .Fn mktime
 234 function to attempt to divine whether summer time is in effect for the
 235 specified time; in this case it does not use a consistent
 236 rule and may give a different answer when later
 237 presented with the same argument.
 238 The
 239 .Fa tm_isdst
 240 and
 241 .Fa tm_gmtoff
 242 members are forced to zero by
 243 .Fn timegm . )
 244 .Pp
 245 On successful completion, the values of the
 246 .Fa tm_wday
 247 and
 248 .Fa tm_yday
 249 components of the structure are set appropriately, and the other components
 250 are set to represent the specified calendar time, but with their values
 251 forced to their normal ranges; the final value of
 252 .Fa tm_mday
 253 is not set until
 254 .Fa tm_mon
 255 and
 256 .Fa tm_year
 257 are determined.
 258 The
 259 .Fn mktime
 260 function
 261 returns the specified calendar time; if the calendar time cannot be
 262 represented, it returns \-1;
 263 .Pp
 264 The
 265 .Fn difftime
 266 function
 267 returns the difference between two calendar times,
 268 .Pf ( Fa time1
 269 -
 270 .Fa time0 ) ,
 271 expressed in seconds.
 272 .Pp
 273 External declarations as well as the tm structure definition are in the
 274 .In time.h
 275 include file.
 276 The tm structure includes at least the following fields:
 277 .Bd -literal -offset indent
 278 int tm_sec;     /\(** seconds (0 - 60) \(**/
 279 int tm_min;     /\(** minutes (0 - 59) \(**/
 280 int tm_hour;    /\(** hours (0 - 23) \(**/
 281 int tm_mday;    /\(** day of month (1 - 31) \(**/
 282 int tm_mon;     /\(** month of year (0 - 11) \(**/
 283 int tm_year;    /\(** year \- 1900 \(**/
 284 int tm_wday;    /\(** day of week (Sunday = 0) \(**/
 285 int tm_yday;    /\(** day of year (0 - 365) \(**/
 286 int tm_isdst;   /\(** is summer time in effect? \(**/
 287 char \(**tm_zone;       /\(** abbreviation of timezone name \(**/
 288 long tm_gmtoff; /\(** offset from UTC in seconds \(**/
 289 .Ed
 290 .Pp
 291 The
 292 field
 293 .Fa tm_isdst
 294 is non-zero if summer time is in effect.
 295 .Pp
 296 The field
 297 .Fa tm_gmtoff
 298 is the offset (in seconds) of the time represented from
 299 .Tn UTC ,
 300 with positive
 301 values indicating east of the Prime Meridian.
 302 .Sh COMPATIBILITY
 303 The
 304 .Fn asctime
 305 and
 306 .Fn ctime
 307 functions
 308 behave strangely for years before 1000 or after 9999.
 309 The 1989 and 1999 editions of the C Standard say
 310 that years from -99 through 999 are converted without
 311 extra spaces, but this conflicts with longstanding
 312 tradition and with this implementation.
 313 Traditional implementations of these two functions are
 314 restricted to years in the range 1900 through 2099.
 315 To avoid this portability mess, new programs should use
 316 .Xr strftime 3
 317 instead.
 318 .Sh SEE ALSO
 319 .Xr date 1 ,
 320 .Xr gettimeofday 2 ,
 321 .Xr getenv 3 ,
 322 .Xr strftime 3 ,
 323 .Xr time 3 ,
 324 .Xr tzset 3 ,
 325 .Xr tzfile 5
 326 .Sh STANDARDS
 327 The
 328 .Fn asctime ,
 329 .Fn ctime ,
 330 .Fn difftime ,
 331 .Fn gmtime ,
 332 .Fn localtime ,
 333 and
 334 .Fn mktime
 335 functions conform to
 336 .St -isoC ,
 337 and conform to
 338 .St -p1003.1-96
 339 provided the selected local timezone does not contain a leap-second table
 340 (see
 341 .Xr zic 8 ) .
 342 .Pp
 343 The
 344 .Fn asctime_r ,
 345 .Fn ctime_r ,
 346 .Fn gmtime_r ,
 347 and
 348 .Fn localtime_r
 349 functions are expected to conform to
 350 .St -p1003.1-96
 351 (again provided the selected local timezone does not contain a leap-second
 352 table).
 353 .Pp
 354 The
 355 .Fn timegm
 356 function is not specified by any standard; its function cannot be
 357 completely emulated using the standard functions described above.
 358 .Sh HISTORY
 359 This manual page is derived from
 360 the time package contributed to Berkeley by
 361 .An Arthur Olson
 362 and which appeared in
 363 .Bx 4.3 .
 364 .Sh BUGS
 365 Except for
 366 .Fn difftime ,
 367 .Fn mktime ,
 368 and the
 369 .Fn \&_r
 370 variants of the other functions,
 371 these functions leaves their result in an internal static object and return
 372 a pointer to that object.
 373 Subsequent calls to these
 374 function will modify the same object.
 375 .Pp
 376 The C Standard provides no mechanism for a program to modify its current
 377 local timezone setting, and the
 378 .Tn POSIX Ns No \&-standard
 379 method is not reentrant.  (However, thread-safe implementations are provided
 380 in the
 381 .Tn POSIX
 382 threaded environment.)
 383 .Pp
 384 The
 385 .Va tm_zone
 386 field of a returned
 387 .Vt tm
 388 structure points to a static array of characters,
 389 which will also be overwritten by any subsequent calls (as well as by
 390 subsequent calls to
 391 .Xr tzset 3
 392 and
 393 .Xr tzsetwall 3 ) .
 394 .Pp
 395 Use of the external variable
 396 .Fa tzname
 397 is discouraged; the
 398 .Fa tm_zone
 399 entry in the tm structure is preferred.