common/lib/libprop/prop_string.3

   1 .\"     $NetBSD: prop_string.3,v 1.8 2011/02/26 12:56:36 wiz 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 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
  86 The
  87 .Nm prop_string
  88 family of functions operate on a string value property object type.
  89 .Bl -tag -width "xxxxx"
  90 .It Fn prop_string_create "void"
  91 Create an empty mutable string.
  92 Returns
  93 .Dv NULL
  94 on failure.
  95 .It Fn prop_string_create_cstring "const char *cstring"
  96 Create a mutable string that contains a copy of
  97 .Fa cstring .
  98 Returns
  99 .Dv NULL
 100 on failure.
 101 .It Fn prop_string_create_cstring_nocopy "const char *cstring"
 102 Create an immutable string that contains a reference to
 103 .Fa cstring .
 104 Returns
 105 .Dv NULL
 106 on failure.
 107 .It Fn prop_string_copy "prop_string_t string"
 108 Copy a string.
 109 If the string being copied is an immutable external C string reference,
 110 then the copy is also immutable and references the same external C string.
 111 Returns
 112 .Dv NULL
 113 on failure.
 114 .It Fn prop_string_copy_mutable "prop_string_t string"
 115 Copy a string, always creating a mutable copy.
 116 Returns
 117 .Dv NULL
 118 on failure.
 119 .It Fn prop_string_size "prop_string_t string"
 120 Returns the size of the string, not including the terminating NUL.
 121 If the supplied object isn't a string, zero is returned.
 122 .It Fn prop_string_mutable "prop_string_t string"
 123 Returns
 124 .Dv true
 125 if the string is mutable.
 126 If the supplied object isn't a string,
 127 .Dv false
 128 is returned.
 129 .It Fn prop_string_cstring "prop_string_t string"
 130 Returns a copy of the string's contents as a C string.
 131 The caller is responsible for freeing the returned buffer.
 132 .Pp
 133 In user space, the buffer is allocated using
 134 .Xr malloc 3 .
 135 In the kernel, the buffer is allocated using
 136 .Xr malloc 9
 137 using the malloc type
 138 .Dv M_TEMP .
 139 .Pp
 140 Returns
 141 .Dv NULL
 142 on failure.
 143 .It Fn prop_string_cstring_nocopy "prop_string_t string"
 144 Returns an immutable reference to the contents of the string as a
 145 C string.
 146 If the supplied object isn't a string,
 147 .Dv NULL
 148 is returned.
 149 .It Fn prop_string_append "prop_string_t str1" "prop_string_t str2"
 150 Append the contents of
 151 .Fa str2
 152 to
 153 .Fa str1 ,
 154 which must be mutable.
 155 Returns
 156 .Dv true
 157 upon success and
 158 .Dv false
 159 otherwise.
 160 .It Fn prop_string_append_cstring "prop_string_t string" "const char *cstring"
 161 Append the C string
 162 .Fa cstring
 163 to
 164 .Fa string ,
 165 which must be mutable.
 166 Returns
 167 .Dv true
 168 upon success and
 169 .Dv false
 170 otherwise.
 171 .It Fn prop_string_equals "prop_string_t str1" "prop_string_t str2"
 172 Returns
 173 .Dv true
 174 if the two string objects are equivalent.
 175 .It Fn prop_string_equals_cstring "prop_string_t string" "const char *cstring"
 176 Returns
 177 .Dv true
 178 if 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
 190 The
 191 .Nm proplib
 192 property container object library first appeared in
 193 .Nx 4.0 .