ctime(3) ctime(3)
NAME
asctime, ctime, difftime, gmtime, localtime, mktime, tzset,
tzsetwall - convert date and time to ASCII
SYNOPSIS
extern char *tzname[2];
void tzset()
void tzsetwall()
#include <sys/types.h>
char *ctime(clock)
time_t *clock;
double difftime(time1,time0)
time_t time1;
time_t time0;
#include <time.h>
char *asctime(tm)
struct tm *tm;
struct tm *localtime(clock)
long *clock;
struct tm *gmtime(clock)
long *clock;
time_t mktime(tm)
struct tm *tm;
extern long timezone;
extern int daylight;
DESCRIPTION
tzset uses the value of the environment variable TZ to set
time conversion information used by localtime. If TZ does
not appear in the environment, the best available approxima-
tion to local wall-clock time, as specified by the file lo-
caltime in the system time-conversion information directory,
is used by the localtime function. If TZ appears in the en-
vironment but its value is a null string, Coordinated
Universal Time (UTC) is used (without leap-second correc-
tion). If TZ appears in the environment and its value is
not a null string, TZ is used in one of the following ways:
If the value begins with a colon (:), it is used as a
pathname of a file from which to read the time-
conversion information.
April, 1990 1
ctime(3) ctime(3)
If the value does not begin with a colon, it is first
used as the pathname of a file from which to read the
time conversion information, and if that file cannot be
read, it is used directly as a specification of the
time-conversion information.
If it begins with a slash (/), it is used as an absolute
pathname when TZ is used as a pathname; otherwise, it is
used as a pathname relative to a system time-conversion in-
formation directory. The file must be in the format speci-
fied in tzfile(5).
When TZ is used directly as a specification of the time-
conversion information, it must have the following syntax
(spaces are inserted for clarity):
stdoffset[dst[offset][,rule]]
The placeholders mean the following:
std and dst Specify three or more bytes that are the
designation for the standard (std) or
summer (dst) time zone. Only std is re-
quired. If dst is missing, then summer
time does not apply in this locale. Up-
percase and lowercase letters are expli-
citly allowed. Any characters except a
leading colon (:), digits, a comma (,),
a minus sign (-), a plus sign (+), and
ASCII NUL are allowed.
offset Add the value one of offset to the local
time to arrive at UTC. The format of
offset is:
hh[:mm[:ss]]
The minutes (mm) and seconds (ss) are
optional. The hour (hh) is required and
may be a single digit. The value of
offset following std is required. If no
offset follows dst, summer time is as-
sumed to be one hour ahead of standard
time. One or more digits may be used;
the value is always interpreted as a de-
cimal number. The hour must be between
0 and 24, and the minutes and seconds,
if present, between 0 and 59. If pre-
ceded by a - (minus sign), the time zone
is east of the prime meridian; other-
wise, it is west, which may be indicated
by an optional preceding + (plus sign).
2 April, 1990
ctime(3) ctime(3)
rule Specify when to change to and back from
summer time. The format of rule is:
date/time,date/time
where the first date describes when the
change from standard to summer time oc-
curs and the second date describes when
the change back happens. Each time
field describes when, in current local
time, the change to the other time is
made.
The format of date is one of the follow-
ing:
Jn The Julian day n
(1 < n < 365). Leap days are
not counted so that in all
years, including leap years,
February 28 is day 59, and
March 1 is day 60. It is im-
possible 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 d'th day (0 < d < 6) of
week n of month m of the year
(1 < n < 5, 1 < m < 12, where
week 5 means ``the last d day
in month m'' which may occur
in either the fourth or the
fifth week). Week 1 is the
first week in which the d'th
day occurs. Day 0 is Sunday.
The time has the same format as offset
except that no leading - or + (minus or
plus sign) is allowed. The default, if
time is not given, is 02:00:00.
If no rule is present in TZ, the rules specified by the
tzfile(5)-format file posixrules in the system time-
conversion information directory are used, with the standard
and summer time offsets from UTC replaced by those specified
by the values of offset in TZ.
April, 1990 3
ctime(3) ctime(3)
For compatibility with System V Release 3.1, a semicolon (;)
may be used to separate rule from the rest of the specifica-
tion. For compatibility with applications that expect the
environment variable TZ to be in the format of System V
Release 2, the value of TZ should not include rule.
If the TZ environment variable does not specify a
tzfile(5)-format and cannot be interpreted as a direct
specification, UTC is used with the standard time abbrevia-
tion set to the value of the TZ environment variable (or to
the leading characters of its value if it is lengthy).
In most installations TZ is set by default, when the user
logs on, to the value in the file /etc/TIMEZONE.
Tzsetwall arranges for the system's best approximation to
local wall-clock time to be delivered by subsequent calls to
localtime.
Ctime converts a long integer, pointed to by clock,
representing the time in seconds since 00:00:00 UTC, January
1, 1970, and returns a pointer to a 26-character string of
the form
Thu Nov 24 18:22:48 1986
All the fields have a constant width.
localtime and gmtime return pointers to tm structures,
described below. localtime corrects for the time zone and
any time-zone adjustments, such as daylight-saving time
(DST) in the United States. Before doing so, localtime
calls tzset, if tzset has not been called in the current
process. After filling in the tm structure, localtime sets
the tm_isdst'th element of tzname to a pointer to an ASCII
string that's the time-zone abbreviation to be used with the
return value of localtime.
Gmtime converts to UTC.
Asctime converts the time value tm to a 26-character string,
as shown in the above example, and returns a pointer to the
string.
mktime converts the broken-down time, expressed as local
time, in the structure pointed to by tm into a calendar time
value with the same encoding as that of the values returned
by the time function. 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
4 April, 1990
ctime(3) ctime(3)
(for example, daylight-saving time in the United States)
respectively, is or is not in effect for the specified time.
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.
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 - 60) */
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; /* is DST ("summer" time) in effect? */
Tm_isdst is nonzero if a timezone adjustment such as
daylight-savings time or summer time is in effect.
The external variable timezone contains the difference, in
seconds, between UTC and local standard time (in Pacific
Standard Time, timezone is 5*60*60). The external variable
daylight is nonzero if a timezone adjustment such as DST or
summer time is in effect.
FILES
/etc/zoneinfo Time-zone information directory
/etc/zoneinfo/localtime Local time zone file
/etc/zoneinfo/posixrules Used with POSIX-style TZ's
/etc/zoneinfo/GMT For UTC leap seconds
If /etc/zoneinfo/GMT is absent, UTC leap seconds are loaded
from /etc/zoneinfo/posixrules.
SEE ALSO
tzfile(4), getenv(3), time(2), environ(5)
April, 1990 5
NOTES
The return values point to static data whose content is
overwritten by each call.
6 April, 1990