diff options
Diffstat (limited to 'man-pages-posix-2003/man3p/time.3p')
| -rw-r--r-- | man-pages-posix-2003/man3p/time.3p | 157 |
1 files changed, 157 insertions, 0 deletions
diff --git a/man-pages-posix-2003/man3p/time.3p b/man-pages-posix-2003/man3p/time.3p new file mode 100644 index 0000000..281b932 --- /dev/null +++ b/man-pages-posix-2003/man3p/time.3p @@ -0,0 +1,157 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "TIME" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" time +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.SH NAME +time \- get time +.SH SYNOPSIS +.LP +\fB#include <time.h> +.br +.sp +time_t time(time_t *\fP\fItloc\fP\fB); +.br +\fP +.SH DESCRIPTION +.LP +The \fItime\fP() function shall return the value of time in seconds +since the Epoch. +.LP +The \fItloc\fP argument points to an area where the return value is +also stored. If \fItloc\fP is a null pointer, no value is +stored. +.SH RETURN VALUE +.LP +Upon successful completion, \fItime\fP() shall return the value of +time. Otherwise, (\fBtime_t\fP)-1 shall be returned. +.SH ERRORS +.LP +No errors are defined. +.LP +\fIThe following sections are informative.\fP +.SH EXAMPLES +.SS Getting the Current Time +.LP +The following example uses the \fItime\fP() function to calculate +the time elapsed, in seconds, since the Epoch, \fIlocaltime\fP() to +convert that value to a broken-down time, and \fIasctime\fP() to convert +the broken-down time values into a printable string. +.sp +.RS +.nf + +\fB#include <stdio.h> +#include <time.h> +.sp + +int main(void) +{ +time_t result; +.sp + + result = time(NULL); + printf("%s%ju secs since the Epoch\\n", + asctime(localtime(&result)), + (uintmax_t)result); + return(0); +} +\fP +.fi +.RE +.LP +This example writes the current time to \fIstdout\fP in a form like +this: +.sp +.RS +.nf + +\fBWed Jun 26 10:32:15 1996 +835810335 secs since the Epoch +\fP +.fi +.RE +.SS Timing an Event +.LP +The following example gets the current time, prints it out in the +user's format, and prints the number of minutes to an event +being timed. +.sp +.RS +.nf + +\fB#include <time.h> +#include <stdio.h> +\&... +time_t now; +int minutes_to_event; +\&... +time(&now); +minutes_to_event = ...; +printf("The time is "); +puts(asctime(localtime(&now))); +printf("There are %d minutes to the event.\\n", + minutes_to_event); +\&... +\fP +.fi +.RE +.SH APPLICATION USAGE +.LP +None. +.SH RATIONALE +.LP +The \fItime\fP() function returns a value in seconds (type \fBtime_t\fP) +while \fItimes\fP() returns a set of values in clock ticks (type \fBclock_t\fP). +Some historical +implementations, such as 4.3 BSD, have mechanisms capable of returning +more precise times (see below). A generalized timing scheme +to unify these various timing mechanisms has been proposed but not +adopted. +.LP +Implementations in which \fBtime_t\fP is a 32-bit signed integer (many +historical implementations) fail in the year 2038. +IEEE\ Std\ 1003.1-2001 does not address this problem. However, the +use of the \fBtime_t\fP type is mandated in order to +ease the eventual fix. +.LP +The use of the \fI<time.h>\fP header instead of \fI<sys/types.h>\fP +allows compatibility with the ISO\ C standard. +.LP +Many historical implementations (including Version 7) and the 1984 +/usr/group standard use \fBlong\fP instead of \fBtime_t\fP. +This volume of IEEE\ Std\ 1003.1-2001 uses the latter type in order +to agree with the ISO\ C standard. +.LP +4.3 BSD includes \fItime\fP() only as an alternate function to the +more flexible \fIgettimeofday\fP() function. +.SH FUTURE DIRECTIONS +.LP +In a future version of this volume of IEEE\ Std\ 1003.1-2001, \fBtime_t\fP +is likely to be required to be capable of +representing times far in the future. Whether this will be mandated +as a 64-bit type or a requirement that a specific date in the +future be representable (for example, 10000 AD) is not yet determined. +Systems purchased after the approval of this volume of +IEEE\ Std\ 1003.1-2001 should be evaluated to determine whether their +lifetime will extend past 2038. +.SH SEE ALSO +.LP +\fIasctime\fP(), \fIclock\fP(), \fIctime\fP(), +\fIdifftime\fP(), \fIgettimeofday\fP(), \fIgmtime\fP(), \fIlocaltime\fP(), +\fImktime\fP(), +\fIstrftime\fP(), \fIstrptime\fP(), \fIutime\fP(), the Base Definitions +volume of IEEE\ Std\ 1003.1-2001, \fI<time.h>\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version and the original IEEE and +The Open Group Standard, the original IEEE and The Open Group Standard +is the referee document. The original Standard can be obtained online at +http://www.opengroup.org/unix/online.html . |