| 1 |
'\" t |
| 2 |
.TH "UDEV_DEVICE_NEW_FROM_SYSPATH" "3" "" "systemd 259.5" "udev_device_new_from_syspath" |
| 3 |
.\" ----------------------------------------------------------------- |
| 4 |
.\" * Define some portability stuff |
| 5 |
.\" ----------------------------------------------------------------- |
| 6 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 7 |
.\" http://bugs.debian.org/507673 |
| 8 |
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html |
| 9 |
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| 10 |
.ie \n(.g .ds Aq \(aq |
| 11 |
.el .ds Aq ' |
| 12 |
.\" ----------------------------------------------------------------- |
| 13 |
.\" * set default formatting |
| 14 |
.\" ----------------------------------------------------------------- |
| 15 |
.\" disable hyphenation |
| 16 |
.nh |
| 17 |
.\" disable justification (adjust text to left margin only) |
| 18 |
.ad l |
| 19 |
.\" ----------------------------------------------------------------- |
| 20 |
.\" * MAIN CONTENT STARTS HERE * |
| 21 |
.\" ----------------------------------------------------------------- |
| 22 |
.SH "NAME" |
| 23 |
udev_device_new_from_syspath, udev_device_new_from_devnum, udev_device_new_from_subsystem_sysname, udev_device_new_from_device_id, udev_device_new_from_environment, udev_device_ref, udev_device_unref \- Create, acquire and release a udev device object |
| 24 |
.SH "SYNOPSIS" |
| 25 |
.sp |
| 26 |
.ft B |
| 27 |
.nf |
| 28 |
#include <libudev\&.h> |
| 29 |
.fi |
| 30 |
.ft |
| 31 |
.HP \w'struct\ udev_device\ *udev_device_new_from_syspath('u |
| 32 |
.BI "struct udev_device *udev_device_new_from_syspath(struct\ udev\ *" "udev" ", const\ char\ *" "syspath" ");" |
| 33 |
.HP \w'struct\ udev_device\ *udev_device_new_from_devnum('u |
| 34 |
.BI "struct udev_device *udev_device_new_from_devnum(struct\ udev\ *" "udev" ", char\ " "type" ", dev_t\ " "devnum" ");" |
| 35 |
.HP \w'struct\ udev_device\ *udev_device_new_from_subsystem_sysname('u |
| 36 |
.BI "struct udev_device *udev_device_new_from_subsystem_sysname(struct\ udev\ *" "udev" ", const\ char\ *" "subsystem" ", const\ char\ *" "sysname" ");" |
| 37 |
.HP \w'struct\ udev_device\ *udev_device_new_from_device_id('u |
| 38 |
.BI "struct udev_device *udev_device_new_from_device_id(struct\ udev\ *" "udev" ", const\ char\ *" "id" ");" |
| 39 |
.HP \w'struct\ udev_device\ *udev_device_new_from_environment('u |
| 40 |
.BI "struct udev_device *udev_device_new_from_environment(struct\ udev\ *" "udev" ");" |
| 41 |
.HP \w'struct\ udev_device\ *udev_device_ref('u |
| 42 |
.BI "struct udev_device *udev_device_ref(struct\ udev_device\ *" "udev_device" ");" |
| 43 |
.HP \w'struct\ udev_device\ *udev_device_unref('u |
| 44 |
.BI "struct udev_device *udev_device_unref(struct\ udev_device\ *" "udev_device" ");" |
| 45 |
.SH "DESCRIPTION" |
| 46 |
.PP |
| 47 |
\fBudev_device_new_from_syspath()\fR, |
| 48 |
\fBudev_device_new_from_devnum()\fR, |
| 49 |
\fBudev_device_new_from_subsystem_sysname()\fR, |
| 50 |
\fBudev_device_new_from_device_id()\fR, and |
| 51 |
\fBudev_device_new_from_environment()\fR |
| 52 |
allocate a new udev device object and returns a pointer to it\&. This object is opaque and must not be accessed by the caller via different means than functions provided by libudev\&. Initially, the reference count of the device is 1\&. You can acquire further references, and drop gained references via |
| 53 |
\fBudev_device_ref()\fR |
| 54 |
and |
| 55 |
\fBudev_device_unref()\fR\&. Once the reference count hits 0, the device object is destroyed and freed\&. |
| 56 |
.PP |
| 57 |
\fBudev_device_new_from_syspath()\fR, |
| 58 |
\fBudev_device_new_from_devnum()\fR, |
| 59 |
\fBudev_device_new_from_subsystem_sysname()\fR, and |
| 60 |
\fBudev_device_new_from_device_id()\fR |
| 61 |
create the device object based on information found in |
| 62 |
/sys/, annotated with properties from the udev\-internal device database\&. A syspath is any subdirectory of |
| 63 |
/sys/, with the restriction that a subdirectory of |
| 64 |
/sys/devices |
| 65 |
(or a symlink to one) represents a real device and as such must contain a |
| 66 |
uevent |
| 67 |
file\&. |
| 68 |
\fBudev_device_new_from_devnum()\fR |
| 69 |
takes a device type, which can be |
| 70 |
\fBb\fR |
| 71 |
for block devices or |
| 72 |
\fBc\fR |
| 73 |
for character devices, as well as a devnum (see |
| 74 |
\fBmakedev\fR(3))\&. |
| 75 |
\fBudev_device_new_from_subsystem_sysname()\fR |
| 76 |
looks up devices based on the provided subsystem and sysname (see |
| 77 |
\fBudev_device_get_subsystem\fR(3) |
| 78 |
and |
| 79 |
\fBudev_device_get_sysname\fR(3)) and |
| 80 |
\fBudev_device_new_from_device_id()\fR |
| 81 |
looks up devices based on the provided device ID, which is a special string in one of the following four forms: |
| 82 |
.sp |
| 83 |
.it 1 an-trap |
| 84 |
.nr an-no-space-flag 1 |
| 85 |
.nr an-break-flag 1 |
| 86 |
.br |
| 87 |
.B Table\ \&1.\ \&Device ID strings |
| 88 |
.TS |
| 89 |
allbox tab(:); |
| 90 |
lB lB. |
| 91 |
T{ |
| 92 |
Example |
| 93 |
T}:T{ |
| 94 |
Explanation |
| 95 |
T} |
| 96 |
.T& |
| 97 |
l l |
| 98 |
l l |
| 99 |
l l |
| 100 |
l l. |
| 101 |
T{ |
| 102 |
\fIb8:2\fR |
| 103 |
T}:T{ |
| 104 |
block device major:minor |
| 105 |
T} |
| 106 |
T{ |
| 107 |
\fIc128:1\fR |
| 108 |
T}:T{ |
| 109 |
char device major:minor |
| 110 |
T} |
| 111 |
T{ |
| 112 |
\fIn3\fR |
| 113 |
T}:T{ |
| 114 |
network device ifindex |
| 115 |
T} |
| 116 |
T{ |
| 117 |
\fI+sound:card29\fR |
| 118 |
T}:T{ |
| 119 |
kernel driver core subsystem:device name |
| 120 |
T} |
| 121 |
.TE |
| 122 |
.sp 1 |
| 123 |
.PP |
| 124 |
\fBudev_device_new_from_environment()\fR |
| 125 |
creates a device from the current environment (see |
| 126 |
\fBenviron\fR(7))\&. Each key\-value pair is interpreted in the same way as if it was received in an uevent (see |
| 127 |
\fBudev_monitor_receive_device\fR(3))\&. The keys |
| 128 |
\fBDEVPATH\fR, |
| 129 |
\fBSUBSYSTEM\fR, |
| 130 |
\fBACTION\fR, and |
| 131 |
\fBSEQNUM\fR |
| 132 |
are mandatory\&. |
| 133 |
.SH "RETURN VALUE" |
| 134 |
.PP |
| 135 |
On success, |
| 136 |
\fBudev_device_new_from_syspath()\fR, |
| 137 |
\fBudev_device_new_from_devnum()\fR, |
| 138 |
\fBudev_device_new_from_subsystem_sysname()\fR, |
| 139 |
\fBudev_device_new_from_device_id()\fR |
| 140 |
and |
| 141 |
\fBudev_device_new_from_environment()\fR |
| 142 |
return a pointer to the allocated udev device\&. On failure, |
| 143 |
\fBNULL\fR |
| 144 |
is returned, and |
| 145 |
\fIerrno\fR |
| 146 |
is set appropriately\&. |
| 147 |
\fBudev_device_ref()\fR |
| 148 |
returns the argument that it was passed, unmodified\&. |
| 149 |
\fBudev_device_unref()\fR |
| 150 |
always returns |
| 151 |
\fBNULL\fR\&. |
| 152 |
.SH "HISTORY" |
| 153 |
.PP |
| 154 |
\fBudev_device_new_from_syspath()\fR, |
| 155 |
\fBudev_device_new_from_devnum()\fR, |
| 156 |
\fBudev_device_new_from_subsystem_sysname()\fR, |
| 157 |
\fBudev_device_new_from_device_id()\fR, |
| 158 |
\fBudev_device_new_from_environment()\fR, |
| 159 |
\fBudev_device_ref()\fR, and |
| 160 |
\fBudev_device_unref()\fR |
| 161 |
were added in version 221\&. |
| 162 |
.SH "SEE ALSO" |
| 163 |
.PP |
| 164 |
\fBudev_new\fR(3), \fBudev_device_get_syspath\fR(3), \fBudev_device_has_tag\fR(3), \fBudev_enumerate_new\fR(3), \fBudev_monitor_new_from_netlink\fR(3), \fBudev_list_entry\fR(3), \fBsystemd\fR(1) |