2 * Copyright © 2010 Codethink Limited
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Lesser General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the licence, or (at your option) any later version.
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Lesser General Public License for more details.
14 * You should have received a copy of the GNU Lesser General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
19 * Author: Ryan Lortie <desrt@desrt.ca>
24 #include "gtimezone.h"
30 #include "gmappedfile.h"
31 #include "gtestutils.h"
32 #include "gfileutils.h"
33 #include "gstrfuncs.h"
42 * @short_description: a structure representing a time zone
43 * @see_also: #GDateTime
45 * #GTimeZone is a structure that represents a time zone, at no
46 * particular point in time. It is refcounted and immutable.
48 * A time zone contains a number of intervals. Each interval has
49 * an abbreviation to describe it, an offet to UTC and a flag indicating
50 * if the daylight savings time is in effect during that interval. A
51 * time zone always has at least one interval -- interval 0.
53 * Every UTC time is contained within exactly one interval, but a given
54 * local time may be contained within zero, one or two intervals (due to
55 * incontinuities associated with daylight savings time).
57 * An interval may refer to a specific period of time (eg: the duration
58 * of daylight savings time during 2010) or it may refer to many periods
59 * of time that share the same properties (eg: all periods of daylight
60 * savings time). It is also possible (usually for political reasons)
61 * that some properties (like the abbreviation) change between intervals
62 * without other properties changing.
64 * #GTimeZone is available since GLib 2.26.
70 * #GDateTime is an opaque structure whose members cannot be accessed
76 /* zoneinfo file format {{{1 */
79 typedef struct { gchar bytes[8]; } gint64_be;
80 typedef struct { gchar bytes[4]; } gint32_be;
81 typedef struct { gchar bytes[4]; } guint32_be;
83 static inline gint64 gint64_from_be (const gint64_be be) {
84 gint64 tmp; memcpy (&tmp, &be, sizeof tmp); return GINT64_FROM_BE (tmp);
87 static inline gint32 gint32_from_be (const gint32_be be) {
88 gint32 tmp; memcpy (&tmp, &be, sizeof tmp); return GINT32_FROM_BE (tmp);
91 static inline guint32 guint32_from_be (const guint32_be be) {
92 guint32 tmp; memcpy (&tmp, &be, sizeof tmp); return GUINT32_FROM_BE (tmp);
99 guchar tzh_reserved[15];
101 guint32_be tzh_ttisgmtcnt;
102 guint32_be tzh_ttisstdcnt;
103 guint32_be tzh_leapcnt;
104 guint32_be tzh_timecnt;
105 guint32_be tzh_typecnt;
106 guint32_be tzh_charcnt;
116 /* GTimeZone structure and lifecycle {{{1 */
123 const struct tzhead *header;
124 const struct ttinfo *infos;
127 const gint32_be *one;
128 const gint64_be *two;
130 const guint8 *indices;
137 G_LOCK_DEFINE_STATIC (time_zones);
138 static GHashTable/*<string?, GTimeZone>*/ *time_zones;
144 * Decreases the reference count on @tz.
149 g_time_zone_unref (GTimeZone *tz)
154 ref_count = g_atomic_int_get (&tz->ref_count);
156 g_assert (ref_count > 0);
160 if (tz->name != NULL)
164 /* someone else might have grabbed a ref in the meantime */
165 if G_UNLIKELY (g_atomic_int_get (&tz->ref_count) != 1)
167 G_UNLOCK(time_zones);
171 g_hash_table_remove (time_zones, tz->name);
172 G_UNLOCK(time_zones);
176 g_bytes_unref (tz->zoneinfo);
180 g_slice_free (GTimeZone, tz);
183 else if G_UNLIKELY (!g_atomic_int_compare_and_exchange (&tz->ref_count,
193 * Increases the reference count on @tz.
195 * Returns: a new reference to @tz.
200 g_time_zone_ref (GTimeZone *tz)
202 g_assert (tz->ref_count > 0);
204 g_atomic_int_inc (&tz->ref_count);
209 /* fake zoneinfo creation (for RFC3339/ISO 8601 timezones) {{{1 */
211 * parses strings of the form 'hh' 'hhmm' or 'hh:mm' where:
216 parse_time (const gchar *time_,
219 if (*time_ < '0' || '2' < *time_)
222 *offset = 10 * 60 * 60 * (*time_++ - '0');
224 if (*time_ < '0' || '9' < *time_)
227 *offset += 60 * 60 * (*time_++ - '0');
229 if (*offset > 23 * 60 * 60)
238 if (*time_ < '0' || '5' < *time_)
241 *offset += 10 * 60 * (*time_++ - '0');
243 if (*time_ < '0' || '9' < *time_)
246 *offset += 60 * (*time_++ - '0');
248 return *time_ == '\0';
252 parse_constant_offset (const gchar *name,
262 return parse_time (name, offset);
265 if (parse_time (name, offset))
277 zone_for_constant_offset (const gchar *name)
279 const gchar fake_zoneinfo_headers[] =
280 "TZif" "2..." "...." "...." "...."
281 "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0"
282 "TZif" "2..." "...." "...." "...."
283 "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\1" "\0\0\0\7";
285 struct tzhead headers[2];
291 if (name == NULL || !parse_constant_offset (name, &offset))
294 offset = GINT32_TO_BE (offset);
296 fake = g_malloc (sizeof *fake);
297 memcpy (fake, fake_zoneinfo_headers, sizeof fake_zoneinfo_headers);
298 memcpy (&fake->info.tt_gmtoff, &offset, sizeof offset);
299 fake->info.tt_isdst = FALSE;
300 fake->info.tt_abbrind = 0;
301 strcpy (fake->abbr, name);
303 return g_bytes_new_take (fake, sizeof *fake);
306 /* Construction {{{1 */
309 * @identifier: (allow-none): a timezone identifier
311 * Creates a #GTimeZone corresponding to @identifier.
313 * @identifier can either be an RFC3339/ISO 8601 time offset or
314 * something that would pass as a valid value for the
315 * <varname>TZ</varname> environment variable (including %NULL).
317 * Valid RFC3339 time offsets are <literal>"Z"</literal> (for UTC) or
318 * <literal>"±hh:mm"</literal>. ISO 8601 additionally specifies
319 * <literal>"±hhmm"</literal> and <literal>"±hh"</literal>.
321 * The <varname>TZ</varname> environment variable typically corresponds
322 * to the name of a file in the zoneinfo database, but there are many
323 * other possibilities. Note that those other possibilities are not
324 * currently implemented, but are planned.
326 * g_time_zone_new_local() calls this function with the value of the
327 * <varname>TZ</varname> environment variable. This function itself is
328 * independent of the value of <varname>TZ</varname>, but if @identifier
329 * is %NULL then <filename>/etc/localtime</filename> will be consulted
330 * to discover the correct timezone.
333 * url='http://tools.ietf.org/html/rfc3339#section-5.6'>RFC3339
334 * §5.6</ulink> for a precise definition of valid RFC3339 time offsets
335 * (the <varname>time-offset</varname> expansion) and ISO 8601 for the
336 * full list of valid time offsets. See <ulink
337 * url='http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html'>The
338 * GNU C Library manual</ulink> for an explanation of the possible
339 * values of the <varname>TZ</varname> environment variable.
341 * You should release the return value by calling g_time_zone_unref()
342 * when you are done with it.
344 * Returns: the requested timezone
349 g_time_zone_new (const gchar *identifier)
355 if (time_zones == NULL)
356 time_zones = g_hash_table_new (g_str_hash, g_str_equal);
359 tz = g_hash_table_lookup (time_zones, identifier);
365 tz = g_slice_new0 (GTimeZone);
366 tz->name = g_strdup (identifier);
369 tz->zoneinfo = zone_for_constant_offset (identifier);
371 if (tz->zoneinfo == NULL)
375 /* identifier can be a relative or absolute path name;
376 if relative, it is interpreted starting from /usr/share/zoneinfo
377 while the POSIX standard says it should start with :,
378 glibc allows both syntaxes, so we should too */
379 if (identifier != NULL)
383 tzdir = getenv ("TZDIR");
385 tzdir = "/usr/share/zoneinfo";
387 if (*identifier == ':')
390 if (g_path_is_absolute (identifier))
391 filename = g_strdup (identifier);
393 filename = g_build_filename (tzdir, identifier, NULL);
396 filename = g_strdup ("/etc/localtime");
398 file = g_mapped_file_new (filename, FALSE, NULL);
401 tz->zoneinfo = g_bytes_new_with_free_func (g_mapped_file_get_contents (file),
402 g_mapped_file_get_length (file),
403 (GDestroyNotify)g_mapped_file_unref,
404 g_mapped_file_ref (file));
405 g_mapped_file_unref (file);
410 if (tz->zoneinfo != NULL)
413 const struct tzhead *header = g_bytes_get_data (tz->zoneinfo, &size);
415 if (size < sizeof (struct tzhead) || memcmp (header, "TZif", 4))
417 g_bytes_unref (tz->zoneinfo);
423 tz->version = header->tzh_version;
424 /* we trust the file completely. */
425 if (tz->version == '2')
426 tz->header = (const struct tzhead *)
427 (((const gchar *) (header + 1)) +
428 guint32_from_be(header->tzh_ttisgmtcnt) +
429 guint32_from_be(header->tzh_ttisstdcnt) +
430 8 * guint32_from_be(header->tzh_leapcnt) +
431 5 * guint32_from_be(header->tzh_timecnt) +
432 6 * guint32_from_be(header->tzh_typecnt) +
433 guint32_from_be(header->tzh_charcnt));
437 typecnt = guint32_from_be (tz->header->tzh_typecnt);
438 tz->timecnt = guint32_from_be (tz->header->tzh_timecnt);
439 if (tz->version == '2')
441 tz->trans.two = (gconstpointer) (tz->header + 1);
442 tz->indices = (gconstpointer) (tz->trans.two + tz->timecnt);
446 tz->trans.one = (gconstpointer) (tz->header + 1);
447 tz->indices = (gconstpointer) (tz->trans.one + tz->timecnt);
449 tz->infos = (gconstpointer) (tz->indices + tz->timecnt);
450 tz->abbrs = (gconstpointer) (tz->infos + typecnt);
455 g_hash_table_insert (time_zones, tz->name, tz);
457 g_atomic_int_inc (&tz->ref_count);
458 G_UNLOCK (time_zones);
464 * g_time_zone_new_utc:
466 * Creates a #GTimeZone corresponding to UTC.
468 * This is equivalent to calling g_time_zone_new() with a value like
469 * "Z", "UTC", "+00", etc.
471 * You should release the return value by calling g_time_zone_unref()
472 * when you are done with it.
474 * Returns: the universal timezone
479 g_time_zone_new_utc (void)
481 return g_time_zone_new ("UTC");
485 * g_time_zone_new_local:
487 * Creates a #GTimeZone corresponding to local time. The local time
488 * zone may change between invocations to this function; for example,
489 * if the system administrator changes it.
491 * This is equivalent to calling g_time_zone_new() with the value of the
492 * <varname>TZ</varname> environment variable (including the possibility
495 * You should release the return value by calling g_time_zone_unref()
496 * when you are done with it.
498 * Returns: the local timezone
503 g_time_zone_new_local (void)
505 return g_time_zone_new (getenv ("TZ"));
508 /* Internal helpers {{{1 */
509 inline static const struct ttinfo *
510 interval_info (GTimeZone *tz,
514 return tz->infos + tz->indices[interval - 1];
520 interval_start (GTimeZone *tz,
525 if (tz->version == '2')
526 return gint64_from_be (tz->trans.two[interval - 1]);
528 return gint32_from_be (tz->trans.one[interval - 1]);
534 interval_end (GTimeZone *tz,
537 if (interval < tz->timecnt)
539 if (tz->version == '2')
540 return gint64_from_be (tz->trans.two[interval]) - 1;
542 return gint32_from_be (tz->trans.one[interval]) - 1;
548 interval_offset (GTimeZone *tz,
551 return gint32_from_be (interval_info (tz, interval)->tt_gmtoff);
554 inline static gboolean
555 interval_isdst (GTimeZone *tz,
558 return interval_info (tz, interval)->tt_isdst;
562 interval_abbrind (GTimeZone *tz,
565 return interval_info (tz, interval)->tt_abbrind;
569 interval_local_start (GTimeZone *tz,
573 return interval_start (tz, interval) + interval_offset (tz, interval);
579 interval_local_end (GTimeZone *tz,
582 if (interval < tz->timecnt)
583 return interval_end (tz, interval) + interval_offset (tz, interval);
589 interval_valid (GTimeZone *tz,
592 return interval <= tz->timecnt;
595 /* g_time_zone_find_interval() {{{1 */
598 * g_time_zone_adjust_time:
600 * @type: the #GTimeType of @time_
601 * @time_: a pointer to a number of seconds since January 1, 1970
603 * Finds an interval within @tz that corresponds to the given @time_,
604 * possibly adjusting @time_ if required to fit into an interval.
605 * The meaning of @time_ depends on @type.
607 * This function is similar to g_time_zone_find_interval(), with the
608 * difference that it always succeeds (by making the adjustments
611 * In any of the cases where g_time_zone_find_interval() succeeds then
612 * this function returns the same value, without modifying @time_.
614 * This function may, however, modify @time_ in order to deal with
615 * non-existent times. If the non-existent local @time_ of 02:30 were
616 * requested on March 14th 2010 in Toronto then this function would
617 * adjust @time_ to be 03:00 and return the interval containing the
620 * Returns: the interval containing @time_, never -1
625 g_time_zone_adjust_time (GTimeZone *tz,
631 if (tz->zoneinfo == NULL)
634 /* find the interval containing *time UTC
635 * TODO: this could be binary searched (or better) */
636 for (i = 0; i < tz->timecnt; i++)
637 if (*time_ <= interval_end (tz, i))
640 g_assert (interval_start (tz, i) <= *time_ && *time_ <= interval_end (tz, i));
642 if (type != G_TIME_TYPE_UNIVERSAL)
644 if (*time_ < interval_local_start (tz, i))
645 /* if time came before the start of this interval... */
649 /* if it's not in the previous interval... */
650 if (*time_ > interval_local_end (tz, i))
652 /* it doesn't exist. fast-forward it. */
654 *time_ = interval_local_start (tz, i);
658 else if (*time_ > interval_local_end (tz, i))
659 /* if time came after the end of this interval... */
663 /* if it's not in the next interval... */
664 if (*time_ < interval_local_start (tz, i))
665 /* it doesn't exist. fast-forward it. */
666 *time_ = interval_local_start (tz, i);
669 else if (interval_isdst (tz, i) != type)
670 /* it's in this interval, but dst flag doesn't match.
671 * check neighbours for a better fit. */
673 if (i && *time_ <= interval_local_end (tz, i - 1))
676 else if (i < tz->timecnt &&
677 *time_ >= interval_local_start (tz, i + 1))
686 * g_time_zone_find_interval:
688 * @type: the #GTimeType of @time_
689 * @time_: a number of seconds since January 1, 1970
691 * Finds an the interval within @tz that corresponds to the given @time_.
692 * The meaning of @time_ depends on @type.
694 * If @type is %G_TIME_TYPE_UNIVERSAL then this function will always
695 * succeed (since universal time is monotonic and continuous).
697 * Otherwise @time_ is treated is local time. The distinction between
698 * %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in
699 * the case that the given @time_ is ambiguous. In Toronto, for example,
700 * 01:30 on November 7th 2010 occurred twice (once inside of daylight
701 * savings time and the next, an hour later, outside of daylight savings
702 * time). In this case, the different value of @type would result in a
703 * different interval being returned.
705 * It is still possible for this function to fail. In Toronto, for
706 * example, 02:00 on March 14th 2010 does not exist (due to the leap
707 * forward to begin daylight savings time). -1 is returned in that
710 * Returns: the interval containing @time_, or -1 in case of failure
715 g_time_zone_find_interval (GTimeZone *tz,
721 if (tz->zoneinfo == NULL)
724 for (i = 0; i < tz->timecnt; i++)
725 if (time_ <= interval_end (tz, i))
728 if (type == G_TIME_TYPE_UNIVERSAL)
731 if (time_ < interval_local_start (tz, i))
733 if (time_ > interval_local_end (tz, --i))
737 else if (time_ > interval_local_end (tz, i))
739 if (time_ < interval_local_start (tz, ++i))
743 else if (interval_isdst (tz, i) != type)
745 if (i && time_ <= interval_local_end (tz, i - 1))
748 else if (i < tz->timecnt && time_ >= interval_local_start (tz, i + 1))
755 /* Public API accessors {{{1 */
758 * g_time_zone_get_abbreviation:
760 * @interval: an interval within the timezone
762 * Determines the time zone abbreviation to be used during a particular
763 * @interval of time in the time zone @tz.
765 * For example, in Toronto this is currently "EST" during the winter
766 * months and "EDT" during the summer months when daylight savings time
769 * Returns: the time zone abbreviation, which belongs to @tz
774 g_time_zone_get_abbreviation (GTimeZone *tz,
777 g_return_val_if_fail (interval_valid (tz, interval), NULL);
779 if (tz->header == NULL)
782 return tz->abbrs + interval_abbrind (tz, interval);
786 * g_time_zone_get_offset:
788 * @interval: an interval within the timezone
790 * Determines the offset to UTC in effect during a particular @interval
791 * of time in the time zone @tz.
793 * The offset is the number of seconds that you add to UTC time to
794 * arrive at local time for @tz (ie: negative numbers for time zones
795 * west of GMT, positive numbers for east).
797 * Returns: the number of seconds that should be added to UTC to get the
803 g_time_zone_get_offset (GTimeZone *tz,
806 g_return_val_if_fail (interval_valid (tz, interval), 0);
808 if (tz->header == NULL)
811 return interval_offset (tz, interval);
815 * g_time_zone_is_dst:
817 * @interval: an interval within the timezone
819 * Determines if daylight savings time is in effect during a particular
820 * @interval of time in the time zone @tz.
822 * Returns: %TRUE if daylight savings time is in effect
827 g_time_zone_is_dst (GTimeZone *tz,
830 g_return_val_if_fail (interval_valid (tz, interval), FALSE);
832 if (tz->header == NULL)
835 return interval_isdst (tz, interval);
839 /* vim:set foldmethod=marker: */