Timegm

Timegm is a non-standard C library function that converts a broken-down time specification in Coordinated Universal Time (UTC) to a time_t value representing seconds since the Unix epoch (00:00:00 UTC on January 1, 1970). It serves as the UTC counterpart to mktime, which interprets the input as local time.

Prototype and behavior: time_t timegm(struct tm *tm); The function takes a pointer to a tm structure, which describes a calendar time in UTC, and returns the corresponding time_t. The input fields (year, month, day, hour, minute, second) are normalized, and the function may modify the tm structure to reflect the normalized values. It returns (time_t) -1 on error; since -1 can be a valid time value for dates before the epoch, robust code should detect errors by carefully inspecting errno or by setting errno to 0 before the call and verifying that it changes.

Availability and portability: timegm is not part of the POSIX standard. It is provided by many Unix-like systems, including GNU libc, BSD variants, and macOS, as well as Windows in some environments via alternatives such as _mkgmtime. Because of its non-standard status, portable code often avoids timegm in favor of other methods or conditional implementations.

Usage notes and alternatives: Since timegm assumes UTC, it does not apply local time zone or daylight saving adjustments. Leap seconds are not represented in time_t, so timegm does not account for them. When timegm is unavailable, common workarounds include temporarily setting the TZ environment variable to UTC and using mktime, or using platform-specific equivalents like MSVC’s _mkgmtime.

See also: mktime, gmtime, localtime, tzset, and the TZ environment variable.