ctime, asctime, localtime, gmtime, mktime, strftime, tzset - convert date and time to ASCII

---

SYNOPSIS

#include <time.h>

char *ctime(const time_t *timer);

char *asctime(const struct tm *timeptr);

struct tm *localtime(const time_t *timer);

struct tm *gmtime(const time_t *timer);

char *timezone(ing zone, int dst);

time_t mktime(struct tm *timeptr);

size_t strftime(char *s, size_t maxsize, const char *format, const struct tm *timeptr);

void tzset(void);

extern char *tzname[2];

DESCRIPTION

If TZ does not appear in the environment, the TZDEFAULT file (as defined in tzfile.h) is used. If this file fails for any reason, the Greenwich Mean Time (GMT) offset as provided by the kernel is used. In this case, DST is ignored, resulting in the time being incorrect by some amount if DST is currently in effect. If this fails for any reason, GMT is used.

If TZ appears in the environment but its value is a null string, GMT is used; if TZ appears and begins with a slash, it is used as the absolute pathname of the tzfile(5)-format file from which to read the time conversion information; if TZ appears and begins with a character other than a slash, it's used as a pathname relative to the system time conversion information directory, defined as TZDIR in the include file tzfile.h. If this file fails for any reason, GMT is used.

Programs that always wish to use local wall clock time should explicitly remove the environmental variable TZ with unsetenv(3).

Ctime converts the calendar time pointed to by timer, such as returned by time(2) into ASCII and returns a pointer to a 26-character string in the following form (all the fields have constant width):

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

Asctime converts the broken-down time in the structure pointed to by timeptr into a string as returned by ctime.

Localtime and gmtime return pointers to structures containing the broken-down time. Localtime corrects for the time zone and possible daylight savings time; gmtime converts directly to GMT, which is the time UNIX uses.

The tm structure declaration from the <time.h> file is:

struct tm {
	int tm_sec;	/* seconds after the minute (0-59) */
	int tm_min;	/* minutes after the hour (0-59) */
	int tm_hour;	/* hours since midnight (0-23) */
	int tm_mday;	/* day of the month (1-31) */
	int tm_mon;	/* months since January (0-11) */
	int tm_year;	/* years since 1900 */
	int tm_wday;	/* days since Sunday (0-6) */
	int tm_yday;	/* days since Jan. 1 (0-365) */
	int tm_isdst;	/* flag; daylight savings time in effect */
	long tm_gmtoff;	/* offset from GMT in seconds */
	char *tm_zone;	/* abbreviation of timezone name */
};

Tm_isdst is non-zero if a time zone adjustment such as Daylight Savings time is in effect.

Tm_gmtoff is the offset (in seconds) of the time represented from GMT, with positive values indicating East of Greenwich.

Timezone remains for compatibility reasons only; it's impossible to reliably map timezone's arguments (zone, a ``minutes west of GMT'' value and dst, a ``daylight saving time in effect'' flag) to a time zone abbreviation.

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(3). The original values of the tm structure members tm_wday and tm_yday are ignored. On successful completion of mktime these values are set appropriately. The values for the tm_year, tm_mon, tm_mday, tm_hour, tm_min, and tm_sec may be outside the ranges described above and will be adjusted appropriately to reflect the correct time. For example, if tm_year is set to 1980 and tm_mon is set to -2 the return value would reflect November 1979.

Strftime places characters into the array pointed to by s as controlled by the string pointed to by format. The format string consists of zero or more conversion specifiers and ordinary characters. A conversion specifier consists of a % character followed by a character that determines the behavior of the conversion specifier. All ordinary characters (including the terminating null character) are copied unchanged into the array. Each conversion specifier is replaced by appropriate characters as described in the following list. The appropriate characters are determined by the values contained in the structure pointed to by timeptr. Below is a list of conversion specifiers:

%%

identical to %

%a

abbreviated weekday name

%A

full weekday name

%b

abbreviated month name

%B

full month name

%c

time and date using the time and date representation for the locale (%X %x)

%d

day of the month as a decimal number (01-31)

%H

hour based on a 24-hour clock as a decimal number (00-23)

%I

hour based on a 12-hour clock as a decimal number (01-12)

%j

day of the year as a decimal number (001-366)

%m

month as a decimal number (01-12)

%M

minute as a decimal number (00-59)

%p

AM/PM designation associated with a 12-hour clock

%S

second as a decimal number (00-61)

%w

weekday as a decimal number (0-6), where Sunday is 0

%x

date using the date representation for the locale

%X

time using the time representation for the locale

%y

year without century (00-99)

%Y

year with century (e.g. 1990)

%Z

time zone name or abbreviation, or no characters if no time zone is determinable.

RETURN VALUE

Asctime returns a pointer to a string.

Localtime returns a pointer to a tm structure.

Gmtime returns a pointer to a tm structure, or a null pointer if GMT is not available.

Mktime returns the specified calendar time encoded as a value of type time_t. If the calendar time cannot be represented, the value (time_t)-1 is returned.

Strftime returns the number of characters placed into the array pointed to by s not including the terminating null character if the total number of resulting characters including the terminating null character is not more than maxsize. Otherwise, zero is returned.

NOTE

SEE ALSO

Created by unroff & hp-tools. © somebody (See intro for details). All Rights Reserved. Last modified 11/5/97