ctime(3) CLIX ctime(3)
NAME
ctime, localtime, gmtime, asctime, cftime, ascftime, mktime, strftime,
tzset - Converts date and time to string
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <sys/types.h>
#include <time.h>
char *ctime(
time_t *clock );
struct tm *localtime(
time_t *clock );
struct tm *gmtime(
time_t *clock );
char *asctime(
struct tm *tm );
int cftime(
char *buf ,
char *fmt ,
time_t *clock );
int ascftime(
char *buf ,
char *fmt ,
struct tm *tm );
time_t mktime(
struct tm *tm );
int strftime(
char *buf ,
size_t bufsize ,
char *fmt ,
struct tm *tm );
extern long timezone ;
extern long altzone ;
extern int daylight ;
2/94 - Intergraph Corporation 1
ctime(3) CLIX ctime(3)
extern char *tzname[2] ;
void tzset(
void );
PARAMETERS
clock Points to an integer representing the time since midnight,
January 1, 1970.
tm Points to a tm structure.
fmt Specifies a format string.
buf Specifies a 26-character array into which time information is
placed.
bufsize Specifies the size of the buffer.
DESCRIPTION
The ctime(), localtime(), and gmtime() functions accept parameters 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.
The ctime() function returns a pointer to a 26-character string in the
following form (fields have constant width):
Fri Sep 13 00:00:00 1986\n\0
The localtime() and gmtime() functions return pointers to tm structures,
described below. The localtime() function corrects for the main time zone
and possible alternate (Daylight Savings) time zone. The gmtime()
function converts directly to GMT, which is the time the UNIX system uses.
The asctime() function 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 */
2 Intergraph Corporation - 2/94
ctime(3) CLIX ctime(3)
};
The tm_isdst member is nonzero if the alternate time zone is in effect.
The cftime() and ascftime() functions provide the capabilities of ctime()
and asctime(), respectively, plus others. The cftime() function takes an
integer of type time_t, pointed to by clock, and converts it to a
character string. The ascftime() function takes a pointer to a tm
structure and converts it to a character string. The strftime() function
accepts the same arguments as ascftime(), plus size_t which identifies the
length of buf. If this length is exceeded, the strftime() function
returns a value of 0.
In cftime(), ascftime(), and strftime(), 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. The
fmt parameter controls the format of the resulting string.
The fmt parameter is a character string consisting of field descriptors
and text characters reminiscent of printf(). Each field descriptor
consists of the character % followed by a character specifying the
replacement for the field descriptor. All other characters are copied
from fmt into the result. The following field descriptors are supported
by the three functions:
%% Same as %.
%a Abbreviated weekday name.
%A Full weekday name.
%b Abbreviated month name.
%B Full month name.
%c Time and date. (Supported by the strftime() function only.)
%d Day of month (01 - 31).
%D Date as %m/%d/%y. (Not supported by the strftime() function.)
%e Day of month (1 - 31). Single digits are preceded by a blank.
%h Abbreviated month name. (Not supported by the strftime() function.)
%H Hour (00 - 23).
%I Hour (00 - 12).
%j Day number of year (001 - 366).
2/94 - Intergraph Corporation 3
ctime(3) CLIX ctime(3)
%m Month number (01 - 12).
%M Minute (00 - 59).
%n Same as \n. (Not supported by the strftime() function.)
%p Ante meridian or post meridian.
%r Time as %I:%M:%S %p. (Not supported by the strftime() function.)
%R Time as %H:%M. (Not supported by the strftime() function.)
%S Seconds (00 - 59).
%t Insert a tab. (Not supported by the strftime() function.)
%T Time as %H:%M:%S. (Not supported by the strftime() function.)
%U Week number of year (00 - 53). Sunday is the first day of week.
%w Weekday number. Sunday = 0.
%W Week number of year (00 - 53). Monday is the first day of week.
%x Local specific date format.
%X Local specific time format.
%y Year within century (00 - 99). (Not supported by the strftime()
function.)
%Y Year as ccyy (For example: 1986).
%Z Time zone name.
The difference between %U and %W lies in which day is counted as the first
of the week.
The following example 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
by the cftime() and ascftime() functions. If CFTIME is undefined or empty,
a default format is used. The default format string is taken from the
file containing the date and time strings associated with the then current
language. (See below for details on changing the current language, and
see cftime() for a description of the structure of these files.)
4 Intergraph Corporation - 2/94
ctime(3) CLIX ctime(3)
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 is used (the default is the usa-
english strings).
The mktime() function converts the value pointed to by the tm argument to
a local time value, expressed as the number of seconds since 00:00:00 GMT,
Jan. 1, 1970. The mktime() function then calls tzset() and the time value
is corrected for the time zone and possible alternate time zone (such as
Daylight Savings Time).
The extern long variable timezone contains the difference, in seconds,
between GMT and the main time zone. The extern 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 nonzero if an alternate time zone exists. Time zone names are
in the external variable tzname, which, by default is set to:
char *tzname[2] = { "GMT", " " };
The functions know the peculiarities of this conversion for various U.S.A.
time periods, specifically: 1974, 1975, and 1987. The functions handle
the new daylight savings time starting with the first Sunday in April
1987.
The tzset() function uses the contents of the environment variable TZ to
override the value of the different external variables. See TIMEZONE(4)
for the syntax and description of the TZ environment variable.
The tzset() function 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
The following list shows the settings of the variables with the New Jersey
example of TZ:
⊕ tzname[] is EST.
⊕ timezone is set to 5*60*60.
2/94 - Intergraph Corporation 5
ctime(3) CLIX ctime(3)
⊕ tzname[] is EDT.
⊕ altzone is 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.
⊕ daylight will be set to nonzero.
Starting and ending times are relative to the alternate time zone. If the
alternate time zone start date, end date, and time are not provided, the
days for the United States that year will be used and the time will be
02:00:00. If the start and end dates are provided but the time is not
provided, the time will be 02:00:00. The effects of tzset() are thus to
change the values of the external variables timezone, altzone, daylight,
and tzname. The tzset() function is called by localtime() and mktime(),
and may also be called explicitly by the user.
In most installations, TZ is set to the correct value, by default, when
the user logs on with the local /etc/profile file (see profile(4)).
EXAMPLES
1. To get current time and date using ctime():
#include <time.h>
#include <sys/types.h>
main()
{
time_t current_time;
char *time_string;
time(¤t_time);
time_string=ctime(¤t_time);
printf("I.e., %s.\n",time_string);
}
2. To get the local time and GMT using localtime() and gmtime() with the
asctime() function:
#include <time.h>
#include <sys/types.h>
main()
{
time_t current_time;
char *time_string;
time(¤t_time);
6 Intergraph Corporation - 2/94
ctime(3) CLIX ctime(3)
time_string=asctime(localtime(¤t_time));
printf("The local time is: %s.\n",time_string);
time_string=asctime(gmtime(¤t_time));
printf("The time in Greenwich is: %s.\n",time_string);
}
3. To alter the output format of the time using ascftime():
#include <time.h>
#include <sys/types.h>
main()
{
time_t current_time;
/* struct tm time_structure;*/
char *time_string;
char buffer[100];
char *format_string="Today is %A, %B %d.%nThe time is %R.";
time(¤t_time);
ascftime(buffer,format_string,(gmtime(¤t_time)));
printf("%s\n",buffer);
}
4. To override the default output format of the time using cftime():
#include <time.h>
#include <sys/types.h>
main()
{
time_t current_time;
char *time_string;
char buffer[100];
char *format_string =
"This is %A, %B %e, %Y.%nThe time is %R.%n.";
time(¤t_time);
cftime(buffer,format_string,¤t_time);
printf("%s\n",buffer);
}
5. To alter the output format of the time using strftime():
#include <time.h>
#include <sys/types.h>
2/94 - Intergraph Corporation 7
ctime(3) CLIX ctime(3)
main()
{
time_t current_time;
char *time_string;
char buffer[100];
char *format_string="Today is %A, %B %d. The time
is %I:%M.";
time(¤t_time);
strftime(buffer, 100, format_string,
(localtime(¤t_time)));
printf("%s0,buffer);
}
6. To convert April 4, 1976 10:15 am to the number of seconds since
January 1, 1970 00:00 using mktime():
#include <time.h>
#include <sys/types.h>
main()
{
time_t time;
struct tm apr_4_1976;
apr_4_1976.tm_sec = 0;
apr_4_1976.tm_min = 15;
apr_4_1976.tm_hour = 10;
apr_4_1976.tm_mday = 4;
apr_4_1976.tm_mon = 3; /* 0 based */
apr_4_1976.tm_year = 76;
apr_4_1976.tm_isdst = 0; /* mktime() will figure out
* tm_isdst */
time = mktime (&apr_4_1976);
}
FILES
/lib/cftime
Directory that contains the language-specific printable files.
CAUTIONS
Setting the time during the interval of change from timezone to altzone or
vice versa can produce unpredictable results.
The return values for ctime(), localtime(), and gmtime() point to static
8 Intergraph Corporation - 2/94
ctime(3) CLIX ctime(3)
data whose content is overwritten by each call.
RETURN VALUES
asctime()
Returns a pointer to a 26-character string resulting from the
conversion of a tm structure.
ctime()
Returns a pointer to a 26-character string.
ascftime()
cftime()
Returns the number of characters placed in the buffer array.
gmtime()
localtime()
Returns a pointer to tm structures.
strftime()
Returns the number of characters placed in the buffer array.
Returns a 0 if an error occurs or if a string exceeds bufsiz.
mktime()
Returns the value of time in seconds since 00:00:00 GMT, January 1,
1970, corrected for the current time zone, resulting from the
conversion of a tm structure.
RELATED INFORMATION
Files: cftime(4), profile(4), TIMEZONE(4)
Functions: time(2), getenv(3), putenv(3), printf(3)
Miscellany: environ(4)
2/94 - Intergraph Corporation 9