2 * Copyright © 2009, 2010 Codethink Limited
3 * Copyright © 2011 Collabora Ltd.
5 * This library is free software; you can redistribute it and/or
6 * modify it under the terms of the GNU Lesser General Public
7 * License as published by the Free Software Foundation; either
8 * version 2 of the licence, or (at your option) any later version.
10 * This library is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 * Lesser General Public License for more details.
15 * You should have received a copy of the GNU Lesser General Public
16 * License along with this library; if not, see <http://www.gnu.org/licenses/>.
18 * Author: Ryan Lortie <desrt@desrt.ca>
19 * Stef Walter <stefw@collabora.co.uk>
26 #include <glib/garray.h>
27 #include <glib/gstrfuncs.h>
28 #include <glib/gatomic.h>
29 #include <glib/gslice.h>
30 #include <glib/gtestutils.h>
31 #include <glib/gmem.h>
32 #include <glib/gmessages.h>
37 #include <sys/types.h>
40 #include "glib-unix.h"
47 * A simple refcounted data type representing an immutable sequence of zero or
48 * more bytes from an unspecified origin.
50 * The purpose of a #GBytes is to keep the memory region that it holds
51 * alive for as long as anyone holds a reference to the bytes. When
52 * the last reference count is dropped, the memory is released. Multiple
53 * unrelated callers can use byte data in the #GBytes without coordinating
54 * their activities, resting assured that the byte data will not change or
55 * move while they hold a reference.
57 * A #GBytes can come from many different origins that may have
58 * different procedures for freeing the memory region. Examples are
59 * memory from g_malloc(), from memory slices, from a #GMappedFile or
60 * memory from other allocators.
62 * #GBytes work well as keys in #GHashTable. Use g_bytes_equal() and
63 * g_bytes_hash() as parameters to g_hash_table_new() or g_hash_table_new_full().
64 * #GBytes can also be used as keys in a #GTree by passing the g_bytes_compare()
65 * function to g_tree_new().
67 * The data pointed to by this bytes must not be modified. For a mutable
68 * array of bytes see #GByteArray. Use g_bytes_unref_to_array() to create a
69 * mutable array for a #GBytes sequence. To create an immutable #GBytes from
70 * a mutable #GByteArray, use the g_byte_array_free_to_bytes() function.
85 #if GLIB_SIZEOF_SIZE_T == 4
92 /* important: the ->data field of GBytesInline should always be 'nicely
95 G_STATIC_ASSERT (G_STRUCT_OFFSET (GBytesInline, data) % (2 * sizeof (gpointer)) == 0);
96 G_STATIC_ASSERT (G_STRUCT_OFFSET (GBytesInline, data) % 8 == 0);
108 GBytesData data_bytes;
110 GDestroyNotify notify;
114 #define G_BYTES_TYPE_INLINE (-1)
115 #define G_BYTES_TYPE_STATIC (-2)
116 #define G_BYTES_TYPE_FREE (-3)
117 #define G_BYTES_TYPE_NOTIFY (-4)
119 /* All bytes are either inline or subtypes of GBytesData */
120 #define G_BYTES_IS_INLINE(bytes) ((bytes)->type_or_fd == G_BYTES_TYPE_INLINE)
121 #define G_BYTES_IS_DATA(bytes) (!G_BYTES_IS_INLINE(bytes))
123 /* More specific subtypes of GBytesData */
124 #define G_BYTES_IS_STATIC(bytes) ((bytes)->type_or_fd == G_BYTES_TYPE_STATIC)
125 #define G_BYTES_IS_FREE(bytes) ((bytes)->type_or_fd == G_BYTES_TYPE_FREE)
126 #define G_BYTES_IS_NOTIFY(bytes) ((bytes)->type_or_fd == G_BYTES_TYPE_NOTIFY)
128 /* we have a memfd if type_or_fd >= 0 */
129 #define G_BYTES_IS_MEMFD(bytes) ((bytes)->type_or_fd >= 0)
132 g_bytes_allocate (guint struct_size,
138 bytes = g_slice_alloc (struct_size);
139 bytes->size = data_size;
140 bytes->ref_count = 1;
141 bytes->type_or_fd = type_or_fd;
148 * @data: (transfer none) (array length=size) (element-type guint8) (allow-none):
149 * the data to be used for the bytes
150 * @size: the size of @data
152 * Creates a new #GBytes from @data.
154 * @data is copied. If @size is 0, @data may be %NULL.
156 * Returns: (transfer full): a new #GBytes
161 g_bytes_new (gconstpointer data,
166 g_return_val_if_fail (data != NULL || size == 0, NULL);
168 bytes = g_bytes_allocate (G_STRUCT_OFFSET (GBytesInline, data[size]), G_BYTES_TYPE_INLINE, size);
169 memcpy (bytes->data, data, size);
171 return (GBytes *) bytes;
175 * g_bytes_new_take_zero_copy_fd:
176 * @fd: a file descriptor capable of being zero-copy-safe
178 * Creates a new #GBytes from @fd.
180 * @fd must be capable of being made zero-copy-safe. In concrete terms,
181 * this means that a call to g_unix_fd_ensure_zero_copy_safe() on @fd
182 * will succeed. This call will be made before returning.
184 * This call consumes @fd, transferring ownership to the returned
187 * Returns: (transfer full): a new #GBytes
193 g_bytes_new_take_zero_copy_fd (gint fd)
198 g_return_val_if_fail_se (g_unix_fd_ensure_zero_copy_safe (fd), NULL);
200 /* We already checked this is a memfd... */
201 g_assert_se (fstat (fd, &buf) == 0);
203 if (buf.st_size == 0)
205 g_assert_se (close (fd) == 0);
207 return g_bytes_new (NULL, 0);
210 bytes = g_bytes_allocate (sizeof (GBytesData), fd, buf.st_size);
211 bytes->data = mmap (NULL, buf.st_size, PROT_READ, MAP_PRIVATE, fd, 0);
212 if (bytes->data == MAP_FAILED)
213 /* this is similar to malloc() failing, so do the same... */
214 g_error ("mmap() on memfd failed: %s\n", g_strerror (errno));
216 return (GBytes *) bytes;
218 #endif /* G_OS_UNIX */
222 * @data: (transfer full) (array length=size) (element-type guint8) (allow-none):
223 the data to be used for the bytes
224 * @size: the size of @data
226 * Creates a new #GBytes from @data.
228 * After this call, @data belongs to the bytes and may no longer be
229 * modified by the caller. g_free() will be called on @data when the
230 * bytes is no longer in use. Because of this @data must have been created by
231 * a call to g_malloc(), g_malloc0() or g_realloc() or by one of the many
232 * functions that wrap these calls (such as g_new(), g_strdup(), etc).
234 * For creating #GBytes with memory from other allocators, see
235 * g_bytes_new_with_free_func().
237 * @data may be %NULL if @size is 0.
239 * Returns: (transfer full): a new #GBytes
244 g_bytes_new_take (gpointer data,
249 bytes = g_bytes_allocate (sizeof (GBytesNotify), G_BYTES_TYPE_FREE, size);
252 return (GBytes *) bytes;
256 * g_bytes_new_static: (skip)
257 * @data: (transfer full) (array length=size) (element-type guint8) (allow-none):
258 the data to be used for the bytes
259 * @size: the size of @data
261 * Creates a new #GBytes from static data.
263 * @data must be static (ie: never modified or freed). It may be %NULL if @size
266 * Returns: (transfer full): a new #GBytes
271 g_bytes_new_static (gconstpointer data,
276 g_return_val_if_fail (data != NULL || size == 0, NULL);
278 bytes = g_bytes_allocate (sizeof (GBytesData), G_BYTES_TYPE_STATIC, size);
279 bytes->data = (gpointer) data;
281 return (GBytes *) bytes;
285 * g_bytes_new_with_free_func:
286 * @data: (array length=size) (allow-none): the data to be used for the bytes
287 * @size: the size of @data
288 * @free_func: the function to call to release the data
289 * @user_data: data to pass to @free_func
291 * Creates a #GBytes from @data.
293 * When the last reference is dropped, @free_func will be called with the
294 * @user_data argument.
296 * @data must not be modified after this call is made until @free_func has
297 * been called to indicate that the bytes is no longer in use.
299 * @data may be %NULL if @size is 0.
301 * Returns: (transfer full): a new #GBytes
306 g_bytes_new_with_free_func (gconstpointer data,
308 GDestroyNotify free_func,
314 return g_bytes_new_static (data, size);
316 bytes = g_bytes_allocate (sizeof (GBytesNotify), G_BYTES_TYPE_NOTIFY, size);
317 bytes->data_bytes.data = (gpointer) data;
318 bytes->notify = free_func;
319 bytes->user_data = user_data;
321 return (GBytes *) bytes;
325 * g_bytes_new_from_bytes:
327 * @offset: offset which subsection starts at
328 * @length: length of subsection
330 * Creates a #GBytes which is a subsection of another #GBytes. The @offset +
331 * @length may not be longer than the size of @bytes.
333 * A reference to @bytes will be held by the newly created #GBytes until
334 * the byte data is no longer needed.
336 * Returns: (transfer full): a new #GBytes
341 g_bytes_new_from_bytes (GBytes *bytes,
345 /* Note that length may be 0. */
346 g_return_val_if_fail (bytes != NULL, NULL);
347 g_return_val_if_fail (offset <= bytes->size, NULL);
348 g_return_val_if_fail (offset + length <= bytes->size, NULL);
350 return g_bytes_new_with_free_func ((gchar *) g_bytes_get_data (bytes, NULL) + offset, length,
351 (GDestroyNotify)g_bytes_unref, g_bytes_ref (bytes));
357 * @size: (out) (allow-none): location to return size of byte data
359 * Get the byte data in the #GBytes. This data should not be modified.
361 * This function will always return the same pointer for a given #GBytes.
363 * %NULL may be returned if @size is 0. This is not guaranteed, as the #GBytes
364 * may represent an empty string with @data non-%NULL and @size as 0. %NULL will
365 * not be returned if @size is non-zero.
367 * Returns: (transfer none) (array length=size) (type guint8) (allow-none): a pointer to the
368 * byte data, or %NULL
373 g_bytes_get_data (GBytes *bytes,
376 g_return_val_if_fail (bytes != NULL, NULL);
381 if (G_BYTES_IS_DATA (bytes))
383 GBytesData *data_bytes = (GBytesData *) bytes;
385 return data_bytes->data;
387 else if (G_BYTES_IS_INLINE (bytes))
389 GBytesInline *inline_bytes = (GBytesInline *) bytes;
391 return inline_bytes->data;
394 g_assert_not_reached ();
401 * Get the size of the byte data in the #GBytes.
403 * This function will always return the same value for a given #GBytes.
410 g_bytes_get_size (GBytes *bytes)
412 g_return_val_if_fail (bytes != NULL, 0);
417 * g_bytes_get_zero_copy_fd:
420 * Gets the zero-copy fd from a #GBytes, if it has one.
422 * Returns -1 if @bytes was not created from a zero-copy fd.
424 * A #GBytes created with a zero-copy fd may have been internally
425 * converted into another type of #GBytes for any reason at all. This
426 * function may therefore return -1 at any time, even for a #GBytes that
427 * was created with g_bytes_new_take_zero_copy_fd().
429 * The returned file descriptor belongs to @bytes. Do not close it.
431 * Returns: a file descriptor, or -1
436 g_bytes_get_zero_copy_fd (GBytes *bytes)
438 g_return_val_if_fail (bytes != NULL, -1);
440 if (G_BYTES_IS_MEMFD (bytes))
441 return bytes->type_or_fd;
450 * Increase the reference count on @bytes.
452 * Returns: the #GBytes
457 g_bytes_ref (GBytes *bytes)
459 g_return_val_if_fail (bytes != NULL, NULL);
461 g_atomic_int_inc (&bytes->ref_count);
468 * @bytes: (allow-none): a #GBytes
470 * Releases a reference on @bytes. This may result in the bytes being
476 g_bytes_unref (GBytes *bytes)
481 if (g_atomic_int_dec_and_test (&bytes->ref_count))
483 switch (bytes->type_or_fd)
485 case G_BYTES_TYPE_STATIC:
486 /* data does not need to be freed */
487 g_slice_free (GBytesData, (GBytesData *) bytes);
490 case G_BYTES_TYPE_INLINE:
491 /* data will be freed along with struct */
492 g_slice_free1 (G_STRUCT_OFFSET (GBytesInline, data[bytes->size]), bytes);
495 case G_BYTES_TYPE_FREE:
497 GBytesData *data_bytes = (GBytesData *) bytes;
499 g_free (data_bytes->data);
501 g_slice_free (GBytesData, data_bytes);
505 case G_BYTES_TYPE_NOTIFY:
507 GBytesNotify *notify_bytes = (GBytesNotify *) bytes;
509 /* We don't create GBytesNotify if callback was NULL */
510 (* notify_bytes->notify) (notify_bytes->user_data);
512 g_slice_free (GBytesNotify, notify_bytes);
518 GBytesData *data_bytes = (GBytesData *) bytes;
520 g_assert (bytes->type_or_fd >= 0);
522 g_assert_se (munmap (data_bytes->data, bytes->size) == 0);
523 g_assert_se (close (bytes->type_or_fd) == 0);
525 g_slice_free (GBytesData, data_bytes);
534 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
535 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
537 * Compares the two #GBytes values being pointed to and returns
538 * %TRUE if they are equal.
540 * This function can be passed to g_hash_table_new() as the @key_equal_func
541 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
543 * Returns: %TRUE if the two keys match.
548 g_bytes_equal (gconstpointer bytes1,
549 gconstpointer bytes2)
551 gconstpointer d1, d2;
554 g_return_val_if_fail (bytes1 != NULL, FALSE);
555 g_return_val_if_fail (bytes2 != NULL, FALSE);
557 d1 = g_bytes_get_data ((GBytes *) bytes1, &s1);
558 d2 = g_bytes_get_data ((GBytes *) bytes2, &s2);
566 return memcmp (d1, d2, s1) == 0;
571 * @bytes: (type GLib.Bytes): a pointer to a #GBytes key
573 * Creates an integer hash code for the byte data in the #GBytes.
575 * This function can be passed to g_hash_table_new() as the @key_hash_func
576 * parameter, when using non-%NULL #GBytes pointers as keys in a #GHashTable.
578 * Returns: a hash value corresponding to the key.
583 g_bytes_hash (gconstpointer bytes)
590 g_return_val_if_fail (bytes != NULL, 0);
592 data = g_bytes_get_data ((GBytes *) bytes, &size);
596 h = (h << 5) + h + *(data++);
603 * @bytes1: (type GLib.Bytes): a pointer to a #GBytes
604 * @bytes2: (type GLib.Bytes): a pointer to a #GBytes to compare with @bytes1
606 * Compares the two #GBytes values.
608 * This function can be used to sort GBytes instances in lexographical order.
610 * Returns: a negative value if bytes2 is lesser, a positive value if bytes2 is
611 * greater, and zero if bytes2 is equal to bytes1
616 g_bytes_compare (gconstpointer bytes1,
617 gconstpointer bytes2)
619 gconstpointer d1, d2;
623 g_return_val_if_fail (bytes1 != NULL, 0);
624 g_return_val_if_fail (bytes2 != NULL, 0);
626 d1 = g_bytes_get_data ((GBytes *) bytes1, &s1);
627 d2 = g_bytes_get_data ((GBytes *) bytes2, &s2);
629 ret = memcmp (d1, d2, MIN (s1, s2));
630 if (ret == 0 && s1 != s2)
631 ret = s1 < s2 ? -1 : 1;
637 * g_bytes_unref_to_data:
638 * @bytes: (transfer full): a #GBytes
639 * @size: location to place the length of the returned data
641 * Unreferences the bytes, and returns a pointer the same byte data
644 * As an optimization, the byte data is returned without copying if this was
645 * the last reference to bytes and bytes was created with g_bytes_new(),
646 * g_bytes_new_take() or g_byte_array_free_to_bytes(). In all other cases the
649 * Returns: (transfer full): a pointer to the same byte data, which should
650 * be freed with g_free()
655 g_bytes_unref_to_data (GBytes *bytes,
660 g_return_val_if_fail (bytes != NULL, NULL);
661 g_return_val_if_fail (size != NULL, NULL);
665 * Optimal path: if this is was the last reference, then we can return
666 * the data from this GBytes without copying.
668 if (G_BYTES_IS_FREE(bytes) && g_atomic_int_get (&bytes->ref_count) == 1)
670 GBytesData *data_bytes = (GBytesData *) bytes;
672 result = data_bytes->data;
675 g_slice_free (GBytesData, data_bytes);
681 data = g_bytes_get_data (bytes, size);
682 result = g_memdup (data, *size);
683 g_bytes_unref (bytes);
690 * g_bytes_unref_to_array:
691 * @bytes: (transfer full): a #GBytes
693 * Unreferences the bytes, and returns a new mutable #GByteArray containing
694 * the same byte data.
696 * As an optimization, the byte data is transferred to the array without copying
697 * if this was the last reference to bytes and bytes was created with
698 * g_bytes_new(), g_bytes_new_take() or g_byte_array_free_to_bytes(). In all
699 * other cases the data is copied.
701 * Returns: (transfer full): a new mutable #GByteArray containing the same byte data
706 g_bytes_unref_to_array (GBytes *bytes)
711 g_return_val_if_fail (bytes != NULL, NULL);
713 data = g_bytes_unref_to_data (bytes, &size);
714 return g_byte_array_new_take (data, size);