ctime(3C)

NAME

ctime, localtime, gmtime, asctime, strftime, cftime, ascftime, mktime, tzset − convert date and time to string

SYNOPSIS

#include <time.h>

char ∗ctime (clock)
time_t ∗clock;

struct tm ∗localtime (clock)
time_t ∗clock;

struct tm ∗gmtime (clock)
time_t ∗clock;

char ∗asctime (tm)
struct tm ∗tm;

size_t strftime(buf, size, fmt, tm)
char ∗buf, ∗fmt;
int size;
struct tm ∗tm;

int cftime(buf, fmt, clock)
char ∗buf, ∗fmt;
time_t ∗clock;

int ascftime (buf, fmt, tm)
char ∗buf, ∗fmt;
struct tm ∗tm;

time_t mktime (timeptr)
struct tm ∗timeptr;

extern time_t timezone, altzone;

extern int daylight;

extern char ∗tzname[2];

void tzset ( )

DESCRIPTION

ctime, localtime, and gmtime accept arguments of type time_t pointed to by clock, representing the time in seconds since 00:00:00 GMT, January 1, 1970. ctime returns a pointer to a 26-character string in the following form:

Fri Sep 13 00:00:00 1986\n\0

Time zone and daylight savings corrections are made before the string is generated. The fields are constant in width.

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 converts directly to Greenwich Mean Time (GMT), also known as Coordinated Universal Time (UTC), which is the time the UNIX system uses internally.

asctime converts a tm structure to a 26-character string, as shown in the above example, and returns a pointer to the string.

strftime and ascftime provide the capabilities of asctime in addition to providing control over the format of the resulting string. cftime does the same with the capabilities of ctime. strftime and ascftime take a pointer to a tm structure and convert it to a character string. cftime takes a calendar time of type time_t pointed to by clock and converts it to a character string. In both functions, the characters are placed into the array pointed to by buf (plus a terminating \0) and the value returned is the number of such characters (not counting the terminating \0). For strftime, no more than size characters are placed into the array. fmt controls the format of the resulting string.

mktime converts the time represented by the tm structure pointed to by timeptr into a time_t type calendar time. In addition to computing the calendar time, mktime normalizes the supplied tm structure.

Declarations of all the functions and externals, and the tm structure, are in the <time.h> header file. The structure declaration is:

structtm {

inttm_sec;/∗ seconds after the minute — [0, 59] ∗/
inttm_min;/∗ minutes after the hour — [0, 59] ∗/
inttm_hour;/∗ hour since midnight — [0, 23] ∗/
inttm_mday;/∗ day of the month — [1, 31] ∗/
inttm_mon;/∗ months since January — [0, 11] ∗/
inttm_year;/∗ years since 1900 ∗/
inttm_wday;/∗ days since Sunday — [0, 6] ∗/
inttm_yday;/∗ days since January 1 — [0, 365] ∗/
inttm_isdst;/∗ flag for daylight savings time ∗/
longtm_gmtoff;/∗ offset (seconds) from Greenwich (BSD)∗/

char∗tm_zone;/∗ Ascii time zone name (BSD)∗/

};

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 the alternate time zone was in effect.)

Normalized tm Structure

mktime ignores the original values of the tm_wday and tm_yday components of the structure, and the original values of the other components are not restricted to the ranges indicated by the definition of the structure. On successful completion, the values of the tm_wday and tm_yday components are set appropriately, and the other components are set to represent the specified calendar time, but with their values forced to be within the appropriate ranges. The final value of tm_mday is not set until tm_mon and tm_year are determined.

mktime returns the specified calendar time. If the calendar time cannot be represented, the function returns the value ((time_t)(−1)).

The original values of the components may be either greater than or less than the specified range. For example, a tm_hour or −1 means 1 hour before midnight, tm_mday of 0 means the day preceding the current month, and tm_mon or −2 means 2 months before January of tm_year.

Note that times before GMT Dec 13 20:45:52 1901 or after GMT Jan 19 03:14:07 2038 cannot be represented in a time_t value. Note also that the value returned on error, ((time_t)−1), corresponds to GMT Dec 31 23:59:59 1969 and so that value is also considered to be outside the valid range of mktime. The total time represented by tm_sec, tm_min, tm_hour, or tm_mday should not exceed the number of seconds in December or January for the first years and last years representable in time_t values. tm_year should be for year 1970 or later.

If tm_isdst is positive, the original values are assumed to be in the alternate time zone. If it turns out that the alternate time zone is not valid for the computed calendar time, then the components are adjusted to be in the main time zone. Likewise, if tm_isdst is zero, the original values are assumed to be in the main time zone and are converted to the alternate time zone if the the main time zone is not valid. If tm_isdst is negative, the correct time zone is determined and the components are not adjusted. Local time zone information is used as if mktime had called tzset.

