man2/time.2

   1 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" Modified by Michael Haardt <michael@moria.de>
   6 .\" Modified Sat Jul 24 14:13:40 1993 by Rik Faith <faith@cs.unc.edu>
   7 .\" Additions by Joseph S. Myers <jsm28@cam.ac.uk>, 970909
   8 .\"
   9 .TH TIME 2 2022-09-09 "Linux man-pages (unreleased)"
  10 .SH NAME
  11 time \- get time in seconds
  12 .SH LIBRARY
  13 Standard C library
  14 .RI ( libc ", " \-lc )
  15 .SH SYNOPSIS
  16 .nf
  17 .B #include <time.h>
  18 .PP
  19 .BI "time_t time(time_t *" tloc );
  20 .fi
  21 .SH DESCRIPTION
  22 .BR time ()
  23 returns the time as the number of seconds since the
  24 Epoch, 1970-01-01 00:00:00 +0000 (UTC).
  25 .PP
  26 If
  27 .I tloc
  28 is non-NULL,
  29 the return value is also stored in the memory pointed to by
  30 .IR tloc .
  31 .SH RETURN VALUE
  32 On success, the value of time in seconds since the Epoch is returned.
  33 On error, \fI((time_t)\ \-1)\fP is returned, and
  34 .I errno
  35 is set to indicate the error.
  36 .SH ERRORS
  37 .TP
  38 .B EFAULT
  39 .I tloc
  40 points outside your accessible address space (but see BUGS).
  41 .IP
  42 On systems where the C library
  43 .BR time ()
  44 wrapper function invokes an implementation provided by the
  45 .BR vdso (7)
  46 (so that there is no trap into the kernel),
  47 an invalid address may instead trigger a
  48 .B SIGSEGV
  49 signal.
  50 .SH STANDARDS
  51 SVr4, 4.3BSD, C89, C99, POSIX.1-2001.
  52 .\" Under 4.3BSD, this call is obsoleted by
  53 .\" .BR gettimeofday (2).
  54 POSIX does not specify any error conditions.
  55 .SH NOTES
  56 POSIX.1 defines
  57 .I seconds since the Epoch
  58 using a formula that approximates the number of seconds between a
  59 specified time and the Epoch.
  60 This formula takes account of the facts that
  61 all years that are evenly divisible by 4 are leap years,
  62 but years that are evenly divisible by 100 are not leap years
  63 unless they are also evenly divisible by 400,
  64 in which case they are leap years.
  65 This value is not the same as the actual number of seconds between the time
  66 and the Epoch, because of leap seconds and because system clocks are not
  67 required to be synchronized to a standard reference.
  68 The intention is that the interpretation of seconds since the Epoch values be
  69 consistent; see POSIX.1-2008 Rationale A.4.15 for further rationale.
  70 .PP
  71 On Linux, a call to
  72 .BR time ()
  73 with
  74 .I tloc
  75 specified as NULL cannot fail with the error
  76 .BR EOVERFLOW ,
  77 even on ABIs where
  78 .I time_t
  79 is a signed 32-bit integer and the clock reaches or exceeds 2**31 seconds
  80 (2038-01-19 03:14:08 UTC, ignoring leap seconds).
  81 (POSIX.1 permits, but does not require, the
  82 .B EOVERFLOW
  83 error in the case where the seconds since the Epoch will not fit in
  84 .IR time_t .)
  85 Instead, the behavior on Linux is undefined when the system time is out of the
  86 .I time_t
  87 range.
  88 Applications intended to run after 2038 should use ABIs with
  89 .I time_t
  90 wider than 32 bits.
  91 .SH BUGS
  92 Error returns from this system call are indistinguishable from
  93 successful reports that the time is a few seconds
  94 .I before
  95 the Epoch, so the C library wrapper function never sets
  96 .I errno
  97 as a result of this call.
  98 .PP
  99 The
 100 .I tloc
 101 argument is obsolescent and should always be NULL in new code.
 102 When
 103 .I tloc
 104 is NULL, the call cannot fail.
 105 .\"
 106 .SS C library/kernel differences
 107 On some architectures, an implementation of
 108 .BR time ()
 109 is provided in the
 110 .BR vdso (7).
 111 .SH SEE ALSO
 112 .BR date (1),
 113 .BR gettimeofday (2),
 114 .BR ctime (3),
 115 .BR ftime (3),
 116 .BR time (7),
 117 .BR vdso (7)