Struct_tm

This article is written like a manual or guidebook. Please help rewrite this article from a neutral point of view. (August 2009)

In the C and C++ programming languages, time.h (ctime is the recommended header file for C++ programs) is a header file defined in the C Standard Library to declare time and date functions that provide standardized access to time/date manipulation and formatting.

Functions

char *asctime(const struct tm* tmptr)

Convert tm to a string in the 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 newline and a terminating null character, containing a total of 26 characters. The string pointed at is statically allocated and shared by ctime and asctime functions. Each time one of these functions is called the contents of the string is overwritten.

clock_t clock(void)

Return number of clock ticks since process start.

char* ctime(const time_t* timer)

Convert time_t time value to string in the same format as asctime. The string pointed is statically allocated and shared by ctime and asctime functions. Each time one of these functions is called the content of the string is overwritten. ctime also uses internally the buffer used by gmtime and localtime as return value, so a call to this function will overwrite this.

double difftime(time_t timer2, time_t timer1)

Returns the difference in seconds between the two times.

struct tm* gmtime(const time_t* timer)

Convert a time_t value to a tm structure as UTC time. This structure is statically allocated and shared by gmtime, localtime and ctime functions. Each time one of these functions is called the content of the structure is overwritten.

struct tm* gmtime_r(const time_t* timer, struct tm* result)

Convert a time_t value to a tm structure as UTC time. The time is stored in the tm struct referred to by result. This function is the thread-safe version of gmtime.

struct tm* localtime(const time_t* timer)

Convert a time_t time value to a tm structure as local time (ie time adjusted for the local time zone and daylight savings). This structure is statically allocated and shared by gmtime, localtime and ctime functions. Each time one of these functions is called the content of the structure is overwritten.

time_t mktime(struct tm* ptm)

Convert tm to a time_t time value. Checks the members of the tm structure passed as parameter ptm adjusting the values if the ones provided are not in the possible range or they are incomplete or mistaken and then translates that structure to a time_t value that is returned. The original values of tm_wday and tm_yday members of ptm are ignored and filled with the correspondent ones to the calculated date. The range of tm_mday is not checked until tm_mon and tm_year are determined. On error, a -1 value is returned.

time_t time(time_t* timer)

Get the current time (number of seconds from the epoch) from the system clock. Stores that value in timer. If timer is null, the value is not stored, but it is still returned by the function.

size t strftime(char* s, size t n, const char* format, const struct tm* tptr)

Format tm into a date/time string.

char * strptime(const char* buf, const char* format, struct tm* tptr)

Scan values from buf string into tptr struct. On success it returns pointer to the character following the last character parsed. Otherwise it returns null.

time_t timegm(struct tm *brokentime)

timegm is functionally identical to mktime except it always takes the input values to be Coordinated Universal Time (UTC) regardless of any local time zone setting. Note that timegm is the inverse of gmtime.

Portability note: mktime is essentially universally available. timegm is rather rare. For the most portable (but non-thread safe) conversion from a UTC broken-down time to a simple time, set the TZ environment variable to UTC, call mktime, then set TZ back.

Constants

CLK_PER_SEC

Constant that defines the number of clock ticks per second. Used by the clock() function.

CLOCKS_PER_SEC

An alternative name for CLK_PER_SEC used in its place in some libraries.

CLK_TCK

Obsolete macro for CLK_PER_SEC.

Data types

clock_t

Data type returned by clock().
Generally defined as int or long int.

time_t

Data type returned by time().
Generally defined as int or long int.

struct tm

A non-linear^{[clarification needed]}, broken-down calendar representation of time.

Calendar time

Calendar time (also known as "broken-down time") in the C standard library is represented as the struct tm structure, consisting of the following members:

Examples

This snippet prints the current time to stdout (to the shell).

#include <stdio.h>
#include <time.h>
 
int main()
{
    const time_t timer = time(NULL);
    printf("ctime is %s\n", ctime(&timer));
    return 0;
}

References

• "Calendar Time". The GNU C Library Reference Manual. 2001-07-06. http://www.gnu.org/software/libc/manual/html_node/Calendar-Time.html. Retrieved 2007-04-03. 
• time.h: time types – Base Definitions Reference, The Single UNIX® Specification, Issue 7 from The Open Group
• "gmtime". The Open Group Base Specifications. 2008-12-09. http://www.opengroup.org/onlinepubs/009695399/functions/gmtime.html.