glib/gvariant-core.c

/*
 * Copyright © 2007, 2008 Ryan Lortie
 * Copyright © 2010 Codethink Limited
 * Copyright © 2022 Endless OS Foundation, LLC
 *
 * SPDX-License-Identifier: LGPL-2.1-or-later
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
 */

#include "config.h"

#include <glib/gvariant-core.h>

#include <glib/gvariant-internal.h>
#include <glib/gvariant-serialiser.h>
#include <glib/gtestutils.h>
#include <glib/gbitlock.h>
#include <glib/gatomic.h>
#include <glib/gbytes.h>
#include <glib/gslice.h>
#include <glib/gmem.h>
#include <glib/grefcount.h>
#include <string.h>

#include "glib_trace.h"

/*
 * This file includes the structure definition for GVariant and a small
 * set of functions that are allowed to access the structure directly.
 *
 * This minimises the amount of code that can possibly touch a GVariant
 * structure directly to a few simple fundamental operations.  These few
 * operations are written to be completely threadsafe with respect to
 * all possible outside access.  This means that we only need to be
 * concerned about thread safety issues in this one small file.
 *
 * Most GVariant API functions are in gvariant.c.
 */

struct _GVariant
/* see below for field member documentation */
{
  GVariantTypeInfo *type_info;
  gsize size;

  union
  {
    struct
    {
      GBytes *bytes;
      gconstpointer data;
      gsize ordered_offsets_up_to;
      gsize checked_offsets_up_to;
    } serialised;

    struct
    {
      GVariant **children;
      gsize n_children;
    } tree;
  } contents;

  gint state;
  gatomicrefcount ref_count;
  gsize depth;
};

/* struct GVariant:
 *
 * There are two primary forms of GVariant instances: "serialized form"
 * and "tree form".
 *
 * "serialized form": A serialized GVariant instance stores its value in
 *                    the GVariant serialization format.  All
 *                    basic-typed instances (ie: non-containers) are in
 *                    serialized format, as are some containers.
 *
 * "tree form": Some containers are in "tree form".  In this case,
 *              instead of containing the serialized data for the
 *              container, the instance contains an array of pointers to
 *              the child values of the container (thus forming a tree).
 *
 * It is possible for an instance to transition from tree form to
 * serialized form.  This happens, implicitly, if the serialized data is
 * requested (eg: via g_variant_get_data()).  Serialized form instances
 * never transition into tree form.
 *
 *
 * The fields of the structure are documented here:
 *
 * type_info: this is a reference to a GVariantTypeInfo describing the
 *            type of the instance.  When the instance is freed, this
 *            reference must be released with g_variant_type_info_unref().
 *
 *            The type_info field never changes during the life of the
 *            instance, so it can be accessed without a lock.
 *
 * size: this is the size of the serialized form for the instance, if it
 *       is known.  If the instance is in serialized form then it is, by
 *       definition, known.  If the instance is in tree form then it may
 *       be unknown (in which case it is -1).  It is possible for the
 *       size to be known when in tree form if, for example, the user
 *       has called g_variant_get_size() without calling
 *       g_variant_get_data().  Additionally, even when the user calls
 *       g_variant_get_data() the size of the data must first be
 *       determined so that a large enough buffer can be allocated for
 *       the data.
 *
 *       Once the size is known, it can never become unknown again.
 *       g_variant_ensure_size() is used to ensure that the size is in
 *       the known state -- it calculates the size if needed.  After
 *       that, the size field can be accessed without a lock.
 *
 * contents: a union containing either the information associated with
 *           holding a value in serialized form or holding a value in
 *           tree form.
 *
 *   .serialised: Only valid when the instance is in serialized form.
 *
 *                Since an instance can never transition away from
 *                serialized form, once these fields are set, they will
 *                never be changed.  It is therefore valid to access
 *                them without holding a lock.
 *
 *     .bytes:  the #GBytes that contains the memory pointed to by
 *              .data, or %NULL if .data is %NULL.  In the event that
 *              the instance was deserialized from another instance,
 *              then the bytes will be shared by both of them.  When
 *              the instance is freed, this reference must be released
 *              with g_bytes_unref().
 *
 *     .data: the serialized data (of size 'size') of the instance.
 *            This pointer should not be freed or modified in any way.
 *            #GBytes is responsible for memory management.
 *
 *            This pointer may be %NULL in two cases:
 *
 *              - if the serialized size of the instance is 0
 *
 *              - if the instance is of a fixed-sized type and was
 *                deserialized out of a corrupted container such that
 *                the container contains too few bytes to point to the
 *                entire proper fixed-size of this instance.  In this
 *                case, 'size' will still be equal to the proper fixed
 *                size, but this pointer will be %NULL.  This is exactly
 *                the reason that g_variant_get_data() sometimes returns
 *                %NULL.  For all other calls, the effect should be as
 *                if .data pointed to the appropriate number of nul
 *                bytes.
 *
 *     .ordered_offsets_up_to: If ordered_offsets_up_to == n this means that all
 *                             the frame offsets up to and including the frame
 *                             offset determining the end of element n are in
 *                             order. This guarantees that the bytes of element
 *                             n don't overlap with any previous element.
 *
 *                             For trusted data this is set to G_MAXSIZE and we
 *                             don't check that the frame offsets are in order.
 *
 *                             Note: This doesn't imply the offsets are good in
 *                             any way apart from their ordering.  In particular
 *                             offsets may be out of bounds for this value or
 *                             may imply that the data overlaps the frame
 *                             offsets themselves.
 *
 *                             This field is only relevant for arrays of non
 *                             fixed width types and for tuples.
 *
 *     .checked_offsets_up_to: Similarly to .ordered_offsets_up_to, this stores
 *                             the index of the highest element, n, whose frame
 *                             offsets (and all the preceding frame offsets)
 *                             have been checked for validity.
 *
 *                             It is always the case that
 *                             .checked_offsets_up_to ≥ .ordered_offsets_up_to.
 *
 *                             If .checked_offsets_up_to == .ordered_offsets_up_to,
 *                             then a bad offset has not been found so far.
 *
 *                             If .checked_offsets_up_to > .ordered_offsets_up_to,
 *                             then a bad offset has been found at
 *                             (.ordered_offsets_up_to + 1).
 *
 *                             This field is only relevant for arrays of non
 *                             fixed width types and for tuples.
 *
 *   .tree: Only valid when the instance is in tree form.
 *
 *          Note that accesses from other threads could result in
 *          conversion of the instance from tree form to serialized form
 *          at any time.  For this reason, the instance lock must always
 *          be held while performing any operations on 'contents.tree'.
 *
 *     .children: the array of the child instances of this instance.
 *                When the instance is freed (or converted to serialized
 *                form) then each child must have g_variant_unref()
 *                called on it and the array must be freed using
 *                g_free().
 *
 *     .n_children: the number of items in the .children array.
 *
 * state: a bitfield describing the state of the instance.  It is a
 *        bitwise-or of the following STATE_* constants:
 *
 *    STATE_LOCKED: the instance lock is held.  This is the bit used by
 *                  g_bit_lock().
 *
 *    STATE_SERIALISED: the instance is in serialized form.  If this
 *                      flag is not set then the instance is in tree
 *                      form.
 *
 *    STATE_TRUSTED: for serialized form instances, this means that the
 *                   serialized data is known to be in normal form (ie:
 *                   not corrupted).
 *
 *                   For tree form instances, this means that all of the
 *                   child instances in the contents.tree.children array
 *                   are trusted.  This means that if the container is
 *                   serialized then the resulting data will be in
 *                   normal form.
 *
 *                   If this flag is unset it does not imply that the
 *                   data is corrupted.  It merely means that we're not
 *                   sure that it's valid.  See g_variant_is_trusted().
 *
 *    STATE_FLOATING: if this flag is set then the object has a floating
 *                    reference.  See g_variant_ref_sink().
 *
 * ref_count: the reference count of the instance
 *
 * depth: the depth of the GVariant in a hierarchy of nested containers,
 *        increasing with the level of nesting. The top-most GVariant has depth
 *        zero.  This is used to avoid recursing too deeply and overflowing the
 *        stack when handling deeply nested untrusted serialized GVariants.
 */
