glib/gtimezone.c

   1 /*
   2  * Copyright © 2010 Codethink Limited
   3  *
   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.
   8  *
   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.
  13  *
  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.
  18  *
  19  * Author: Ryan Lortie <desrt@desrt.ca>
  20  */
  21
  22 /* Prologue {{{1 */
  23
  24 #include "gtimezone.h"
  25
  26 #include <string.h>
  27 #include <stdlib.h>
  28 #include <signal.h>
  29
  30 #include "gmappedfile.h"
  31 #include "gtestutils.h"
  32 #include "gfileutils.h"
  33 #include "gstrfuncs.h"
  34 #include "ghash.h"
  35 #include "gthread.h"
  36 #include "gbuffer.h"
  37
  38 /**
  39  * SECTION:timezone
  40  * @title: GTimeZone
  41  * @short_description: A structure representing a time zone
  42  * @see_also: #GDateTime
  43  *
  44  * #GTimeZone is a structure that represents a time zone, at no
  45  * particular point in time.  It is refcounted and immutable.
  46  *
  47  * A time zone contains a number of intervals.  Each interval has
  48  * an abbreviation to describe it, an offet to UTC and a flag indicating
  49  * if the daylight savings time is in effect during that interval.  A
  50  * time zone always has at least one interval -- interval 0.
  51  *
  52  * Every UTC time is contained within exactly one interval, but a given
  53  * local time may be contained within zero, one or two intervals (due to
  54  * incontinuities associated with daylight savings time).
  55  *
  56  * An interval may refer to a specific period of time (eg: the duration
  57  * of daylight savings time during 2010) or it may refer to many periods
  58  * of time that share the same properties (eg: all periods of daylight
  59  * savings time).  It is also possible (usually for political reasons)
  60  * that some properties (like the abbreviation) change between intervals
  61  * without other properties changing.
  62  *
  63  * #GTimeZone is available since GLib 2.26.
  64  */
  65
  66 /**
  67  * GTimeZone:
  68  *
  69  * #GDateTime is an opaque structure whose members cannot be accessed
  70  * directly.
  71  *
  72  * Since: 2.26
  73  **/
  74
  75 /* zoneinfo file format {{{1 */
  76
  77 /* unaligned */
  78 typedef struct { gchar bytes[8]; } gint64_be;
  79 typedef struct { gchar bytes[4]; } gint32_be;
  80 typedef struct { gchar bytes[4]; } guint32_be;
  81
  82 static inline gint64 gint64_from_be (const gint64_be be) {
  83   gint64 tmp; memcpy (&tmp, &be, sizeof tmp); return GINT64_FROM_BE (tmp);
  84 }
  85
  86 static inline gint32 gint32_from_be (const gint32_be be) {
  87   gint32 tmp; memcpy (&tmp, &be, sizeof tmp); return GINT32_FROM_BE (tmp);
  88 }
  89
  90 static inline guint32 guint32_from_be (const guint32_be be) {
  91   guint32 tmp; memcpy (&tmp, &be, sizeof tmp); return GUINT32_FROM_BE (tmp);
  92 }
  93
  94 struct tzhead
  95 {
  96   gchar      tzh_magic[4];
  97   gchar      tzh_version;
  98   guchar     tzh_reserved[15];
  99
 100   guint32_be tzh_ttisgmtcnt;
 101   guint32_be tzh_ttisstdcnt;
 102   guint32_be tzh_leapcnt;
 103   guint32_be tzh_timecnt;
 104   guint32_be tzh_typecnt;
 105   guint32_be tzh_charcnt;
 106 };
 107
 108 struct ttinfo
 109 {
 110   gint32_be tt_gmtoff;
 111   guint8    tt_isdst;
 112   guint8    tt_abbrind;
 113 };
 114
 115 /* GTimeZone structure and lifecycle {{{1 */
 116 struct _GTimeZone
 117 {
 118   gchar   *name;
 119
 120   GBuffer *zoneinfo;
 121
 122   const struct tzhead *header;
 123   const struct ttinfo *infos;
 124   const gint64_be     *trans;
 125   const guint8        *indices;
 126   const gchar         *abbrs;
 127   gint                 timecnt;
 128
 129   gint     ref_count;
 130 };
 131
 132 G_LOCK_DEFINE_STATIC (local_timezone);
 133 static GTimeZone *local_timezone;
 134
 135 G_LOCK_DEFINE_STATIC (time_zones);
 136 static GHashTable/*<string?, GTimeZone>*/ *time_zones;
 137
 138 /**
 139  * g_time_zone_unref:
 140  * @tz: a #GTimeZone
 141  *
 142  * Decreases the reference count on @tz.
 143  *
 144  * Since: 2.26
 145  **/
 146 void
 147 g_time_zone_unref (GTimeZone *tz)
 148 {
 149   int ref_count;
 150
 151 again:
 152   ref_count = g_atomic_int_get (&tz->ref_count);
 153
 154   g_assert (ref_count > 0);
 155
 156   if (ref_count == 1)
 157     {
 158       if G_UNLIKELY (tz == local_timezone)
 159         {
 160           g_critical ("The last reference on the local timezone was just "
 161                       "dropped, but GTimeZone itself still owns one.  This "
 162                       "means that g_time_zone_unref() was called too many "
 163                       "times.  Returning without lowering the refcount.");
 164
 165           /* We don't want to just inc this back again since if there
 166            * are refcounting bugs in the code then maybe we are already
 167            * at -1 and inc will just take us back to 0.  Set to 1 to be
 168            * sure.
 169            */
 170           return;
 171         }
 172
 173       if (tz->name != NULL)
 174         {
 175           G_LOCK(time_zones);
 176
 177           /* someone else might have grabbed a ref in the meantime */
 178           if G_UNLIKELY (g_atomic_int_get (&tz->ref_count) != 1)
 179             {
 180               G_UNLOCK(time_zones);
 181               goto again;
 182             }
 183
 184           g_hash_table_remove (time_zones, tz->name);
 185           G_UNLOCK(time_zones);
 186         }
 187
 188       if (tz->zoneinfo)
 189         g_buffer_unref (tz->zoneinfo);
 190
 191       g_free (tz->name);
 192
 193       g_slice_free (GTimeZone, tz);
 194     }
 195
 196   else if G_UNLIKELY (!g_atomic_int_compare_and_exchange (&tz->ref_count,
 197                                                           ref_count,
 198                                                           ref_count - 1))
 199     goto again;
 200 }
 201
 202 /**
 203  * g_time_zone_ref:
 204  * @tz: a #GTimeZone
 205  *
 206  * Increases the reference count on @tz.
 207  *
 208  * Returns: a new reference to @tz.
 209  *
 210  * Since: 2.26
 211  **/
 212 GTimeZone *
 213 g_time_zone_ref (GTimeZone *tz)
 214 {
 215   g_assert (tz->ref_count > 0);
 216
 217   g_atomic_int_inc (&tz->ref_count);
 218
 219   return tz;
 220 }
 221
 222 /* fake zoneinfo creation (for RFC3339/ISO 8601 timezones) {{{1 */
 223 /*
 224  * parses strings of the form 'hh' 'hhmm' or 'hh:mm' where:
 225  *  - hh is 00 to 23
 226  *  - mm is 00 to 59
 227  */
 228 static gboolean
 229 parse_time (const gchar *time_,
 230             gint32      *offset)
 231 {
 232   if (*time_ < '0' || '2' < *time_)
 233     return FALSE;
 234
 235   *offset = 10 * 60 * 60 * (*time_++ - '0');
 236
 237   if (*time_ < '0' || '9' < *time_)
 238     return FALSE;
 239
 240   *offset += 60 * 60 * (*time_++ - '0');
 241
 242   if (*offset > 23 * 60 * 60)
 243     return FALSE;
 244
 245   if (*time_ == '\0')
 246     return TRUE;
 247
 248   if (*time_ == ':')
 249     time_++;
 250
 251   if (*time_ < '0' || '5' < *time_)
 252     return FALSE;
 253
 254   *offset += 10 * 60 * (*time_++ - '0');
 255
 256   if (*time_ < '0' || '9' < *time_)
 257     return FALSE;
 258
 259   *offset += 60 * (*time_++ - '0');
 260
 261   return *time_ == '\0';
 262 }
 263
 264 static gboolean
 265 parse_constant_offset (const gchar *name,
 266                        gint32      *offset)
 267 {
 268   switch (*name++)
 269     {
 270     case 'Z':
 271       *offset = 0;
 272       return !*name;
 273
 274     case '+':
 275       return parse_time (name, offset);
 276
 277     case '-':
 278       if (parse_time (name, offset))
 279         {
 280           *offset = -*offset;
 281           return TRUE;
 282         }
 283
 284     default:
 285       return FALSE;
 286     }
 287 }
 288
 289 static GBuffer *
 290 zone_for_constant_offset (const gchar *name)
 291 {
 292   const gchar fake_zoneinfo_headers[] =
 293     "TZif" "2..." "...." "...." "...."
 294     "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0"
 295     "TZif" "2..." "...." "...." "...."
 296     "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\1" "\0\0\0\7";
 297   struct {
 298     struct tzhead headers[2];
 299     struct ttinfo info;
 300     gchar abbr[8];
 301   } *fake;
 302   gint32 offset;
 303
 304   if (name == NULL || !parse_constant_offset (name, &offset))
 305     return NULL;
 306
 307   offset = GINT32_TO_BE (offset);
 308
 309   fake = g_malloc (sizeof *fake);
 310   memcpy (fake, fake_zoneinfo_headers, sizeof fake_zoneinfo_headers);
 311   memcpy (&fake->info.tt_gmtoff, &offset, sizeof offset);
 312   fake->info.tt_isdst = FALSE;
 313   fake->info.tt_abbrind = 0;
 314   strcpy (fake->abbr, name);
 315
 316   return g_buffer_new_take_data (fake, sizeof *fake);
 317 }
 318
 319 /* Construction {{{1 */
 320 /**
 321  * g_time_zone_new:
 322  * @identifier: (allow-none): a timezone identifier
 323  *
 324  * Creates a #GTimeZone corresponding to @identifier.
 325  *
 326  * @identifier can either be an RFC3339/ISO 8601 time offset or
 327  * something that would pass as a valid value for the
 328  * <varname>TZ</varname> environment variable (including %NULL).
 329  *
 330  * Valid RFC3339 time offsets are <literal>"Z"</literal> (for UTC) or
 331  * <literal>"±hh:mm"</literal>.  ISO 8601 additionally specifies
 332  * <literal>"±hhmm"</literal> and <literal>"±hh"</literal>.
 333  *
 334  * The <varname>TZ</varname> environment variable typically corresponds
 335  * to the name of a file in the zoneinfo database, but there are many
 336  * other possibilities.  Note that those other possibilities are not
 337  * currently implemented, but are planned.
 338  *
 339  * g_time_zone_new_local() calls this function with the value of the
 340  * <varname>TZ</varname> environment variable.  This function itself is
 341  * independent of the value of <varname>TZ</varname>, but if @identifier
 342  * is %NULL then <filename>/etc/localtime</filename> will be consulted
 343  * to discover the correct timezone.
 344  *
 345  * See <ulink
 346  * url='http://tools.ietf.org/html/rfc3339#section-5.6'>RFC3339
 347  * §5.6</ulink> for a precise definition of valid RFC3339 time offsets
 348  * (the <varname>time-offset</varname> expansion) and ISO 8601 for the
 349  * full list of valid time offsets.  See <ulink
 350  * url='http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html'>The
 351  * GNU C Library manual</ulink> for an explanation of the possible
 352  * values of the <varname>TZ</varname> environment variable.
 353  *
 354  * You should release the return value by calling g_time_zone_unref()
 355  * when you are done with it.
 356  *
 357  * Returns: the requested timezone
 358  *
 359  * Since: 2.26
 360  **/
 361 GTimeZone *
 362 g_time_zone_new (const gchar *identifier)
 363 {
 364   GTimeZone *tz;
 365
 366   G_LOCK (time_zones);
 367   if (time_zones == NULL)
 368     time_zones = g_hash_table_new (g_str_hash, g_str_equal);
 369
 370   if (identifier)
 371     tz = g_hash_table_lookup (time_zones, identifier);
 372   else
 373     tz = NULL;
 374
 375   if (tz == NULL)
 376     {
 377       tz = g_slice_new0 (GTimeZone);
 378       tz->name = g_strdup (identifier);
 379       tz->ref_count = 0;
 380
 381       tz->zoneinfo = zone_for_constant_offset (identifier);
 382
 383       if (tz->zoneinfo == NULL)
 384         {
 385           gchar *filename;
 386
 387           if (identifier != NULL)
 388             {
 389               const gchar *tzdir;
 390
 391               tzdir = getenv ("TZDIR");
 392               if (tzdir == NULL)
 393                 tzdir = "/usr/share/zoneinfo";
 394
 395               filename = g_build_filename (tzdir, identifier, NULL);
 396             }
 397           else
 398             filename = g_strdup ("/etc/localtime");
 399
 400           tz->zoneinfo = (GBuffer *) g_mapped_file_new (filename, FALSE, NULL);
 401           g_free (filename);
 402         }
 403
 404       if (tz->zoneinfo != NULL)
 405         {
 406           const struct tzhead *header = tz->zoneinfo->data;
 407           gsize size = tz->zoneinfo->size;
 408
 409           /* we only bother to support version 2 */
 410           if (size < sizeof (struct tzhead) || memcmp (header, "TZif2", 5))
 411             {
 412               g_buffer_unref (tz->zoneinfo);
 413               tz->zoneinfo = NULL;
 414             }
 415           else
 416             {
 417               gint typecnt;
 418
 419               /* we trust the file completely. */
 420               tz->header = (const struct tzhead *)
 421                 (((const gchar *) (header + 1)) +
 422                   guint32_from_be(header->tzh_ttisgmtcnt) +
 423                   guint32_from_be(header->tzh_ttisstdcnt) +
 424                   8 * guint32_from_be(header->tzh_leapcnt) +
 425                   5 * guint32_from_be(header->tzh_timecnt) +
 426                   6 * guint32_from_be(header->tzh_typecnt) +
 427                   guint32_from_be(header->tzh_charcnt));
 428
 429               typecnt     = guint32_from_be (tz->header->tzh_typecnt);
 430               tz->timecnt = guint32_from_be (tz->header->tzh_timecnt);
 431               tz->trans   = (gconstpointer) (tz->header + 1);
 432               tz->indices = (gconstpointer) (tz->trans + tz->timecnt);
 433               tz->infos   = (gconstpointer) (tz->indices + tz->timecnt);
 434               tz->abbrs   = (gconstpointer) (tz->infos + typecnt);
 435             }
 436         }
 437
 438       if (identifier)
 439         g_hash_table_insert (time_zones, tz->name, tz);
 440     }
 441   g_atomic_int_inc (&tz->ref_count);
 442   G_UNLOCK (time_zones);
 443
 444   return tz;
 445 }
 446
 447 /**
 448  * g_time_zone_new_utc:
 449  *
 450  * Creates a #GTimeZone corresponding to UTC.
 451  *
 452  * This is equivalent to calling g_time_zone_new() with a value like
 453  * "Z", "UTC", "+00", etc.
 454  *
 455  * You should release the return value by calling g_time_zone_unref()
 456  * when you are done with it.
 457  *
 458  * Returns: the universal timezone
 459  *
 460  * Since: 2.26
 461  **/
 462 GTimeZone *
 463 g_time_zone_new_utc (void)
 464 {
 465   return g_time_zone_new ("UTC");
 466 }
 467
 468 /**
 469  * g_time_zone_new_local:
 470  *
 471  * Creates a #GTimeZone corresponding to local time.
 472  *
 473  * This is equivalent to calling g_time_zone_new() with the value of the
 474  * <varname>TZ</varname> environment variable (including the possibility
 475  * of %NULL).  Changes made to <varname>TZ</varname> after the first
 476  * call to this function may or may not be noticed by future calls.
 477  *
 478  * You should release the return value by calling g_time_zone_unref()
 479  * when you are done with it.
 480  *
 481  * Returns: the local timezone
 482  *
 483  * Since: 2.26
 484  **/
 485 GTimeZone *
 486 g_time_zone_new_local (void)
 487 {
 488   GTimeZone *result;
 489
 490   G_LOCK (local_timezone);
 491   if (local_timezone == NULL)
 492     local_timezone = g_time_zone_new (getenv ("TZ"));
 493
 494   result = g_time_zone_ref (local_timezone);
 495   G_UNLOCK (local_timezone);
 496
 497   return result;
 498 }
 499
 500 /**
 501  * g_time_zone_refresh_local:
 502  *
 503  * Notifies #GTimeZone that the local timezone may have changed.
 504  *
 505  * In response, #GTimeZone will drop its cache of the local time zone.
 506  * No existing #GTimeZone will be modified and no #GDateTime will change
 507  * its timezone but future calls to g_time_zone_new_local() will start
 508  * returning the new timezone.
 509  *
 510  * #GTimeZone does no monitoring of the local timezone on its own, which
 511  * is why you have to call this function to notify it of the change.
 512  *
 513  * If you use #GTimeZoneMonitor to watch for changes then this function
 514  * will automatically be called for you.
 515  **/
 516 void
 517 g_time_zone_refresh_local (void)
 518 {
 519   GTimeZone *drop_this_ref = NULL;
 520
 521   G_LOCK (local_timezone);
 522   drop_this_ref = local_timezone;
 523   local_timezone = NULL;
 524   G_UNLOCK (local_timezone);
 525
 526   if (drop_this_ref)
 527     g_time_zone_unref (drop_this_ref);
 528 }
 529
 530 /* Internal helpers {{{1 */
 531 inline static const struct ttinfo *
 532 interval_info (GTimeZone *tz,
 533                gint       interval)
 534 {
 535   if (interval)
 536     return tz->infos + tz->indices[interval - 1];
 537
 538   return tz->infos;
 539 }
 540
 541 inline static gint64
 542 interval_start (GTimeZone *tz,
 543                 gint       interval)
 544 {
 545   if (interval)
 546     return gint64_from_be (tz->trans[interval - 1]);
 547
 548   return G_MININT64;
 549 }
 550
 551 inline static gint64
 552 interval_end (GTimeZone *tz,
 553               gint       interval)
 554 {
 555   if (interval < tz->timecnt)
 556     return gint64_from_be (tz->trans[interval]) - 1;
 557
 558   return G_MAXINT64;
 559 }
 560
 561 inline static gint32
 562 interval_offset (GTimeZone *tz,
 563                  gint       interval)
 564 {
 565   return gint32_from_be (interval_info (tz, interval)->tt_gmtoff);
 566 }
 567
 568 inline static gboolean
 569 interval_isdst (GTimeZone *tz,
 570                 gint       interval)
 571 {
 572   return interval_info (tz, interval)->tt_isdst;
 573 }
 574
 575 inline static guint8
 576 interval_abbrind (GTimeZone *tz,
 577                   gint       interval)
 578 {
 579   return interval_info (tz, interval)->tt_abbrind;
 580 }
 581
 582 inline static gint64
 583 interval_local_start (GTimeZone *tz,
 584                       gint       interval)
 585 {
 586   if (interval)
 587     return interval_start (tz, interval) + interval_offset (tz, interval);
 588
 589   return G_MININT64;
 590 }
 591
 592 inline static gint64
 593 interval_local_end (GTimeZone *tz,
 594                     gint       interval)
 595 {
 596   if (interval < tz->timecnt)
 597     return interval_end (tz, interval) + interval_offset (tz, interval);
 598
 599   return G_MAXINT64;
 600 }
 601
 602 static gboolean
 603 interval_valid (GTimeZone *tz,
 604                 gint       interval)
 605 {
 606   return interval <= tz->timecnt;
 607 }
 608
 609 /* g_time_zone_find_interval() {{{1 */
 610
 611 /**
 612  * g_time_zone_adjust_time:
 613  * @tz: a #GTimeZone
 614  * @type: the #GTimeType of @time_
 615  * @time_: a pointer to a number of seconds since January 1, 1970
 616  *
 617  * Finds an interval within @tz that corresponds to the given @time_,
 618  * possibly adjusting @time_ if required to fit into an interval.
 619  * The meaning of @time_ depends on @type.
 620  *
 621  * This function is similar to g_time_zone_find_interval(), with the
 622  * difference that it always succeeds (by making the adjustments
 623  * described below).
 624  *
 625  * In any of the cases where g_time_zone_find_interval() succeeds then
 626  * this function returns the same value, without modifying @time_.
 627  *
 628  * This function may, however, modify @time_ in order to deal with
 629  * non-existent times.  If the non-existent local @time_ of 02:30 were
 630  * requested on March 13th 2010 in Toronto then this function would
 631  * adjust @time_ to be 03:00 and return the interval containing the
 632  * adjusted time.
 633  *
 634  * Returns: the interval containing @time_, never -1
 635  *
 636  * Since: 2.26
 637  **/
 638 gint
 639 g_time_zone_adjust_time (GTimeZone *tz,
 640                          GTimeType  type,
 641                          gint64    *time_)
 642 {
 643   gint i;
 644
 645   if (tz->zoneinfo == NULL)
 646     return 0;
 647
 648   /* find the interval containing *time UTC
 649    * TODO: this could be binary searched (or better) */
 650   for (i = 0; i < tz->timecnt; i++)
 651     if (*time_ <= interval_end (tz, i))
 652       break;
 653
 654   g_assert (interval_start (tz, i) <= *time_ && *time_ <= interval_end (tz, i));
 655
 656   if (type != G_TIME_TYPE_UNIVERSAL)
 657     {
 658       if (*time_ < interval_local_start (tz, i))
 659         /* if time came before the start of this interval... */
 660         {
 661           i--;
 662
 663           /* if it's not in the previous interval... */
 664           if (*time_ > interval_local_end (tz, i))
 665             {
 666               /* it doesn't exist.  fast-forward it. */
 667               i++;
 668               *time_ = interval_local_start (tz, i);
 669             }
 670         }
 671
 672       else if (*time_ > interval_local_end (tz, i))
 673         /* if time came after the end of this interval... */
 674         {
 675           i++;
 676
 677           /* if it's not in the next interval... */
 678           if (*time_ < interval_local_start (tz, i))
 679             /* it doesn't exist.  fast-forward it. */
 680             *time_ = interval_local_start (tz, i);
 681         }
 682
 683       else if (interval_isdst (tz, i) != type)
 684         /* it's in this interval, but dst flag doesn't match.
 685          * check neighbours for a better fit. */
 686         {
 687           if (i && *time_ <= interval_local_end (tz, i - 1))
 688             i--;
 689
 690           else if (i < tz->timecnt &&
 691                    *time_ >= interval_local_start (tz, i + 1))
 692             i++;
 693         }
 694     }
 695
 696   return i;
 697 }
 698
 699 /**
 700  * g_time_zone_find_interval:
 701  * @tz: a #GTimeZone
 702  * @type: the #GTimeType of @time_
 703  * @time_: a number of seconds since January 1, 1970
 704  *
 705  * Finds an the interval within @tz that corresponds to the given @time_.
 706  * The meaning of @time_ depends on @type.
 707  *
 708  * If @type is %G_TIME_TYPE_UNIVERSAL then this function will always
 709  * succeed (since universal time is monotonic and continuous).
 710  *
 711  * Otherwise @time_ is treated is local time.  The distinction between
 712  * %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in
 713  * the case that the given @time_ is ambiguous.  In Toronto, for example,
 714  * 01:30 on November 7th 2010 occured twice (once inside of daylight
 715  * savings time and the next, an hour later, outside of daylight savings
 716  * time).  In this case, the different value of @type would result in a
 717  * different interval being returned.
 718  *
 719  * It is still possible for this function to fail.  In Toronto, for
 720  * example, 02:00 on March 14th 2010 does not exist (due to the leap
 721  * forward to begin daylight savings time).  -1 is returned in that
 722  * case.
 723  *
 724  * Returns: the interval containing @time_, or -1 in case of failure
 725  *
 726  * Since: 2.26
 727  */
 728 gint
 729 g_time_zone_find_interval (GTimeZone *tz,
 730                            GTimeType  type,
 731                            gint64     time_)
 732 {
 733   gint i;
 734
 735   if (tz->zoneinfo == NULL)
 736     return 0;
 737
 738   for (i = 0; i < tz->timecnt; i++)
 739     if (time_ <= interval_end (tz, i))
 740       break;
 741
 742   if (type == G_TIME_TYPE_UNIVERSAL)
 743     return i;
 744
 745   if (time_ < interval_local_start (tz, i))
 746     {
 747       if (time_ > interval_local_end (tz, --i))
 748         return -1;
 749     }
 750
 751   else if (time_ > interval_local_end (tz, i))
 752     {
 753       if (time_ < interval_local_start (tz, ++i))
 754         return -1;
 755     }
 756
 757   else if (interval_isdst (tz, i) != type)
 758     {
 759       if (i && time_ <= interval_local_end (tz, i - 1))
 760         i--;
 761
 762       else if (i < tz->timecnt && time_ >= interval_local_start (tz, i + 1))
 763         i++;
 764     }
 765
 766   return i;
 767 }
 768
 769 /* Public API accessors {{{1 */
 770
 771 /**
 772  * g_time_zone_get_abbreviation:
 773  * @tz: a #GTimeZone
 774  * @interval: an interval within the timezone
 775  *
 776  * Determines the time zone abbreviation to be used during a particular
 777  * @interval of time in the time zone @tz.
 778  *
 779  * For example, in Toronto this is currently "EST" during the winter
 780  * months and "EDT" during the summer months when daylight savings time
 781  * is in effect.
 782  *
 783  * Returns: the time zone abbreviation, which belongs to @tz
 784  *
 785  * Since: 2.26
 786  **/
 787 const gchar *
 788 g_time_zone_get_abbreviation (GTimeZone *tz,
 789                               gint       interval)
 790 {
 791   g_return_val_if_fail (interval_valid (tz, interval), NULL);
 792
 793   if (tz->header == NULL)
 794     return "UTC";
 795
 796   return tz->abbrs + interval_abbrind (tz, interval);
 797 }
 798
 799 /**
 800  * g_time_zone_get_offset:
 801  * @tz: a #GTimeZone
 802  * @interval: an interval within the timezone
 803  *
 804  * Determines the offset to UTC in effect during a particular @interval
 805  * of time in the time zone @tz.
 806  *
 807  * The offset is the number of seconds that you add to UTC time to
 808  * arrive at local time for @tz (ie: negative numbers for time zones
 809  * west of GMT, positive numbers for east).
 810  *
 811  * Returns: the number of seconds that should be added to UTC to get the
 812  *          local time in @tz
 813  *
 814  * Since: 2.26
 815  **/
 816 gint32
 817 g_time_zone_get_offset (GTimeZone *tz,
 818                         gint       interval)
 819 {
 820   g_return_val_if_fail (interval_valid (tz, interval), 0);
 821
 822   if (tz->header == NULL)
 823     return 0;
 824
 825   return interval_offset (tz, interval);
 826 }
 827
 828 /**
 829  * g_time_zone_is_dst:
 830  * @tz: a #GTimeZone
 831  * @interval: an interval within the timezone
 832  *
 833  * Determines if daylight savings time is in effect during a particular
 834  * @interval of time in the time zone @tz.
 835  *
 836  * Returns: %TRUE if daylight savings time is in effect
 837  *
 838  * Since: 2.26
 839  **/
 840 gboolean
 841 g_time_zone_is_dst (GTimeZone *tz,
 842                     gint       interval)
 843 {
 844   g_return_val_if_fail (interval_valid (tz, interval), FALSE);
 845
 846   if (tz->header == NULL)
 847     return FALSE;
 848
 849   return interval_isdst (tz, interval);
 850 }
 851
 852 /* Epilogue {{{1 */
 853 /* vim:set foldmethod=marker: */