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