CTIME(3)CTIME(3)NAME
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
Tzset uses the value of the environment variable TZ to set up the time
conversion information used by localtime, ctime, strftime and mktime.
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
Ctime returns the pointer returned by asctime with that broken-down
time as argument.
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
The return values point to static data whose content is overwritten by
each call. The tm_zone field of a returned struct tm points to a
static array of characters, which will also be overwritten at the next
call (and by calls to tzset).
SEE ALSOgettimeofday(2), getenv(3), time(3), tzfile(5), environ(7)4th Berkeley Distribution August 1, 1992 CTIME(3)