2 System Utilities sysfs Library - libsysfs
3 =========================================
15 5.1 Directory and Attribute Data Structures
16 5.1.1 Attribute Structure
18 5.1.3 Directory Structure
19 5.2 Bus Data Structure
20 5.3 Class Data Structures
21 5.4 Root Device Data Structure
22 5.5 Device Data Structure
23 5.6 Driver Data Structure
26 6.2 Filesystem Functions
27 6.2.1 Attribute Functions
28 6.2.2 Directory Link Functions
29 6.2.3 Directory Functions
42 Libsysfs' purpose is to provide a consistent and stable interface for
43 querying system device information exposed through the sysfs filesystem.
44 The library implements functions for querying filesystem information,
45 such as reading directories and files. It also contains routines for
46 working with buses, classes, and the device tree.
52 The library must satisfy the following requirements:
54 - It must provide a stable programming interfaces that applications can
57 - It must provide functions to retrieve device Vital Product Data (VPD)
58 information for Error Log Analysis (ELA) support. ELA will provide
59 device driver and device bus address information.
61 - It must provide access to all system devices and information exposed
64 - It must provide a function to find sysfs' current mount point.
66 - It must provide a function for udev to retrieve a device's major and
73 - sysfs: Sysfs is a virtual filesystem in 2.5+ Linux kernels that
74 presents a hierarchical representation of all system physical and
75 virtual devices. It presents system devices by bus, by class, and
76 by topology. Callbacks to device drivers are exposed as files in
77 device directories. Sysfs, for all purposes, is our tree of system
78 devices. For more information, please see:
80 http://www.kernel.org/pub/linux/kernel/people/mochel/doc/
82 - udev: Udev is Greg Kroah-Hartman's User Space implementation of devfs.
83 Udev creates /dev nodes for devices upon Hotplug events. The Hotplug
84 event provides udev with a sysfs directory location of the device. Udev
85 must use that directory to grab device's major and minor number, which it
86 will use to create the /dev node. For more information, please see:
88 http://www.kernel.org/pub/linux/utils/kernel/hotplug/
94 Libsysfs grew from a common need. There are several applications under
95 development that need access to sysfs and system devices. Udev, on a
96 hotplug event, must take a sysfs device path and create a /dev node. Our
97 diagnostic client needs to list all system devices. Finally, our Error
98 Log Analysis piece is required to retrieve VPD information for a
99 failing device. We divided to create a single library interface rather
100 than having these separate applications create their own accesses to
101 sysfs involving reading directories and files.
103 Libsysfs will also provide stability for applications to be built upon. Sysfs
104 currently doesn't enforce any standards for callback or file names. File
105 names change depending on bus or class. Sysfs is also changing, it is
106 currently being developed. Libsysfs will provide a stable interface to
107 applications while allowing sysfs to change underneath it.
109 Like sysfs, the library will provide devices to applications by bus, by
110 class, and by topology. The library will function similar to directories
111 and files that lie underneath it. To query a device on a PCI bus, one would
112 "open" the bus to scan or read devices and "close" the bus when
113 completed. Besides supplying functions to retrieve devices, the library
114 will also provide some utility functions like getting sysfs mount point.
120 Libsysfs will classify system devices following sysfs' example, dividing
121 them by bus, class, and devices. The library presents this information
122 generically. It doesn't, for example, differentiate between PCI and USB
123 buses. Device attributes are presented with values as they are exposed
124 by sysfs, the values are not formatted.
126 The library will provide standard definitions for working with sysfs
127 and devices, here's some examples:
129 #define SYSFS_FSTYPE_NAME "sysfs"
130 #define SYSFS_PROC_MNTS "/proc/mounts"
131 #define SYSFS_BUS_DIR "/bus"
132 #define SYSFS_BUS_NAME "bus"
133 #define SYSFS_CLASS_DIR "/class"
134 #define SYSFS_CLASS_DIR "/class"
135 #define SYSFS_BLOCK_DIR "/block"
136 #define SYSFS_BLOCK_NAME "block"
137 #define SYSFS_DEVICES_DIR "/devices"
138 #define SYSFS_DEVICES_NAME "devices"
139 #define SYSFS_DRIVERS_DIR "/drivers"
140 #define SYSFS_DRIVERS_NAME "drivers"
141 #define SYSFS_NAME_ATTRIBUTE "name"
143 The library uses some definitions to mark maximum size of a sysfs name or
146 #define SYSFS_PATH_MAX 255
147 #define SYSFS_NAME_LEN 50
148 #define SYSFS_BUS_ID_SIZE 20
152 As of release 0.4.0 of libsysfs, a number of changes have been made
153 so that the dlists and "directory" references in all libsysfs's
154 structures are not populated until such time that it is absolutely
155 necessary. Hence, these elements may not contain valid data at all
156 times (as was the case before).
158 5.1 Directory and Attribute Data Structures
159 -------------------------------------------
161 The library implements structures to represent sysfs directories, links,
165 5.1.1 Attribute Structure
166 -------------------------
168 A file in sysfs represents a device or driver attribute. Attributes can be
169 read only, write only, or read and write. File data can be ASCII and
170 binary. The library has the following structure to represent files:
172 struct sysfs_attribute {
173 unsigned char *value;
174 unsigned short len; /* value length */
175 unsigned short method; /* show and store */
176 unsigned char name[SYSFS_NAME_LEN];
177 unsigned char path[SYSFS_PATH_MAX];
180 Path represents the file/attribute's full path. Value is used when reading
181 from or writing to an attribute. "len" is the length of data in "value".
182 Method is a bitmask for defining if the attribute supports show(read)
189 Symbolic links are used in sysfs to link bus or class views with
193 unsigned char name[SYSFS_NAME_LEN];
194 unsigned char path[SYSFS_PATH_MAX];
195 unsigned char target[SYSFS_PATH_MAX];
198 Link's name is stored in "name' and it's target stored in "target". Absolute
199 path to the link is stored in "path".
202 5.1.3 Directory Structure
203 -------------------------
205 The directory structure represents a sysfs directory:
207 struct sysfs_directory {
208 struct dlist *subdirs;
210 struct dlist *attributes;
211 unsigned char name[SYSFS_NAME_LEN];
212 unsigned char path[SYSFS_PATH_MAX];
215 The sysfs_directory structure includes the list of subdirectories, links and
216 attributes. The "name" and absolute "path" are also stored in the structure.
217 The sysfs_directory structure is intended for use internal to the library.
218 Applications needing access to attributes and links from the directory
219 will need to make appropriate calls (described below) to get the same.
222 5.2 Bus Data Structure
223 ----------------------
225 All buses look similar in sysfs including lists of devices and drivers,
226 therefore we use the following structure to represent all sysfs buses:
229 unsigned char name[SYSFS_NAME_LEN];
230 unsigned char path[SYSFS_PATH_MAX];
232 /* internal use only */
233 struct dlist *drivers;
234 struct dlist *devices;
235 struct sysfs_directory *directory;
238 The sysfs_bus structure contains the bus "name", while the "path" to bus
239 directory is also stored. It also contains lists of devices on the bus
240 and drivers that are registered on it. The bus' directory is represented
241 by the sysfs_directory structure and it contains references to all the
242 subdirectories, links, and attributes. The sysfs_directory structure
243 is for internal use only. The following functions may be used by
244 applications to retrieve data from the sysfs_directory structure:
246 struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus)
247 struct sysfs_attribute *sysfs_get_bus_attribute(struct sysfs_bus *bus,
248 unsigned char *attrname)
251 5.3 Class Data Structures
252 -------------------------
254 The library uses two data structures to represent classes in sysfs. Sysfs
255 classes contains a class directory like "net" or "scsi_host" and then
256 class devices like "eth0", "lo", or "eth1" for the "net" class.
259 unsigned char name[SYSFS_NAME_LEN];
260 unsigned char path[SYSFS_PATH_MAX];
262 /* for internal use only */
263 struct dlist *devices;
264 struct sysfs_directory *directory;
267 The sysfs_class represents device classes in sysfs like "net". It contains
268 the class "name", "path" to the class, a list of class devices and the
269 directory representation (for internal use only).
271 struct sysfs_class_device {
272 unsigned char name[SYSFS_NAME_LEN];
273 unsigned char classname[SYSFS_NAME_LEN];
274 unsigned char path[SYSFS_PATH_MAX];
276 /* for internal use only */
277 struct sysfs_class_device *parent;
278 struct sysfs_device *sysdevice; /* NULL if virtual */
279 struct sysfs_driver *driver; /* NULL if not implemented */
280 struct sysfs_directory *directory;
283 A class device isn't the same as a sysfs_device, it's specific to the class in
284 which it belongs. The class device structure contains the name of the class
285 the class device belongs to, its sysfs_device reference and that device's
286 driver reference (if any). It also contains the name of the class device
287 - like "eth0", its parent point (if present) and its sysfs directory
288 information including links and attributes (for internal use only).
289 The following function may be used by applications to retrieve data
290 from the sysfs_directory structure:
292 struct dlist *sysfs_get_classdev_attributes(struct sysfs_class_device *cdev);
295 5.4 Root Device Data Structure
296 ------------------------------
298 Device hierarchies in sysfs are represented under the /sys/devices directory
299 structure. Sysfs devices typically spawn off from base devices which are
300 represented by a sysfs_root_device.
302 struct sysfs_root_device {
303 unsigned char name[SYSFS_NAME_LEN];
304 unsigned char path[SYSFS_PATH_MAX];
306 /* for internal use only */
307 struct dlist *devices;
308 struct sysfs_directory *directory;
311 The sysfs_root_device structure contains a list of "devices" that spawn off it.
312 The name of the root device as represented under /sys/devices is read into
313 "name" and the absolute path into "path" and its sysfs_directory information
314 intended to be used internal to the library.
317 5.5 Device Data Structure
318 -------------------------
320 The sysfs_device structure represents a system device that's exposed
321 in sysfs under the /sys/devices directory structure.
323 struct sysfs_device {
324 unsigned char name[SYSFS_NAME_LEN];
325 unsigned char bus_id[SYSFS_NAME_LEN];
326 unsigned char bus[SYSFS_NAME_LEN];
327 unsigned char driver_name[SYSFS_NAME_LEN];
328 unsigned char path[SYSFS_PATH_MAX];
330 /* for internal use only */
331 struct sysfs_device *parent;
332 struct dlist *children;
333 struct sysfs_directory *directory;
336 The sysfs_device structure contains a "parent" pointer, a list of child
337 devices, if any, device's directory, its bus id - which is the name of
338 device's directory, the bus name on which this device is registered and
339 its driver name. The device structure also contains the absolute path
340 to the device and a directory structure, which contains a list of the
341 device's attributes (for internal use only). The following functions
342 may be used to obtain information from sysfs_directory structure:
344 struct sysfs_attribute *sysfs_get_device_attribute(struct sysfs_device *dev,
345 const unsigned char *name)
346 struct dlist *sysfs_get_device_attributes(struct sysfs_device *device)
349 5.6 Driver Data Structure
350 -------------------------
352 The sysfs_driver structure represents a device driver.
354 struct sysfs_driver {
355 unsigned char name[SYSFS_NAME_LEN];
356 unsigned char path[SYSFS_PATH_MAX];
358 /* for internal use only */
359 struct dlist *devices;
360 struct sysfs_directory *directory;
363 The sysfs_driver structure contains a list of devices that use this driver,
364 the name of the driver, its path, and its directory information, which
365 includes the driver's attributes (for internal use only). The following
366 function may be used to retrieve driver attribute information from the
367 sysfs_directory structure:
369 struct dlist *sysfs_get_driver_attributes(struct sysfs_driver *driver)
375 Libsysfs will provide functions to access system devices by bus, by class,
376 and by device. Functions will act like accessing directories and files,
377 using "open" and "close". Open returns a structure and close is used
378 to clean that structure up.
381 6.1 Utility Functions
382 ---------------------
384 The library will provide a few utility functions for working with sysfs.
386 -------------------------------------------------------------------------------
387 Name: sysfs_get_mnt_path
389 Description: Function finds the mount path for filesystem type "sysfs".
391 Arguments: unsigned char *mnt_path Mount path buffer
392 size_t len Size of mount path buffer
394 Returns: Zero with success.
395 -1 with error. Errno will be set with error:
396 - EINVAL for invalid argument, if buffer is NULL.
398 Prototype: sysfs_get_mnt_path(unsigned char *mnt_path, size_t len);
399 -------------------------------------------------------------------------------
401 -------------------------------------------------------------------------------
402 Name: sysfs_get_name_from_path
404 Description: Function returns the last directory or file name from the
407 Arguments: const unsigned char *path Path to parse name from
408 unsigned char *name Buffer to put parsed name into
409 size_t *len Size of name buffer
411 Returns: 0 with success.
412 -1 on Error. Errno will be set with error, returning
413 - EINVAL for invalid arguments
415 Prototype: int sysfs_get_name_from_path(const unsigned char *path,
416 unsigned char *name, size_t *len)
417 -------------------------------------------------------------------------------
419 -------------------------------------------------------------------------------
422 Description: Sysfs readlink function, reads the link at supplied path
423 and returns its target path.
425 Arguments: const unsigned char *path Link's path
426 unsigned char *target Buffer to place link's target path
427 size_t len Size of target buffer
429 Returns: 0 with success
430 -1 with error. Errno will be set with error, returning
431 - EINVAL for invalid arguments
433 Prototype: int sysfs_get_link(const unsigned char *path,
434 unsigned char *target, size_t len)
435 -------------------------------------------------------------------------------
437 -------------------------------------------------------------------------------
438 Name: sysfs_open_subsystem_list
440 Description: Function returns the list of entries for the given subsystem. If
441 the argument is "bus", this function will return a list of buses
442 ("pci", "scsi", etc) supported on the system.
444 sysfs_close_list() has to be called to free the list obtained
447 Arguments: unsigned char *name Subsystem to open, like "bus"..
449 Returns: dlist of entries for the subsystem on success
450 NULL with error indicating the "name" subsystem is invalid.
452 Prototype: struct dlist *sysfs_open_subsystem_list(unsigned char *name)
453 -------------------------------------------------------------------------------
455 -------------------------------------------------------------------------------
456 Name: sysfs_open_bus_devices_list
458 Description: Function returns the list of devices on the given bus.
460 sysfs_close_list() has to be called to free the list obtained
463 Arguments: unsigned char *name Bus name to open "pci"/"scsi"/"usb"..
465 Returns: dlist of device names for the given bus on success
466 NULL with error indicating the bus is not supported.
468 Prototype: struct dlist *sysfs_open_bus_devices_list(unsigned char *name)
469 -------------------------------------------------------------------------------
471 -------------------------------------------------------------------------------
472 Name: sysfs_close_list
474 Description: Closes a given dlist. This can be used as a generic list close
477 Arguments: struct dlist *list List to be closed
479 Prototype: void sysfs_close_list(struct dlist *list)
480 -------------------------------------------------------------------------------
482 -------------------------------------------------------------------------------
483 Name: sysfs_path_is_dir
485 Description: Utility function to verify if a given path is to a directory.
487 Arguments: unsigned char *path Path to verify
489 Returns: 0 on success, 1 on error
490 - EINVAL for invalid arguments
492 Prototype: int sysfs_path_is_dir(unsigned char *path)
493 -------------------------------------------------------------------------------
495 -------------------------------------------------------------------------------
496 Name: sysfs_path_is_file
498 Description: Utility function to verify if a given path is to a file.
500 Arguments: unsigned char *path Path to verify
502 Returns: 0 on success, 1 on error
503 - EINVAL for invalid arguments
505 Prototype: int sysfs_path_is_file(unsigned char *path)
506 -------------------------------------------------------------------------------
508 -------------------------------------------------------------------------------
509 Name: sysfs_path_is_link
511 Description: Utility function to verify if a given path is to a link.
513 Arguments: unsigned char *path Path to verify
515 Returns: 0 on success, 1 on error
516 - EINVAL for invalid arguments
518 Prototype: int sysfs_path_is_link(unsigned char *path)
519 -------------------------------------------------------------------------------
521 6.2 Filesystem Functions
522 ------------------------
524 Libsysfs provides a set of functions to open, read, and close directories
525 and attributes/files in sysfs. These functions mirror their filesystem
526 function counterparts.
528 6.2.1 Attribute Functions
529 -------------------------
531 Along with the usual open, read, and close functions, libsysfs provides
532 a couple other functions for accessing attribute values.
534 -------------------------------------------------------------------------------
535 Name: sysfs_open_attribute
537 Description: Opens up a file in sysfs and creates a sysfs_attribute
538 structure. File isn't read with this function.
540 Arguments: const unsigned char *path File/Attribute's path
542 Returns: struct sysfs_attribute * with success.
543 NULL with error. Errno will be set with error, returning
544 - EINVAL for invalid arguments
546 Prototype: struct sysfs_attribute *sysfs_open_attribute
547 (const unsigned char *path)
548 -------------------------------------------------------------------------------
550 -------------------------------------------------------------------------------
551 Name: sysfs_close_attribute
553 Description: Cleans up and closes sysfs_attribute structure.
555 Arguments: struct sysfs_attribute *sysattr Attribute to close
557 Prototype: void sysfs_close_attribute(struct sysfs_attribute *sysattr)
558 -------------------------------------------------------------------------------
560 -------------------------------------------------------------------------------
561 Name: sysfs_read_dir_attributes
563 Description: Reads the given sysfs_directory to create a list of attributes.
565 Arguments: struct sysfs_directory *sysdir sysfs_directory whose
568 Returns: struct dlist * of attributes on success
569 NULL with error. Errno will be set on error, returning EINVAL
570 for invalid arguments
572 Prototype: struct dlist *sysfs_read_dir_attributes
573 (struct sysfs_directory *sysdir)
574 -------------------------------------------------------------------------------
576 -------------------------------------------------------------------------------
577 Name: sysfs_refresh_attributes
579 Description: Given a list of attributes, this function refreshes the values
580 of attributes in the list.
582 Arguments: struct dlist *attrlist list of attributes to refresh
584 Returns: 0 with success.
585 1 with error. Errno will be set on error, returning EINVAL
586 for invalid arguments
588 Prototype: int sysfs_refresh_attributes(struct dlist *attrlist)
589 -------------------------------------------------------------------------------
591 -------------------------------------------------------------------------------
592 Name: sysfs_read_attribute
594 Description: Reads the supplied attribute. Since the maximum transfer
595 from a sysfs attribute is a pagesize, function reads in
596 up to a page from the file and stores it in the "value"
597 field in the attribute.
599 Arguments: struct sysfs_attribute *sysattr Attribute to read
601 Returns: 0 with success.
602 -1 with error. Errno will be set with error, returning
603 - EINVAL for invalid arguments
605 Prototype: int sysfs_read_attribute(struct sysfs_attribute *sysattr)
606 -------------------------------------------------------------------------------
608 -------------------------------------------------------------------------------
609 Name: sysfs_write_attribute
611 Description: Writes to the supplied attribute. Function validates if attribute
612 is writable, and writes the new value to the attribute. Value to
613 write as well as its length is user supplied. In case the length
614 written is not equal to the length requested to be written, the
615 original value is restored and an error is returned.
617 Arguments: struct sysfs_attribute *sysattr Attribute to write to
618 const unsigned char *new_value New value for the attribute
619 size_t len Length of "new_value"
621 Returns: 0 with success.
622 -1 with error. Errno will be set with error, returning
623 - EINVAL for invalid arguments
625 Prototype: int sysfs_write_attribute(struct sysfs_attribute *sysattr,
626 const unsigned char *new_value, size_t len)
627 -------------------------------------------------------------------------------
629 -------------------------------------------------------------------------------
630 Name: sysfs_read_attribute_value
632 Description: Given a path to a specific attribute, function reads and
633 returns its value to the supplied value buffer.
635 Arguments: const unsigned char *attrpath Attribute path to read
636 unsigned char *value Buffer to place attribute's value
637 size_t vsize Size of buffer
639 Returns: 0 with success.
640 -1 with error. Errno will be set with error, returning
641 - EINVAL for invalid arguments
643 Prototype: int sysfs_read_attribute_value(const unsigned char *attrpath,
644 unsigned char *value, size_t vsize)
645 -------------------------------------------------------------------------------
647 -------------------------------------------------------------------------------
648 Name: sysfs_get_value_from_attributes
650 Description: Function takes a single or linked list of sysfs attribute
651 structures and returns the value of the specified attribute
654 Arguments: struct sysfs_attribute *attr
655 Attribute list to search through
656 const unsigned char *name Name of attribute to return value
658 Returns: unsigned char * attribute value with success.
659 NULL with error. Errno will be set with error, returning
660 - EINVAL for invalid arguments
662 Prototype: unsigned char *sysfs_get_value_from_attributes
663 (struct sysfs_attribute *attr, const unsigned char * name)
664 -------------------------------------------------------------------------------
666 -------------------------------------------------------------------------------
667 Name: sysfs_get_directory_attribute
669 Description: Function walks the list of attributes for the given sysfs
670 directory and returns the sysfs_attribute structure for
671 the specified attribute name.
673 Arguments: struct sysfs_directory *dir Directory in which to search
674 unsigned char *attrname Attribute name to look for
676 Returns: struct sysfs_attribute on success.
677 NULL with error. Errno will be set with error, returning
678 - EINVAL for invalid arguments
680 Prototype: struct sysfs_attribute *sysfs_get_directory_attribute
681 (struct sysfs_directory *dir, unsigned char *attrname)
682 -------------------------------------------------------------------------------
688 Sysfs contains many symbolic links, like bus links to bus devices. Libsysfs
689 treats links differently than directories due to processing differences. A
690 link in the /sys/bus/"busname"/devices/ directory indicates a device in the
691 /sys/devices directory. Through links we give the functionality to know
692 what is and what isn't a link and the ability to query the links target.
694 -------------------------------------------------------------------------------
695 Name: sysfs_open_link
697 Description: Opens a directory link.
699 Arguments: const unsigned char *linkpath Path to link
701 Returns: struct sysfs_link * with success.
702 NULL with error. Errno will be set with error, returning
703 - EINVAL for invalid arguments
705 Prototype: struct sysfs_link *sysfs_open_link
706 (const unsigned char *linkpath)
707 -------------------------------------------------------------------------------
709 -------------------------------------------------------------------------------
710 Name: sysfs_close_link
712 Description: Closes a directory link structure.
714 Arguments: struct sysfs_link *ln Link to close
716 Prototype: void sysfs_close_link(struct sysfs_link *ln)
717 -------------------------------------------------------------------------------
719 -------------------------------------------------------------------------------
720 Name: sysfs_read_dir_links
722 Description: Reads the given sysfs_directory to create a list of links.
724 Arguments: struct sysfs_directory *sysdir sysfs_directory whose
727 Returns: struct dlist * of links with success
728 NULL with error. Errno will be set on error, returning EINVAL
729 for invalid arguments
731 Prototype: struct dlist *sysfs_read_dir_links
732 (struct sysfs_directory *sysdir)
733 -------------------------------------------------------------------------------
735 -------------------------------------------------------------------------------
736 Name: sysfs_get_directory_link
738 Description: Function walks the list of links for the given sysfs directory
739 and returns the sysfs_link structure for the specified link
742 Arguments: struct sysfs_directory *dir Directory in which to search
743 unsigned char *linkname Link name to look for
745 Returns: struct sysfs_link * with success.
746 NULL with error. Errno will be set with error, returning
747 - EINVAL for invalid arguments
749 Prototype: struct sysfs_link *sysfs_get_directory_link
750 (struct sysfs_directory *dir, unsigned char *linkname)
751 -------------------------------------------------------------------------------
753 -------------------------------------------------------------------------------
754 Name: sysfs_get_subdirectory_link
756 Description: Function walks the list of links for the given sysfs directory
757 and its subdirectories returns the sysfs_link structure for
758 the specified link name.
760 Arguments: struct sysfs_directory *dir Directory in which to search
761 unsigned char *linkname Link name to look for
763 Returns: struct sysfs_link * with success.
764 NULL with error. Errno will be set with error, returning
765 - EINVAL for invalid arguments
767 Prototype: struct sysfs_link *sysfs_get_subdirectory_link
768 (struct sysfs_directory *dir, unsigned char *linkname)
769 -------------------------------------------------------------------------------
772 6.2.3 Directory Functions
773 -------------------------
775 Sysfs directories can represent every directory under sysfs. The structures
776 keep track of subdirectories, links, and files. Like opendir, readdir, and
777 closedir, libsysfs provides open, read, and close functions for working with
778 sysfs directories. Open creates the sysfs_directory structure. Read reads in
779 its contents - like subdirectories, links, and files. Close cleans it all
782 -------------------------------------------------------------------------------
783 Name: sysfs_open_directory
785 Description: Opens a sysfs directory at a specific path
787 Arguments: const unsigned char *path Directory path to open
789 Returns: struct sysfs_directory * with success.
790 NULL with error. Errno will be set with error, returning
791 - EINVAL for invalid arguments
793 Prototype: struct sysfs_directory *sysfs_open_directory
794 (const unsigned char *path)
795 -------------------------------------------------------------------------------
797 -------------------------------------------------------------------------------
798 Name: sysfs_close_directory
800 Description: Closes specific directory, its subdirectories, links, and
803 Arguments: struct sysfs_directory *sysdir Directory to close
805 Prototype: void sysfs_close_directory(struct sysfs_directory *sysdir)
806 -------------------------------------------------------------------------------
808 -------------------------------------------------------------------------------
809 Name: sysfs_read_dir_subdirs
811 Description: Reads the given sysfs_directory to create a list of subdirs.
813 Arguments: struct sysfs_directory *sysdir sysfs_directory whose
814 subdirs have to be read
816 Returns: struct dlist * of links with success
817 NULL with error. Errno will be set on error, returning EINVAL
818 for invalid arguments
820 Prototype: struct dlist *sysfs_read_dir_subdirs
821 (struct sysfs_directory *sysdir)
822 -------------------------------------------------------------------------------
824 -------------------------------------------------------------------------------
825 Name: sysfs_read_directory
827 Description: Read the supplied directory. Reading fills in the directory's
828 contents like subdirectories, links, and attributes.
830 Arguments: struct sysfs_directory *sysdir Directory to read
832 Returns: 0 with success.
833 -1 with error. Errno will be set with error, returning
834 - EINVAL for invalid arguments
836 Prototype: int sysfs_read_directory(struct sysfs_directory *sysdir)
837 -------------------------------------------------------------------------------
839 -------------------------------------------------------------------------------
840 Name: sysfs_read_all_subdirs
842 Description: Reads all subdirs under a given supplied directory.
844 Arguments: struct sysfs_directory *sysdir Directory to read
846 Returns: 0 with success.
847 -1 with error. Errno will be set with error, returning
848 - EINVAL for invalid arguments
850 Prototype: int sysfs_read_all_subdirs(struct sysfs_directory *sysdir)
851 -------------------------------------------------------------------------------
853 -------------------------------------------------------------------------------
854 Name: sysfs_get_subdirectory
856 Description: Function walks the directory tree for the given directory and
857 returns a sysfs_directory structure for the specified directory
860 Arguments: struct sysfs_directory *dir Directory in which to search
861 unsigned char *subname Name of directory to look for
863 Returns: struct sysfs_directory with success.
864 NULL with error. Errno will be set with error, returning
865 - EINVAL for invalid arguments
866 -------------------------------------------------------------------------------
872 The library provides a functions for viewing buses represented in sysfs.
873 The sysfs_open_bus opens a bus in the /sys/bus directory, such as "pci",
874 "usb", or "scsi". The open command returns a sysfs_bus structure that
875 contains a list of the bus' devices. The sysfs_close_bus function is
876 used to clean up the bus structure. Given a device or a driver,
877 functions are provided to determine what bus they are on.
879 -------------------------------------------------------------------------------
882 Description: Function opens up one of the buses represented in sysfs in
883 the /sys/bus directory. It returns a sysfs_bus structure
884 that includes a list of bus devices and drivers.
886 Arguments: const unsigned char *name Bus name to open, like "pci"...
888 Returns: struct sysfs_bus * with success
889 NULL with error. Errno will be set with error, returning
890 - EINVAL for invalid arguments
892 Prototype: struct sysfs_bus *sysfs_open_bus(const unsigned char *name)
893 -------------------------------------------------------------------------------
895 -------------------------------------------------------------------------------
896 Name: sysfs_close_bus
898 Description: Function closes up the sysfs_bus structure including its
899 devices, drivers, and directory.
901 Arguments: sysfs_bus *bus Bus structure to close
903 Prototype: void sysfs_close_bus(struct sysfs_bus *bus)
904 -------------------------------------------------------------------------------
906 -------------------------------------------------------------------------------
907 Name: sysfs_get_bus_devices
909 Description: Function returns a list of devices that are registered with
912 Arguments: struct sysfs_bus *bus Bus whose devices list to return
914 Returns: struct dlist * of sysfs_devices on success
915 NULL with error. Errno will be sent with error, returning
916 - EINVAL for invalid arguments
918 Prototype: struct dlist *sysfs_get_bus_devices(struct sysfs_bus *bus)
919 -------------------------------------------------------------------------------
921 -------------------------------------------------------------------------------
922 Name: sysfs_get_bus_drivers
924 Description: Function returns a list of drivers that are registered with
927 Arguments: struct sysfs_bus *bus Bus whose drivers list to return
929 Returns: struct dlist * of sysfs_drivers on success
930 NULL with error. Errno will be sent with error, returning
931 - EINVAL for invalid arguments
933 Prototype: struct dlist *sysfs_get_bus_drivers(struct sysfs_bus *bus)
934 -------------------------------------------------------------------------------
936 -------------------------------------------------------------------------------
937 Name: sysfs_get_bus_device
939 Description: Function takes a sysfs_bus structure(obtained on a successful
940 return from a sysfs_open_bus() call) and looks for the given
941 device on this bus. On success, it returns a sysfs_device
942 structure corresponding to the device.
944 Arguments: struct sysfs_bus *bus Bus structure on which to search
945 unsigned char *id Device to look for
947 Returns: struct sysfs_device * with success
948 NULL with error. Errno will be set with error, returning
949 - EINVAL for invalid arguments
951 Prototype: struct sysfs_device *sysfs_get_bus_device
952 (struct sysfs_bus *bus, unsigned char *id)
953 -------------------------------------------------------------------------------
955 -------------------------------------------------------------------------------
956 Name: sysfs_get_bus_driver
958 Description: Function takes a sysfs_bus structure (obtained on a successful
959 return from a sysfs_open_bus() call) and looks for the given
960 driver on this bus. On success, it returns a sysfs_driver
961 structure corresponding to the driver.
963 Arguments: struct sysfs_bus *bus Bus structure on which to search
964 unsigned char *drvname Driver to look for
966 Returns: struct sysfs_driver * with success
967 NULL with error. Errno will be set with error, returning
968 - EINVAL for invalid arguments
970 Prototype: struct sysfs_device *sysfs_get_bus_driver
971 (struct sysfs_bus *bus, unsigned char *drvname)
972 -------------------------------------------------------------------------------
974 -------------------------------------------------------------------------------
975 Name: sysfs_get_bus_attributes
977 Description: Function takes a sysfs_bus structure and returns a list of
978 attributes for the bus.
980 Arguments: struct sysfs_bus *bus Bus for which attributes are required
982 Returns: struct dlist * of attributes with success
983 NULL with error. Errno will be set with error, returning
984 - EINVAL for invalid arguments
986 Prototype: struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus)
987 -------------------------------------------------------------------------------
989 -------------------------------------------------------------------------------
990 Name: sysfs_get_bus_attribute
992 Description: Function takes a sysfs_bus structure and looks for the required
993 attribute on the bus. On success, it returns a sysfs_attribute
994 structure corresponding to the given attribute.
996 Arguments: struct sysfs_bus *bus Bus structure on which to search
997 unsigned char *attrname Attribute to look for
999 Returns: struct sysfs_attribute * with success
1000 NULL with error. Errno will be set with error, returning
1001 - EINVAL for invalid arguments
1003 Prototype: struct sysfs_attribute *sysfs_get_bus_attribute
1004 (struct sysfs_bus *bus, unsigned char *attrname)
1005 -------------------------------------------------------------------------------
1007 -------------------------------------------------------------------------------
1008 Name: sysfs_open_bus_device
1010 Description: Given the name of the bus on which to look for, this function
1011 locates a given device on the bus and returns a sysfs_device
1012 structure corresponding to the requested device.
1015 1. The sysfs_device structure obtained upon successful return
1016 from this function has to be closed by calling
1017 sysfs_close_device().
1019 Arguments: unsigned char *busname Bus on which to search
1020 unsigned char *dev_id Name of the device to look for
1022 Returns: struct sysfs_device * on success
1023 NULL with error. Errno will be set with error, returning
1024 - EINVAL for invalid arguments
1026 Prototype: struct sysfs_device *sysfs_open_bus_device
1027 (unsigned char *busname, unsigned char *dev_id)
1028 -------------------------------------------------------------------------------
1030 -------------------------------------------------------------------------------
1031 Name: sysfs_find_driver_bus
1033 Description: Given the name of a driver, this function finds the name of the
1034 bus the driver is on
1036 Arguments: const unsigned char *driver Name of the driver to look for
1037 unsigned char *busname Buffer to return the bus name
1038 size_t bsize Size of the "busname" buffer
1040 Returns: 0 with success.
1041 -1 with error. Errno will be set with error, returning
1042 - EINVAL for invalid arguments
1044 Prototype: int sysfs_find_driver_bus(const unsigned char *driver,
1045 unsigned char *busname, size_t bsize)
1046 -------------------------------------------------------------------------------
1052 Libsysfs provides functions to open sysfs classes and their class devices.
1053 These functions too operate with open and close, close must be called to
1054 clean up the class structures. Given a class device name, functions are
1055 provided to determine what class they belong to. Once a class device
1056 name and the class it belongs to is known, a function to open the
1057 class device is provided. This method can be used when details of
1058 a single class device is required.
1060 -------------------------------------------------------------------------------
1061 Name: sysfs_open_class
1063 Description: Function opens up one of the classes represented in sysfs in
1064 the /sys/class directory. It returns a sysfs_class structure
1065 that includes a list of class devices.
1067 Arguments: const unsigned char *name Class name to open, like "net"..
1069 Returns: struct sysfs_class * with success
1070 NULL with error. Errno will be set with error, returning
1071 - EINVAL for invalid arguments
1073 Prototype: struct sysfs_class *sysfs_open_class(const unsigned char *name)
1074 -------------------------------------------------------------------------------
1076 -------------------------------------------------------------------------------
1077 Name: sysfs_close_class
1079 Description: Function closes up the sysfs_class structure including its
1082 Arguments: sysfs_class *class Class structure to close
1084 Prototype: void sysfs_close_class(struct sysfs_class *class);
1085 -------------------------------------------------------------------------------
1087 -------------------------------------------------------------------------------
1088 Name: sysfs_open_class_device_path
1090 Description: Function opens up one of the class devices represented in
1091 sysfs in sysfs/class/"class"/ directory. It returns a
1092 sysfs_class_device structure.
1094 Arguments: const unsigned char *path Path to class device
1096 Returns: struct sysfs_class_device * with success
1097 NULL with error. Errno will be set with error, returning
1098 - EINVAL for invalid arguments
1100 Prototype: struct sysfs_class_device *sysfs_open_class_device_path
1101 (const unsigned char *path)
1102 -------------------------------------------------------------------------------
1104 -------------------------------------------------------------------------------
1105 Name: sysfs_close_class_device
1107 Description: Function closes up the sysfs_class_device structure.
1109 Arguments: sysfs_class_device *dev Class device structure to close
1111 Prototype: void sysfs_close_class_device(struct sysfs_class_device *dev)
1112 -------------------------------------------------------------------------------
1114 -------------------------------------------------------------------------------
1115 Name: sysfs_get_class_device
1117 Description: Function takes a sysfs_class structure(obtained on a successful
1118 return from a sysfs_open_class() call) and looks for the given
1119 device in this class. On success, it returns a sysfs_class_device
1120 structure corresponding to the class device.
1122 Arguments: struct sysfs_class *class Class on which to search
1123 unsigned_char *name Class device "name" to look for
1125 Returns: struct sysfs_class_device * with success
1126 NULL with error. Errno will be set with error, returning
1127 - EINVAL for invalid arguments
1129 Prototype: struct sysfs_class_device *sysfs_get_class_device
1130 (struct sysfs_class *class, unsigned char *name)
1131 -------------------------------------------------------------------------------
1133 -------------------------------------------------------------------------------
1134 Name: sysfs_get_class_devices
1136 Description: Function returns a list of class devices for the given class.
1138 Arguments: struct sysfs_class *cls Class whose class device list
1141 Returns: struct dlist * of sysfs_class_devices on success
1142 NULL with error. Errno will be set with error, returning
1143 - EINVAL for invalid arguments
1145 Prototype: struct dlist *sysfs_get_class_devices(struct sysfs_class *cls)
1146 -------------------------------------------------------------------------------
1148 -------------------------------------------------------------------------------
1149 Name: sysfs_open_class_device
1151 Description: Given the name of the class on which to look for, this function
1152 locates a given class device and returns a sysfs_class_device
1153 structure corresponding to the requested class device.
1156 1. The sysfs_class_device structure obtained upon successful
1157 return from this function has to be closed by calling
1158 sysfs_close_class_device().
1159 2. Class this device belongs to must be known prior to calling
1162 Arguments: const unsigned char *classname Class on which to search
1163 unsigned char *name Class device "name" to open
1165 Returns: struct sysfs_class_device * with success
1166 NULL with error. Errno will be set with error, returning
1167 - EINVAL for invalid arguments
1169 Prototype: struct sysfs_class_device *sysfs_open_class_device
1170 (const unsigned char *classname, unsigned char *class)
1171 -------------------------------------------------------------------------------
1173 -------------------------------------------------------------------------------
1174 Name: sysfs_get_classdev_device
1176 Description: Function returns the sysfs_device reference (if present) for the
1179 Arguments: struct sysfs_class_device *clsdev Class device whose
1180 sysfs_device reference
1183 Returns: struct sysfs_device * on success
1184 NULL with error. Errno will be set with error, returning
1185 - EINVAL for invalid arguments
1187 Prototype: struct sysfs_device *sysfs_get_classdev_device
1188 (struct sysfs_class_device *clsdev)
1189 -------------------------------------------------------------------------------
1191 -------------------------------------------------------------------------------
1192 Name: sysfs_get_classdev_driver
1194 Description: Function returns the sysfs_driver reference (if present) for the
1197 Arguments: struct sysfs_class_device *clsdev Class device whose
1198 sysfs_driver reference
1201 Returns: struct sysfs_driver * on success
1202 NULL with error. Errno will be set with error, returning
1203 - EINVAL for invalid arguments
1205 Prototype: struct sysfs_driver *sysfs_get_classdev_driver
1206 (struct sysfs_class_device *clsdev)
1207 -------------------------------------------------------------------------------
1209 -------------------------------------------------------------------------------
1210 Name: sysfs_get_classdev_parent
1212 Description: Function returns the sysfs_class_device reference for the parent
1213 (if present) of the given class device.
1215 Arguments: struct sysfs_class_device *clsdev Class device whose
1219 Returns: struct sysfs_class_device * on success
1220 NULL with error. Errno will be set with error, returning
1221 - EINVAL for invalid arguments
1223 Prototype: struct sysfs_class_device *sysfs_get_classdev_parent
1224 (struct sysfs_class_device *clsdev)
1225 -------------------------------------------------------------------------------
1227 -------------------------------------------------------------------------------
1228 Name: sysfs_get_classdev_attributes
1230 Description: Function takes a sysfs_class_device structure and returns a list
1231 of attributes for the class device.
1233 Arguments: struct sysfs_class_device *cdev Class device for which
1234 attributes are required
1236 Returns: struct dlist * of attributes with success
1237 NULL with error. Errno will be set with error, returning
1238 - EINVAL for invalid arguments
1240 Prototype: struct dlist *sysfs_get_classdev_attributes
1241 (struct sysfs_class_device *cdev)
1242 -------------------------------------------------------------------------------
1244 -------------------------------------------------------------------------------
1245 Name: sysfs_get_classdev_attr
1247 Description: Searches supplied class device's attributes by name and returns
1250 Arguments: struct sysfs_class_device *clsdev Device to search
1251 const unsigned char *name Attribute name to find
1253 Returns: struct sysfs_attribute * with success
1254 NULL with error. Errno will be set with error, returning
1255 - EINVAL for invalid arguments
1257 Prototype: struct sysfs_attribute *sysfs_get_classdev_attr
1258 (struct sysfs_class_device *clsdev, const unsigned char *name)
1259 -------------------------------------------------------------------------------
1261 -------------------------------------------------------------------------------
1262 Name: sysfs_open_classdev_attr
1264 Description: Function takes as arguments, a the name of the class, the class
1265 device name and the name of the required attribute.
1268 1. The struct sysfs_attribute * obtained upon successful
1269 return from this function has to be closed by making
1270 a call to sysfs_close_attribute()
1272 Arguments: unsigned char *classname Class name on which to search
1273 unsigned char *dev Name of the class device
1274 unsigned char *attrib Attribute to open
1276 Returns: struct sysfs_attribute * with success.
1277 NULL with error. Errno will be set with error, returning
1278 - EINVAL for invalid arguments
1280 Prototype: struct sysfs_attribute *sysfs_write_classdev_attr
1281 (const unsigned char *classname, const unsigned char *dev,
1282 const unsigned char *attrib)
1283 -------------------------------------------------------------------------------
1286 6.5 Device Functions
1287 --------------------
1289 Devices represent everything in sysfs under /sys/devices, which is a
1290 hierarchical view of system devices. Besides the expected open and
1291 close functions, libsysfs provides open and close functions for
1292 root devices. These functions recursively open or close a device
1293 and all of its children.
1295 -------------------------------------------------------------------------------
1296 Name: sysfs_open_device_path
1298 Description: Opens up a device at a specific path. It opens the device's
1299 directory, reads the directory, and returns a sysfs_device
1302 Arguments: const unsigned char *path Path to device
1304 Returns: struct sysfs_device * with success
1305 NULL with error. Errno will be set with error, returning
1306 - EINVAL for invalid arguments
1308 Prototype: struct sysfs_device *sysfs_open_device_path
1309 (const unsigned char *path)
1310 -------------------------------------------------------------------------------
1312 -------------------------------------------------------------------------------
1313 Name: sysfs_close_device
1315 Description: Function closes up the sysfs_device structure.
1317 Arguments: sysfs_device *dev Device structure to close
1319 Prototype: void sysfs_close_device(struct sysfs_device *dev)
1320 -------------------------------------------------------------------------------
1322 -------------------------------------------------------------------------------
1323 Name: sysfs_open_root_device
1325 Description: Function opens up one of the root devices represented in sysfs
1326 in the /sys/devices directory. It returns a sysfs_root_device
1327 structure that includes a list of devices in the tree.
1329 Arguments: const unsigned char *name Name of the root device to open
1331 Returns: struct sysfs_root_device * with success
1332 NULL with error. Errno will be set with error, returning
1333 - EINVAL for invalid arguments
1335 Prototype: struct sysfs_device *sysfs_open_root_device
1336 (const unsigned char *name)
1337 -------------------------------------------------------------------------------
1339 -------------------------------------------------------------------------------
1340 Name: sysfs_close_root_device
1342 Description: Function closes up the sysfs_root_device structure including the
1343 devices in the root device tree.
1345 Arguments: sysfs_device *root Root device structure to close
1347 Prototype: void sysfs_close_root_device(struct sysfs_root_device *root)
1348 -------------------------------------------------------------------------------
1350 -------------------------------------------------------------------------------
1351 Name: sysfs_get_device_parent
1353 Description: Function returns the sysfs_device reference for the parent
1354 (if present) of the given sysfs_device.
1356 Arguments: struct sysfs_device *dev sysfs_device whose parent
1357 reference is required
1359 Returns: struct sysfs_device * on success
1360 NULL with error. Errno will be set with error, returning
1361 - EINVAL for invalid arguments
1363 Prototype: struct sysfs_device *sysfs_get_device_parent
1364 (struct sysfs_device *dev)
1365 -------------------------------------------------------------------------------
1367 -------------------------------------------------------------------------------
1368 Name: sysfs_get_root_devices
1370 Description: Function returns a list of devices under the given root device.
1372 Arguments: struct sysfs_root_device *root sysfs_root_device whose devices
1375 Returns: struct dlist * of sysfs_devices on success
1376 NULL with error. Errno will be set with error, returning
1377 - EINVAL for invalid arguments
1379 Prototype: struct dlist *sysfs_get_root_devices
1380 (struct sysfs_root_device *root)
1381 -------------------------------------------------------------------------------
1383 -------------------------------------------------------------------------------
1384 Name: sysfs_get_device_attr
1386 Description: Searches supplied device's attributes by name and returns
1389 Arguments: struct sysfs_device *dev Device to search
1390 const unsigned char *name Attribute name to find
1392 Returns: struct sysfs_attribute * with success
1393 NULL with error. Errno will be set with error, returning
1394 - EINVAL for invalid arguments
1396 Prototype: struct sysfs_attribute *sysfs_get_device_attr
1397 (struct sysfs_device *dev, const unsigned char *name)
1398 -------------------------------------------------------------------------------
1400 -------------------------------------------------------------------------------
1401 Name: sysfs_get_device_attributes
1403 Description: Function takes a sysfs_device structure and returns a list
1404 of attributes for the device.
1406 Arguments: struct sysfs_device *device Device for which
1407 attributes are required
1409 Returns: struct dlist * of attributes with success
1410 NULL with error. Errno will be set with error, returning
1411 - EINVAL for invalid arguments
1413 Prototype: struct dlist *sysfs_get_device_attributes
1414 (struct sysfs_device *device)
1415 -------------------------------------------------------------------------------
1417 -------------------------------------------------------------------------------
1418 Name: sysfs_open_device
1420 Description: Given the name of the bus on which to look for, this function
1421 locates a given device and returns a sysfs_device structure
1422 corresponding to the requested device.
1424 Arguments: const unsigned char *bus_id Device to look for
1425 const unsigned char *bus Bus on which to search
1427 Returns: struct sysfs_device * with success
1428 NULL with error. Errno will be set with error, returning
1429 - EINVAL for invalid arguments
1431 Prototype: struct sysfs_device *sysfs_open_device
1432 (const unsigned char *bus_id, const unsigned char *bus)
1433 -------------------------------------------------------------------------------
1435 -------------------------------------------------------------------------------
1436 Name: sysfs_open_device_attr
1438 Description: Function takes as arguments, the bus on which to search for a
1439 device, and an attribute of the device to open.
1442 1. The struct sysfs_attribute * obtained upon successful
1443 return from this function has to be closed by making
1444 a call to sysfs_close_attribute()
1446 Arguments: unsigned char *bus Bus on which to search
1447 unsigned char *bus_id Device to look for
1448 unsigned char *attrib Name of the attribute to open
1450 Returns: struct sysfs_attribute * with success.
1451 NULL with error. Errno will be set with error, returning
1452 - EINVAL for invalid arguments
1454 Prototype: struct sysfs_attribute *sysfs_open_device_attr
1455 (const unsigned char *bus, const unsigned char *bus_id,
1456 const unsigned char *attrib)
1457 -------------------------------------------------------------------------------
1460 6.6 Driver Functions
1461 --------------------
1463 Drivers are represented in sysfs under the /sys/bus/xxx/drivers (xxx being
1464 the bus type, such as "pci", "usb, and so on). Functions are provided to
1465 open and close drivers.
1467 -------------------------------------------------------------------------------
1468 Name: sysfs_open_driver_path
1470 Description: Opens driver at specific path.
1472 Arguments: const unsigned char *path Path to driver
1474 Returns: struct sysfs_driver * with success
1475 NULL with error. Errno will be set with error, returning
1476 - EINVAL for invalid arguments
1478 Prototype: struct sysfs_driver *sysfs_open_driver_path
1479 (const unsigned char *path)
1480 -------------------------------------------------------------------------------
1482 -------------------------------------------------------------------------------
1483 Name: sysfs_close_driver
1485 Description: Closes and cleans up sysfs_driver structure.
1487 Arguments: sysfs_driver *driver Driver structure to close
1489 Prototype: void sysfs_close_driver(struct sysfs_driver *driver)
1490 -------------------------------------------------------------------------------
1492 -------------------------------------------------------------------------------
1493 Name: sysfs_get_driver_devices
1495 Description: Function returns a list of devices that use this driver.
1497 Arguments: struct sysfs_driver *driver Driver whose devices list is
1500 Returns: struct dlist * of sysfs_devices on success
1501 NULL with error. Errno will be set with error, returning
1502 - EINVAL for invalid arguments
1504 Prototype: struct dlist *sysfs_get_driver_devices
1505 (struct sysfs_driver *driver)
1506 -------------------------------------------------------------------------------
1508 -------------------------------------------------------------------------------
1509 Name: sysfs_get_driver_device
1511 Description: Function returns a sysfs_device reference for the device with
1512 "name" that uses this driver
1514 Arguments: struct sysfs_driver *driver Driver on which to search
1515 const unsigned char *name Name of the device to look for
1517 Returns: struct sysfs_device * corresponding to "name" on success
1518 NULL with error. Errno will be set with error, returning
1519 - EINVAL for invalid arguments
1521 Prototype: struct dlist *sysfs_get_driver_device
1522 (struct sysfs_driver *driver, const unsigned char *name)
1523 -------------------------------------------------------------------------------
1525 -------------------------------------------------------------------------------
1526 Name: sysfs_get_driver_attr
1528 Description: Searches supplied driver's attributes by name and returns
1531 Arguments: struct sysfs_driver *drv Driver to search
1532 const unsigned char *name Attribute name to find
1534 Returns: struct sysfs_attribute * with success
1535 NULL with error. Errno will be set with error, returning
1536 - EINVAL for invalid arguments
1538 Prototype: struct sysfs_attribute *sysfs_get_driver_attr
1539 (struct sysfs_driver *drv, const unsigned char *name)
1540 -------------------------------------------------------------------------------
1542 -------------------------------------------------------------------------------
1543 Name: sysfs_get_driver_attributes
1545 Description: Function takes a sysfs_driver structure and returns a list
1546 of attributes for the driver.
1548 Arguments: struct sysfs_driver *driver Driver for which
1549 attributes are required
1551 Returns: struct dlist * of attributes with success
1552 NULL with error. Errno will be set with error, returning
1553 - EINVAL for invalid arguments
1555 Prototype: struct dlist *sysfs_get_driver_attributes
1556 (struct sysfs_driver *driver)
1557 -------------------------------------------------------------------------------
1559 -------------------------------------------------------------------------------
1560 Name: sysfs_open_driver
1562 Description: Given the name of the bus on which to look for, this function
1563 locates a given driver and returns a sysfs_driver structure
1564 corresponding to the requested device.
1567 1. The sysfs_driver structure obtained upon successful return
1568 from this function has to be closed by calling
1569 sysfs_close_driver_by_name().
1570 2. Bus on which to look for this driver should be known prior
1571 to calling this function. Use sysfs_find_driver_bus()
1574 Arguments: const unsigned char *drv_name Driver to look for
1575 const unsigned char *bus Bus on which to search
1576 size_t bsize Size of "bus"
1578 Returns: struct sysfs_driver * with success
1579 NULL with error. Errno will be set with error, returning
1580 - EINVAL for invalid arguments
1582 Prototype: struct sysfs_driver *sysfs_open_driver
1583 (const unsigned char *drv_name,
1584 const unsigned char *bus, size_t bsize)
1585 -------------------------------------------------------------------------------
1587 -------------------------------------------------------------------------------
1588 Name: sysfs_get_driver_links
1590 Description: Function returns a list of links for a given driver
1592 Arguments: struct sysfs_driver *driver Driver to get links from
1594 Returns: struct dlist * of links on success
1597 Prototype: struct dlist *sysfs_get_driver_links
1598 (struct sysfs_driver *driver)
1599 -------------------------------------------------------------------------------
1601 -------------------------------------------------------------------------------
1602 Name: sysfs_open_driver_attr
1604 Description: Function takes as arguments, the bus the driver is registered
1605 on, the driver name and the name of the attribute to open.
1608 1. The struct sysfs_attribute * obtained upon successful
1609 return from this function has to be closed by making
1610 a call to sysfs_close_attribute()
1612 Arguments: unsigned char *bus Bus on which driver is present
1613 unsigned char *drv Driver to look for
1614 unsigned char *attrib Name of the attribute to open
1616 Returns: struct sysfs_attribute * with success.
1617 NULL with error. Errno will be set with error, returning
1618 - EINVAL for invalid arguments
1620 Prototype: struct sysfs_attribute *sysfs_open_driver_attr
1621 (const unsigned char *bus, const unsigned char *drv,
1622 const unsigned char *attrib)
1623 -------------------------------------------------------------------------------
1626 7. Navigating a dlist
1627 ---------------------
1629 Libsysfs uses (yet another) list implementation thanks to Eric J Bohm.
1631 Some library functions return a dlist of devices/drivers/attributes, etc.
1632 To navigate the list returned the macro "dlist_for_each_data" is to be used.
1634 ------------------------------------------------------------------------------
1635 Function/Macro name: dlist_for_each_data
1637 Description: Walk the given list, returning a known data type/
1638 structure in each iteration.
1640 Arguments: struct dlist *list List pointer
1641 data_iterator Data type/structure variable
1642 contained in the list
1643 datatype Data type/structure contained
1646 Returns: On each iteration, "data_iterator" will contain a list
1647 element of "datatype"
1649 Usage example: The function sysfs_get_classdev_attributes() returns a
1650 dlist of attributes. To navigate the list:
1652 struct sysfs_attribute *attr = NULL;
1653 struct dlist *attrlist = NULL;
1657 attrlist = sysfs_get_classdev_attributes
1658 (struct sysfs_class_device *cdev)
1659 if (attrlist != NULL) {
1660 dlist_for_each_data(attrlist, attr,
1661 struct sysfs_attribute) {
1667 -------------------------------------------------------------------------------
1673 Accessing devices through libsysfs is supposed to mirror accessing devices
1674 in the filesystem it represents. Here's a typical order of operation:
1676 - get sysfs mount point
1677 - "open" sysfs category, ie. bus, class, or device
1678 - work with category
1679 - "close" sysfs category
1685 Libsysfs is meant to provide a stable application programming interface to
1686 sysfs. Applications can depend upon the library to access system devices
1687 and functions exposed through sysfs.