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