diff options
Diffstat (limited to 'man2/time.2')
| -rw-r--r-- | man2/time.2 | 117 |
1 files changed, 117 insertions, 0 deletions
diff --git a/man2/time.2 b/man2/time.2 new file mode 100644 index 0000000..f121e9c --- /dev/null +++ b/man2/time.2 @@ -0,0 +1,117 @@ +.\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.\" Modified by Michael Haardt <michael@moria.de> +.\" Modified Sat Jul 24 14:13:40 1993 by Rik Faith <faith@cs.unc.edu> +.\" Additions by Joseph S. Myers <jsm28@cam.ac.uk>, 970909 +.\" +.TH time 2 2023-03-30 "Linux man-pages 6.05.01" +.SH NAME +time \- get time in seconds +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.B #include <time.h> +.PP +.BI "time_t time(time_t *_Nullable " tloc ); +.fi +.SH DESCRIPTION +.BR time () +returns the time as the number of seconds since the +Epoch, 1970-01-01 00:00:00 +0000 (UTC). +.PP +If +.I tloc +is non-NULL, +the return value is also stored in the memory pointed to by +.IR tloc . +.SH RETURN VALUE +On success, the value of time in seconds since the Epoch is returned. +On error, \fI((time_t)\ \-1)\fP is returned, and +.I errno +is set to indicate the error. +.SH ERRORS +.TP +.B EFAULT +.I tloc +points outside your accessible address space (but see BUGS). +.IP +On systems where the C library +.BR time () +wrapper function invokes an implementation provided by the +.BR vdso (7) +(so that there is no trap into the kernel), +an invalid address may instead trigger a +.B SIGSEGV +signal. +.SH VERSIONS +POSIX.1 defines +.I seconds since the Epoch +using a formula that approximates the number of seconds between a +specified time and the Epoch. +This formula takes account of the facts that +all years that are evenly divisible by 4 are leap years, +but years that are evenly divisible by 100 are not leap years +unless they are also evenly divisible by 400, +in which case they are leap years. +This value is not the same as the actual number of seconds between the time +and the Epoch, because of leap seconds and because system clocks are not +required to be synchronized to a standard reference. +The intention is that the interpretation of seconds since the Epoch values be +consistent; see POSIX.1-2008 Rationale A.4.15 for further rationale. +.PP +On Linux, a call to +.BR time () +with +.I tloc +specified as NULL cannot fail with the error +.BR EOVERFLOW , +even on ABIs where +.I time_t +is a signed 32-bit integer and the clock reaches or exceeds 2**31 seconds +(2038-01-19 03:14:08 UTC, ignoring leap seconds). +(POSIX.1 permits, but does not require, the +.B EOVERFLOW +error in the case where the seconds since the Epoch will not fit in +.IR time_t .) +Instead, the behavior on Linux is undefined when the system time is out of the +.I time_t +range. +Applications intended to run after 2038 should use ABIs with +.I time_t +wider than 32 bits. +.SS C library/kernel differences +On some architectures, an implementation of +.BR time () +is provided in the +.BR vdso (7). +.SH STANDARDS +C11, POSIX.1-2008. +.SH HISTORY +SVr4, 4.3BSD, C89, POSIX.1-2001. +.\" Under 4.3BSD, this call is obsoleted by +.\" .BR gettimeofday (2). +.SH BUGS +Error returns from this system call are indistinguishable from +successful reports that the time is a few seconds +.I before +the Epoch, so the C library wrapper function never sets +.I errno +as a result of this call. +.PP +The +.I tloc +argument is obsolescent and should always be NULL in new code. +When +.I tloc +is NULL, the call cannot fail. +.SH SEE ALSO +.BR date (1), +.BR gettimeofday (2), +.BR ctime (3), +.BR ftime (3), +.BR time (7), +.BR vdso (7) |