CTIME(S) UNIX System V CTIME(S)
Name
ctime, localtime, gmtime, asctime, cftime, ascftime,
strftime, tzset - convert date and time to string
Syntax
#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;
int strftime(s, maxsize, format, timeptr)
char *s;
int maxsize;
char *format;
struct tm *timeptr;
void tzset ( )
extern long timezone, altzone;
extern int daylight;
extern char *tzname[2];
#include <time.h>
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 Greenwich
Mean Time (GMT), January 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 GMT, which is the time the UNIX
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
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(S). 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
%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(F) 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 strftime function places its output (according to the
format string format and the time values contained in the
structure pointed to by timeptr), followed by the null
character (\0) in consecutive bytes starting at s. The
maximum length of the output string is specified by maxsize,
the maximum number of characters including the terminating
null character.
The strftime function converts and formats the time values
contained in the structure pointed to by timeptr under
control of the format string format. The string format is a
character string can contain two types of object. These are:
plain characters, which are simply copied to the output
string, and directives.
Each directive is introduced by the percent character (%).
The following directives are independent of the program's
current locale (see locale(M)):
%d is replaced by the day of the month as a decimal number
(01-31)
%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)
%S is replaced by the second as a decimal number (00-59)
%U is replaced by the week number of the year (Sunday as the
first day of the week) as a decimal number (00-52)
%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-52)
%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 timezone name, or by no characters if
no timezone exists
%% is replaced by %
The strings used to replace the following directives are
dependent on the program's current locale, and are defined
using the utility timtbl(M)):
%a is replaced by the locale's abbreviated weekday name
%A is replaced by the locale's full weekday name
%b is replaced by the locale's abbreviated month name
%B is replaced by the locale's full month name
%c is replaced by the locale's appropriate date and time
representation
%p is replaced by the locale's equivalent of AM or PM
%x is replaced by the locale's appropriate date
representation
%X is replaced by the locale's appropriate time
representation
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
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, 1989.
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" .
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(F) and environ(M). 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(M)).
Return Value
The strftime function returns the number of characters
placed in the string s (not including the terminating null
character), or zero if the length of the output string would
exceed maxsize. In the latter case, the content of the
output string s is undefined.
Zero is also returned by strftime if the function detects a
situation which would lead to infinite recursion; for
example, if a format string refers to itself.
Files
/lib/cftime - directory that contains the language specific
printable files
See Also
time(S), timtbl(M), getenv(S), putenv(S), printf(S),
cftime(F), nl_cxtime(S) profile(M), timezone(F), environ(M).
Note
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.
Standards Conformance
asctime, ctime, gmtime and localtime are conformant with:
AT&T SVID Issue 2, Select Code 307-127;
The X/Open Portability Guide II of January 1987;
ANSI X3.159-198X C Language Draft Standard, May 13,
1988;
IEEE POSIX Std 1003.1-1988 with C Standard Language-
Dependent System Support;
and NIST FIPS 151-1.
strftime is conformant with:
ANSI X3.159-198X C Language Draft Standard, May 13, 1988;
IEEE POSIX Std 1003.1-1988 with C Standard Language-
Dependent System Support;
and NIST FIPS 151-1.
tzset is conformant with:
AT&T SVID Issue 2, Select Code 307-127;
The X/Open Portability Guide II of January 1987;
IEEE POSIX Std 1003.1-1988 with C Standard Language-
Dependent System Support;
and NIST FIPS 151-1.
(printed 6/20/89)