BSD 4_3_Net_2 release

[unix-history] / usr / src / lib / libc / gen / tzset.3

diff --git a/usr/src/lib/libc/gen/tzset.3 b/usr/src/lib/libc/gen/tzset.3
index 3a575d2..436a0e4 100644 (file)
--- a/usr/src/lib/libc/gen/tzset.3
+++ b/usr/src/lib/libc/gen/tzset.3
@@ -1,244 +1,325 @@
-.\" Copyright (c) 1989 The Regents of the University of California.
+.\" Copyright (c) 1989, 1991 The Regents of the University of California.

 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to Berkeley by
 .\" Arthur Olson.
 .\"
 .\" All rights reserved.
 .\"
 .\" This code is derived from software contributed to Berkeley by
 .\" Arthur Olson.
 .\"

-.\" %sccs.include.redist.man%
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"    This product includes software developed by the University of
+.\"    California, Berkeley and its contributors.
+.\" 4. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.

 .\"
 .\"

-.\"    @(#)tzset.3     5.1 (Berkeley) %G%
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.

 .\"
 .\"

-.TH TZSET 3 ""
-.SH NAME
-tzset, tzsetwall \- initialize time conversion information
-.SH SYNOPSIS
-.nf
-.ft B
-void tzset()
-
-void tzsetwall()
-.ft R
-.fi
-.SH DESCRIPTION
-.I Tzset
+.\"    @(#)tzset.3     5.3 (Berkeley) 7/23/91
+.\"
+.Dd July 23, 1991
+.Dt TZSET 3
+.Os
+.Sh NAME
+.Nm tzset ,
+.Nm tzsetwall
+.Nd initialize time conversion information
+.Sh SYNOPSIS
+.Fd #include <time.h>
+.Ft void
+.Fn tzset void
+.Ft void
+.Fn tzsetwall void
+.Sh DESCRIPTION
+The
+.Fn tzset
+function

 initializes time conversion information used by the library routine
 initializes time conversion information used by the library routine

-.IR localtime .
+.Xr localtime 3 .

 The environment variable
 The environment variable

-.B TZ
+.Ev TZ

 specifies how this is done.
 specifies how this is done.

-.PP
+.Pp

 If
 If

-.B TZ
+.Ev TZ

 does not appear in the environment, the best available approximation to
 local wall clock time, as specified by the
 does not appear in the environment, the best available approximation to
 local wall clock time, as specified by the

-.IR tzfile (5)-format
-file ``/etc/localtime'' is used.
-.PP
+.Xr tzfile 5 Ns -format
+file
+.Pa /etc/localtime
+is used.
+.Pp

 If
 If

-.B TZ
+.Ev TZ

 appears in the environment but its value is a null string, Coordinated
 appears in the environment but its value is a null string, Coordinated

-Universal Time (UTC) is used (without leap second correction).
-.PP
+Universal Time
+.Pq Tn UTC
+is used (without leap second correction).
+.Pp

 If
 If

-.B TZ
-appears in the environment and its value begins with a colon (``:''),
-the rest of its value is used as a pathname of a 
-.IR tzfile (5)-format
+.Ev TZ
+appears in the environment and its value begins with a colon
+.Pq Ql : ,
+the rest of its value is used as a pathname of a
+.Xr tzfile 5 Ns -format

 file from which to read the time conversion information.
 file from which to read the time conversion information.

-If the first character of the pathname is a slash (``/'') it is used as
+If the first character of the pathname is a slash
+.Pq Ql /
+it is used as

 an absolute pathname; otherwise, it is used as a pathname relative to
 the system time conversion information directory.
 an absolute pathname; otherwise, it is used as a pathname relative to
 the system time conversion information directory.

-.PP
+.Pp

 If its value does not begin with a colon, it is first used as the pathname
 of a file (as described above) from which to read the time conversion
 information.
 If that file cannot be read, the value is then interpreted as a direct
 specification (the format is described below) of the time conversion
 information.
 If its value does not begin with a colon, it is first used as the pathname
 of a file (as described above) from which to read the time conversion
 information.
 If that file cannot be read, the value is then interpreted as a direct
 specification (the format is described below) of the time conversion
 information.

-.PP
+.Pp

 If the
 If the

-.B TZ
+.Ev TZ

 environment variable does not specify a
 environment variable does not specify a

-.IR tzfile (5)-format
+.Xr tzfile 5 Ns -format

 file and cannot be interpreted as a direct specification,
 file and cannot be interpreted as a direct specification,

-UTC is used.
-.PP
-.I Tzsetwall
+.Tn UTC
+is used.
+.Pp
+The
+.Fn tzsetwall
+function

 sets things up so that
 sets things up so that

-.I localtime
+.Xr localtime

 returns the best available approximation of local wall clock time.
 returns the best available approximation of local wall clock time.

-.SH "SPECIFICATION FORMAT"
+.Sh SPECIFICATION FORMAT

 When
 When

