libsysdev.3

.\" Copyright (c) 2015 A.D. Isaac Dunham, no rights reserved
.\" Released under the libsysdev license
.TH "LIBSYSDEV" 3 2015 "libsysdev"
.SH NAME
libsysdev \- library to access sysfs information about devices
.SH SYNOPSIS
.nf
.B #include <libsysdev/sysdev.h>
.sp
.BI "char *sysdev_getsyspath(unsigned int " major ", unsigned int " minor ", int ischar);"
.BI "char *sysdev_devfd_to_syspath(int " devfd ");"
.BI "int sysdev_devfd_to_sysfd(int " devfd ");"
.BI "int sysdev_devfd_to_pciid(int *" vendor_id ", int *" device_id ", int " devfd ");"
.BI "int sysdev_getproductids(int *" vendor_id ", int *" device_id ", int " sysfd ");"
.fi
.SH DESCRIPTION
In general,
.I devfd
means a file descriptor referring to a device.
.I syspath
means a string containing an absolute path within
.I /sys.
.I sysfd
means a file descriptor referring to a syspath.

.BI "sysdev_getsyspath( " major ", " minor ", " ischar ")"
takes as its first two arguments
the
.I major
and
.I minor
of a device;
.I ischar
should be nonzero if the device is a character device,
0 if it is a block device.
On success it returns a
.BR calloc (3)ed
buffer of length
.BR PATH_MAX ,
containing
a path of the general form
.I /sys/devices/.../device
that corresponds to the device described by the arguments.

Note that, for simplicity of implementation, this version of
.BR libsysdev ()
returns a syspath of the form
.IR /sys//devices/...
(note the double slash); relying on a fixed offset from the start is wrong,
and this behavior may well change in future.

.BI sysdev_devfd_to_syspath( devfd )
takes as its only argument a file descriptor
referring to a device node. It returns the same output as
.BR sysdev_getsyspath ().

.BI sysdev_devfd_to_sysfd( devfd )
takes as its only argument a file descriptor
referring to a device node. It returns a file descriptor referring to a
corresponding directory in
.IR /sys .

.BI "sysdev_getproductids(int *" vendor_id ", int *" device_id ", int " sysfd )
fills
.I vendor_id
with the PCI vendor number and
.I device_id
with the PCI device number found in
the sysfs directory pointed to by
.IR sysfd .
It returns 0 if it is successful,
nonzero if it fails.

.BI "sysdev_devfd_to_pciid(int *" vendor_id ", int *" device_id ", int " devfd )
fills
.I vendor_id
with the PCI vendor number and
.I device_id
with the PCI device number for the device to which
.I devfd
refers.
It returns 0 on success, nonzero on failure.

.SH RETURN VALUE
.BR sysdev_getsyspath ()
and
.BR sysdev_devfd_to_syspath ()
return the sysfs directory
corresponding to the device referred to by their arguments.
If it cannot be determined, they return NULL.

.BR sysdev_devfd_to_sysfd ()
returns a file descriptor for the sysfs directory
corresponding to the device of which
.I devfd
is a file descriptor.

.BR sysdev_getproductids ()
fills its first two arguments with the PCI ids
found in the sysfs directory pointed to by
.IR sysfd .
It returns 0 if it is successful, nonzero if it fails.
.BI "sysdev_devfd_to_pciid(int *" vend ", int *" chip ", int " devfd );
is equivalent to
.BI "sysdev_getproductids(int *" vend ", int *" chip ", sysdev_devfd_to_sysfd(" devfd ));
and has the same return values.

.SH ERRORS
Functions that take a device fd as an argument (
.BR sysdev_devfd_to_syspath (),
.BR sysdev_devfd_to_sysfd (),
and
.BR sysdev_devfd_to_pciid ())
will set
.I errno
=
.B EINVAL
if
.I devfd
does not refer to a device.

Functions that take a device fd as an argument call
.BR fstat (3)
internally and can fail with any failure that
.BR fstat (3)
encounters.

.BR sysdev_devfd_to_sysfd ()
and
.BR sysdev_getproductids ()
call
.BR open (2)
internally and can fail with any failure that
.BR open (2)
encounters.

.BR sysdev_getsyspath (),
.BR sysdev_devfd_to_syspath (),
.BR sysdev_devfd_to_sysfd (),
and
.BR sysdev_devfd_to_pciid ()
use
.BR calloc(3)
internally and can theoretically set any error which it sets.