#define STATE_LOCKED     1
#define STATE_SERIALISED 2
#define STATE_TRUSTED    4
#define STATE_FLOATING   8

/* -- private -- */
/* < private >
 * g_variant_lock:
 * @value: a #GVariant
 *
 * Locks @value for performing sensitive operations.
 */
static void
g_variant_lock (GVariant *value)
{
  g_bit_lock (&value->state, 0);
}

/* < private >
 * g_variant_unlock:
 * @value: a #GVariant
 *
 * Unlocks @value after performing sensitive operations.
 */
static void
g_variant_unlock (GVariant *value)
{
  g_bit_unlock (&value->state, 0);
}

/* < private >
 * g_variant_release_children:
 * @value: a #GVariant
 *
 * Releases the reference held on each child in the 'children' array of
 * @value and frees the array itself.  @value must be in tree form.
 *
 * This is done when freeing a tree-form instance or converting it to
 * serialized form.
 *
 * The current thread must hold the lock on @value.
 */
static void
g_variant_release_children (GVariant *value)
{
  gsize i;

  g_assert (value->state & STATE_LOCKED);
  g_assert (~value->state & STATE_SERIALISED);

  for (i = 0; i < value->contents.tree.n_children; i++)
    g_variant_unref (value->contents.tree.children[i]);

  g_free (value->contents.tree.children);
}

/* This begins the main body of the recursive serializer.
 *
 * There are 3 functions here that work as a team with the serializer to
 * get things done.  g_variant_store() has a trivial role, but as a
 * public API function, it has its definition elsewhere.
 *
 * Note that "serialization" of an instance does not mean that the
 * instance is converted to serialized form -- it means that the
 * serialized form of an instance is written to an external buffer.
 * g_variant_ensure_serialised() (which is not part of this set of
 * functions) is the function that is responsible for converting an
 * instance to serialized form.
 *
 * We are only concerned here with container types since non-container
 * instances are always in serialized form.  For these instances,
 * storing their serialized form merely involves a memcpy().
 *
 * Serialization is a two-step process.  First, the size of the
 * serialized data must be calculated so that an appropriately-sized
 * buffer can be allocated.  Second, the data is written into the
 * buffer.
 *
 * Determining the size:
 *   The process of determining the size is triggered by a call to
 *   g_variant_ensure_size() on a container.  This invokes the
 *   serializer code to determine the size.  The serializer is passed
 *   g_variant_fill_gvs() as a callback.
 *
 *   g_variant_fill_gvs() is called by the serializer on each child of
 *   the container which, in turn, calls g_variant_ensure_size() on
 *   itself and fills in the result of its own size calculation.
 *
 *   The serializer uses the size information from the children to
 *   calculate the size needed for the entire container.
 *
 * Writing the data:
 *   After the buffer has been allocated, g_variant_serialise() is
 *   called on the container.  This invokes the serializer code to write
 *   the bytes to the container.  The serializer is, again, passed
 *   g_variant_fill_gvs() as a callback.
 *
 *   This time, when g_variant_fill_gvs() is called for each child, the
 *   child is given a pointer to a sub-region of the allocated buffer
 *   where it should write its data.  This is done by calling
 *   g_variant_store().  In the event that the instance is in serialized
 *   form this means a memcpy() of the serialized data into the
 *   allocated buffer.  In the event that the instance is in tree form
 *   this means a recursive call back into g_variant_serialise().
 *
 *
 * The forward declaration here allows corecursion via callback:
 */
