ctime(3C) (C Programming Language Utilities) ctime(3C)
NAME
ctime, localtime, gmtime, asctime, tzset - convert date and time to
string
SYNOPSIS
#include <time.h>
char *ctime (const timet *clock);
struct tm *localtime (const timet *clock);
struct tm *gmtime (const timet *clock);
char *asctime (const struct tm *tm);
extern timet timezone, altzone;
extern int daylight;
extern char *tzname[2];
void tzset (void);
DESCRIPTION
ctime, localtime, and gmtime accept arguments of type timet, pointed
to by clock, representing the time in seconds since 00:00:00 UTC,
January 1, 1970. ctime returns a pointer to a 26-character string as
shown below. Time zone and daylight savings corrections are made
before the string is generated. The fields are constant in width:
Fri Sep 13 00:00:00 1986\n\0
localtime and gmtime return pointers to tm structures, described
below. localtime corrects for the main time zone and possible
alternate (``daylight saving'') time zone; gmtime converts directly
to Coordinated Universal Time (UTC), which is the time the UNIX
system uses internally.
asctime converts a tm structure to a 26-character string, as shown in
the above example, and returns a pointer to the string.
Declarations of all the functions and externals, and the tm
structure, are in the <time.h> header file. The structure
declaration is:
struct tm {
int tm_sec; /* seconds after the minute - [0, 61]
for leap seconds */
int tm_min; /* minutes after the hour - [0, 59] */
int tm_hour; /* hour since midnight - [0, 23] */
int tm_mday; /* day of the month - [1, 31] */
8/91 Page 1
ctime(3C) (C Programming Language Utilities) ctime(3C)
int tm_mon; /* months since January - [0, 11] */
int tm_year; /* years since 1900 */
int tm_wday; /* days since Sunday - [0, 6] */
int tm_yday; /* days since January 1 - [0, 365] */
int tm_isdst; /* flag for alternate daylight saving time */
};
The value of tmisdst is positive if daylight saving time is in
effect, zero if daylight saving time is not in effect, and negative
if the information is not available. (Previously, the value of
tmisdst was defined as non-zero if daylight saving time was in
effect.)
The external timet variable altzone contains the difference, in
seconds, between Coordinated Universal Time and the alternate time
zone. The external variable timezone contains the difference, in
seconds, between UTC and local standard time. The external variable
daylight indicates whether time should reflect daylight savings time.
Both timezone and altzone default to 0 (UTC). The external variable
daylight is non-zero if an alternate time zone exists. The time zone
names are contained in the external variable tzname, which by default
is set to:
char *tzname[2] = { "GMT", " " };
These functions know about the peculiarities of this conversion for
various time periods for the U.S.A (specifically, the years 1974,
1975, and 1987). They will handle the new daylight saving time
starting with the first Sunday in April, 1987.
tzset uses the contents of the environment variable TZ to override
the value of the different external variables. The function tzset is
called by asctime and may also be called by the user. See environ(5)
for a description of the TZ environment variable.
tzset scans the contents of the environment variable and assigns the
different fields to the respective variable. For example, the most
complete setting for New Jersey in 1986 could be
"EST5EDT4,116/2:00:00,298/2:00:00" .
or simply
EST5EDT
An example of a southern hemisphere setting such as the Cook Islands
could be
"KDT9:30KST10:00,63/5:00,302/20:00"
Page 2 8/91
ctime(3C) (C Programming Language Utilities) ctime(3C)
In the longer version of the New Jersey example of TZ, tzname[0] is
EST, timezone will be set to 5*60*60, tzname[1] is EDT, altzone will
be set to 4*60*60, the starting date of the alternate time zone is
the 117th day at 2 AM, the ending date of the alternate time zone is
the 299th day at 2 AM (using zero-based Julian days), and daylight
will be set positive. Starting and ending times are relative to the
alternate time zone. If the alternate time zone start and end dates
and the time are not provided, the days for the United States that
year will be used and the time will be 2 AM. If the start and end
dates are provided but the time is not provided, the time will be 2
AM. The effects of tzset are thus to change the values of the
external variables timezone, altzone, daylight and tzname. ctime,
localtime, mktime and strftime will also update these external
variables as if they had called tzset at the time specified by the
timet or struct tm value that they are converting.
Note that in most installations, TZ is set to the correct value by
default when the user logs on, via the local /etc/profile file [see
profile(4) and timezone(4)].
FILES
/usr/lib/locale/language/LCTIME - file containing locale specific
date and time information
SEE ALSO
time(2), getenv(3C), mktime(3C), putenv(3C), printf(3S),
setlocale(3C), strftime(3C), cftime(4), profile(4), timezone(4),
environ(5).
NOTES
The return values for ctime, localtime and gmtime point to static
data whose content is overwritten by each call.
Setting the time during the interval of change from timezone to
altzone or vice versa can produce unpredictable results. The system
administrator must change the Julian start and end days annually.
8/91 Page 3