CTIME(3V) — SYSTEM V LIBRARY

NAME

ctime, localtime, gmtime, asctime, timelocal, timegm, tzset, tzsetwall − convert date and time

SYNOPSIS

#include <time.h>

struct tm ∗localtime(clock)
long ∗clock;

struct tm ∗gmtime(clock)
long ∗clock;

char ∗asctime(tm)
struct tm ∗tm;

char ∗ctime(clock)
long ∗clock;

time_t timelocal(tm)
struct tm ∗tm;

time_t timegm(tm)
struct tm ∗tm;

void tzset()

void tzsetwall()

extern long timezone;

extern int daylight;

extern char ∗tzname[2];

DESCRIPTION

localtime() and gmtime() return pointers to structures containing the time, broken down into various components of that time represented in a particular time zone. localtime() breaks down a time specified by the clock argument, correcting for the time zone and any time zone adjustments (such as Daylight Savings Time). Before doing so, localtime() calls tzset() (if tzset() has not been called in the current process). gmtime() breaks down a time specified by the clock argument into GMT, which is the time the system uses.

asctime() converts a time value contained in a “tm” structure to a 26-character string of the form:

Sun Sep 16 01:03:52 1973\n\0

Each field has a constant width. asctime() returns a pointer to the string.

ctime() converts a long integer, pointed to by clock, to a 26-character string of the form produced by asctime(). It first breaks down clock to a struct tm by calling localtime(), and then calls asctime() to convert that struct tm to a string.

timelocal() and timegm() convert the time specified by the tm argument to a time value that represents that time expressed as the number of seconds since Jan. 1, 1970, 00:00, Greenwich Mean Time. timelocal() converts a struct tm that represents local time, correcting for the time zone and any time zone adjustments (such as Daylight Savings Time). Before doing so, timelocal() calls tzset() (if tzset() has not been called in the current process). timegm() converts a struct tm that represents GMT.

tzset() uses the value of the environment variable TZ to set time conversion information used by localtime(). If TZ is absent from the environment, the best available approximation to local wall clock time is used by localtime(). 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-format (see tzfile(5)) file from which to read the time conversion information; if TZ appears and begins with a character other than a slash, it is used as a pathname relative to a system time conversion information directory.

tzsetwall() sets things up so that localtime() returns the best available approximation of local wall clock time.

Declarations of all the functions and externals, and the “tm” structure, are in the <time.h> header file. The structure (of type) struct tm includes the following fields:

int tm_sec;/∗ seconds (0 - 59) ∗/
int tm_min;/∗ minutes (0 - 59) ∗/
int tm_hour;/∗ hours (0 - 23) ∗/
int tm_mday;/∗ day of month (1 - 31) ∗/
int tm_mon;/∗ month of year (0 - 11) ∗/
int tm_year;/∗ year − 1900 ∗/
int tm_wday;/∗ day of week (Sunday = 0) ∗/
int tm_yday;/∗ day of year (0 - 365) ∗/
int tm_isdst;/∗ 1 if DST in effect ∗/
char ∗tm_zone;/∗ abbreviation of timezone name ∗/
long tm_gmtoff; /∗ offset from GMT in seconds ∗/

tm_isdst is non-zero if Daylight Savings Time is in effect. tm_zone points to a string that is the name used for the local time zone at the time being converted. tm_gmtoff is the offset (in seconds) of the time represented from GMT, with positive values indicating East of Greenwich.

The external long variable timezone contains the difference, in seconds, between GMT and local standard time (in PST, timezone is 8∗60∗60). If this difference is not a constant, timezone will contain the value of the offset on January 1, 1970 at 00:00 GMT. Since this is not necessarily the same as the value at some particular time, the time in question should be converted to a “struct tm” using localtime() (see ctime(3)) and the tm_gmtoff field of that structure should be used. The external variable daylight is non-zero if and only if Daylight Savings Time would be in effect within the current time zone at some time; it does not indicate whether Daylight Savings Time is currently in effect.

The external variable tzname is an array of two char ∗ pointers. The first pointer points to a character string that is the name of the current time zone when Daylight Savings Time is not in effect; the second one, if Daylight Savings Time conversion should be applied, points to a character string that is the name of the current time zone when Daylight Savings Time is in effect. These strings are updated by localtime() whenever a time is converted. If Daylight Savings Time is in effect at the time being converted, the second pointer is set to point to the name of the current time zone at that time, otherwise the first pointer is so set.

timezone, daylight, and tzname are retained for compatibility with existing programs.

FILES

/usr/share/lib/zoneinfo
standard time conversion information directory

/usr/share/lib/zoneinfo/localtime
local time zone file

BUGS

The return values point to static data, whose contents are 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() or tzsetwall()).

Sun Release 4.0 — Last change: 22 March 1989

Museum