.\" Copyright (c) 1989 The Regents of the University of California.
.\" This code is derived from software contributed to Berkeley by
.\" Redistribution and use in source and binary forms are permitted provided
.\" that: (1) source distributions retain this entire copyright notice and
.\" comment, and (2) distributions including binaries display the following
.\" acknowledgement: ``This product includes software developed by the
.\" University of California, Berkeley and its contributors'' in the
.\" documentation or other materials provided with the distribution and in
.\" all advertising materials mentioning features or use of this software.
.\" 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.
.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND WITHOUT ANY EXPRESS OR IMPLIED
.\" WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
.\" @(#)ctime.3 6.13 (Berkeley) 6/23/90
.TH CTIME 3 "June 23, 1990"
asctime, ctime, difftime, gmtime, localtime, mktime, tzset, tzsetwall \- convert date and time to ASCII
.B extern char *tzname[2];
.B #include <sys/types.h>
.B double difftime(time1, time0)
.B struct tm *localtime(clock)
.B struct tm *gmtime(clock)
uses the value of the environment variable
to set time conversion information used by
does not appear in the environment,
the best available approximation to local wall clock time, as specified
in the system time conversion information directory, is used by
appears in the environment but its value is a null string,
Coordinated Universal Time (UTC) is used (without leap second
appears in the environment and its value is not a null string:
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 information,
and, if that file cannot be read, is used directly as a specification of
the time conversion information.
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
The file must be in the format specified in
is used directly as a specification of the time conversion information,
it must have the following syntax (spaces inserted for clarity):
\fIstd\|offset\fR[\fIdst\fR[\fIoffset\fR][\fB,\fIrule\fR]]
Three or more bytes that are the designation for the standard
is missing, then summer time does not apply in this locale.
Upper- and lowercase letters are explicitly allowed. Any characters
and ASCII NUL are allowed.
Indicates the value one must add to the local time to arrive at
Coordinated Universal Time. The
\fIhh\fR[\fB:\fImm\fR[\fB:\fIss\fR]]
is required and may be a single digit. The
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
the time zone shall be east of the Prime Meridian; otherwise it shall be
west (which may be indicated by an optional preceding
Indicates when to change to and back from summer time. The
\fIdate\fB/\fItime\fB,\fIdate\fB/\fItime\fR
describes when the change from standard to summer time occurs and the
describes when the change back happens. Each
field describes when, in current local time, the change to the other
.RI "(1\ \(<=" "\ n\ " "\(<=\ 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.
The zero-based Julian day
.RI "(0\ \(<=" "\ n\ " "\(<=\ 365).
Leap days are counted, and it is possible to refer to February 29.
.RI "(0\ \(<=" "\ d\ " "\(<=\ 6)
.RI "(1\ \(<=" "\ n\ " "\(<=\ 5,
.RI "1\ \(<=" "\ m\ " "\(<=\ 12,
where week 5 means ``the last
which may occur in either the fourth or the fifth week). Week 1 is the
day occurs. Day zero is Sunday.
except that no leading sign
is allowed. The default, if
in the system time conversion information directory are used, with the
standard and summer time offsets from UTC replaced by those specified by
For compatibility with System V Release 3.1, a semicolon
may be used to separate the
from the rest of the specification.
environment variable does not specify a
and cannot be interpreted as a direct specification,
returns the best available approximation of local wall clock time.
converts a long integer, pointed to by
representing the time in seconds since
00:00:00 UTC, January 1, 1970,
and returns a pointer to a
Thu Nov 24 18:22:48 1986\n\0
All the fields have constant width.
return pointers to ``tm'' structures, described below.
corrects for the time zone and any time zone adjustments
(such as Daylight Saving Time in the U.S.A.).
has not been called in the current process).
After filling in the ``tm'' structure,
ASCII string that's the time zone abbreviation to be used with
converts to Coordinated Universal Time.
converts a time value contained in a
``tm'' structure to a 26-character string,
as shown in the above example,
converts the broken-down time,
in the structure pointed to by
into a calendar time value with the same encoding as that of the values
The original values of the
components of the structure are ignored,
and the original values of the other components are not restricted
(A positive or zero value for
to presume initially that summer time (for example, Daylight Saving Time
is or is not in effect for the specified time.
function to attempt to divine whether summer time is in effect
On successful completion, the values of the
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
returns the specified calendar time;
If the calendar time cannot be represented,
returns the difference between two calendar times,
Declarations of all the functions and externals, and the ``tm'' structure,
includes the following fields:
.ta .5i +\w'long tm_gmtoff;\0\0'u
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 \(**/
fields exist, and are filled in, only if arrangements to do
so were made when the library containing these functions was
There is no guarantee that these fields will continue to exist
in this form in future releases of this code.
is non-zero if summer time is in effect.
is the offset (in seconds) of the time represented
from UTC, with positive values indicating east
.ta \w'/usr/share/zoneinfo/posixrules\0\0'u
/usr/share/zoneinfo time zone information directory
/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
.I /usr/share/zoneinfo/GMT
UTC leap seconds are loaded from
.IR /usr/share/zoneinfo/posixrules .
time(2), getenv(3), tzfile(5)
The return values point to static data
whose content is overwritten by each call.
points to a static array of characters, which
will also be overwritten at the next call
Avoid using out-of-range values with
when setting up lunch with promptness sticklers in Riyadh.
projects / unix-history / blob