lib/libdevattr/udev_device.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_DEVICE 3
  33 .Os
  34 .Sh NAME
  35 .Nm udev_device_ref ,
  36 .Nm udev_device_unref ,
  37 .Nm udev_device_get_dictionary ,
  38 .Nm udev_device_get_udev ,
  39 .Nm udev_device_get_action ,
  40 .Nm udev_device_get_devnum ,
  41 .Nm udev_device_get_devnode ,
  42 .Nm udev_device_get_driver ,
  43 .Nm udev_device_get_subsystem ,
  44 .Nm udev_device_get_kptr ,
  45 .Nm udev_device_get_major ,
  46 .Nm udev_device_get_minor ,
  47 .Nm udev_device_get_property_value
  48 .Nd udev device functions
  49 .Sh LIBRARY
  50 .Lb libdevattr
  51 .Sh SYNOPSIS
  52 .In devattr.h
  53 .Ft struct udev_device *
  54 .Fn udev_device_ref "struct udev_device *udev_device"
  55 .Ft void
  56 .Fn udev_device_unref "struct udev_device *udev_device"
  57 .Ft struct udev *
  58 .Fn udev_device_get_udev "struct udev_device *udev_device"
  59 .Ft prop_dictionary_t
  60 .Fn udev_device_get_dictionary "struct udev_device *udev_device"
  61 .Ft const char *
  62 .Fn udev_device_get_action "struct udev_device *udev_device"
  63 .Ft dev_t
  64 .Fn udev_device_get_devnum "struct udev_device *udev_device"
  65 .Ft const char *
  66 .Fn udev_device_get_devnode "struct udev_device *udev_device"
  67 .Ft const char *
  68 .Fn udev_device_get_driver "struct udev_device *udev_device"
  69 .Ft const char *
  70 .Fn udev_device_get_subsystem "struct udev_device *udev_device"
  71 .Ft uint64_t
  72 .Fn udev_device_get_kptr "struct udev_device *udev_device"
  73 .Ft int32_t
  74 .Fn udev_device_get_major "struct udev_device *udev_device"
  75 .Ft int32_t
  76 .Fn udev_device_get_minor "struct udev_device *udev_device"
  77 .Ft const char *
  78 .Fn udev_device_get_property_value "struct udev_device *udev_device" "const char *key"
  79 .Sh DESCRIPTION
  80 The
  81 .Fn udev_device_ref
  82 and
  83 .Fn udev_device_unref
  84 functions increase or decrease the reference count on a
  85 .Fa udev_device
  86 object respectively.
  87 When the reference count drops to 0, the object is automatically destroyed.
  88 The
  89 .Fn udev_device_ref
  90 function returns the same object that was passed in.
  91 .Pp
  92 The
  93 .Fn udev_device_get_udev
  94 function returns the udev context in which the
  95 .Fa udev_device
  96 was created.
  97 .Pp
  98 The
  99 .Fn udev_device_get_dictionary
 100 function returns the raw
 101 .Xr prop_dictionary 3
 102 dictionary associated to the given
 103 .Fa udev_device .
 104 It returns
 105 .Dv NULL
 106 when no dictionary is associated to the device.
 107 .Pp
 108 The
 109 .Fn udev_device_get_action
 110 function returns the action, as a string, related to the
 111 .Fa udev_device .
 112 Possible actions are "add" for attach events, "remove" for detach events and
 113 "none" if the udev_device is not associated with a particular event.
 114 .Pp
 115 The
 116 .Fn udev_device_get_devnum ,
 117 .Fn udev_device_get_devnode ,
 118 .Fn udev_device_get_driver ,
 119 .Fn udev_device_get_subsystem ,
 120 .Fn udev_device_get_kptr ,
 121 .Fn udev_device_get_major
 122 and
 123 .Fn udev_device_get_minor
 124 function return some information of the device corresponding to the
 125 .Fa udev_device .
 126 The
 127 .Fn udev_device_get_devnum ,
 128 function returns the device number.
 129 The
 130 .Fn udev_device_get_devnode
 131 function returns the full path in the system to the given device.
 132 The returned string and errno are the same as for the
 133 .Xr devname 3
 134 function.
 135 The
 136 .Fn udev_device_get_driver
 137 and
 138 .Fn udev_device_get_subsystem
 139 functions return the driver name and subsystem of the device if available.
 140 Otherwise they return
 141 .Dv NULL .
 142 The
 143 .Fn udev_device_get_kptr ,
 144 .Fn udev_device_get_major
 145 and
 146 .Fn udev_device_get_minor
 147 functions return the kernel pointer to the associated cdev_t, the major and the
 148 minor number, respectively.
 149 .Pp
 150 The
 151 .Fn udev_device_get_property_value
 152 function returns the value for the
 153 .Fa udev_device
 154 for the specified property
 155 .Fa key .
 156 It returns
 157 .Dv NULL
 158 if the specified
 159 .Fa udev_device
 160 has no property for
 161 .Fa key .
 162 .Sh SEE ALSO
 163 .Xr devattr 3 ,
 164 .Xr udev 3 ,
 165 .Xr udev_enumerate 3 ,
 166 .Xr udev_monitor 3 ,
 167 .Xr udevd 8