lib/libdevattr/udev_monitor.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 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
  83 The
  84 .Fn udev_monitor_new
  85 function creates a new udev_monitor object in the specified udev context
  86 .Fa udev_ctx .
  87 It returns
  88 .Dv NULL
  89 if no such object could be created.
  90 .Pp
  91 The
  92 .Fn udev_monitor_ref
  93 and
  94 .Fn udev_monitor_unref
  95 functions increase or decrease the reference count on a
  96 .Fa udev_monitor
  97 object respectively.
  98 When the reference count drops to 0, the object is automatically destroyed and
  99 any remaining event socket closed.
 100 The
 101 .Fn udev_monitor_ref
 102 function returns the same object that was passed in.
 103 .Pp
 104 The
 105 .Fn udev_monitor_get_udev
 106 function returns the udev context in which the
 107 .Fa udev_monitor
 108 object was created.
 109 .Pp
 110 The
 111 .Fn udev_monitor_enable_receiving
 112 function enables receiving event notifications matching the filters added by
 113 previous calls to
 114 .Fn udev_monitor_filter_* .
 115 The function returns -1 if an error occurs.
 116 .Pp
 117 The
 118 .Fn udev_monitor_receive_device
 119 function reads a udev_device, once the monitor has been enabled for receiving.
 120 This call will block until a device is available.
 121 It returns
 122 .Dv NULL
 123 if a read error occurs.
 124 .Pp
 125 The
 126 .Fn udev_monitor_get_fd
 127 returns the raw file descriptor on which events are notified after a call to
 128 .Fn udev_monitor_enable_receiving .
 129 This file descriptor can then be used in conjunction with
 130 .Xr poll 2
 131 or
 132 .Xr kqueue 2 .
 133 The
 134 .Fn udev_monitor_receive_device
 135 call must be used to read from the descriptor.
 136 The function returns -1 if the socket is not connected.
 137 .Pp
 138 The
 139 .Fn udev_monitor_filter_add_match_subsystem_devtype
 140 function adds a filter that matches the given
 141 .Fa subsystem
 142 and/or
 143 .Fa devtype .
 144 If
 145 .Fa subsystem
 146 or
 147 .Fa devtype
 148 is
 149 .Dv NULL ,
 150 that argument is ignored.
 151 The function returns 0 in case of success and a negative value if an error
 152 occurred.
 153 NOTE: Currently devtype matching is not implemented.
 154 .Pp
 155 The
 156 .Fn udev_monitor_filter_add_match_expr ,
 157 .Fn udev_monitor_filter_add_match_property ,
 158 .Fn udev_monitor_filter_add_nomatch_expr
 159 and
 160 .Fn udev_monitor_filter_add_nomatch_property
 161 functions add a filter to match or not to match, respectively, devices with the
 162 specified
 163 .Fa key
 164 and value
 165 .Fa expr .
 166 The
 167 .Fa expr
 168 can contain wildcards.
 169 On error, these functions return a negative value and 0 if no error occurred.
 170 .Pp
 171 The
 172 .Fn udev_monitor_filter_add_match_regex ,
 173 and
 174 .Fn udev_monitor_filter_add_nomatch_regex
 175 functions add a filter to match or not to match, respectively, devices with the
 176 specified
 177 .Fa key
 178 and value
 179 .Fa expr .
 180 The
 181 .Fa expr
 182 can contain regular expressions according to
 183 .Xr regex 3 .
 184 On 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