Use GDateTime for date-and-time values in GLib, GTimeZone to choose the time zone, and GTimeSpan for fixed intervals measured in microseconds. The key distinction is whether you mean a calendar change—such as the same local time tomorrow—or an elapsed duration, such as exactly 24 hours. Those can produce different results around daylight-saving transitions.
What GLib’s date and time types represent
GDateTime is an immutable, reference-counted value that combines a Gregorian date and time with a time zone. It has microsecond precision and supports dates from 0001-01-01 00:00:00 through 9999-12-31 23:59:59.999999. It follows POSIX time semantics, so it does not represent leap seconds.
GTimeZone represents a time zone, and GTimeSpan represents a signed interval in microseconds. These types serve different purposes: a time zone determines how an instant is expressed as a local clock time, while a span measures elapsed time.
How to create a GDateTime
Get the current date and time
Choose the constructor that makes the intended zone explicit:
#1 Best Overall
g_date_time_new_now(tz)gets the current time in a suppliedGTimeZone.g_date_time_new_now_local()uses the system’s local time zone.g_date_time_new_now_utc()uses UTC.
Build a value from calendar fields
Use g_date_time_new(tz, year, month, day, hour, minute, seconds) when you have explicit fields and a time zone. The local-time and UTC convenience constructors are g_date_time_new_local() and g_date_time_new_utc(). For example:
GDateTime *meeting = g_date_time_new_utc(2026, 10, 7, 14, 30, 0.0);The seconds argument can include a fractional part, allowing microsecond precision. Check the returned pointer: a constructor can return NULL if the requested value is invalid or outside the supported range.
Build from Unix time or ISO 8601 text
Use g_date_time_new_from_unix_utc() or g_date_time_new_from_unix_local() when the input is Unix seconds and you want to interpret it in UTC or local time. Use g_date_time_new_from_iso8601() to parse ISO 8601 text; it accepts a time-zone argument for interpreting text that does not specify its own zone. The timeval constructors are deprecated since GLib 2.62; prefer the Unix-time APIs.
Rank #2
How to convert a GDateTime to another time zone
Construct a GTimeZone for a named zone, then pass it to g_date_time_to_timezone(). For UTC and the system’s local zone, use g_date_time_to_utc() and g_date_time_to_local().
GTimeZone *london = g_time_zone_new("Europe/London");
GDateTime *london_time = g_date_time_to_timezone(meeting, london);These conversions preserve the instant and express it in the destination zone; they do not move the event to a different instant. Use a time-zone identifier such as Europe/London, not an abbreviation such as BST or GMT: abbreviations are not valid identifiers for g_time_zone_new().
How to add time without confusing days and hours
Choose calendar arithmetic or elapsed-time arithmetic
Calendar arithmetic changes a date or clock field. Use g_date_time_add_days(), g_date_time_add_weeks(), g_date_time_add_months(), or g_date_time_add_years() when the request is framed in calendar terms. Use g_date_time_add_hours(), g_date_time_add_minutes(), g_date_time_add_seconds(), or g_date_time_add() for a specified duration.
| Intent | Approach | Important distinction |
|---|---|---|
| Same local clock time on the next calendar day | g_date_time_add_days(dt, 1) |
Calendar addition; the elapsed duration can be 23 or 25 hours across a daylight-saving transition. |
| Exactly 24 elapsed hours later | Add a 24-hour duration, for example g_date_time_add_hours(dt, 24) |
Fixed-duration addition; the resulting local clock time may differ across a daylight-saving transition. |
| Two calendar months later | g_date_time_add_months(dt, 2) |
One two-month addition can differ from two separate one-month additions near the end of a month. |
The GLib reference gives January 31 as an example: adding two months produces March 31, while adding one month twice can produce March 28 or 29. If the exact rule matters to your application, choose the operation that expresses the rule rather than assuming calendar units are interchangeable with fixed durations.
Measure or compare two values
Use g_date_time_difference() to get the signed GTimeSpan between two values. Use g_date_time_compare() to order values, or g_date_time_equal() to test whether they represent the same date and time. Compare instants, not formatted strings: formatting can vary with zone and locale.
The Tool Desk
Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →How to convert a GDateTime to Unix time
g_date_time_to_unix() returns Unix time in whole seconds, rounded down. It therefore does not preserve a fractional second. Current GLib documentation also lists microsecond Unix-conversion APIs for newer releases; check the API available in the GLib version you target if your application needs fractional Unix timestamps.
GTimeSpan values are expressed in microseconds. GLib defines G_TIME_SPAN_SECOND as 1,000,000 microseconds, with related constants for milliseconds, minutes, hours, and days. Use these constants when converting a duration to or from a span rather than treating a span as seconds.
How to format a GDateTime
Produce ISO 8601 output
Call g_date_time_format_iso8601() when you need ISO 8601 text containing the date, time, and time-zone information. It is the direct choice for a standardized representation rather than a locale-oriented display string.
Choose a custom display format
g_date_time_format() accepts a documented subset of the C99 strftime() format language, selected GNU extensions (%k, %l, %s, P, and modifiers), and Python’s %f for fractional seconds. It always returns UTF-8. Month names, weekday names, and other locale-sensitive output can vary by locale, so a custom formatted string is not necessarily suitable as a stable interchange format.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteHow to manage returned values and failures
GDateTime is immutable: do not expect an arithmetic or conversion function to edit its input. These operations return a new value. Nearly all operations can fail with NULL if the requested result would exceed the supported range, so check results before using them.
Release each owned reference with g_date_time_unref(). If another part of your program needs to retain a value independently, use g_date_time_ref() for that additional ownership. Apply the same ownership discipline to reference-counted GTimeZone values.
Quick Recap
Which GLib date and time operation should you use?
| Need | Use |
|---|---|
| Current value in UTC, local time, or a specified zone | g_date_time_new_now_utc(), g_date_time_new_now_local(), or g_date_time_new_now(tz) |
| Explicit calendar fields | g_date_time_new(), g_date_time_new_local(), or g_date_time_new_utc() |
| Unix seconds | g_date_time_new_from_unix_utc() or g_date_time_new_from_unix_local() |
| ISO 8601 input or output | g_date_time_new_from_iso8601() or g_date_time_format_iso8601() |
| Same local time on another date | Calendar arithmetic such as g_date_time_add_days() or g_date_time_add_months() |
| Exact elapsed duration | Duration arithmetic such as g_date_time_add() or g_date_time_add_hours() |
| Express the same instant in another zone | g_date_time_to_timezone(), g_date_time_to_utc(), or g_date_time_to_local() |
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
