lib/libdevattr/udev_enumerate.3

   1 .\"
   2 .\" Copyright (c) 2010 The DragonFly Project.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\"
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in
  12 .\"    the documentation and/or other materials provided with the
  13 .\"    distribution.
  14 .\" 3. Neither the name of The DragonFly Project nor the names of its
  15 .\"    contributors may be used to endorse or promote products derived
  16 .\"    from this software without specific, prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
  21 .\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
  22 .\" COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
  23 .\" INCIDENTAL, SPECIAL, EXEMPLARY OR CONSEQUENTIAL DAMAGES (INCLUDING,
  24 .\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  25 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
  26 .\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
  27 .\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
  28 .\" OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  29 .\" SUCH DAMAGE.
  30 .\"
  31 .Dd July 11, 2010
  32 .Dt UDEV_ENUMERATE 3
  33 .Os
  34 .Sh NAME
  35 .Nm udev_enumerate_new ,
  36 .Nm udev_enumerate_ref ,
  37 .Nm udev_enumerate_unref ,
  38 .Nm udev_enumerate_get_udev ,
  39 .Nm udev_enumerate_scan_devices ,
  40 .Nm udev_enumerate_get_array ,
  41 .Nm udev_enumerate_get_list_entry ,
  42 .Nm udev_list_entry_get_next ,
  43 .Nm udev_list_entry_foreach ,
  44 .Nm udev_list_entry_get_dictionary ,
  45 .Nm udev_list_entry_get_device ,
  46 .Nm udev_enumerate_add_match_subsystem ,
  47 .Nm udev_enumerate_add_nomatch_subsystem ,
  48 .Nm udev_enumerate_add_match_expr ,
  49 .Nm udev_enumerate_add_match_property ,
  50 .Nm udev_enumerate_add_nomatch_expr ,
  51 .Nm udev_enumerate_add_nomatch_property ,
  52 .Nm udev_enumerate_add_match_regex ,
  53 .Nm udev_enumerate_add_nomatch_regex
  54 .Nd device listing functions
  55 .Sh LIBRARY
  56 .Lb libdevattr
  57 .Sh SYNOPSIS
  58 .In devattr.h
  59 .Ft struct udev_enumerate *
  60 .Fn udev_enumerate_new "struct udev *udev_ctx"
  61 .Ft struct udev_enumerate *
  62 .Fn udev_enumerate_ref "struct udev *udev_ctx"
  63 .Ft void
  64 .Fn udev_enumerate_unref "struct udev *udev_ctx"
  65 .Ft struct udev *
  66 .Fn udev_enumerate_get_udev "struct udev *udev_ctx"
  67 .Ft int
  68 .Fn udev_enumerate_scan_devices "struct udev *udev_ctx"
  69 .Ft prop_array_t
  70 .Fn udev_enumerate_get_array "struct udev_enumerate *udev_enum"
  71 .Ft struct udev_list_entry *
  72 .Fn udev_enumerate_get_list_entry "struct udev_enumerate *udev_enum"
  73 .Ft struct udev_list_entry *
  74 .Fn udev_list_entry_get_next "struct udev_list_entry *list_entry"
  75 .Ft this is a macro....
  76 .Fn udev_list_entry_foreach
  77 .Ft prop_dictionary_t
  78 .Fn udev_list_entry_get_dictionary "struct udev_list_entry *list_entry"
  79 .Ft struct udev_device *
  80 .Fn udev_list_entry_get_device "struct udev_list_entry *list_entry"
  81 .Ft int
  82 .Fn udev_enumerate_add_match_subsystem "struct udev_enumerate *udev_enum" "const char *subsystem"
  83 .Ft int
  84 .Fn udev_enumerate_add_nomatch_subsystem "struct udev_enumerate *udev_enum" "const char *subsystem"
  85 .Ft int
  86 .Fn udev_enumerate_add_match_expr "struct udev_enumerate *udev_enum" "const char *key" "char *expr"
  87 .Ft int
  88 .Fn udev_enumerate_add_match_property "struct udev_enumerate *udev_enum" "const char *key" "const char *property"
  89 .Ft int
  90 .Fn udev_enumerate_add_nomatch_expr "struct udev_enumerate *udev_enum" "const char *key" "char *expr"
  91 .Ft int
  92 .Fn udev_enumerate_add_nomatch_property "struct udev_enumerate *udev_enum" "const char *key" "const char *property"
  93 .Ft int
  94 .Fn udev_enumerate_add_match_regex "struct udev_enumerate *udev_enum" "const char *key" "char *expr"
  95 .Ft int
  96 .Fn udev_enumerate_add_nomatch_regex "struct udev_enumerate *udev_enum" "const char *key" "char *expr"
  97 .Sh DESCRIPTION
  98 The
  99 .Fn udev_enumerate_new
 100 function creates a new udev_enumerate object in the specified udev context
 101 .Fa udev_ctx .
 102 It returns
 103 .Dv NULL
 104 if no such object could be created.
 105 .Pp
 106 The
 107 .Fn udev_enumerate_ref
 108 and
 109 .Fn udev_enumerate_unref
 110 functions increase or decrease the reference count on a
 111 .Fa udev_enumerate
 112 object respectively.
 113 When the reference count drops to 0, the object is automatically destroyed.
 114 The
 115 .Fn udev_enumerate_ref
 116 function returns the same object that was passed in.
 117 .Pp
 118 The
 119 .Fn udev_enumerate_get_udev
 120 function returns the udev context in which the
 121 .Fa udev_enumerate
 122 object was created.
 123 .Pp
 124 The
 125 .Fn udev_enumerate_scan_devices
 126 function retrieves the set of devices matching the set of expressions and
 127 properties specified with previous calls to
 128 .Fn udev_enumerate_add_match_*
 129 and
 130 .Fn udev_enumerate_add_nomatch_* .
 131 This function returns -1 in case of failure.
 132 .Pp
 133 The
 134 .Fn udev_enumerate_get_array
 135 function returns the raw
 136 .Xr prop_array 3
 137 array containing the whole set of devices retrieved by
 138 .Fn udev_enumerate_scan_devices .
 139 .Pp
 140 The
 141 .Fn udev_enumerate_get_list_entry
 142 function returns the first list entry of the specified
 143 .Fa udev_enumerate
 144 context or
 145 .Dv NULL
 146 if the set is empty.
 147 The
 148 .Fn udev_list_entry_get_next
 149 returns the next list element after
 150 .Fa list_entry
 151 or
 152 .Dv NULL
 153 if the current element was the last.
 154 The
 155 .Fn udev_list_entry_foreach
 156 is a convenient macro behaving as a for loop that will iterate the whole set
 157 starting at the list element specified by
 158 .Fa first_entry
 159 and setting
 160 .Fa list_entry
 161 to the current element.
 162 .Pp
 163 The
 164 .Fn udev_list_entry_get_device
 165 function returns the
 166 .Fa udev_device
 167 associated to the current list entry or
 168 .Dv NULL
 169 if no device is associated.
 170 .Pp
 171 The
 172 .Fn udev_list_entry_get_dictionary
 173 function returns the raw
 174 .Xr prop_dictionary 3
 175 dictionary associated to the list entry or
 176 .Dv NULL
 177 if no dictionary is associated.
 178 .Pp
 179 The
 180 .Fn udev_enumerate_add_match_subsystem
 181 and
 182 .Fn udev_enumerate_add_nomatch_subsystem
 183 functions add a filter to match or not to match, respectively, devices with the
 184 specified
 185 .Fa subsystem .
 186 These functions return a negative value if an error occured and 0 if no error
 187 occured.
 188 .Pp
 189 The
 190 .Fn udev_enumerate_add_match_expr ,
 191 .Fn udev_enumerate_add_match_property ,
 192 .Fn udev_enumerate_add_nomatch_expr
 193 and
 194 .Fn udev_enumerate_add_nomatch_property
 195 functions add a filter to match or not to match, respectively, devices with the
 196 specified
 197 .Fa key
 198 and value
 199 .Fa expr .
 200 The
 201 .Fa expr
 202 can contain wildcards.
 203 On error, these functions return a negative value and 0 if no error occured.
 204 .Pp
 205 The
 206 .Fn udev_enumerate_add_match_regex ,
 207 and
 208 .Fn udev_enumerate_add_nomatch_regex
 209 functions add a filter to match or not to match, respectively, devices with the
 210 specified
 211 .Fa key
 212 and value
 213 .Fa expr .
 214 The
 215 .Fa expr
 216 can contain regular expressions according to
 217 .Xr regex 3 .
 218 On error, these functions return a negative value and 0 if no error occured.
 219 .Sh SEE ALSO
 220 .Xr devattr 3 ,
 221 .Xr udev 3 ,
 222 .Xr udev_device 3 ,
 223 .Xr udev_monitor 3 ,
 224 .Xr udevd 8