static void g_variant_fill_gvs (GVariantSerialised *, gpointer);

/* < private >
 * g_variant_ensure_size:
 * @value: a #GVariant
 *
 * Ensures that the ->size field of @value is filled in properly.  This
 * must be done as a precursor to any serialization of the value in
 * order to know how large of a buffer is needed to store the data.
 *
 * The current thread must hold the lock on @value.
 */
static void
g_variant_ensure_size (GVariant *value)
{
  g_assert (value->state & STATE_LOCKED);

  if (value->size == (gsize) -1)
    {
      gpointer *children;
      gsize n_children;

      children = (gpointer *) value->contents.tree.children;
      n_children = value->contents.tree.n_children;
      value->size = g_variant_serialiser_needed_size (value->type_info,
                                                      g_variant_fill_gvs,
                                                      children, n_children);
    }
}

/* < private >
 * g_variant_to_serialised:
 * @value: a #GVariant
 *
 * Gets a GVariantSerialised for a GVariant in state STATE_SERIALISED.
 */
inline static GVariantSerialised
g_variant_to_serialised (GVariant *value)
{
  g_assert (value->state & STATE_SERIALISED);
  {
    GVariantSerialised serialised = {
      value->type_info,
      (gpointer) value->contents.serialised.data,
      value->size,
      value->depth,
      value->contents.serialised.ordered_offsets_up_to,
      value->contents.serialised.checked_offsets_up_to,
    };
    return serialised;
  }
}

/* < private >
 * g_variant_serialise:
 * @value: a #GVariant
 * @data: an appropriately-sized buffer
 *
 * Serializes @value into @data.  @value must be in tree form.
 *
 * No change is made to @value.
 *
 * The current thread must hold the lock on @value.
 */
static void
g_variant_serialise (GVariant *value,
                     gpointer  data)
{
  GVariantSerialised serialised = { 0, };
  gpointer *children;
  gsize n_children;

  g_assert (~value->state & STATE_SERIALISED);
  g_assert (value->state & STATE_LOCKED);

  serialised.type_info = value->type_info;
  serialised.size = value->size;
  serialised.data = data;
  serialised.depth = value->depth;
  serialised.ordered_offsets_up_to = 0;
  serialised.checked_offsets_up_to = 0;

  children = (gpointer *) value->contents.tree.children;
  n_children = value->contents.tree.n_children;

  g_variant_serialiser_serialise (serialised, g_variant_fill_gvs,
                                  children, n_children);
}

/* < private >
 * g_variant_fill_gvs:
 * @serialised: a pointer to a #GVariantSerialised
 * @data: a #GVariant instance
 *
 * This is the callback that is passed by a tree-form container instance
 * to the serializer.  This callback gets called on each child of the
 * container.  Each child is responsible for performing the following
 * actions:
 *
 *  - reporting its type
 *
 *  - reporting its serialized size (requires knowing the size first)
 *
 *  - possibly storing its serialized form into the provided buffer
 */
static void
g_variant_fill_gvs (GVariantSerialised *serialised,
                    gpointer            data)
{
  GVariant *value = data;

  g_variant_lock (value);
  g_variant_ensure_size (value);
  g_variant_unlock (value);

  if (serialised->type_info == NULL)
    serialised->type_info = value->type_info;
  g_assert (serialised->type_info == value->type_info);

  if (serialised->size == 0)
    serialised->size = value->size;
  g_assert (serialised->size == value->size);
  serialised->depth = value->depth;

  if (value->state & STATE_SERIALISED)
    {
      serialised->ordered_offsets_up_to = value->contents.serialised.ordered_offsets_up_to;
      serialised->checked_offsets_up_to = value->contents.serialised.checked_offsets_up_to;
    }
  else
    {
      serialised->ordered_offsets_up_to = 0;
      serialised->checked_offsets_up_to = 0;
    }

  if (serialised->data)
    /* g_variant_store() is a public API, so it
     * it will reacquire the lock if it needs to.
     */
    g_variant_store (value, serialised->data);
}

/* this ends the main body of the recursive serializer */

/* < private >
 * g_variant_ensure_serialised:
 * @value: a #GVariant
 *
 * Ensures that @value is in serialized form.
 *
 * If @value is in tree form then this function ensures that the
 * serialized size is known and then allocates a buffer of that size and
 * serializes the instance into the buffer.  The 'children' array is
 * then released and the instance is set to serialized form based on the
 * contents of the buffer.
 *
 * The current thread must hold the lock on @value.
 */
