Table of Contents

Previous

Next

1.15 The Standard Headers: <time.h>

The header <time.h> declares types and functions for manipulating date and time.  Some functions process local time, which may differ from calendar time, for example because of time zone.  clock_t and time_t are arithmetic types representing times, and struct tm holds the components of a calendar time:

clock_t clock(void)

clock returns the processor time used by the program since the beginning of execution, or -1 if unavailable.  clock()/CLOCKS_PER_SEC is a time in seconds.

time_t time(time_t *tp)

time returns the current calendar time or -1 if the time is not available.  If tp is not NULL, the return value is also assigned to *tp.

double difftime(time_t time2, time_t time1)

difftime returns time2-time1 in seconds.

time_t mktime(struct tm *tp)

mktime converts the local time in the structure *tp into calendar time in the same representation used by time.  The components will have values in the ranges shown.  mktime returns the calendar time or -1 if it cannot be represented.

char *asctime(const struct tm *tp)

asctime converts the time in the structure *tp into a string of the form

   Sun Jan  3 15:14:13 1988\n\0

char *ctime(const time_t *tp)

ctime converts the calendar time *tp to local time; it is equivalent to

   asctime(localtime(tp))

struct tm *gmtime(const time_t *tp)

gmtime converts the calendar time *tp into Coordinated Universal Time (UTC).  It returns NULL if UTC is not available.  The name gmtime has historical significance.

struct tm *localtime(const time_t *tp)

localtime converts the calendar time *tp into local time.

struct tm *strftime(char *s, size_t smax, const char *fmt, const struct tm *tp)

strftime formats date and time information from *tp into s according to fmt, which is analagous to a printf format.  Ordinary characters (including the terminating '\0') are copied into s.  Each %c is replaced as described below, using values appropriate for the local environment.  No more than smax characters are placed into s.  strftime returns the number of characters, excluding the '\0', or zero if more than smax characters were produced.