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