static void
g_variant_ensure_serialised (GVariant *value)
{
  g_assert (value->state & STATE_LOCKED);

  if (~value->state & STATE_SERIALISED)
    {
      GBytes *bytes;
      gpointer data;

      TRACE(GLIB_VARIANT_START_SERIALISE(value, value->type_info));
      g_variant_ensure_size (value);
      data = g_malloc (value->size);
      g_variant_serialise (value, data);

      g_variant_release_children (value);

      bytes = g_bytes_new_take (data, value->size);
      value->contents.serialised.data = g_bytes_get_data (bytes, NULL);
      value->contents.serialised.bytes = bytes;
      value->contents.serialised.ordered_offsets_up_to = G_MAXSIZE;
      value->contents.serialised.checked_offsets_up_to = G_MAXSIZE;
      value->state |= STATE_SERIALISED;
      TRACE(GLIB_VARIANT_END_SERIALISE(value, value->type_info));
    }
}

/* < private >
 * g_variant_alloc:
 * @type: the type of the new instance
 * @serialised: if the instance will be in serialised form
 * @trusted: if the instance will be trusted
 *
 * Allocates a #GVariant instance and does some common work (such as
 * looking up and filling in the type info), setting the state field,
 * and setting the ref_count to 1.
 *
 * Returns: a new #GVariant with a floating reference
 */
static GVariant *
g_variant_alloc (const GVariantType *type,
                 gboolean            serialised,
                 gboolean            trusted)
{
  GVariant *value;

  value = g_slice_new (GVariant);
  value->type_info = g_variant_type_info_get (type);
  value->state = (serialised ? STATE_SERIALISED : 0) |
                 (trusted ? STATE_TRUSTED : 0) |
                 STATE_FLOATING;
  value->size = (gssize) -1;
  g_atomic_ref_count_init (&value->ref_count);
  value->depth = 0;

  return value;
}

/**
 * g_variant_new_from_bytes:
 * @type: a #GVariantType
 * @bytes: a #GBytes
 * @trusted: if the contents of @bytes are trusted
 *
 * Constructs a new serialized-mode #GVariant instance.  This is the
 * inner interface for creation of new serialized values that gets
 * called from various functions in gvariant.c.
 *
 * A reference is taken on @bytes.
 *
 * The data in @bytes must be aligned appropriately for the @type being loaded.
 * Otherwise this function will internally create a copy of the memory (since
 * GLib 2.60) or (in older versions) fail and exit the process.
 *
 * Returns: (transfer none): a new #GVariant with a floating reference
 *
 * Since: 2.36
 */
GVariant *
g_variant_new_from_bytes (const GVariantType *type,
                          GBytes             *bytes,
                          gboolean            trusted)
{
  GVariant *value;
  guint alignment;
  gsize size;
  GBytes *owned_bytes = NULL;
  GVariantSerialised serialised;

  value = g_variant_alloc (type, TRUE, trusted);

  g_variant_type_info_query (value->type_info,
                             &alignment, &size);

  /* Ensure the alignment is correct. This is a huge performance hit if it’s
   * not correct, but that’s better than aborting if a caller provides data
   * with the wrong alignment (which is likely to happen very occasionally, and
   * only cause an abort on some architectures — so is unlikely to be caught
   * in testing). Callers can always actively ensure they use the correct
   * alignment to avoid the performance hit. */
  serialised.type_info = value->type_info;
  serialised.data = (guchar *) g_bytes_get_data (bytes, &serialised.size);
  serialised.depth = 0;
  serialised.ordered_offsets_up_to = trusted ? G_MAXSIZE : 0;
  serialised.checked_offsets_up_to = trusted ? G_MAXSIZE : 0;

  if (!g_variant_serialised_check (serialised))
    {
#ifdef HAVE_POSIX_MEMALIGN
      gpointer aligned_data = NULL;
      gsize aligned_size = g_bytes_get_size (bytes);

      /* posix_memalign() requires the alignment to be a multiple of
       * sizeof(void*), and a power of 2. See g_variant_type_info_query() for
       * details on the alignment format.
       *
       * While calling posix_memalign() with aligned_size==0 is safe on glibc,
       * POSIX specifies that the behaviour is implementation-defined, so avoid
       * that and leave aligned_data==NULL in that case.
       * See https://pubs.opengroup.org/onlinepubs/9699919799/functions/posix_memalign.html */
      if (aligned_size != 0 &&
          posix_memalign (&aligned_data, MAX (sizeof (void *), alignment + 1),
                          aligned_size) != 0)
        g_error ("posix_memalign failed");

      if (aligned_size != 0)
        memcpy (aligned_data, g_bytes_get_data (bytes, NULL), aligned_size);

      bytes = owned_bytes = g_bytes_new_with_free_func (aligned_data,
                                                        aligned_size,
                                                        free, aligned_data);
      aligned_data = NULL;
#else
      /* NOTE: there may be platforms that lack posix_memalign() and also
       * have malloc() that returns non-8-aligned.  if so, we need to try
       * harder here.
       */
      bytes = owned_bytes = g_bytes_new (g_bytes_get_data (bytes, NULL),
                                         g_bytes_get_size (bytes));
#endif
    }

  value->contents.serialised.bytes = g_bytes_ref (bytes);

  if (size && g_bytes_get_size (bytes) != size)
    {
      /* Creating a fixed-sized GVariant with a bytes of the wrong
       * size.
       *
       * We should do the equivalent of pulling a fixed-sized child out
       * of a brozen container (ie: data is NULL size is equal to the correct
       * fixed size).
       */
      value->contents.serialised.data = NULL;
      value->size = size;
    }
  else
    {
      value->contents.serialised.data = g_bytes_get_data (bytes, &value->size);
    }

  value->contents.serialised.ordered_offsets_up_to = trusted ? G_MAXSIZE : 0;
  value->contents.serialised.checked_offsets_up_to = trusted ? G_MAXSIZE : 0;

  g_clear_pointer (&owned_bytes, g_bytes_unref);

  TRACE(GLIB_VARIANT_FROM_BUFFER(value, value->type_info, value->ref_count, value->state));

  return value;
}

