ctime(3C) DG/UX 4.30 ctime(3C)
NAME
ctime, localtime, gmtime, asctime, cftime, ascftime,
difftime, mktime, strftime, tzset - date and time
conversions
SYNOPSIS
#include <time.h>
char *ctime (clock)
timet *clock;
struct tm *localtime (clock)
timet *clock;
struct tm *gmtime (clock)
timet *clock;
char *asctime (tm)
struct tm *tm;
int cftime (buf, fmt, clock)
char *buf, *fmt;
timet *clock;
int ascftime (buf, fmt, tm)
char *buf, *fmt;
struct tm *tm;
double difftime (time1, time0)
timet time1, time0;
timet mktime (tm)
struct tm *tm);
sizet strftime (buf, maxsize, fmt, tm)
char *buf;
sizet maxsize;
char *fmt;
struct tm *tm;
extern long timezone, altzone;
extern int daylight;
extern char *tzname[2];
void tzset ( )
DESCRIPTION
Ctime converts a long integer, pointed to by clock,
representing the time in seconds since 00:00:00 GMT, January
1, 1970, and returns a pointer to a 26-character string in
Licensed material--property of copyright holder(s) Page 1
ctime(3C) DG/UX 4.30 ctime(3C)
the following form. All the fields have constant width.
Sun Sep 16 01:03:52 1973\n\0
Localtime and gmtime return pointers to "tm" structures,
described below. Localtime corrects for the time zone and
possible Daylight Savings Time; gmtime converts directly to
Greenwich Mean Time (GMT), which is the time the DG/UX
system uses.
Asctime converts a "tm" structure to a 26-character string,
as shown in the above example, and returns a pointer to the
string.
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 (0 - 59) */
int tm_min; /* minutes (0 - 59) */
int tm_hour; /* hours (0 - 23) */
int tm_mday; /* day of month (1 - 31) */
int tm_mon; /* month of year (0 - 11) */
int tm_year; /* year - 1900 */
int tm_wday; /* day of week (Sunday = 0) */
int tm_yday; /* day of year (0 - 365) */
int tm_isdst;
};
Tm_isdst is non-zero if Daylight Savings Time is in effect.
Cftime and ascftime provide the capabilities of ctime and
asctime, respectively, as well as additional ones. Cftime
takes an integer of type time_t pointed to by clock and
converts it to a character string. Ascftime takes a pointer
to a "tm" structure and converts it to a character string.
In both functions, the characters are placed into the array
pointed to by buf (with a terminating \0) and the value
returned is the number of such characters (not counting the
terminating \0). Fmt controls the format of the resulting
string.
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
Licensed material--property of copyright holder(s) Page 2
ctime(3C) DG/UX 4.30 ctime(3C)
%A full weekday name
%b abbreviated month name
%B full month name
%c appropriate date and time representation
%C 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 - 59 )
%t insert a tab
%T time as %H:%M:%S
%U week number of year ( 01 - 52 ), Sunday is the
first day of week
%w weekday number ( Sunday = 0 )
%W week number of year ( 01 - 52 ), Monday is the
first day of week
%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. Week number 01 is the
first week with four or more January days in it.
The example below shows what the values in the "tm"
structure would look like for Thursday, August 28, 1986 at
12:44:36 in New Jersey.
ascftime (buf, "%A %b %d %j", tm)
This example would result in the buffer containing "Thursday
Aug 28 240".
If fmt is (char *)0 or fmt points to a null string, the
value of the environment variable CFTIME is used. If CFTIME
is undefined or empty, a default format is used. The
default format string is taken from the file that contains
the date and time strings associated with the then current
language [see below for details on changing the current
language and cftime(4) for a description of the structure of
Licensed material--property of copyright holder(s) Page 3
ctime(3C) DG/UX 4.30 ctime(3C)
these files].
The user can request that the output of cftime, ascftime and
strftime be in a specific language by setting the
environment variable LANGUAGE to the desired language. If
LANGUAGE is empty, unset or set to an unsupported language,
the last language requested will be used (the default is the
usa-english strings).
Difftime returns the difference in seconds between two
calendar times, time1 - time0.
Mktime converts the calendar time expressed by the values in
a "tm" structure to the form returned by the time function.
The values in the structure are not constrained to the
ranges indicated above: mktime sets the values in the "tm"
structure to represent the specified time, forcing the
values into those ranges and setting tmwday and tmyday
appropriately. Mktime returns -1 if the calendar time
cannot be represented.
Strftime is similar to ascftime: it converts a calendar
time into a character string in a locale-sensitive manner
(see locale(3c)). Tm should point to a "tm" structure whose
values represent a calendar time, buf to an array to hold
the resultant character string, and fmt to a character
string that controls the conversion. The fmt consists of a
multibyte character sequence, beginning and ending in its
initial shift state, holding ordinary multibyte characters
along with any number of field descriptors prefixed by a "%"
character. Strftime copies ordinary characters (including
the terminating null character) unchanged from fmt to buf,
and replaces each field descriptor in the same manner as
cftime and ascftime.
The appropriate representation of each of the field
descriptors is determined by the LCTIME category of the
current locale, and by the values in the "tm" structure. If
the resultant character string holds no more than maxsize
characters, strftime returns the number of characters placed
in the array buf (excluding the terminating null character).
Otherwise, strftime returns zero, and the contents of buf
are indeterminate.
The external long variable timezone contains the difference,
in seconds, between GMT and local standard time (in EST,
timezone is 5*60*60). The external long variable altzone
contains the difference, in seconds, between GMT and
Daylight Savings Time. Both timezone and altzone default to
0 (GMT). The external variable daylight is non-zero if and
only if the standard U.S.A. Daylight Savings Time
conversion should be applied. The time zone names are
Licensed material--property of copyright holder(s) Page 4
ctime(3C) DG/UX 4.30 ctime(3C)
contained in the external variable tzname, which by default
is set to
char *tzname[2] = { "GMT", " " };
The program knows about the peculiarities of this conversion
in 1974, 1975, and 1987; If necessary, a table for these
years can be extended. The functions handle the new
daylight savings time starting with the first Sunday in
April, 1987.
Tzset uses the contents of TZ to override the value of the
different external variables. Tzset scans the contents of
the environment variable and assigns the various fields to
their respective variables. For example, the setting for
New Jersey in 1986 would be
EST5EDT4,117/2:00:00,299/2:00:00
or simply
EST5EDT
When the longer format is used, the variable must be
surrounded by double quotes as shown. 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, and daylight will be set
to non-zero. 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
variables timezone, altzone, daylight and tzname. Tzset is
called implicitly by ascftime(), cftime(), ctime(),
localtime(), mktime(), and strftime(). It may also be
called explicitly by the user.
Note that in most installations, TZ is set by default when
the user logs on, to a value in the local /etc/profile file
(see profile(4)).
Time(2) is quite useful for producing the values with which
to call ctime(3C).
The contents of the environment variable named TZ shall be
used by the functions ascftime(), cftime(), ctime(),
localtime(), mktime(), and strftime() to override the
Licensed material--property of copyright holder(s) Page 5
ctime(3C) DG/UX 4.30 ctime(3C)
default time zone. The value of TZ has one of the two forms
(spaces inserted for clarity):
:characters
or:
std offset dst offset, rule
If TZ is of the first format (i.e., if the first character
is a colon), the string following the colon is the name of
the timezone that will be loaded in from the
/usr/lib/locale/TZ directory. For example, if TZ was set to
US/Eastern, it would load the /usr/lib/local/TZ/US/Eastern
timezone definition file. The timezones under this
directory are produced with the zic(1) command.
The expanded format (for all TZs whose value does not have a
colon as the first character) is as follows:
stdoffset[dst[offset][,start[/time],end[/time]]]
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. Upper- and lowercase letters
are explicitly allowed. Any characters except a
leading colon (:), digits, comma (,), minus (-), plus
(+), and ASCII NUL are allowed.
offset
Indicates the value one must add to the local time to
arrive at Coordinated Universal Time. 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
``+'').
Licensed material--property of copyright holder(s) Page 6
ctime(3C) DG/UX 4.30 ctime(3C)
rule Indicates when to change to and back from summer time.
The rule has the form:
date/time,date/time
where the first date describes when the change from
standard to summer time occurs and the second date
describes when the change back happens. Each time
field describes when, in current local time, the change
to the other time is made.
The format of date shall be one of the following:
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 < n < 365). Leap
days shall be counted, and it is possible to refer
to February 29.
Mm.n.d
The d th day (0 < d < 6) of week n of month m of
the year (1 < n < 5, 1 < m < 12, where week 5
means ``the last d day in month m '' which may
occur in either the fourth or the fifth week).
Week 1 is the first week in which the d'th day
occurs. Day zero is Sunday.
The time has the same format as offset except that no
leading sign (``-'' or ``+'') shall be allowed. The
default, if time is not given, shall be 02:00:00.
Whenever ascftime(), cftime(), ctime(), localtime(),
mktime(), or strftime() is called, the time zone names
contained in the external variable tzname() shall be set as
if the tzset() function had been called.
Applications are explicitly allowed to change TZ and have
the changed TZ apply to themselves.
SEE ALSO
time(2), getenv(3C), dftime(4), profile(4), timezone(4),
environ(5), zic(1).
CAVEAT
The return values point to static data whose content is
overwritten by each call. Setting the time during the
interval of change from timezone to altzone or vice versa
can produce unpredictable results.
Licensed material--property of copyright holder(s) Page 7
ctime(3C) DG/UX 4.30 ctime(3C)
The system administrator must change the Julian start and
end days annually if the full form of the TZ variable is
specified.
COPYRIGHTS
Portions of this text are reprinted from IEEE Std 1003.1-
1988, Portable Operating System Interface for Computer
Environment, copyright © 1988 by the Institute of Electrical
and Electronics Engineers, Inc., with the permission of the
IEEE Standards Department. To purchase IEEE Standards, call
800/678-IEEE.
In the event of a discrepancy between the electronic and the
original printed version, the original version takes
precedence.
Licensed material--property of copyright holder(s) Page 8