move and update libsysfs.txt

Signed-off-by: Kay Sievers <kay.sievers@suse.de>

1 files changed, 1954 insertions, 0 deletions

diff --git a/libsysfs/libsysfs.txt b/libsysfs/libsysfs.txt
new file mode 100644
index 0000000000..b877cb8030
--- /dev/null
+++ b/libsysfs/libsysfs.txt
@@ -0,0 +1,1954 @@
+
+	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:	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
+		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.