1.\" $NetBSD: prop_string.3,v 1.4 2007/08/16 16:31:00 thorpej 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.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd April 22, 2006 38.Dt PROP_STRING 3 39.Os 40.Sh NAME 41.Nm prop_string , 42.Nm prop_string_create , 43.Nm prop_string_create_cstring , 44.Nm prop_string_create_cstring_nocopy , 45.Nm prop_string_copy , 46.Nm prop_string_copy_mutable , 47.Nm prop_string_size , 48.Nm prop_string_mutable , 49.Nm prop_string_cstring , 50.Nm prop_string_cstring_nocopy , 51.Nm prop_string_append , 52.Nm prop_string_append_cstring , 53.Nm prop_string_equals , 54.Nm prop_string_equals_cstring 55.Nd string value property object 56.Sh LIBRARY 57.Lb libprop 58.Sh SYNOPSIS 59.In prop/proplib.h 60.\" 61.Ft prop_string_t 62.Fn prop_string_create "void" 63.Ft prop_string_t 64.Fn prop_string_create_cstring "const char *cstring" 65.Ft prop_string_t 66.Fn prop_string_create_cstring_nocopy "const char *cstring" 67.\" 68.Ft prop_string_t 69.Fn prop_string_copy "prop_string_t string" 70.Ft prop_string_t 71.Fn prop_string_copy_mutable "prop_string_t string" 72.\" 73.Ft char * 74.Fn prop_string_cstring "prop_string_t string" 75.Ft const char * 76.Fn prop_string_cstring_nocopy "prop_string_t string" 77.\" 78.Ft bool 79.Fn prop_string_append "prop_string_t str1" "prop_string_t str2" 80.Ft bool 81.Fn prop_string_append_cstring "prop_string_t string" "const char *cstring" 82.\" 83.Ft bool 84.Fn prop_string_equals "prop_string_t str1" "prop_string_t str2" 85.Ft bool 86.Fn prop_string_equals_cstring "prop_string_t string" "const char *cstring" 87.Sh DESCRIPTION 88The 89.Nm prop_string 90family of functions operate on a string value property object type. 91.Bl -tag -width "xxxxx" 92.It Fn prop_string_create "void" 93Create an empty mutable string. 94.It Fn prop_string_create_cstring "const char *cstring" 95Create a mutable string that contains a copy of 96.Fa cstring . 97.It Fn prop_string_create_cstring_nocopy "const char *cstring" 98Create an immutable string that contains a reference to 99.Fa cstring . 100.It Fn prop_string_copy "prop_string_t string" 101Copy a string. 102If the the string being copied is an immutable external C string reference, 103then the copy is also immutable and references the same external C string. 104.It Fn prop_string_copy_mutable "prop_string_t string" 105Copy a string, always creating a mutable copy. 106.It Fn prop_string_size "prop_string_t string" 107Returns the size of the string, not including the terminating NUL. 108.It Fn prop_string_mutable "prop_string_t string" 109Returns 110.Dv true 111if the string is mutable. 112.It Fn prop_string_cstring "prop_string_t string" 113Returns a copy of the string's contents as a C string. 114The caller is responsible for freeing the returned buffer. 115.Pp 116In user space, the buffer is allocated using 117.Xr malloc 3 . 118In the kernel, the buffer is allocated using 119.Xr malloc 9 120using the malloc type 121.Dv M_TEMP . 122.It Fn prop_string_cstring_nocopy "prop_string_t string" 123Returns an immutable reference to the contents of the string as a 124C string. 125.It Fn prop_string_append "prop_string_t str1" "prop_string_t str2" 126Append the contents of 127.Fa str2 128to 129.Fa str1 , 130which must be mutable. 131Returns 132.Dv true 133upon success and 134.Dv false 135otherwise. 136.It Fn prop_string_append_cstring "prop_string_t string" "const char *cstring" 137Append the C string 138.Fa cstring 139to 140.Fa string , 141which must be mutable. 142Returns 143.Dv true 144upon success and 145.Dv false 146otherwise. 147.It Fn prop_string_equals "prop_string_t str1" "prop_string_t str2" 148Returns 149.Dv true 150if the two string objects are equivalent. 151.It Fn prop_string_equals_cstring "prop_string_t string" "const char *cstring" 152Returns 153.Dv true 154if the string's value is equivalent to 155.Fa cstring . 156.El 157.Sh SEE ALSO 158.Xr prop_array 3 , 159.Xr prop_bool 3 , 160.Xr prop_data 3 , 161.Xr prop_dictionary 3 , 162.Xr prop_number 3 , 163.Xr prop_object 3 , 164.Xr proplib 3 165.Sh HISTORY 166The 167.Nm proplib 168property container object library first appeared in 169.Nx 4.0 . 170