ctime(3C) DG/UX 5.4R3.00 ctime(3C)
NAME
ctime, ctimer, localtime, localtimer, gmtime, gmtimer, asctime,
asctimer, tzset - convert date and time to string
SYNOPSIS
#include <time.h>
char *ctime (const timet *clock);
char *ctimer (const timet *clock, char *buf, int *buflen);
struct tm *localtime (const timet *clock);
struct tm *localtimer (const timet *clock, struct tm *result);
struct tm *gmtime (const timet *clock);
struct tm *gmtimer (const timet *clock, struct tm *result);
char *asctime (const struct tm *tm);
char *asctimer (const struct tm *tm, char *buf, int *buflen)
void tzset (void);
extern timet timezone, altzone;
extern int daylight;
extern char *tzname[2];
DESCRIPTION
buf is a pointer to the location of a string (array of characters
terminated by a null character) into which the time is returned.
buflen is the maximum number of characters in *buf . clock is a
pointer to calendar time representing the time in seconds since
00:00:00 UTC, January 1, 1970. tm and result refer to a pointer to a
structure containing the broken-down time.
ctime, localtime, and gmtime accept arguments of type timet, pointed
to by clock. 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
The ctimer function converts the calendar time pointed to by clock
to local time in the same form as ctime. Instead of returning static
data, ctimer returns the string into the location pointed to by buf.
Upon successful completion, the return value from the function is a
pointer to the same structure buf points to. If the function was not
successful, the return value is a NULL pointer and errno is set to
indicate the error.
Licensed material--property of copyright holder(s) 1
ctime(3C) DG/UX 5.4R3.00 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 Coordinated Universal Time (UTC), which is the time the DG/UX
system uses internally.
The localtimer and gmtimer functions work like localtime and gmtime
respectively except for the data returned. Instead of returning
static data, both functions return a pointer to the broken down time
structure in the parameter result. The return value of these
functions is a pointer to the same structure result points to.
asctime and asctimer convert a broken-down time in the tm structure
to a character string. asctime returns a 26-character string.
asctimer returns a character string pointed to by buf with a maximum
of buflen characters. If successful, both functions return a pointer
to a string with the same format as ctime. asctimer also returns a
pointer to the character string in buf. Otherwise asctimer returns
NULL and sets errno to indicate the error.
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. (Previously, the value of
tmisdst was defined as non-zero if daylight savings time was in
effect.)
The external timet 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 (in EST, timezone is
5*60*60). 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
Licensed material--property of copyright holder(s) 2
ctime(3C) DG/UX 5.4R3.00 ctime(3C)
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, asctimer 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. The effects of tzset are thus to change the values of the
external variables timezone, altzone, daylight, and tzname. ctime,
ctimer, localtime, localtimer, mktime, and strftime will also
update these external variables 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)].
time(2) is quite useful for producing the values with which to call
ctime(3C).
Licensed material--property of copyright holder(s) 3
ctime(3C) DG/UX 5.4R3.00 ctime(3C)
Considerations for Threads Programming
+------------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+------------+-----------------------------+
|asctime | N - - |
|asctimer | Y N N |
|ctime | N - - |
|ctimer | Y N N |
|gmtime | N - - |
|gmtimer | Y N N |
|localtime | N - - |
|localtimer | Y N N |
|tzset | Y N N |
+------------+-----------------------------+
When one thread changes the external variables timezone, altzone,
daylight and tzname[2], the other threads running in a process will
be affected. The value of these variables will change immediately for
all threads running in a process.
FILES
/usr/lib/locale/language/LCTIME - file containing locale specific
date and time information
DIAGNOSTICS
Errors
If the following condition occurs, ctimer and asctimer 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.
SEE ALSO
time(2), reentrant(3), getenv(3C), difftime(3C), mktime(3C),
putenv(3C), printf(3S), setlocale(3C), strftime(3C), profile(4),
strftime(4), timezone(4), environ(5), zic(1M).
NOTES
Executing putenv to change the TZ environment variable, does not
automatically update tzname[2]. A tzset must be done after the
putenv to re-synchronize the environment with the tzname array.
Otherwise the value for for tzname[2] may be out of date and cause
incorrect results.
The functions asctimer, ctimer, gmtimer, and localtimer are only
available in the shared library, libc.so.
The return values for ctime, localtime, and gmtime point to static
data whose content is overwritten by each call.
Licensed material--property of copyright holder(s) 4
ctime(3C) DG/UX 5.4R3.00 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 Julian start and end days
annually if the full form of the TZ variable is specified.
Licensed material--property of copyright holder(s) 5