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