Memory Allocation
D-Bus low-level public API

dbus_malloc(), dbus_free(), etc. More...

## Macros

#define | dbus_new(type, count)
| Safe macro for using dbus_malloc().
#define | dbus_new0(type, count)
| Safe macro for using dbus_malloc0().

## Typedefs

typedef void(* | DBusFreeFunction) (void *memory)
| The type of a function which frees a block of memory.

## Functions

void * | dbus_malloc (size_t bytes)
| Allocates the given number of bytes, as with standard malloc().
void * | dbus_malloc0 (size_t bytes)
| Allocates the given number of bytes, as with standard malloc(), but all bytes are initialized to zero as with calloc().
void * | dbus_realloc (void *memory, size_t bytes)
| Resizes a block of memory previously allocated by dbus_malloc() or dbus_malloc0().
void | dbus_free (void *memory)
| Frees a block of memory previously allocated by dbus_malloc() or dbus_malloc0().
void | dbus_free_string_array (char **str_array)
| Frees a NULL-terminated array of strings.
void | dbus_shutdown (void)
| Frees all memory allocated internally by libdbus and reverses the effects of dbus_threads_init().

## Detailed Description

dbus_malloc(), dbus_free(), etc.

Functions and macros related to allocating and releasing blocks of memory.

## Macro Definition Documentation

## dbus_new

#define dbus_new | ( |  | type,
|  |  | count )

Value:
((type*)dbus_malloc (sizeof (type) * (count)))
dbus_malloc
void * dbus_malloc(size_t bytes)
Allocates the given number of bytes, as with standard malloc().
Definition dbus-memory.c:470

Safe macro for using dbus_malloc().

Accepts the type to allocate and the number of type instances to allocate as arguments, and returns a memory block cast to the desired type, instead of as a void*.

Parameters

  type | type name to allocate
  count | number of instances in the allocated array

Returns
  the new memory block or NULL on failure

Definition at line 59 of file dbus-memory.h.

Referenced by _dbus_credentials_add_credential(), _dbus_credentials_new(), _dbus_groups_from_uid(), _dbus_listen_systemd_sockets(), _dbus_server_new_for_socket(), dbus_message_copy(), and dbus_parse_address().

## dbus_new0

#define dbus_new0 | ( |  | type,
|  |  | count )

Value:
((type*)dbus_malloc0 (sizeof (type) * (count)))
dbus_malloc0
void * dbus_malloc0(size_t bytes)
Allocates the given number of bytes, as with standard malloc(), but all bytes are initialized to zero...
Definition dbus-memory.c:540

Safe macro for using dbus_malloc0().

Accepts the type to allocate and the number of type instances to allocate as arguments, and returns a memory block cast to the desired type, instead of as a void*. The allocated array is initialized to all-bits-zero.

Parameters

  type | type name to allocate
  count | number of instances in the allocated array

Returns
  the new memory block or NULL on failure

Definition at line 60 of file dbus-memory.h.

Referenced by _dbus_connection_new_for_transport(), _dbus_counter_new(), _dbus_decompose_path(), _dbus_directory_open(), _dbus_dup_string_array(), _dbus_get_environment(), _dbus_hash_table_new(), _dbus_hash_table_to_array(), _dbus_listen_tcp_socket(), _dbus_mem_pool_new(), _dbus_message_iter_get_args_valist(), _dbus_message_loader_new(), _dbus_object_tree_new(), _dbus_pending_call_new_unlocked(), _dbus_server_new_for_socket(), _dbus_timeout_list_new(), _dbus_timeout_new(), _dbus_transport_new_for_socket(), _dbus_user_database_lookup(), _dbus_user_database_lookup_group(), _dbus_user_database_new(), _dbus_variant_read(), _dbus_watch_list_new(), _dbus_watch_new(), dbus_connection_add_filter(), dbus_message_copy(), and dbus_parse_address().

## Typedef Documentation

## DBusFreeFunction

typedef void(* DBusFreeFunction) (void *memory)

