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 "gbufferprivate.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 (time_zones);
 133 static GHashTable/*<string?, GTimeZone>*/ *time_zones;
 134
 135 /**
 136  * g_time_zone_unref:
 137  * @tz: a #GTimeZone
 138  *
 139  * Decreases the reference count on @tz.
 140  *
 141  * Since: 2.26
 142  **/
 143 void
 144 g_time_zone_unref (GTimeZone *tz)
 145 {
 146   int ref_count;
 147
 148 again:
 149   ref_count = g_atomic_int_get (&tz->ref_count);
 150
 151   g_assert (ref_count > 0);
 152
 153   if (ref_count == 1)
 154     {
 155       if (tz->name != NULL)
 156         {
 157           G_LOCK(time_zones);
 158
 159           /* someone else might have grabbed a ref in the meantime */
 160           if G_UNLIKELY (g_atomic_int_get (&tz->ref_count) != 1)
 161             {
 162               G_UNLOCK(time_zones);
 163               goto again;
 164             }
 165
 166           g_hash_table_remove (time_zones, tz->name);
 167           G_UNLOCK(time_zones);
 168         }
 169
 170       if (tz->zoneinfo)
 171         g_buffer_unref (tz->zoneinfo);
 172
 173       g_free (tz->name);
 174
 175       g_slice_free (GTimeZone, tz);
 176     }
 177
 178   else if G_UNLIKELY (!g_atomic_int_compare_and_exchange (&tz->ref_count,
 179                                                           ref_count,
 180                                                           ref_count - 1))
 181     goto again;
 182 }
 183
 184 /**
 185  * g_time_zone_ref:
 186  * @tz: a #GTimeZone
 187  *
 188  * Increases the reference count on @tz.
 189  *
 190  * Returns: a new reference to @tz.
 191  *
 192  * Since: 2.26
 193  **/
 194 GTimeZone *
 195 g_time_zone_ref (GTimeZone *tz)
 196 {
 197   g_assert (tz->ref_count > 0);
 198
 199   g_atomic_int_inc (&tz->ref_count);
 200
 201   return tz;
 202 }
 203
 204 /* fake zoneinfo creation (for RFC3339/ISO 8601 timezones) {{{1 */
 205 /*
 206  * parses strings of the form 'hh' 'hhmm' or 'hh:mm' where:
 207  *  - hh is 00 to 23
 208  *  - mm is 00 to 59
 209  */
 210 static gboolean
 211 parse_time (const gchar *time_,
 212             gint32      *offset)
 213 {
 214   if (*time_ < '0' || '2' < *time_)
 215     return FALSE;
 216
 217   *offset = 10 * 60 * 60 * (*time_++ - '0');
 218
 219   if (*time_ < '0' || '9' < *time_)
 220     return FALSE;
 221
 222   *offset += 60 * 60 * (*time_++ - '0');
 223
 224   if (*offset > 23 * 60 * 60)
 225     return FALSE;
 226
 227   if (*time_ == '\0')
 228     return TRUE;
 229
 230   if (*time_ == ':')
 231     time_++;
 232
 233   if (*time_ < '0' || '5' < *time_)
 234     return FALSE;
 235
 236   *offset += 10 * 60 * (*time_++ - '0');
 237
 238   if (*time_ < '0' || '9' < *time_)
 239     return FALSE;
 240
 241   *offset += 60 * (*time_++ - '0');
 242
 243   return *time_ == '\0';
 244 }
 245
 246 static gboolean
 247 parse_constant_offset (const gchar *name,
 248                        gint32      *offset)
 249 {
 250   switch (*name++)
 251     {
 252     case 'Z':
 253       *offset = 0;
 254       return !*name;
 255
 256     case '+':
 257       return parse_time (name, offset);
 258
 259     case '-':
 260       if (parse_time (name, offset))
 261         {
 262           *offset = -*offset;
 263           return TRUE;
 264         }
 265
 266     default:
 267       return FALSE;
 268     }
 269 }
 270
 271 static GBuffer *
 272 zone_for_constant_offset (const gchar *name)
 273 {
 274   const gchar fake_zoneinfo_headers[] =
 275     "TZif" "2..." "...." "...." "...."
 276     "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0"
 277     "TZif" "2..." "...." "...." "...."
 278     "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\0" "\0\0\0\1" "\0\0\0\7";
 279   struct {
 280     struct tzhead headers[2];
 281     struct ttinfo info;
 282     gchar abbr[8];
 283   } *fake;
 284   gint32 offset;
 285
 286   if (name == NULL || !parse_constant_offset (name, &offset))
 287     return NULL;
 288
 289   offset = GINT32_TO_BE (offset);
 290
 291   fake = g_malloc (sizeof *fake);
 292   memcpy (fake, fake_zoneinfo_headers, sizeof fake_zoneinfo_headers);
 293   memcpy (&fake->info.tt_gmtoff, &offset, sizeof offset);
 294   fake->info.tt_isdst = FALSE;
 295   fake->info.tt_abbrind = 0;
 296   strcpy (fake->abbr, name);
 297
 298   return g_buffer_new_take_data (fake, sizeof *fake);
 299 }
 300
 301 /* Construction {{{1 */
 302 /**
 303  * g_time_zone_new:
 304  * @identifier: (allow-none): a timezone identifier
 305  *
 306  * Creates a #GTimeZone corresponding to @identifier.
 307  *
 308  * @identifier can either be an RFC3339/ISO 8601 time offset or
 309  * something that would pass as a valid value for the
 310  * <varname>TZ</varname> environment variable (including %NULL).
 311  *
 312  * Valid RFC3339 time offsets are <literal>"Z"</literal> (for UTC) or
 313  * <literal>"±hh:mm"</literal>.  ISO 8601 additionally specifies
 314  * <literal>"±hhmm"</literal> and <literal>"±hh"</literal>.
 315  *
 316  * The <varname>TZ</varname> environment variable typically corresponds
 317  * to the name of a file in the zoneinfo database, but there are many
 318  * other possibilities.  Note that those other possibilities are not
 319  * currently implemented, but are planned.
 320  *
 321  * g_time_zone_new_local() calls this function with the value of the
 322  * <varname>TZ</varname> environment variable.  This function itself is
 323  * independent of the value of <varname>TZ</varname>, but if @identifier
 324  * is %NULL then <filename>/etc/localtime</filename> will be consulted
 325  * to discover the correct timezone.
 326  *
 327  * See <ulink
 328  * url='http://tools.ietf.org/html/rfc3339#section-5.6'>RFC3339
 329  * §5.6</ulink> for a precise definition of valid RFC3339 time offsets
 330  * (the <varname>time-offset</varname> expansion) and ISO 8601 for the
 331  * full list of valid time offsets.  See <ulink
 332  * url='http://www.gnu.org/s/libc/manual/html_node/TZ-Variable.html'>The
 333  * GNU C Library manual</ulink> for an explanation of the possible
 334  * values of the <varname>TZ</varname> environment variable.
 335  *
 336  * You should release the return value by calling g_time_zone_unref()
 337  * when you are done with it.
 338  *
 339  * Returns: the requested timezone
 340  *
 341  * Since: 2.26
 342  **/
 343 GTimeZone *
 344 g_time_zone_new (const gchar *identifier)
 345 {
 346   GTimeZone *tz;
 347
 348   G_LOCK (time_zones);
 349   if (time_zones == NULL)
 350     time_zones = g_hash_table_new (g_str_hash, g_str_equal);
 351
 352   if (identifier)
 353     tz = g_hash_table_lookup (time_zones, identifier);
 354   else
 355     tz = NULL;
 356
 357   if (tz == NULL)
 358     {
 359       tz = g_slice_new0 (GTimeZone);
 360       tz->name = g_strdup (identifier);
 361       tz->ref_count = 0;
 362
 363       tz->zoneinfo = zone_for_constant_offset (identifier);
 364
 365       if (tz->zoneinfo == NULL)
 366         {
 367           gchar *filename;
 368
 369           if (identifier != NULL)
 370             {
 371               const gchar *tzdir;
 372
 373               tzdir = getenv ("TZDIR");
 374               if (tzdir == NULL)
 375                 tzdir = "/usr/share/zoneinfo";
 376
 377               filename = g_build_filename (tzdir, identifier, NULL);
 378             }
 379           else
 380             filename = g_strdup ("/etc/localtime");
 381
 382           tz->zoneinfo = (GBuffer *) g_mapped_file_new (filename, FALSE, NULL);
 383           g_free (filename);
 384         }
 385
 386       if (tz->zoneinfo != NULL)
 387         {
 388           const struct tzhead *header = tz->zoneinfo->data;
 389           gsize size = tz->zoneinfo->size;
 390
 391           /* we only bother to support version 2 */
 392           if (size < sizeof (struct tzhead) || memcmp (header, "TZif2", 5))
 393             {
 394               g_buffer_unref (tz->zoneinfo);
 395               tz->zoneinfo = NULL;
 396             }
 397           else
 398             {
 399               gint typecnt;
 400
 401               /* we trust the file completely. */
 402               tz->header = (const struct tzhead *)
 403                 (((const gchar *) (header + 1)) +
 404                   guint32_from_be(header->tzh_ttisgmtcnt) +
 405                   guint32_from_be(header->tzh_ttisstdcnt) +
 406                   8 * guint32_from_be(header->tzh_leapcnt) +
 407                   5 * guint32_from_be(header->tzh_timecnt) +
 408                   6 * guint32_from_be(header->tzh_typecnt) +
 409                   guint32_from_be(header->tzh_charcnt));
 410
 411               typecnt     = guint32_from_be (tz->header->tzh_typecnt);
 412               tz->timecnt = guint32_from_be (tz->header->tzh_timecnt);
 413               tz->trans   = (gconstpointer) (tz->header + 1);
 414               tz->indices = (gconstpointer) (tz->trans + tz->timecnt);
 415               tz->infos   = (gconstpointer) (tz->indices + tz->timecnt);
 416               tz->abbrs   = (gconstpointer) (tz->infos + typecnt);
 417             }
 418         }
 419
 420       if (identifier)
 421         g_hash_table_insert (time_zones, tz->name, tz);
 422     }
 423   g_atomic_int_inc (&tz->ref_count);
 424   G_UNLOCK (time_zones);
 425
 426   return tz;
 427 }
 428
 429 /**
 430  * g_time_zone_new_utc:
 431  *
 432  * Creates a #GTimeZone corresponding to UTC.
 433  *
 434  * This is equivalent to calling g_time_zone_new() with a value like
 435  * "Z", "UTC", "+00", etc.
 436  *
 437  * You should release the return value by calling g_time_zone_unref()
 438  * when you are done with it.
 439  *
 440  * Returns: the universal timezone
 441  *
 442  * Since: 2.26
 443  **/
 444 GTimeZone *
 445 g_time_zone_new_utc (void)
 446 {
 447   return g_time_zone_new ("UTC");
 448 }
 449
 450 /**
 451  * g_time_zone_new_local:
 452  *
 453  * Creates a #GTimeZone corresponding to local time.  The local time
 454  * zone may change between invocations to this function; for example,
 455  * if the system administrator changes it.
 456  *
 457  * This is equivalent to calling g_time_zone_new() with the value of the
 458  * <varname>TZ</varname> environment variable (including the possibility
 459  * of %NULL).
 460  *
 461  * You should release the return value by calling g_time_zone_unref()
 462  * when you are done with it.
 463  *
 464  * Returns: the local timezone
 465  *
 466  * Since: 2.26
 467  **/
 468 GTimeZone *
 469 g_time_zone_new_local (void)
 470 {
 471   return g_time_zone_new (getenv ("TZ"));
 472 }
 473
 474 /* Internal helpers {{{1 */
 475 inline static const struct ttinfo *
 476 interval_info (GTimeZone *tz,
 477                gint       interval)
 478 {
 479   if (interval)
 480     return tz->infos + tz->indices[interval - 1];
 481
 482   return tz->infos;
 483 }
 484
 485 inline static gint64
 486 interval_start (GTimeZone *tz,
 487                 gint       interval)
 488 {
 489   if (interval)
 490     return gint64_from_be (tz->trans[interval - 1]);
 491
 492   return G_MININT64;
 493 }
 494
 495 inline static gint64
 496 interval_end (GTimeZone *tz,
 497               gint       interval)
 498 {
 499   if (interval < tz->timecnt)
 500     return gint64_from_be (tz->trans[interval]) - 1;
 501
 502   return G_MAXINT64;
 503 }
 504
 505 inline static gint32
 506 interval_offset (GTimeZone *tz,
 507                  gint       interval)
 508 {
 509   return gint32_from_be (interval_info (tz, interval)->tt_gmtoff);
 510 }
 511
 512 inline static gboolean
 513 interval_isdst (GTimeZone *tz,
 514                 gint       interval)
 515 {
 516   return interval_info (tz, interval)->tt_isdst;
 517 }
 518
 519 inline static guint8
 520 interval_abbrind (GTimeZone *tz,
 521                   gint       interval)
 522 {
 523   return interval_info (tz, interval)->tt_abbrind;
 524 }
 525
 526 inline static gint64
 527 interval_local_start (GTimeZone *tz,
 528                       gint       interval)
 529 {
 530   if (interval)
 531     return interval_start (tz, interval) + interval_offset (tz, interval);
 532
 533   return G_MININT64;
 534 }
 535
 536 inline static gint64
 537 interval_local_end (GTimeZone *tz,
 538                     gint       interval)
 539 {
 540   if (interval < tz->timecnt)
 541     return interval_end (tz, interval) + interval_offset (tz, interval);
 542
 543   return G_MAXINT64;
 544 }
 545
 546 static gboolean
 547 interval_valid (GTimeZone *tz,
 548                 gint       interval)
 549 {
 550   return interval <= tz->timecnt;
 551 }
 552
 553 /* g_time_zone_find_interval() {{{1 */
 554
 555 /**
 556  * g_time_zone_adjust_time:
 557  * @tz: a #GTimeZone
 558  * @type: the #GTimeType of @time_
 559  * @time_: a pointer to a number of seconds since January 1, 1970
 560  *
 561  * Finds an interval within @tz that corresponds to the given @time_,
 562  * possibly adjusting @time_ if required to fit into an interval.
 563  * The meaning of @time_ depends on @type.
 564  *
 565  * This function is similar to g_time_zone_find_interval(), with the
 566  * difference that it always succeeds (by making the adjustments
 567  * described below).
 568  *
 569  * In any of the cases where g_time_zone_find_interval() succeeds then
 570  * this function returns the same value, without modifying @time_.
 571  *
 572  * This function may, however, modify @time_ in order to deal with
 573  * non-existent times.  If the non-existent local @time_ of 02:30 were
 574  * requested on March 13th 2010 in Toronto then this function would
 575  * adjust @time_ to be 03:00 and return the interval containing the
 576  * adjusted time.
 577  *
 578  * Returns: the interval containing @time_, never -1
 579  *
 580  * Since: 2.26
 581  **/
 582 gint
 583 g_time_zone_adjust_time (GTimeZone *tz,
 584                          GTimeType  type,
 585                          gint64    *time_)
 586 {
 587   gint i;
 588
 589   if (tz->zoneinfo == NULL)
 590     return 0;
 591
 592   /* find the interval containing *time UTC
 593    * TODO: this could be binary searched (or better) */
 594   for (i = 0; i < tz->timecnt; i++)
 595     if (*time_ <= interval_end (tz, i))
 596       break;
 597
 598   g_assert (interval_start (tz, i) <= *time_ && *time_ <= interval_end (tz, i));
 599
 600   if (type != G_TIME_TYPE_UNIVERSAL)
 601     {
 602       if (*time_ < interval_local_start (tz, i))
 603         /* if time came before the start of this interval... */
 604         {
 605           i--;
 606
 607           /* if it's not in the previous interval... */
 608           if (*time_ > interval_local_end (tz, i))
 609             {
 610               /* it doesn't exist.  fast-forward it. */
 611               i++;
 612               *time_ = interval_local_start (tz, i);
 613             }
 614         }
 615
 616       else if (*time_ > interval_local_end (tz, i))
 617         /* if time came after the end of this interval... */
 618         {
 619           i++;
 620
 621           /* if it's not in the next interval... */
 622           if (*time_ < interval_local_start (tz, i))
 623             /* it doesn't exist.  fast-forward it. */
 624             *time_ = interval_local_start (tz, i);
 625         }
 626
 627       else if (interval_isdst (tz, i) != type)
 628         /* it's in this interval, but dst flag doesn't match.
 629          * check neighbours for a better fit. */
 630         {
 631           if (i && *time_ <= interval_local_end (tz, i - 1))
 632             i--;
 633
 634           else if (i < tz->timecnt &&
 635                    *time_ >= interval_local_start (tz, i + 1))
 636             i++;
 637         }
 638     }
 639
 640   return i;
 641 }
 642
 643 /**
 644  * g_time_zone_find_interval:
 645  * @tz: a #GTimeZone
 646  * @type: the #GTimeType of @time_
 647  * @time_: a number of seconds since January 1, 1970
 648  *
 649  * Finds an the interval within @tz that corresponds to the given @time_.
 650  * The meaning of @time_ depends on @type.
 651  *
 652  * If @type is %G_TIME_TYPE_UNIVERSAL then this function will always
 653  * succeed (since universal time is monotonic and continuous).
 654  *
 655  * Otherwise @time_ is treated is local time.  The distinction between
 656  * %G_TIME_TYPE_STANDARD and %G_TIME_TYPE_DAYLIGHT is ignored except in
 657  * the case that the given @time_ is ambiguous.  In Toronto, for example,
 658  * 01:30 on November 7th 2010 occurred twice (once inside of daylight
 659  * savings time and the next, an hour later, outside of daylight savings
 660  * time).  In this case, the different value of @type would result in a
 661  * different interval being returned.
 662  *
 663  * It is still possible for this function to fail.  In Toronto, for
 664  * example, 02:00 on March 14th 2010 does not exist (due to the leap
 665  * forward to begin daylight savings time).  -1 is returned in that
 666  * case.
 667  *
 668  * Returns: the interval containing @time_, or -1 in case of failure
 669  *
 670  * Since: 2.26
 671  */
 672 gint
 673 g_time_zone_find_interval (GTimeZone *tz,
 674                            GTimeType  type,
 675                            gint64     time_)
 676 {
 677   gint i;
 678
 679   if (tz->zoneinfo == NULL)
 680     return 0;
 681
 682   for (i = 0; i < tz->timecnt; i++)
 683     if (time_ <= interval_end (tz, i))
 684       break;
 685
 686   if (type == G_TIME_TYPE_UNIVERSAL)
 687     return i;
 688
 689   if (time_ < interval_local_start (tz, i))
 690     {
 691       if (time_ > interval_local_end (tz, --i))
 692         return -1;
 693     }
 694
 695   else if (time_ > interval_local_end (tz, i))
 696     {
 697       if (time_ < interval_local_start (tz, ++i))
 698         return -1;
 699     }
 700
 701   else if (interval_isdst (tz, i) != type)
 702     {
 703       if (i && time_ <= interval_local_end (tz, i - 1))
 704         i--;
 705
 706       else if (i < tz->timecnt && time_ >= interval_local_start (tz, i + 1))
 707         i++;
 708     }
 709
 710   return i;
 711 }
 712
 713 /* Public API accessors {{{1 */
 714
 715 /**
 716  * g_time_zone_get_abbreviation:
 717  * @tz: a #GTimeZone
 718  * @interval: an interval within the timezone
 719  *
 720  * Determines the time zone abbreviation to be used during a particular
 721  * @interval of time in the time zone @tz.
 722  *
 723  * For example, in Toronto this is currently "EST" during the winter
 724  * months and "EDT" during the summer months when daylight savings time
 725  * is in effect.
 726  *
 727  * Returns: the time zone abbreviation, which belongs to @tz
 728  *
 729  * Since: 2.26
 730  **/
 731 const gchar *
 732 g_time_zone_get_abbreviation (GTimeZone *tz,
 733                               gint       interval)
 734 {
 735   g_return_val_if_fail (interval_valid (tz, interval), NULL);
 736
 737   if (tz->header == NULL)
 738     return "UTC";
 739
 740   return tz->abbrs + interval_abbrind (tz, interval);
 741 }
 742
 743 /**
 744  * g_time_zone_get_offset:
 745  * @tz: a #GTimeZone
 746  * @interval: an interval within the timezone
 747  *
 748  * Determines the offset to UTC in effect during a particular @interval
 749  * of time in the time zone @tz.
 750  *
 751  * The offset is the number of seconds that you add to UTC time to
 752  * arrive at local time for @tz (ie: negative numbers for time zones
 753  * west of GMT, positive numbers for east).
 754  *
 755  * Returns: the number of seconds that should be added to UTC to get the
 756  *          local time in @tz
 757  *
 758  * Since: 2.26
 759  **/
 760 gint32
 761 g_time_zone_get_offset (GTimeZone *tz,
 762                         gint       interval)
 763 {
 764   g_return_val_if_fail (interval_valid (tz, interval), 0);
 765
 766   if (tz->header == NULL)
 767     return 0;
 768
 769   return interval_offset (tz, interval);
 770 }
 771
 772 /**
 773  * g_time_zone_is_dst:
 774  * @tz: a #GTimeZone
 775  * @interval: an interval within the timezone
 776  *
 777  * Determines if daylight savings time is in effect during a particular
 778  * @interval of time in the time zone @tz.
 779  *
 780  * Returns: %TRUE if daylight savings time is in effect
 781  *
 782  * Since: 2.26
 783  **/
 784 gboolean
 785 g_time_zone_is_dst (GTimeZone *tz,
 786                     gint       interval)
 787 {
 788   g_return_val_if_fail (interval_valid (tz, interval), FALSE);
 789
 790   if (tz->header == NULL)
 791     return FALSE;
 792
 793   return interval_isdst (tz, interval);
 794 }
 795
 796 /* Epilogue {{{1 */
 797 /* vim:set foldmethod=marker: */