Date and Time Functions -- <time.h>

The header time.h defines four macros, and declares several types and functions for manipulating time. Many functions deal with a calender time that represents the current date (according to the Gregorian calender) and time. Some functions deal with local time, which is the calender time expressed for some specific time zone, and with Daylight Saving Time, which is a temporary change in the algorithm for determining local time. The local timezone and Daylight Saving Time are implementation-defined.

The macros defined are NULL; and

CLOCKS_PER_SEC

which expands to a constant expression with type clock_t described below, and which is the number per second of the value returned by the clock function.

The types declared are size_t;

clock_t

and

time_t

which are arithmetic types capable of representing times; and

struct tm

which holds the components of a calender time, called the broken-down time.

The tm structure shall contain at least the following members, in any order, The semantics of the members and their normal ranges are expressed in the comments.

int tm_sec; ${\bf //}$ seconds after the minute--[0,60]
int tm_min; ${\bf //}$ minutes after the hout--[0,59]
int tm_hour; ${\bf //}$ hours since midnight--[0,23]
int tm_mday; ${\bf //}$ day of the month--[1,31]
int tm_mon; ${\bf //}$ months since January--[0,11]
int tm_year; ${\bf //}$ years since 1900
int tm_wday; ${\bf //}$ days since Sunday--[0.6]
int tm_yday; ${\bf //}$ days since January 1--[0,365]
int tm_isdst; ${\bf //}$ Daylight Saving Time flag

The value of tm_isdst is positive if Daylight Saving Time is in effect, zero if Daylight Saving Time is not in effect, and negative if the information is not available.

Public Data
None.

Functions
The following functions are implemented using the time header.

 

Functions   Description 
 
asctime()   		 Converts broken-down time into a string.

clock()   		 Determines the processor time used.

ctime()   		 Converts from calendar time to local time.

difftime()   		 Computes the difference between two calender times.

gmtime()   		 Converts from calendar time to broken time.

localtime()   		  Converts from calendar time to broken-down time.

mktime()    		 Converts broken-down time to calender time.

strftime()   		 Places characters into an array.

time()   		 Determines the current calendar time.

Macros
The following macros are defined for the time header.

 

Macro   Description 
 
NULL 		 Used to indicate end-of-file.

CLOCKS_PER_SEC 		 Holds the value of number per second of the value returned.

Declared Types
The following types are declared in the time header.

 

Declared Types   Description 
 
size_t 		 Unsigned integer.

clock_t 		 Arithmetic type capable of representing times.

time_t 		 Arithmetic type capable of representing times.

struct tm 		 Structure which holds various date and time elements.

Portability
This header has no known portability issues.

asctime



asctime  

Synopsis
#include <time.h
char * asctime(const struct tm *timeptr);

Purpose
Converts broken-down time into a string.

Return Value
The asctime() function returns a pointer to the string.

Parameters
timeptr Pointer to a structure of type tm

Description
The asctime() function converts the broken-down time in the structure pointed to by timeptr into a string in the form

Sun Sep 16 01:03:52 1973 ${\bf\backslash n \backslash 0 }$

using the equivalent of the following algorithm.

CLICK HERE

Example 1
asctime



asctime  

Synopsis
#include <<><2067>>time.h>
char * asctime(const struct tm *timeptr);

Purpose
Converts broken-down time into a string.

Return Value
The asctime() function returns a pointer to the string.

Parameters
timeptr Pointer to a structure of type tm

Description
The asctime() function converts the broken-down time in the structure pointed to by timeptr into a string in the form

Sun Sep 16 01:03:52 1973 ${\bf\backslash n \backslash 0 }$

using the equivalent of the following algorithm.

CLICK HERE

Example 1
rawht asctime



asctime  

Synopsis
#include <time.h>
char * asctime(const struct tm *timeptr);

Purpose
Converts broken-down time into a string.

Return Value
The asctime() function returns a pointer to the string.

Parameters
timeptr Pointer to a structure of type tm

Description
The asctime() function converts the broken-down time in the structure pointed to by timeptr into a string in the form

Sun Sep 16 01:03:52 1973 ${\bf\backslash n \backslash 0 }$

using the equivalent of the following algorithm.

CLICK HERE

Example 1
CLICK HERE

Output
CLICK HERE

Example 2
CLICK HERE

Output
CLICK HERE

See Also

clock



clock  

Synopsis
#include <time.h>
clock_t clock(void);

Purpose
Determines the processor time used.

Return Value
The clock() function returns the implementation's best approximation to the processor time used by the program since the beginning of an implementation-defined era related only to the program invocation. To determine the time in seconds, the value returned by the clock() function should be divided by the valu clock



clock  

Synopsis
#include <time.h>
clock_t clock(void);

Purpose
Determines the processor time used.

Return Value
The clock() function returns the implementation's best approximation to the processor time used by the program since the beginning of an implementation-defined era related only to the program invocation. To determine the time in seconds, the value returned by the clock() function should be divided by the value of the macro CLOCKS_PER_SEC. If the processor time used is not available or its value cannot be represented, the function returns the value (clock_t) - 1.

Parameters
void Void argument.

Description
The clock() function determines the processor time used.

Example
CLICK HERE

Output
CLICK HERE

See Also

ctime



ctime  

Synopsis
#include <time.h
char * ctime(const time_t *timer);

Purpose
Converts from calendar time to local time.

Return Value
The ctime() function returns the pointer returned by the asctime() function with that broken-down time as argument.

Parameters
timer Variable pointer used to hold a calender time.

Description
The ctime() function determines converts the calendar time pointed to by timer to local time in the form of a string. It is equivalent to

{asctime(localtime(timer))

ctime



ctime  

Synopsis
#include <time.h>
char * ctime(const time_t *timer);

Purpose
Converts from calendar time to local time.

Return Value
The ctime() function returns the pointer returned by the asctime() function with that broken-down time as argument.

Parameters
timer Variable pointer used to hold a calender time.

Description
The ctime() function determines converts the calendar time pointed to by timer to local time in the form of a string. It is equivalent to

ctime



ctime  

Synopsis
#include <<><2524>>time.h>
char * ctime(const time_t *timer);

Purpose
Converts from calendar time to local time.

Return Value
The ctime() function returns the pointer returned by the asctime() function with that broken-down time as argument.

Parameters
timer Variable pointer used to hold a calender time.

Description
The ctime() function determines converts the calendar time pointed to by timer to local time in the form of a string. It is equivalent to

asctime(localtime(timer))

ctime



ctime  

Synopsis
#include <time.h>
char * ctime(const time_t *timer);

Purpose
Converts from calendar time to local time.

Return Value
The ctime() function returns the pointer returned by the asctime() function with that broken-down time as argument.

Parameters
timer Variable pointer used to hold a calender time.

Description
The ctime() function determines converts the calendar time pointed to by timer to local time in the form of a string. It is equivalent to

asctime(localtime(timer))

Example
CLICK HERE

Output
CLICK HERE

See Also

difftime



difftime  

Synopsis
#include <time.h>
double difftime(time_t time1, time_t time0);

Purpose
Computes the difference between two calender times.

Return Value
The difftime() function returns the difference expressed in seconds as a double.

Parameters
time1 Variable used to hold a calender time.
time0 Variable used to hold a calender time.

Description
The difftime() function computes the difference between two calender times: time1 - time0.

Example
CLICK HERE

Output
CLICK HERE

See Also
difftime



difftime  

Synopsis
#include <time.h>
double difftime(time_t time1, time_t time0);

Purpose
Computes the difference between two calender times.

Return Value
The difftime() function returns the difference expressed in seconds as a double.

Parameters
time1 Variable used to hold a calender time.
time0 Variable used to hold a calender time.

Description
The difftime() function computes the difference between two calender times: time1 - time0.

Example
CLICK HERE

Output
CLICK HERE

See Also

gmtime



gmtime  

Synopsis
#include <time.h>
struct tm * gmtime(const time_t *timer);

Purpose
Converts from calendar time to broken time.

Return Value
The gmtime() function returns a pointer to the broken-down time, or a null pointer if the specified time cannot be converted to UTC.

Parameters
timer Variable pointer used to hold a calender time.

Description
The gmtime() function converts the calendar time pointed to by timer into a broken-down time, expressed as UTC.

Example
CLICK HERE

Output
CLICK HERE

See Also

gmtime



gmtime  

Synopsis
#include <time.h>
struct tm * gmtime(const time_t *timer);

Purpose
Converts from calendar time to broken time.

Return Value
The gmtime() function returns a pointer to the broken-down time, or a null pointer if the specified time cannot be converted to UTC.

Parameters
timer Variable pointer used to hold a calender time.

Description
The gmtime() function converts the calendar time pointed to by timer into a broken-down time, expressed as UTC.

Example
CLICK HERE

Output
CLICK HERE

See Also

localtime



localtime  

Synopsis
#include <time.h>
char * localtime(const time_t *timer);

Purpose
Converts from calendar time to broken-down time.

Return Value
The localtime() function returns a pointer to the broken-down time, or a null pointer if the specified time cannot be converted to local time.

Parameters
timer Variable pointer used to hold a calender time.

Description
The localtime() function converts the calendar time pointed to by timer into a broken-down time, expressed as local time.

Example
CLICK HERE

Output
CLICK HERE

localtime



localtime  

Synopsis
#include <time.h>
char * localtime(const time_t *timer);

Purpose
Converts from calendar time to broken-down time.

Return Value
The localtime() function returns a pointer to the broken-down time, or a null pointer if the specified time cannot be converted to local time.

Parameters
timer Variable pointer used to hold a calender time.

Description
The localtime() function converts the calendar time pointed to by timer into a broken-down time, expressed as local time.

Example
CLICK HERE

Output
CLICK HERE

See Also

mktime



mktime  

Synopsis
#include <time.h>
time_t mktime(struct tm*timeptr);

Purpose
Converts broken-down time to calender time.

Return Value
The mktime() function returns the specified calendar time encoded as a value of type time_t. If the calendar time cannot be represented, the function returns the value (time_t) - 1.

Parameters
timeptr Pointer to a structure of type tm

Description
The mktime() function converts the broken-down time, expressed as local time, in the structure pointed to by timeptr into a calender time value with the same encoding as that of the values returned by the time() function. the original tm_wday and tm_yday components of the struc mktime



mktime  

Synopsis
#include <time.h>
time_t mktime(struct tm*timeptr);

Purpose
Converts broken-down time to calender time.

Return Value
The mktime() function returns the specified calendar time encoded as a value of type time_t. If the calendar time cannot be represented, the function returns the value (time_t) - 1.

Parameters
timeptr Pointer to a structure of type tm

Description
The mktime() function converts the broken-down time, expressed as local time, in the structure pointed to by timeptr into a calender time value with the same encoding as that of the values returned by the time() function. the original tm_wday and tm_yday components of the structure are ignored, and the original values of the other components are not restricted to the ranges indicated above. On successful completion, the values of the tm_wday and tm_yday components of the structure are set appropriately, and the other components are set to represent the specified calender time, but with their values forced to the ranges indicated above; the final value of the tm_mday is not set until tm_mon and tm_year are determined.

If the call is successful, a second call to the mktime() function with the resulting struct tm value shall always leave it unchanged and return the same value as the first call. Furthermore, if the normalized time is exactly representable as a time_t value, then the normalized broken-down time and the broken-down time generated by converting the result of the mktime() function by a call to localtime() shall be identical.

Example
CLICK HERE

Output
CLICK HERE

See Also

strftime



strftime  

Synopsis
#include <time.h
char strftime(char * restrict s, size_t maxsize, const char * restrict format, const struct tm * restrict timeptr);

Purpose
Places characters into an array.

Return Value
If the total number of resulting characters including the terminating null character is not more than maxsize, the strftime() function returns the number of characters placed into the array pointed to by s not including the terminating null character. Otherwise, zero is returned and the contents of the array are indeterminate.

Parameters
s Character pointer argument.
maxsize Unsigned integer argument.
strftime



strftime  

Synopsis
#include <<><3843>>time.h>
char strftime(char * restrict s, size_t maxsize, const char * restrict format, const struct tm * restrict timeptr);

Purpose
Places characters into an array.

Return Value
If the total number of resulting characters including the terminating null character is not more than maxsize, the strftime() function returns the number of characters placed into the array pointed to by s not including the terminating null character. Otherwise, zero is returned and the contents of the array are indeterminate.

Parameters
s Character pointer argument.
maxsize Unsigned integer argument.

newpage strftime



strftime  

Synopsis
#include <time.h>
char strftime(char * restrict s, size_t maxsize, const char * restrict format, const struct tm * restrict timeptr);

Purpose
Places characters into an array.

Return Value
If the total number of resulting characters including the terminating null character is not more than maxsize, the strftime() function returns the number of characters placed into the array pointed to by s not including the terminating null character. Otherwise, zero is returned and the contents of the array are indeterminate.

Parameters
s Character pointer argument.
maxsize Unsigned integer argument.
format Character pointer argument.
timeptr Pointer to structure.

Description
The strftime() function places characters into the array pointed to by s as controlled by the string pointed to by format. The format shall be a multibyte character sequence, beginning and ending in its initial shift state. The format string consists of zero or more conversion specifiers and ordinary multibyte characters. A conversion specifier consists of a % character, possibly followed by an Eor O modifier character (described below), followed by a character that determines the behavior of the conversion specifier. All ordinary multibyte characters (including the terminating null character) are copied unchanged into the array. If copying takes place between objects that overlap, the behavior is undefined. No more than maxsize characters are placed into the array.

Each conversion specifier is replaced by appropriate characters as described in the following list. The appropriate characters are determined using the LC_TIME category of the current locale and by the values of zero or more members of the broken-down time structure pointed to by timeptr, as specified in brackets in the description. If any of the specified values is outside the normal range, the characters stored are unspecified.

%a

is replaced by the locale's abbreviated weekday name. [tm_wday]

%A

is replaced by the locale's full weekday name. [tm_wday]

%b

is replaced by the locale's abbreviated month name. [tm_mon]

%B

is replaced by the locale's full month name. [tm_mon]

%c

is replaced by the locale's appropriate date and time representation.

%C

is replaced by the year divided by 100 and truncated to an integer, as a decimal number (00-99). [tm_year]

bf %d

is replaced by the day of the month as a decimal number (01-31). [tm_mday]

%D

is equivalent to ${\bf \lq\lq \%m \backslash \%d \backslash \%y ''}$. [tm_mon, tm_mday, tm_year]

%e

is replaced by day of the month as a decimal number (01-31); a single digit is preceded by a space. [tm_mday]

%F

is equivalent to ${\bf \lq\lq \%Y-\%m-\%d''}$ (the ISO 8601 date format). [tm_year, tm_mon, tm_mday]

%g

is replaced by the last two digits of the week-based year (see below) as a decimal number (00-99). [tm_year, tm_wday, tm_yday]

%G

is replaced by the week-based year (see below) as a decimal number (e.g., 1997). [tm_year, tm_wday, tm_yday]

%h

is equivalent to `` %b ''. [tm_mon]

%H

is replaced by the hour (24-hour clock) as a decimal number (01-23). [tm_hour]

%I

is replaced by the hour (12-hour clock) as a decimal number (01-12). [tm_hour]

%j

is replaced by the day of the year as a decimal number (001-366). [tm_yday]

%m

is replaced by the month as a decimal number (01-12). [tm_mon]

%M

is replaced by the minute as a decimal number (00-59). [tm_min]

%n

is replaced by a new-line character.

%p

is replaced by the locale's equivalent of the AM/PM designations associated with a 12-hour clock. [tm_hour]

%r

is replaced by the locale's 12-hour clock time. [tm_hour, tm_min, tm_sec]

%R

is equivalent to ``%H:%M''. [tm_hour, tm_min]

%S

is replaced by the second as a decimal number (00-60). [tm_sec]

%t

is replaced by a horizontal-tab character.

%T

is equivalent to ``%H:%M:%S'' (the ISO 8601 time format). [tm_hour, tm_min, tm_sec]

%u

is replaced by the ISO 8601 weekday as a decimal number (1-7), where Monday is 1. [tm_wday]

%U

is replaced by the week number of the year (the first Sunday as the first day of week 1) as a decimal number (00-53). [tm_year, tm_wday, tm_yday]

%V

is replaced by the ISO 8601 week number (see below) as a decimal number (01-53). [tm_year, tm_wday, tm_yday]

%w

is replaced by the weekday as a decimal number (0-6), where Sunday is 0. [tm_wday]

%W

is replaced by the week weeknumber of the year (the first Monday as the first day of week 1) s a decimal number (00-53). [tm_year, tm_wday, tm_yday]

%x

is replaced by the locale's appropriate date representation.

%X

is replaced by the locale's appropriate time representation.

%y

is replaced by the last 2 digits of the year as a decimal number (00-99). [tm_year]

%Y

is replaced by the year as a decimal number (e.g., 1997). [tm_year]

%z

is replaced by the offset from UTC in the ISO 8601 format ``-0430'' (meaning 4 hours 30 minutes behind UTC, west of Greenwich), or by no characters if no time zone is determinable. [tm_isdst]

%Z

is replaced by the locale's time zone name or abbreviation, or by no characters if no time zone is determinable. [tm_isdst]

%%

is replaced by %.

Some conversion specifiers can be modified by the inclusion of an E or O modifier character to indicate an alternative format or specification. If the alternative format or specification does not exist for the current locale, the modifier is ignored.

%Ec

is replaced by the locale's alternative date and time representation.

%EC

is replaced by the name of the base year (period) in the locale's alternative representation.

%Ex

is replaced by the locale's alternative date representation.

%EX

is replaced by the locale's alternative time representation.

%Ey

is replaced by the offset from %EC (year only) in the locale's alternative representation.

%EY

is replaced by the locale's full alternative year representation.

%Od

is replaced by the day of the month, using the locale's alternative numeric symbols (filled as needed with leading zeros, or with leading spaces if there is no alternative symbol for zero).

%Oe

is replaced by the day of the month, using the locale's alternative numeric symbols (filled as needed with leading spaces).

%OH

is replaced by the hour (24-hour clock), using the locale's alternative numeric symbols.

%OI

is replaced by the hour (12-hour clock), using the locale's alternative numeric symbols.

%Om

is replaced by the month, using the locale's alternative numeric symbols.

%OM

is replaced by the minutes, using the locale's alternative numeric symbols.

%OS

is replaced by the seconds, using the locale's alternative numeric symbols.

%Ou

is replaced by the ISO 8601 weekday as a number in the locale's alternative representation, where Monday is 1.

%OU

is replaced by the week number, using the locale's alternative numeric symbols.

%OV

is replaced by the ISO 8601 week number, using the locale's alternative numeric symbols.

%Ow

is replaced by the weekday as a number, using the locale's alternative numeric symbols.

%OW

is replaced by the week number of the year, using the locale's alternative numeric symbols.

%Oy

is replaced by the last 2 digits of the year, using the locale's alternative numeric symbols.

%g, %G, and %V give values according to the ISO 8601 week-based year. In this system, weeks begin on a Monday and week 1 of the year is the week that includes January 4th, which is also the week that includes the first Thursday of the year, and is also the first week that contains at least four days in the year. If the first Monday of January is the 2nd, 3rd, or 4th, the preceding days are part of the last week of the preceding year; thus, for Saturday 2nd January 1999, %G is replaced by 1998 and %V is replaced by 53. If December 29th, 30th, or 31st is a Monday, it and any following days are part of week 1 of the following year. Thus, for Tuesday 30th December 1997, %G is replaced by 1998 and %V is replaced by 1.

If a conversion specifier is not one of the above, the behavior is undefined.

In the ``C'' locale, the Eand O modifiers are ignored and the replacement strings for the following specifiers are:

%a

the first three characters of %A.

%A

one of ``Sunday'', ``Monday'', ... ,``Saturday''.

%b

one of the first three characters of %B.

%B

one of ``January'', ``February'', ... , ``December''.

%c

equivalent to ``%A %B %d %T %Y''.

%p

one of ``am'' or ``pm''.

%r

equivalent to ``%I:%M:%S:%p''.

%x

equivalent to ``%A:%B:%d:%Y''.

%X

equivalent to ``%T''.

%Z

implementation-defined.

Example
CLICK HERE

Output
CLICK HERE

See Also

time



time  

Synopsis
#include <time.h>
time_t time(time_t timer);

Purpose
Determines the current calender time.

Return Value
The time() function returns the implementation's best approximation to the current calendar time. The value (time_t) - 1 is returned if the calendar time is not available. If timer is not a null pointer, the return value is time



time  

Synopsis
#include <time.h>
time_t time(time_t timer);

Purpose
Determines the current calender time.

Return Value
The time() function returns the implementation's best approximation to the current calendar time. The value (time_t) - 1 is returned if the calendar time is not available. If timer is not a null pointer, the return value is also assigned to the object it points to.

Parameters
timer Variable used to hold a calender time.

Description
The time() function determines the current calendar time. The encoding of the value is unspecified.

Example
CLICK HERE

Output
CLICK HERE

See Also