The type of a function which frees a block of memory.

Parameters

  memory | the memory to free

Definition at line 65 of file dbus-memory.h.

## Function Documentation

## dbus_free()

DBUS_EXPORT void dbus_free | ( | void * | memory | ) |

Frees a block of memory previously allocated by dbus_malloc() or dbus_malloc0().

If passed NULL, does nothing.

Parameters

  memory | block to be freed

Definition at line 710 of file dbus-memory.c.

References _dbus_assert, _dbus_atomic_dec(), and TRUE.

Referenced by _dbus_auth_unref(), _dbus_babysitter_unref(), _dbus_connection_new_for_transport(), _dbus_counter_new(), _dbus_counter_unref(), _dbus_credentials_add_adt_audit_data(), _dbus_credentials_add_linux_security_label(), _dbus_credentials_add_windows_sid(), _dbus_credentials_clear(), _dbus_credentials_take_unix_gids(), _dbus_credentials_unref(), _dbus_data_slot_allocator_free(), _dbus_data_slot_list_free(), _dbus_directory_close(), _dbus_directory_open(), _dbus_group_info_free(), _dbus_group_info_unref(), _dbus_hash_table_new(), _dbus_hash_table_unref(), _dbus_keyring_unref(), _dbus_listen_systemd_sockets(), _dbus_listen_tcp_socket(), _dbus_mem_pool_dealloc(), _dbus_mem_pool_free(), _dbus_message_loader_new(), _dbus_message_loader_unref(), _dbus_object_tree_new(), _dbus_object_tree_register(), _dbus_object_tree_unref(), _dbus_pending_call_new_unlocked(), _dbus_printf_string_upper_bound(), _dbus_server_finalize_base(), _dbus_server_init_base(), _dbus_server_listen_platform_specific(), _dbus_server_new_for_domain_socket(), _dbus_server_new_for_socket(), _dbus_server_new_for_tcp_socket(), _dbus_set_up_transient_session_servicedirs(), _dbus_split_paths_and_append(), _dbus_string_free(), _dbus_timeout_list_free(), _dbus_timeout_unref(), _dbus_transport_finalize_base(), _dbus_transport_new_for_socket(), _dbus_transport_open(), _dbus_user_database_unref(), _dbus_user_info_free(), _dbus_user_info_unref(), _dbus_variant_read(), _dbus_watch_list_free(), _dbus_watch_unref(), dbus_address_entries_free(), dbus_connection_free_preallocated_send(), dbus_error_free(), dbus_free_string_array(), dbus_message_copy(), dbus_parse_address(), dbus_realloc(), and dbus_shutdown().

## dbus_free_string_array()

DBUS_EXPORT void dbus_free_string_array | ( | char ** | str_array | ) |

Frees a NULL-terminated array of strings.

If passed NULL, does nothing.

Parameters

  str_array | the array to be freed

Definition at line 758 of file dbus-memory.c.

References dbus_free().

Referenced by _dbus_auth_set_mechanisms(), _dbus_auth_unref(), _dbus_decompose_path(), _dbus_dup_string_array(), _dbus_get_environment(), _dbus_hash_table_to_array(), _dbus_message_iter_get_args_valist(), _dbus_object_tree_dispatch_and_unlock(), _dbus_server_finalize_base(), dbus_connection_get_object_path_data(), dbus_connection_list_registered(), dbus_connection_unregister_object_path(), and dbus_server_set_auth_mechanisms().

## dbus_malloc()

DBUS_EXPORT DBUS_MALLOC void * dbus_malloc | ( | size_t | bytes | ) |

Allocates the given number of bytes, as with standard malloc().

Guaranteed to return NULL if bytes is zero on all platforms. Returns NULL if the allocation fails. The memory must be released with dbus_free().

dbus_malloc() memory is NOT safe to free with regular free() from the C library. Free it with dbus_free() only.

Parameters

  bytes | number of bytes to allocate