/* -- internal -- */

/* < internal >
 * g_variant_new_from_children:
 * @type: a #GVariantType
 * @children: an array of #GVariant pointers.  Consumed.
 * @n_children: the length of @children
 * @trusted: %TRUE if every child in @children is trusted
 *
 * Constructs a new tree-mode #GVariant instance.  This is the inner
 * interface for creation of new serialized values that gets called from
 * various functions in gvariant.c.
 *
 * @children is consumed by this function.  g_free() will be called on
 * it some time later.
 *
 * Returns: a new #GVariant with a floating reference
 */
GVariant *
g_variant_new_from_children (const GVariantType  *type,
                             GVariant           **children,
                             gsize                n_children,
                             gboolean             trusted)
{
  GVariant *value;

  value = g_variant_alloc (type, FALSE, trusted);
  value->contents.tree.children = children;
  value->contents.tree.n_children = n_children;
  TRACE(GLIB_VARIANT_FROM_CHILDREN(value, value->type_info, value->ref_count, value->state));

  return value;
}

/* < internal >
 * g_variant_get_type_info:
 * @value: a #GVariant
 *
 * Returns the #GVariantTypeInfo corresponding to the type of @value.  A
 * reference is not added, so the return value is only good for the
 * duration of the life of @value.
 *
 * Returns: the #GVariantTypeInfo for @value
 */
GVariantTypeInfo *
g_variant_get_type_info (GVariant *value)
{
  return value->type_info;
}

/* < internal >
 * g_variant_is_trusted:
 * @value: a #GVariant
 *
 * Determines if @value is trusted by #GVariant to contain only
 * fully-valid data.  All values constructed solely via #GVariant APIs
 * are trusted, but values containing data read in from other sources
 * are usually not trusted.
 *
 * The main advantage of trusted data is that certain checks can be
 * skipped.  For example, we don't need to check that a string is
 * properly nul-terminated or that an object path is actually a
 * properly-formatted object path.
 *
 * Returns: if @value is trusted
 */
gboolean
g_variant_is_trusted (GVariant *value)
{
  return (value->state & STATE_TRUSTED) != 0;
}

/* < internal >
 * g_variant_get_depth:
 * @value: a #GVariant
 *
 * Gets the nesting depth of a #GVariant. This is 0 for a #GVariant with no
 * children.
 *
 * Returns: nesting depth of @value
 */
gsize
g_variant_get_depth (GVariant *value)
{
  return value->depth;
}

/* -- public -- */

/**
 * g_variant_unref:
 * @value: a #GVariant
 *
 * Decreases the reference count of @value.  When its reference count
 * drops to 0, the memory used by the variant is freed.
 *
 * Since: 2.24
 **/
void
g_variant_unref (GVariant *value)
{
  g_return_if_fail (value != NULL);

  TRACE(GLIB_VARIANT_UNREF(value, value->type_info, value->ref_count, value->state));

  if (g_atomic_ref_count_dec (&value->ref_count))
    {
      if G_UNLIKELY (value->state & STATE_LOCKED)
        g_critical ("attempting to free a locked GVariant instance.  "
                    "This should never happen.");

      value->state |= STATE_LOCKED;

      g_variant_type_info_unref (value->type_info);

      if (value->state & STATE_SERIALISED)
        g_bytes_unref (value->contents.serialised.bytes);
      else
        g_variant_release_children (value);

      memset (value, 0, sizeof (GVariant));
      g_slice_free (GVariant, value);
    }
}

/**
 * g_variant_ref:
 * @value: a #GVariant
 *
 * Increases the reference count of @value.
 *
 * Returns: the same @value
 *
 * Since: 2.24
 **/
GVariant *
g_variant_ref (GVariant *value)
{
  g_return_val_if_fail (value != NULL, NULL);

  TRACE(GLIB_VARIANT_REF(value, value->type_info, value->ref_count, value->state));

  g_atomic_ref_count_inc (&value->ref_count);

  return value;
}

/**
 * g_variant_ref_sink:
 * @value: a #GVariant
 *
 * #GVariant uses a floating reference count system.  All functions with
 * names starting with `g_variant_new_` return floating
 * references.
 *
 * Calling g_variant_ref_sink() on a #GVariant with a floating reference
 * will convert the floating reference into a full reference.  Calling
 * g_variant_ref_sink() on a non-floating #GVariant results in an
 * additional normal reference being added.
 *
 * In other words, if the @value is floating, then this call "assumes
 * ownership" of the floating reference, converting it to a normal
 * reference.  If the @value is not floating, then this call adds a
 * new normal reference increasing the reference count by one.
 *
 * All calls that result in a #GVariant instance being inserted into a
 * container will call g_variant_ref_sink() on the instance.  This means
 * that if the value was just created (and has only its floating
 * reference) then the container will assume sole ownership of the value
 * at that point and the caller will not need to unreference it.  This
 * makes certain common styles of programming much easier while still
 * maintaining normal refcounting semantics in situations where values
 * are not floating.
 *
 * Returns: the same @value
 *
 * Since: 2.24
 **/