-.B TZ
+.Ev TZ

 is used directly as a specification of the time conversion information,
 it must have the following syntax (spaces inserted for clarity):
 is used directly as a specification of the time conversion information,
 it must have the following syntax (spaces inserted for clarity):

-.IP
-\fIstd\|offset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIrule\fR]]
-.PP
+.Bd -filled -offset indent
+.Em std offset Bo
+.Em dst Bo
+.Em offset
+.Bc
+.Bo
+.No , Em rule
+.Bc
+.Bc
+.Ed
+.Pp

 Where:
 Where:

-.RS
-.TP 15
-.IR std " and " dst
+.Bl -tag -width std_and_dst -offset indent
+.It Em std No and Em dst

 Three or more bytes that are the designation for the standard
 Three or more bytes that are the designation for the standard

-.RI ( std )
+.Pq Em std

 or summer
 or summer

-.RI ( dst )
+.Pq Em dst

 time zone.  Only
 time zone.  Only

-.I std
+.Em std

 is required; if
 is required; if

-.I dst
+.Em dst

 is missing, then summer time does not apply in this locale.
 is missing, then summer time does not apply in this locale.

-Upper- and lowercase letters are explicitly allowed.  Any characters
+Upper and lowercase letters are explicitly allowed.  Any characters

 except a leading colon
 except a leading colon

-.RB ( : ),
+.Pq Ql : ,

 digits, comma
 digits, comma

-.RB ( , ),
+.Pq Ql \&, ,

 minus
 minus

