1.\" $NetBSD: prop_string.3,v 1.10 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_STRING 3 32.Os 33.Sh NAME 34.Nm prop_string , 35.Nm prop_string_create_copy , 36.Nm prop_string_create_format , 37.Nm prop_string_create_nocopy , 38.Nm prop_string_value , 39.Nm prop_string_copy_value , 40.Nm prop_string_copy , 41.Nm prop_string_size , 42.Nm prop_string_equals , 43.Nm prop_string_equals_string , 44.Nm prop_string_compare , 45.Nm prop_string_compare_string 46.Nd string value property object 47.Sh LIBRARY 48.Lb libprop 49.Sh SYNOPSIS 50.In prop/proplib.h 51.\" 52.Ft prop_string_t 53.Fn prop_string_create_copy "const char *cstring" 54.Ft prop_string_t 55.Fn prop_string_create_format "const char *fmt" "..." 56.Ft prop_string_t 57.Fn prop_string_create_nocopy "const char *cstring" 58.\" 59.Ft prop_string_t 60.Fn prop_string_copy "prop_string_t string" 61.Ft bool 62.Fn prop_string_copy_value "prop_string_t string" "char *buf" "size_t buflen" 63.\" 64.Ft size_t 65.Fn prop_string_size "prop_string_t string" 66.\" 67.Ft const char * 68.Fn prop_string_value "prop_string_t string" 69.\" 70.Ft bool 71.Fn prop_string_equals "prop_string_t str1" "prop_string_t str2" 72.Ft bool 73.Fn prop_string_equals_string "prop_string_t string" "const char *cstring" 74.\" 75.Ft int 76.Fn prop_string_compare "prop_string_t str1" "prop_string_t str2" 77.Ft int 78.Fn prop_string_compare_string "prop_string_t string" "const char *cstring" 79.Sh DESCRIPTION 80The 81.Nm 82family of functions operate on a string value property object type. 83.Bl -tag -width "xxxxx" 84.It Fn prop_string_create_copy "const char *cstring" 85Create a string object that contains a copy of 86.Fa cstring . 87Returns 88.Dv NULL 89on failure. 90.It Fn prop_string_create_format "const char *fmt" "..." 91Similar to 92.Fn prop_string_create_copy , 93but creates the string using the specified 94.Xr printf 3 95format. 96.It Fn prop_string_create_nocopy "const char *cstring" 97Similar to 98.Fn prop_string_create_copy , 99but is allowed to not create an internal copy of the string data, instead 100referencing the string data passed by the caller. 101Caution must be exercised because string objects can have an indefinite 102lifespan. 103The caller must therefore ensure that the provided string data 104reference will also be valid indefinitely. 105This is provided only as a memory optimization; it is not guaranteed that 106the returned string object will reference the provided string data, and 107thus callers should not rely on this behavior. 108Returns 109.Dv NULL 110on failure. 111.It Fn prop_string_copy "prop_string_t string" 112Copy a string object. 113If the string object being copied has an external string buffer reference, 114then the copy also references the same external string buffer. 115Returns 116.Dv NULL 117on failure. 118.It Fn prop_string_size "prop_string_t string" 119Returns the size of the string, not including the terminating NUL; 120equivalent semantics to 121.Xr strlen 3 . 122If the supplied object isn't a string, zero is returned. 123.It Fn prop_string_value "prop_string_t string" 124Returns an reference to the contents of the string as a C string. 125If the supplied object isn't a string, 126.Dv NULL 127is returned. 128.It Fn prop_string_copy_value "prop_string_t string" "void *buf" "size_t buflen" 129Copies the contents of the string object including the terminating NUL 130into the supplied buffer of the specified size. 131Returns 132.Dv true 133if the copy succeeds 134and 135.Dv false 136if the supplied buffer is not large enough or if the object is not a 137string object. 138.It Fn prop_string_equals "prop_string_t str1" "prop_string_t str2" 139Returns 140.Dv true 141if the two string objects are equivalent. 142.It Fn prop_string_equals_string "prop_string_t string" "const char *cstring" 143Returns 144.Dv true 145if the string's value is equivalent to 146.Fa cstring . 147.It Fn prop_string_compare "prop_string_t str1" "prop_string_t str2" 148Compares two strings using 149.Xr strcmp 3 150semantics. 151If either of the two objects are not string objects, an arbitrary 152non-matching value will be returned. 153.It Fn prop_string_compare_string "prop_string_t string" "const char *cstring" 154Compares the a string object to the specified C string using 155.Xr strcmp 3 156semantics. 157If either the object is not a string object, an arbitrary 158non-matching value will be returned. 159.El 160.Sh SEE ALSO 161.Xr prop_array 3 , 162.Xr prop_bool 3 , 163.Xr prop_data 3 , 164.Xr prop_dictionary 3 , 165.Xr prop_number 3 , 166.Xr prop_object 3 , 167.Xr proplib 3 168.Sh HISTORY 169The 170.Xr proplib 3 171property container object library first appeared in 172.Nx 4.0 . 173Support for mutable string objects was deprecated in 174.Nx 10.0 . 175