ctime(3P) INTERACTIVE UNIX System (POSIX) ctime(3P)
NAME
ctime, localtime, gmtime, asctime, strftime; tzset - convert
date and time to string
SYNOPSIS
#include <sys/types.h>
#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;
strftime (s, maxsize, format, tm);
char *s;
size_t maxsize;
char *format;
struct tm *tm;
void tzset ();
extern char *tzname[2];
extern long timezone;
extern long altzone;
extern long daylight;
DESCRIPTION
The ctime, localtime, and gmtime fuctions accept arguments
of type time_t (declared in <sys/types.h>), pointed to by
clock, representing the time in seconds since 00:00:00
Greenwich Mean Time (GMT), January 1, 1970. The ctime func-
tion returns a pointer to a 26-character string in the fol-
lowing form. All the fields have constant width:
Fri Sep 13 00:00:00 1986\n\0
The localtime and gmtime functions return pointers to tm
structures, described below. The localtime function
corrects for the main time zone and possible alternate (Day-
light Saving) time zone; gmtime converts directly to GMT,
which is the time the UNIX System uses.
The asctime function converts a tm structure to a 26-
character string, as shown in the above example, and returns
a pointer to the string.
Rev. 1.1 Page 1
ctime(3P) INTERACTIVE UNIX System (POSIX) ctime(3P)
Declarations of all the functions and externals, and the tm
structure, are in the <time.h> header file. The structure
declaration is:
struct tm {
int tm_sec; /* seconds after the minute-[0,59] */
int tm_min; /* minutes after the hour-[0,59] */
int tm_hour;/* hour since midnight-[0,23] */
int tm_mday;/* day of the month-[1,31] */
int tm_mon; /* months since January-[0,12] */
int tm_year;/* years since 1900 */
int tm_wday;/* days since Sunday-[0,6] */
int tm_yday;/* days since January 1-[0,365] */
int tm_isdst;/* flag for Daylight Saving Time */
};
tm_isdst is nonzero if the alternate time zone is in effect.
The strftime function 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 conver-
sion 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. 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:
%a is replaced by the locale's abbreviated weekday name.
%A is replaced by the locale's full weekday name.
%b is replaced by the locale's abbreviated month name.
%B is replaced by the locale's full month name.
%c is replaced by the locale's appropriate date and time representation.
%d is replaced by the day of the month as a decimal number (0-31).
%H is replaced by the hour (24-hour clock) as a decimal number (00-23).
%I is replaced by the hour (12-hour clock) as a decimal number (00-12).
%j is replaced by the day of the year as a decimal number (001-366).
%m is replaced by the month as a decimal number (01-12).
%M is replaced by the minute as a decimal number (00-59).
%p is replaced by the locale's equivalent of the AM/PM designations
associated with a 12-hour clock.
%S is replaced by the second as a decimal number (00-61).
%U is replaced by the week number of the year (the first Sunday as the
first day of week 1) as a decimal number (00-53).
%w is replaced by the weekday as a decimal number [0 (Sunday)-6].
%W is replaced by the week number of the year (the first Monday as
the first day of week 1) as a decimal number (00-53).
%x is replaced by the locale's appropriate date representation.
Rev. 1.1 Page 2
ctime(3P) INTERACTIVE UNIX System (POSIX) ctime(3P)
%X is replaced by the locale's appropriate time representation.
%y is replaced by the year without century as a decimal number (00-99).
%Y is replaced by the year with century as a decimal number.
%Z is replaced by the time zone name or abbreviation, or by no
characters if no time zone is determinable.
%% is replaced by %.
If a conversion specifier is not one of the above, the
behavior is undefined.
RETURN VALUE
If the total number of resulting characters including the
terminating null character is not more than maxsize, the
strftime function returns the number of characters placed
into the array pointed to by s not including the terminating
null character. Otherwise, zero is returned and the con-
tents of the array are indeterminate.
The external long variable timezone contains the difference,
in seconds, between GMT and the main time zone; the external
long variable altzone contains the difference, in seconds,
between GMT and the alternate time zone; 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 contents of the environment variable named TZ is used by
the functions ctime(), localtime(), strftime(), and mktime()
to override the default time zone. The value of TZ must be
in either of two formats (spaces inserted for clarity):
:std offset [dst [offset] [,rule]]
or:
std offset [dst [offset] [,rule]]
where:
std and dst
Three or more bytes that are the designation for the
standard (std) or summer (dst) time zone. Only std is
required; if dst is missing, then summer time does not
apply in this locale. Uppercase and lowercase letters
are explicitly allowed. Any characters except a lead-
ing colon (:), digits, comma (,), minus (-), plus (+),
and ASCII NUL are allowed.
offset
Indicates the value one must add to the local time to
Rev. 1.1 Page 3
ctime(3P) INTERACTIVE UNIX System (POSIX) ctime(3P)
arrive at GMT. The offset has the form:
hh[:mm[:ss]]
The minutes (mm) and seconds (ss) are optional. The
hour (hh) shall be required and may be a single digit.
The offset following std shall be required. If no
offset follows dst, summer time is assumed to be one
hour ahead of standard time. One or more digits may be
used; the value is always interpreted as a decimal
number. The hour shall be between zero and 24, and the
minutes (and seconds)-if present-between zero and 59.
Out of range values may cause unpredictable behavior.
If preceded by a -, the time zone shall be east of the
Prime Meridian; otherwise it shall be west (which may
be indicated by an optional preceding +).
rule Indicates when to change to and back from summer time.
The rule has the following form if the TZ string
started with a colon (:):
[;ordinal-start[/time];ordinal-end[/time]]
and otherwise:
[,start[/time],end[/time]]
where start and ordinal-start define the date when the
change from standard to summer time occurs, and end and
ordinal-end define the date when the change back hap-
pens. In either case, the time is when, in local time,
the change is made.
The format of date shall be one of the following:
ordinal-start
ordinal-end
The ordinal day number (1 n 366). Leap days are
counted.
Jn The Julian day n (1 < n < 365). Leap days shall
not be counted. That is, in all years-including
leap years-February 28 is day 59 and March 1 is
day 60. It is impossible to explicitly refer to
the occasional February 29.
n The zero-based Julian day (0 < d < 365). Leap
days shall be counted, and it is possible to refer
to February 29.
Mm.n.d
The dth day of the nth week of the mth month of
the year. The month must be between 1 and 12, the
Rev. 1.1 Page 4
ctime(3P) INTERACTIVE UNIX System (POSIX) ctime(3P)
week between 1 and 5, and the day between 0 and 6
(0=Sunday). Week n is the nth week of the month
in which day d occurs. Week 5 always means ``the
last week in the month this day occurs,'' even if
there are only 4 weeks in the month. This format
makes it easy to specify, for example, ``the first
Sunday in May'' as M5.1.0.
Whenever ctime(), strftime(), mktime(), or localtime() is
called, the time zone names contained in the external vari-
able tzname shall be set as if the tzset() function has been
called.
Applications are explicitly allowed to change TZ and have
the changed TZ apply to them.
The following settings for the TZ environment variable would
result in the same start and end times for Daylight Saving
Time for the year 1988:
PST8PDT
:PST8:00PDT;093;303
PST8PDT7:00:00,J092;J302
PST8PDT7,M4.1.0/02:00,M10.5.0/02:00
The last format shown above is the format used if no start-
ing date or ending date is given., i.e., the first Sunday in
April at 2:00 a.m. and the last Sunday in October at 2:00
a.m.
The functions know about the peculiarities of this conver-
sion for various time periods for the U.S.A (specifically,
the years 1974, 1975, and 1987). The functions will handle
the new Daylight Saving Time starting with the first Sunday
in April, 1987.
A setting for the southern hemisphere, such as the Cook
Islands, could be:
"KDT9:30KST10,63/5:00,302/20:00"
This means that Standard time starts on the 63rd day at 5:00
a.m. and is 10 hours later than GMT. Daylight Saving Time
starts on the 302nd day at 8:00 p.m. and is 30 minutes ear-
lier.
The tzset function is used to compute these dates and times;
it is called by localtime and may also be called explicitly
by the user. The function sets the tzname array, the day-
light, the timezone, and the altzone variables.
SEE ALSO
getenv(3C), putenv(3C), profile(4), timezone(4),
environ(5P).
Rev. 1.1 Page 5
ctime(3P) INTERACTIVE UNIX System (POSIX) ctime(3P)
WARNING
The return values for ctime, localtime, and gmtime point to
static data whose content is overwritten by each call.
Rev. 1.1 Page 6