common/lib/libprop/prop_data.3

   1 .\"     $NetBSD: prop_data.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 April 22, 2006
  31 .Dt PROP_DATA 3
  32 .Os
  33 .Sh NAME
  34 .Nm prop_data ,
  35 .Nm prop_data_create_data ,
  36 .Nm prop_data_create_data_nocopy ,
  37 .Nm prop_data_copy ,
  38 .Nm prop_data_size ,
  39 .Nm prop_data_data ,
  40 .Nm prop_data_data_nocopy ,
  41 .Nm prop_data_equals ,
  42 .Nm prop_data_equals_data
  43 .Nd opaque data value property object
  44 .Sh LIBRARY
  45 .Lb libprop
  46 .Sh SYNOPSIS
  47 .In prop/proplib.h
  48 .\"
  49 .Ft prop_data_t
  50 .Fn prop_data_create_data "const void *blob" "size_t len"
  51 .Ft prop_data_t
  52 .Fn prop_data_create_data_nocopy "const void *blob" "size_t len"
  53 .\"
  54 .Ft prop_data_t
  55 .Fn prop_data_copy "prop_data_t data"
  56 .\"
  57 .Ft size_t
  58 .Fn prop_data_size "prop_data_t data"
  59 .Ft void *
  60 .Fn prop_data_data "prop_data_t data"
  61 .Ft const void *
  62 .Fn prop_data_data_nocopy "prop_data_t data"
  63 .\"
  64 .Ft bool
  65 .Fn prop_data_equals "prop_data_t dat1" "prop_data_t dat2"
  66 .Ft bool
  67 .Fn prop_data_equals_data "prop_data_t data" "const void *blob" "size_t len"
  68 .Sh DESCRIPTION
  69 The
  70 .Nm prop_data
  71 family of functions operate on an opaque data value property object type.
  72 .Bl -tag -width "xxxxx"
  73 .It Fn prop_data_create_data "const void *blob" "size_t len"
  74 Create a data object that contains a copy of
  75 .Fa blob
  76 with size
  77 .Fa len .
  78 Returns
  79 .Dv NULL
  80 on failure.
  81 .It Fn prop_data_create_data_nocopy "const void *blob" "size_t len"
  82 Create a data object that contains a reference to
  83 .Fa blob
  84 with size
  85 .Fa len .
  86 Returns
  87 .Dv NULL
  88 on failure.
  89 .It Fn prop_data_copy "prop_data_t data"
  90 Copy a data object.
  91 If the data object being copied is an external data reference,
  92 then the copy also references the same external data.
  93 Returns
  94 .Dv NULL
  95 on failure.
  96 .It Fn prop_data_size "prop_data_t data"
  97 Returns the size of the data object.
  98 If the supplied object isn't a data object, zero is returned.
  99 .It Fn prop_data_data "prop_data_t data"
 100 Returns a copy of the data object's contents.
 101 The caller is responsible for freeing the returned buffer.
 102 If the supplied object isn't a data object or
 103 if the data container is empty,
 104 .Dv NULL
 105 is returned.
 106 .Pp
 107 In user space, the buffer is allocated using
 108 .Xr malloc 3 .
 109 In the kernel, the buffer is allocated using
 110 .Xr malloc 9
 111 using the malloc type
 112 .Dv M_TEMP .
 113 .It Fn prop_data_data_nocopy "prop_data_t data"
 114 Returns an immutable reference to the contents of the data object.
 115 If the supplied object isn't a data object,
 116 .Dv NULL
 117 is returned.
 118 .It Fn prop_data_equals "prop_data_t dat1" "prop_data_t dat2"
 119 Returns
 120 .Dv true
 121 if the two data objects are equivalent.
 122 If at least one of the supplied objects isn't a data object,
 123 .Dv false
 124 is returned.
 125 .It Fn prop_data_equals_data "prop_data_t data" "const void *blob" "size_t len"
 126 Returns
 127 .Dv true
 128 if the data object's value is equivalent to
 129 .Fa blob
 130 with size
 131 .Fa len .
 132 If the supplied object isn't a data object,
 133 .Dv false
 134 is returned.
 135 .El
 136 .Sh SEE ALSO
 137 .Xr prop_array 3 ,
 138 .Xr prop_bool 3 ,
 139 .Xr prop_dictionary 3 ,
 140 .Xr prop_number 3 ,
 141 .Xr prop_object 3 ,
 142 .Xr prop_string 3 ,
 143 .Xr proplib 3
 144 .Sh HISTORY
 145 The
 146 .Nm proplib
 147 property container object library first appeared in
 148 .Nx 4.0 .