Returns
  allocated memory, or NULL if the allocation fails.

Definition at line 470 of file dbus-memory.c.

References _dbus_abort(), _dbus_atomic_inc(), _dbus_warn(), and NULL.

Referenced by _dbus_mem_pool_alloc(), _dbus_memdup(), _dbus_printf_string_upper_bound(), _dbus_strdup(), _dbus_string_copy_data(), and _dbus_string_init_preallocated().

## dbus_malloc0()

DBUS_EXPORT DBUS_MALLOC void * dbus_malloc0 | ( | size_t | bytes | ) |

Allocates the given number of bytes, as with standard malloc(), but all bytes are initialized to zero as with calloc().

Guaranteed to return NULL if bytes is zero on all platforms. Returns NULL if the allocation fails. The memory must be released with dbus_free().

dbus_malloc0() memory is NOT safe to free with regular free() from the C library. Free it with dbus_free() only.

Parameters

  bytes | number of bytes to allocate

Returns
  allocated memory, or NULL if the allocation fails.

Definition at line 540 of file dbus-memory.c.

References _dbus_abort(), _dbus_atomic_inc(), _dbus_warn(), and NULL.

Referenced by _dbus_mem_pool_alloc().

## dbus_realloc()

DBUS_EXPORT void * dbus_realloc | ( | void * | memory,
|  | size_t | bytes )

Resizes a block of memory previously allocated by dbus_malloc() or dbus_malloc0().

Guaranteed to free the memory and return NULL if bytes is zero on all platforms. Returns NULL if the resize fails. If the resize fails, the memory is not freed.

Parameters

  memory | block to be resized
  bytes | new size of the memory block

Returns
  allocated memory, or NULL if the resize fails.

Definition at line 610 of file dbus-memory.c.

References _dbus_abort(), _dbus_atomic_inc(), _dbus_warn(), dbus_free(), FALSE, and NULL.

Referenced by _dbus_data_slot_allocator_alloc(), _dbus_data_slot_list_set(), and _dbus_listen_tcp_socket().

## dbus_shutdown()

DBUS_EXPORT void dbus_shutdown | ( | void |  | ) |

Frees all memory allocated internally by libdbus and reverses the effects of dbus_threads_init().

libdbus keeps internal global variables, for example caches and thread locks, and it can be useful to free these internal data structures.

dbus_shutdown() does NOT free memory that was returned to the application. It only frees libdbus-internal data structures.

You MUST free all memory and release all reference counts returned to you by libdbus prior to calling dbus_shutdown().

If a shared connection is open, calling dbus_shutdown() will drain its queue of messages and disconnect it. In particular, this will result in processing of the special Disconnected signal, which may result in a call to _exit(), unless you have used dbus_connection_set_exit_on_disconnect() to disable that behaviour.

You can't continue to use any D-Bus objects, such as connections, that were allocated prior to dbus_shutdown(). You can, however, start over; call dbus_threads_init() again, create new connections, and so forth.

WARNING: dbus_shutdown() is NOT thread safe, it must be called while NO other threads are using D-Bus. (Remember, you have to free all D-Bus objects and memory before you call dbus_shutdown(), so no thread can be using libdbus.)

The purpose of dbus_shutdown() is to allow applications to get clean output from memory leak checkers. dbus_shutdown() may also be useful if you want to dlopen() libdbus instead of linking to it, and want to be able to unload the library again.

There is absolutely no requirement to call dbus_shutdown() - in fact, most applications won't bother and should not feel guilty.

You have to know that nobody is using libdbus in your application's process before you can call dbus_shutdown(). One implication of this is that calling dbus_shutdown() from a library is almost certainly wrong, since you don't know what the rest of the app is up to.

Definition at line 906 of file dbus-memory.c.

References _dbus_current_generation, _dbus_threads_lock_platform_specific(), _dbus_threads_unlock_platform_specific(), ShutdownClosure::data, dbus_free(), ShutdownClosure::func, ShutdownClosure::next, and NULL.