ctime(3C) ctime(3C)
NAME
ctime, localtime, gmtime, asctime, timezone, altzone, daylight,
tzname, 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 *timeptr);
extern long int 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 (Coordinated Universal Time), January 1, 1970. ctime() returns a
pointer to a 26-character string in the following form (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
ctime() is equivalent to:
asctime(localtime(clock))
localtime() and gmtime() return pointers to tm structures, described
below. localtime() corrects for the main time zone and possible alter-
nate ("daylight savings") time zone; gmtime() converts directly to
UTC, which is the time the Reliant 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 using the
equivalent of the following algorithm:
char *asctime(const struct tm *timeptr)
{
static char wdayname[7][3] = {
"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
};
static char monname[12][3] = {
"Jan", "Feb", "Mar", "Apr", "May", "Jun",
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
};
static char result[26];
Page 1 Reliant UNIX 5.44 Printed 11/98
ctime(3C) ctime(3C)
sprintf(result, "%.3s %.3s%3d %.2d:%.2d:%.2d %d\n",
wdayname[timeptr->tmwday],
monname[timeptr->tmmon],
timeptr->tmmday, timeptr->tmhour,
timeptr->tmmin, timeptr->tmsec,
1900 + timeptr->tmyear);
return result;
}
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] */
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.
The external variable altzone contains the difference, in seconds,
between UTC 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. (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() or may also be called by the user. Further details
about the TZ environment variable will be found in the description of
environ(5).
Page 2 Reliant UNIX 5.44 Printed 11/98
ctime(3C) ctime(3C)
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 pro-
vided 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(), local-
time(), 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)].
RETURN VALUE
The ctime() and localtime() function return the pointer returned by
asctime() with that broken-down time as an argument.
Upon successful completion, asctime() returns a pointer to the string.
The gmtime() function returns a pointer to a struct tm.
NOTES
The asctime(), ctime(), gmtime() and localtime() functions return
values in one of two static objects: a broken-down time structure and
an array of char. Execution of any of the functions may overwrite the
information returned in either of these objects by any of the other
functions.
Page 3 Reliant UNIX 5.44 Printed 11/98
ctime(3C) ctime(3C)
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 start and end days annually if the form
of calendar used is the Julian.
gmtime() and localtime() do not support localized date and time for-
mats. strftime(3C) should be used to achieve maximum portability.
FILES
/usr/lib/locale/locale/LCTIME
contains specific date and time information for the local envi-
ronment.
SEE ALSO
time(2), cftime(3C), clock(3C), getenv(3C), mktime(3C), putenv(3C),
setlocale(3C), strftime(3C), printf(3S), profile(4), timezone(4),
environ(5).
Page 4 Reliant UNIX 5.44 Printed 11/98