9.17. Date and time
These functions deal with either ‘elapsed’ or ‘calendar’ time.
They share the <time.h> header, which declares the
functions as necessary and also the following:
CLOCKS_PER_SEC
- This is the number of ‘ticks’ per second returned by the
clock function.
clock_t
time_t
- These are arithmetic types used to represent different forms of
time.
struct tm
-
This structure is used to hold the values representing a calendar time.
It contains the following members, with the meanings as shown.
int tm_sec /* seconds after minute [0-61] (61 allows for 2 leap-seconds)*/
int tm_min /* minutes after hour [0-59] */
int tm_hour /* hours after midnight [0-23] */
int tm_mday /* day of the month [1-31] */
int tm_mon /* month of year [0-11] */
int tm_year /* current year-1900 */
int tm_wday /* days since Sunday [0-6] */
int tm_yday /* days since January 1st [0-365] */
int tm_isdst /* daylight savings indicator */
The tm_isdst member is positive if daylight savings time
is in effect, zero if not and negative if that information is not
available.
The time manipulation functions are the following:
#include <time.h>
clock_t clock(void);
double difftime(time_t time1, time_t time2);
time_t mktime(struct tm *timeptr);
time_t time(time_t *timer);
char *asctime(const struct tm *timeptr);
char *ctime(const time_t *timer);
struct tm *gmtime(const time_t *timer);
struct tm *localtime(const time_t *timer);
size_t strftime(char *s, size_t maxsize,
const char *format,
const struct tm *timeptr);
The functions asctime , ctime ,
gmtime , localtime , and strftime
all share static data structures, either of type struct tm or
char [] , and calls to one of them may overwrite the data
stored by a previous call to one of the others. If this is likely to cause
problems, their users should take care to copy any values needed.
clock
- Returns the best available approximation to the time used by the
current invocation of the program, in ‘ticks’.
(clock_t)-1 is returned if no value is available. To find
the actual time used by a run of a program, it is necessary to find the
difference between the value at the start of the run and the time of
interest—there is an implementation-defined constant factor which
biases the value returned from clock. To determine the time in
seconds, the value returned should be divided by
CLOCKS_PER_SEC .
difftime
- This returns the difference in seconds between two calendar
times.
mktime
-
This returns the calendar time corresponding to the values in
a structure pointed to by timeptr , or
(time_t)-1 if the value cannot be represented.
The tm_wday and tm_yday members of the
structure are ignored, the other members are not restricted to their
usual values. On successful conversion, the members of the structure
are all set to appropriate values within their normal ranges. This
function is useful to find out what value of a time_t
corresponds to a known date and time.
time
- Returns the best approximation to the current calendar time in an
unspecified encoding.
(time_t)-1 is returned if the time is
not available.
asctime
-
Converts the time in the structure pointed to by timeptr
into a string of the form
Sun Sep 16 01:03:52 1973\n\0
the example being taken from the Standard. The Standard defines the
algorithm used, but the important point to notice is that all the fields
within that string are of constant width and relevant to most
English-speaking communities. The string is stored in a static structure
which may be overwritten by a subsequent call to one of the other
time-manipulation functions (see above).
ctime
- Equivalent to
asctime(localtime(timer)) . See
asctime for the return value.
gmtime
- Returns a pointer to a
struct tm set to represent the
calendar time pointed to by timer . The time is expressed in
terms of Coordinated Universal Time (UTC) (formerly Greenwich Mean
Time). A null pointer is returned if UTC is not available.
localtime
- Converts the time pointed to by
timer into local time and
puts the results into a struct tm , returning a pointer to that
structure.
strftime
-
Fills the character array pointed to by s with at most
maxsize characters. The format string is used
to format the time represented in the structure pointed to
timeptr . Characters in the format string
(including the terminating null) are copied unchanged into the array,
unless one of the following format directives is found—then the
value specified below is copied into the destination, as
appropriate to the locale.
%a |
abbreviated weekday name |
%A |
full weekday name |
%b |
abbreviated month name |
%B |
full month name |
%c |
date and time representation |
%d |
decimal day of month number 01–31 |
%H |
hour 00–23 (24 hour format) |
%I |
hour 01–12 (12 hour format) |
%j |
day of year 001–366 |
%m |
month 01–12 |
%M |
minute 00–59 |
%p |
local equivalent of ‘AM’ or ‘PM’ |
%S |
second 00–61 |
%U |
week number in year 00–53
(Sunday is first day of week |
%w |
weekday, 0–6 (Sunday is 0) |
%W |
week number in year 00–53
(Monday is first day of week |
%x |
local date representation |
%X |
local time representation |
%y |
year without century prefix 00–99 |
%Y |
year with century prefix |
%Z |
timezone name, or no characters if no timezone exists |
%% |
a % character |
The total number of characters copied into *s is
returned, excluding the null. If there was not room (as determined by
maxsize ) for the trailing null, zero is returned.
|
Printer-friendly version
The C Book
This book is published as a matter of historical interest.
Please read the
copyright and disclaimer information.
GBdirect Ltd provides up-to-date training and consultancy in
C,
Embedded C,
C++
and a wide range of
other subjects based on
open standards if you happen to be interested.
|