1.\" $NetBSD: prop_object.3,v 1.11 2025/04/23 02:58:52 thorpej Exp $ 2.\" 3.\" Copyright (c) 2006, 2025 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 April 20, 2025 31.Dt PROP_OBJECT 3 32.Os 33.Sh NAME 34.Nm prop_object , 35.Nm prop_object_retain , 36.Nm prop_object_release , 37.Nm prop_object_type , 38.Nm prop_object_equals , 39.Nm prop_object_iterator_next , 40.Nm prop_object_iterator_reset , 41.Nm prop_object_iterator_release , 42.Nm prop_object_externalize , 43.Nm prop_object_externalize_with_format , 44.Nm prop_object_externalize_to_file , 45.Nm prop_object_externalize_to_file_with_format , 46.Nm prop_object_internalize , 47.Nm prop_object_internalize_from_file 48.Nd general property container object functions 49.Sh LIBRARY 50.Lb libprop 51.Sh SYNOPSIS 52.In prop/proplib.h 53.\" 54.Ft void 55.Fn prop_object_retain "prop_object_t obj" 56.Ft void 57.Fn prop_object_release "prop_object_t obj" 58.\" 59.Ft prop_type_t 60.Fn prop_object_type "prop_object_t obj" 61.Ft bool 62.Fn prop_object_equals "prop_object_t obj1" "prop_object_t obj2" 63.\" 64.Ft prop_object_t 65.Fn prop_object_iterator_next "prop_object_iterator_t iter" 66.Ft void 67.Fn prop_object_iterator_reset "prop_object_iterator_t iter" 68.Ft void 69.Fn prop_object_iterator_release "prop_object_iterator_t iter" 70.\" 71.Ft char * 72.Fn prop_object_externalize "prop_object_t obj" 73.Ft char * 74.Fn prop_object_externalize_with_format "prop_object_t obj" \ 75 "prop_format_t format" 76.Ft bool 77.Fn prop_object_externalize_to_file "prop_object_t obj" "const char *path" 78.Ft bool 79.Fn prop_object_externalize_to_file_with_format "prop_object_t obj" \ 80 "const char *path" "prop_format_t format" 81.\" 82.Ft prop_object_t 83.Fn prop_object_internalize "const char *data" 84.Ft prop_object_t 85.Fn prop_object_internalize_from_file "const char *path" 86.Sh DESCRIPTION 87The 88.Nm 89family of functions operate on all property container object types. 90.Bl -tag -width "" 91.It Fn prop_object_retain "prop_object_t obj" 92Increment the reference count on an object. 93.It Fn prop_object_release "prop_object_t obj" 94Decrement the reference count on an object. 95If the last reference is dropped, the object is freed. 96.It Fn prop_object_type "prop_object_t obj" 97Determine the type of the object. 98Objects are one of the following types: 99.Pp 100.Bl -tag -width "PROP_TYPE_DICT_KEYSYM" -compact 101.It Dv PROP_TYPE_BOOL 102Boolean value 103.Pq prop_bool_t 104.It Dv PROP_TYPE_NUMBER 105Number 106.Pq prop_number_t 107.It Dv PROP_TYPE_STRING 108String 109.Pq prop_string_t 110.It Dv PROP_TYPE_DATA 111Opaque data 112.Pq prop_data_t 113.It Dv PROP_TYPE_ARRAY 114Array 115.Pq prop_array_t 116.It Dv PROP_TYPE_DICTIONARY 117Dictionary 118.Pq prop_dictionary_t 119.It Dv PROP_TYPE_DICT_KEYSYM 120Dictionary key symbol 121.Pq prop_dictionary_keysym_t 122.El 123.Pp 124If 125.Fa obj 126is 127.Dv NULL , 128then 129.Dv PROP_TYPE_UNKNOWN 130is returned. 131.It Fn prop_object_equals "prop_object_t obj1" "prop_object_t obj2" 132Returns 133.Dv true 134if the two objects are of the same type and are equivalent. 135.It Fn prop_object_iterator_next "prop_object_iterator_t iter" 136Return the next object in the collection 137.Pq array or dictionary 138being iterated by the iterator 139.Fa iter . 140If there are no more objects in the collection, 141.Dv NULL 142is returned. 143.It Fn prop_object_iterator_reset "prop_object_iterator_t iter" 144Reset the iterator to the first object in the collection being iterated 145by the iterator 146.Fa iter . 147.It Fn prop_object_iterator_release "prop_object_iterator_t iter" 148Release the iterator 149.Fa iter . 150.It Fn prop_object_externalize "prop_object_t obj" 151Externalizes an object, returning a NUL-terminated buffer containing 152a representation of the object in the default format 153.Pq XML property list . 154The caller is responsible for freeing the returned buffer. 155If converting to the external representation fails for any reason, 156.Dv NULL 157is returned. 158.Pp 159In user space, the buffer is allocated using 160.Xr malloc 3 . 161In the kernel, the buffer is allocated using 162.Xr malloc 9 163using the malloc type 164.Dv M_TEMP . 165.It Fn prop_object_externalize_with_format "prop_object_t obj" \ 166 "prop_format_t format" 167Like 168.Fn prop_object_externalize , 169except the output format is specified explicitly. 170The following formats are supported: 171.Pp 172.Bl -tag -width "PROP_FORMAT_JSON" -compact 173.It Dv PROP_FORMAT_JSON 174RFC 8259 JSON format 175.It Dv PROP_FORMAT_XML 176XML property list format 177.El 178.It Fn prop_object_externalize_to_file "prop_object_t" \ 179 "const char *path" 180.It Fn prop_object_externalize_to_file_with_format "prop_object_t" \ 181 "const char *path" "prop_format_t format" 182Like 183.Fn prop_object_externalize 184and 185.Fn prop_object_externalize_with_format , 186except the external representation is written to the file specified by 187.Fa path . 188The file is saved with the mode 189.Dv 0666 190as modified by the process's file creation mask 191.Pq see Xr umask 2 192and is written atomically. 193Returns 194.Dv false 195if externalizing the object or writing the file fails for any reason. 196.It Fn prop_object_internalize "const char *data" 197Parses the external representation of an object in the NUL-terminated 198buffer 199.Fa data 200and returns the corresponding object. 201The format of the external representation is detected automatically. 202Returns 203.Dv NULL 204if parsing fails for any reason. 205.It Fn prop_object_internalize_from_file "const char *path" 206.El 207.Sh SEE ALSO 208.Xr prop_array 3 , 209.Xr prop_bool 3 , 210.Xr prop_data 3 , 211.Xr prop_dictionary 3 , 212.Xr prop_number 3 , 213.Xr prop_string 3 , 214.Xr proplib 3 215.Sh HISTORY 216The 217.Xr proplib 3 218property container object library first appeared in 219.Nx 4.0 . 220