CTIME(3C) SysV CTIME(3C)
NAME
ctime, localtime, gmtime, asctime, cftime, ascftime, 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;
int cftime (buf, fmt, clock)
char *buf, *fmt;
time_t *clock;
int ascftime (buf, fmt, tm)
char *buf, *fmt;
struct tm *tm
size_t strftime(s, maxsize, fmt, timeptr)
char *s;
size_t maxsize;
const char *fmt;
const struct tm *timeptr;
extern long timezone, altzone;
extern int daylight;
extern char *tzname[2];
void tzset ( )
DESCRIPTION
ctime, localtime, and gmtime accept arguments of type time_t (declared in
<sys/types.h>), 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. All the fields have constant
width.
Tue Oct 20 09:53:59 1987\n\0
localtime and gmtime return pointers to tm structures, described below.
localtime corrects for the time zone and possible alternate ("Daylight
Savings Time") time zone; gmtime converts directly to Greenwich Mean Time
(GMT), which is the time SysV 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 nonzero 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
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 print(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.
strftime places characters into the array pointed to by s as controlled
by the string pointed to by fmt. The format must be a multibyte
character sequence, beginning and ending in its initial shift state. The
fmt 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.
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.
cftime, ascftime, and strftime all support the following field
descriptors:
%% Same as %
%a Abbreviated weekday name
%A Full weekday name
%b Abbreviated month name
%B Full month name
%d Day of month (01-31)
%H Hour (00-23)
%I Hour (00-12)
%j Day number of year (001-366)
%m Month number (01-12)
%M Minute (00-59)
%p Ante meridian or post meridian
%S Seconds (00-59)
%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 (for example, 1988)
%Z Time zone name
For the purposes of %U and %W, cftime and ascftime consider week number
01 to be the first week with four or more January days in it.
cftime and ascftime support the following descriptors that strftime
doesn't:
%D Date as %m/%d/%y
%e Day of month (1-31; single digits are preceded by a blank)
%h Abbreviated month name
%n Same as \n
%r Time as %I:%M:%S %p
%R Time as %H:%M
%t Insert tab
%T Time as %H:%M:%S
strftime supports the following descriptor that cftime and ascftime
don't:
%c The locale's appropriate date and time representations.
If fmt is (char *)0, cftime and ascftime use the value of the environment
variable CFTIME. If CFTIME is undefined or empty, a default format is
used. The default format string is taken from the file in /lib/cftime
(see cftime(4)) that contains the date and time strings associated with
the current language.
Setting the environment variable LANGUAGE to the name of a file in
/usr/lib/cftime causes cftime and ascftime to default to the format
specified by the contents of that file if CFTIME is undefined or empty.
If LANGUAGE is also undefined, empty, or set to an unsupported language,
the last language requested will be used (the default is usa_english).
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; timezone and altzone both default to 0 (GMT). The external
variable daylight is nonzero if an alternate time zone exists. The time
zone names are contained in the external variable tzname. The main time
zone defaults to GMT; the default alternate time zone is blank.
The functions know about the peculiarities of this conversion for the
years 1974 and 1975 in the U.S.A. They handle the new daylight savings
time that started with the first Sunday in April of 1987.
tzset scans the contents of the environment variable TZ and overrides the
values of timezone, altzone, daylight, and tzname, depending upon what it
finds. See timezone(4).
FILES
/usr/lib/cftime Directory for language-
specific format files
/usr/lib/cftime/danish
/usr/lib/cftime/finnish
/usr/lib/cftime/french
/usr/lib/cftime/german
/usr/lib/cftime/italian Language-specific format
/usr/lib/cftime/norwegian files
/usr/lib/cftime/spanish
/usr/lib/cftime/swedish
/usr/lib/cftime/usa_english
NOTE
The return values for ctime, localtime, and gmtime point to static data
whose content is overwritten by each call.
Parts of this discussion are adapted from ANS X3.159-1989.
SEE ALSO
time(2), getenv(3C), putenv(3C), printf(3S), cftime(4), profile(4),
timezone(4), environ(5).