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 November 16, 2010 32.Dt UDEV_MONITOR 3 33.Os 34.Sh NAME 35.Nm udev_monitor_new , 36.Nm udev_monitor_ref , 37.Nm udev_monitor_unref , 38.Nm udev_monitor_get_udev , 39.Nm udev_monitor_get_fd , 40.Nm udev_monitor_receive_device , 41.Nm udev_monitor_enable_receiving , 42.Nm udev_monitor_filter_add_match_subsystem_devtype , 43.Nm udev_monitor_filter_add_match_expr , 44.Nm udev_monitor_filter_add_match_property , 45.Nm udev_monitor_filter_add_nomatch_expr , 46.Nm udev_monitor_filter_add_nomatch_property , 47.Nm udev_monitor_filter_add_match_regex , 48.Nm udev_monitor_filter_add_nomatch_regex 49.Nd device event monitor functions 50.Sh LIBRARY 51.Lb libdevattr 52.Sh SYNOPSIS 53.In devattr.h 54.Ft struct udev_monitor * 55.Fn udev_monitor_new "struct udev *udev_ctx" 56.Ft struct udev_monitor * 57.Fn udev_monitor_ref "struct udev_monitor *udev_monitor" 58.Ft void 59.Fn udev_monitor_unref "struct udev_monitor *udev_monitor" 60.Ft struct udev * 61.Fn udev_monitor_get_udev "struct udev_monitor *udev_monitor" 62.Ft int 63.Fn udev_monitor_get_fd "struct udev_monitor *udev_monitor" 64.Ft struct udev_device * 65.Fn udev_monitor_receive_device "struct udev_monitor *udev_monitor" 66.Ft int 67.Fn udev_monitor_enable_receiving "struct udev_monitor *udev_monitor" 68.Ft int 69.Fn udev_monitor_filter_add_match_subsystem_devtype "struct udev_monitor *udev_monitor" "const char *subsystem" "const char *devtype" 70.Ft int 71.Fn udev_monitor_filter_add_match_expr "struct udev_monitor *udev_monitor" "const char *key" "char *expr" 72.Ft int 73.Fn udev_monitor_filter_add_match_property "struct udev_monitor *udev_monitor" "const char *key" "const char *expr" 74.Ft int 75.Fn udev_monitor_filter_add_nomatch_expr "struct udev_monitor *udev_monitor" "const char *key" "char *expr" 76.Ft int 77.Fn udev_monitor_filter_add_nomatch_property "struct udev_monitor *udev_monitor" "const char *key" "const char *expr" 78.Ft int 79.Fn udev_monitor_filter_add_match_regex "struct udev_monitor *udev_monitor" "const char *key" "char *expr" 80.Ft int 81.Fn udev_monitor_filter_add_nomatch_regex "struct udev_monitor *udev_monitor" "const char *key" "char *expr" 82.Sh DESCRIPTION 83The 84.Fn udev_monitor_new 85function creates a new udev_monitor object in the specified udev context 86.Fa udev_ctx . 87It returns 88.Dv NULL 89if no such object could be created. 90.Pp 91The 92.Fn udev_monitor_ref 93and 94.Fn udev_monitor_unref 95functions increase or decrease the reference count on a 96.Fa udev_monitor 97object respectively. 98When the reference count drops to 0, the object is automatically destroyed and 99any remaining event socket closed. 100The 101.Fn udev_monitor_ref 102function returns the same object that was passed in. 103.Pp 104The 105.Fn udev_monitor_get_udev 106function returns the udev context in which the 107.Fa udev_monitor 108object was created. 109.Pp 110The 111.Fn udev_monitor_enable_receiving 112function enables receiving event notifications matching the filters added by 113previous calls to 114.Fn udev_monitor_filter_* . 115The function returns -1 if an error occurs. 116.Pp 117The 118.Fn udev_monitor_receive_device 119function reads a udev_device, once the monitor has been enabled for receiving. 120This call will block until a device is available. 121It returns 122.Dv NULL 123if a read error occurs. 124.Pp 125The 126.Fn udev_monitor_get_fd 127returns the raw file descriptor on which events are notified after a call to 128.Fn udev_monitor_enable_receiving . 129This file descriptor can then be used in conjunction with 130.Xr poll 2 131or 132.Xr kqueue 2 . 133The 134.Fn udev_monitor_receive_device 135call must be used to read from the descriptor. 136The function returns -1 if the socket is not connected. 137.Pp 138The 139.Fn udev_monitor_filter_add_match_subsystem_devtype 140function adds a filter that matches the given 141.Fa subsystem 142and/or 143.Fa devtype . 144If 145.Fa subsystem 146or 147.Fa devtype 148is 149.Dv NULL , 150that argument is ignored. 151The function returns 0 in case of success and a negative value if an error 152occurred. 153NOTE: Currently devtype matching is not implemented. 154.Pp 155The 156.Fn udev_monitor_filter_add_match_expr , 157.Fn udev_monitor_filter_add_match_property , 158.Fn udev_monitor_filter_add_nomatch_expr 159and 160.Fn udev_monitor_filter_add_nomatch_property 161functions add a filter to match or not to match, respectively, devices with the 162specified 163.Fa key 164and value 165.Fa expr . 166The 167.Fa expr 168can contain wildcards. 169On error, these functions return a negative value and 0 if no error occurred. 170.Pp 171The 172.Fn udev_monitor_filter_add_match_regex , 173and 174.Fn udev_monitor_filter_add_nomatch_regex 175functions add a filter to match or not to match, respectively, devices with the 176specified 177.Fa key 178and value 179.Fa expr . 180The 181.Fa expr 182can contain regular expressions according to 183.Xr regex 3 . 184On error, these functions return a negative value and 0 if no error occurred. 185.Sh SEE ALSO 186.Xr devattr 3 , 187.Xr udev 3 , 188.Xr udev_device 3 , 189.Xr udev_enumerate 3 , 190.Xr udevd 8 191