|
|
#include <time.h>char *asctime (const struct tm *tm); char *asctime_r(const struct tm *tm, char *result);
char *ctime (const time_t *clock); char *ctime_r(const time_t *clock, char *result);
struct tm *gmtime (const time_t *clock); struct tm *gmtime_r(const time_t *clock, struct tm *result);
struct tm *localtime (const time_t *clock); struct tm *localtime_r(const time_t *clock, struct tm *result);
void tzset(void);
extern time_t timezone, altzone; extern int daylight; extern char *tzname[2];
ctime- converts UNIX ``epoch'' time to local time
gmtime- convert time to UTC
localtime- converts time pointed to by clock to tm structure
tzset- changes values of time variables
altzone- difference in seconds between UTC and alternate time zone
daylight- set to non-zero value if alternate time zone exists
timezone- difference in seconds between UTC and local time zone
tzname- contains time zone names
In many of the functions described on this manual page, ``epoch'' is used to describe the moment at which time in the UNIX operating system started. The exact starting point is 1970-01-01 00:00 UTC. This point is arbitrary and does not have any special significance.
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.
localtime(S) and localtime_r( ) convert the time in seconds pointed to by clock into a tm structure. The time in clock is the number of seconds since the epoch. 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. The output is the same as that generated by tzset(S).
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( ) and gmtime_r( ) convert the calendar time pointed to by clock into a broken-down time expressed as Coordinated Universal Time (UTC). gmtime_r( ) stores the broken-down time in the struct tm pointed to by result and returns result upon successful completion.
asctime converts a tm structure to a 26-character string, 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 result, which is assumed to hold at least 26 characters. It returns result upon successful completion.
The asctime(S) routine uses the equivalent of the following algorithm to create the date string:
char *asctime(timeptr)
struct tm *timeptr;
{
static char wday_name[7][3] = {
"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"
};
static char mon_name[12][3] = {
"Jan", "Feb", "Mar", "Apr", "May", "Jun",
"Jul", "Aug", "Sep", "Oct", "Nov", "Dec"
};
static char result[26];
sprintf(result, "%.3s %.3s %2d %.2d:%.2d:%.2d %d\n",
wday_name[timeptr->tm_wday],
mon_name[timeptr->tm_mon],
timeptr->tm_mday, timeptr->tm_hour,
timeptr->tm_min, timeptr->tm_sec,
1900 + timeptr->tm_year);
return result;
}
ctime(S) and ctime_r( ) convert the time pointed to by clock representing seconds since the epoch to local time in the form of a 26-character string, and return a pointer to this string. ctime( ) is equivalent to asctime_r(localtime_r(clock,lresult), aresult). ctime_r( ) returns result upon successful completion. The string has the following form. All the fields have constant width.
Fri Sep 13 00:00:00 1986\n\0Time zone and daylight savings corrections are made before the string is generated.
Declarations of all the functions and externals, and the tm structure, are in the <time.h> header file. The tm structure declaration is:
struct tm {
int tm_sec; /* seconds after the minute -- [0, 61] */
/* 60 and 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 daylight savings time */
long tm_tzadj; /* seconds from UTC (east < 0) */
char tm_name[LTZNMAX]; /* name of timezone */
};
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 timezone contains the difference, in seconds, between UTC and the local time zone; the external time_t variable altzone contains the difference, in seconds, between UTC and the alternate time zone; 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", " " };
LTZNMAX specifies the maximum number of
bytes in the time zone name.
The functions handle the peculiarities of this conversion for various time periods for the USA (specifically, the years 1974, 1975, 1976, and 1987). The functions 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. See timezone(F) or environ(M) for the syntax of TZ. tzset( ) 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( ) uses the value of the environment variable TZ to set time conversion information used by localtime(S), ctime(S), strftime(S) and mktime(S). If TZ is absent from the environment, implementation-defined default time zone information is used.
For example, the setting of TZ for New Jersey in 1986 could be
"EST5EDT4,116/2:00:00,298/2:00:00" .or simply
EST5EDTA southern hemisphere setting could be
"KDT9:30KST10:00,303/20:00,64/5:00"
When the longer format is used, the variable must be surrounded by double quotes as shown. For more details, see timezone(F) and environ(M).
In the longer version of the New Jersey example of TZ, the following are set by tzset( ):
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(M)).
asctime( ) returns a date string representing the converted time; ctime( ) returns a date string, with time expressed in local time.
gmtime( ) returns a pointer to a tm structure, with time expressed in UTC (which is the same as GMT); localtime( ) returns a pointer to a tm structure, with time expressed in local time.
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.
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992;
ANSI X3.159-1989 Programming Language -- C
;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1)
;
and
NIST FIPS 151-1
.
tzset(S) is conformant with:
X/Open CAE Specification, System Interfaces and Headers, Issue 4, 1992;
IEEE POSIX Std 1003.1-1990 System Application Program Interface (API) [C Language] (ISO/IEC 9945-1)
;
and
NIST FIPS 151-1
.