ctime(3C) COMPATIBILITY FUNCTIONS 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 savings'') 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 tmsec; /* seconds after the minute - [0, 61] */
/* for leap seconds */
int tmmin; /* minutes after the hour - [0, 59] */
int tmhour; /* hour since midnight - [0, 23] */
Last change: C Programming Language Utilities 1
ctime(3C) COMPATIBILITY FUNCTIONS ctime(3C)
int tmmday; /* day of the month - [1, 31] */
int tmmon; /* months since January - [0, 11] */
int tmyear; /* years since 1900 */
int tmwday; /* days since Sunday - [0, 6] */
int tmyday; /* days since January 1 - [0, 365] */
int tmisdst; /* flag for alternate daylight */
/* savings time */
};
The value of tmisdst is positive if daylight savings time
is in effect, zero if daylight savings 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 savings time was in effect.)
The external timet variable altzone contains the differ-
ence, in seconds, between Coordinated Universal Time and the
alternate time zone. The external variable timezone con-
tains 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 vari-
able 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 conver-
sion for various time periods for the U.S. (specifically,
the years 1974, 1975, and 1987). They will handle the new
daylight savings 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
Last change: C Programming Language Utilities 2
ctime(3C) COMPATIBILITY FUNCTIONS ctime(3C)
An example of a southern hemisphere setting such as the Cook
Islands could be
KDT9:30KST10:00,63/5:00,302/20:00
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 vari-
ables 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.
Last change: C Programming Language Utilities 3