The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.

#### NAME

> time - get time

#### SYNOPSIS

> ``#include <time.h>
> time_t time(time_t *`tloc`);
> ``

#### DESCRIPTION

> [CX] The functionality described on this reference page is aligned with the ISO C standard. Any conflict between the requirements described here and the ISO C standard is unintentional. This volume of IEEE Std 1003.1-2001 defers to the ISO C standard.

> The time() function shall return the value of time [CX] in seconds since the Epoch.

> The tloc argument points to an area where the return value is also stored. If tloc is a null pointer, no value is stored.

#### RETURN VALUE

> Upon successful completion, time() shall return the value of time. Otherwise, (time_t)-1 shall be returned.

#### ERRORS

> No errors are defined.

The following sections are informative.

#### EXAMPLES

> ##### Getting the Current Time

> The following example uses the time() function to calculate the time elapsed, in seconds, since the Epoch, localtime() to convert that value to a broken-down time, and asctime() to convert the broken-down time values into a printable string.

>     #include <stdio.h>
>     #include <time.h>

>     int main(void)
>     {
>     time_t result;

>         result = time(NULL);
>         printf("%s%ju secs since the Epoch\n",
>             asctime(localtime(&result)),
>                 (uintmax_t)result);
>         return(0);
>     }

> This example writes the current time to stdout in a form like this:

>     Wed Jun 26 10:32:15 1996
>     835810335 secs since the Epoch

> ##### Timing an Event

> 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.

>     #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);
>     ...

#### APPLICATION USAGE

> None.

#### RATIONALE

> The time() function returns a value in seconds (type time_t) while times() returns a set of values in clock ticks (type clock_t). 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.

> Implementations in which time_t 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 time_t type is mandated in order to ease the eventual fix.

> The use of the <time.h> header instead of <sys/types.h> allows compatibility with the ISO C standard.

> Many historical implementations (including Version 7) and the 1984 /usr/group standard use long instead of time_t. This volume of IEEE Std 1003.1-2001 uses the latter type in order to agree with the ISO C standard.

> 4.3 BSD includes time() only as an alternate function to the more flexible gettimeofday() function.

#### FUTURE DIRECTIONS

> In a future version of this volume of IEEE Std 1003.1-2001, time_t 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.

#### SEE ALSO

> asctime(), clock(), ctime() , difftime(), gettimeofday(), gmtime(), localtime(), mktime(), strftime(), strptime(), utime(), the Base Definitions volume of IEEE Std 1003.1-2001, <time.h>

#### CHANGE HISTORY

> First released in Issue 1. Derived from Issue 1 of the SVID.

#### Issue 6

> Extensions beyond the ISO C standard are marked.

> The EXAMPLES, RATIONALE, and FUTURE DIRECTIONS sections are added.

End of informative text.

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]