NAME
asctime, asctime_r, ctime, ctime_r, difftime, gmtime,
gmtime_r, localtime, localtime_r, mktime, tzset - Converts
time units
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <time.h>
char *asctime(
const struct tm *timeptr) ;
int asctime_r(
const struct tm *timeptr,
char *buffer,
int len) ;
char *ctime(
const time_t *timer) ;
int ctime_r(
const time_t *timer,
char *buffer,
int len );
double difftime(
time_t time1,
time_t time2) ;
struct tm *gmtime(
const time_t *timer) ;
int gmtime_r(
const time_t *timer,
struct tm *result ) ;
struct tm *localtime(
const time_t *timer ) ;
int localtime_r(
const time_t timer,
struct tm *result ) ;
time_t mktime(
struct tm *timeptr) ;
void tzset(void) ;
extern char *tzname[] ;
extern long timezone ;
extern int daylight ;
PARAMETERS
timeptr Points to a type tm structure that defines space
for broken-down time.
time1 Specifies a time value expressed in seconds.
time2 Specifies a time value expressed in seconds.
timer Points to a variable that specifies a time value
in seconds.
buffer Points to a character array used to store the gen-
erated date and time string.
len Specifies an integer that defines the length of
the character array.
DESCRIPTION
The asctime(), asctime_r(), ctime(), difftime(), gmtime(),
gmtime_r(), localtime(), localtime_r(), mktime(), and
tzset() functions are used to convert time units to strings,
to store converted time units for subsequent processing, and
to convert stored time information to other time units. Time
information used in these functions is stored in a type tm
structure, which is defined in the time.h include file.
The asctime() function converts type tm structure broken-
down time information pointed to by the timeptr parameter to
a date and time string with the following 26-byte format:
Sun Sep 16 01:03:52 1973\n\0
This format contains 5 fields and is terminated by a newline
and 0 byte.
The asctime_r() function is the reentrant version of asc-
time() for use with multiple threads.
The ctime() function converts the time in seconds since the
Epoch, pointed to by the timer parameter, to a character
string. The Epoch is taken as 00:00:00 GMT 1 Jan 1970. The
character string specifies local time in the same format as
does the asctime() function. Local time-zone information is
set as though the tzset() function were called. This func-
tion is equivalent to asctime (localtime (timer)).
The reentrant version of this function is identical, except
that it stores the string in the buffer parameter up to len
characters.
The difftime() function returns a signed time value in
seconds that is the difference between the values of the
time1 and time2 parameters, also expressed in seconds.
The gmtime() function converts the time in seconds since the
Epoch, pointed to by the timer parameter, into broken-down
time, expressed as UTC (Coordinated Universal Time).
Broken-down time is stored in the type tm structure pointed
to by the return value of the gmtime() function.
The gmtime_r() function is the reentrant version of
gmtime(). This information is stored in the tm structure
passed in the result parameter.
The localtime() function converts the time in seconds since
the Epoch, pointed to by the timer parameter, into broken-
down time, expressed as local time. This function corrects
for the time-zone and any seasonal time adjustments.
Broken-down time is stored in the type tm structure pointed
to by the return value of this function. Local time-zone
information is set as though the tzset() function were
called.
The localtime_r() function is the reentrant version of
localtime() for use with multiple threads.
The mktime() function converts the broken-down time,
expressed as local time, in the type tm structure pointed to
by the timeptr parameter, into a time since the Epoch in the
same format as that of values returned by the time() func-
tion. The original values of parameters timeptr->tm_wday
and timeptr->tm_yday of the structure are ignored, and the
original values of other members of the structure are not
restricted to the ranges defined in the time.h header file.
The range [0, 61] for structure member tm_sec allows for an
occasional leap second or double leap second.
A positive or 0 (zero) value for member tm_isdst tells the
mktime() function whether daylight saving time is in effect.
A negative value for tm_isdst tells the mktime() function to
find out whether daylight saving time is in effect for the
specified time. Local time-zone information is set as
though the tzset() function were called.
On successful completion, values for the timeptr->tm_wday
and timeptr->tm_yday members of the structure are set, and
the other members are set to specified times since the
Epoch, but with their values forced to the ranges indicated
above; the final value of timeptr->tm_mday is not set until
the values of members timeptr->tm_mon and timeptr->tm_year
are determined.
The tzset() function uses the value of the environment
variable TZ to set time conversion information used by the
localtime(), localtime_r(), ctime(), ctime_r(), strftime(),
and mktime() functions. When environment variable TZ is
absent, implementation-defined default time-zone information
is used.
When the TZ environment variable is defined, the defined
value overrides the default time-zone value. The environment
facility contains formatted time zone information specified
by TZ. Environment variable TZ is usually set when a system
is started with the value that is defined in either the
/etc/environment or /etc/profile files. However, TZ may
also be set by a user as a regular environment variable for
converting to alternate time zones.
The tzset() function sets the external variable tzname as
follows:
tzname[0] = std ;
tzname[1] = dst ;
where std and dst are the strings designating standard and
daylight saving time zones, respectively, as described for
the TZ environment variable.
The tzset() function also sets the external variable day-
light to 0 (zero) when daylight saving time conversions
should never be applied for the time zone in use; otherwise
daylight is set to a nonzero value. The external variable
timezone is set to the difference, in seconds, between Coor-
dinated Universal Time (UTC) and local standard time. In the
following table, entries in the TZ column are time-zone
environmental variables, and entries in the Timezone column
are time units expressed as UTC time.
TZ Timezone
________________
EST 5*60*60
GMT 0*60*60
JST -9*60*60
MET -1*60*60
MST 7*60*60
PST 8*60*60
External variable tzname specifies the name of the standard
time zone (tzname[0]) and of the time zone when daylight
saving time is in effect (tzname[1]). For example:
extern char *tzname[2] = {"EST","EDT"};
External variable timezone specifies the difference, in
seconds, between GMT and local standard time. For example,
the value of timezone is 5 * 60 * 60 for U.S. Eastern Stan-
dard Time.
External variable daylight is set nonzero when a daylight
saving time conversion should be applied. By default, this
conversion follows standard U.S. time conventions; other
time conventions may be specified. The default conversion
algorithm adjusts for peculiarities of U.S. daylight saving
time in 1974 and 1975.
NOTES
The asctime(), ctime(), gmtime(), and localtime() functions
are not supported for multi-threaded applications. Instead,
their reentrant equivalents, asctime_r(), ctime_r(),
gmtime_r(), and localtime_r(), should be used with multiple
threads.
The difftime(), mktime(), and tzset() functions are sup-
ported for multi-threaded applications.
AES Support Level:
Full use (asctime(), ctime(), difftime(),
gmtime(), localtime(), mktime(), tzset())
RETURN VALUES
When any of the asctime(), ctime(), gmtime(), or localtime()
functions complete successfully, the return value may point
to static storage, which may be overwritten by subsequent
calls to these functions. On error, these functions return
a null pointer and errno is set to a value indicating the
error.
Upon successful completion, the asctime() and ctime() func-
tions return a pointer to a character string that expresses
the time in a fixed format.
Upon successful completion the difftime() function returns a
value, expressed in seconds, that is the difference between
the values of parameters time1 and time2.
Upon successful completion, the gmtime() and gmtime_r()
functions return a pointer to a type tm broken-down time
structure, which contains converted GMT time information.
When UTC is not available, this function returns a null
pointer.
Upon successful completion, the localtime() functions return
a pointer to a type tm broken-down time structure, which
contains converted local time.
Upon successful completion, the mktime() function returns
the specified time since the Epoch written as a value of
type time_t . On error, or whenever the time since the
Epoch cannot be represented, this function returns the value
(time_t)-1, and sets errno to indicate the error.
Upon successful completion, the asctime_r(), ctime_r(),
gmtime_r(), and localtime_r(), functions return a value of 0
(zero). Otherwise, -1 is returned and errno is set to indi-
cate the error.
ERRORS
If any of these functions fails, errno may be set to the
following value:
[EINVAL] The buffer or timer parameter is null, the len
parameter is 0 (zero), or the specified broken-
down time can not be represented as time since the
Epoch.
RELATED INFORMATION
Functions: getenv(3), strftime(3), time(3)
Acknowledgement and Disclaimer