1.\" $NetBSD: prop_string.3,v 1.6 2008/04/30 13:10:46 martin 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 prop/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 char * 67.Fn prop_string_cstring "prop_string_t string" 68.Ft const char * 69.Fn prop_string_cstring_nocopy "prop_string_t string" 70.\" 71.Ft bool 72.Fn prop_string_append "prop_string_t str1" "prop_string_t str2" 73.Ft bool 74.Fn prop_string_append_cstring "prop_string_t string" "const char *cstring" 75.\" 76.Ft bool 77.Fn prop_string_equals "prop_string_t str1" "prop_string_t str2" 78.Ft bool 79.Fn prop_string_equals_cstring "prop_string_t string" "const char *cstring" 80.Sh DESCRIPTION 81The 82.Nm prop_string 83family of functions operate on a string value property object type. 84.Bl -tag -width "xxxxx" 85.It Fn prop_string_create "void" 86Create an empty mutable string. 87Returns 88.Dv NULL 89on failure. 90.It Fn prop_string_create_cstring "const char *cstring" 91Create a mutable string that contains a copy of 92.Fa cstring . 93Returns 94.Dv NULL 95on failure. 96.It Fn prop_string_create_cstring_nocopy "const char *cstring" 97Create an immutable string that contains a reference to 98.Fa cstring . 99Returns 100.Dv NULL 101on failure. 102.It Fn prop_string_copy "prop_string_t string" 103Copy a string. 104If the the string being copied is an immutable external C string reference, 105then the copy is also immutable and references the same external C string. 106Returns 107.Dv NULL 108on failure. 109.It Fn prop_string_copy_mutable "prop_string_t string" 110Copy a string, always creating a mutable copy. 111Returns 112.Dv NULL 113on failure. 114.It Fn prop_string_size "prop_string_t string" 115Returns the size of the string, not including the terminating NUL. 116If the supplied object isn't a string, zero is returned. 117.It Fn prop_string_mutable "prop_string_t string" 118Returns 119.Dv true 120if the string is mutable. 121If the supplied object isn't a string, 122.Dv false 123is returned. 124.It Fn prop_string_cstring "prop_string_t string" 125Returns a copy of the string's contents as a C string. 126The caller is responsible for freeing the returned buffer. 127.Pp 128In user space, the buffer is allocated using 129.Xr malloc 3 . 130In the kernel, the buffer is allocated using 131.Xr malloc 9 132using the malloc type 133.Dv M_TEMP . 134.Pp 135Returns 136.Dv NULL 137on failure. 138.It Fn prop_string_cstring_nocopy "prop_string_t string" 139Returns an immutable reference to the contents of the string as a 140C string. 141If the supplied object isn't a string, 142.Dv NULL 143is returned. 144.It Fn prop_string_append "prop_string_t str1" "prop_string_t str2" 145Append the contents of 146.Fa str2 147to 148.Fa str1 , 149which must be mutable. 150Returns 151.Dv true 152upon success and 153.Dv false 154otherwise. 155.It Fn prop_string_append_cstring "prop_string_t string" "const char *cstring" 156Append the C string 157.Fa cstring 158to 159.Fa string , 160which must be mutable. 161Returns 162.Dv true 163upon success and 164.Dv false 165otherwise. 166.It Fn prop_string_equals "prop_string_t str1" "prop_string_t str2" 167Returns 168.Dv true 169if the two string objects are equivalent. 170.It Fn prop_string_equals_cstring "prop_string_t string" "const char *cstring" 171Returns 172.Dv true 173if the string's value is equivalent to 174.Fa cstring . 175.El 176.Sh SEE ALSO 177.Xr prop_array 3 , 178.Xr prop_bool 3 , 179.Xr prop_data 3 , 180.Xr prop_dictionary 3 , 181.Xr prop_number 3 , 182.Xr prop_object 3 , 183.Xr proplib 3 184.Sh HISTORY 185The 186.Nm proplib 187property container object library first appeared in 188.Nx 4.0 . 189