Time Functions (time.

h)

time
Get the current calendar time as a time_t object.

The function returns this value, and if the argument is not a null pointer, the value is also
set to the object pointed by timer.

Parameters

Pointer to an object of type time_t, where the time value is stored.

Alternatively, this parameter can be a null pointer, in which case the parameter is not
used, but a time_t object is still returned by the function.

Return Value

The current calendar time as a time_t object.

If the argument is not a null pointer, the return value is the same as the one stored in the
location pointed by the argument.

If the function could not retrieve the calendar time, it returns a -1 value.

Example

/* time example */
#include <stdio.h>
#include <time.h>

int main ()
{
time_t seconds;

seconds = time (NULL);

printf ("%ld hours since January 1, 1970", seconds/3600);

return 0;
}
Localtime
Convert time_t to tm as local time

Uses the time pointed by timer to fill a tm structure with the values that represent the
corresponding local time.

struct tm * localtime ( const time_t * timer );

Parameters
timer -Pointer to a time_t value representing a calendar time (see time_t).

Return Value

A pointer to a tm structure with the time information filled in.

This structure is statically allocated and shared by the functions gmtime and localtime.
Each time either one of these functions is called the content of this structure is
overwritten.

Example

/* localtime example */
#include <stdio.h>
#include <time.h>

int main ()
{
time_t rawtime;
struct tm * timeinfo;

time ( &rawtime );
timeinfo = localtime ( &rawtime );
printf ( "Current local time and date: %s", asctime (timeinfo) );

return 0;
}
Strftime
Format time to string
Copies into ptr the content of format, expanding its format tags into the corresponding
values as specified by timeptr, with a limit of maxsize characters.

Parameters

Pointer to the destination array where the resulting C string is copied.

Maximum number of characters to be copied to ptr.

format

C string containing any combination of regular characters and special format specifiers.
These format specifiers are replaced by the function to the corresponding values to
represent the time specified in timeptr. They all begin with a percentage (%) sign, and are:

specifier Replaced by Example

%a Abbreviated weekday name * Thu
%A Full weekday name * Thursday
%b Abbreviated month name * Aug
%B Full month name * August
Thu Aug 23
%c Date and time representation *
14:55:02 2001
%d Day of the month (01-31) 23
%H Hour in 24h format (00-23) 14
%I Hour in 12h format (01-12) 02
%j Day of the year (001-366) 235
%m Month as a decimal number (01-12) 08
%M Minute (00-59) 55
%p AM or PM designation PM
%S Second (00-61) 02
Week number with the first Sunday as the first day
%U 33
of week one (00-53)
Weekday as a decimal number with Sunday as 0 (0-
%w 4
6)
Week number with the first Monday as the first day
%W 34
of week one (00-53)
%x Date representation * 08/23/01
%X Time representation * 14:55:02
%y Year, last two digits (00-99) 01
 %Y Year 2001
%Z Timezone name or abbreviation CDT
%% A % sign %

* The specifiers whose description is marked with an asterisk (*) are locale-dependent.

timeptr

Pointer to a tm structure that contains a calendar time broken down into its components
(see tm).

/* strftime example */

#include <stdio.h>
#include <time.h>

int main ()
{
time_t rawtime;
struct tm * timeinfo;
char buffer [80];

time ( &rawtime );
timeinfo = localtime ( &rawtime );

strftime (buffer,80,"Now it's %I:%M%p.",timeinfo);

puts (buffer);

return 0;
}

ctime
char * ctime ( const time_t * timer );

Convert time_t value to string

Converts the time_t object pointed by timer to a C string containing a human-readable
version of the corresponding local time and date.

The returned string has the following format:

Www Mmm dd hh:mm:ss yyyy
Where Www is the weekday, Mmm the month in letters, dd the day of the month,
hh:mm:ss the time, and yyyy the year.
The string is followed by a new-line character ('\n') and the terminating null-character.
This function is equivalent to: asctime(localtime(timer)).

Parameters

Pointer to a time_t object that contains a calendar time.

Return Value

A C string containing the date and time information in a human-readable format.

The array which holds this string is statically allocated and shared by both the ctime and
asctime functions. Each time either one of these functions is called the content of this
array is overwritten.

Example

/* ctime example */
#include <stdio.h>
#include <time.h>

int main ()
{
time_t rawtime;

time ( &rawtime );
printf ( "The current local time is: %s", ctime (&rawtime) );

return 0;
}

time
time_t time ( time_t * timer );

Get current time

Get the current calendar time as a time_t object.

The function returns this value, and if the argument is not a null pointer, the value is also
set to the object pointed by timer.

Parameters
Pointer to an object of type time_t, where the time value is stored.
Alternatively, this parameter can be a null pointer, in which case the parameter is not
used, but a time_t object is still returned by the function.
Return Value
The current calendar time as a time_t object.
If the argument is not a null pointer, the return value is the same as the one stored in the
location pointed by the argument.

If the function could not retrieve the calendar time, it returns a -1 value.

Example

/* time example */
#include <stdio.h>
#include <time.h>

int main ()
{
time_t seconds;

seconds = time (NULL);

printf ("%ld hours since January 1, 1970", seconds/3600);

return 0;
}

mktime
time_t mktime ( struct tm * timeptr );

Convert tm structure to time_t

