ctime(3C)

NAME

ctime(), ctime_r(), asctime(), asctime_r(), daylight(), difftime(), gmtime(), gmtime_r(), localtime(), localtime_r(), mktime(), timezone(), tzname(), tzset() — convert date and time to string

SYNOPSIS

#include <time.h>

char *asctime(const struct tm *timeptr);

char *asctime_r(const struct tm *timeptr, char *buffer);

char *ctime(const time_t *timer);

char *ctime_r(const time_t *timer, char *buffer);

double difftime(time_t time1, time_t time0);

struct tm *gmtime(const time_t *timer);

struct tm *gmtime_r(const time_t *timer, struct tm *result);

struct tm *localtime(const time_t *timer);

struct tm *localtime_r(const time_t *timer, struct tm *result);

time_t mktime(struct tm *timeptr);

extern long timezone;

extern int daylight;

extern char *tzname[2];

void tzset(void);

DESCRIPTION

asctime()

Convert the broken-down time contained in the structure pointed to by timeptr and return a pointer to a 26-character string in the form:

Sun Sep 16 01:03:52 1973\n\0

All the fields have constant width.

asctime() returns NULL and sets errno to ERANGE if tm_year in timeptr is less than 0 or is greater than 8099. In both 32-bit and 64-bit HP-UX, the minimum date supported by asctime() is January 1 00:00:00 1900 and the maximum date supported by asctime() is December 31 23:59:59 9999.

asctime_r()

is identical to asctime(), except that it places the result in the user supplied buffer and returns a pointer to buffer upon success. A buffer length of at least 26 is required.

ctime()

Convert the calendar time pointed to by timer, representing the time in seconds since the Epoch, and return a pointer to the local time in the form of a string. Equivalent to:

asctime(localtime(timer))

The minimum date supported by ctime() in both 32-bit and 64-bit HP-UX is Friday December 13 20:45:52 UTC 1901. The maximum dates supported by ctime() are Tuesday January 19 03:14:07 UTC 2038 and Friday December 31 23:59:59 UTC 9999 in 32-bit HP-UX and 64-bit HP-UX, respectively.

In 64-bit HP-UX, ctime() returns NULL and sets errno to ERANGE if timer is less than the number of seconds that corresponds to the minimum date supported (i.e., INT_MIN, as defined in limits.h), or exceeds the number of seconds that corresponds to the maximum date supported.

ctime_r()

is identical to ctime(), except that it places the result in the user supplied buffer and returns a pointer to buffer upon success. A buffer length of at least 26 is required.

difftime()

Return the difference in seconds between two calendar times: time1 - time0.

gmtime()

Convert directly to Coordinated Universal Time (UTC), the time standard used by the HP-UX operating system. gmtime() returns a pointer to the tm structure described below.

The minimum date supported by gmtime() in both 32-bit and 64-bit HP-UX is Friday December 13 20:45:52 UTC 1901. The maximum dates supported by gmtime() are Tuesday January 19 03:14:07 UTC 2038 and Friday December 31 23:59:59 UTC 9999 in 32-bit HP-UX and 64-bit HP-UX, respectively.

In 64-bit HP-UX, gmtime() returns NULL and sets errno to ERANGE if timer is less than the number of seconds that corresponds to the minimum date supported (i.e., INT_MIN, as defined in limits.h), or exceeds the number of seconds that corresponds to the maximum date supported.

gmtime_r()

is identical to gmtime(), except that gmtime_r() stores the result in the tm struct pointed to by result and returns result upon success.

localtime()

Correct for the time zone and any summer time zone adjustments (such as Daylight Savings Time in the USA), according to the contents of the TZ environment variable (see Environment Variables below). localtime() returns a pointer to the tm structure described below.

The minimum date supported by localtime() in both 32-bit and 64-bit HP-UX is Friday December 13 20:45:52 UTC 1901. The maximum dates supported by localtime() are Tuesday January 19 03:14:07 UTC 2038 and Friday December 31 23:59:59 UTC 9999 in 32-bit HP-UX and 64-bit HP-UX, respectively.

In 64-bit HP-UX, localtime() returns NULL and sets errno to ERANGE if timer is less than the number of seconds that corresponds to the minimum date supported (i.e., INT_MIN, as defined in limits.h), or exceeds the number of seconds that corresponds to the maximum date supported.

localtime_r()

is identical to localtime(), except that localtime_r() stores the result in the tm struct pointed to by result and returns result upon success.

mktime()

Convert the broken-down time (expressed as local time) in the structure pointed to by timeptr into a calendar time value with the same encoding as that of the values returned by time(). The original values of the tm_wday and tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated below.

A positive or zero value for tm_isdst causes mktime() to initially presume that Daylight Saving Time respectively is or is not in effect for the specified time. A negative value for tm_isdst causes mktime() to attempt to determine whether Daylight Saving Time is in effect for the specified time.

