diff options
Diffstat (limited to 'docs/libsysfs.txt')
| -rw-r--r-- | docs/libsysfs.txt | 1489 |
1 files changed, 1337 insertions, 152 deletions
diff --git a/docs/libsysfs.txt b/docs/libsysfs.txt index c38d74d..c3e3b1f 100644 --- a/docs/libsysfs.txt +++ b/docs/libsysfs.txt @@ -2,8 +2,8 @@ System Utilities sysfs Library - libsysfs ========================================= -Version: 0.1.0 -June 30, 2003 +Version: 1.2.0 +September 13, 2004 Contents -------- @@ -18,26 +18,32 @@ Contents 5.1.3 Directory Structure 5.2 Bus Data Structure 5.3 Class Data Structures - 5.4 Device Data Structure - 5.5 Driver Data Structure + 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. Usage -8. Conclusion + 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 consistant and stable interface for +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 @@ -85,6 +91,13 @@ The library must satisfy the following requirements: 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 ----------- @@ -94,7 +107,7 @@ 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 devided to create a single library interface rather +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. @@ -111,6 +124,11 @@ and files that lie underneath it. To query a device on a PCI bus, one would 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 ------------------ @@ -126,11 +144,10 @@ and devices, here's some examples: #define SYSFS_FSTYPE_NAME "sysfs" #define SYSFS_PROC_MNTS "/proc/mounts" -#define SYSFS_BUS_DIR "/bus" -#define SYSFS_CLASS_DIR "/class" -#define SYSFS_DEVICES_DIR "/devices" +#define SYSFS_BUS_NAME "bus" +#define SYSFS_CLASS_NAME "class" +#define SYSFS_BLOCK_NAME "block" #define SYSFS_DEVICES_NAME "devices" -#define SYSFS_DRIVERS_DIR "/drivers" #define SYSFS_DRIVERS_NAME "drivers" #define SYSFS_NAME_ATTRIBUTE "name" @@ -142,6 +159,18 @@ path length: #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 ------------------------------------------- @@ -157,16 +186,17 @@ 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 { - struct sysfs_attribute *next; + char name[SYSFS_NAME_LEN]; char path[SYSFS_PATH_MAX]; char *value; - int method; /* show and store */ + unsigned short len; /* value length */ + unsigned short method; /* show and store */ }; -The library links attributes together using the "next" pointer. Path -represents the file/attribute's full path. Value is used when reading -from or writing to an attribute. Method is a bitmask for defining if -the attribute supports show(read) and/or store(write). +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 @@ -176,13 +206,13 @@ Symbolic links are used in sysfs to link bus or class views with particular devices. struct sysfs_link { - struct sysfs_link *next; char name[SYSFS_NAME_LEN]; - char target[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + char target[SYSFS_PATH_MAX]; }; -The "next" pointer is for linking links together. Link's name is stored -in name and it's target stored in target. +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 @@ -191,16 +221,20 @@ in name and it's target stored in target. The directory structure represents a sysfs directory: struct sysfs_directory { - struct sysfs_directory *next; + char name[SYSFS_NAME_LEN]; char path[SYSFS_PATH_MAX]; - struct sysfs_directory *subdirs; - struct sysfs_link *links; - struct sysfs_attribute *attributes; + + /* Private: for internal use only */ + struct dlist *subdirs; + struct dlist *links; + struct dlist *attributes; }; -The directory structure includes a "next" pointer for linking directories -together. It also includes the directory's full path and links to -subdirectories, links, and 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 @@ -210,19 +244,26 @@ 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 { - struct sysfs_bus *next; 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; - struct sysfs_driver *drivers; - struct sysfs_device *devices; }; -The "next" pointer, as with other structures, is used for linking buses -together. The bus name, like "pci" or "usb", is stored in the name field. -The bus' directory is represented by the sysfs_directory structure and -it contains references to all the subdirectories, links, and attributes -associated with the bus. Finally, the bus contains lists of those -devices on the bus and their drivers. +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 @@ -233,67 +274,117 @@ 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 { - struct sysfs_class *next; char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + + /* Private: for internal use only */ + struct dlist *devices; struct sysfs_directory *directory; - struct sysfs_class_device *devices; }; -The sysfs_class represents device classes in sysfs like "net". It contains -a "next" pointer for list management, the class name, and the directory -representation. Finally, it contains a linked list of class devices. +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 { - struct sysfs_class_device *next; char name[SYSFS_NAME_LEN]; - struct sysfs_directory *directory; + 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 a "next" -pointer for list management, the name of the class device - like "eth0", -its sysfs directory information including links and attributes, and -finally the sysfs_device reference and that device's driver reference. +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 Device Data Structure +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 { - struct sysfs_device *next; char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; char bus_id[SYSFS_NAME_LEN]; - struct sysfs_driver *driver; + 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; - struct sysfs_device *children; }; -The sysfs_device structure contains a "next" pointer for linking a list -of devices together, its name as read from the "name" attribute in the -device's directory, its bus id - which is the name of device's directory, -and a reference to its driver. The device structure also contains a -directory structure, which contains a list of the device's attributes, -and a list of its child devices, if it has any. +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.5 Driver Data Structure + +5.6 Driver Data Structure ------------------------- The sysfs_driver structure represents a device driver. struct sysfs_driver { - struct sysfs_driver *next; char name[SYSFS_NAME_LEN]; + char path[SYSFS_PATH_MAX]; + + /* Private: for internal use only */ + struct dlist *devices; struct sysfs_directory *directory; }; -It contains a "next" pointer, the name of the driver, and its directory -information, which includes the driver's attributes. +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 @@ -305,7 +396,21 @@ using "open" and "close". Open returns a structure and close is used to clean that structure up. -6.1 Utility Functions +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. @@ -315,12 +420,13 @@ Name: sysfs_get_mnt_path Description: Function finds the mount path for filesystem type "sysfs". -Arguments: chat *mnt_path Mount path buffer +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. + - EINVAL for invalid argument, if buffer is NULL or + if len is zero Prototype: sysfs_get_mnt_path(char *mnt_path, size_t len); ------------------------------------------------------------------------------- @@ -331,7 +437,7 @@ Name: sysfs_get_name_from_path Description: Function returns the last directory or file name from the included path. -Arguments: char *path Path to parse name from +Arguments: const char *path Path to parse name from char *name Buffer to put parsed name into size_t *len Size of name buffer @@ -339,18 +445,18 @@ 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(char *path, char *name, - size_t *len) +Prototype: int sysfs_get_name_from_path(const char *path, + char *name, size_t *len) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- Name: sysfs_get_link -Description: Sysfs realink function, reads the link at supplied path +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 path + char *target Buffer to place link's target size_t len Size of target buffer Returns: 0 with success @@ -360,21 +466,104 @@ Returns: 0 with success 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 -6.2 Filesystem Functions +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.2.1 Attribute Functions + +6.3.1 Attribute Functions ------------------------- Along with the usual open, read, and close functions, libsysfs provides -a couple other functions for accessing attribute values. Specific -functions to write attributes or attribute values will be added in the -near future. +a couple other functions for accessing attribute values. ------------------------------------------------------------------------------- Name: sysfs_open_attribute @@ -382,13 +571,13 @@ 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: char *path File/Attribute's path +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(char *path) +Prototype: struct sysfs_attribute *sysfs_open_attribute(const char *path) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- @@ -402,6 +591,54 @@ 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 @@ -409,7 +646,7 @@ Description: Reads the supplied attribute. Since the maximum transfer 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 +Arguments: struct sysfs_attribute *sysattr Attribute to read Returns: 0 with success. -1 with error. Errno will be set with error, returning @@ -419,21 +656,43 @@ 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: char *attrpath Attribute path to read - char *value Buffer to place attribute's value +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(char *attrpath, char *value, - size_t vsize) +Prototype: int sysfs_read_attribute_value(const char *attrpath, + char *value, size_t vsize) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- @@ -443,20 +702,38 @@ 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 - char *name Name of attribute to return value +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, char * name) + (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 -6.2.2 Link Functions +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 @@ -470,13 +747,13 @@ Name: sysfs_open_link Description: Opens a directory link. -Arguments: char *linkpath Path to 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(char *linkpath) +Prototype: struct sysfs_link *sysfs_open_link(const char *linkpath) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- @@ -484,13 +761,97 @@ Name: sysfs_close_link Description: Closes a directory link structure. -Arguments: struct sysfs_link *ln Link to close +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) +------------------------------------------------------------------------------- -6.2.3 Directory Functions +------------------------------------------------------------------------------- +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 @@ -505,13 +866,13 @@ Name: sysfs_open_directory Description: Opens a sysfs directory at a specific path -Arguments: char *path Directory path to open +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(char *path) +Prototype: struct sysfs_directory *sysfs_open_directory(const char *path) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- @@ -526,6 +887,22 @@ Prototype: void sysfs_close_directory(struct sysfs_directory *sysdir) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- +Name: sysfs_read_dir_subdirs + +Description: Reads the given sysfs_directory to create a list of subdirs. + +Arguments: struct sysfs_directory *sysdir sysfs_directory whose + subdirs have to be read + +Returns: 0 with success. + -1 with error. Errno will be set with error, returning + - EINVAL for invalid arguments + +Prototype: int sysfs_read_dir_subdirs + (struct sysfs_directory *sysdir) +------------------------------------------------------------------------------- + +------------------------------------------------------------------------------- Name: sysfs_read_directory Description: Read the supplied directory. Reading fills in the directory's @@ -540,15 +917,80 @@ Returns: 0 with success. 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.3 Bus Functions +6.4 Bus Functions ----------------- -The library provides a couple 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. +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 @@ -557,13 +999,13 @@ 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: char *name Bus name to open, like "pci".... +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(char *name) +Prototype: struct sysfs_bus *sysfs_open_bus(const char *name) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- @@ -574,16 +1016,153 @@ Description: Function closes up the sysfs_bus structure including its Arguments: sysfs_bus *bus Bus structure to close -Prototype: void sysfs_close_bus(struct sysfs_bus *bus); +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) +------------------------------------------------------------------------------- -6.4 Class Functions +------------------------------------------------------------------------------- +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. +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 @@ -592,13 +1171,13 @@ 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: char *name Class name to open, like "net".... +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(char *name) +Prototype: struct sysfs_class *sysfs_open_class(const char *name) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- @@ -607,25 +1186,26 @@ Name: sysfs_close_class Description: Function closes up the sysfs_class structure including its class devices. -Arguments: sysfs_class *class Class structure to close +Arguments: sysfs_class *cls Class structure to close -Prototype: void sysfs_close_class(struct sysfs_class *class); +Prototype: void sysfs_close_class(struct sysfs_class *cls); ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- -Name: sysfs_open_class_device +Name: sysfs_open_class_device_path Description: Function opens up one of the class devices represented in - sysfs in sysfs/class/"class"/ directory. It retunrs a + sysfs in sysfs/class/"class"/ directory. It returns a sysfs_class_device structure. -Arguments: char *path Path to class device +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(char *path) +Prototype: struct sysfs_class_device *sysfs_open_class_device_path + (const char *path) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- @@ -638,30 +1218,218 @@ 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. -6.5 Device Functions +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 tree functions. The -tree functions recursively open or close a device and all of its -children. +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 +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: char *path Path to device +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(char *path) +Prototype: struct sysfs_device *sysfs_open_device_path(const char *path) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- @@ -669,36 +1437,95 @@ Name: sysfs_close_device Description: Function closes up the sysfs_device structure. -Arguments: sysfs_device *dev Device structure to close +Arguments: sysfs_device *dev Device structure to close Prototype: void sysfs_close_device(struct sysfs_device *dev) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- -Name: sysfs_open_device_tree +Name: sysfs_open_root_device -Description: Same as sysfs_open_device except it recursively opens - children devices and adds them to the tree. Returns root - tree. +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: char *path Path to device +Arguments: const char *name Name of the root device to open -Returns: struct sysfs_device * with success +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_device_tree(char *path) +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: Same as sysfs_close_device except it recursively closes - all child devices. +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) +------------------------------------------------------------------------------- -Arguments: sysfs_device *dev Root device structure to close +------------------------------------------------------------------------------- +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 -Prototype: void sysfs_close_device_tree(struct sysfs_device *dev) +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) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- @@ -708,34 +1535,126 @@ Description: Searches supplied device's attributes by name and returns the attribute. Arguments: struct sysfs_device *dev Device to search - char *name Attribute name to find + 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, char *name) + (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.6 Driver Functions +6.7 Driver Functions -------------------- -Libsysfs includes two functions - open and close - for drivers. +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 +Name: sysfs_open_driver_path Description: Opens driver at specific path. -Arguments: char *path Path to driver +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(char *path) +Prototype: struct sysfs_driver *sysfs_open_driver_path(const char *path) ------------------------------------------------------------------------------- ------------------------------------------------------------------------------- @@ -748,8 +1667,237 @@ 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. -7. Usage +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 @@ -761,8 +1909,45 @@ in the filesystem it represents. Here's a typical order of operation: - "close" sysfs category -8. Conclusion -------------- +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 |