Interprets the contents of the tm structure pointed by timeptr as a calendar time
expressed in local time. This calendar time is used to adjust the values of the members of
timeptr accordingly and returned as an object of type time_t.

The original values of the members tm_wday and tm_yday of timeptr are ignored, and the
ranges of values for the rest of its members are not restricted to their normal values (like
tm_mday being between 1 and 31).

The object pointed by timeptr is modified, setting the tm_wday and tm_yday to their
appropiate values, and modifying the other members as necessary to values within the
normal range representing the specified time.

Parameters
timeptr
Pointer to a tm structure that contains a calendar time broken down into its components
(see tm).
Return Value

A time_t value corresponding to the calendar time passed as argument.

On error, a -1 value is returned.
Example
/* mktime example: weekday calculator */
#include <stdio.h>
#include <time.h>

int main ()
{
time_t rawtime;
struct tm * timeinfo;
int year, month ,day;
char * weekday[] = { "Sunday", "Monday",
"Tuesday", "Wednesday",
"Thursday", "Friday", "Saturday"};

/* prompt user for date */

printf ("Enter year: "); scanf ("%d",&year);
printf ("Enter month: "); scanf ("%d",&month);
printf ("Enter day: "); scanf ("%d",&day);

/* get current timeinfo and modify it to the user's choice */

time ( &rawtime );
timeinfo = localtime ( &rawtime );
timeinfo->tm_year = year - 1900;
timeinfo->tm_mon = month - 1;
timeinfo->tm_mday = day;

/* call mktime: timeinfo->tm_wday will be set */

mktime ( timeinfo );

printf ("That day is a %s.\n", weekday[timeinfo->tm_wday]);

return 0;
}

Difftime

double difftime ( time_t time2, time_t time1 );

Return difference between two times

Calculates the difference in seconds between time1 and time2.

Parameters
time2 - time_t object representing the latter of the two times.
time1 - time_t object representing the earlier of the two times.

Return Value
The difference in seconds (time2-time1) as a floating point double.
Example
/* difftime example */
#include <stdio.h>
#include <time.h>

int main ()
{
time_t start,end;
char szInput [256];
double dif;

time (&start);
printf ("Please, enter your name: ");
gets (szInput);
time (&end);
dif = difftime (end,start);
printf ("Hi %s.\n", szInput);
printf ("It took you %.2lf seconds to type your name.\n", dif );

return 0;
}

clock_t
Clock type
Type capable of representing clock tick counts and support arithmetical operations.

This type is returned by the clock function of the <ctime> header to represent the number
of click ticks since the beginning of the program execution.

size_t - Unsigned integral type

size_t corresponds to the integral data type returned by the language operator sizeof and
is defined in the <ctime> header file (among others) as an unsigned integral type.

In <ctime>, it is used in the function strftime as the type of its parameter maxsize and as
its return value. In both cases it used to express counts of characters.
time_t
Time type
Type capable of representing times and support arithmetical operations.

This type is returned by the time function and is used as parameter by some other
functions of the <ctime> header.

It is almost universally expected to be an integral value representing the number of

seconds elapsed since 00:00 hours, Jan 1, 1970 UTC. This is due to historical reasons,
since it corresponds to a unix timestamp, but is widely implemented in C libraries across
all platforms.

Time structures
struct tm
Structure containing a calendar date and time broken down into its components.

The structure contains nine members of type int, which are (in any order):

1 int tm_sec;
2 int tm_min;
3 int tm_hour;
4 int tm_mday;
5 int tm_mon;
6 int tm_year;
7 int tm_wday;
8 int tm_yday;
9 int tm_isdst;

The meaning of each is:

Member Meaning Range

tm_sec seconds after the minute 0-61*
tm_min minutes after the hour 0-59
tm_hour hours since midnight 0-23
tm_mday day of the month 1-31
tm_mon months since January 0-11
tm_year years since 1900
tm_wday days since Sunday 0-6
tm_yday days since January 1 0-365
tm_isdst Daylight Saving Time flag
The Daylight Saving Time flag (tm_isdst) is greater than zero if Daylight Saving Time is in
effect, zero if Daylight Saving Time is not in effect, and less than zero if the information is
not available.

* tm_sec is generally 0-59. Extra range to accommodate for leap seconds in certain
systems.

Asctime

char * asctime ( const struct tm * timeptr );

Convert tm structure to string

Interprets the contents of the tm structure pointed by timeptr as a calendar time and
converts it to a C string containing a human-readable version of the corresponding date
and time.

The returned string has the following format:

Www Mmm dd hh:mm:ss yyyy

Where Www is the weekday, Mmm the month in letters, dd the day of the month,
hh:mm:ss the time, and yyyy the year.

The string is followed by a new-line character ('\n') and the terminating null-character.

Parameters
timeptr - Pointer to a tm structure that contains a calendar time broken down into its
components (see tm).

Return Value
A C string containing the date and time information in a human-readable format.
The array which holds this string is statically allocated and shared by both the ctime and
asctime functions. Each time either one of these functions is called the content of this
array is overwritten.

Example
/* asctime example */
#include <stdio.h>
#include <time.h>
int main ()
{
time_t rawtime;
struct tm * timeinfo;
 time ( &rawtime );
timeinfo = localtime ( &rawtime );
printf ( "The current date/time is: %s", asctime (timeinfo) );

return 0;
}