Upon successful completion, all the components are set to represent the specified calendar time, but with their values forced to the ranges indicated below. The final value of tm_mday is not set until tm_mon and tm_year are determined. mktime() returns the specified calendar time encoded as a value of type time_t.

If the calendar time cannot be represented, the function returns the value (time_t)—1 and sets errno to ERANGE. Note the value (time_t)—1 also corresponds to the time 23:59:59 on Dec 31, 1969 (plus or minus time zone and Daylight Saving Time adjustments). Thus it is necessary to check both the return value and errno to reliably detect an error condition.

tzset()

Sets the values of the external variables timezone, daylight, and tzname according to the contents of the TZ environment variable (independent of any time value). The functions localtime(), mktime(), ctime(), asctime(), and strftime() (see strftime(3C)) call tzset() and use the values returned in the external variables described below for their operations. tzset() can also be called directly by the user.

When the environment variable TZ is not set, tzset() checks the default file /etc/default/tz for the timezone value and sets timezone values based on that. The file /etc/default/tz contains the timezone value used by tzset() when the environment variable TZ is not set. The format for the file is same as TZ format without the prefix TZ=. Please check environ(5) for TZ format.

If the value of the timezone cannot be determined using the environment variable TZ or the file /etc/default/tz, it is set to the default value of EST5EDT. If the timezone is set to the default value of EST5EDT and the timezone adjustment file is not available, the timezone is set to a default value of UTC (Coordinated Universal Time).

/etc/default/tz can be modified for an appropriate default value for timezone.

The <time.h> header file contains declarations of all relevant functions and externals. It also contains the tm structure, which includes the following members:

int tm_sec;      /* seconds after the minute - [0,61] */
int tm_min;      /* minutes after the hour - [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;     /* years since 1900 */
int tm_wday;     /* days since Sunday - [0,6] */
int tm_yday;     /* days since January 1 - [0,365] */
int tm_isdst;    /* daylight savings time flag */

The value of tm_isdst is positive if a summer time zone adjustment such as Daylight Savings Time is in effect, zero if not in effect, and negative if the information is not available.

The external variable timezone contains the difference, in seconds, between UTC and local standard time (for example, in the U.S. Eastern time zone (EST), timezone is 5*60*60). The external variable daylight is non-zero only if a summer time zone adjustment is specified in the TZ environment variable. The external variable tzname[2] contains the local standard and local summer time zone abbreviations as specified by the TZ environment variable.

EXTERNAL INFLUENCES

Locale

The LC_CTYPE category determines the interpretation of the bytes within format as single and/or multi-byte characters.

Environment Variables

The tzset() function uses the contents of TZ to set the values of the external variables timezone, daylight, and tzname. TZ also determines the time zone name substituted for the %Z and %z directives and the time zone adjustments performed by localtime(), mktime(), and ctime(). Two methods for specifying a time zone within TZ are described in environ(5).

International Code Set Support

Single and multibyte character code sets are supported.

RETURN VALUE

For asctime_r() and ctime_r(), if the buffer is of insufficient length, a NULL is returned and errno set to EINVAL.

asctime_r(), ctime_r(), gmtime_r(), and localtime_r() return a NULL and set errno to EINVAL if NULL pointers are passed in as arguments.

A NULL is returned and errno is set to ERANGE if the input to the following routines is not within the supported range: asctime(), asctime_r(), ctime(), ctime_r(), gmtime(), gmtime_r(), localtime(), localtime_r().

APPLICATION USAGE

The return values for asctime(), ctime(), gmtime(), and localtime() point to static data whose contents is overwritten by each call.

WARNINGS

Users of asctime_r(), ctime_r(), gmtime_r(), and localtime_r() should also note that these functions now conform to POSIX.1c. The old prototypes of these functions are supported for compatibility with existing DCE applications only.

The range of tm_sec([0,61]) extends to 61 to allow for the occasional one or two leap seconds. However, the ``seconds since the Epoch'' value returned by time() and passed as the timer argument does not include accumulated leap seconds. The tm structure generated by localtime() and gmtime() will never reflect any leap seconds. Upon successful completion, mktime() forces the value of the tm_sec component to the range [0,59].

AUTHOR

ctime() was developed by AT&T and HP.

STANDARDS CONFORMANCE

ctime(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

asctime(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

daylight: AES, SVID2, SVID3, XPG2, XPG3, XPG4

difftime(): AES, SVID3, XPG4, ANSI C

gmtime(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

localtime(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

mktime(): AES, SVID3, XPG3, XPG4, FIPS 151-2, POSIX.1, ANSI C

timezone: AES, SVID3, XPG2, XPG3, XPG4

tzname: AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

tzset(): AES, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1

asctime_r(), ctime_r(), localtime_r(), gmtime_r(): POSIX.1c