Controlling the Output Format

strftime, ascftime, and cftime place characters into the buf array as controlled by the string pointed to by fmt. fmt is a character string that consists of field descriptors and text characters, reminiscent of printf(3S). Each field descriptor consists of a % character followed by another character which specifies the replacement for the field descriptor. All other characters are copied from fmt into the result. The following field descriptors are supported:

%% same as %

%a abbreviated weekday name

%A full weekday name

%b abbreviated month name

%B full month name

%c default date and time representation

%C default date and time representation as produced by date(1)

%d day of month ( 01 - 31 )

%D date as %m/%d/%y

%e day of month (1-31; single digits are preceded by a blank)

%h abbreviated month name

%H hour ( 00 - 23 )

%I hour ( 00 - 12 )

%j day number of year ( 001 - 366 )

%m month number ( 01 - 12 )

%M minute ( 00 - 59 )

%n same as \n

%p ante meridian or post meridian

%r time as %I:%M:%S %p

%R time as %H:%M

%S seconds ( 00 - 61 )

%t insert a tab

%T time as %H:%M:%S

%U week number of year ( 01 - 53 ), Sunday is the first day of week 1

%w weekday number ( Sunday = 0 )

%W week number of year ( 01 - 53 ), Monday is the first day of week 1

%x Local specific date format

%X Local specific time format

%y year within century ( 00 - 99 )

%Y year as ccyy ( e.g. 1986)

%Z time zone name

The difference between %U and %W lies in which day is counted as the first of the week. In programs linked in one of the ANSI C compilation modes (see hc(1)), and in programs linked in the 88open OCS-compliant mode, week number 01 is the week with the first January Sunday (%U) or Monday (%W) in it. Otherwise, week number 01 is the first week with four or more January days in it.

The example below shows what the string in buf would look like if the values in the tm structure corresponded to Thursday, August 28, 1986 at 12:44:36 in New Jersey.

strftime (buf, strsize, "%A %m %d %j", tm)

This example would result in the buffer containing “Thursday Aug 28 240”.

If fmt is (char ∗)0, then the locale’s default format is used. For strftime, the default format is the same as “%c”, for cftime and ascftime the default format is the same as “%C”. cftime and ascftime first try to use the value of the environment variable CFTIME, and if that is undefined or empty the default format is used. Under 88open OCS-compliant mode, the default representation for strftime in the “C” locale is a concatenation of the %x and %X representations. Otherwise, it is the same as that returned by ctime.

Each directive, including the default format string, is replaced by appropriate characters determined by the LC_TIME category of the then current locale and by the time information passed as parameters. See below for details on changing the current language and strftime(4) for a description of the structure of these files.

Selecting the Output Language

The user can request that the output of strftime, ascftime, and cftime be in a specific language by setting the LC_TIME category of the current locale with the setlocale(3C) function. In the default “C” locale, the strings are appropriate for U.S. English.

Time Zone

The external time_t variable timezone contains the difference, in seconds, between GMT and the local standard time; the external time_t variable altzone contains the difference, in seconds, between GMT and the alternate time zone. The external variable daylight indicates whether time should reflect daylight savings time. Both timezone and altzone default to 0 (GMT). 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", " " };

The functions know about the peculiarities of this conversion for various time periods for the U.S.A (specifically, the years 1974, 1975, and 1987). They will 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 environ(5) for a description of the TZ environment variable.

tzset is called by localtime, ctime, strftime, and mktime and may also be called explicitly by the user. It scans the contents of the environment variable and assigns the different fields to the respective variable. For example, the setting for New Jersey in 1986 could be

EST5EDT4;116/2:00:00,298/2:00:00

or simply

EST5EDT

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 will be set to 5∗60∗60, tzname[1] is EDT, altzone will be 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 will be set positive. Starting and ending times are relative to the alternate 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 midnight. The effects of tzset are thus to change the values of the external variables timezone, altzone, daylight, and tzname.

If the string in the TZ variable begins with a “:”, it is treated as the pathname of a compiled time zone information file [see zic(1M)]. If the name does not begin with a “/”, it is sought relative to the directory /usr/lib/locale/TZ.

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(4) and timezone(4)].

FILES

/usr/lib/locale/locale/LC_TIME
file that contains the locale specific date and time information

/usr/lib/locale/TZ directory of compiled time zone data files

NOTES

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

strftime is the preferred method for formatting the date and time string. ascftime and cftime are obsolete and are provided only for compatibility with previous releases.

Format specifiers %C, %D, %e, %h, %n, %r, %R, %t, and %T are extensions to the ANSI C standard.

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.

Berkeley has dropped support for the function timezone so Harris has followed suit. Programs which use the obsolete function timezone should use tm_zone instead.

CX/UX Programmer’s Reference Manual

Museum

Related Articles