src/prop_string.3

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