CTIME(3C) (C Programming Language Utilities) CTIME(3C)
NAME
ctime, localtime, gmtime, asctime, cftime, ascftime, tzset -
convert date and time to string
SYNOPSIS
#include <sys/types.h>
#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;
extern long timezone, altzone;
extern int daylight;
extern char *tzname[2];
void tzset ( )
DESCRIPTION
ctime, localtime, and gmtime accept arguments of type timet
(declared in <sys/types.h>), pointed to by clock,
representing the time in seconds since 00:00:00 GMT, January
Page 1 May 1989
CTIME(3C) (C Programming Language Utilities) CTIME(3C)
1, 1970. ctime returns a pointer to a 26-character string
in the following form. All the fields have constant width.
Fri Sep 13 00:00:00 1986\n\0
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), which
is the time the 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 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 */
};
tm_isdst is non-zero if the alternate time zone 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
Page 2 May 1989
CTIME(3C) (C Programming Language Utilities) CTIME(3C)
pointed to by buf (plus 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
%A full weekday name
%b abbreviated month name
%B full month name
%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
Page 3 May 1989
CTIME(3C) (C Programming Language Utilities) CTIME(3C)
%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 %m %d %j", tm)
This example would result in the buffer containing "Thursday
Aug 28 240".
If fmt is (char *)0, 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 these files].
The user can request that the output of cftime and ascftime
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).
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
Page 4 May 1989
CTIME(3C) (C Programming Language Utilities) CTIME(3C)
char *tzname[2] = { "GMT", " " };
The functions know about the peculiarities of this
conversion for various time periods for the U.S.A
(specifically, the years 1974, 1975, and 1987). The
functions 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. The
syntax of TZ can be described as follows:
TZ -> zone
| zone signed_time
| zone signed_time zone
| zone signed_time zone dst
zone -> letter letter letter
signed_time -> sign time
| time
time -> hour
| hour : minute
| hour : minute : second
dst -> signed_time
| signed_time ; dst_date , dst_date
| ; dst_date , dst_date
dst_date -> julian
| julian / time
letter -> a | A | b | B | ... | z | Z
hour -> 00 | 01 | ... | 23
minute -> 00 | 01 | ... | 59
second -> 00 | 01 | ... | 59
julian -> 001 | 002 | ...| 366
sign -> - | +
tzset scans the contents of the environment variable and
assigns the different fields to the respective variable.
For example, the setting for New Jersey in 1986 could be
"EST5EDT4;117/2:00:00,299/2:00:00" .
Page 5 May 1989
CTIME(3C) (C Programming Language Utilities) CTIME(3C)
or simply
EST5EDT
A southern hemisphere setting such as the Cook Islands could
be
"KDT9:30KST10:00;64/5:00,303/20:00"
When the longer format is used, the variable must be
surrounded by double quotes as shown. For more details, see
timezone(4) and environ(5). 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 by localtime and may also be called explicitly by the
user.
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)].
FILES
/lib/cftime - directory that contains the language specific
printable files
SEE ALSO
time(2), getenv(3C), putenv(3C), printf(3S), cftime(4),
profile(4), timezone(4), environ(5).
Page 6 May 1989
CTIME(3C) (C Programming Language Utilities) CTIME(3C)
CAVEAT
The return values for ctime, localtime and gmtime 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.
The system administrator must change the Julian start and
end days annually if the full form of the TZ variable is
specified.
Page 7 May 1989