NAME
asctime, ctime, difftime, gmtime, localtime, mktime, timezone,
tzset - convert date and time to ASCII

SYNOPSIS
void tzset()

char *ctime(clock)
const time_t *clock;

double difftime(time1, time0)
time_t time1, time2;

#include <time.h>

char *asctime(tm)
const struct tm *tm;

struct tm *localtime(clock)
const time_t *clock;

time_t mktime(tm)
struct tm *tm;

struct tm *gmtime(clock)
const time_t *clock;

char *timezone(zone, dst)
int zone, dst;

DESCRIPTION
Tzset uses the value of the environment variable TZ to set up the
time conversion information used by localtime.

If TZ does not appear in the environment, the TZDEFAULT file (as
defined in tzfile.h) is used by localtime. If this file fails for
any reason, the GMT offset as provided by the kernel is used. In
this case, DST is ignored, resulting in the time being incorrect by
some amount if DST is currently in effect. If this fails for any
reason, GMT is used.

If TZ appears in the environment but its value is a null string,
Greenwich Mean Time is used; if TZ appears and begins with a slash,
it is used as the absolute pathname of the tzfile(5)-format file
from which to read the time conversion information; if TZ appears
and begins with a character other than a slash, it’s used as a
pathname relative to the system time conversion information
directory, defined as TZDIR in the include file tzfile.h. If this
file fails for any reason, the GMT offset as provided by the kernel
is used, as described above. If this fails for any reason, GMT is
used.

Programs that always wish to use local wall clock time should
explicitly remove the environmental variable TZ with unsetenv(3).

Ctime converts a long integer, pointed to by clock, such as
returned by time(3), into ASCII and returns a pointer to a 26-
character string in the following form. All the fields have
constant width.

Sun Sep 16 01:03:52 197300

Localtime and gmtime return pointers to structures containing the
broken-down time. Localtime corrects for the time zone and
possible daylight savings time; gmtime converts directly to GMT,
which is the time UNIX uses. Asctime converts a broken-down time
to ASCII and returns a pointer to a 26-character string.

Mktime converts the broken-down time, expressed as local time, in
the structure pointed to by tm into a time value with the same
encoding as that of the values returned by the time(3) function,
that is, seconds from the Epoch, January 1, 1970 00:00:00 GMT.

The original values of the tm_wday and tm_yday components of the
structure are ignored, and the original values of the other
components are not restricted to their normal ranges. (A positive
or zero value for tm_isdst causes mktime to presume initially that
summer time (for example, Daylight Saving Time) is or is not in
effect for the specified time, respectively. A negative value for
tm_isdst causes the mktime function to attempt to divine whether
summer time is in effect for the specified time.)

On successful completion, the values of the tm_wday and tm_yday
components of the structure are set appropriately, and the other
components are set to represent the specified calendar time, but
with their values forced to their normal ranges; the final value of
tm_mday is not set until tm_mon and tm_year are determined. Mktime
returns the specified calendar time; if the calendar time cannot be
represented, it returns -1;

Difftime returns the difference between two calendar times (time1 -
time0), expressed in seconds.

The structure declaration from the include file is:

struct tm {
int tm_sec; /* 0-60 seconds */
int tm_min; /* 0-59 minutes */
int tm_hour; /* 0-23 hour */
int tm_mday; /* 1-31 day of month */
int tm_mon; /* 0-11 month */
int tm_year; /* 0- year - 1900 */
int tm_wday; /* 0-6 day of week (Sunday = 0) */
int tm_yday; /* 0-365 day of year */
int tm_isdst; /* flag: daylight savings time in effect */
char **tm_zone; /* abbreviation of timezone name */
long tm_gmtoff; /* offset from GMT in seconds */
};

Tm_isdst is positive if Daylight Savings time is in effect, zero if
not, and negative if the information is not available.

Tm_gmtoff is the offset (in seconds) of the time represented from
GMT, with positive values indicating East of Greenwich.

Timezone remains for compatibility reasons only; it’s impossible to
reliably map timezone’s arguments (zone, a "minutes west of GMT"
value and dst, a "daylight saving time in effect" flag) to a time
zone abbreviation.

If the environmental string TZNAME exists, timezone returns its
value, unless it consists of two comma separated strings, in which
case the second string is returned if dst is non-zero, else the
first string. If TZNAME doesn’t exist, zone is checked for
equality with a built-in table of values, in which case timezone
returns the time zone or daylight time zone abbreviation associated
with that value. If the requested zone does not appear in the
table, the difference from GMT is returned; e.g. in Afghanistan,
timezone(-(60*4+30), 0) is appropriate because it is 4:30 ahead of
GMT, and the string GMT+4:30 is returned. Programs that in the
past used the timezone function should return the zone name as set
by localtime to assure correctness.

FILES
/usr/etc/zoneinfo time zone information directory
/usr/etc/zoneinfo/localtime local time zone file

SEE ALSO
gettimeofday(2), getenv(3), time(3), tzfile(5), environ(7)

NOTE
Except for difftime, the return values point to static data whose
content is overwritten by each call. The tm_zone field of a
returned struct tm points to a static array of characters, which
will also be overwritten at the next call (and by calls to tzset).