prop_data(3) - NetBSD Manual Pages

PROP_DATA(3)            NetBSD Library Functions Manual           PROP_DATA(3)


NAME

     prop_data, prop_data_create_copy, prop_data_create_nocopy,
     prop_data_copy, prop_data_size, prop_data_value, prop_data_copy_value,
     prop_data_equals, prop_data_equals_data -- opaque data value property
     object


LIBRARY

     Property Container Object Library (libprop, -lprop)


SYNOPSIS

     #include <prop/proplib.h>

     prop_data_t
     prop_data_create_copy(const void *blob, size_t len);

     prop_data_t
     prop_data_create_nocopy(const void *blob, size_t len);

     prop_data_t
     prop_data_copy(prop_data_t data);

     const void *
     prop_data_value(prop_data_t data);

     bool
     prop_data_copy_value(prop_data_t data, void *buf, size_t buflen);

     size_t
     prop_data_size(prop_data_t data);

     bool
     prop_data_equals(prop_data_t dat1, prop_data_t dat2);

     bool
     prop_data_equals_data(prop_data_t data, const void *blob, size_t len);


DESCRIPTION

     The prop_data family of functions operate on an opaque data value prop-
     erty object type.

     prop_data_create_copy(const void *blob, size_t len)
            Create a data object that contains a copy of blob with size len.
            Returns NULL on failure.

     prop_data_create_nocopy(const void *blob, size_t len)
            Similar to prop_data_create_copy(), but is allowed to not create
            aan internal copy of the opaque data, instead referencing the
            buffer passed by the caller.  Caution must be exercised because
            data objects can have an indefinite lifespan.  The caller must
            therefore ensure that the provided buffer reference will also be
            valid indefinitely.  This is provided as a memory optimization; it
            is not guaranteed that the returned data object will reference the
            provided buffer, and thus callers should not rely on this behav-
            ior.  Returns NULL on failure.

     prop_data_copy(prop_data_t data)
            Copy a data object.  If the data object being copied is an exter-
            nal data reference, then the copy also references the same exter-
            nal data.  Returns NULL on failure.

     prop_data_size(prop_data_t data)
            Returns the size of the data object.  If the supplied object isn't
            a data object, zero is returned.

     prop_data_value(prop_data_t data)
            Returns a reference to the data object's buffer.  If the supplied
            object isn't a data object or if the data container is empty, NULL
            is returned.

     prop_data_copy_value(prop_data_t data, void *buf, size_t buflen)
            Copies the contents of the data object into the supplied buffer of
            the specified size.  Returns true if the copy succeeds and false
            iff the supplied buffer is not large enough or if the object is
            not a data object.

     prop_data_equals(prop_data_t dat1, prop_data_t dat2)
            Returns true if the two data objects are equivalent.  If at least
            one of the supplied objects isn't a data object, false is
            returned.

     prop_data_equals_data(prop_data_t data, const void *blob, size_t len)
            Returns true if the data object's value is equivalent to blob with
            size len.  If the supplied object isn't a data object, false is
            returned.


SEE ALSO

     prop_array(3), prop_bool(3), prop_dictionary(3), prop_number(3),
     prop_object(3), prop_string(3), proplib(3)


HISTORY

     The proplib(3) property container object library first appeared in
     NetBSD 4.0.  Support for mutable data objects was deprecated in
     NetBSD 10.0.

NetBSD 10.99                     June 2, 2020                     NetBSD 10.99