CTIME(3C) SysV CTIME(3C)
NAME
ctime, ctime_r, localtime, localtime_r, gmtime, gmtime_r, asctime,
asctime_r, strftime, tzset - convert date and time to string
SYNOPSIS
#include <time.h>
char *ctime (clock)
const time_t *clock;
int ctime_r (clock, buffer, len)
const time_t *clock;
char *buffer;
int len;
struct tm *localtime (clock)
const time_t *clock;
int tm localtime_r (clock, result)
const time_t *clock;
struct tm *result;
struct tm *gmtime (clock)
const time_t *clock;
int gmtime_r (clock, result)
const time_t *clock;
struct tm *result;
char *asctime (tm)
const struct tm *tm;
int asctime_r (tm, buffer, len)
const struct *tm;
char *buffer;
int len;
size_t strftime(s, maxsize, format, timeptr)
char *s;
size_t maxsize;
const char *format;
const struct tm *timeptr;
extern long timezone, altzone;
extern int daylight;
extern char *tzname[2];
void tzset (void )
DESCRIPTION
ctime, localtime, and gmtime accept arguments of type time_t pointed to
by clock, representing the time in seconds since the Epoch: 00:00:00,
January 1, 1970 (expressed as Coordinated Universal Time (UTC)). 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
Local timezone information is set as though ctime called tzset. Local
timezone information is used as though localtime called tzset.
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 - 61) */
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; /* Daylight Savings Time flag */
};
tm_isdst is nonzero if the alternate time zone is in effect.
The strftime function places characters into the array pointed to by the
s argument as controlled by the string pointed to by the format argument.
The string pointed to by the format argument is a multibyte character
sequence, beginning and ending in its initial shift state.
maxsize specifies the maximum number of characters to be written to the
array pointed to by the s argument.
timeptr points to a type tm structure that contains broken-down time
information.
Local time zone information is used as though the strftime function
called the tzset(3c) function. Time information used in this subroutine
is fetched from space containing type tm structure data, which is defined
in the time.h include file. The type tm structure must contain the time
information used by this subroutine to construct the time and date
string.
The format string consists of zero or more conversion specifications and
ordinary multibyte characters. A conversion specification consists of a %
(percent) character followed by a character that determines how the
conversion specification constructs the formatted string.
All ordinary multibyte characters (including the terminating null
character) are copied unchanged into the s array. When copying between
objects that overlap takes place, behavior of this function is undefined.
No more than the number of characters specified by the maxsize argument
are written to the array. Each conversion specification 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 values specified by the type tm structure pointed
to by the timeptr argument.
%a Is replaced by the abbreviated weekday
name appropriate for the locale
%A Is replaced by the full weekday name
appropriate for the locale
%b Is replaced by the abbreviated month
name appropriate for the locale
%B Is replaced by the full month name
appropriate for the locale
%c Is replaced by the date and time
representation appropriate for the
locale
%d Is replaced by the day of the month as a
decimal number [01, 31]
%D XPG3: Is replaced by the date (%m/%d/%y)
%h XPG3: Is replaced by the abbreviated
month name appropriate for the locale
%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 [01, 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]
%n XPG3: Is replaced by a newline character
%p Is replaced by the locale equivalent of
either a.m. or p.m.
%r XPG3: Is replaced by the time in
a.m./p.m. notation according to
British/US conventions (%I:%M:%S\
[AM|PM])
%S Is replaced by the second as a decimal
number [00, 61]
%t Is replaced by a tab character
%T XPG3: Is replaced by the time (%H:%M:%S)
%U Is replaced by the week number of the
year (Sunday as the first day of the
week) 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 (Monday as the first day of the
week) as a decimal number [00, 53]
%x Is replaced by the date representation
appropriate for the locale
%X Is replaced by the time representation
appropriate for the locale
%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 when
no time zone exists
%% Is replaced by %
When a directive is not one of the above, the behavior of this function
is undefined.
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 uses the value of the environment variable TZ to set time
conversion information used by localtime, ctime, strftime(3C), and
mktime(3C). If TZ is absent from the environment, default time zone
information is filled in from the node's timezone setting (as set via
/com/tz(1) or the calendar(1) SAU).
The tzset function sets the external variable tzname as follows:
tzname[0] = "std";
tzname[1] = "dst";
where std and dst are the strings designating the standard and daylight
saving time zones respectively, as described for the TZ environment
variable.
The tzset function also sets the external variable daylight to zero if
Daylight Saving Time conversions should never be applied for the time
zone in use; otherwise nonzero. The external variable timezone is set to
the difference, in seconds, between Coordintated Universal time (UTC) and
local standard time.
NOTES
The asctime, ctime, gmtime, and localtime functions are not supported for
multi-threaded applications. Instead, their reentrant equivalents,
asctime_r, ctime_r, gmtime_r, and localtime_r, should be used with
multiple threads.
DIAGNOSTICS
When any of the asctime, ctime, gmtime, or localtime functions complete
successfully, the return value may point to static storage, which may be
overwritten by subsequent calls to these functions. On error, these
functions return a null pointer and errno is set to a value indicating
the error.
Upon successful completion, the asctime and ctime functions return a
pointer to a character string that expresses the time in a fixed format.
Upon successful completion, the gmtime function returns a pointer to a
type tm broken-down time structure, which contains converted GMT time
information. When UTC is not available, this function returns a null
pointer.
Upon successful completion, the localtime functions return a pointer to a
type tm broken-down time structure, which contains converted local time.
When the total number of resulting characters, including the terminating
null character, is not more than maxsize, the strftime function returns
the number of characters written into the array pointed to by the s
argument. The returned value does not include the terminating null
character. Otherwise, a value of (size_t) 0 (zero) is returned and the
contents of the array are undefined.
Upon successful completion, the asctime_r, ctime_r, gmtime_r, and
localtime_r, functions return a value of 0 (zero). Otherwise, -1 is
returned and errno is set to indicate the error.
SEE ALSO
time(2), getenv(3C), putenv(3C), printf(3S), setlocale(3C) profile(4),
timezone(4), <time.h>, environ(5).