'\" t
.TH "UDEV_DEVICE_NEW_FROM_SYSPATH" "3" "" "systemd 241" "udev_device_new_from_syspath"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
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
.SH "SYNOPSIS"
.sp
.ft B
.nf
#include <libudev\&.h>
.fi
.ft
.HP \w'struct\ udev_device\ *udev_device_new_from_syspath('u
.BI "struct udev_device *udev_device_new_from_syspath(struct\ udev\ *" "udev" ", const\ char\ *" "syspath" ");"
.HP \w'struct\ udev_device\ *udev_device_new_from_devnum('u
.BI "struct udev_device *udev_device_new_from_devnum(struct\ udev\ *" "udev" ", char\ " "type" ", dev_t\ " "devnum" ");"
.HP \w'struct\ udev_device\ *udev_device_new_from_subsystem_sysname('u
.BI "struct udev_device *udev_device_new_from_subsystem_sysname(struct\ udev\ *" "udev" ", const\ char\ *" "subsystem" ", const\ char\ *" "sysname" ");"
.HP \w'struct\ udev_device\ *udev_device_new_from_device_id('u
.BI "struct udev_device *udev_device_new_from_device_id(struct\ udev\ *" "udev" ", const\ char\ *" "id" ");"
.HP \w'struct\ udev_device\ *udev_device_new_from_environment('u
.BI "struct udev_device *udev_device_new_from_environment(struct\ udev\ *" "udev" ");"
.HP \w'struct\ udev_device\ *udev_device_ref('u
.BI "struct udev_device *udev_device_ref(struct\ udev_device\ *" "udev_device" ");"
.HP \w'struct\ udev_device\ *udev_device_unref('u
.BI "struct udev_device *udev_device_unref(struct\ udev_device\ *" "udev_device" ");"
.SH "DESCRIPTION"
.PP
\fBudev_device_new_from_syspath\fR,
\fBudev_device_new_from_devnum\fR,
\fBudev_device_new_from_subsystem_sysname\fR,
\fBudev_device_new_from_device_id\fR, and
\fBudev_device_new_from_environment\fR
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
\fBudev_device_ref()\fR
and
\fBudev_device_unref()\fR\&. Once the reference count hits 0, the device object is destroyed and freed\&.
.PP
\fBudev_device_new_from_syspath\fR,
\fBudev_device_new_from_devnum\fR,
\fBudev_device_new_from_subsystem_sysname\fR, and
\fBudev_device_new_from_device_id\fR
create the device object based on information found in
/sys, annotated with properties from the udev\-internal device database\&. A syspath is any subdirectory of
/sys, with the restriction that a subdirectory of
/sys/devices
(or a symlink to one) represents a real device and as such must contain a
uevent
file\&.
\fBudev_device_new_from_devnum\fR
takes a device type, which can be
\fBb\fR
for block devices or
\fBc\fR
for character devices, as well as a devnum (see
\fBmakedev\fR(3))\&.
\fBudev_device_new_from_subsystem_sysname\fR
looks up devices based on the provided subsystem and sysname (see
\fBudev_device_get_subsystem\fR(3)
and
\fBudev_device_get_sysname\fR(3)) and
\fBudev_device_new_from_device_id\fR
looks up devices based on the provided device ID, which is a special string in one of the following four forms:
.sp
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.B Table\ \&1.\ \&Device ID strings
.TS
allbox tab(:);
lB lB.
T{
Example
T}:T{
Explanation
T}
.T&
l l
l l
l l
l l.
T{
\fIb8:2\fR
T}:T{
block device major:minor
T}
T{
\fIc128:1\fR
T}:T{
char device major:minor
T}
T{
\fIn3\fR
T}:T{
network device ifindex
T}
T{
\fI+sound:card29\fR
T}:T{
kernel driver core subsystem:device name
T}
.TE
.sp 1
.PP
\fBudev_device_new_from_environment\fR
creates a device from the current environment (see
\fBenviron\fR(7))\&. Each key\-value pair is interpreted in the same way as if it was received in an uevent (see
\fBudev_monitor_receive_device\fR(3))\&. The keys
\fBDEVPATH\fR,
\fBSUBSYSTEM\fR,
\fBACTION\fR, and
\fBSEQNUM\fR
are mandatory\&.
.SH "RETURN VALUE"
.PP
On success,
\fBudev_device_new_from_syspath()\fR,
\fBudev_device_new_from_devnum()\fR,
\fBudev_device_new_from_subsystem_sysname()\fR,
\fBudev_device_new_from_device_id()\fR
and
\fBudev_device_new_from_environment()\fR
return a pointer to the allocated udev device\&. On failure,
\fBNULL\fR
is returned, and
\fIerrno\fR
is set appropriately\&.
\fBudev_device_ref()\fR
returns the argument that it was passed, unmodified\&.
\fBudev_device_unref()\fR
always returns
\fBNULL\fR\&.
.SH "SEE ALSO"
.PP
\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),