1.\" $NetBSD: prop_data.3,v 1.9 2020/06/06 21:25:59 thorpej Exp $ 2.\" 3.\" Copyright (c) 2006, 2020 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Jason R. Thorpe. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd June 2, 2020 31.Dt PROP_DATA 3 32.Os 33.Sh NAME 34.Nm prop_data , 35.Nm prop_data_create_copy , 36.Nm prop_data_create_nocopy , 37.Nm prop_data_copy , 38.Nm prop_data_size , 39.Nm prop_data_value , 40.Nm prop_data_copy_value , 41.Nm prop_data_equals , 42.Nm prop_data_equals_data 43.Nd opaque data value property object 44.Sh LIBRARY 45.Lb libprop 46.Sh SYNOPSIS 47.In prop/proplib.h 48.\" 49.Ft prop_data_t 50.Fn prop_data_create_copy "const void *blob" "size_t len" 51.Ft prop_data_t 52.Fn prop_data_create_nocopy "const void *blob" "size_t len" 53.\" 54.Ft prop_data_t 55.Fn prop_data_copy "prop_data_t data" 56.\" 57.Ft const void * 58.Fn prop_data_value "prop_data_t data" 59.Ft bool 60.Fn prop_data_copy_value "prop_data_t data" "void *buf" "size_t buflen" 61.\" 62.Ft size_t 63.Fn prop_data_size "prop_data_t data" 64.\" 65.Ft bool 66.Fn prop_data_equals "prop_data_t dat1" "prop_data_t dat2" 67.Ft bool 68.Fn prop_data_equals_data "prop_data_t data" "const void *blob" "size_t len" 69.Sh DESCRIPTION 70The 71.Nm 72family of functions operate on an opaque data value property object type. 73.Bl -tag -width "xxxxx" 74.It Fn prop_data_create_copy "const void *blob" "size_t len" 75Create a data object that contains a copy of 76.Fa blob 77with size 78.Fa len . 79Returns 80.Dv NULL 81on failure. 82.It Fn prop_data_create_nocopy "const void *blob" "size_t len" 83Similar to 84.Fn prop_data_create_copy , 85but is allowed to not create aan internal copy of the opaque data, instead 86referencing the buffer passed by the caller. 87Caution must be exercised because data objects can have an indefinite 88lifespan. 89The caller must therefore ensure that the provided buffer reference will 90also be valid indefinitely. 91This is provided as a memory optimization; it is not guaranteed that 92the returned data object will reference the provided buffer, and thus 93callers should not rely on this behavior. 94Returns 95.Dv NULL 96on failure. 97.It Fn prop_data_copy "prop_data_t data" 98Copy a data object. 99If the data object being copied is an external data reference, 100then the copy also references the same external data. 101Returns 102.Dv NULL 103on failure. 104.It Fn prop_data_size "prop_data_t data" 105Returns the size of the data object. 106If the supplied object isn't a data object, zero is returned. 107.It Fn prop_data_value "prop_data_t data" 108Returns a reference to the data object's buffer. 109If the supplied object isn't a data object or 110if the data container is empty, 111.Dv NULL 112is returned. 113.It Fn prop_data_copy_value "prop_data_t data" "void *buf" "size_t buflen" 114Copies the contents of the data object into the supplied buffer of the 115specified size. 116Returns 117.Dv true 118if the copy succeeds and 119.Dv false 120iff the supplied buffer is not large enough or if the object is not a 121data object. 122.It Fn prop_data_equals "prop_data_t dat1" "prop_data_t dat2" 123Returns 124.Dv true 125if the two data objects are equivalent. 126If at least one of the supplied objects isn't a data object, 127.Dv false 128is returned. 129.It Fn prop_data_equals_data "prop_data_t data" "const void *blob" "size_t len" 130Returns 131.Dv true 132if the data object's value is equivalent to 133.Fa blob 134with size 135.Fa len . 136If the supplied object isn't a data object, 137.Dv false 138is returned. 139.El 140.Sh SEE ALSO 141.Xr prop_array 3 , 142.Xr prop_bool 3 , 143.Xr prop_dictionary 3 , 144.Xr prop_number 3 , 145.Xr prop_object 3 , 146.Xr prop_string 3 , 147.Xr proplib 3 148.Sh HISTORY 149The 150.Xr proplib 3 151property container object library first appeared in 152.Nx 4.0 . 153Support for mutable data objects was deprecated in 154.Nx 10.0 . 155