CTIME(3) BSD CTIME(3)
NAME
ctime, ctime_r, localtime, localtime_r, gmtime, gmtime_r, asctime,
asctime_r strftime, _bky_timezone, 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;
char *_bky_timezone(zone, dst)
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 BSD 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 */
};
When local time is necessary, the program consults the system to
determine the time zone and whether the U.S.A. daylight savings time
adjustment is appropriate. The program understands some of the
peculiarities in time conversion over the past 10-20 years; if necessary,
this understanding can be extended.
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 Is replaced by the date (%m/%d/%y)
%h 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 Is replaced by a newline character
%p Is replaced by the locale equivalent of
either a.m. or p.m.
%r 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 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.
_bky_timezone returns the name of the time zone associated with its first
argument, which is measured in minutes westward from Greenwich (see note
below for information on timezone). If the second argument is 0, the
standard zone name is used; otherwise, the Daylight Savings Zone. If the
required name does not appear in a table built into the routine, the
difference from GMT is produced; for example, in Afghanistan
_bky_timezone(-(60*4+30), 0)
is appropriate because Afghanistan is four and a half hours ahead of GMT.
This call would produce the string GMT+4:30.
tzset uses the value of the environment variable TZ to set time
conversion information used by localtime, ctime, strftime, 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.
NOTE
The name timezone refers to a data location as specified by Domain/OS
System V. To use the BSD timezone function, change the name of the call
to
_bky_timezone
or add
-Dtimezone=_bky_timezone
to the compile line, or add
#define timezone _bky_timezone
before the first #include directive in your program.
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
cc(1), gettimeofday(2), time(1) printf(3S), setlocale(3), <time.h>.