CTIME(3) — C LIBRARY FUNCTIONS

NAME

ctime, localtime, gmtime, asctime, dysize, 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;

int dysize(y)
int y;

time_t timelocal(tm)
struct tm ∗tm;

time_t timegm(tm)
struct tm ∗tm;

void tzset()

void tzsetwall()

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.

dysize returns the number of days in the argument year, either 365 or 366.

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.

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: 6 October 1987

Museum