Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
TZSET(3)	       FreeBSD Library Functions Manual		      TZSET(3)

NAME
     tzset, tzalloc, tzgetname,	tzgetgmtoff, tzfree -- initialize time conver-
     sion information

LIBRARY
     Standard C	Library	(libc, -lc)

SYNOPSIS
     #include <time.h>

     timezone_t
     tzalloc(const char	*zone);

     void
     tzfree(timezone_t restrict	tz);

     const char	*
     tzgetname(timezone_t restrict tz, int isdst);

     long
     tzgetgmtoff(timezone_t restrict tz, int isdst);

     void
     tzset(void);

DESCRIPTION
     The tzalloc() function takes as an	argument a timezone name and returns a
     timezone_t	object suitable	to be used in the ctime_rz(), localtime_rz(),
     and mktime_z() functions.

     If	tz is not a valid timezone description,	or if the object cannot	be al-
     located, tzalloc()	returns	a NULL pointer and sets	errno.

     A NULL pointer may	be passed to tzalloc() instead of a timezone name, to
     refer to the current system timezone.  An empty timezone string indicates
     Coordinated Universal Time	(UTC).

     Note that instead of setting the environment variable TZ, and globally
     changing the behavior of the calling program, one can use multiple	time-
     zones at the same time by using separate timezone_t objects allocated by
     tzalloc() and calling the "z" variants of the functions.  The tzfree()
     function deallocates tz, which was	previously allocated by	tzalloc().
     This invalidates any tm_zone pointers that	tz was used to set.  The func-
     tion tzgetname() returns the name for the given tz.  If isdst is 0, the
     call is equivalent	to tzname[0].  If isdst	is set to 1 the	call is	equiv-
     alent to tzname[1].  The return values for	both tzgetname() and
     tzgmtoff()	correspond to the latest time for which	data is	available,
     even if that refers to a future time.  Finally, the tzgetgmtoff() func-
     tion acts like tzgetname()	only it	returns	the offset in seconds from GMT
     for the timezone.	If there is no match, then -1 is returned and errno is
     set to ESRCH.  The	tzset()	function acts like tzalloc(getenv("TZ")), ex-
     cept it saves any resulting timezone object into internal storage that is
     accessed by localtime(), localtime_r(), and mktime().  The	anonymous
     shared timezone object is freed by	the next call to tzset().  If the im-
     plied call	to tzalloc() fails, tzset() falls back on Universal Time (UT).
     If	TZ is NULL, the	best available approximation to	local (wall clock)
     time, as specified	by the tzfile(5) format	file /etc/localtime is used by
     localtime(3).  If TZ appears in the environment but its value is the
     empty string, UT is used, with the	abbreviation "UTC" and without leap
     second correction;	please see ctime(3).  If TZ is nonnull and nonempty:

     -	 if the	value begins with a colon, it is used as a pathname 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 time	conversion informa-
	 tion, and, if that file cannot	be read, is used directly as a speci-
	 fication of the time conversion information.

     When TZ 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
     /usr/share/zoneinfo.  The file must be in the format specified in
     tzfile(5).

     When TZ is	used directly as a specification of the	time conversion	infor-
     mation, it	must have the following	syntax (spaces inserted	for clarity):

	   stdoffset[dst[offset][,rule]]

     where:
     std and dst  Three	or more	bytes that are the designation for the stan-
		  dard (std) or	the alternative	(dst such as daylight saving
		  time)	timezone.  Only	std is required; if dst	is missing,
		  then daylight	saving 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 NUL bytes are allowed.  Alterna-
		  tively, a designation	can be surrounded by angle brackets <
		  and >; in this case, the designation can contain any charac-
		  ters other than > and	NUL.
     offset	  Indicates the	value one must add 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 fol-
		  lowing std is	required.  If no offset	follows	dst, daylight
		  saving 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 timezone
		  shall	be east	of the Prime Meridian; otherwise it shall be
		  west (which may be indicated by an optional preceding	"+").
     rule	  Indicates when to change to and back from daylight saving
		  time.	 The rule has the form:

			date/time,date/time

		  where	the first date describes when the change from standard
		  to daylight saving time occurs 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.	 As an extension to POSIX, daylight saving is assumed
		  to be	in effect all year if it begins	January	1 at 00:00 and
		  ends December	31 at 24:00 plus the difference	between	day-
		  light	saving and standard time, leaving no room for standard
		  time in the calendar.	 The format of date is one of the fol-
		  lowing:
		  Jn		  The Julian day n (1 <= n <= 365).  Leap days
				  are not counted; that	is, in all years - in-
				  cluding 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 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 Sunday.
		  The time has the same	format as offset except	that POSIX
		  does not allow a leading sign	"-" or "+" is allowed.	As an
		  extension to POSIX, the hours	part of	time can range from
		  -167 through 167; this allows	for unusual rules such as "the
		  Saturday before the first Sunday of March".  The default, if
		  time is not given, is	02:00:00.

     Here are some examples of TZ values that directly specify the timezone
     rules; they use some of the extensions to POSIX.

     EST5    stands for	US Eastern Standard Time (EST),	5 hours	behind UT,
	     without daylight saving.

     FJT-12FJST,M11.1.0,M1.3.4/75

     <+12>-12<+13>,M11.1.0,M1.2.1/147
	     stands for	Fiji time, 12 hours ahead of UT, springing forward on
	     November's	first Sunday at	02:00, and falling back	on January's
	     second Monday at 147:00 (i.e., 03:00 on the first Sunday on or
	     after January 14).	 The abbreviations for standard	and daylight
	     saving time are "+12" and "+13".

     IST-2IDT,M3.4.4/26,M10.5.0
	     stands for	Israel Standard	Time (IST) and Israel Daylight Time
	     (IDT), 2 hours ahead of UT, springing forward on March's fourth
	     Thursday at 26:00 (i.e., 02:00 on the first Friday	on or after
	     March 23),	and falling back on October's last Sunday at 02:00.

     <-04>4<-03>,J1/0,J365/25
	     stands for	permanent daylight saving time,	3 hours	behind UT with
	     abbreviation "-03".  There	is a dummy fall-back transition	on De-
	     cember 31 at 25:00	daylight saving	time (i.e., 24:00 standard
	     time, equivalent to January 1 at 00:00 standard time), and	a si-
	     multaneous	spring-forward transition on January 1 at 00:00	stan-
	     dard time,	so daylight saving time	is in effect all year and the
	     initial _-04_ is a	placeholder.

     <-03>3<-02>,M3.5.0/-2,M10.5.0/-1
	     stands for	time in	western	Greenland, 3 hours behind UT, where
	     clocks follow the EU rules	of springing forward on	March's	last
	     Sunday at 01:00 UT	(-02:00	local time, i.e., 22:00	the previous
	     day) and falling back on October's	last Sunday at 01:00 UT
	     (-01:00 local time, i.e., 23:00 the previous day).	 The abbrevia-
	     tions for standard	and daylight saving time are "-03" and "-02".

     If	no rule	is present in TZ, the rules specified by the tzfile(5) format
     file posixrules in	/usr/share/zoneinfo are	used, with the standard	and
     daylight saving time offsets from UT replaced by those specified by the
     offset values in TZ.

     For compatibility with System V Release 3.1, a semicolon (;) may be used
     to	separate the rule from the rest	of the specification.

FILES
     /etc/localtime		     local timezone file
     /usr/share/zoneinfo	     local timezone information	directory
     /usr/share/zoneinfo/posixrules  used with POSIX-style TZ's
     /usr/share/zoneinfo/GMT	     for UTC leap seconds

     If	/usr/share/zoneinfo/GMT	is absent, UTC leap seconds are	loaded from
     /usr/share/zoneinfo/posixrules.

SEE ALSO
     ctime(3), getenv(3), strftime(3), time(3),	tzfile(5)

STANDARDS
     The tzset() function conforms to IEEE Std 1003.1-1988 ("POSIX.1").

BUGS
     Neither the tzgetname() nor tzgmtoff() functions have the ability to
     specify the point in time for which the requested data should be re-
     turned.

FreeBSD	13.0			 July 2, 2019			  FreeBSD 13.0

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | STANDARDS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=tzset&sektion=3&manpath=NetBSD+9.2>

home | help