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 .Fn udev_list_entry_foreach "struct udev_list_entry *list_entry" "struct udev_list_entry *first_entry"
  76 .Ft prop_dictionary_t
  77 .Fn udev_list_entry_get_dictionary "struct udev_list_entry *list_entry"
  78 .Ft struct udev_device *
  79 .Fn udev_list_entry_get_device "struct udev_list_entry *list_entry"
  80 .Ft int
  81 .Fn udev_enumerate_add_match_subsystem "struct udev_enumerate *udev_enum" "const char *subsystem"
  82 .Ft int
  83 .Fn udev_enumerate_add_nomatch_subsystem "struct udev_enumerate *udev_enum" "const char *subsystem"
  84 .Ft int
  85 .Fn udev_enumerate_add_match_expr "struct udev_enumerate *udev_enum" "const char *key" "char *expr"
  86 .Ft int
  87 .Fn udev_enumerate_add_match_property "struct udev_enumerate *udev_enum" "const char *key" "const char *property"
  88 .Ft int
  89 .Fn udev_enumerate_add_nomatch_expr "struct udev_enumerate *udev_enum" "const char *key" "char *expr"
  90 .Ft int
  91 .Fn udev_enumerate_add_nomatch_property "struct udev_enumerate *udev_enum" "const char *key" "const char *property"
  92 .Ft int
  93 .Fn udev_enumerate_add_match_regex "struct udev_enumerate *udev_enum" "const char *key" "char *expr"
  94 .Ft int
  95 .Fn udev_enumerate_add_nomatch_regex "struct udev_enumerate *udev_enum" "const char *key" "char *expr"
  96 .Sh DESCRIPTION
  97 The
  98 .Fn udev_enumerate_new
  99 function creates a new udev_enumerate object in the specified udev context
 100 .Fa udev_ctx .
 101 It returns
 102 .Dv NULL
 103 if no such object could be created.
 104 .Pp
 105 The
 106 .Fn udev_enumerate_ref
 107 and
 108 .Fn udev_enumerate_unref
 109 functions increase or decrease the reference count on a
 110 .Fa udev_enumerate
 111 object respectively.
 112 When the reference count drops to 0, the object is automatically destroyed.
 113 The
 114 .Fn udev_enumerate_ref
 115 function returns the same object that was passed in.
 116 .Pp
 117 The
 118 .Fn udev_enumerate_get_udev
 119 function returns the udev context in which the
 120 .Fa udev_enumerate
 121 object was created.
 122 .Pp
 123 The
 124 .Fn udev_enumerate_scan_devices
 125 function retrieves the set of devices matching the set of expressions and
 126 properties specified with previous calls to
 127 .Fn udev_enumerate_add_match_*
 128 and
 129 .Fn udev_enumerate_add_nomatch_* .
 130 This function returns -1 in case of failure.
 131 .Pp
 132 The
 133 .Fn udev_enumerate_get_array
 134 function returns the raw
 135 .Xr prop_array 3
 136 array containing the whole set of devices retrieved by
 137 .Fn udev_enumerate_scan_devices .
 138 .Pp
 139 The
 140 .Fn udev_enumerate_get_list_entry
 141 function returns the first list entry of the specified
 142 .Fa udev_enumerate
 143 context or
 144 .Dv NULL
 145 if the set is empty.
 146 The
 147 .Fn udev_list_entry_get_next
 148 returns the next list element after
 149 .Fa list_entry
 150 or
 151 .Dv NULL
 152 if the current element was the last.
 153 The
 154 .Fn udev_list_entry_foreach
 155 is a convenient macro behaving as a for loop that will iterate the whole set
 156 starting at the list element specified by
 157 .Fa first_entry
 158 and setting
 159 .Fa list_entry
 160 to the current element.
 161 .Pp
 162 The
 163 .Fn udev_list_entry_get_device
 164 function returns the
 165 .Fa udev_device
 166 associated to the current list entry or
 167 .Dv NULL
 168 if no device is associated.
 169 .Pp
 170 The
 171 .Fn udev_list_entry_get_dictionary
 172 function returns the raw
 173 .Xr prop_dictionary 3
 174 dictionary associated to the list entry or
 175 .Dv NULL
 176 if no dictionary is associated.
 177 .Pp
 178 The
 179 .Fn udev_enumerate_add_match_subsystem
 180 and
 181 .Fn udev_enumerate_add_nomatch_subsystem
 182 functions add a filter to match or not to match, respectively, devices with the
 183 specified
 184 .Fa subsystem .
 185 These functions return a negative value if an error occured and 0 if no error
 186 occured.
 187 .Pp
 188 The
 189 .Fn udev_enumerate_add_match_expr ,
 190 .Fn udev_enumerate_add_match_property ,
 191 .Fn udev_enumerate_add_nomatch_expr
 192 and
 193 .Fn udev_enumerate_add_nomatch_property
 194 functions add a filter to match or not to match, respectively, devices with the
 195 specified
 196 .Fa key
 197 and value
 198 .Fa expr .
 199 The
 200 .Fa expr
 201 can contain wildcards.
 202 On error, these functions return a negative value and 0 if no error occured.
 203 .Pp
 204 The
 205 .Fn udev_enumerate_add_match_regex ,
 206 and
 207 .Fn udev_enumerate_add_nomatch_regex
 208 functions add a filter to match or not to match, respectively, devices with the
 209 specified
 210 .Fa key
 211 and value
 212 .Fa expr .
 213 The
 214 .Fa expr
 215 can contain regular expressions according to
 216 .Xr regex 3 .
 217 On error, these functions return a negative value and 0 if no error occured.
 218 .Sh SEE ALSO
 219 .Xr devattr 3 ,
 220 .Xr udev 3 ,
 221 .Xr udev_device 3 ,
 222 .Xr udev_monitor 3 ,
 223 .Xr udevd 8