ctime(3C) ctime(3C)
NAME
ctime, localtime, gmtime, asctime, strftime, cftime, ascf-
time, mktime, tzset - convert date and time to string
SYNOPSIS
#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;
size_t strftime(buf, size, fmt, tm)
char *buf, *fmt;
int size;
struct tm *tm;
int cftime(buf, fmt, clock)
char *buf, *fmt;
time_t *clock;
int ascftime (buf, fmt, tm)
char *buf, *fmt;
struct tm *tm;
time_t mktime (timeptr)
struct tm *timeptr;
extern time_t timezone, altzone;
extern int daylight;
extern char *tzname[2];
void tzset ( )
DESCRIPTION
ctime, localtime, and gmtime accept arguments of type time_t
pointed to by clock, representing the time in seconds since
00:00:00 GMT, January 1, 1970. ctime returns a pointer to a
26-character string in the following form:
Fri Sep 13 00:00:00 1986\n\0
Page 1 CX/UX Programmer's Reference Manual
ctime(3C) ctime(3C)
Time zone and daylight savings corrections are made before
the string is generated. The fields are constant in width.
localtime and gmtime return pointers to tm structures,
described below. localtime corrects for the main time zone
and possible alternate (``daylight savings'') time zone;
gmtime converts directly to Greenwich Mean Time (GMT), also
known as Coordinated Universal Time (UTC), which is the time
the UNIX system uses internally.
asctime converts a tm structure to a 26-character string, as
shown in the above example, and returns a pointer to the
string.
strftime and ascftime provide the capabilities of asctime in
addition to providing control over the format of the result-
ing string. cftime does the same with the capabilities of
ctime. strftime and ascftime take a pointer to a tm struc-
ture and convert it to a character string. cftime takes a
calendar time of type time_t pointed to by clock and con-
verts it to a character string. In both functions, the char-
acters are placed into the array pointed to by buf (plus a
terminating \0) and the value returned is the number of such
characters (not counting the terminating \0). For strftime,
no more than size characters are placed into the array. fmt
controls the format of the resulting string.
mktime converts the time represented by the tm structure
pointed to by timeptr into a time_t type calendar time. In
addition to computing the calendar time, mktime normalizes
the supplied tm structure.
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, 11] */
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 savings time */
long tm_gmtoff; /* offset (seconds) from Greenwich (BSD)*/
char *tm_zone; /* Ascii time zone name (BSD)*/
};
Page 2 CX/UX Programmer's Reference Manual
ctime(3C) ctime(3C)
The value of tm_isdst is positive if daylight savings time
is in effect, zero if daylight savings time is not in
effect, and negative if the information is not available.
(Previously, the value of tm_isdst was defined as non-zero
if the alternate time zone was in effect.)
Normalized tm Structure
mktime ignores the original values of the tm_wday and
tm_yday components of the structure, and the original values
of the other components are not restricted to the ranges
indicated by the definition of the structure. On successful
completion, the values of the tm_wday and tm_yday components
are set appropriately, and the other components are set to
represent the specified calendar time, but with their values
forced to be within the appropriate ranges. The final value
of tm_mday is not set until tm_mon and tm_year are deter-
mined.
mktime returns the specified calendar time. If the calendar
time cannot be represented, the function returns the value
((time_t)(-1)).
The original values of the components may be either greater
than or less than the specified range. For example, a
tm_hour or -1 means 1 hour before midnight, tm_mday of 0
means the day preceding the current month, and tm_mon or -2
means 2 months before January of tm_year.
Note that times before GMT Dec 13 20:45:52 1901 or after GMT
Jan 19 03:14:07 2038 cannot be represented in a time_t
value. Note also that the value returned on error,
((time_t)-1), corresponds to GMT Dec 31 23:59:59 1969 and so
that value is also considered to be outside the valid range
of mktime. The total time represented by tm_sec, tm_min,
tm_hour, or tm_mday should not exceed the number of seconds
in December or January for the first years and last years
representable in time_t values. tm_year should be for year
1970 or later.
If tm_isdst is positive, the original values are assumed to
be in the alternate time zone. If it turns out that the
alternate time zone is not valid for the computed calendar
time, then the components are adjusted to be in the main
time zone. Likewise, if tm_isdst is zero, the original
values are assumed to be in the main time zone and are con-
verted to the alternate time zone if the the main time zone
is not valid. If tm_isdst is negative, the correct time
zone is determined and the components are not adjusted.
Local time zone information is used as if mktime had called
tzset.
Page 3 CX/UX Programmer's Reference Manual
ctime(3C) ctime(3C)
Controlling the Output Format
strftime, ascftime, and cftime place characters into the buf
array as controlled by the string pointed to by fmt. fmt is
a character string that consists of field descriptors and
text characters, reminiscent of printf(3S). Each field
descriptor consists of a % character followed by another
character which 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 abbreviated weekday name
%A full weekday name
%b abbreviated month name
%B full month name
%c default date and time representation
%C default date and time representation as produced
by date(1)
%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 abbreviated month name
%H hour ( 00 - 23 )
%I hour ( 00 - 12 )
%j day number of year ( 001 - 366 )
%m month number ( 01 - 12 )
%M minute ( 00 - 59 )
%n same as \n
%p ante meridian or post meridian
%r time as %I:%M:%S %p
%R time as %H:%M
%S seconds ( 00 - 61 )
%t insert a tab
%T time as %H:%M:%S
%U week number of year ( 01 - 53 ), Sunday is the
first day of week 1
%w weekday number ( Sunday = 0 )
%W week number of year ( 01 - 53 ), Monday is the
first day of week 1
%x Local specific date format
%X Local specific time format
%y year within century ( 00 - 99 )
%Y year as ccyy ( e.g. 1986)
%Z time zone name
The difference between %U and %W lies in which day is
counted as the first of the week. In programs linked in one
of the ANSI C compilation modes (see hc(1)), and in programs
linked in the 88open OCS-compliant mode, week number 01 is
the week with the first January Sunday (%U) or Monday (%W)
Page 4 CX/UX Programmer's Reference Manual
ctime(3C) ctime(3C)
in it. Otherwise, week number 01 is the first week with
four or more January days in it.
The example below shows what the string in buf would look
like if the values in the tm structure corresponded to
Thursday, August 28, 1986 at 12:44:36 in New Jersey.
strftime (buf, strsize, "%A %m %d %j", tm)
This example would result in the buffer containing ``Thurs-
day Aug 28 240''.
If fmt is (char *)0, then the locale's default format is
used. For strftime, the default format is the same as
``%c'', for cftime and ascftime the default format is the
same as ``%C''. cftime and ascftime first try to use the
value of the environment variable CFTIME, and if that is
undefined or empty the default format is used. Under 88open
OCS-compliant mode, the default representation for strftime
in the ``C'' locale is a concatenation of the %x and %X
representations. Otherwise, it is the same as that returned
by ctime.
Each directive, including the default format string, is
replaced by appropriate characters determined by the LC_TIME
category of the then current locale and by the time informa-
tion passed as parameters. See below for details on chang-
ing the current language and strftime(4) for a description
of the structure of these files.
Selecting the Output Language
The user can request that the output of strftime, ascftime,
and cftime be in a specific language by setting the LC_TIME
category of the current locale with the setlocale(3C) func-
tion. In the default ``C'' locale, the strings are
appropriate for U.S. English.
Time Zone
The external time_t variable timezone contains the differ-
ence, in seconds, between GMT and the local standard time;
the external time_t variable altzone contains the differ-
ence, in seconds, between GMT and the alternate time zone.
The external variable daylight indicates whether time should
reflect daylight savings time. 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", " " };
Page 5 CX/UX Programmer's Reference Manual
ctime(3C) ctime(3C)
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). They will handle the new
daylight savings time starting with the first Sunday in
April, 1987.
tzset uses the contents of the environment variable TZ to
override the value of the different external variables. See
environ(5) for a description of the TZ environment variable.
tzset is called by localtime, ctime, strftime, and mktime
and may also be called explicitly by the user. It scans the
contents of the environment variable and assigns the dif-
ferent fields to the respective variable. For example, the
setting for New Jersey in 1986 could be
EST5EDT4;116/2:00:00,298/2:00:00
or simply
EST5EDT
A southern hemisphere setting such as the Cook Islands could
be
KDT9:30KST10:00;63/5:00,302/20:00
In the longer version of the New Jersey example of TZ,
tzname[0] is EST, timezone will be set to 5*60*60, tzname[1]
is EDT, altzone will be set to 4*60*60, the starting date of
the alternate time zone is the 117th day at 2 AM, the ending
date of the alternate time zone is the 299th day at 2 AM
(using zero-based Julian days), and daylight will be set
positive. Starting and ending times are relative to the
alternate time zone. If the alternate time zone start and
end dates and the time are not provided, the days for the
United States that year will be used and the time will be 2
AM. If the start and end dates are provided but the time is
not provided, the time will be midnight. The effects of
tzset are thus to change the values of the external vari-
ables timezone, altzone, daylight, and tzname.
If the string in the TZ variable begins with a ``:'', it is
treated as the pathname of a compiled time zone information
file [see zic(1M)]. If the name does not begin with a
``/'', it is sought relative to the directory
/usr/lib/locale/TZ.
Note that in most installations, TZ is set to the correct
value by default when the user logs on, via the local
/etc/profile file [see profile(4) and timezone(4)].
Page 6 CX/UX Programmer's Reference Manual
ctime(3C) ctime(3C)
FILES
/usr/lib/locale/locale/LC_TIME
file that contains the locale specific
date and time information
/usr/lib/locale/TZ directory of compiled time zone data
files
SEE ALSO
time(2), getenv(3C), printf(3S), setlocale(3C), profile(4),
strftime(4), timezone(4), environ(5).
date(1), hc(1) in the CX/UX User's Reference Manual.
zic(1M) in the CX/UX Administrator's Reference Manual.
NOTES
The return values for ctime, localtime and gmtime point to
static data whose content is overwritten by each call.
strftime is the preferred method for formatting the date and
time string. ascftime and cftime are obsolete and are pro-
vided only for compatibility with previous releases.
Format specifiers %C, %D, %e, %h, %n, %r, %R, %t, and %T are
extensions to the ANSI C standard.
Setting the time during the interval of change from timezone
to altzone or vice versa can produce unpredictable results.
The system administrator must change the Julian start and
end days annually if the full form of the TZ variable is
specified.
Berkeley has dropped support for the function timezone so
Harris has followed suit. Programs which use the obsolete
function timezone should use tm_zone instead.
Page 7 CX/UX Programmer's Reference Manual