CTIME(3C)

NAME

ctime, localtime, gmtime, mktime, difftime, asctime, timezone, daylight, tzname, tzset, nl_ctime, nl_cxtime, nl_asctime, nl_ascxtime − convert date and time to string

SYNOPSIS

#include <time.h>

char ∗ctime (timer)
const time_t ∗timer;

char ∗nl_cxtime (timer, format)
const time_t ∗timer;
const char ∗format;

char ∗nl_ctime (timer, format, langid)
const time_t ∗timer; const char ∗format;
int langid;

struct tm ∗localtime (timer)
const time_t ∗timer;

struct tm ∗gmtime (timer)
const time_t ∗timer;

double difftime (time1, time0)
time_t time1, time0;

time_t mktime (timeptr)
struct tm ∗timeptr;

char ∗asctime (timeptr)
const struct tm ∗timeptr;

char ∗nl_ascxtime (timeptr, format)
const struct tm ∗timeptr;
const char ∗format;

char ∗nl_asctime (timeptr, format, langid)
const struct tm ∗timeptr;
const char ∗format;
int langid;

void tzset ( )

extern time_t timezone;

extern int daylight;

extern char ∗tzname[2];

DESCRIPTION

Asctime converts the broken-down time contained in the structure pointed to by timeptr and returns 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.

Ctime converts the calendar time pointed to by timer, representing the time in seconds since the Epoch, and returns a pointer to the local time in the form of a string. It is equivalent to:

asctime(localtime(timer))

Localtime and gmtime return pointers to tm structures, described below. Localtime corrects 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). Gmtime converts directly to Coordinated Universal Time (UTC), which is the time the HP-UX system uses.

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

Mktime converts 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(2). 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 initially to 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. On 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.

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.

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, nl_ctime, nl_cxtime, asctime, nl_asctime, nl_ascxtime, and strftime(3C) call tzset and use the values returned in the external variables described below for their operations. Tzset may also be called directly by the user.

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 is non-zero only if you have specified a summer time zone adjustment in your 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.

Nl_cxtime extends the capabilities of ctime. The format specification allows the date and time to be output in a variety of ways. Format uses the field descriptors and field width and precision specifications defined in strftime(3C). If the format is the null string, the D_T_FMT string defined by langinfo(5) is used. Nl_cxtime is provided for historical reasons only; its use is not recommended.

Nl_ctime performs in a manner similar to nl_cxtime, but effectively first calls langinit (see nl_init(3C)) to load the program’s locale according to the language specified by langid. Nl_ctime also appends a newline to the formatted string. Nl_ctime is provided for historical reasons only; its use is not recommended.

Nl_ascxtime, like nl_cxtime, allows the date string to be formatted. However, like asctime, nl_asctime takes a pointer to a tm structure as its argument. Nl_ascxtime is provided for historical reasons only; its use is not recommended.

Nl_asctime performs like nl_ascxtime, but first calls langinit (see nl_init(3C)) to load the program’s locale according to the language specified by langid. Nl_asctime also appends a newline to the formatted string. Nl_asctime is provided for historical reasons only; its use is not recommended.

EXTERNAL INFLUENCES

Locale

The LC_TIME category determines for the functions nl_cxtime, nl_ctime, nl_ascxtime and nl_asctime the characters to be substituted for the directives described in strftime(3C) as being from the locale. It also determines the default output format used when a null format string is supplied to these functions.

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

Environment Variables

The function tzset 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, ctime, nl_ctime and nl_cxtime. Two methods for specifying a time zone within TZ are described in environ(5).

International Code Set Support

Single- and multi-byte character code sets are supported.

WARNINGS

The return values point to static data whose content is overwritten by each call.

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(2) 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 will force the value of the tm_sec component to the range [0,59].

The use of strftime(3C) is recommended in place of the ctime, nl_cxtime, nl_ctime, asctime, nl_ascxtime, and nl_asctime routines defined here.

AUTHOR

Ctime was developed by AT&T and HP.

STANDARDS CONFORMANCE

ctime: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

asctime: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

daylight: SVID2, XPG2, XPG3

difftime: ANSI C

gmtime: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

localtime: SVID2, XPG2, XPG3, POSIX.1, FIPS 151-1, ANSI C

mktime: XPG3, POSIX.1, FIPS 151-1, ANSI C

nl_ascxtime: XPG2

nl_cxtime: XPG2

timezone: XPG2, XPG3

tzname: XPG2, XPG3, POSIX.1, FIPS 151-1

tzset: XPG2, XPG3, POSIX.1, FIPS 151-1

Hewlett-Packard Company — HP-UX Release 7.0: Sept 1989

Museum

Related Articles