PROP_DICTIONARY_UTIL(3)

PROP_DICTIONARY_UTIL(3) | Library Functions Manual | PROP_DICTIONARY_UTIL(3)

# NAME

`prop_dictionary_util`, `prop_dictionary_get_dict`, `prop_dictionary_get_bool`, `prop_dictionary_set_bool`, `prop_dictionary_get_schar`, `prop_dictionary_get_uchar`, `prop_dictionary_set_schar`, `prop_dictionary_set_uchar`, `prop_dictionary_get_short`, `prop_dictionary_get_ushort`, `prop_dictionary_set_short`, `prop_dictionary_set_ushort`, `prop_dictionary_get_int`, `prop_dictionary_get_uint`, `prop_dictionary_set_int`, `prop_dictionary_set_uint`, `prop_dictionary_get_long`, `prop_dictionary_get_ulong`, `prop_dictionary_set_long`, `prop_dictionary_set_ulong`, `prop_dictionary_get_longlong`, `prop_dictionary_get_ulonglong`, `prop_dictionary_set_longlong`, `prop_dictionary_set_ulonglong`, `prop_dictionary_get_intptr`, `prop_dictionary_get_uintptr`, `prop_dictionary_set_intptr`, `prop_dictionary_set_uintptr`, `prop_dictionary_get_int8`, `prop_dictionary_get_uint8`, `prop_dictionary_set_int8`, `prop_dictionary_set_uint8`, `prop_dictionary_get_int16`, `prop_dictionary_get_uint16`, `prop_dictionary_set_int16`, `prop_dictionary_set_uint16`, `prop_dictionary_get_int32`, `prop_dictionary_get_uint32`, `prop_dictionary_set_int32`, `prop_dictionary_set_uint32`, `prop_dictionary_get_int64`, `prop_dictionary_get_uint64`, `prop_dictionary_set_int64`, `prop_dictionary_set_uint64`, `prop_dictionary_get_data`, `prop_dictionary_set_data`, `prop_dictionary_set_data_nocopy`, `prop_dictionary_get_string`, `prop_dictionary_set_string`, `prop_dictionary_set_string_nocopy`, `prop_dictionary_set_and_rel` —
dictionary property collection object utility functions

# LIBRARY

Property Container Object Library (libprop, -lprop)

# SYNOPSIS

`#include <prop/proplib.h>`

bool
`prop_dictionary_get_dict`(prop_dictionary_t dict, const char *key, prop_dictionary_t *dictp);

bool
`prop_dictionary_get_bool`(prop_dictionary_t dict, const char *key, bool *valp);

bool
`prop_dictionary_set_bool`(prop_dictionary_t dict, const char *key, bool val);

bool
`prop_dictionary_get_schar`(prop_dictionary_t dict, const char *key, signed char *valp);

bool
`prop_dictionary_get_uchar`(prop_dictionary_t dict, const char *key, unsigned char *valp);

bool
`prop_dictionary_set_schar`(prop_dictionary_t dict, const char *key, signed char val);

bool
`prop_dictionary_set_uchar`(prop_dictionary_t dict, const char *key, unsigned char val);

bool
`prop_dictionary_get_short`(prop_dictionary_t dict, const char *key, short *valp);

bool
`prop_dictionary_get_ushort`(prop_dictionary_t dict, const char *key, unsigned short *valp);

bool
`prop_dictionary_set_short`(prop_dictionary_t dict, const char *key, short val);

bool
`prop_dictionary_set_ushort`(prop_dictionary_t dict, const char *key, unsigned short val);

bool
`prop_dictionary_get_int`(prop_dictionary_t dict, const char *key, int *valp);

bool
`prop_dictionary_get_uint`(prop_dictionary_t dict, const char *key, unsigned int *valp);

bool
`prop_dictionary_set_int`(prop_dictionary_t dict, const char *key, int val);

bool
`prop_dictionary_set_uint`(prop_dictionary_t dict, const char *key, unsigned int val);

bool
`prop_dictionary_get_long`(prop_dictionary_t dict, const char *key, long *valp);

bool
`prop_dictionary_get_ulong`(prop_dictionary_t dict, const char *key, unsigned long *valp);

bool
`prop_dictionary_set_long`(prop_dictionary_t dict, const char *key, long val);

bool
`prop_dictionary_set_ulong`(prop_dictionary_t dict, const char *key, unsigned long val);

bool
`prop_dictionary_get_longlong`(prop_dictionary_t dict, const char *key, long long *valp);

bool
`prop_dictionary_get_ulonglong`(prop_dictionary_t dict, const char *key, unsigned long long *valp);

bool
`prop_dictionary_set_longlong`(prop_dictionary_t dict, const char *key, long long val);

