ctime(3) Library Functions Manual ctime(3)
Name
ctime, localtime, gmtime, asctime, difftime, mktime, timezone, tzset - date and time functions
Syntax
As shown, the and calls are common to both the non-System V environment and the System V environment.
Common to Both Environments
#include <time.h>
void tzset()
char *ctime(clock)
time_t *clock;
char *asctime(tm)
struct tm *tm;
struct tm *localtime(clock)
time_t *clock;
struct tm *gmtime(clock)
time_t *clock;
double difftime(time1, time0)
time_t time1, time0;
time_t mktime(timeptr)
struct tm *timeptr;
extern char *tzname[2];
BSD Environment Only
char *timezone(zone, dst)
System V and POSIX Environments Only
extern long timezone;
extern int daylight;
Description
The call uses the value of the environment variable TZ to set up the time conversion information used by
If TZ does not appear in the environment, the file is used by If this file fails for any reason, the Greenwich Mean Time (GMT) offset as
provided by the kernel is used. In this case, Daylight Savings Time (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, GMT is used; if TZ appears and its value is not a null string, its value
is interpreted using rules specific to the System V and non-System V environments.
Programs that always wish to use local wall clock time should explicitly remove the environmental variable TZ with
The call converts a long integer, pointed to by clock, representing the time in seconds since 00:00:00 GMT, January 1, 1970, 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 1985
The and calls return pointers to tm structures, described below. The call corrects for the time zone and possible DST; converts directly
to GMT, which is the time the ULTRIX system uses.
The call converts a tm structure to a 26-character string, as shown in the previous 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:
struct tm {
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; /* flag: daylight savings time in
effect */
long tm_gmtoff; /* offset from GMT in seconds */
char *tm_zone; /* abbreviation of timezone name */
};
tm_isdst is nonzero if DST is in effect.
tm_gmtoff is the offset (in seconds) of the time represented from GMT, with positive values indicating East of Greenwich.
The call computes the difference between two calendar times: time1 - time0 and returns the difference expressed in seconds.
The call converts the broken-down local time in the tm structure pointed to by timeptr into a calendar time value with the same encoding as
that of the values returned by The values of tm_wday and tm_yday in the structure are ignored, and the other values are not restricted to
the ranges indicated above for the tm structure. A positive or zero value for tm_isdst causes to presume that DST, respectively, is or is
not in effect for the specified time. A negative value causes to attempt to determine whether DST is in effect for the specified time. On
successful completion, the values of tm_wday and tm_yday are set appropriately, and the other components are set to represent the specified
calendar time, but with their values forced to the ranges indicated above. If the calendar time cannot be represented, the function returns
the value (time_t)-1.
The external variable tzname, contains the current time zone names. The function sets this variable.
BSD and POSIX Environment Only
If TZ appears in the environment and its value is not a null string, its value has one of three formats:
:
or
:pathname
or
stdoffset[dst[offset][,start[/time],end[/time]]]
If TZ is the single colon format (first format), GMT is used.
If TZ is the colon followed by a pathname format (second), the characters following the colon specify a pathname of a format file from
which to read the time conversion information. If the pathname begins with a slash, it represents an absolute pathname; otherwise the path-
name is relative to the system time conversion information directory If this file fails for any reason, the GMT offset as provided by the
kernel is used.
If the first character in TZ is not a colon (third format), the components of the string have the following meaning:
std and dst Three or more characters that are the designation for the standard (std) or summer (dst) time zone. Only std is required; if
dst is missing, then summer time does not apply in this locale. Upper- and lowercase letters are explicitly allowed. Any
characters except a leading colon (:), digits, comma (,), minus (-), plus (+), and ASCII NUL are allowed.
offset Indicates the value to be added to the local time to arrive at Coordinated Universal Time. The offset has the form:
hh[:mm[:ss]]
The minutes (mm) and seconds (ss) are optional. The hour (hh) is required and may be a single digit. The offset following
std is required. If no offset follows dst, summer time is assumed to be one hour ahead of standard time. One or more digits
may be used; the value is always interpreted as a decimal number. The hour must be between zero and 24, and the minutes
(and seconds) - if present - between zero and 59. If preceded by a "-", the time zone is east of the Prime Meridian; other-
wise it is west (which may be indicated by an optional preceding "+").
start and end Indicates when to change to and back from summer time. Start describes the date when the change from standard to summer time
occurs and end describes the date when the change back happens. The format of start and end must be one of the following:
Jn The Julian day n (1 <= n <= 365). Leap days are not counted. That is, in all years, including leap years, February
28 is day 59 and March 1 is day 60. It is impossible to explicitly refer to the occasional February 29.
n The zero-based Julian day (0 <= n <= 365). Leap days are counted, and it is possible to refer to February 29.
Mm.n.d The nth d day of month m (1 <= n <= 5, 0 <= d <= 6, 1 <= m <= 12). When n is 5 it refers to the last d day of month
m. Day 0 is Sunday.
time The time field describes the time when, in current time, the change to or from summer time occurs. Time has the same format
as offset except that no leading sign (a minus sign (-) or a plus sign (+)) is allowed. The default, if time is not given,
is 02:00:00.
As an example of the previous format, if the TZ environment variable had the value EST5EDT4,M4.1.0,M10.5.0 it would describe the rule,
which went into effect in 1987, for the Eastern time zone in the USA. Specifically, EST would be the designation for standard time, which
is 5 hours behind GMT. EDT would be the designation for DST, which is 4 hours behind GMT. DST starts on the first Sunday in April and ends
on the last Sunday in October. In both cases, since the time was not specified, the change to and from DST would occur at the default time
of 2:00 AM.
The call remains for compatibility reasons only; it is 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, 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 does not exist, zone is checked for equality with a built-in table
of values, in which case 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; that is, in Afghanistan, 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 function should return the zone name as set by to assure correct-
ness.
System V Environment Only
If TZ appears in the environment its value specifies a pathname of a format file from which to read the time conversion information. If the
pathname begins with a slash, it represents an absolute pathname; otherwise the pathname is relative to the system time conversion informa-
tion directory
If TZ appears in the environment and using the value as a pathname of a format file fails for any reason, the value is assumed to be a
three-letter time zone name followed by a number representing the difference between local time and GMT in hours, followed by an optional
three-letter name for a time zone on DST. For example, the setting for New Jersey would be EST5EDT.
System V and POSIX Environment Only
The external long variable contains the difference, in seconds, between GMT and local standard time (in EST, is 5*60*60). The external
variable daylight is nonzero if any daylight time rules are to be applied (that is, if the specified timezone includes rules for daylight
time). These variables are set whenever or are called.
Restrictions
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
Files
/etc/zoneinfo time zone information directory
/etc/zoneinfo/localtime local time zone file
See Also
gettimeofday(2), getenv(3), strftime(3), time(3), tzfile(5), environ(7)
ctime(3)