Converts the formats of date and time representations.
Standard C Library (libc.a)
#include <time.h>char *ctime ( Clock)
const time_t *Clock;
struct tm *localtime (Clock)
const time_t *Clock;struct tm *gmtime (Clock)
const time_t *Clock;time_t mktime( Timeptr)
struct tm *Timeptr;
double difftime( Time1, Time0)
time_t Time0, Time1;
char *asctime ( Tm)
const struct tm *Tm;
void tzset ( )
extern long int timezone;
extern int daylight;
extern char *tzname[];Attention: Do not use the tzset subroutine when linking with both libc.a and libbsd.a. The tzset subroutine sets the global external variable called timezone, which conflicts with the timezone subroutine in libbsd.a. This name collision may cause unpredictable results.
Attention: Do not use the ctime, localtime, gmtime, or asctime subroutine in a multithreaded environment. See the multithread alternatives in the ctime_r (ctime_r, localtime_r, gmtime_r, or asctime_r Subroutine), localtime_r, gmtime_r, or asctime_r subroutine article.
The ctime subroutine converts a time value pointed to by the Clock parameter, which represents the time in seconds since 00:00:00 Coordinated Universal Time (UTC), January 1, 1970, into a 26-character string in the following form:
Sun Sept 16 01:03:52 1973\n\0The width of each field is always the same as shown here.
The ctime subroutine adjusts for the time zone and daylight saving time, if it is in effect.
The localtime subroutine converts the long integer pointed to by the Clock parameter, which contains the time in seconds since 00:00:00 UTC, 1 January 1970, into a tm structure. The localtime subroutine adjusts for the time zone and for daylight-saving time, if it is in effect. Use the time-zone information as though localtime called tzset.
The gmtime subroutine converts the long integer pointed to by the Clock parameter into a tm structure containing the Coordinated Universal Time (UTC), which is the time standard the operating system uses.
The tm structure is defined in the time.h file, and it contains the following members:
int tm_sec; /* Seconds (0 - 59) */
int tm_min; /* Minutes (0 - 59) */
int tm_hour; /* Hours (0 - 23) */
int tm_mday; /* Day of month (1 - 31) */
int tm_mon; /* Month of year (0 - 11) */
int tm_year; /* Year - 1900 */
int tm_wday; /* Day of week (Sunday = 0) */
int tm_yday; /* Day of year (0 - 365) */
int tm_isdst; /* Nonzero = Daylight saving time */The mktime subroutine is the reverse function of the localtime subroutine. The mktime subroutine converts the tm structure into the time in seconds since 00:00:00 UTC, 1 January 1970. The tm_wday and tm_yday fields are ignored, and the other components of the tm structure are not restricted to the ranges specified in the /usr/include/time.h file. The value of the tm_isdst field determines the following actions of the mktime subroutine:
| Item | Description |
|---|---|
| 0 | Initially presumes that Daylight Savings Time (DST) is not in effect. |
| >0 | Initially presumes that DST is in effect. |
| -1 | Actively determines whether DST is in effect from the specified time and the local time zone. Local time zone information is set by the tzset subroutine. |
Upon successful completion, the mktime subroutine sets the values of the tm_wday and tm_yday fields appropriately. Other fields are set to represent the specified time since January 1, 1970. However, the values are forced to the ranges specified in the /usr/include/time.h file. The final value of the tm_mday field is not set until the values of the tm_mon and tm_year fields are determined.
The difftime subroutine computes the difference between two calendar times: the Time1 and -Time0 parameters.
The asctime subroutine converts a tm structure to a 26-character string of the same format as ctime.
If the TZ environment variable is defined, then its value overrides the default time zone, which is the U.S. Eastern time zone. The environment facility contains the format of the time zone information specified by TZ. TZ is usually set when the system is started with the value that is defined in either the /etc/environment or /etc/profile files. However, it can also be set by the user as a regular environment variable for performing alternate time zone conversions.
The tzset subroutine sets the timezone, daylight, and tzname external variables to reflect the setting of TZ. The tzset subroutine is called by ctime and localtime, and it can also be called explicitly by an application program.
The timezone external variable contains the difference, in seconds, between UTC and local standard time. For example, the value of timezone is 5 * 60 * 60 for U.S. Eastern Standard Time.
The daylight external variable is nonzero when a daylight-saving time conversion should be applied. By default, this conversion follows the standard U.S. conventions; other conventions can be specified. The default conversion algorithm adjusts for the peculiarities of U.S. daylight saving time in 1974 and 1975.
The tzname external variable contains the name of the standard time zone (tzname[0]) and of the time zone when Daylight Savings Time is in effect (tzname[1]). For example:
char *tzname[2] = {"EST", "EDT"};The time.h file contains declarations of all these subroutines and externals and the tm structure.
| Item | Description |
|---|---|
| Clock | Specifies the pointer to the time value in seconds. |
| Timeptr | Specifies the pointer to a tm structure. |
| Time1 | Specifies the pointer to a time_t structure. |
| Time0 | Specifies the pointer to a time_t structure. |
| Tm | Specifies the pointer to a tm structure. |
Attention: The return values point to static data that is overwritten by each call.
The tzset subroutine returns no value.
The mktime subroutine returns the specified time in seconds encoded as a value of type time_t. If the time cannot be represented, the function returns the value (time_t)-1.
The localtime and gmtime subroutines return a pointer to the struct tm.
The ctime and asctime subroutines return a pointer to a 26-character string.
The difftime subroutine returns the difference expressed in seconds as a value of type double.