C Reference ยท ctype.h, math.h and others
C localtime() and gmtime() functions
Reference for localtime() and gmtime(): convert a time_t into a struct tm in UTC or local time, the tm fields, thread-safe _r variants and pitfalls.
gmtime() and localtime() convert a time_t (seconds since the epoch) into a struct tm: a "broken-down" calendar time with separate fields for the year, month, day, hour and so on. gmtime() gives Coordinated Universal Time (UTC); localtime() applies the program's time zone and daylight-saving rules.
Both return a pointer to a statically allocated struct tm that the next call overwrites. For thread-safe code use gmtime_r() and localtime_r() (POSIX, and part of C23).
#include <time.h> time_t t = 1700000000; struct tm *utc = gmtime(&t); printf("%d\n", utc->tm_year + 1900); /* 2023 */
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with scanf or fgets), it gets the next line from this box.
Syntax
struct tm *gmtime(const time_t *timer); struct tm *localtime(const time_t *timer); struct tm *gmtime_r(const time_t *restrict timer, struct tm *restrict result); /* POSIX, C23 */ struct tm *localtime_r(const time_t *restrict timer, struct tm *restrict result); /* POSIX, C23 */
| Name | Description |
|---|---|
timer |
Pointer to the time_t to convert. Passing a pointer to a temporary is fine: time_t t = ...; gmtime(&t). |
result |
(_r versions) Your own struct tm that receives the answer. |
The fields of struct tm:
| Field | Range | Notes |
|---|---|---|
tm_sec |
0 to 60 | 60 allows a leap second. |
tm_min, tm_hour |
0 to 59, 0 to 23 | |
tm_mday |
1 to 31 | The only field that starts at 1 for a day. |
tm_mon |
0 to 11 | Zero-based: January is 0. |
tm_year |
years since 1900 | Add 1900 for the calendar year. |
tm_wday |
0 to 6 | Days since Sunday. |
tm_yday |
0 to 365 | Days since January 1. |
tm_isdst |
positive, 0 or negative | Daylight saving in effect, not in effect, or unknown. |
Returns: a pointer to the broken-down time, or NULL if the value cannot be represented (for example, a year that overflows int). The _r functions return result or NULL.
Usage notes
- The result of
gmtime()/localtime()is shared. The next call to either of them (or toctime()/asctime()) overwrites it, so copy the struct (struct tm copy = *p;) before calling again. The two functions typically share the same buffer, which makesprintf("%d %d", gmtime(&a)->tm_hour, gmtime(&b)->tm_hour)print the same number twice. - Months and years are offset. Print
tm_mon + 1andtm_year + 1900; forgetting this is the most common date bug in C. - Always check for
NULLbefore dereferencing, particularly for user-supplied or very large values. localtime()depends on the environment. TheTZvariable (and on Windows the system settings) selects the zone. Calltzset()after changingTZ. POSIX-style rule strings such asEST5EDT,M3.2.0,M11.1.0work without any zone files; names likeAmerica/New_Yorkneed the system's zone database.- Offset sign in
TZ: in POSIX strings the number is hours west of UTC, soEST5is UTC-5 andCET-1is UTC+1. - Prefer UTC for storage and logs, and convert to local time only for display.
- Thread safety: use
gmtime_r()andlocaltime_r()in multithreaded programs. On Windows the equivalents aregmtime_s()andlocaltime_s(), with the arguments in the opposite order. - Inverse operations:
mktime()converts a localstruct tmback totime_t;timegm()does the same for UTC (C23, and a common extension earlier). - Standard version:
gmtimeandlocaltimeare C89;gmtime_randlocaltime_rare POSIX and were added to the C standard in C23.
Related
- time and clock, strftime, mktime and difftime, getenv
- Lessons: Time and date