GVariant *
g_variant_ref_sink (GVariant *value)
{
  g_return_val_if_fail (value != NULL, NULL);
  g_return_val_if_fail (!g_atomic_ref_count_compare (&value->ref_count, 0), NULL);

  g_variant_lock (value);

  TRACE(GLIB_VARIANT_REF_SINK(value, value->type_info, value->ref_count, value->state, value->state & STATE_FLOATING));

  if (~value->state & STATE_FLOATING)
    g_variant_ref (value);
  else
    value->state &= ~STATE_FLOATING;

  g_variant_unlock (value);

  return value;
}

/**
 * g_variant_take_ref:
 * @value: a #GVariant
 *
 * If @value is floating, sink it.  Otherwise, do nothing.
 *
 * Typically you want to use g_variant_ref_sink() in order to
 * automatically do the correct thing with respect to floating or
 * non-floating references, but there is one specific scenario where
 * this function is helpful.
 *
 * The situation where this function is helpful is when creating an API
 * that allows the user to provide a callback function that returns a
 * #GVariant.  We certainly want to allow the user the flexibility to
 * return a non-floating reference from this callback (for the case
 * where the value that is being returned already exists).
 *
 * At the same time, the style of the #GVariant API makes it likely that
 * for newly-created #GVariant instances, the user can be saved some
 * typing if they are allowed to return a #GVariant with a floating
 * reference.
 *
 * Using this function on the return value of the user's callback allows
 * the user to do whichever is more convenient for them.  The caller
 * will always receives exactly one full reference to the value: either
 * the one that was returned in the first place, or a floating reference
 * that has been converted to a full reference.
 *
 * This function has an odd interaction when combined with
 * g_variant_ref_sink() running at the same time in another thread on
 * the same #GVariant instance.  If g_variant_ref_sink() runs first then
 * the result will be that the floating reference is converted to a hard
 * reference.  If g_variant_take_ref() runs first then the result will
 * be that the floating reference is converted to a hard reference and
 * an additional reference on top of that one is added.  It is best to
 * avoid this situation.
 *
 * Returns: the same @value
 **/
GVariant *
g_variant_take_ref (GVariant *value)
{
  g_return_val_if_fail (value != NULL, NULL);
  g_return_val_if_fail (!g_atomic_ref_count_compare (&value->ref_count, 0), NULL);

  TRACE(GLIB_VARIANT_TAKE_REF(value, value->type_info, value->ref_count, value->state, value->state & STATE_FLOATING));
  g_atomic_int_and (&value->state, ~STATE_FLOATING);

  return value;
}

/**
 * g_variant_is_floating:
 * @value: a #GVariant
 *
 * Checks whether @value has a floating reference count.
 *
 * This function should only ever be used to assert that a given variant
 * is or is not floating, or for debug purposes. To acquire a reference
 * to a variant that might be floating, always use g_variant_ref_sink()
 * or g_variant_take_ref().
 *
 * See g_variant_ref_sink() for more information about floating reference
 * counts.
 *
 * Returns: whether @value is floating
 *
 * Since: 2.26
 **/
gboolean
g_variant_is_floating (GVariant *value)
{
  g_return_val_if_fail (value != NULL, FALSE);

  return (value->state & STATE_FLOATING) != 0;
}

/**
 * g_variant_get_size:
 * @value: a #GVariant instance
 *
 * Determines the number of bytes that would be required to store @value
 * with g_variant_store().
 *
 * If @value has a fixed-sized type then this function always returned
 * that fixed size.
 *
 * In the case that @value is already in serialized form or the size has
 * already been calculated (ie: this function has been called before)
 * then this function is O(1).  Otherwise, the size is calculated, an
 * operation which is approximately O(n) in the number of values
 * involved.
 *
 * Returns: the serialized size of @value
 *
 * Since: 2.24
 **/
gsize
g_variant_get_size (GVariant *value)
{
  g_variant_lock (value);
  g_variant_ensure_size (value);
  g_variant_unlock (value);

  return value->size;
}

/**
 * g_variant_get_data:
 * @value: a #GVariant instance
 *
 * Returns a pointer to the serialized form of a #GVariant instance.
 * The returned data may not be in fully-normalised form if read from an
 * untrusted source.  The returned data must not be freed; it remains
 * valid for as long as @value exists.
 *
 * If @value is a fixed-sized value that was deserialized from a
 * corrupted serialized container then %NULL may be returned.  In this
 * case, the proper thing to do is typically to use the appropriate
 * number of nul bytes in place of @value.  If @value is not fixed-sized
 * then %NULL is never returned.
 *
 * In the case that @value is already in serialized form, this function
 * is O(1).  If the value is not already in serialized form,
 * serialization occurs implicitly and is approximately O(n) in the size
 * of the result.
 *
 * To deserialize the data returned by this function, in addition to the
 * serialized data, you must know the type of the #GVariant, and (if the
 * machine might be different) the endianness of the machine that stored
 * it. As a result, file formats or network messages that incorporate
 * serialized #GVariants must include this information either
 * implicitly (for instance "the file always contains a
 * %G_VARIANT_TYPE_VARIANT and it is always in little-endian order") or
 * explicitly (by storing the type and/or endianness in addition to the
 * serialized data).
 *
 * Returns: (transfer none): the serialized form of @value, or %NULL
 *
 * Since: 2.24
 **/
gconstpointer
g_variant_get_data (GVariant *value)
{
  g_variant_lock (value);
  g_variant_ensure_serialised (value);
  g_variant_unlock (value);

  return value->contents.serialised.data;
}

