ctime(3C)ctime(3C)NAME
ctime, localtime, gmtime, asctime, tzset, ctime_r, localtime_r, gmtime_r,
asctime_r - convert date and time to string
SYNOPSIS
#include <time.h>
char *ctime (const time_t *clock);
struct tm *localtime (const time_t *clock);
struct tm *gmtime (const time_t *clock);
char *asctime (const struct tm *tm);
extern time_t timezone, _timezone, altzone, _altzone;
extern int daylight, _daylight;
extern char *tzname[2], *_tzname[2];
void tzset (void);
char *ctime_r (const time_t *clock, char *buf);
struct tm *localtime_r (const time_t *clock,
struct tm *result);
struct tm *gmtime_r (const time_t *clock,
struct tm *result);
char *asctime_r (const struct tm *tm, char *buf);
DESCRIPTION
ctime, ctime_r, localtime, localtime_r, gmtime, and gmtime_r accept
arguments of type time_t, pointed to by clock, representing the time in
seconds since 00:00:00 UTC, January 1, 1970. ctime and ctime_r return 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, localtime_r, gmtime, and gmtime_r return pointers to tm
structures, described below. localtime and localtime_r correct for the
main time zone and possible alternate (``daylight savings'') time zone;
gmtime and gmtime_r convert directly to Coordinated Universal Time (UTC),
which is the time the UNIX system uses internally.
asctime and asctime_r convert a tm structure to a 26-character string, as
shown in the above example, and returns a pointer to the string.
Page 1
ctime(3C)ctime(3C)
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] */
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 */
/* savings time */
};
The value of tm_isdst 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 tm_isdst was
defined as non-zero if daylight savings time was in effect.)
ctime, gmtime, asctime, and localtime all return pointers to static data
which are overwritten on each call. Reentrant versions of these
functions are also available as name_r. The parameter buf to asctime_r
and ctime_r specify a character buffer where the resultant string should
be placed. This buffer should be at least 26 characters long. The
parameter result to gmtime_r and localtime_r points to where the
resultant broken-down time is placed. These two functions always return
a pointer to that same structure.
The external time_t 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", " " };
Each of these global variables have an alias which makes the variable
names ANSI compliant. The alias refers to the same storage location and
is identified by preceding the name of the variable with an underscore
'_'.
These functions know about the peculiarities of this conversion 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.
Page 2
ctime(3C)ctime(3C)
tzset uses the contents of the environment variable TZ to override the
value of the different external variables. It also sets the external
variable daylight to zero if Daylight Savings Time conversions should
never be applied for the time zone in use; otherwise, non-zero. tzset is
called by asctime and asctime_r 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
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. tzset changes 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 time_t 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)].
EXAMPLES
This example returns a string containing the current date and time using
any locally set timezone information:
time_t t;
char *c;
t = time(NULL);
c = asctime(localtime(&t));
Page 3
ctime(3C)ctime(3C)DIAGNOSTICSFILES
/usr/lib/locale/language/LC_TIME - file containing locale specific date
and time information
SEE ALSOtime(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.
Page 4
