mirror of
https://github.com/systemd/systemd-stable.git
synced 2024-10-30 23:21:08 +03:00
0c17d02da2
Mary Edie Merideth noticed this typo. I think this is what it was supposed to be. Judging by the pattern.
1688 lines
61 KiB
Plaintext
1688 lines
61 KiB
Plaintext
|
|
System Utilities sysfs Library - libsysfs
|
|
=========================================
|
|
|
|
Version: 0.4.0
|
|
December 16, 2003
|
|
|
|
Contents
|
|
--------
|
|
1. Introduction
|
|
2. Requirements
|
|
3. Definitions
|
|
4. Overview
|
|
5. Data Structures
|
|
5.1 Directory and Attribute Data Structures
|
|
5.1.1 Attribute Structure
|
|
5.1.2 Link Structure
|
|
5.1.3 Directory Structure
|
|
5.2 Bus Data Structure
|
|
5.3 Class Data Structures
|
|
5.4 Root Device Data Structure
|
|
5.5 Device Data Structure
|
|
5.6 Driver Data Structure
|
|
6. Functions
|
|
6.1 Utility Functions
|
|
6.2 Filesystem Functions
|
|
6.2.1 Attribute Functions
|
|
6.2.2 Directory Link Functions
|
|
6.2.3 Directory Functions
|
|
6.3 Bus Functions
|
|
6.4 Class Functions
|
|
6.5 Device Functions
|
|
6.6 Driver Functions
|
|
7. Navigating a dlist
|
|
8. Usage
|
|
9. Conclusion
|
|
|
|
|
|
1. Introduction
|
|
---------------
|
|
|
|
Libsysfs' purpose is to provide a consistent and stable interface for
|
|
querying system device information exposed through the sysfs filesystem.
|
|
The library implements functions for querying filesystem information,
|
|
such as reading directories and files. It also contains routines for
|
|
working with buses, classes, and the device tree.
|
|
|
|
|
|
2. Requirements
|
|
---------------
|
|
|
|
The library must satisfy the following requirements:
|
|
|
|
- It must provide a stable programming interfaces that applications can
|
|
be built upon.
|
|
|
|
- It must provide functions to retrieve device Vital Product Data (VPD)
|
|
information for Error Log Analysis (ELA) support. ELA will provide
|
|
device driver and device bus address information.
|
|
|
|
- It must provide access to all system devices and information exposed
|
|
by sysfs.
|
|
|
|
- It must provide a function to find sysfs' current mount point.
|
|
|
|
- It must provide a function for udev to retrieve a device's major and
|
|
minor numbers.
|
|
|
|
|
|
3. Definitions
|
|
--------------
|
|
|
|
- sysfs: Sysfs is a virtual filesystem in 2.5+ Linux kernels that
|
|
presents a hierarchical representation of all system physical and
|
|
virtual devices. It presents system devices by bus, by class, and
|
|
by topology. Callbacks to device drivers are exposed as files in
|
|
device directories. Sysfs, for all purposes, is our tree of system
|
|
devices. For more information, please see:
|
|
|
|
http://www.kernel.org/pub/linux/kernel/people/mochel/doc/
|
|
|
|
- udev: Udev is Greg Kroah-Hartman's User Space implementation of devfs.
|
|
Udev creates /dev nodes for devices upon Hotplug events. The Hotplug
|
|
event provides udev with a sysfs directory location of the device. Udev
|
|
must use that directory to grab device's major and minor number, which it
|
|
will use to create the /dev node. For more information, please see:
|
|
|
|
http://www.kernel.org/pub/linux/utils/kernel/hotplug/
|
|
|
|
|
|
4. Overview
|
|
-----------
|
|
|
|
Libsysfs grew from a common need. There are several applications under
|
|
development that need access to sysfs and system devices. Udev, on a
|
|
hotplug event, must take a sysfs device path and create a /dev node. Our
|
|
diagnostic client needs to list all system devices. Finally, our Error
|
|
Log Analysis piece is required to retrieve VPD information for a
|
|
failing device. We divided to create a single library interface rather
|
|
than having these separate applications create their own accesses to
|
|
sysfs involving reading directories and files.
|
|
|
|
Libsysfs will also provide stability for applications to be built upon. Sysfs
|
|
currently doesn't enforce any standards for callback or file names. File
|
|
names change depending on bus or class. Sysfs is also changing, it is
|
|
currently being developed. Libsysfs will provide a stable interface to
|
|
applications while allowing sysfs to change underneath it.
|
|
|
|
Like sysfs, the library will provide devices to applications by bus, by
|
|
class, and by topology. The library will function similar to directories
|
|
and files that lie underneath it. To query a device on a PCI bus, one would
|
|
"open" the bus to scan or read devices and "close" the bus when
|
|
completed. Besides supplying functions to retrieve devices, the library
|
|
will also provide some utility functions like getting sysfs mount point.
|
|
|
|
|
|
5. Data Structures
|
|
------------------
|
|
|
|
Libsysfs will classify system devices following sysfs' example, dividing
|
|
them by bus, class, and devices. The library presents this information
|
|
generically. It doesn't, for example, differentiate between PCI and USB
|
|
buses. Device attributes are presented with values as they are exposed
|
|
by sysfs, the values are not formatted.
|
|
|
|
The library will provide standard definitions for working with sysfs
|
|
and devices, here's some examples:
|
|
|
|
#define SYSFS_FSTYPE_NAME "sysfs"
|
|
#define SYSFS_PROC_MNTS "/proc/mounts"
|
|
#define SYSFS_BUS_DIR "/bus"
|
|
#define SYSFS_BUS_NAME "bus"
|
|
#define SYSFS_CLASS_DIR "/class"
|
|
#define SYSFS_CLASS_NAME "class"
|
|
#define SYSFS_BLOCK_DIR "/block"
|
|
#define SYSFS_BLOCK_NAME "block"
|
|
#define SYSFS_DEVICES_DIR "/devices"
|
|
#define SYSFS_DEVICES_NAME "devices"
|
|
#define SYSFS_DRIVERS_DIR "/drivers"
|
|
#define SYSFS_DRIVERS_NAME "drivers"
|
|
#define SYSFS_NAME_ATTRIBUTE "name"
|
|
|
|
The library uses some definitions to mark maximum size of a sysfs name or
|
|
path length:
|
|
|
|
#define SYSFS_PATH_MAX 255
|
|
#define SYSFS_NAME_LEN 50
|
|
#define SYSFS_BUS_ID_SIZE 20
|
|
|
|
|
|
NOTE:
|
|
As of release 0.4.0 of libsysfs, a number of changes have been made
|
|
so that the dlists and "directory" references in all libsysfs's
|
|
structures are not populated until such time that it is absolutely
|
|
necessary. Hence, these elements may not contain valid data at all
|
|
times (as was the case before).
|
|
|
|
5.1 Directory and Attribute Data Structures
|
|
-------------------------------------------
|
|
|
|
The library implements structures to represent sysfs directories, links,
|
|
and files.
|
|
|
|
|
|
5.1.1 Attribute Structure
|
|
-------------------------
|
|
|
|
A file in sysfs represents a device or driver attribute. Attributes can be
|
|
read only, write only, or read and write. File data can be ASCII and
|
|
binary. The library has the following structure to represent files:
|
|
|
|
struct sysfs_attribute {
|
|
unsigned char *value;
|
|
unsigned short len; /* value length */
|
|
unsigned short method; /* show and store */
|
|
unsigned char name[SYSFS_NAME_LEN];
|
|
unsigned char path[SYSFS_PATH_MAX];
|
|
};
|
|
|
|
Path represents the file/attribute's full path. Value is used when reading
|
|
from or writing to an attribute. "len" is the length of data in "value".
|
|
Method is a bitmask for defining if the attribute supports show(read)
|
|
and/or store(write).
|
|
|
|
|
|
5.1.2 Link Structure
|
|
--------------------
|
|
|
|
Symbolic links are used in sysfs to link bus or class views with
|
|
particular devices.
|
|
|
|
struct sysfs_link {
|
|
unsigned char name[SYSFS_NAME_LEN];
|
|
unsigned char path[SYSFS_PATH_MAX];
|
|
unsigned char target[SYSFS_PATH_MAX];
|
|
};
|
|
|
|
Link's name is stored in "name' and it's target stored in "target". Absolute
|
|
path to the link is stored in "path".
|
|
|
|
|
|
5.1.3 Directory Structure
|
|
-------------------------
|
|
|
|
The directory structure represents a sysfs directory:
|
|
|
|
struct sysfs_directory {
|
|
struct dlist *subdirs;
|
|
struct dlist *links;
|
|
struct dlist *attributes;
|
|
unsigned char name[SYSFS_NAME_LEN];
|
|
unsigned char path[SYSFS_PATH_MAX];
|
|
};
|
|
|
|
The sysfs_directory structure includes the list of subdirectories, links and
|
|
attributes. The "name" and absolute "path" are also stored in the structure.
|
|
The sysfs_directory structure is intended for use internal to the library.
|
|
Applications needing access to attributes and links from the directory
|
|
will need to make appropriate calls (described below) to get the same.
|
|
|
|
|
|
5.2 Bus Data Structure
|
|
----------------------
|
|
|
|
All buses look similar in sysfs including lists of devices and drivers,
|
|
therefore we use the following structure to represent all sysfs buses:
|
|
|
|
struct sysfs_bus {
|
|
unsigned char name[SYSFS_NAME_LEN];
|
|
unsigned char path[SYSFS_PATH_MAX];
|
|
|
|
/* internal use only */
|
|
struct dlist *drivers;
|
|
struct dlist *devices;
|
|
struct sysfs_directory *directory;
|
|
};
|
|
|
|
The sysfs_bus structure contains the bus "name", while the "path" to bus
|
|
directory is also stored. It also contains lists of devices on the bus
|
|
and drivers that are registered on it. The bus' directory is represented
|
|
by the sysfs_directory structure and it contains references to all the
|
|
subdirectories, links, and attributes. The sysfs_directory structure
|
|
is for internal use only. The following functions may be used by
|
|
applications to retrieve data from the sysfs_directory structure:
|
|
|
|
struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus)
|
|
struct sysfs_attribute *sysfs_get_bus_attribute(struct sysfs_bus *bus,
|
|
unsigned char *attrname)
|
|
|
|
|
|
5.3 Class Data Structures
|
|
-------------------------
|
|
|
|
The library uses two data structures to represent classes in sysfs. Sysfs
|
|
classes contains a class directory like "net" or "scsi_host" and then
|
|
class devices like "eth0", "lo", or "eth1" for the "net" class.
|
|
|
|
struct sysfs_class {
|
|
unsigned char name[SYSFS_NAME_LEN];
|
|
unsigned char path[SYSFS_PATH_MAX];
|
|
|
|
/* for internal use only */
|
|
struct dlist *devices;
|
|
struct sysfs_directory *directory;
|
|
};
|
|
|
|
The sysfs_class represents device classes in sysfs like "net". It contains
|
|
the class "name", "path" to the class, a list of class devices and the
|
|
directory representation (for internal use only).
|
|
|
|
struct sysfs_class_device {
|
|
unsigned char name[SYSFS_NAME_LEN];
|
|
unsigned char classname[SYSFS_NAME_LEN];
|
|
unsigned char path[SYSFS_PATH_MAX];
|
|
|
|
/* for internal use only */
|
|
struct sysfs_class_device *parent;
|
|
struct sysfs_device *sysdevice; /* NULL if virtual */
|
|
struct sysfs_driver *driver; /* NULL if not implemented */
|
|
struct sysfs_directory *directory;
|
|
};
|
|
|
|
A class device isn't the same as a sysfs_device, it's specific to the class in
|
|
which it belongs. The class device structure contains the name of the class
|
|
the class device belongs to, its sysfs_device reference and that device's
|
|
driver reference (if any). It also contains the name of the class device
|
|
- like "eth0", its parent point (if present) and its sysfs directory
|
|
information including links and attributes (for internal use only).
|
|
The following function may be used by applications to retrieve data
|
|
from the sysfs_directory structure:
|
|
|
|
struct dlist *sysfs_get_classdev_attributes(struct sysfs_class_device *cdev);
|
|
|
|
|
|
5.4 Root Device Data Structure
|
|
------------------------------
|
|
|
|
Device hierarchies in sysfs are represented under the /sys/devices directory
|
|
structure. Sysfs devices typically spawn off from base devices which are
|
|
represented by a sysfs_root_device.
|
|
|
|
struct sysfs_root_device {
|
|
unsigned char name[SYSFS_NAME_LEN];
|
|
unsigned char path[SYSFS_PATH_MAX];
|
|
|
|
/* for internal use only */
|
|
struct dlist *devices;
|
|
struct sysfs_directory *directory;
|
|
};
|
|
|
|
The sysfs_root_device structure contains a list of "devices" that spawn off it.
|
|
The name of the root device as represented under /sys/devices is read into
|
|
"name" and the absolute path into "path" and its sysfs_directory information
|
|
intended to be used internal to the library.
|
|
|
|
|
|
5.5 Device Data Structure
|
|
-------------------------
|
|
|
|
The sysfs_device structure represents a system device that's exposed
|
|
in sysfs under the /sys/devices directory structure.
|
|
|
|
struct sysfs_device {
|
|
unsigned char name[SYSFS_NAME_LEN];
|
|
unsigned char bus_id[SYSFS_NAME_LEN];
|
|
unsigned char bus[SYSFS_NAME_LEN];
|
|
unsigned char driver_name[SYSFS_NAME_LEN];
|
|
unsigned char path[SYSFS_PATH_MAX];
|
|
|
|
/* for internal use only */
|
|
struct sysfs_device *parent;
|
|
struct dlist *children;
|
|
struct sysfs_directory *directory;
|
|
};
|
|
|
|
The sysfs_device structure contains a "parent" pointer, a list of child
|
|
devices, if any, device's directory, its bus id - which is the name of
|
|
device's directory, the bus name on which this device is registered and
|
|
its driver name. The device structure also contains the absolute path
|
|
to the device and a directory structure, which contains a list of the
|
|
device's attributes (for internal use only). The following functions
|
|
may be used to obtain information from sysfs_directory structure:
|
|
|
|
struct sysfs_attribute *sysfs_get_device_attribute(struct sysfs_device *dev,
|
|
const unsigned char *name)
|
|
struct dlist *sysfs_get_device_attributes(struct sysfs_device *device)
|
|
|
|
|
|
5.6 Driver Data Structure
|
|
-------------------------
|
|
|
|
The sysfs_driver structure represents a device driver.
|
|
|
|
struct sysfs_driver {
|
|
unsigned char name[SYSFS_NAME_LEN];
|
|
unsigned char path[SYSFS_PATH_MAX];
|
|
|
|
/* for internal use only */
|
|
struct dlist *devices;
|
|
struct sysfs_directory *directory;
|
|
};
|
|
|
|
The sysfs_driver structure contains a list of devices that use this driver,
|
|
the name of the driver, its path, and its directory information, which
|
|
includes the driver's attributes (for internal use only). The following
|
|
function may be used to retrieve driver attribute information from the
|
|
sysfs_directory structure:
|
|
|
|
struct dlist *sysfs_get_driver_attributes(struct sysfs_driver *driver)
|
|
|
|
|
|
6. Functions
|
|
------------
|
|
|
|
Libsysfs will provide functions to access system devices by bus, by class,
|
|
and by device. Functions will act like accessing directories and files,
|
|
using "open" and "close". Open returns a structure and close is used
|
|
to clean that structure up.
|
|
|
|
|
|
6.1 Utility Functions
|
|
---------------------
|
|
|
|
The library will provide a few utility functions for working with sysfs.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_mnt_path
|
|
|
|
Description: Function finds the mount path for filesystem type "sysfs".
|
|
|
|
Arguments: unsigned char *mnt_path Mount path buffer
|
|
size_t len Size of mount path buffer
|
|
|
|
Returns: Zero with success.
|
|
-1 with error. Errno will be set with error:
|
|
- EINVAL for invalid argument, if buffer is NULL.
|
|
|
|
Prototype: sysfs_get_mnt_path(unsigned char *mnt_path, size_t len);
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_name_from_path
|
|
|
|
Description: Function returns the last directory or file name from the
|
|
included path.
|
|
|
|
Arguments: const unsigned char *path Path to parse name from
|
|
unsigned char *name Buffer to put parsed name into
|
|
size_t *len Size of name buffer
|
|
|
|
Returns: 0 with success.
|
|
-1 on Error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: int sysfs_get_name_from_path(const unsigned char *path,
|
|
unsigned char *name, size_t *len)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_link
|
|
|
|
Description: Sysfs readlink function, reads the link at supplied path
|
|
and returns its target path.
|
|
|
|
Arguments: const unsigned char *path Link's path
|
|
unsigned char *target Buffer to place link's target path
|
|
size_t len Size of target buffer
|
|
|
|
Returns: 0 with success
|
|
-1 with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: int sysfs_get_link(const unsigned char *path,
|
|
unsigned char *target, size_t len)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_subsystem_list
|
|
|
|
Description: Function returns the list of entries for the given subsystem. If
|
|
the argument is "bus", this function will return a list of buses
|
|
("pci", "scsi", etc) supported on the system.
|
|
|
|
sysfs_close_list() has to be called to free the list obtained
|
|
from this call.
|
|
|
|
Arguments: unsigned char *name Subsystem to open, like "bus"..
|
|
|
|
Returns: dlist of entries for the subsystem on success
|
|
NULL with error indicating the "name" subsystem is invalid.
|
|
|
|
Prototype: struct dlist *sysfs_open_subsystem_list(unsigned char *name)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_bus_devices_list
|
|
|
|
Description: Function returns the list of devices on the given bus.
|
|
|
|
sysfs_close_list() has to be called to free the list obtained
|
|
from this call.
|
|
|
|
Arguments: unsigned char *name Bus name to open "pci"/"scsi"/"usb"..
|
|
|
|
Returns: dlist of device names for the given bus on success
|
|
NULL with error indicating the bus is not supported.
|
|
|
|
Prototype: struct dlist *sysfs_open_bus_devices_list(unsigned char *name)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_close_list
|
|
|
|
Description: Closes a given dlist. This can be used as a generic list close
|
|
routine.
|
|
|
|
Arguments: struct dlist *list List to be closed
|
|
|
|
Prototype: void sysfs_close_list(struct dlist *list)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_path_is_dir
|
|
|
|
Description: Utility function to verify if a given path is to a directory.
|
|
|
|
Arguments: unsigned char *path Path to verify
|
|
|
|
Returns: 0 on success, 1 on error
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: int sysfs_path_is_dir(unsigned char *path)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_path_is_file
|
|
|
|
Description: Utility function to verify if a given path is to a file.
|
|
|
|
Arguments: unsigned char *path Path to verify
|
|
|
|
Returns: 0 on success, 1 on error
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: int sysfs_path_is_file(unsigned char *path)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_path_is_link
|
|
|
|
Description: Utility function to verify if a given path is to a link.
|
|
|
|
Arguments: unsigned char *path Path to verify
|
|
|
|
Returns: 0 on success, 1 on error
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: int sysfs_path_is_link(unsigned char *path)
|
|
-------------------------------------------------------------------------------
|
|
|
|
6.2 Filesystem Functions
|
|
------------------------
|
|
|
|
Libsysfs provides a set of functions to open, read, and close directories
|
|
and attributes/files in sysfs. These functions mirror their filesystem
|
|
function counterparts.
|
|
|
|
6.2.1 Attribute Functions
|
|
-------------------------
|
|
|
|
Along with the usual open, read, and close functions, libsysfs provides
|
|
a couple other functions for accessing attribute values.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_attribute
|
|
|
|
Description: Opens up a file in sysfs and creates a sysfs_attribute
|
|
structure. File isn't read with this function.
|
|
|
|
Arguments: const unsigned char *path File/Attribute's path
|
|
|
|
Returns: struct sysfs_attribute * with success.
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_attribute *sysfs_open_attribute
|
|
(const unsigned char *path)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_close_attribute
|
|
|
|
Description: Cleans up and closes sysfs_attribute structure.
|
|
|
|
Arguments: struct sysfs_attribute *sysattr Attribute to close
|
|
|
|
Prototype: void sysfs_close_attribute(struct sysfs_attribute *sysattr)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_read_dir_attributes
|
|
|
|
Description: Reads the given sysfs_directory to create a list of attributes.
|
|
|
|
Arguments: struct sysfs_directory *sysdir sysfs_directory whose
|
|
attributes to read
|
|
|
|
Returns: struct dlist * of attributes on success
|
|
NULL with error. Errno will be set on error, returning EINVAL
|
|
for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_read_dir_attributes
|
|
(struct sysfs_directory *sysdir)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_refresh_attributes
|
|
|
|
Description: Given a list of attributes, this function refreshes the values
|
|
of attributes in the list.
|
|
|
|
Arguments: struct dlist *attrlist list of attributes to refresh
|
|
|
|
Returns: 0 with success.
|
|
1 with error. Errno will be set on error, returning EINVAL
|
|
for invalid arguments
|
|
|
|
Prototype: int sysfs_refresh_attributes(struct dlist *attrlist)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_read_attribute
|
|
|
|
Description: Reads the supplied attribute. Since the maximum transfer
|
|
from a sysfs attribute is a pagesize, function reads in
|
|
up to a page from the file and stores it in the "value"
|
|
field in the attribute.
|
|
|
|
Arguments: struct sysfs_attribute *sysattr Attribute to read
|
|
|
|
Returns: 0 with success.
|
|
-1 with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: int sysfs_read_attribute(struct sysfs_attribute *sysattr)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_write_attribute
|
|
|
|
Description: Writes to the supplied attribute. Function validates if attribute
|
|
is writable, and writes the new value to the attribute. Value to
|
|
write as well as its length is user supplied. In case the length
|
|
written is not equal to the length requested to be written, the
|
|
original value is restored and an error is returned.
|
|
|
|
Arguments: struct sysfs_attribute *sysattr Attribute to write to
|
|
const unsigned char *new_value New value for the attribute
|
|
size_t len Length of "new_value"
|
|
|
|
Returns: 0 with success.
|
|
-1 with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: int sysfs_write_attribute(struct sysfs_attribute *sysattr,
|
|
const unsigned char *new_value, size_t len)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_read_attribute_value
|
|
|
|
Description: Given a path to a specific attribute, function reads and
|
|
returns its value to the supplied value buffer.
|
|
|
|
Arguments: const unsigned char *attrpath Attribute path to read
|
|
unsigned char *value Buffer to place attribute's value
|
|
size_t vsize Size of buffer
|
|
|
|
Returns: 0 with success.
|
|
-1 with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: int sysfs_read_attribute_value(const unsigned char *attrpath,
|
|
unsigned char *value, size_t vsize)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_value_from_attributes
|
|
|
|
Description: Function takes a single or linked list of sysfs attribute
|
|
structures and returns the value of the specified attribute
|
|
name.
|
|
|
|
Arguments: struct sysfs_attribute *attr
|
|
Attribute list to search through
|
|
const unsigned char *name Name of attribute to return value
|
|
|
|
Returns: unsigned char * attribute value with success.
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: unsigned char *sysfs_get_value_from_attributes
|
|
(struct sysfs_attribute *attr, const unsigned char * name)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_directory_attribute
|
|
|
|
Description: Function walks the list of attributes for the given sysfs
|
|
directory and returns the sysfs_attribute structure for
|
|
the specified attribute name.
|
|
|
|
Arguments: struct sysfs_directory *dir Directory in which to search
|
|
unsigned char *attrname Attribute name to look for
|
|
|
|
Returns: struct sysfs_attribute on success.
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_attribute *sysfs_get_directory_attribute
|
|
(struct sysfs_directory *dir, unsigned char *attrname)
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
6.2.2 Link Functions
|
|
--------------------
|
|
|
|
Sysfs contains many symbolic links, like bus links to bus devices. Libsysfs
|
|
treats links differently than directories due to processing differences. A
|
|
link in the /sys/bus/"busname"/devices/ directory indicates a device in the
|
|
/sys/devices directory. Through links we give the functionality to know
|
|
what is and what isn't a link and the ability to query the links target.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_link
|
|
|
|
Description: Opens a directory link.
|
|
|
|
Arguments: const unsigned char *linkpath Path to link
|
|
|
|
Returns: struct sysfs_link * with success.
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_link *sysfs_open_link
|
|
(const unsigned char *linkpath)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_close_link
|
|
|
|
Description: Closes a directory link structure.
|
|
|
|
Arguments: struct sysfs_link *ln Link to close
|
|
|
|
Prototype: void sysfs_close_link(struct sysfs_link *ln)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_read_dir_links
|
|
|
|
Description: Reads the given sysfs_directory to create a list of links.
|
|
|
|
Arguments: struct sysfs_directory *sysdir sysfs_directory whose
|
|
links to read
|
|
|
|
Returns: struct dlist * of links with success
|
|
NULL with error. Errno will be set on error, returning EINVAL
|
|
for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_read_dir_links
|
|
(struct sysfs_directory *sysdir)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_directory_link
|
|
|
|
Description: Function walks the list of links for the given sysfs directory
|
|
and returns the sysfs_link structure for the specified link
|
|
name.
|
|
|
|
Arguments: struct sysfs_directory *dir Directory in which to search
|
|
unsigned char *linkname Link name to look for
|
|
|
|
Returns: struct sysfs_link * with success.
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_link *sysfs_get_directory_link
|
|
(struct sysfs_directory *dir, unsigned char *linkname)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_subdirectory_link
|
|
|
|
Description: Function walks the list of links for the given sysfs directory
|
|
and its subdirectories returns the sysfs_link structure for
|
|
the specified link name.
|
|
|
|
Arguments: struct sysfs_directory *dir Directory in which to search
|
|
unsigned char *linkname Link name to look for
|
|
|
|
Returns: struct sysfs_link * with success.
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_link *sysfs_get_subdirectory_link
|
|
(struct sysfs_directory *dir, unsigned char *linkname)
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
6.2.3 Directory Functions
|
|
-------------------------
|
|
|
|
Sysfs directories can represent every directory under sysfs. The structures
|
|
keep track of subdirectories, links, and files. Like opendir, readdir, and
|
|
closedir, libsysfs provides open, read, and close functions for working with
|
|
sysfs directories. Open creates the sysfs_directory structure. Read reads in
|
|
its contents - like subdirectories, links, and files. Close cleans it all
|
|
up.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_directory
|
|
|
|
Description: Opens a sysfs directory at a specific path
|
|
|
|
Arguments: const unsigned char *path Directory path to open
|
|
|
|
Returns: struct sysfs_directory * with success.
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_directory *sysfs_open_directory
|
|
(const unsigned char *path)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_close_directory
|
|
|
|
Description: Closes specific directory, its subdirectories, links, and
|
|
files.
|
|
|
|
Arguments: struct sysfs_directory *sysdir Directory to close
|
|
|
|
Prototype: void sysfs_close_directory(struct sysfs_directory *sysdir)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_read_dir_subdirs
|
|
|
|
Description: Reads the given sysfs_directory to create a list of subdirs.
|
|
|
|
Arguments: struct sysfs_directory *sysdir sysfs_directory whose
|
|
subdirs have to be read
|
|
|
|
Returns: struct dlist * of links with success
|
|
NULL with error. Errno will be set on error, returning EINVAL
|
|
for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_read_dir_subdirs
|
|
(struct sysfs_directory *sysdir)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_read_directory
|
|
|
|
Description: Read the supplied directory. Reading fills in the directory's
|
|
contents like subdirectories, links, and attributes.
|
|
|
|
Arguments: struct sysfs_directory *sysdir Directory to read
|
|
|
|
Returns: 0 with success.
|
|
-1 with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: int sysfs_read_directory(struct sysfs_directory *sysdir)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_read_all_subdirs
|
|
|
|
Description: Reads all subdirs under a given supplied directory.
|
|
|
|
Arguments: struct sysfs_directory *sysdir Directory to read
|
|
|
|
Returns: 0 with success.
|
|
-1 with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: int sysfs_read_all_subdirs(struct sysfs_directory *sysdir)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_subdirectory
|
|
|
|
Description: Function walks the directory tree for the given directory and
|
|
returns a sysfs_directory structure for the specified directory
|
|
name.
|
|
|
|
Arguments: struct sysfs_directory *dir Directory in which to search
|
|
unsigned char *subname Name of directory to look for
|
|
|
|
Returns: struct sysfs_directory with success.
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
6.3 Bus Functions
|
|
-----------------
|
|
|
|
The library provides a functions for viewing buses represented in sysfs.
|
|
The sysfs_open_bus opens a bus in the /sys/bus directory, such as "pci",
|
|
"usb", or "scsi". The open command returns a sysfs_bus structure that
|
|
contains a list of the bus' devices. The sysfs_close_bus function is
|
|
used to clean up the bus structure. Given a device or a driver,
|
|
functions are provided to determine what bus they are on.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_bus
|
|
|
|
Description: Function opens up one of the buses represented in sysfs in
|
|
the /sys/bus directory. It returns a sysfs_bus structure
|
|
that includes a list of bus devices and drivers.
|
|
|
|
Arguments: const unsigned char *name Bus name to open, like "pci"...
|
|
|
|
Returns: struct sysfs_bus * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_bus *sysfs_open_bus(const unsigned char *name)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_close_bus
|
|
|
|
Description: Function closes up the sysfs_bus structure including its
|
|
devices, drivers, and directory.
|
|
|
|
Arguments: sysfs_bus *bus Bus structure to close
|
|
|
|
Prototype: void sysfs_close_bus(struct sysfs_bus *bus)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_bus_devices
|
|
|
|
Description: Function returns a list of devices that are registered with
|
|
this bus.
|
|
|
|
Arguments: struct sysfs_bus *bus Bus whose devices list to return
|
|
|
|
Returns: struct dlist * of sysfs_devices on success
|
|
NULL with error. Errno will be sent with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_get_bus_devices(struct sysfs_bus *bus)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_bus_drivers
|
|
|
|
Description: Function returns a list of drivers that are registered with
|
|
this bus.
|
|
|
|
Arguments: struct sysfs_bus *bus Bus whose drivers list to return
|
|
|
|
Returns: struct dlist * of sysfs_drivers on success
|
|
NULL with error. Errno will be sent with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_get_bus_drivers(struct sysfs_bus *bus)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_bus_device
|
|
|
|
Description: Function takes a sysfs_bus structure(obtained on a successful
|
|
return from a sysfs_open_bus() call) and looks for the given
|
|
device on this bus. On success, it returns a sysfs_device
|
|
structure corresponding to the device.
|
|
|
|
Arguments: struct sysfs_bus *bus Bus structure on which to search
|
|
unsigned char *id Device to look for
|
|
|
|
Returns: struct sysfs_device * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_device *sysfs_get_bus_device
|
|
(struct sysfs_bus *bus, unsigned char *id)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_bus_driver
|
|
|
|
Description: Function takes a sysfs_bus structure (obtained on a successful
|
|
return from a sysfs_open_bus() call) and looks for the given
|
|
driver on this bus. On success, it returns a sysfs_driver
|
|
structure corresponding to the driver.
|
|
|
|
Arguments: struct sysfs_bus *bus Bus structure on which to search
|
|
unsigned char *drvname Driver to look for
|
|
|
|
Returns: struct sysfs_driver * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_device *sysfs_get_bus_driver
|
|
(struct sysfs_bus *bus, unsigned char *drvname)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_bus_attributes
|
|
|
|
Description: Function takes a sysfs_bus structure and returns a list of
|
|
attributes for the bus.
|
|
|
|
Arguments: struct sysfs_bus *bus Bus for which attributes are required
|
|
|
|
Returns: struct dlist * of attributes with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_bus_attribute
|
|
|
|
Description: Function takes a sysfs_bus structure and looks for the required
|
|
attribute on the bus. On success, it returns a sysfs_attribute
|
|
structure corresponding to the given attribute.
|
|
|
|
Arguments: struct sysfs_bus *bus Bus structure on which to search
|
|
unsigned char *attrname Attribute to look for
|
|
|
|
Returns: struct sysfs_attribute * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_attribute *sysfs_get_bus_attribute
|
|
(struct sysfs_bus *bus, unsigned char *attrname)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_bus_device
|
|
|
|
Description: Given the name of the bus on which to look for, this function
|
|
locates a given device on the bus and returns a sysfs_device
|
|
structure corresponding to the requested device.
|
|
|
|
NOTE:
|
|
1. The sysfs_device structure obtained upon successful return
|
|
from this function has to be closed by calling
|
|
sysfs_close_device().
|
|
|
|
Arguments: unsigned char *busname Bus on which to search
|
|
unsigned char *dev_id Name of the device to look for
|
|
|
|
Returns: struct sysfs_device * on success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_device *sysfs_open_bus_device
|
|
(unsigned char *busname, unsigned char *dev_id)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_find_driver_bus
|
|
|
|
Description: Given the name of a driver, this function finds the name of the
|
|
bus the driver is on
|
|
|
|
Arguments: const unsigned char *driver Name of the driver to look for
|
|
unsigned char *busname Buffer to return the bus name
|
|
size_t bsize Size of the "busname" buffer
|
|
|
|
Returns: 0 with success.
|
|
-1 with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: int sysfs_find_driver_bus(const unsigned char *driver,
|
|
unsigned char *busname, size_t bsize)
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
6.4 Class Functions
|
|
-------------------
|
|
|
|
Libsysfs provides functions to open sysfs classes and their class devices.
|
|
These functions too operate with open and close, close must be called to
|
|
clean up the class structures. Given a class device name, functions are
|
|
provided to determine what class they belong to. Once a class device
|
|
name and the class it belongs to is known, a function to open the
|
|
class device is provided. This method can be used when details of
|
|
a single class device is required.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_class
|
|
|
|
Description: Function opens up one of the classes represented in sysfs in
|
|
the /sys/class directory. It returns a sysfs_class structure
|
|
that includes a list of class devices.
|
|
|
|
Arguments: const unsigned char *name Class name to open, like "net"..
|
|
|
|
Returns: struct sysfs_class * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_class *sysfs_open_class(const unsigned char *name)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_close_class
|
|
|
|
Description: Function closes up the sysfs_class structure including its
|
|
class devices.
|
|
|
|
Arguments: sysfs_class *class Class structure to close
|
|
|
|
Prototype: void sysfs_close_class(struct sysfs_class *class);
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_class_device_path
|
|
|
|
Description: Function opens up one of the class devices represented in
|
|
sysfs in sysfs/class/"class"/ directory. It returns a
|
|
sysfs_class_device structure.
|
|
|
|
Arguments: const unsigned char *path Path to class device
|
|
|
|
Returns: struct sysfs_class_device * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_class_device *sysfs_open_class_device_path
|
|
(const unsigned char *path)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_close_class_device
|
|
|
|
Description: Function closes up the sysfs_class_device structure.
|
|
|
|
Arguments: sysfs_class_device *dev Class device structure to close
|
|
|
|
Prototype: void sysfs_close_class_device(struct sysfs_class_device *dev)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_class_device
|
|
|
|
Description: Function takes a sysfs_class structure(obtained on a successful
|
|
return from a sysfs_open_class() call) and looks for the given
|
|
device in this class. On success, it returns a sysfs_class_device
|
|
structure corresponding to the class device.
|
|
|
|
Arguments: struct sysfs_class *class Class on which to search
|
|
unsigned_char *name Class device "name" to look for
|
|
|
|
Returns: struct sysfs_class_device * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_class_device *sysfs_get_class_device
|
|
(struct sysfs_class *class, unsigned char *name)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_class_devices
|
|
|
|
Description: Function returns a list of class devices for the given class.
|
|
|
|
Arguments: struct sysfs_class *cls Class whose class device list
|
|
is required
|
|
|
|
Returns: struct dlist * of sysfs_class_devices on success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_get_class_devices(struct sysfs_class *cls)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_class_device
|
|
|
|
Description: Given the name of the class on which to look for, this function
|
|
locates a given class device and returns a sysfs_class_device
|
|
structure corresponding to the requested class device.
|
|
|
|
NOTE:
|
|
1. The sysfs_class_device structure obtained upon successful
|
|
return from this function has to be closed by calling
|
|
sysfs_close_class_device().
|
|
2. Class this device belongs to must be known prior to calling
|
|
this function.
|
|
|
|
Arguments: const unsigned char *classname Class on which to search
|
|
unsigned char *name Class device "name" to open
|
|
|
|
Returns: struct sysfs_class_device * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_class_device *sysfs_open_class_device
|
|
(const unsigned char *classname, unsigned char *class)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_classdev_device
|
|
|
|
Description: Function returns the sysfs_device reference (if present) for the
|
|
given class device.
|
|
|
|
Arguments: struct sysfs_class_device *clsdev Class device whose
|
|
sysfs_device reference
|
|
is required
|
|
|
|
Returns: struct sysfs_device * on success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_device *sysfs_get_classdev_device
|
|
(struct sysfs_class_device *clsdev)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_classdev_driver
|
|
|
|
Description: Function returns the sysfs_driver reference (if present) for the
|
|
given class device.
|
|
|
|
Arguments: struct sysfs_class_device *clsdev Class device whose
|
|
sysfs_driver reference
|
|
is required
|
|
|
|
Returns: struct sysfs_driver * on success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_driver *sysfs_get_classdev_driver
|
|
(struct sysfs_class_device *clsdev)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_classdev_parent
|
|
|
|
Description: Function returns the sysfs_class_device reference for the parent
|
|
(if present) of the given class device.
|
|
|
|
Arguments: struct sysfs_class_device *clsdev Class device whose
|
|
parent reference
|
|
is required
|
|
|
|
Returns: struct sysfs_class_device * on success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_class_device *sysfs_get_classdev_parent
|
|
(struct sysfs_class_device *clsdev)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_classdev_attributes
|
|
|
|
Description: Function takes a sysfs_class_device structure and returns a list
|
|
of attributes for the class device.
|
|
|
|
Arguments: struct sysfs_class_device *cdev Class device for which
|
|
attributes are required
|
|
|
|
Returns: struct dlist * of attributes with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_get_classdev_attributes
|
|
(struct sysfs_class_device *cdev)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_classdev_attr
|
|
|
|
Description: Searches supplied class device's attributes by name and returns
|
|
the attribute.
|
|
|
|
Arguments: struct sysfs_class_device *clsdev Device to search
|
|
const unsigned char *name Attribute name to find
|
|
|
|
Returns: struct sysfs_attribute * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_attribute *sysfs_get_classdev_attr
|
|
(struct sysfs_class_device *clsdev, const unsigned char *name)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_classdev_attr
|
|
|
|
Description: Function takes as arguments, a the name of the class, the class
|
|
device name and the name of the required attribute.
|
|
|
|
NOTE:
|
|
1. The struct sysfs_attribute * obtained upon successful
|
|
return from this function has to be closed by making
|
|
a call to sysfs_close_attribute()
|
|
|
|
Arguments: unsigned char *classname Class name on which to search
|
|
unsigned char *dev Name of the class device
|
|
unsigned char *attrib Attribute to open
|
|
|
|
Returns: struct sysfs_attribute * with success.
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_attribute *sysfs_write_classdev_attr
|
|
(const unsigned char *classname, const unsigned char *dev,
|
|
const unsigned char *attrib)
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
6.5 Device Functions
|
|
--------------------
|
|
|
|
Devices represent everything in sysfs under /sys/devices, which is a
|
|
hierarchical view of system devices. Besides the expected open and
|
|
close functions, libsysfs provides open and close functions for
|
|
root devices. These functions recursively open or close a device
|
|
and all of its children.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_device_path
|
|
|
|
Description: Opens up a device at a specific path. It opens the device's
|
|
directory, reads the directory, and returns a sysfs_device
|
|
structure.
|
|
|
|
Arguments: const unsigned char *path Path to device
|
|
|
|
Returns: struct sysfs_device * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_device *sysfs_open_device_path
|
|
(const unsigned char *path)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_close_device
|
|
|
|
Description: Function closes up the sysfs_device structure.
|
|
|
|
Arguments: sysfs_device *dev Device structure to close
|
|
|
|
Prototype: void sysfs_close_device(struct sysfs_device *dev)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_root_device
|
|
|
|
Description: Function opens up one of the root devices represented in sysfs
|
|
in the /sys/devices directory. It returns a sysfs_root_device
|
|
structure that includes a list of devices in the tree.
|
|
|
|
Arguments: const unsigned char *name Name of the root device to open
|
|
|
|
Returns: struct sysfs_root_device * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_device *sysfs_open_root_device
|
|
(const unsigned char *name)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_close_root_device
|
|
|
|
Description: Function closes up the sysfs_root_device structure including the
|
|
devices in the root device tree.
|
|
|
|
Arguments: sysfs_device *root Root device structure to close
|
|
|
|
Prototype: void sysfs_close_root_device(struct sysfs_root_device *root)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_device_parent
|
|
|
|
Description: Function returns the sysfs_device reference for the parent
|
|
(if present) of the given sysfs_device.
|
|
|
|
Arguments: struct sysfs_device *dev sysfs_device whose parent
|
|
reference is required
|
|
|
|
Returns: struct sysfs_device * on success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_device *sysfs_get_device_parent
|
|
(struct sysfs_device *dev)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_root_devices
|
|
|
|
Description: Function returns a list of devices under the given root device.
|
|
|
|
Arguments: struct sysfs_root_device *root sysfs_root_device whose devices
|
|
list is required
|
|
|
|
Returns: struct dlist * of sysfs_devices on success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_get_root_devices
|
|
(struct sysfs_root_device *root)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_device_attr
|
|
|
|
Description: Searches supplied device's attributes by name and returns
|
|
the attribute.
|
|
|
|
Arguments: struct sysfs_device *dev Device to search
|
|
const unsigned char *name Attribute name to find
|
|
|
|
Returns: struct sysfs_attribute * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_attribute *sysfs_get_device_attr
|
|
(struct sysfs_device *dev, const unsigned char *name)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_device_attributes
|
|
|
|
Description: Function takes a sysfs_device structure and returns a list
|
|
of attributes for the device.
|
|
|
|
Arguments: struct sysfs_device *device Device for which
|
|
attributes are required
|
|
|
|
Returns: struct dlist * of attributes with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_get_device_attributes
|
|
(struct sysfs_device *device)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_device
|
|
|
|
Description: Given the name of the bus on which to look for, this function
|
|
locates a given device and returns a sysfs_device structure
|
|
corresponding to the requested device.
|
|
|
|
Arguments: const unsigned char *bus_id Device to look for
|
|
const unsigned char *bus Bus on which to search
|
|
|
|
Returns: struct sysfs_device * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_device *sysfs_open_device
|
|
(const unsigned char *bus_id, const unsigned char *bus)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_device_attr
|
|
|
|
Description: Function takes as arguments, the bus on which to search for a
|
|
device, and an attribute of the device to open.
|
|
|
|
NOTE:
|
|
1. The struct sysfs_attribute * obtained upon successful
|
|
return from this function has to be closed by making
|
|
a call to sysfs_close_attribute()
|
|
|
|
Arguments: unsigned char *bus Bus on which to search
|
|
unsigned char *bus_id Device to look for
|
|
unsigned char *attrib Name of the attribute to open
|
|
|
|
Returns: struct sysfs_attribute * with success.
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_attribute *sysfs_open_device_attr
|
|
(const unsigned char *bus, const unsigned char *bus_id,
|
|
const unsigned char *attrib)
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
6.6 Driver Functions
|
|
--------------------
|
|
|
|
Drivers are represented in sysfs under the /sys/bus/xxx/drivers (xxx being
|
|
the bus type, such as "pci", "usb, and so on). Functions are provided to
|
|
open and close drivers.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_driver_path
|
|
|
|
Description: Opens driver at specific path.
|
|
|
|
Arguments: const unsigned char *path Path to driver
|
|
|
|
Returns: struct sysfs_driver * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_driver *sysfs_open_driver_path
|
|
(const unsigned char *path)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_close_driver
|
|
|
|
Description: Closes and cleans up sysfs_driver structure.
|
|
|
|
Arguments: sysfs_driver *driver Driver structure to close
|
|
|
|
Prototype: void sysfs_close_driver(struct sysfs_driver *driver)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_driver_devices
|
|
|
|
Description: Function returns a list of devices that use this driver.
|
|
|
|
Arguments: struct sysfs_driver *driver Driver whose devices list is
|
|
required
|
|
|
|
Returns: struct dlist * of sysfs_devices on success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_get_driver_devices
|
|
(struct sysfs_driver *driver)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_driver_device
|
|
|
|
Description: Function returns a sysfs_device reference for the device with
|
|
"name" that uses this driver
|
|
|
|
Arguments: struct sysfs_driver *driver Driver on which to search
|
|
const unsigned char *name Name of the device to look for
|
|
|
|
Returns: struct sysfs_device * corresponding to "name" on success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_get_driver_device
|
|
(struct sysfs_driver *driver, const unsigned char *name)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_driver_attr
|
|
|
|
Description: Searches supplied driver's attributes by name and returns
|
|
the attribute.
|
|
|
|
Arguments: struct sysfs_driver *drv Driver to search
|
|
const unsigned char *name Attribute name to find
|
|
|
|
Returns: struct sysfs_attribute * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_attribute *sysfs_get_driver_attr
|
|
(struct sysfs_driver *drv, const unsigned char *name)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_driver_attributes
|
|
|
|
Description: Function takes a sysfs_driver structure and returns a list
|
|
of attributes for the driver.
|
|
|
|
Arguments: struct sysfs_driver *driver Driver for which
|
|
attributes are required
|
|
|
|
Returns: struct dlist * of attributes with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct dlist *sysfs_get_driver_attributes
|
|
(struct sysfs_driver *driver)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_driver
|
|
|
|
Description: Given the name of the bus on which to look for, this function
|
|
locates a given driver and returns a sysfs_driver structure
|
|
corresponding to the requested device.
|
|
|
|
NOTE:
|
|
1. The sysfs_driver structure obtained upon successful return
|
|
from this function has to be closed by calling
|
|
sysfs_close_driver_by_name().
|
|
2. Bus on which to look for this driver should be known prior
|
|
to calling this function. Use sysfs_find_driver_bus()
|
|
to determine this.
|
|
|
|
Arguments: const unsigned char *drv_name Driver to look for
|
|
const unsigned char *bus Bus on which to search
|
|
size_t bsize Size of "bus"
|
|
|
|
Returns: struct sysfs_driver * with success
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_driver *sysfs_open_driver
|
|
(const unsigned char *drv_name,
|
|
const unsigned char *bus, size_t bsize)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_get_driver_links
|
|
|
|
Description: Function returns a list of links for a given driver
|
|
|
|
Arguments: struct sysfs_driver *driver Driver to get links from
|
|
|
|
Returns: struct dlist * of links on success
|
|
NULL with error
|
|
|
|
Prototype: struct dlist *sysfs_get_driver_links
|
|
(struct sysfs_driver *driver)
|
|
-------------------------------------------------------------------------------
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: sysfs_open_driver_attr
|
|
|
|
Description: Function takes as arguments, the bus the driver is registered
|
|
on, the driver name and the name of the attribute to open.
|
|
|
|
NOTE:
|
|
1. The struct sysfs_attribute * obtained upon successful
|
|
return from this function has to be closed by making
|
|
a call to sysfs_close_attribute()
|
|
|
|
Arguments: unsigned char *bus Bus on which driver is present
|
|
unsigned char *drv Driver to look for
|
|
unsigned char *attrib Name of the attribute to open
|
|
|
|
Returns: struct sysfs_attribute * with success.
|
|
NULL with error. Errno will be set with error, returning
|
|
- EINVAL for invalid arguments
|
|
|
|
Prototype: struct sysfs_attribute *sysfs_open_driver_attr
|
|
(const unsigned char *bus, const unsigned char *drv,
|
|
const unsigned char *attrib)
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
7. Navigating a dlist
|
|
---------------------
|
|
|
|
Libsysfs uses (yet another) list implementation thanks to Eric J Bohm.
|
|
|
|
Some library functions return a dlist of devices/drivers/attributes, etc.
|
|
To navigate the list returned the macro "dlist_for_each_data" is to be used.
|
|
|
|
------------------------------------------------------------------------------
|
|
Function/Macro name: dlist_for_each_data
|
|
|
|
Description: Walk the given list, returning a known data type/
|
|
structure in each iteration.
|
|
|
|
Arguments: struct dlist *list List pointer
|
|
data_iterator Data type/structure variable
|
|
contained in the list
|
|
datatype Data type/structure contained
|
|
in the list
|
|
|
|
Returns: On each iteration, "data_iterator" will contain a list
|
|
element of "datatype"
|
|
|
|
Usage example: The function sysfs_get_classdev_attributes() returns a
|
|
dlist of attributes. To navigate the list:
|
|
|
|
struct sysfs_attribute *attr = NULL;
|
|
struct dlist *attrlist = NULL;
|
|
.
|
|
.
|
|
.
|
|
attrlist = sysfs_get_classdev_attributes
|
|
(struct sysfs_class_device *cdev)
|
|
if (attrlist != NULL) {
|
|
dlist_for_each_data(attrlist, attr,
|
|
struct sysfs_attribute) {
|
|
.
|
|
.
|
|
.
|
|
}
|
|
}
|
|
-------------------------------------------------------------------------------
|
|
|
|
|
|
8. Usage
|
|
--------
|
|
|
|
Accessing devices through libsysfs is supposed to mirror accessing devices
|
|
in the filesystem it represents. Here's a typical order of operation:
|
|
|
|
- get sysfs mount point
|
|
- "open" sysfs category, ie. bus, class, or device
|
|
- work with category
|
|
- "close" sysfs category
|
|
|
|
|
|
9. Conclusion
|
|
-------------
|
|
|
|
Libsysfs is meant to provide a stable application programming interface to
|
|
sysfs. Applications can depend upon the library to access system devices
|
|
and functions exposed through sysfs.
|