Standard C Library Functions ctime(3C)
NAME
ctime, ctimer, localtime, localtimer, gmtime, gmtimer,
asctime, asctimer, tzset - convert date and time to string
SYNOPSIS
#include
char *ctime(const timet *clock);
struct tm *localtime(const timet *clock);
struct tm *gmtime(const timet *clock);
char *asctime(const struct tm *tm);
extern timet timezone, altzone;
extern int daylight;
extern char *tzname[2];
void tzset(void);
char *ctimer(const timet *clock, char *buf, int buflen);
struct tm *localtimer(const timet *restrict clock,
struct tm *restrict res);
struct tm *gmtimer(const timet *restrict clock,
struct tm *restrict res);
char *asctimer(const struct tm *restrict tm, char *restrict buf,
int buflen);
Standard conforming
cc [ flag... ] file... -DPOSIXPTHREADSEMANTICS [ library... ]
char *ctimer(const timet *clock, char *buf);
char *asctimer(const struct tm *tm, char *buf);
DESCRIPTION
SunOS 5.11 Last change: 27 May 2005 1
Standard C Library Functions ctime(3C)
The ctime() function converts the time pointed to by clock,
representing the time in seconds since the Epoch (00:00:00
UTC, January 1, 1970), to local time in the form of a 26-
character string, as shown below. Time zone and daylight
savings corrections are made before string generation. The
fields are in constant width:
Fri Sep 13 00:00:00 1986\n\0
The ctime() function is equivalent to:
asctime(localtime(clock))
The ctime(), asctime(), gmtime(), and localtime() functions
return values in one of two thread-specific data objects: a
broken-down time structure and an array of char. Execution
of any of the functions can overwrite the information
returned in either of these objects by any of the other
functions executed by the same thread.
The ctimer() function has the same functionality as ctime()
except that the caller must supply a buffer buf with length
buflen to store the result; buf must be at least 26 bytes.
The standard-conforming ctimer() function does not take a
buflen parameter.
The localtime() and gmtime() functions return pointers to tm
structures (see below). The localtime() function corrects
for the main time zone and possible alternate ("daylight
savings") time zone; the gmtime() function converts directly
to Coordinated Universal Time (UTC), which is what the UNIX
system uses internally.
The localtimer() and gmtimer() functions have the same
functionality as localtime() and gmtime() respectively,
except that the caller must supply a buffer res to store the
result.
The asctime() function converts a tm structure to a 26-
character string, as shown in the previous example, and
returns a pointer to the string.
SunOS 5.11 Last change: 27 May 2005 2
Standard C Library Functions ctime(3C)
The asctimer() function has the same functionality as asc-
time() except that the caller must supply a buffer buf with
length buflen for the result to be stored. The buf argument
must be at least 26 bytes. The standard-conforming
asctimer() function does not take a buflen parameter. The
asctimer() function returns a pointer to buf upon success.
In case of failure, NUL is returned and errno is set.
Declarations of all the functions and externals, and the tm
structure, are in the header. The members of the tm
structure are:
int tmsec; /* seconds after the minute - [0, 60] */
/* 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 was in effect.
The external timet 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 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 conver-
sion for various time periods for the U.S. (specifically,
the years 1974, 1975, and 1987). They start handling the new
daylight savings time starting with the first Sunday in
SunOS 5.11 Last change: 27 May 2005 3
Standard C Library Functions ctime(3C)
April, 1987.
The tzset() function uses the contents of the environment
variable TZ to override the value of the different external
variables. It is called by asctime() and can also be called
by the user. If TZ is not specified or has an invalid set-
ting, tzset() uses GMT0. See environ(5) for a description of
the TZ environment variable.
Starting and ending times are relative to the current local
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()
change the values of the external variables timezone,
altzone, daylight, and tzname.
Note that in most installations, TZ is set to the correct
value by default when the user logs on, using the local
/etc/default/init file (see TIMEZONE(4)).
RETURN VALUES
Upon successful completion, the gmtime() and localtime()
functions return a pointer to a struct tm. If an error is
detected, gmtime() and localtime() return a null pointer.
Upon successful completion, the gmtimer() and localtimer()
functions return the address of the structure pointed to by
the res argument. If an error is detected, gmtimer() and
localtimer() return a null pointer and set errno to indi-
cate the error.
ERORS
The ctimer() and asctimer() functions will fail if:
ERANGE The length of the buffer supplied by the caller is
not large enough to store the result.
The gmtime(), gmtimer(), localtime(), and localtimer()
functions will fail if:
EOVERFLOW The result cannot be represented.
SunOS 5.11 Last change: 27 May 2005 4
Standard C Library Functions ctime(3C)
USAGE
These functions do not support localized date and time for-
mats. The strftime(3C) function can be used when localiza-
tion is required.
The localtime(), localtimer(), gmtime(), gmtimer(),
ctime(), and ctimer() functions assume Gregorian dates.
Times before the adoption of the Gregorian calendar will not
match historial records.
EXAMPLES
Example 1 Examples of the tzset() function.
The tzset() function 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 is set to 5*60*60, tzname[1] is
EDT, altzone is 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 is set posi-
tive. Starting and ending times are relative to the current
local 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
SunOS 5.11 Last change: 27 May 2005 5
Standard C Library Functions ctime(3C)
thus to change the values of the external variables
timezone, altzone, daylight, and tzname. The ctime(), local-
time(), mktime(), and strftime() functions 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.
BUGS
The zoneinfo timezone data files do not transition past Tue
Jan 19 03:14:07 2038 UTC. Therefore for 64-bit applications
using zoneinfo timezones, calculations beyond this date
might not use the correct offset from standard time, and
could return incorrect values. This affects the 64-bit ver-
sion of localtime(), localtimer(), ctime(), and ctimer().
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
CSI Enabled
Interface Stability Standard
MT-Level MT-Safe with exceptions
The asctime(), ctime(), gmtime(), and localtime() functions
are safe to use in multithread applications because they
employ thread-specific data. However, their use is
discouraged because standards do not require them to be
thread-safe. The asctimer() and gmtimer() functions are
MT-Safe. The ctimer(), localtimer(), and tzset() functions
are MT-Safe in multithread applications, as long as no
user-defined function directly modifies one of the following
variables: timezone, altzone, daylight, and tzname. These
four variables are not MT-Safe to access. They are modified
by the tzset() function in an MT-Safe manner. The mktime(),
localtimer(), and ctimer() functions call tzset().
SEE ALSO
time(2), Intro(3), getenv(3C), mktime(3C), printf(3C),
putenv(3C), setlocale(3C), strftime(3C), TIMEZONE(4), attri-
butes(5), environ(5), standards(5)
SunOS 5.11 Last change: 27 May 2005 6
Standard C Library Functions ctime(3C)
NOTES
When compiling multithreaded programs, see Intro(3).
The return values for asctime(), ctime(), gmtime(), and
localtime() point to thread-specific data whose content is
overwritten by each call by the same thread.
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 tzset() has previously evaluated the timezone identified
by the value of the TZ environment variable, tzset() can
reuse the previous settings of the external variables
altzone, daylight, timezone, and tzname[] associated with
that timezone.
Solaris 2.4 and earlier releases provided definitions of the
ctimer(), localtimer(), gmtimer(), and asctimer() func-
tions as specified in POSIX.1c Draft 6. The final POSIX.1c
standard changed the interface for ctimer() and
asctimer(). Support for the Draft 6 interface is provided
for compatibility only and might not be supported in future
releases. New applications and libraries should use the
standard-conforming interface.
For POSIX.1c-conforming applications, the
POSIXPTHREADSEMANTICS and RENTRANT flags are automati-
cally turned on by defining the POSIXCSOURCE flag with a
value >= 199506L.
In Solaris 10, gmtime(), gmtimer(), localtime(), and
localtimer() were updated to return a null pointer if an
error is detected. This change was based on the SUSv3
specification. See standards(5).
SunOS 5.11 Last change: 27 May 2005 7
|
