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