CTIME(3V)

NAME
ctime, asctime, dysize, gmtime, localtime, strftime, strptime, timegm, timelocal, tzset, tzsetwall - convert date and time

SYNOPSIS
#include <time.h>

char *ctime(clock)
time_t *clock;

char *asctime(tm)
struct tm *tm;

int dysize(y)
int y;

struct tm *gmtime(clock)
time_t *clock;

struct tm *localtime(clock)
time_t *clock;

int strftime(buf, bufsize, fmt, tm)
char *buf;
int bufsize;
char *fmt;
struct tm *tm;

char *strptime(buf, fmt, tm)
char *buf;
char *fmt;
struct tm *tm;

time_t timegm(tm)
struct tm *tm;

time_t timelocal(tm)
struct tm *tm;

void tzset()

void tzsetwall()

SYSTEM V SYNOPSIS

In addition to the routines above, the following variables are available:

extern long timezone;

extern int daylight;

extern char *tzname[2];

DESCRIPTION

ctime() converts a long integer, pointed to by clock, to a 26-character string of the form produced by asctime(). It first breaks down clock to a tm structure by calling localtime(), and then calls asctime() to convert that tm structure to a string.

asctime() converts a time value contained in a tm structure to a 26-character string of the form:

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

Each field has a constant width. asctime() returns a pointer to the string.

dysize() returns the number of days in the argument year, either 365 or 366. localtime() and gmtime() return pointers to structures containing the time, broken down into various components of that time represented in a particular time zone. localtime() breaks down a time specified by the value pointed to by the clock argument, correcting for the time zone and any time zone adjustments (such as Daylight Savings Time). Before doing so, localtime() calls tzset() (if tzset() has not been called in the current process). gmtime() breaks down a time specified by the value pointed to by the clock argument into GMT, which is the time the system uses.

strftime() converts a time value contained in the tm structure pointed to by tm to a character string in a format specified by fmt. The character string is placed into the array pointed to by buf, which is assumed to contain room for at least buflen characters. If the result contains no more than buflen characters, strftime() returns the number of characters produced (not including the terminating null character). Otherwise, it returns zero and the contents of the array are indeterminate. fmt is a character string that consists of field descriptors and text characters, reminiscent of printf(3V). Each field descriptor consists of a % character followd by another character that 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  day of week, using locale's abbreviated weekday names

    %A  day of week, using locale's full weekday names

    %b
    %h  month, using locale's abbreviated month names

    %B  month, using locale's full month names

    %c  date and time as %x %X

    %C  date and time, in locale's long-format date and time representation

    %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  hour (00-23)

    %I  hour (00-12)

    %j  day number of year (001-366)

    %k  hour (0-23; single digits are preceded by a blank)

    %l  hour (1-12; single digits are preceded by a blank)

    %m  month number (01-12)

    %M  minute (00-59)

    %n  same as \n

    %p  locale's equivalent of AM or PM, whichever is appropriate

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

    %R  time as %H:%M

    %S  seconds (00-59)

    %t  same as \t

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

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

    %w  day of week; Sunday is day 0

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

    %x  date, using locale's date format

    %X  time, using locale's time format

    %y  year within century (00-99)

    %Y  year, including century (fore example, 1988)

    %Z  time zone abbreviation

The difference between %U and %W lies in which day is counted as the first day of the week. Week number 01 is the first week with four or more January days in it.

strptime() converts the character string pointed to by buf to a time value, which is stored in the tm structure pointed to by tm, using the format specified by fmt. A pointer to the character following the last character in the string pointed to by buf is returned. fmt is a character string that consists of field descriptors and text characters, reminiscent of scanf(3v). Each field descriptor consists of a % character followd by another character that 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
    %A  day of week, using locale's weekday names; either the abbreviated or full name may be specified

    %b
    %B
    %h  month, using locale's month names; either the abbreviated or full name may be specified

    %c  date and time as %x %X

    %C  date and time, in locale's long-format date and time representation

    %d
    %e  day of month (1-31; leading zeroes are permitted but not required)

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

    %H
    %k  hour (0-23; leading zeroes are permitted but not required)

    %I
    %l  hour (0-12; leading zeroes are permitted but not required)

    %j  day number of year (001-366)

    %m  month number (1-12; leading zeroes are permitted but not required)

    %M  minute (0-59; leading zeroes are permitted but not required)

    %p  locale's equivalent of AM or PM

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

    %R  time as %H:%M

    %S  seconds (0-59; leading zeroes are permitted but not required)

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

    %x  date, using locale's date format

    %X  time, using locale's time format

    %y  year within century (0-99; leading zeroes are permitted but not required)

    %Y  year, including century (for example, 1988)