-.RB ( \(mi ),
+.Pq Ql \- ,

 plus
 plus

-.RB ( \(pl ),
-and ASCII NUL are allowed.
-.TP
-.I offset
+.Pq Ql + ,
+and
+.Tn ASCII
+.Dv NUL
+are allowed.
+.It Em offset

 Indicates the value one must add to the local time to arrive at
 Coordinated Universal Time.  The
 Indicates the value one must add to the local time to arrive at
 Coordinated Universal Time.  The

-.I offset
+.Em offset

 has the form:
 has the form:

-.RS
-.IP
-\fIhh\fR[\fB:\fImm\fR[\fB:\fIss\fR]]
-.RE
-.IP
+.Bd -unfilled -offset indent
+.Em hh Bo
+.Pf \&: Em mm
+.Bo
+.Pf \&: Em ss
+.Bc
+.Bc
+.Ed
+.Pp

 The minutes
 The minutes

-.RI ( mm )
+.Pq Em mm

 and seconds
 and seconds

-.RI ( ss )
+.Pq Em ss

 are optional.  The hour
 are optional.  The hour

-.RI ( hh )
+.Pq Em hh

 is required and may be a single digit.  The
 is required and may be a single digit.  The

-.I offset
+.Em offset

 following
 following

-.I std
+.Em std

 is required.  If no
 is required.  If no

-.I offset
+.Em offset

 follows
 follows

-.IR dst ,
+.Em 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) \(em if present \(em between zero and 59.  If preceded by a
 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) \(em if present \(em between zero and 59.  If preceded by a

-.RB `` \(mi '',
+.Pq Ql \-

 the time zone shall be east of the Prime Meridian; otherwise it shall be
 west (which may be indicated by an optional preceding
 the time zone shall be east of the Prime Meridian; otherwise it shall be
 west (which may be indicated by an optional preceding

-.RB `` \(pl '').
-.TP
-.I rule
+.Pq Ql + ) .
+.It Em rule

 Indicates when to change to and back from summer time.  The
 Indicates when to change to and back from summer time.  The

-.I rule
+.Em rule

 has the form:
 has the form:

-.RS
-.IP
-\fIdate\fB/\fItime\fB,\fIdate\fB/\fItime\fR
-.RE
-.IP
+.Bd -filled -offset indent
+.Em date/time,date/time
+.Ed
+.Pp

 where the first
 where the first

-.I date
+.Em date

 describes when the change from standard to summer time occurs and the
 second
 describes when the change from standard to summer time occurs and the
 second

-.I date
+.Em date

 describes when the change back happens.  Each
 describes when the change back happens.  Each

-.I time
+.Em time

 field describes when, in current local time, the change to the other
 time is made.
 field describes when, in current local time, the change to the other
 time is made.

-.IP
+.Pp

 The format of
 The format of

-.I date
+.Em date

 is one of the following:
 is one of the following:

-.RS
-.TP 10
-.BI J n
+.Bl -tag -width "M.m.n.d"
+.It Sy J Em n

 The Julian day
 The Julian day

-.I n
-.RI "(1\ \(<=" "\ n\ " "\(<=\ 365).
+.Em n
+(1 \*(Le
+.Em n
+\*(Le 365).

 Leap days are not counted; that is, in all years \(em including leap
 years \(em February 28 is day 59 and March 1 is day 60.  It is
 impossible to explicitly refer to the occasional February 29.
 Leap days are not counted; that is, in all years \(em including leap
 years \(em February 28 is day 59 and March 1 is day 60.  It is
 impossible to explicitly refer to the occasional February 29.

-.TP
-.I n
+.It Em n

 The zero-based Julian day
 The zero-based Julian day

-.RI "(0\ \(<=" "\ n\ " "\(<=\ 365).
+(0 \*(Le
+.Em n
+\*(Le 365 ) .

 Leap days are counted, and it is possible to refer to February 29.
 Leap days are counted, and it is possible to refer to February 29.

-.TP
-.BI M m . n . d
+.It Sy M  Em m.n.d

 The
 The

-.IR d' th
-day
-.RI "(0\ \(<=" "\ d\ " "\(<=\ 6)
+.Em d Ns 'th
+day (0 \*(Le
+.Em d
+\*(Le 6 )

 of week
 of week

-.I n
+.Em n

 of month
 of month

-.I m
+.Em m

 of the year
 of the year

-.RI "(1\ \(<=" "\ n\ " "\(<=\ 5,
-.RI "1\ \(<=" "\ m\ " "\(<=\ 12,
-where week 5 means ``the last
-.I d
+(1 \*(Le
+.Em n
+\*(Le 5),
+(1 \*(Le
+.Em m
+\*(Le 12),
+where week 5 means
+.Do
+the last
+.Em d

 day in month
 day in month

-.IR m ''
+.Em m
+.Dc

 which may occur in either the fourth or the fifth week).  Week 1 is the
 first week in which the
 which may occur in either the fourth or the fifth week).  Week 1 is the
 first week in which the

-.IR d' th
+.Em d Ns 'th

 day occurs.  Day zero is Sunday.
 day occurs.  Day zero is Sunday.

-.RE
-.IP "" 15
+.Pp

 The
 The

-.I time
+.Em time

 has the same format as
 has the same format as

-.I offset
+.Em offset

 except that no leading sign
 except that no leading sign

-.RB (`` \(mi ''
+.Pq Ql \-

 or
 or

-.RB `` \(pl '')
+.Pq Ql +

 is allowed.  The default, if
 is allowed.  The default, if

-.I time
+.Em time

 is not given, is
 is not given, is

-.BR 02:00:00 .
-.RE
-.LP
+.Sy 02:00:00 .
+.El
+.Pp

 If no
 If no

-.I rule
-is present in the 
-.BR TZ 
+.Em rule
+is present in the
+.Ev TZ

 specification, the rules specified
 by the
 specification, the rules specified
 by the

-.IR tzfile (5)-format
+.Xr tzfile 5 Ns -format

 file
 file

-.B posixrules
+.Em posixrules

 in the system time conversion information directory are used, with the
 in the system time conversion information directory are used, with the

-standard and summer time offsets from UTC replaced by those specified by
+standard and summer time offsets from
+.Tn UTC
+replaced by those specified by

 the
 the

-.I offset
+.Em offset

 values in
 values in

-.BR TZ .
-.PP
+.Ev TZ .
+.El
+.Pp

 For compatibility with System V Release 3.1, a semicolon
 For compatibility with System V Release 3.1, a semicolon

-.RB ( ; )
+.Pq Ql ;

 may be used to separate the
 may be used to separate the

-.I rule
+.Em rule

 from the rest of the specification.
 from the rest of the specification.

-.SH FILES
-.ta \w'/usr/share/zoneinfo/posixrules\0\0'u
-/etc/localtime local time zone file
-.br
-/usr/share/zoneinfo    time zone directory
-.br
-/usr/share/zoneinfo/posixrules rules for POSIX-style TZ's
-.br
-/usr/share/zoneinfo/GMT        for UTC leap seconds
-.sp
-If
-.I /usr/share/zoneinfo/GMT
-is absent, UTC leap seconds are loaded from
-.IR /usr/share/zoneinfo/posixrules .
-.SH SEE ALSO
-date(1), gettimeofday(2), ctime(3), getenv(3), time(3), tzfile(5)
+.Sh FILES
+.Bl -tag -width /usr/share/zoneinfo/posixrules -compact
+.It Pa /etc/localtime
+local time zone file
+.It Pa /usr/share/zoneinfo
+time zone directory
+.It Pa /usr/share/zoneinfo/posixrules
+rules for
+.Tn POSIX Ns -style
+.Tn TZ Ns 's
+.It Pa /usr/share/zoneinfo/GMT for
+.Tn UTC
+leap seconds
+.El
+.Pp
+If the file
+.Pa /usr/share/zoneinfo/GMT
+does not exist,
+.Tn UTC
+leap seconds are loaded from
+.Pa /usr/share/zoneinfo/posixrules .
+.Sh SEE ALSO
+.Xr date 1 ,
+.Xr gettimeofday 2 ,
+.Xr ctime 3 ,
+.Xr getenv 3 ,
+.Xr time 3 ,
+.Xr tzfile 5
+.Sh HISTORY
+The
+.Nm tzset
+and
+.Nm tzsetwall
+functions are
+.Ud .