CTIME(3C) STANDARD C LIBRARY CTIME(3C)
NAME
ctime, ctime_r, localtime, localtime_r, gmtime, gmtime_r,
asctime, asctime_r, tzset -- convert date and time to string
SYNOPSIS
#include <time.h>
char *ctime(const time_t *clock);
char *ctime_r(const time_t *clock, char *buffer);
struct tm *localtime(const time_t *clock);
struct tm *localtime_r(const time_t *clock, struct tm *
result);
struct tm *gmtime(const time_t *clock);
struct tm *gmtime_r(const time_t *clock, struct tm *
result);
char *asctime(const struct tm *tm);
char *asctime_r(const struct tm *tm, char *buffer);
extern time_t timezone, altzone;
extern int daylight;
extern char *tzname[2];
void tzset(void);
DESCRIPTION
The reentrant functions (suffixed by _r) require the user to
allocate the necessary space for the return value and pass a
pointer to this area using result.
ctime, ctime_r, localtime, localtime_r, gmtime, and gmtime_r
accept arguments of type time_t, pointed to by clock, repre-
senting the time in seconds since 00:00:00 GMT, January 1,
1970. ctime returns a pointer to a 26 character string as
shown below. ctime_r converts the calendar time pointed to
by clock to local time in the same format as shown below and
places the string into the location pointed to by buffer,
which is assumed to hold at least 26 characters. ctime_r
returns buffer upon successful completion. 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
SUPER-UX Last change: Oct 19, 1999 1
CTIME(3C) STANDARD C LIBRARY CTIME(3C)
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 Greenwich Time (GMT), which is
the time the UNIX system uses internally. localtime_r con-
verts the calendar time pointed to by clock into a broken-
down time that is stored in the struct tm pointed to by
result. It returns result, upon successful completion.
gmtime_r converts the calendar time pointed to by clock into
a broken-down time expressed as Greenwich Time (GMT). The
broken-down time is stored in the struct tm pointed to by
result. gmtime_r returns result, upon successful comple-
tion.
asctime converts a tm structure to a 26-character string, as
shown in the above example, and returns a pointer to the
string. asctime_r converts the broken-down time in the
structure pointed to by tm into a string that is placed in
the location pointed to by buffer, which is assumed to hold
at least 26 characters. It returns buffer upon successful
completion.
Declarations of all the functions and externals, and the tm
structure, are in the time.h header file. The members for
this structure include:
struct tm{
int tm_sec; /* seconds after the minute - [0,59] */
/* for leap seconds */
int tm_min; /* minutes after the hour - [0,59] */
int tm_hour; /* hours since midnight - [0,23] */
int tm_mday; /* day of the month - [1,31] */
int tm_mon; /* months since January - [0,11] */
int tm_year; /* year 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.)
The external time_t variable altzone contains the differ-
ence, in seconds, between Coordinated Universal Time and
the alternate time zone. The external variable timezone
contains the difference, in seconds, between GMT and local
standard time. The external variable daylight indicates
whether time should reflect daylight savings time. Both
timezone and altzone default to 0 (GMT). The external vari-
able daylight is non-zero if an alternate time zone exists.
SUPER-UX Last change: Oct 19, 1999 2
CTIME(3C) STANDARD C LIBRARY CTIME(3C)
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.A. (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. 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 may also be called by the user. See environ()
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 val-
ues 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
SUPER-UX Last change: Oct 19, 1999 3
CTIME(3C) STANDARD C LIBRARY CTIME(3C)
value by default when the user logs on, via the local
/etc/profile file [see profile(4) and timezone(4)].
THREAD-SAFE
- Multi-safe (only ctime_r, localtime_r, gmtime_r, and asc-
time_r)
SEE ALSO
environ(5), getenv(3C), mktime(3C), printf(3S), profile(4),
putenv(3C), setlocale(3C), strftime(3C), strftime(4),
time(2), timezone(4), pthreads(3T)
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.
Use the reentrant functions for multi-threaded applications.
SUPER-UX Last change: Oct 19, 1999 4
G1AB02E Programmer's Reference Manual