1.\" $NetBSD: prop_string.3,v 1.7 2009/12/14 06:06:22 dholland Exp $ 2.\" 3.\" Copyright (c) 2006 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 January 21, 2008 31.Dt PROP_STRING 3 32.Os 33.Sh NAME 34.Nm prop_string , 35.Nm prop_string_create , 36.Nm prop_string_create_cstring , 37.Nm prop_string_create_cstring_nocopy , 38.Nm prop_string_copy , 39.Nm prop_string_copy_mutable , 40.Nm prop_string_size , 41.Nm prop_string_mutable , 42.Nm prop_string_cstring , 43.Nm prop_string_cstring_nocopy , 44.Nm prop_string_append , 45.Nm prop_string_append_cstring , 46.Nm prop_string_equals , 47.Nm prop_string_equals_cstring 48.Nd string value property object 49.Sh LIBRARY 50.Lb libprop 51.Sh SYNOPSIS 52.In libprop/proplib.h 53.\" 54.Ft prop_string_t 55.Fn prop_string_create "void" 56.Ft prop_string_t 57.Fn prop_string_create_cstring "const char *cstring" 58.Ft prop_string_t 59.Fn prop_string_create_cstring_nocopy "const char *cstring" 60.\" 61.Ft prop_string_t 62.Fn prop_string_copy "prop_string_t string" 63.Ft prop_string_t 64.Fn prop_string_copy_mutable "prop_string_t string" 65.\" 66.Ft size_t 67.Fn prop_string_size "prop_string_t string" 68.Ft bool 69.Fn prop_string_mutable "prop_string_t string" 70.\" 71.Ft char * 72.Fn prop_string_cstring "prop_string_t string" 73.Ft const char * 74.Fn prop_string_cstring_nocopy "prop_string_t string" 75.\" 76.Ft bool 77.Fn prop_string_append "prop_string_t str1" "prop_string_t str2" 78.Ft bool 79.Fn prop_string_append_cstring "prop_string_t string" "const char *cstring" 80.\" 81.Ft bool 82.Fn prop_string_equals "prop_string_t str1" "prop_string_t str2" 83.Ft bool 84.Fn prop_string_equals_cstring "prop_string_t string" "const char *cstring" 85.Sh DESCRIPTION 86The 87.Nm prop_string 88family of functions operate on a string value property object type. 89.Bl -tag -width "xxxxx" 90.It Fn prop_string_create "void" 91Create an empty mutable string. 92Returns 93.Dv NULL 94on failure. 95.It Fn prop_string_create_cstring "const char *cstring" 96Create a mutable string that contains a copy of 97.Fa cstring . 98Returns 99.Dv NULL 100on failure. 101.It Fn prop_string_create_cstring_nocopy "const char *cstring" 102Create an immutable string that contains a reference to 103.Fa cstring . 104Returns 105.Dv NULL 106on failure. 107.It Fn prop_string_copy "prop_string_t string" 108Copy a string. 109If the string being copied is an immutable external C string reference, 110then the copy is also immutable and references the same external C string. 111Returns 112.Dv NULL 113on failure. 114.It Fn prop_string_copy_mutable "prop_string_t string" 115Copy a string, always creating a mutable copy. 116Returns 117.Dv NULL 118on failure. 119.It Fn prop_string_size "prop_string_t string" 120Returns the size of the string, not including the terminating NUL. 121If the supplied object isn't a string, zero is returned. 122.It Fn prop_string_mutable "prop_string_t string" 123Returns 124.Dv true 125if the string is mutable. 126If the supplied object isn't a string, 127.Dv false 128is returned. 129.It Fn prop_string_cstring "prop_string_t string" 130Returns a copy of the string's contents as a C string. 131The caller is responsible for freeing the returned buffer. 132.Pp 133In user space, the buffer is allocated using 134.Xr malloc 3 . 135In the kernel, the buffer is allocated using 136.Xr kmalloc 9 137using the malloc type 138.Dv M_TEMP . 139.Pp 140Returns 141.Dv NULL 142on failure. 143.It Fn prop_string_cstring_nocopy "prop_string_t string" 144Returns an immutable reference to the contents of the string as a 145C string. 146If the supplied object isn't a string, 147.Dv NULL 148is returned. 149.It Fn prop_string_append "prop_string_t str1" "prop_string_t str2" 150Append the contents of 151.Fa str2 152to 153.Fa str1 , 154which must be mutable. 155Returns 156.Dv true 157upon success and 158.Dv false 159otherwise. 160.It Fn prop_string_append_cstring "prop_string_t string" "const char *cstring" 161Append the C string 162.Fa cstring 163to 164.Fa string , 165which must be mutable. 166Returns 167.Dv true 168upon success and 169.Dv false 170otherwise. 171.It Fn prop_string_equals "prop_string_t str1" "prop_string_t str2" 172Returns 173.Dv true 174if the two string objects are equivalent. 175.It Fn prop_string_equals_cstring "prop_string_t string" "const char *cstring" 176Returns 177.Dv true 178if the string's value is equivalent to 179.Fa cstring . 180.El 181.Sh SEE ALSO 182.Xr prop_array 3 , 183.Xr prop_bool 3 , 184.Xr prop_data 3 , 185.Xr prop_dictionary 3 , 186.Xr prop_number 3 , 187.Xr prop_object 3 , 188.Xr proplib 3 189.Sh HISTORY 190The 191.Nm proplib 192property container object library first appeared in 193.Nx 4.0 . 194