/**
 * g_variant_get_data_as_bytes:
 * @value: a #GVariant
 *
 * Returns a pointer to the serialized form of a #GVariant instance.
 * The semantics of this function are exactly the same as
 * g_variant_get_data(), except that the returned #GBytes holds
 * a reference to the variant data.
 *
 * Returns: (transfer full): A new #GBytes representing the variant data
 *
 * Since: 2.36
 */ 
GBytes *
g_variant_get_data_as_bytes (GVariant *value)
{
  const gchar *bytes_data;
  const gchar *data;
  gsize bytes_size;
  gsize size;

  g_variant_lock (value);
  g_variant_ensure_serialised (value);
  g_variant_unlock (value);

  bytes_data = g_bytes_get_data (value->contents.serialised.bytes, &bytes_size);
  data = value->contents.serialised.data;
  size = value->size;

  if (data == NULL)
    {
      g_assert (size == 0);
      data = bytes_data;
    }

  if (data == bytes_data && size == bytes_size)
    return g_bytes_ref (value->contents.serialised.bytes);
  else
    return g_bytes_new_from_bytes (value->contents.serialised.bytes,
                                   data - bytes_data, size);
}


/**
 * g_variant_n_children:
 * @value: a container #GVariant
 *
 * Determines the number of children in a container #GVariant instance.
 * This includes variants, maybes, arrays, tuples and dictionary
 * entries.  It is an error to call this function on any other type of
 * #GVariant.
 *
 * For variants, the return value is always 1.  For values with maybe
 * types, it is always zero or one.  For arrays, it is the length of the
 * array.  For tuples it is the number of tuple items (which depends
 * only on the type).  For dictionary entries, it is always 2
 *
 * This function is O(1).
 *
 * Returns: the number of children in the container
 *
 * Since: 2.24
 **/
gsize
g_variant_n_children (GVariant *value)
{
  gsize n_children;

  g_variant_lock (value);

  if (value->state & STATE_SERIALISED)
    n_children = g_variant_serialised_n_children (
        g_variant_to_serialised (value));
  else
    n_children = value->contents.tree.n_children;

  g_variant_unlock (value);

  return n_children;
}

/**
 * g_variant_get_child_value:
 * @value: a container #GVariant
 * @index_: the index of the child to fetch
 *
 * Reads a child item out of a container #GVariant instance.  This
 * includes variants, maybes, arrays, tuples and dictionary
 * entries.  It is an error to call this function on any other type of
 * #GVariant.
 *
 * It is an error if @index_ is greater than the number of child items
 * in the container.  See g_variant_n_children().
 *
 * The returned value is never floating.  You should free it with
 * g_variant_unref() when you're done with it.
 *
 * Note that values borrowed from the returned child are not guaranteed to
 * still be valid after the child is freed even if you still hold a reference
 * to @value, if @value has not been serialized at the time this function is
 * called. To avoid this, you can serialize @value by calling
 * g_variant_get_data() and optionally ignoring the return value.
 *
 * There may be implementation specific restrictions on deeply nested values,
 * which would result in the unit tuple being returned as the child value,
 * instead of further nested children. #GVariant is guaranteed to handle
 * nesting up to at least 64 levels.
 *
 * This function is O(1).
 *
 * Returns: (transfer full): the child at the specified index
 *
 * Since: 2.24
 **/
GVariant *
g_variant_get_child_value (GVariant *value,
                           gsize     index_)
{
  g_return_val_if_fail (value->depth < G_MAXSIZE, NULL);

  if (~g_atomic_int_get (&value->state) & STATE_SERIALISED)
    {
      /* g_variant_serialised_get_child() does its own checks on index_ */
      g_return_val_if_fail (index_ < g_variant_n_children (value), NULL);

      g_variant_lock (value);

      if (~value->state & STATE_SERIALISED)
        {
          GVariant *child;

          child = g_variant_ref (value->contents.tree.children[index_]);
          g_variant_unlock (value);

          return child;
        }

      g_variant_unlock (value);
    }

  {
    GVariantSerialised serialised = g_variant_to_serialised (value);
    GVariantSerialised s_child;
    GVariant *child;

    /* get the serializer to extract the serialized data for the child
     * from the serialized data for the container
     */
    s_child = g_variant_serialised_get_child (serialised, index_);

    /* Update the cached ordered_offsets_up_to, since @serialised will be thrown away when this function exits */
    value->contents.serialised.ordered_offsets_up_to = MAX (value->contents.serialised.ordered_offsets_up_to, serialised.ordered_offsets_up_to);
    value->contents.serialised.checked_offsets_up_to = MAX (value->contents.serialised.checked_offsets_up_to, serialised.checked_offsets_up_to);

    /* Check whether this would cause nesting too deep. If so, return a fake
     * child. The only situation we expect this to happen in is with a variant,
     * as all other deeply-nested types have a static type, and hence should
     * have been rejected earlier. In the case of a variant whose nesting plus
     * the depth of its child is too great, return a unit variant () instead of
     * the real child. */
    if (!(value->state & STATE_TRUSTED) &&
        g_variant_type_info_query_depth (s_child.type_info) >=
        G_VARIANT_MAX_RECURSION_DEPTH - value->depth)
      {
        g_assert (g_variant_is_of_type (value, G_VARIANT_TYPE_VARIANT));
        g_variant_type_info_unref (s_child.type_info);
        return g_variant_new_tuple (NULL, 0);
      }

    /* create a new serialized instance out of it */
    child = g_slice_new (GVariant);
    child->type_info = s_child.type_info;
    child->state = (value->state & STATE_TRUSTED) |
                   STATE_SERIALISED;
    child->size = s_child.size;
    g_atomic_ref_count_init (&child->ref_count);
    child->depth = value->depth + 1;
    child->contents.serialised.bytes =
      g_bytes_ref (value->contents.serialised.bytes);
    child->contents.serialised.data = s_child.data;
    child->contents.serialised.ordered_offsets_up_to = (value->state & STATE_TRUSTED) ? G_MAXSIZE : s_child.ordered_offsets_up_to;
    child->contents.serialised.checked_offsets_up_to = (value->state & STATE_TRUSTED) ? G_MAXSIZE : s_child.checked_offsets_up_to;

    TRACE(GLIB_VARIANT_FROM_PARENT(child, child->type_info, child->ref_count, child->state, value));

    return child;
  }
}