bool
`prop_dictionary_set_ulonglong`(prop_dictionary_t dict, const char *key, unsigned long long val);

bool
`prop_dictionary_get_intptr`(prop_dictionary_t dict, const char *key, intptr_t *valp);

bool
`prop_dictionary_get_uintptr`(prop_dictionary_t dict, const char *key, uintptr_t *valp);

bool
`prop_dictionary_set_intptr`(prop_dictionary_t dict, const char *key, intptr_t val);

bool
`prop_dictionary_set_uintptr`(prop_dictionary_t dict, const char *key, uintptr_t val);

bool
`prop_dictionary_get_int8`(prop_dictionary_t dict, const char *key, int8_t *valp);

bool
`prop_dictionary_get_uint8`(prop_dictionary_t dict, const char *key, uint8_t *valp);

bool
`prop_dictionary_set_int8`(prop_dictionary_t dict, const char *key, int8_t val);

bool
`prop_dictionary_set_uint8`(prop_dictionary_t dict, const char *key, uint8_t val);

bool
`prop_dictionary_get_int16`(prop_dictionary_t dict, const char *key, int16_t *valp);

bool
`prop_dictionary_get_uint16`(prop_dictionary_t dict, const char *key, uint16_t *valp);

bool
`prop_dictionary_set_int16`(prop_dictionary_t dict, const char *key, int16_t val);

bool
`prop_dictionary_set_uint16`(prop_dictionary_t dict, const char *key, uint16_t val);

bool
`prop_dictionary_get_int32`(prop_dictionary_t dict, const char *key, int32_t *valp);

bool
`prop_dictionary_get_uint32`(prop_dictionary_t dict, const char *key, uint32_t *valp);

bool
`prop_dictionary_set_int32`(prop_dictionary_t dict, const char *key, int32_t val);

bool
`prop_dictionary_set_uint32`(prop_dictionary_t dict, const char *key, uint32_t val);

bool
`prop_dictionary_get_int64`(prop_dictionary_t dict, const char *key, int64_t *valp);

bool
`prop_dictionary_get_uint64`(prop_dictionary_t dict, const char *key, uint64_t *valp);

bool
`prop_dictionary_set_int64`(prop_dictionary_t dict, const char *key, int64_t val);

bool
`prop_dictionary_set_uint64`(prop_dictionary_t dict, const char *key, uint64_t val);

bool
`prop_dictionary_get_cstring`(prop_dictionary_t dict, const char *key, char **strp);

bool
`prop_dictionary_set_cstring`(prop_dictionary_t dict, const char *key, const char *str);

bool
`prop_dictionary_get_data`(prop_dictionary_t dict, const char *key, const void **datap, size_t *sizep);

bool
`prop_dictionary_set_data`(prop_dictionary_t dict, const char *key, const void *data, size_t len);

bool
`prop_dictionary_set_data_nocopy`(prop_dictionary_t dict, const char *key, const void *data, size_t len);

bool
`prop_dictionary_get_string`(prop_dictionary_t dict, const char *key, const char **strp);

bool
`prop_dictionary_set_string`(prop_dictionary_t dict, const char *key, const char *strp);

bool
`prop_dictionary_set_string_nocopy`(prop_dictionary_t dict, const char *key, const char *strp);

bool
`prop_dictionary_set_and_rel`(prop_dictionary_t dict, const char *key, prop_object_t obj);

# DESCRIPTION

The `prop_dictionary_util` family of functions are provided to make getting and setting values in dictionaries more convenient in some applications.

The getters check the type of the returned object and, in some cases, also ensure that the returned value is within the range implied by the getter's value type.

The setters handle object creation and release for the caller.

If the sizep argument to `prop_dictionary_get_data`() is not `NULL`, then it will be set to the size of the returned data.

The `prop_dictionary_get_data`() and `prop_dictionary_set_data_nocopy`() functions do not copy the data that is set or returned. See prop_data(3) for more information.

The `prop_dictionary_get_string`() and `prop_dictionary_set_string_nocopy`() functions do not copy the string that is set or returned. See prop_string(3) for more information.

The `prop_dictionary_set_and_rel`() function adds the object to the dictionary and releases it. The object is always released, even if adding it to the dictionary fails.

# RETURN VALUES

The `prop_dictionary_util` getter functions return `true` if the object exists in the dictionary and the value is in-range, or `false` otherwise.

The `prop_dictionary_util` setter functions return `true` if creating the object and storing it in the dictionary is successful, or `false` otherwise.

# SEE ALSO

prop_bool(3), prop_data(3), prop_dictionary(3), prop_number(3), prop_string(3), proplib(3)

# HISTORY

The proplib(3) property container object library first appeared in NetBSD 4.0.

June 2, 2020 | NetBSD 10.1