diff options
Diffstat (limited to 'docs/libsysfs.txt')
| -rw-r--r-- | docs/libsysfs.txt | 1687 |
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. |