CTIME(3) BSD CTIME(3)
NAME
ctime, localtime, gmtime, asctime, strftime, timezone - convert date and
time to ASCII
SYNOPSIS
#include <time.h>
char *ctime(clock)
const time_t *clock;
struct tm *localtime(clock)
const time_t *clock;
struct tm *gmtime(clock)
const time_t *clock;
char *asctime(tm)
const struct tm *tm;
size_t strftime(s, maxsize, format, timeptr)
char *s;
size_t maxsize;
const char *format;
const struct tm *timeptr;
char *timezone(zone, dst)
DESCRIPTION
ctime returns a pointer to a 26-character string expressing the time
arrived at by adding *clock seconds to midnight, January 1, 1970. The
string has the following form:
Mon Oct 19 17:53:56 1987\n\0
All the fields have constant width.
localtime and gmtime return pointers to structures containing the
individual components of the time. localtime corrects for the time zone
and daylight savings time (if necessary); gmtime converts directly to GMT
(Greenwich Mean Time), which is the time BSD uses. asctime converts a
time from the structures to ASCII and returns a pointer to a 26-character
string.
The structure declaration from the include file is as follows:
struct tm {
int tm_sec; /* 0-59 seconds */
int tm_min; /* 0-59 minutes */
int tm_hour; /* 0-23 hour */
int tm_mday; /* 1-31 day of month */
int tm_mon; /* 0-11 month */
int tm_year; /* 0- year - 1900 */
int tm_wday; /* 0-6 day of week (Sunday = 0) */
int tm_yday; /* 0-365 day of year */
int tm_isdst; /* flag: daylight savings time in effect */
};
When local time is necessary, the program consults the system to
determine the time zone and whether the U.S.A. daylight savings time
adjustment is appropriate. The program understands some of the
peculiarities in time conversion over the past 10-20 years; if necessary,
this understanding can be extended.
strftime places characters into the array pointed to by s as controlled
by the string pointed to by format. The format must be a multibyte
character sequence, beginning and ending in its initial shift state. The
format string consists of zero or more conversion specifiers and ordinary
multibyte characters. A conversion specifier consists of a "%" character
followed by a character that determines the behavior of the conversion
specifier. All ordinary multibyte characters (including the terminating
null character) are copied unchanged into the array. If copying takes
place between objects that overlap, the behavior is undefined. No more
than maxsize characters are placed into the array. Each conversion
specifier is replaced by appropriate characters as described in the
following list. The appropriate characters are determined by the LC_TIME
category of the current locale and by the values contained in the
structure pointed to by timeptr. The entities indicated below replace
the conversion specifiers with which they're associated in the format:
%a The locale's abbreviated weekday name.
%A The locale's full weekday name.
%b The locale's abbreviated month name.
%B The locale's full month name.
%c The locale's appropriate date and time representations.
%d The day of the month as a decimal number (01-31).
%H The hour (24-hour clock) as a decimal number (00-23).
%I The hour (12-hour clock) as a decimal number (00-12).
%j The day of the year as a decimal number (001-366).
%m The month as a decimal number (01-12).
%M The minute as a decimal number (00-59).
%p The locale's equivalent of the AM/PM designations associated with a
12-hour clock.
%S The second as a decimal number (00-61).
%U The week number of the year (the first Sunday as the first day of
week 1) as a decimal number (00-53).
%w The weekday as a decimal number (0 (Sunday)-6).
%W The week number of the year (the first Monday as the first day of
week 1) as a decimal number (00-53).
%x The locale's appropriate date representation.
%X The locale's appropriate time representation.
%y The year without century as a decimal number (00-99).
%Y The year with century as a decimal number.
%Z The time zone name or abbreviation, or by no characters if no time
zone is determinable.
%% "%".
If the total number of resulting characters including the terminating
null character is not more than maxsize, strftime returns the number of
characters placed into the array pointed to by s not including the
terminating null character. Otherwise, strftime returns zero and the
contents of the array are indeterminate.
timezone returns the name of the time zone associated with its first
argument, which is measured in minutes westward from Greenwich. If the
second argument is 0, the standard zone name is used; otherwise, the
Daylight Savings Zone. If the required name does not appear in a table
built into the routine, the difference from GMT is produced; for example,
in Afghanistan
timezone(-(60*4+30), 0)
is appropriate because Afghanistan is four and a half hours ahead of GMT.
This call would produce the string GMT+4:30.
SEE ALSO
cc(1), gettimeofday(2), time(3)
NOTES
The return values point to static data whose content is overwritten by
each call. Other implementations also may make adjustments for
Australian, Eastern European, Middle European, or Western European
daylight savings time.
timezone is available automatically only to programs compiled with the
-A nansi
option (see cc(1)). All other programs must either contain the directive
#define timezone _bky_timezone
or be compiled with the option
-Dtimezone=_bky_timezone
Programs compiled with the
-A ansi
option must, in addition, contain the directive
#define _BSD_SOURCE before any #include directives.
Parts of this discussion are adapted from ANS X3.159-1989.