path: root/docs/libsysfs.txt

	System Utilities sysfs Library - libsysfs
	=========================================

Version: 1.2.0 
September 13, 2004

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 Calling Conventions in Libsysfs
   6.2 Utility Functions
   6.3 Filesystem Functions
       6.3.1 Attribute Functions
       6.3.2 Directory Link Functions
       6.3.3 Directory Functions
   6.4 Bus Functions
   6.5 Class Functions
   6.6 Device Functions
   6.7 Driver Functions
7. Dlists
   7.1 Navigating a dlist
   7.2 Custom sorting using dlist_sort_custom()
8. Usage
9. Testsuite
10. 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/

  Udev provides persistent device naming based on a set of user specified
  rules. The rules a device name is based on could one or a combination of a
  number of parameters such as the bus the device is on, the serial number 
  of the device (in case of USB), the vendor name (in case of SCSI) and so
  on. Udev uses Libsysfs to retrieve relevent information to appropriately
  name devices.


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.

A paper on Libsysfs was presented at Linux.Conf.Au 2004 (Adelaide, January
2004). The paper is available online at:

http://oss.software.ibm.com/linux/papers/libsysfs/libsysfs-linuxconfau2004.pdf


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_NAME          "bus"
#define SYSFS_CLASS_NAME        "class"
#define SYSFS_BLOCK_NAME        "block"
#define SYSFS_DEVICES_NAME      "devices"
#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:
     a. As of release 0.4.0 of sysfsutils, 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).
     b. As of release 1.0.0 of sysfsutils, all dlists in the library are
	sorted in alphabetical order. It is now a requirement that the 
	"name" and "path" be the first two elements of all libsysfs
	structures.


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 {
        char name[SYSFS_NAME_LEN];
        char path[SYSFS_PATH_MAX];
        char *value;
        unsigned short len;             /* value length */
        unsigned short method;          /* show and store */
};

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 {
        char name[SYSFS_NAME_LEN];
        char path[SYSFS_PATH_MAX];
        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 {
        char name[SYSFS_NAME_LEN];
        char path[SYSFS_PATH_MAX];

	/* Private: for internal use only */
        struct dlist *subdirs;
        struct dlist *links;
        struct dlist *attributes;
};

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 {
        char name[SYSFS_NAME_LEN];
        char path[SYSFS_PATH_MAX];

        /* Private: for 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,
						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 {
        char name[SYSFS_NAME_LEN];
        char path[SYSFS_PATH_MAX];

        /* Private: 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 {
        char name[SYSFS_NAME_LEN];
        char path[SYSFS_PATH_MAX];
        char classname[SYSFS_NAME_LEN];

        /* Private: 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 {
        char name[SYSFS_NAME_LEN];
        char path[SYSFS_PATH_MAX];

        /* Private: 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 {
        char name[SYSFS_NAME_LEN];
        char path[SYSFS_PATH_MAX];
        char bus_id[SYSFS_NAME_LEN];
        char bus[SYSFS_NAME_LEN];
        char driver_name[SYSFS_NAME_LEN];

        /* Private: 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 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 {
        char name[SYSFS_NAME_LEN];
        char path[SYSFS_PATH_MAX];

        /* Private: 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 Calling Conventions in Libsysfs
-----------------------------------

Libsysfs uses a simple API calling convention. APIs are classified to be 
one of "open", "get", "close" types. The convention is as follows:

	a. All "open" APIs have a corresponding "close" API.
	b. References obtained using "get" calls should not be closed
		explicitly.
	c. All "opened" references have to be closed with a call to
		their corresponding "close" call. This takes care of
		freeing structure references obtained with "get" calls.


6.2 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:	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 or
				if len is zero

Prototype:	sysfs_get_mnt_path(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 char *path	Path to parse name from
		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 char *path, 
					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 char *path	Link's path
		char *target		Buffer to place link's target 
		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 char *path, 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:	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(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:	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(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:	const char *path	Path to verify

Returns:	0 on success, 1 on error
			- EINVAL for invalid arguments

Prototype:	int sysfs_path_is_dir(const char *path)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
Name:		sysfs_path_is_file

Description:	Utility function to verify if a given path is to a file.

Arguments:	const char *path	Path to verify

Returns:	0 on success, 1 on error
			- EINVAL for invalid arguments

Prototype:	int sysfs_path_is_file(const char *path)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
Name:		sysfs_path_is_link

Description:	Utility function to verify if a given path is to a link.

Arguments:	const char *path	Path to verify

Returns:	0 on success, 1 on error
			- EINVAL for invalid arguments

Prototype:	int sysfs_path_is_link(const char *path)
-------------------------------------------------------------------------------


6.3 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.3.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 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 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_dir_attributes

Description:	Given a list sysfs_directory, this function refreshes the list
		of attributes for the given directory.

Arguments:	struct sysfs_directory *sysdir	sysfs_ directory whose 
						attributes list	to refresh

Returns:	0 with success.
		1 with error. Errno will be set on error, returning EINVAL
				for invalid arguments

Prototype:	int sysfs_refresh_dir_attributes(struct sysfs_directory *sysdir)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
Name:		sysfs_get_dir_attributes

Description:	Returns a list of attributes for the given sysfs_directory.

Arguments:	struct sysfs_directory *sysdir	sysfs_directory whose 
						attributes list to return

Returns:	struct dlist * of attributes with 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_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 the
		given 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 char *new_value			sysattr's new value
		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 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 char *attrpath	Attribute path to read
		char *value		Buffer to read in 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 char *attrpath, 
					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 dlist *attr	Attribute list to search through
		const char *name 	Name of attribute whose value
					to retrieve

Returns:	char * attribute value with success.
		NULL with error. Errno will be set with error, returning
			- EINVAL for invalid arguments

Prototype:	char *sysfs_get_value_from_attributes
			(struct sysfs_attribute *attr, const 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
		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, char *attrname)
-------------------------------------------------------------------------------
		

6.3.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 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 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_dir_links

Description:	Returns a list of links for the given sysfs_directory.

Arguments:	struct sysfs_directory *sysdir	sysfs_directory whose 
						list of links to return

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
		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, 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
		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, char *linkname)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
Name:		sysfs_refresh_dir_links

Description:	Given a list sysfs_directory, this function refreshes the list
		of links under the given directory.

Arguments:	struct sysfs_directory *sysdir	sysfs_ directory whose 
						links list to refresh

Returns:	0 with success.
		1 with error. Errno will be set on error, returning EINVAL
				for invalid arguments

Prototype:	int sysfs_refresh_dir_links(struct sysfs_directory *sysdir)
-------------------------------------------------------------------------------


6.3.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 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 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:	0 with success.
		-1 with error. Errno will be set with error, returning
			- EINVAL for invalid arguments

Prototype:	int 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
		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

Prototype:	struct sysfs_directory *sysfs_get_subdirectory
				(struct sysfs_directory *dir, char *subname)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
Name:		sysfs_get_dir_subdirs

Description:	Returns a list of subdirs for the given sysfs_directory.

Arguments:	struct sysfs_directory *sysdir	sysfs_directory whose 
						subdirectories list to return

Returns:	struct dlist * of directories 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_refresh_dir_subdirs

Description:	Given a list sysfs_directory, this function refreshes the list
		of subdirectories under the given directory.

Arguments:	struct sysfs_directory *sysdir	sysfs_ directory whose 
						subdirs list to refresh

Returns:	0 with success.
		1 with error. Errno will be set on error, returning EINVAL
				for invalid arguments

Prototype:	int sysfs_refresh_dir_subdirs(struct sysfs_directory *sysdir)
-------------------------------------------------------------------------------


6.4 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 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 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
		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, 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
		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, 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
		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, char *attrname)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
Name:		sysfs_refresh_bus_attributes

Description:	Function refreshes the list of attributes for a given sysfs_bus

Arguments:	struct sysfs_bus *bus	Bus whose attributes list to refresh

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_find_driver_bus

Description:	Given the name of a driver, this function finds the name of the
		bus the driver is on

Arguments:	const char *driver	Name of the driver to look for
		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 char *driver,
					char *busname, size_t bsize)
-------------------------------------------------------------------------------


6.5 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 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 char *name)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
Name:		sysfs_close_class

Description:	Function closes up the sysfs_class structure including its
		class devices.

Arguments:	sysfs_class *cls	Class structure to close

Prototype:	void sysfs_close_class(struct sysfs_class *cls);
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
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 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 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 *cls		Class on which to search
		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 *cls, 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 char *classname	Class on which to search
		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 char *classname, char *name)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
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 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 char *name)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
Name:		sysfs_refresh_classdev_attributes

Description:	Function refreshes the list of attributes for a given
		sysfs_class_device.

Arguments:	struct sysfs_class_device *cdev	Class device whose attributes 
						list to refresh

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_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:	char *classname		Class name on which to search
		char *dev		Name of the class device
		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 char *classname, const char *dev, 
							const char *attrib)
-------------------------------------------------------------------------------


6.6 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 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 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 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 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_open_device_tree

Description:	Function opens up the device tree at the specified path.

Arguments:	const char *path	Path at which to open the device tree

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_tree(const char *path)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
Name:		sysfs_close_device_tree

Description:	Function closes the device tree originating at the given 
		sysfs_device.

Arguments:	struct sysfs_device *devroot	Device from which the device
						tree has to be closed

Prototype:	void sysfs_close_device_tree(struct sysfs_device *devroot)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
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 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 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_refresh_device_attributes

Description:	Function refreshes the list of attributes for a given
		sysfs_device.

Arguments:	struct sysfs_device *device	Device whose attributes list 
						to refresh

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_refresh_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 char *bus		Bus on which to search
		const char *bus_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_open_device
			(const char *bus, const char *bus_id)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
Name:		sysfs_get_device_bus

Description:	Given a sysfs_device, this function fills in the bus this 
		device is on in the sysfs_device->bus field.

Arguments:	struct sysfs_device *dev	Device whose bus name to find

Returns:	0 with success.
		-1 with error. Errno will be set with error, returning
			- EINVAL for invalid arguments

Prototype:	int sysfs_get_device_bus(struct sysfs_device *dev)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
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:	char *bus		Bus on which to search
		char *bus_id		Device to look for
		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 char *bus, const char *bus_id, const char *attrib)
-------------------------------------------------------------------------------


6.7 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 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 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_refresh_driver_devices

Description:	Function refreshes the list of devices that use this driver.

Arguments:	struct sysfs_driver *driver	Driver whose devices list is
						required to be refreshed

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_refresh_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 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 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 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 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_refresh_driver_attributes

Description:	Function refreshes the list of attributes for a given
		sysfs_driver.

Arguments:	struct sysfs_driver *driver	Driver whose attributes list 
						to refresh

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_refresh_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 char *bus_name	Bus on which to search
		const char *drv_name	Driver name 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_driver *sysfs_open_driver(const char *bus_name,
							const char *drv_name)
-------------------------------------------------------------------------------

-------------------------------------------------------------------------------
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:	char *bus		Bus on which driver is present
		char *drv		Driver to look for
		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 char *bus, const char *drv, const char *attrib)
-------------------------------------------------------------------------------


7 Dlists
--------

Libsysfs uses (yet another) list implementation thanks to Eric J Bohm.


7.1 Navigating a dlist
----------------------

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) {
				.
				.
				.
				}
			}
-------------------------------------------------------------------------------


7.2 Custom sorting using dlist_sort_custom()
--------------------------------------------

As of release 1.2.0, libsysfs provides a new interface for custom sorting
of dlists. The API dlist_sort_custom() has been added for this purpose.
Applications that would like to define their own sorter function can now
make use of this API.

The sorter function must conform to the following prototype:

	int compare(void *a, void*b)

dlist_sort_custom() expects that the compare function will:
	return >0 for a before b
	return <0 for b before a
	return  0 for a == b


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. Testsuite
------------

Version 1.0.0 of sysfsutils ships with a comprehensive testsuite. The testsuite
shipped as part of the "test" directory of the sysfsutils source package,
results in an executable "testlibsysfs" which will be installed in the
/usr/local/bin directory. Some of the salient features of the testsuite are:

a. Tests _every_ API exported by the library.
b. Tests are performed for all possible combinations of input parameters.
c. Detailed output is provided for the correct case.
d. Facility to redirect output of the tests to a normal file.
e. Number of iterations of tests can be specified.

The testsuite comes with its own configuration file "libsysfs.conf" in the
"test" directory. This file is used to generate a header file at the time
the tests are built. 

To use the testsuite:

a. Modify the variables libsysfs.conf file to appropriate values for your
   system. (The libsysfs.conf file contains comments describing what each
   variable stands for and, in some cases, how to determine an appropriate 
   value for the system under test).

b. Build and install the testsuite.

c. Run the testsuite:

	testlibsysfs <number of iterations> <logfile>

The default logfile is stdout.

NOTE: If the libsysfs.conf file is changed, make sure to run "make clean" in 
the test directory and then a "make" for the changes to take effect.


10. 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.