4.3BSD-Reno/share/man/cat3/tzset.0
CTIME(3) 1990 CTIME(3)
NNAAMMEE
asctime, ctime, difftime, gmtime, localtime, mktime, tzset,
tzsetwall - convert date and time to ASCII
SSYYNNOOPPSSIISS
eexxtteerrnn cchhaarr **ttzznnaammee[[22]];;
vvooiidd ttzzsseett(())
vvooiidd ttzzsseettwwaallll(())
##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
cchhaarr **ccttiimmee((cclloocckk))
ttiimmee__tt **cclloocckk;;
ddoouubbllee ddiiffffttiimmee((ttiimmee11,, ttiimmee00))
ttiimmee__tt ttiimmee11;;
ttiimmee__tt ttiimmee00;;
##iinncclluuddee <<ttiimmee..hh>>
cchhaarr **aassccttiimmee((ttmm))
ssttrruucctt ttmm **ttmm;;
ssttrruucctt ttmm **llooccaallttiimmee((cclloocckk))
lloonngg **cclloocckk;;
ssttrruucctt ttmm **ggmmttiimmee((cclloocckk))
lloonngg **cclloocckk;;
ttiimmee__tt mmkkttiimmee((ttmm))
ssttrruucctt ttmm **ttmm;;
DDEESSCCRRIIPPTTIIOONN
_T_z_s_e_t uses the value of the environment variable TTZZ to set
time conversion information used by _l_o_c_a_l_t_i_m_e. If TTZZ does
not appear in the environment, the best available approxima-
tion to local wall clock time, as specified by the
_t_z_f_i_l_e(5)-format file llooccaallttiimmee in the system time conver-
sion information directory, is used by _l_o_c_a_l_t_i_m_e. If TTZZ
appears in the environment but its value is a null string,
Coordinated Universal Time (UTC) is used (without leap
second correction). If TTZZ appears in the environment and
its value is not a null string:
if the value begins with a colon, it is used as a path-
name of a file from which to read the time conversion
information;
if the value does not begin with a colon, it is first
used as the pathname of a file from which to read the
Printed 7/27/90 June 1
CTIME(3) 1990 CTIME(3)
time conversion information, and, if that file cannot
be read, is used directly as a specification of the
time conversion information.
When TTZZ is used as a pathname, if it begins with a slash, it
is used as an absolute pathname; otherwise, it is used as a
pathname relative to a system time conversion information
directory. The file must be in the format specified in
_t_z_f_i_l_e(5).
When TTZZ is used directly as a specification of the time
conversion information, it must have the following syntax
(spaces inserted for clarity):
_s_t_d_o_f_f_s_e_t[_d_s_t[_o_f_f_s_e_t][,,_r_u_l_e]]
Where:
_s_t_d and _d_s_t Three or more bytes that are the desig-
nation for the standard (_s_t_d) or summer
(_d_s_t) time zone. Only _s_t_d is required;
if _d_s_t is missing, then summer time does
not apply in this locale. Upper- and
lowercase letters are explicitly
allowed. Any characters except a lead-
ing colon (::), digits, comma (,,), minus
(--), plus (++), and ASCII NUL are
allowed.
_o_f_f_s_e_t Indicates the value one must add to the
local time to arrive at Coordinated
Universal Time. The _o_f_f_s_e_t has the
form:
_h_h[::_m_m[::_s_s]]
The minutes (_m_m) and seconds (_s_s) are
optional. The hour (_h_h) is required and
may be a single digit. The _o_f_f_s_e_t fol-
lowing _s_t_d is required. If no _o_f_f_s_e_t
follows _d_s_t, 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 pre-
ceded by a ``--'', the time zone shall be
east of the Prime Meridian; otherwise it
shall be west (which may be indicated by
an optional preceding ``++'').
Printed 7/27/90 June 2
CTIME(3) 1990 CTIME(3)
_r_u_l_e Indicates when to change to and back
from summer time. The _r_u_l_e has the
form:
_d_a_t_e//_t_i_m_e,,_d_a_t_e//_t_i_m_e
where the first _d_a_t_e describes when the
change from standard to summer time
occurs and the second _d_a_t_e describes
when the change back happens. Each _t_i_m_e
field describes when, in current local
time, the change to the other time is
made.
The format of _d_a_t_e is one of the follow-
ing:
JJ_n 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_m.._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 zero is Sun-
day.
The _t_i_m_e has the same format as _o_f_f_s_e_t
except that no leading sign (``--'' or
``++'') is allowed. The default, if _t_i_m_e
is not given, is 0022::0000::0000.
If no _r_u_l_e is present in TTZZ, the rules specified by the
_t_z_f_i_l_e(5)-format file ppoossiixxrruulleess in the system time conver-
sion information directory are used, with the standard and
summer time offsets from UTC replaced by those specified by
the _o_f_f_s_e_t values in TTZZ.
Printed 7/27/90 June 3
CTIME(3) 1990 CTIME(3)
For compatibility with System V Release 3.1, a semicolon (;;)
may be used to separate the _r_u_l_e from the rest of the
specification.
If the TTZZ environment variable does not specify a
_t_z_f_i_l_e(5)-format and cannot be interpreted as a direct
specification, UTC is used.
_T_z_s_e_t_w_a_l_l sets things up so that _l_o_c_a_l_t_i_m_e returns the best
available approximation of local wall clock time.
_C_t_i_m_e converts a long integer, pointed to by _c_l_o_c_k,
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\n\0
All the fields have constant width.
_L_o_c_a_l_t_i_m_e and _g_m_t_i_m_e return pointers to ``tm'' structures,
described below. _L_o_c_a_l_t_i_m_e corrects for the time zone and
any time zone adjustments (such as Daylight Saving Time in
the U.S.A.). Before doing so, _l_o_c_a_l_t_i_m_e calls _t_z_s_e_t (if
_t_z_s_e_t has not been called in the current process). After
filling in the ``tm'' structure, _l_o_c_a_l_t_i_m_e sets the
ttmm__iissddsstt'th element of ttzznnaammee to a pointer to an ASCII
string that's the time zone abbreviation to be used with
_l_o_c_a_l_t_i_m_e's return value.
_G_m_t_i_m_e converts to Coordinated Universal Time.
_A_s_c_t_i_m_e converts a time value contained in a ``tm'' struc-
ture to a 26-character string, as shown in the above exam-
ple, and returns a pointer to the string.
_M_k_t_i_m_e converts the broken-down time, expressed as local
time, in the structure pointed to by _t_m into a calendar time
value with the same encoding as that of the values returned
by the _t_i_m_e function. The original values of the ttmm__wwddaayy
and ttmm__yyddaayy 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
ttmm__iissddsstt causes _m_k_t_i_m_e to presume initially that summer time
(for example, Daylight Saving Time in the U.S.A.) respec-
tively, is or is not in effect for the specified time. A
negative value for ttmm__iissddsstt causes the _m_k_t_i_m_e function to
attempt to divine whether summer time is in effect for the
specified time.) On successful completion, the values of the
ttmm__wwddaayy and ttmm__yyddaayy 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 ttmm__mmddaayy is not set
until ttmm__mmoonn and ttmm__yyeeaarr are determined. _M_k_t_i_m_e returns the
Printed 7/27/90 June 4
CTIME(3) 1990 CTIME(3)
specified calendar time; If the calendar time cannot be
represented, it returns --11.
_D_i_f_f_t_i_m_e returns the difference between two calendar times,
_t_i_m_e_1 - _t_i_m_e_0, expressed in seconds.
Declarations of all the functions and externals, and the
``tm'' structure, are in the <<ttiimmee..hh>> header file. The
structure (of type) ssttrruucctt ttmm 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 summer time in effect? */
char *tm_zone; /* abbreviation of timezone name */
long tm_gmtoff; /* offset from UTC in seconds */
The _t_m__z_o_n_e and _t_m__g_m_t_o_f_f fields exist, and are filled in,
only if arrangements to do so were made when the library
containing these functions was created. There is no guaran-
tee that these fields will continue to exist in this form in
future releases of this code.
_T_m__i_s_d_s_t is non-zero if summer time is in effect.
_T_m__g_m_t_o_f_f is the offset (in seconds) of the time represented
from UTC, with positive values indicating east of the Prime
Meridian.
FFIILLEESS
/usr/share/zoneinfo time zone information direc-
tory
/usr/share/zoneinfo/localtime local time zone file
/usr/share/zoneinfo/posixrules used in converting POSIX-
style TZ's
/usr/share/zoneinfo/GMT for UTC leap seconds
If /_u_s_r/_s_h_a_r_e/_z_o_n_e_i_n_f_o/_G_M_T is absent, UTC leap seconds are
loaded from /_u_s_r/_s_h_a_r_e/_z_o_n_e_i_n_f_o/_p_o_s_i_x_r_u_l_e_s.
SSEEEE AALLSSOO
time(2), getenv(3), tzfile(5)
NNOOTTEESS
The return values point to static data whose content is
overwritten by each call. The ttmm__zzoonnee field of a returned
ssttrruucctt ttmm points to a static array of characters, which will
Printed 7/27/90 June 5
CTIME(3) 1990 CTIME(3)
also be overwritten at the next call (and by calls to _t_z_s_e_t
or _t_z_s_e_t_w_a_l_l).
Avoid using out-of-range values with _m_k_t_i_m_e when setting up
lunch with promptness sticklers in Riyadh.
Printed 7/27/90 June 6