NAME

ctime, localtime, gmtime, asctime, tzset − convert date and time to string

SYNOPSIS

#include <time.h>

char ∗ctime (const time_t ∗clock);

struct tm ∗localtime (const time_t ∗clock);

struct tm ∗gmtime (const time_t ∗clock);

char ∗asctime (const struct tm ∗tm);

extern time_t timezone, altzone;

extern int daylight;

extern char ∗tzname[2];

void tzset (void);

DESCRIPTION

ctime, localtime, and gmtime accept arguments of type time_t, pointed to by clock, representing the time in seconds since 00:00:00 UTC, January 1, 1970.  ctime returns a pointer to a 26-character string as shown below.  Time zone and daylight savings corrections are made before the string is generated.  The fields are constant in width:

Fri Sep 13 00:00:00 1986\n\0

localtime and gmtime return pointers to tm structures, described below.  localtime corrects for the main time zone and possible alternate (“daylight savings”) time zone; gmtime converts directly to Coordinated Universal Time (UTC), which is the time the UNIX system uses internally. 

asctime converts a tm structure to a 26-character string, as shown in the above example, and returns a pointer to the string. 

Declarations of all the functions and externals, and the tm structure, are in the time.h header file.  The structure declaration is:

structtm {
inttm_sec;/∗ seconds after the minute — [0, 61] ∗/
/∗ for leap seconds ∗/
inttm_min;/∗ minutes after the hour — [0, 59] ∗/
inttm_hour;/∗ hour since midnight — [0, 23] ∗/
inttm_mday;/∗ day of the month — [1, 31] ∗/
inttm_mon;/∗ months since January — [0, 11] ∗/
inttm_year;/∗ years since 1900 ∗/
inttm_wday;/∗ days since Sunday — [0, 6] ∗/
inttm_yday;/∗ days since January 1 — [0, 365] ∗/
inttm_isdst;/∗ flag for alternate daylight ∗/
/∗ savings time ∗/
};

The value of tm_isdst is positive if daylight savings time is in effect, zero if daylight savings time is not in effect, and negative if the information is not available. (Previously, the value of tm_isdst was defined as non-zero if daylight savings time was in effect.) 

The external time_t variable altzone contains the difference, in seconds, between Coordinated Universal Time and the alternate time zone.  The external variable timezone contains the difference, in seconds, between UTC and local standard time. The external variable daylight indicates whether time should reflect daylight savings time.  Both timezone and altzone default to 0 (UTC).  The external variable daylight is non-zero if an alternate time zone exists.  The time zone names are contained in the external variable tzname, which by default is set to:

char ∗tzname[2] = { "GMT", "   " };

These functions know about the peculiarities of this conversion for various time periods for the U.S.A.  (specifically, the years 1974, 1975, and 1987).  They will handle the new daylight savings time starting with the first Sunday in April, 1987. 

tzset uses the contents of the environment variable TZ to override the value of the different external variables.  The function tzset is called by asctime and may also be called by the user.  See environ(5) for a description of the TZ environment variable. 

tzset scans the contents of the environment variable and assigns the different fields to the respective variable.  For example, the most complete setting for New Jersey in 1986 could be

EST5EDT4,116/2:00:00,298/2:00:00

or simply

EST5EDT

An example of a southern hemisphere setting such as the Cook Islands could be

KDT9:30KST10:00,63/5:00,302/20:00

In the longer version of the New Jersey example of TZ, tzname[0] is EST, timezone will be set to 5∗60∗60, tzname[1] is EDT, altzone will be set to 4∗60∗60, the starting date of the alternate time zone is the 117th day at 2 AM, the ending date of the alternate time zone is the 299th day at 2 AM (using zero-based Julian days), and daylight will be set positive.  Starting and ending times are relative to the alternate time zone.  If the alternate time zone start and end dates and the time are not provided, the days for the United States that year will be used and the time will be 2 AM.  If the start and end dates are provided but the time is not provided, the time will be 2 AM.  The effects of tzset are thus to change the values of the external variables timezone, altzone, daylight, and tzname.  ctime, localtime, mktime, and strftime will also update these external variables as if they had called tzset at the time specified by the time_t or struct tm value that they are converting.  Note that in most installations, TZ is set to the correct value by default when the user logs on, via the local /etc/profile file [see profile(4) and timezone(4)]. 

FILES

/usr/lib/locale/language/LC_TIME − file containing locale specific date and time information

SEE ALSO

time(2), getenv(3C), mktime(3C), putenv(3C), printf(3S), setlocale(3C), strftime(3C), cftime(4), profile(4), timezone(4), environ(5)

NOTES

The return values for ctime, localtime, and gmtime point to static data whose content may be overwritten as a side effect of any subsequent library call.  The caller should make a private copy of any returned values that are to be retained or passed to other interfaces. 

Setting the time during the interval of change from timezone to altzone or vice versa can produce unpredictable results.  The system administrator must change the Julian start and end days annually. 

  —  C Programming Language Utilities