move and update libsysfs.txt

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

1 files changed, 0 insertions, 1687 deletions

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