Case is ignored when matching items such as month or weekday names. The %M, %S, %y, and %Y fields are optional; if they would be matched by white space, the match is suppressed and the appropriate field of the tm structure pointed to by tm is left unchanged. If any of the format items %d, %e, %H, %k, %I, %l, %m, %M, %S, %y, or %Y are matched, but the string that matches them is followed by white space, all subsequent items in the format string are skipped up to white space or the end of the format. The net result is that, for example, the format %m/%d/%y can be matched by the string 12/31; the tm_mon and tm_mday fields of the tm structure pointed to by tm will be set to 11 and 31, respectively, while the tm_year field will be unchanged.

timelocal() and timegm() convert the time specified by the value pointed to by the tm argument to a time value that represents that time expressed as the number of seconds since Jan. 1, 1970, 00:00, Greenwich Mean Time. timelocal() converts a tm structure that represents local time, correcting for the time zone and any time zone adjustments (such as Daylight Savings Time). Before doing so, timelocal() calls tzset() (if tzset() has not been called in the current process). timegm() converts a tm structure that represents GMT.

tzset() uses the value of the environment variable TZ to set time conversion information used by localtime(). If TZ is absent from the environment, the an available approximation to local wall clock time is used by localtime(). If TZ appears in the environment but its value is a null string, Greenwich Mean Time is used; if TZ appears and begins with a slash, it is used as the absolute pathname of the tzfile-format (see tzfile(5)) file from which to read the time conversion information; if TZ appears and begins with a character other than a slash, it is used as a pathname relative to a system time conversion information directory.

tzsetwall() sets things up so that localtime() returns the best available approximation of local wall clock time.

Declarations of all the functions and externals, and the tm structure, are in the <time.h> header file. The structure (of type) tm structure includes the following fields:

    	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;		/* 1 if DST in effect */
    	char *tm_zone;	/* abbreviation of timezone name */
    	long tm_gmtoff;	/* offset from GMT in seconds */

tm_isdst is non-zero if Daylight Savings Time is in effect. tm_zone points to a string that is the name used for the local time zone at the time being converted. tm_gmtoff is the offset (in seconds) of the time represented from GMT, with positive values indicating East of Greenwich.

SYSTEM V DESCRIPTION

The external long variable timezone contains the difference, in seconds, between GMT and local standard time (in PST, timezone is 8*60*60). If this difference is not a constant, timezone will contain the value of the offset on January 1, 1970 at 00:00 GMT. Since this is not necessarily the same as the value at some particular time, the time in question should be converted to a tm structure using localtime() and the tm_gmtoff field of that structure should be used. The external variable daylight is non-zero if and only if Daylight Savings Time would be in effect within the current time zone at some time; it does not indicate whether Daylight Savings Time is currently in effect.

The external variable tzname is an array of two char * pointers. The first pointer points to a character string that is the name of the current time zone when Daylight Savings Time is not in effect; the second one, if Daylight Savings Time conversion should be applied, points to a character string that is the name of the current time zone when Daylight Savings Time is in effect. These strings are updated by localtime() whenever a time is converted. If Daylight Savings Time is in effect at the time being converted, the second pointer is set to point to the name of the current time zone at that time, otherwise the first pointer is so set.

timezone, daylight, and tzname are retained for compatibility with existing programs.

FILES
/usr/share/lib/zoneinfo
    standard time conversion information directory
/usr/share/lib/zoneinfo/localtime
    local time zone file

SEE ALSO
gettimeofday(2), getenv(3V), time(3V), environ(5V), tzfile(5)

BUGS
The return values point to static data, whose contents are overwritten by each call. The tm_zone field of a returned tm structure points to a static array of characters, which will also be overwritten at the next call (and by calls to tzset() or tzsetwall()).