Skip to content
Tutorials Center
My learning

Topics

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).

C
#include <time.h>

time_t t = 1700000000;
struct tm *utc = gmtime(&t);
printf("%d\n", utc->tm_year + 1900);   /* 2023 */

Try it

C Taking a struct tm apart

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.

C Time zones and the reentrant variant

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

C
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 to ctime()/asctime()) overwrites it, so copy the struct (struct tm copy = *p;) before calling again. The two functions typically share the same buffer, which makes printf("%d %d", gmtime(&a)->tm_hour, gmtime(&b)->tm_hour) print the same number twice.
  • Months and years are offset. Print tm_mon + 1 and tm_year + 1900; forgetting this is the most common date bug in C.
  • Always check for NULL before dereferencing, particularly for user-supplied or very large values.
  • localtime() depends on the environment. The TZ variable (and on Windows the system settings) selects the zone. Call tzset() after changing TZ. POSIX-style rule strings such as EST5EDT,M3.2.0,M11.1.0 work without any zone files; names like America/New_York need the system's zone database.
  • Offset sign in TZ: in POSIX strings the number is hours west of UTC, so EST5 is UTC-5 and CET-1 is UTC+1.
  • Prefer UTC for storage and logs, and convert to local time only for display.
  • Thread safety: use gmtime_r() and localtime_r() in multithreaded programs. On Windows the equivalents are gmtime_s() and localtime_s(), with the arguments in the opposite order.
  • Inverse operations: mktime() converts a local struct tm back to time_t; timegm() does the same for UTC (C23, and a common extension earlier).
  • Standard version: gmtime and localtime are C89; gmtime_r and localtime_r are POSIX and were added to the C standard in C23.