5.1 commit.
[dragonfly.git] / lib / libdevattr / udev_device.3
blobde8be3d891a5275c96bc728b603811d2106287fd
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.
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.
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
123 .Fn udev_device_get_minor
124 function return some information of the device corresponding to the
125 .Fa udev_device .
127 .Fn udev_device_get_devnum ,
128 function returns the device number.
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.
136 .Fn udev_device_get_driver
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 .
143 .Fn udev_device_get_kptr ,
144 .Fn udev_device_get_major
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.
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