/**
 * g_variant_maybe_get_child_value:
 * @value: a container #GVariant
 * @index_: the index of the child to fetch
 *
 * Reads a child item out of a container #GVariant instance, if it is in normal
 * form. If it is not in normal form, return %NULL.
 *
 * This function behaves the same as g_variant_get_child_value(), except that it
 * returns %NULL if the child is not in normal form. g_variant_get_child_value()
 * would instead return a new default value of the correct type.
 *
 * This is intended to be used internally to avoid unnecessary #GVariant
 * allocations.
 *
 * The returned value is never floating.  You should free it with
 * g_variant_unref() when you're done with it.
 *
 * This function is O(1).
 *
 * Returns: (transfer full): the child at the specified index
 *
 * Since: 2.74
 */
GVariant *
g_variant_maybe_get_child_value (GVariant *value,
                                 gsize     index_)
{
  g_return_val_if_fail (value->depth < G_MAXSIZE, NULL);

  if (~g_atomic_int_get (&value->state) & STATE_SERIALISED)
    {
      /* g_variant_serialised_get_child() does its own checks on index_ */
      g_return_val_if_fail (index_ < g_variant_n_children (value), NULL);

      g_variant_lock (value);

      if (~value->state & STATE_SERIALISED)
        {
          GVariant *child;

          child = g_variant_ref (value->contents.tree.children[index_]);
          g_variant_unlock (value);

          return child;
        }

      g_variant_unlock (value);
    }

  {
    GVariantSerialised serialised = g_variant_to_serialised (value);
    GVariantSerialised s_child;

    /* get the serializer to extract the serialized data for the child
     * from the serialized data for the container
     */
    s_child = g_variant_serialised_get_child (serialised, index_);

    if (!(value->state & STATE_TRUSTED) && s_child.data == NULL)
      {
        g_variant_type_info_unref (s_child.type_info);
        return NULL;
      }

    g_variant_type_info_unref (s_child.type_info);
    return g_variant_get_child_value (value, index_);
  }
}

/**
 * g_variant_store:
 * @value: the #GVariant to store
 * @data: (not nullable): the location to store the serialized data at
 *
 * Stores the serialized form of @value at @data.  @data should be
 * large enough.  See g_variant_get_size().
 *
 * The stored data is in machine native byte order but may not be in
 * fully-normalised form if read from an untrusted source.  See
 * g_variant_get_normal_form() for a solution.
 *
 * As with g_variant_get_data(), to be able to deserialize the
 * serialized variant successfully, its type and (if the destination
 * machine might be different) its endianness must also be available.
 *
 * This function is approximately O(n) in the size of @data.
 *
 * Since: 2.24
 **/
void
g_variant_store (GVariant *value,
                 gpointer  data)
{
  g_variant_lock (value);

  if (value->state & STATE_SERIALISED)
    {
      if (value->contents.serialised.data != NULL)
        memcpy (data, value->contents.serialised.data, value->size);
      else
        memset (data, 0, value->size);
    }
  else
    g_variant_serialise (value, data);

  g_variant_unlock (value);
}

/**
 * g_variant_is_normal_form:
 * @value: a #GVariant instance
 *
 * Checks if @value is in normal form.
 *
 * The main reason to do this is to detect if a given chunk of
 * serialized data is in normal form: load the data into a #GVariant
 * using g_variant_new_from_data() and then use this function to
 * check.
 *
 * If @value is found to be in normal form then it will be marked as
 * being trusted.  If the value was already marked as being trusted then
 * this function will immediately return %TRUE.
 *
 * There may be implementation specific restrictions on deeply nested values.
 * GVariant is guaranteed to handle nesting up to at least 64 levels.
 *
 * Returns: %TRUE if @value is in normal form
 *
 * Since: 2.24
 **/
gboolean
g_variant_is_normal_form (GVariant *value)
{
  if (value->state & STATE_TRUSTED)
    return TRUE;

  g_variant_lock (value);

  if (value->depth >= G_VARIANT_MAX_RECURSION_DEPTH)
    return FALSE;

  if (value->state & STATE_SERIALISED)
    {
      if (g_variant_serialised_is_normal (g_variant_to_serialised (value)))
        value->state |= STATE_TRUSTED;
    }
  else
    {
      gboolean normal = TRUE;
      gsize i;

      for (i = 0; i < value->contents.tree.n_children; i++)
        normal &= g_variant_is_normal_form (value->contents.tree.children[i]);

      if (normal)
        value->state |= STATE_TRUSTED;
    }

  g_variant_unlock (value);

  return (value->state & STATE_TRUSTED) != 0;
}