lib/libc/gen/time.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 .\" the American National Standards Committee X3, on Information
   6 .\" Processing Systems.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  11 .\" 1. Redistributions of source code must retain the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer.
  13 .\" 2. Redistributions in binary form must reproduce the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer in the
  15 .\"    documentation and/or other materials provided with the distribution.
  16 .\" 3. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     @(#)time.3      8.1 (Berkeley) 6/4/93
  33 .\" $FreeBSD$
  34 .\"
  35 .Dd April 14, 2022
  36 .Dt TIME 3
  37 .Os
  38 .Sh NAME
  39 .Nm time
  40 .Nd get time of day
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In time.h
  45 .Ft time_t
  46 .Fn time "time_t *tloc"
  47 .Sh DESCRIPTION
  48 The
  49 .Fn time
  50 function
  51 returns the value of time in seconds since 0 hours, 0 minutes,
  52 0 seconds, January 1, 1970, Coordinated Universal Time (UTC).
  53 If an error occurs,
  54 .Fn time
  55 returns the value
  56 .Po Vt time_t Pc Ns \-1 .
  57 .Pp
  58 The return value is also stored in
  59 .No \&* Ns Va tloc ,
  60 provided that
  61 .Va tloc
  62 is non-null.
  63 .Sh ERRORS
  64 The
  65 .Fn time
  66 function may fail for any of the reasons described in
  67 .Xr clock_gettime 2 .
  68 .Sh SEE ALSO
  69 .Xr clock_gettime 2 ,
  70 .Xr gettimeofday 2 ,
  71 .Xr ctime 3
  72 .Sh STANDARDS
  73 The
  74 .Nm
  75 function conforms to
  76 .St -p1003.1-2008 .
  77 .Sh HISTORY
  78 The
  79 .Fn time
  80 system call first appeared in
  81 .At v1 .
  82 Through the
  83 .At v3 ,
  84 it returned 60 Hz ticks since an epoch that changed occasionally, because it
  85 was a 32-bit value that overflowed in a little over 2 years.
  86 .Pp
  87 In
  88 .At v4
  89 the granularity of the return value was reduced to whole seconds,
  90 delaying the aforementioned overflow until 2038.
  91 .Pp
  92 .At v7
  93 introduced the
  94 .Fn ftime
  95 system call, which returned time at a millisecond level,
  96 though retained the
  97 .Fn gtime
  98 system call (exposed as
  99 .Fn time
 100 in userland).
 101 .Fn time
 102 could have been implemented as a wrapper around
 103 .Fn ftime ,
 104 but that wasn't done.
 105 .Pp
 106 .Bx 4.1c
 107 implemented a higher-precision time function
 108 .Fn gettimeofday
 109 to replace
 110 .Fn ftime
 111 and reimplemented
 112 .Fn time
 113 in terms of that.
 114 .Pp
 115 Since
 116 .Fx 9
 117 the implementation of
 118 .Fn time
 119 uses
 120 .Fn clock_gettime "CLOCK_SECOND"
 121 instead of
 122 .Fn gettimeofday
 123 for performance reasons.
 124 .Sh BUGS
 125 Neither
 126 .St -isoC-99
 127 nor
 128 .St -p1003.1-2001
 129 requires
 130 .Fn time
 131 to set
 132 .Va errno
 133 on failure; thus, it is impossible for an application to distinguish
 134 the valid time value \-1 (representing the last UTC second of 1969)
 135 from the error return value.
 136 .Pp
 137 Systems conforming to earlier versions of the C and POSIX
 138 standards (including older versions of
 139 .Fx )
 140 did not set
 141 .No \&* Ns Va tloc
 142 in the error case.