ctime(3C) SDK R4.11 ctime(3C)
NAME
ctime, ctime_r, localtime, localtime_r, gmtime, gtime_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, int buflen);
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, int buflen);
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. buflen is the maximum number of characters in the
buffer pointer being passed in.
ctime, ctime_r, localtime, localtime_, 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 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 Aug 13 00:00:00 1993\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 DG/UX
system uses internally. localtime_r converts 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 Coordinated Universal Time
(UTC). The broken-down time is stored in the struct tm pointed to by
result. gmtime_r returns result, upon successful completion.
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:
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.)
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
conversions (not necessarily if they are in effect currently, just if
the conversions should be done at all). 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 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 , asctime_r 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 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)].
Files
/usr/lib/locale/language/LC_TIME
file containing locale specific date and time information
Errors
If an error occurs, localtime_r and gmtime_r return (struct tm *)
NULL.
If the following condition occurs, ctime_r and asctime_r return NULL
and set errno to the corresponding value:
[ERANGE] The value of buflen is smaller than the length of the
string to be returned.
Considerations for Threads Programming
+------------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+------------+-----------------------------+
|asctime | N - - |
|asctime_r | Y N N |
|ctime | N - - |
|ctime_r | Y N N |
|gmtime | N - - |
|gmtime_r | Y N N |
|localtime | N - - |
|localtime_r | Y N N |
|tzset | Y N N |
+------------+-----------------------------+
REFERENCES
time(2), reentrant(3), getenv(3C), mktime(3C), putenv(3C),
setlocale(3C), strftime(3C), printf(3S), profile(4), strftime(4),
timezone(4), environ(5),
NOTICES
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 if
the full form of the TZ variable is specified.
Use the reentrant functions for multithreaded applications.
Licensed material--property of copyright holder(s)