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
25 6.1 Calling Conventions in Libsysfs
27 6.3 Filesystem Functions
28 6.3.1 Attribute Functions
29 6.3.2 Directory Link Functions
30 6.3.3 Directory Functions
36 7.1 Navigating a dlist
37 7.2 Custom sorting using dlist_sort_custom()
46 Libsysfs' purpose is to provide a consistent and stable interface for
47 querying system device information exposed through the sysfs filesystem.
48 The library implements functions for querying filesystem information,
49 such as reading directories and files. It also contains routines for
50 working with buses, classes, and the device tree.
56 The library must satisfy the following requirements:
58 - It must provide a stable programming interfaces that applications can
61 - It must provide functions to retrieve device Vital Product Data (VPD)
62 information for Error Log Analysis (ELA) support. ELA will provide
63 device driver and device bus address information.
65 - It must provide access to all system devices and information exposed
68 - It must provide a function to find sysfs' current mount point.
70 - It must provide a function for udev to retrieve a device's major and
77 - sysfs: Sysfs is a virtual filesystem in 2.5+ Linux kernels that
78 presents a hierarchical representation of all system physical and
79 virtual devices. It presents system devices by bus, by class, and
80 by topology. Callbacks to device drivers are exposed as files in
81 device directories. Sysfs, for all purposes, is our tree of system
82 devices. For more information, please see:
84 http://www.kernel.org/pub/linux/kernel/people/mochel/doc/
86 - udev: Udev is Greg Kroah-Hartman's User Space implementation of devfs.
87 Udev creates /dev nodes for devices upon Hotplug events. The Hotplug
88 event provides udev with a sysfs directory location of the device. Udev
89 must use that directory to grab device's major and minor number, which it
90 will use to create the /dev node. For more information, please see:
92 http://www.kernel.org/pub/linux/utils/kernel/hotplug/
94 Udev provides persistent device naming based on a set of user specified
95 rules. The rules a device name is based on could one or a combination of a
96 number of parameters such as the bus the device is on, the serial number
97 of the device (in case of USB), the vendor name (in case of SCSI) and so
98 on. Udev uses Libsysfs to retrieve relevent information to appropriately
105 Libsysfs grew from a common need. There are several applications under
106 development that need access to sysfs and system devices. Udev, on a
107 hotplug event, must take a sysfs device path and create a /dev node. Our
108 diagnostic client needs to list all system devices. Finally, our Error
109 Log Analysis piece is required to retrieve VPD information for a
110 failing device. We divided to create a single library interface rather
111 than having these separate applications create their own accesses to
112 sysfs involving reading directories and files.
114 Libsysfs will also provide stability for applications to be built upon. Sysfs
115 currently doesn't enforce any standards for callback or file names. File
116 names change depending on bus or class. Sysfs is also changing, it is
117 currently being developed. Libsysfs will provide a stable interface to
118 applications while allowing sysfs to change underneath it.
120 Like sysfs, the library will provide devices to applications by bus, by
121 class, and by topology. The library will function similar to directories
122 and files that lie underneath it. To query a device on a PCI bus, one would
123 "open" the bus to scan or read devices and "close" the bus when
124 completed. Besides supplying functions to retrieve devices, the library
125 will also provide some utility functions like getting sysfs mount point.
127 A paper on Libsysfs was presented at Linux.Conf.Au 2004 (Adelaide, January
128 2004). The paper is available online at:
130 http://oss.software.ibm.com/linux/papers/libsysfs/libsysfs-linuxconfau2004.pdf
136 Libsysfs will classify system devices following sysfs' example, dividing
137 them by bus, class, and devices. The library presents this information
138 generically. It doesn't, for example, differentiate between PCI and USB
139 buses. Device attributes are presented with values as they are exposed
140 by sysfs, the values are not formatted.
142 The library will provide standard definitions for working with sysfs
143 and devices, here's some examples:
145 #define SYSFS_FSTYPE_NAME "sysfs"
146 #define SYSFS_PROC_MNTS "/proc/mounts"
147 #define SYSFS_BUS_NAME "bus"
148 #define SYSFS_CLASS_NAME "class"
149 #define SYSFS_BLOCK_NAME "block"
150 #define SYSFS_DEVICES_NAME "devices"
151 #define SYSFS_DRIVERS_NAME "drivers"
152 #define SYSFS_NAME_ATTRIBUTE "name"
154 The library uses some definitions to mark maximum size of a sysfs name or
157 #define SYSFS_PATH_MAX 255
158 #define SYSFS_NAME_LEN 50
159 #define SYSFS_BUS_ID_SIZE 20
163 a. As of release 0.4.0 of sysfsutils, a number of changes have been
164 made so that the dlists and "directory" references in all libsysfs's
165 structures are not populated until such time that it is absolutely
166 necessary. Hence, these elements may not contain valid data at all
167 times (as was the case before).
168 b. As of release 1.0.0 of sysfsutils, all dlists in the library are
169 sorted in alphabetical order. It is now a requirement that the
170 "name" and "path" be the first two elements of all libsysfs
174 5.1 Directory and Attribute Data Structures
175 -------------------------------------------
177 The library implements structures to represent sysfs directories, links,
181 5.1.1 Attribute Structure
182 -------------------------
184 A file in sysfs represents a device or driver attribute. Attributes can be
185 read only, write only, or read and write. File data can be ASCII and
186 binary. The library has the following structure to represent files:
188 struct sysfs_attribute {
189 char name[SYSFS_NAME_LEN];
190 char path[SYSFS_PATH_MAX];
192 unsigned short len; /* value length */
193 unsigned short method; /* show and store */
196 Path represents the file/attribute's full path. Value is used when reading
197 from or writing to an attribute. "len" is the length of data in "value".
198 Method is a bitmask for defining if the attribute supports show(read)
205 Symbolic links are used in sysfs to link bus or class views with
209 char name[SYSFS_NAME_LEN];
210 char path[SYSFS_PATH_MAX];
211 char target[SYSFS_PATH_MAX];
214 Link's name is stored in "name' and it's target stored in "target". Absolute
215 path to the link is stored in "path".
218 5.1.3 Directory Structure
219 -------------------------
221 The directory structure represents a sysfs directory:
223 struct sysfs_directory {
224 char name[SYSFS_NAME_LEN];
225 char path[SYSFS_PATH_MAX];
227 /* Private: for internal use only */
228 struct dlist *subdirs;
230 struct dlist *attributes;
233 The sysfs_directory structure includes the list of subdirectories, links and
234 attributes. The "name" and absolute "path" are also stored in the structure.
235 The sysfs_directory structure is intended for use internal to the library.
236 Applications needing access to attributes and links from the directory
237 will need to make appropriate calls (described below) to get the same.
240 5.2 Bus Data Structure
241 ----------------------
243 All buses look similar in sysfs including lists of devices and drivers,
244 therefore we use the following structure to represent all sysfs buses:
247 char name[SYSFS_NAME_LEN];
248 char path[SYSFS_PATH_MAX];
250 /* Private: for internal use only */
251 struct dlist *drivers;
252 struct dlist *devices;
253 struct sysfs_directory *directory;
256 The sysfs_bus structure contains the bus "name", while the "path" to bus
257 directory is also stored. It also contains lists of devices on the bus
258 and drivers that are registered on it. The bus' directory is represented
259 by the sysfs_directory structure and it contains references to all the
260 subdirectories, links, and attributes. The sysfs_directory structure
261 is for internal use only. The following functions may be used by
262 applications to retrieve data from the sysfs_directory structure:
264 struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus)
265 struct sysfs_attribute *sysfs_get_bus_attribute(struct sysfs_bus *bus,
269 5.3 Class Data Structures
270 -------------------------
272 The library uses two data structures to represent classes in sysfs. Sysfs
273 classes contains a class directory like "net" or "scsi_host" and then
274 class devices like "eth0", "lo", or "eth1" for the "net" class.
277 char name[SYSFS_NAME_LEN];
278 char path[SYSFS_PATH_MAX];
280 /* Private: for internal use only */
281 struct dlist *devices;
282 struct sysfs_directory *directory;
285 The sysfs_class represents device classes in sysfs like "net". It contains
286 the class "name", "path" to the class, a list of class devices and the
287 directory representation (for internal use only).
289 struct sysfs_class_device {
290 char name[SYSFS_NAME_LEN];
291 char path[SYSFS_PATH_MAX];
292 char classname[SYSFS_NAME_LEN];
294 /* Private: for internal use only */
295 struct sysfs_class_device *parent;
296 struct sysfs_device *sysdevice; /* NULL if virtual */
297 struct sysfs_driver *driver; /* NULL if not implemented */
298 struct sysfs_directory *directory;
301 A class device isn't the same as a sysfs_device, it's specific to the class in
302 which it belongs. The class device structure contains the name of the class
303 the class device belongs to, its sysfs_device reference and that device's
304 driver reference (if any). It also contains the name of the class device
305 - like "eth0", its parent point (if present) and its sysfs directory
306 information including links and attributes (for internal use only).
307 The following function may be used by applications to retrieve data
308 from the sysfs_directory structure:
310 struct dlist *sysfs_get_classdev_attributes(struct sysfs_class_device *cdev);
313 5.4 Root Device Data Structure
314 ------------------------------
316 Device hierarchies in sysfs are represented under the /sys/devices directory
317 structure. Sysfs devices typically spawn off from base devices which are
318 represented by a sysfs_root_device.
320 struct sysfs_root_device {
321 char name[SYSFS_NAME_LEN];
322 char path[SYSFS_PATH_MAX];
324 /* Private: for internal use only */
325 struct dlist *devices;
326 struct sysfs_directory *directory;
329 The sysfs_root_device structure contains a list of "devices" that spawn off it.
330 The name of the root device as represented under /sys/devices is read into
331 "name" and the absolute path into "path" and its sysfs_directory information
332 intended to be used internal to the library.
335 5.5 Device Data Structure
336 -------------------------
338 The sysfs_device structure represents a system device that's exposed
339 in sysfs under the /sys/devices directory structure.
341 struct sysfs_device {
342 char name[SYSFS_NAME_LEN];
343 char path[SYSFS_PATH_MAX];
344 char bus_id[SYSFS_NAME_LEN];
345 char bus[SYSFS_NAME_LEN];
346 char driver_name[SYSFS_NAME_LEN];
348 /* Private: for internal use only */
349 struct sysfs_device *parent;
350 struct dlist *children;
351 struct sysfs_directory *directory;
354 The sysfs_device structure contains a "parent" pointer, a list of child
355 devices, if any, device's directory, its bus id - which is the name of
356 device's directory, the bus name on which this device is registered and
357 its driver name. The device structure also contains the absolute path
358 to the device and a directory structure, which contains a list of the
359 device's attributes (for internal use only). The following functions
360 may be used to obtain information from sysfs_directory structure:
362 struct sysfs_attribute *sysfs_get_device_attribute(struct sysfs_device *dev,
364 struct dlist *sysfs_get_device_attributes(struct sysfs_device *device)
367 5.6 Driver Data Structure
368 -------------------------
370 The sysfs_driver structure represents a device driver.
372 struct sysfs_driver {
373 char name[SYSFS_NAME_LEN];
374 char path[SYSFS_PATH_MAX];
376 /* Private: for internal use only */
377 struct dlist *devices;
378 struct sysfs_directory *directory;
381 The sysfs_driver structure contains a list of devices that use this driver,
382 the name of the driver, its path, and its directory information, which
383 includes the driver's attributes (for internal use only). The following
384 function may be used to retrieve driver attribute information from the
385 sysfs_directory structure:
387 struct dlist *sysfs_get_driver_attributes(struct sysfs_driver *driver)
393 Libsysfs will provide functions to access system devices by bus, by class,
394 and by device. Functions will act like accessing directories and files,
395 using "open" and "close". Open returns a structure and close is used
396 to clean that structure up.
399 6.1 Calling Conventions in Libsysfs
400 -----------------------------------
402 Libsysfs uses a simple API calling convention. APIs are classified to be
403 one of "open", "get", "close" types. The convention is as follows:
405 a. All "open" APIs have a corresponding "close" API.
406 b. References obtained using "get" calls should not be closed
408 c. All "opened" references have to be closed with a call to
409 their corresponding "close" call. This takes care of
410 freeing structure references obtained with "get" calls.
413 6.2 Utility Functions
414 ---------------------
416 The library will provide a few utility functions for working with sysfs.
418 -------------------------------------------------------------------------------
419 Name: sysfs_get_mnt_path
421 Description: Function finds the mount path for filesystem type "sysfs".
423 Arguments: char *mnt_path Mount path buffer
424 size_t len Size of mount path buffer
426 Returns: Zero with success.
427 -1 with error. Errno will be set with error:
428 - EINVAL for invalid argument, if buffer is NULL or
431 Prototype: sysfs_get_mnt_path(char *mnt_path, size_t len);
432 -------------------------------------------------------------------------------
434 -------------------------------------------------------------------------------
435 Name: sysfs_get_name_from_path
437 Description: Function returns the last directory or file name from the
440 Arguments: const char *path Path to parse name from
441 char *name Buffer to put parsed name into
442 size_t *len Size of name buffer
444 Returns: 0 with success.
445 -1 on Error. Errno will be set with error, returning
446 - EINVAL for invalid arguments
448 Prototype: int sysfs_get_name_from_path(const char *path,
449 char *name, size_t *len)
450 -------------------------------------------------------------------------------
452 -------------------------------------------------------------------------------
455 Description: Sysfs readlink function, reads the link at supplied path
456 and returns its target path.
458 Arguments: const char *path Link's path
459 char *target Buffer to place link's target
460 size_t len Size of target buffer
462 Returns: 0 with success
463 -1 with error. Errno will be set with error, returning
464 - EINVAL for invalid arguments
466 Prototype: int sysfs_get_link(const char *path, char *target, size_t len)
467 -------------------------------------------------------------------------------
469 -------------------------------------------------------------------------------
470 Name: sysfs_open_subsystem_list
472 Description: Function returns the list of entries for the given subsystem. If
473 the argument is "bus", this function will return a list of buses
474 ("pci", "scsi", etc) supported on the system.
476 sysfs_close_list() has to be called to free the list obtained
479 Arguments: char *name Subsystem to open, like "bus"..
481 Returns: dlist of entries for the subsystem on success
482 NULL with error indicating the "name" subsystem is invalid.
484 Prototype: struct dlist *sysfs_open_subsystem_list(char *name)
485 -------------------------------------------------------------------------------
487 -------------------------------------------------------------------------------
488 Name: sysfs_open_bus_devices_list
490 Description: Function returns the list of devices on the given bus.
492 sysfs_close_list() has to be called to free the list obtained
495 Arguments: char *name Bus name to open "pci"/"scsi"/"usb"..
497 Returns: dlist of device names for the given bus on success
498 NULL with error indicating the bus is not supported.
500 Prototype: struct dlist *sysfs_open_bus_devices_list(char *name)
501 -------------------------------------------------------------------------------
503 -------------------------------------------------------------------------------
504 Name: sysfs_close_list
506 Description: Closes a given dlist. This can be used as a generic list close
509 Arguments: struct dlist *list List to be closed
511 Prototype: void sysfs_close_list(struct dlist *list)
512 -------------------------------------------------------------------------------
514 -------------------------------------------------------------------------------
515 Name: sysfs_path_is_dir
517 Description: Utility function to verify if a given path is to a directory.
519 Arguments: const char *path Path to verify
521 Returns: 0 on success, 1 on error
522 - EINVAL for invalid arguments
524 Prototype: int sysfs_path_is_dir(const char *path)
525 -------------------------------------------------------------------------------
527 -------------------------------------------------------------------------------
528 Name: sysfs_path_is_file
530 Description: Utility function to verify if a given path is to a file.
532 Arguments: const char *path Path to verify
534 Returns: 0 on success, 1 on error
535 - EINVAL for invalid arguments
537 Prototype: int sysfs_path_is_file(const char *path)
538 -------------------------------------------------------------------------------
540 -------------------------------------------------------------------------------
541 Name: sysfs_path_is_link
543 Description: Utility function to verify if a given path is to a link.
545 Arguments: const char *path Path to verify
547 Returns: 0 on success, 1 on error
548 - EINVAL for invalid arguments
550 Prototype: int sysfs_path_is_link(const char *path)
551 -------------------------------------------------------------------------------
554 6.3 Filesystem Functions
555 ------------------------
557 Libsysfs provides a set of functions to open, read, and close directories
558 and attributes/files in sysfs. These functions mirror their filesystem
559 function counterparts.
562 6.3.1 Attribute Functions
563 -------------------------
565 Along with the usual open, read, and close functions, libsysfs provides
566 a couple other functions for accessing attribute values.
568 -------------------------------------------------------------------------------
569 Name: sysfs_open_attribute
571 Description: Opens up a file in sysfs and creates a sysfs_attribute
572 structure. File isn't read with this function.
574 Arguments: const char *path File/Attribute's path
576 Returns: struct sysfs_attribute * with success.
577 NULL with error. Errno will be set with error, returning
578 - EINVAL for invalid arguments
580 Prototype: struct sysfs_attribute *sysfs_open_attribute(const char *path)
581 -------------------------------------------------------------------------------
583 -------------------------------------------------------------------------------
584 Name: sysfs_close_attribute
586 Description: Cleans up and closes sysfs_attribute structure.
588 Arguments: struct sysfs_attribute *sysattr Attribute to close
590 Prototype: void sysfs_close_attribute(struct sysfs_attribute *sysattr)
591 -------------------------------------------------------------------------------
593 -------------------------------------------------------------------------------
594 Name: sysfs_read_dir_attributes
596 Description: Reads the given sysfs_directory to create a list of attributes.
598 Arguments: struct sysfs_directory *sysdir sysfs_directory whose
601 Returns: struct dlist * of attributes on success
602 NULL with error. Errno will be set on error, returning EINVAL
603 for invalid arguments
605 Prototype: struct dlist *sysfs_read_dir_attributes
606 (struct sysfs_directory *sysdir)
607 -------------------------------------------------------------------------------
609 -------------------------------------------------------------------------------
610 Name: sysfs_refresh_dir_attributes
612 Description: Given a list sysfs_directory, this function refreshes the list
613 of attributes for the given directory.
615 Arguments: struct sysfs_directory *sysdir sysfs_ directory whose
616 attributes list to refresh
618 Returns: 0 with success.
619 1 with error. Errno will be set on error, returning EINVAL
620 for invalid arguments
622 Prototype: int sysfs_refresh_dir_attributes(struct sysfs_directory *sysdir)
623 -------------------------------------------------------------------------------
625 -------------------------------------------------------------------------------
626 Name: sysfs_get_dir_attributes
628 Description: Returns a list of attributes for the given sysfs_directory.
630 Arguments: struct sysfs_directory *sysdir sysfs_directory whose
631 attributes list to return
633 Returns: struct dlist * of attributes with success
634 NULL with error. Errno will be set on error, returning EINVAL
635 for invalid arguments
637 Prototype: struct dlist *sysfs_read_dir_attributes
638 (struct sysfs_directory *sysdir)
639 -------------------------------------------------------------------------------
641 -------------------------------------------------------------------------------
642 Name: sysfs_read_attribute
644 Description: Reads the supplied attribute. Since the maximum transfer
645 from a sysfs attribute is a pagesize, function reads in
646 up to a page from the file and stores it in the "value"
647 field in the attribute.
649 Arguments: struct sysfs_attribute *sysattr Attribute to read
651 Returns: 0 with success.
652 -1 with error. Errno will be set with error, returning
653 - EINVAL for invalid arguments
655 Prototype: int sysfs_read_attribute(struct sysfs_attribute *sysattr)
656 -------------------------------------------------------------------------------
658 -------------------------------------------------------------------------------
659 Name: sysfs_write_attribute
661 Description: Writes to the supplied attribute. Function validates if the
662 given attribute is writable, and writes the new value to the
663 attribute. Value to write as well as its length is user
664 supplied. In case the length written is not equal to the
665 length requested to be written, the original value is
666 restored and an error is returned.
668 Arguments: struct sysfs_attribute *sysattr Attribute to write to
669 const char *new_value sysattr's new value
670 size_t len Length of "new_value"
672 Returns: 0 with success.
673 -1 with error. Errno will be set with error, returning
674 - EINVAL for invalid arguments
676 Prototype: int sysfs_write_attribute(struct sysfs_attribute *sysattr,
677 const char *new_value, size_t len)
678 -------------------------------------------------------------------------------
680 -------------------------------------------------------------------------------
681 Name: sysfs_read_attribute_value
683 Description: Given a path to a specific attribute, function reads and
684 returns its value to the supplied value buffer.
686 Arguments: const char *attrpath Attribute path to read
687 char *value Buffer to read in attribute's value
688 size_t vsize Size of buffer
690 Returns: 0 with success.
691 -1 with error. Errno will be set with error, returning
692 - EINVAL for invalid arguments
694 Prototype: int sysfs_read_attribute_value(const char *attrpath,
695 char *value, size_t vsize)
696 -------------------------------------------------------------------------------
698 -------------------------------------------------------------------------------
699 Name: sysfs_get_value_from_attributes
701 Description: Function takes a single or linked list of sysfs attribute
702 structures and returns the value of the specified attribute
705 Arguments: struct dlist *attr Attribute list to search through
706 const char *name Name of attribute whose value
709 Returns: char * attribute value with success.
710 NULL with error. Errno will be set with error, returning
711 - EINVAL for invalid arguments
713 Prototype: char *sysfs_get_value_from_attributes
714 (struct sysfs_attribute *attr, const char *name)
715 -------------------------------------------------------------------------------
717 -------------------------------------------------------------------------------
718 Name: sysfs_get_directory_attribute
720 Description: Function walks the list of attributes for the given sysfs
721 directory and returns the sysfs_attribute structure for
722 the specified attribute name.
724 Arguments: struct sysfs_directory *dir Directory in which to search
725 char *attrname Attribute name to look for
727 Returns: struct sysfs_attribute on success.
728 NULL with error. Errno will be set with error, returning
729 - EINVAL for invalid arguments
731 Prototype: struct sysfs_attribute *sysfs_get_directory_attribute
732 (struct sysfs_directory *dir, char *attrname)
733 -------------------------------------------------------------------------------
739 Sysfs contains many symbolic links, like bus links to bus devices. Libsysfs
740 treats links differently than directories due to processing differences. A
741 link in the /sys/bus/"busname"/devices/ directory indicates a device in the
742 /sys/devices directory. Through links we give the functionality to know
743 what is and what isn't a link and the ability to query the links target.
745 -------------------------------------------------------------------------------
746 Name: sysfs_open_link
748 Description: Opens a directory link.
750 Arguments: const char *linkpath Path to link
752 Returns: struct sysfs_link * with success.
753 NULL with error. Errno will be set with error, returning
754 - EINVAL for invalid arguments
756 Prototype: struct sysfs_link *sysfs_open_link(const char *linkpath)
757 -------------------------------------------------------------------------------
759 -------------------------------------------------------------------------------
760 Name: sysfs_close_link
762 Description: Closes a directory link structure.
764 Arguments: struct sysfs_link *ln Link to close
766 Prototype: void sysfs_close_link(struct sysfs_link *ln)
767 -------------------------------------------------------------------------------
769 -------------------------------------------------------------------------------
770 Name: sysfs_read_dir_links
772 Description: Reads the given sysfs_directory to create a list of links.
774 Arguments: struct sysfs_directory *sysdir sysfs_directory whose
777 Returns: struct dlist * of links with success
778 NULL with error. Errno will be set on error, returning EINVAL
779 for invalid arguments
781 Prototype: struct dlist *sysfs_read_dir_links
782 (struct sysfs_directory *sysdir)
783 -------------------------------------------------------------------------------
785 -------------------------------------------------------------------------------
786 Name: sysfs_get_dir_links
788 Description: Returns a list of links for the given sysfs_directory.
790 Arguments: struct sysfs_directory *sysdir sysfs_directory whose
791 list of links to return
793 Returns: struct dlist * of links with success
794 NULL with error. Errno will be set on error, returning EINVAL
795 for invalid arguments
797 Prototype: struct dlist *sysfs_read_dir_links
798 (struct sysfs_directory *sysdir)
799 -------------------------------------------------------------------------------
801 -------------------------------------------------------------------------------
802 Name: sysfs_get_directory_link
804 Description: Function walks the list of links for the given sysfs directory
805 and returns the sysfs_link structure for the specified link
808 Arguments: struct sysfs_directory *dir Directory in which to search
809 char *linkname Link name to look for
811 Returns: struct sysfs_link * with success.
812 NULL with error. Errno will be set with error, returning
813 - EINVAL for invalid arguments
815 Prototype: struct sysfs_link *sysfs_get_directory_link
816 (struct sysfs_directory *dir, char *linkname)
817 -------------------------------------------------------------------------------
819 -------------------------------------------------------------------------------
820 Name: sysfs_get_subdirectory_link
822 Description: Function walks the list of links for the given sysfs directory
823 and its subdirectories returns the sysfs_link structure for
824 the specified link name.
826 Arguments: struct sysfs_directory *dir Directory in which to search
827 char *linkname Link name to look for
829 Returns: struct sysfs_link * with success.
830 NULL with error. Errno will be set with error, returning
831 - EINVAL for invalid arguments
833 Prototype: struct sysfs_link *sysfs_get_subdirectory_link
834 (struct sysfs_directory *dir, char *linkname)
835 -------------------------------------------------------------------------------
837 -------------------------------------------------------------------------------
838 Name: sysfs_refresh_dir_links
840 Description: Given a list sysfs_directory, this function refreshes the list
841 of links under the given directory.
843 Arguments: struct sysfs_directory *sysdir sysfs_ directory whose
844 links list to refresh
846 Returns: 0 with success.
847 1 with error. Errno will be set on error, returning EINVAL
848 for invalid arguments
850 Prototype: int sysfs_refresh_dir_links(struct sysfs_directory *sysdir)
851 -------------------------------------------------------------------------------
854 6.3.3 Directory Functions
855 -------------------------
857 Sysfs directories can represent every directory under sysfs. The structures
858 keep track of subdirectories, links, and files. Like opendir, readdir, and
859 closedir, libsysfs provides open, read, and close functions for working with
860 sysfs directories. Open creates the sysfs_directory structure. Read reads in
861 its contents - like subdirectories, links, and files. Close cleans it all
864 -------------------------------------------------------------------------------
865 Name: sysfs_open_directory
867 Description: Opens a sysfs directory at a specific path
869 Arguments: const char *path Directory path to open
871 Returns: struct sysfs_directory * with success.
872 NULL with error. Errno will be set with error, returning
873 - EINVAL for invalid arguments
875 Prototype: struct sysfs_directory *sysfs_open_directory(const char *path)
876 -------------------------------------------------------------------------------
878 -------------------------------------------------------------------------------
879 Name: sysfs_close_directory
881 Description: Closes specific directory, its subdirectories, links, and
884 Arguments: struct sysfs_directory *sysdir Directory to close
886 Prototype: void sysfs_close_directory(struct sysfs_directory *sysdir)
887 -------------------------------------------------------------------------------
889 -------------------------------------------------------------------------------
890 Name: sysfs_read_dir_subdirs
892 Description: Reads the given sysfs_directory to create a list of subdirs.
894 Arguments: struct sysfs_directory *sysdir sysfs_directory whose
895 subdirs have to be read
897 Returns: struct dlist * of links with success
898 NULL with error. Errno will be set on error, returning EINVAL
899 for invalid arguments
901 Prototype: struct dlist *sysfs_read_dir_subdirs
902 (struct sysfs_directory *sysdir)
903 -------------------------------------------------------------------------------
905 -------------------------------------------------------------------------------
906 Name: sysfs_read_directory
908 Description: Read the supplied directory. Reading fills in the directory's
909 contents like subdirectories, links, and attributes.
911 Arguments: struct sysfs_directory *sysdir Directory to read
913 Returns: 0 with success.
914 -1 with error. Errno will be set with error, returning
915 - EINVAL for invalid arguments
917 Prototype: int sysfs_read_directory(struct sysfs_directory *sysdir)
918 -------------------------------------------------------------------------------
920 -------------------------------------------------------------------------------
921 Name: sysfs_read_all_subdirs
923 Description: Reads all subdirs under a given supplied directory.
925 Arguments: struct sysfs_directory *sysdir Directory to read
927 Returns: 0 with success.
928 -1 with error. Errno will be set with error, returning
929 - EINVAL for invalid arguments
931 Prototype: int sysfs_read_all_subdirs(struct sysfs_directory *sysdir)
932 -------------------------------------------------------------------------------
934 -------------------------------------------------------------------------------
935 Name: sysfs_get_subdirectory
937 Description: Function walks the directory tree for the given directory and
938 returns a sysfs_directory structure for the specified directory
941 Arguments: struct sysfs_directory *dir Directory in which to search
942 char *subname Name of directory to look for
944 Returns: struct sysfs_directory with success.
945 NULL with error. Errno will be set with error, returning
946 - EINVAL for invalid arguments
948 Prototype: struct sysfs_directory *sysfs_get_subdirectory
949 (struct sysfs_directory *dir, char *subname)
950 -------------------------------------------------------------------------------
952 -------------------------------------------------------------------------------
953 Name: sysfs_get_dir_subdirs
955 Description: Returns a list of subdirs for the given sysfs_directory.
957 Arguments: struct sysfs_directory *sysdir sysfs_directory whose
958 subdirectories list to return
960 Returns: struct dlist * of directories with success
961 NULL with error. Errno will be set on error, returning EINVAL
962 for invalid arguments
964 Prototype: struct dlist *sysfs_read_dir_subdirs
965 (struct sysfs_directory *sysdir)
966 -------------------------------------------------------------------------------
968 -------------------------------------------------------------------------------
969 Name: sysfs_refresh_dir_subdirs
971 Description: Given a list sysfs_directory, this function refreshes the list
972 of subdirectories under the given directory.
974 Arguments: struct sysfs_directory *sysdir sysfs_ directory whose
975 subdirs list to refresh
977 Returns: 0 with success.
978 1 with error. Errno will be set on error, returning EINVAL
979 for invalid arguments
981 Prototype: int sysfs_refresh_dir_subdirs(struct sysfs_directory *sysdir)
982 -------------------------------------------------------------------------------
988 The library provides a functions for viewing buses represented in sysfs.
989 The sysfs_open_bus opens a bus in the /sys/bus directory, such as "pci",
990 "usb", or "scsi". The open command returns a sysfs_bus structure that
991 contains a list of the bus' devices. The sysfs_close_bus function is
992 used to clean up the bus structure. Given a device or a driver,
993 functions are provided to determine what bus they are on.
995 -------------------------------------------------------------------------------
998 Description: Function opens up one of the buses represented in sysfs in
999 the /sys/bus directory. It returns a sysfs_bus structure
1000 that includes a list of bus devices and drivers.
1002 Arguments: const char *name Bus name to open, like "pci"...
1004 Returns: struct sysfs_bus * with success
1005 NULL with error. Errno will be set with error, returning
1006 - EINVAL for invalid arguments
1008 Prototype: struct sysfs_bus *sysfs_open_bus(const char *name)
1009 -------------------------------------------------------------------------------
1011 -------------------------------------------------------------------------------
1012 Name: sysfs_close_bus
1014 Description: Function closes up the sysfs_bus structure including its
1015 devices, drivers, and directory.
1017 Arguments: sysfs_bus *bus Bus structure to close
1019 Prototype: void sysfs_close_bus(struct sysfs_bus *bus)
1020 -------------------------------------------------------------------------------
1022 -------------------------------------------------------------------------------
1023 Name: sysfs_get_bus_devices
1025 Description: Function returns a list of devices that are registered with
1028 Arguments: struct sysfs_bus *bus Bus whose devices list to return
1030 Returns: struct dlist * of sysfs_devices on success
1031 NULL with error. Errno will be sent with error, returning
1032 - EINVAL for invalid arguments
1034 Prototype: struct dlist *sysfs_get_bus_devices(struct sysfs_bus *bus)
1035 -------------------------------------------------------------------------------
1037 -------------------------------------------------------------------------------
1038 Name: sysfs_get_bus_drivers
1040 Description: Function returns a list of drivers that are registered with
1043 Arguments: struct sysfs_bus *bus Bus whose drivers list to return
1045 Returns: struct dlist * of sysfs_drivers on success
1046 NULL with error. Errno will be sent with error, returning
1047 - EINVAL for invalid arguments
1049 Prototype: struct dlist *sysfs_get_bus_drivers(struct sysfs_bus *bus)
1050 -------------------------------------------------------------------------------
1052 -------------------------------------------------------------------------------
1053 Name: sysfs_get_bus_device
1055 Description: Function takes a sysfs_bus structure(obtained on a successful
1056 return from a sysfs_open_bus() call) and looks for the given
1057 device on this bus. On success, it returns a sysfs_device
1058 structure corresponding to the device.
1060 Arguments: struct sysfs_bus *bus Bus structure on which to search
1061 char *id Device to look for
1063 Returns: struct sysfs_device * with success
1064 NULL with error. Errno will be set with error, returning
1065 - EINVAL for invalid arguments
1067 Prototype: struct sysfs_device *sysfs_get_bus_device
1068 (struct sysfs_bus *bus, char *id)
1069 -------------------------------------------------------------------------------
1071 -------------------------------------------------------------------------------
1072 Name: sysfs_get_bus_driver
1074 Description: Function takes a sysfs_bus structure (obtained on a successful
1075 return from a sysfs_open_bus() call) and looks for the given
1076 driver on this bus. On success, it returns a sysfs_driver
1077 structure corresponding to the driver.
1079 Arguments: struct sysfs_bus *bus Bus structure on which to search
1080 char *drvname Driver to look for
1082 Returns: struct sysfs_driver * with success
1083 NULL with error. Errno will be set with error, returning
1084 - EINVAL for invalid arguments
1086 Prototype: struct sysfs_device *sysfs_get_bus_driver
1087 (struct sysfs_bus *bus, char *drvname)
1088 -------------------------------------------------------------------------------
1090 -------------------------------------------------------------------------------
1091 Name: sysfs_get_bus_attributes
1093 Description: Function takes a sysfs_bus structure and returns a list of
1094 attributes for the bus.
1096 Arguments: struct sysfs_bus *bus Bus for which attributes are required
1098 Returns: struct dlist * of attributes with success
1099 NULL with error. Errno will be set with error, returning
1100 - EINVAL for invalid arguments
1102 Prototype: struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus)
1103 -------------------------------------------------------------------------------
1105 -------------------------------------------------------------------------------
1106 Name: sysfs_get_bus_attribute
1108 Description: Function takes a sysfs_bus structure and looks for the required
1109 attribute on the bus. On success, it returns a sysfs_attribute
1110 structure corresponding to the given attribute.
1112 Arguments: struct sysfs_bus *bus Bus structure on which to search
1113 char *attrname Attribute to look for
1115 Returns: struct sysfs_attribute * with success
1116 NULL with error. Errno will be set with error, returning
1117 - EINVAL for invalid arguments
1119 Prototype: struct sysfs_attribute *sysfs_get_bus_attribute
1120 (struct sysfs_bus *bus, char *attrname)
1121 -------------------------------------------------------------------------------
1123 -------------------------------------------------------------------------------
1124 Name: sysfs_refresh_bus_attributes
1126 Description: Function refreshes the list of attributes for a given sysfs_bus
1128 Arguments: struct sysfs_bus *bus Bus whose attributes list to refresh
1130 Returns: struct dlist * of attributes with success
1131 NULL with error. Errno will be set with error, returning
1132 - EINVAL for invalid arguments
1134 Prototype: struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus)
1135 -------------------------------------------------------------------------------
1137 -------------------------------------------------------------------------------
1138 Name: sysfs_find_driver_bus
1140 Description: Given the name of a driver, this function finds the name of the
1141 bus the driver is on
1143 Arguments: const char *driver Name of the driver to look for
1144 char *busname Buffer to return the bus name
1145 size_t bsize Size of the "busname" buffer
1147 Returns: 0 with success.
1148 -1 with error. Errno will be set with error, returning
1149 - EINVAL for invalid arguments
1151 Prototype: int sysfs_find_driver_bus(const char *driver,
1152 char *busname, size_t bsize)
1153 -------------------------------------------------------------------------------
1159 Libsysfs provides functions to open sysfs classes and their class devices.
1160 These functions too operate with open and close, close must be called to
1161 clean up the class structures. Given a class device name, functions are
1162 provided to determine what class they belong to. Once a class device
1163 name and the class it belongs to is known, a function to open the
1164 class device is provided. This method can be used when details of
1165 a single class device is required.
1167 -------------------------------------------------------------------------------
1168 Name: sysfs_open_class
1170 Description: Function opens up one of the classes represented in sysfs in
1171 the /sys/class directory. It returns a sysfs_class structure
1172 that includes a list of class devices.
1174 Arguments: const char *name Class name to open, like "net"..
1176 Returns: struct sysfs_class * with success
1177 NULL with error. Errno will be set with error, returning
1178 - EINVAL for invalid arguments
1180 Prototype: struct sysfs_class *sysfs_open_class(const char *name)
1181 -------------------------------------------------------------------------------
1183 -------------------------------------------------------------------------------
1184 Name: sysfs_close_class
1186 Description: Function closes up the sysfs_class structure including its
1189 Arguments: sysfs_class *cls Class structure to close
1191 Prototype: void sysfs_close_class(struct sysfs_class *cls);
1192 -------------------------------------------------------------------------------
1194 -------------------------------------------------------------------------------
1195 Name: sysfs_open_class_device_path
1197 Description: Function opens up one of the class devices represented in
1198 sysfs in sysfs/class/"class"/ directory. It returns a
1199 sysfs_class_device structure.
1201 Arguments: const char *path Path to class device
1203 Returns: struct sysfs_class_device * with success
1204 NULL with error. Errno will be set with error, returning
1205 - EINVAL for invalid arguments
1207 Prototype: struct sysfs_class_device *sysfs_open_class_device_path
1209 -------------------------------------------------------------------------------
1211 -------------------------------------------------------------------------------
1212 Name: sysfs_close_class_device
1214 Description: Function closes up the sysfs_class_device structure.
1216 Arguments: sysfs_class_device *dev Class device structure to close
1218 Prototype: void sysfs_close_class_device(struct sysfs_class_device *dev)
1219 -------------------------------------------------------------------------------
1221 -------------------------------------------------------------------------------
1222 Name: sysfs_get_class_device
1224 Description: Function takes a sysfs_class structure(obtained on a successful
1225 return from a sysfs_open_class() call) and looks for the given
1226 device in this class. On success, it returns a sysfs_class_device
1227 structure corresponding to the class device.
1229 Arguments: struct sysfs_class *cls Class on which to search
1230 char *name Class device "name" to look for
1232 Returns: struct sysfs_class_device * with success
1233 NULL with error. Errno will be set with error, returning
1234 - EINVAL for invalid arguments
1236 Prototype: struct sysfs_class_device *sysfs_get_class_device
1237 (struct sysfs_class *cls, char *name)
1238 -------------------------------------------------------------------------------
1240 -------------------------------------------------------------------------------
1241 Name: sysfs_get_class_devices
1243 Description: Function returns a list of class devices for the given class.
1245 Arguments: struct sysfs_class *cls Class whose class device list
1248 Returns: struct dlist * of sysfs_class_devices on success
1249 NULL with error. Errno will be set with error, returning
1250 - EINVAL for invalid arguments
1252 Prototype: struct dlist *sysfs_get_class_devices(struct sysfs_class *cls)
1253 -------------------------------------------------------------------------------
1255 -------------------------------------------------------------------------------
1256 Name: sysfs_open_class_device
1258 Description: Given the name of the class on which to look for, this function
1259 locates a given class device and returns a sysfs_class_device
1260 structure corresponding to the requested class device.
1263 1. The sysfs_class_device structure obtained upon successful
1264 return from this function has to be closed by calling
1265 sysfs_close_class_device().
1266 2. Class this device belongs to must be known prior to calling
1269 Arguments: const char *classname Class on which to search
1270 char *name Class device "name" to open
1272 Returns: struct sysfs_class_device * with success
1273 NULL with error. Errno will be set with error, returning
1274 - EINVAL for invalid arguments
1276 Prototype: struct sysfs_class_device *sysfs_open_class_device
1277 (const char *classname, char *name)
1278 -------------------------------------------------------------------------------
1280 -------------------------------------------------------------------------------
1281 Name: sysfs_get_classdev_device
1283 Description: Function returns the sysfs_device reference (if present) for the
1286 Arguments: struct sysfs_class_device *clsdev Class device whose
1287 sysfs_device reference
1290 Returns: struct sysfs_device * on success
1291 NULL with error. Errno will be set with error, returning
1292 - EINVAL for invalid arguments
1294 Prototype: struct sysfs_device *sysfs_get_classdev_device
1295 (struct sysfs_class_device *clsdev)
1296 -------------------------------------------------------------------------------
1298 -------------------------------------------------------------------------------
1299 Name: sysfs_get_classdev_driver
1301 Description: Function returns the sysfs_driver reference (if present) for
1302 the given class device.
1304 Arguments: struct sysfs_class_device *clsdev Class device whose
1305 sysfs_driver reference
1308 Returns: struct sysfs_driver * on success
1309 NULL with error. Errno will be set with error, returning
1310 - EINVAL for invalid arguments
1312 Prototype: struct sysfs_driver *sysfs_get_classdev_driver
1313 (struct sysfs_class_device *clsdev)
1314 -------------------------------------------------------------------------------
1316 -------------------------------------------------------------------------------
1317 Name: sysfs_get_classdev_parent
1319 Description: Function returns the sysfs_class_device reference for the
1320 parent (if present) of the given class device.
1322 Arguments: struct sysfs_class_device *clsdev Class device whose
1326 Returns: struct sysfs_class_device * on success
1327 NULL with error. Errno will be set with error, returning
1328 - EINVAL for invalid arguments
1330 Prototype: struct sysfs_class_device *sysfs_get_classdev_parent
1331 (struct sysfs_class_device *clsdev)
1332 -------------------------------------------------------------------------------
1334 -------------------------------------------------------------------------------
1335 Name: sysfs_get_classdev_attributes
1337 Description: Function takes a sysfs_class_device structure and returns a
1338 list of attributes for the class device.
1340 Arguments: struct sysfs_class_device *cdev Class device for which
1341 attributes are required
1343 Returns: struct dlist * of attributes with success
1344 NULL with error. Errno will be set with error, returning
1345 - EINVAL for invalid arguments
1347 Prototype: struct dlist *sysfs_get_classdev_attributes
1348 (struct sysfs_class_device *cdev)
1349 -------------------------------------------------------------------------------
1351 -------------------------------------------------------------------------------
1352 Name: sysfs_get_classdev_attr
1354 Description: Searches supplied class device's attributes by name and returns
1357 Arguments: struct sysfs_class_device *clsdev Device to search
1358 const char *name Attribute name to find
1360 Returns: struct sysfs_attribute * with success
1361 NULL with error. Errno will be set with error, returning
1362 - EINVAL for invalid arguments
1364 Prototype: struct sysfs_attribute *sysfs_get_classdev_attr
1365 (struct sysfs_class_device *clsdev, const char *name)
1366 -------------------------------------------------------------------------------
1368 -------------------------------------------------------------------------------
1369 Name: sysfs_refresh_classdev_attributes
1371 Description: Function refreshes the list of attributes for a given
1374 Arguments: struct sysfs_class_device *cdev Class device whose attributes
1377 Returns: struct dlist * of attributes with success
1378 NULL with error. Errno will be set with error, returning
1379 - EINVAL for invalid arguments
1381 Prototype: struct dlist *sysfs_get_classdev_attributes
1382 (struct sysfs_class_device *cdev)
1383 -------------------------------------------------------------------------------
1385 -------------------------------------------------------------------------------
1386 Name: sysfs_open_classdev_attr
1388 Description: Function takes as arguments, a the name of the class, the class
1389 device name and the name of the required attribute.
1392 1. The struct sysfs_attribute * obtained upon successful
1393 return from this function has to be closed by making
1394 a call to sysfs_close_attribute()
1396 Arguments: char *classname Class name on which to search
1397 char *dev Name of the class device
1398 char *attrib Attribute to open
1400 Returns: struct sysfs_attribute * with success.
1401 NULL with error. Errno will be set with error, returning
1402 - EINVAL for invalid arguments
1404 Prototype: struct sysfs_attribute *sysfs_write_classdev_attr
1405 (const char *classname, const char *dev,
1407 -------------------------------------------------------------------------------
1410 6.6 Device Functions
1411 --------------------
1413 Devices represent everything in sysfs under /sys/devices, which is a
1414 hierarchical view of system devices. Besides the expected open and
1415 close functions, libsysfs provides open and close functions for
1416 root devices. These functions recursively open or close a device
1417 and all of its children.
1419 -------------------------------------------------------------------------------
1420 Name: sysfs_open_device_path
1422 Description: Opens up a device at a specific path. It opens the device's
1423 directory, reads the directory, and returns a sysfs_device
1426 Arguments: const char *path Path to device
1428 Returns: struct sysfs_device * with success
1429 NULL with error. Errno will be set with error, returning
1430 - EINVAL for invalid arguments
1432 Prototype: struct sysfs_device *sysfs_open_device_path(const char *path)
1433 -------------------------------------------------------------------------------
1435 -------------------------------------------------------------------------------
1436 Name: sysfs_close_device
1438 Description: Function closes up the sysfs_device structure.
1440 Arguments: sysfs_device *dev Device structure to close
1442 Prototype: void sysfs_close_device(struct sysfs_device *dev)
1443 -------------------------------------------------------------------------------
1445 -------------------------------------------------------------------------------
1446 Name: sysfs_open_root_device
1448 Description: Function opens up one of the root devices represented in sysfs
1449 in the /sys/devices directory. It returns a sysfs_root_device
1450 structure that includes a list of devices in the tree.
1452 Arguments: const char *name Name of the root device to open
1454 Returns: struct sysfs_root_device * with success
1455 NULL with error. Errno will be set with error, returning
1456 - EINVAL for invalid arguments
1458 Prototype: struct sysfs_device *sysfs_open_root_device(const char *name)
1459 -------------------------------------------------------------------------------
1461 -------------------------------------------------------------------------------
1462 Name: sysfs_close_root_device
1464 Description: Function closes up the sysfs_root_device structure including the
1465 devices in the root device tree.
1467 Arguments: sysfs_device *root Root device structure to close
1469 Prototype: void sysfs_close_root_device(struct sysfs_root_device *root)
1470 -------------------------------------------------------------------------------
1472 -------------------------------------------------------------------------------
1473 Name: sysfs_open_device_tree
1475 Description: Function opens up the device tree at the specified path.
1477 Arguments: const char *path Path at which to open the device tree
1479 Returns: struct sysfs_device * with success
1480 NULL with error, Errno will be set with error, returning
1481 - EINVAL for invalid arguments
1483 Prototype: struct sysfs_device *sysfs_open_device_tree(const char *path)
1484 -------------------------------------------------------------------------------
1486 -------------------------------------------------------------------------------
1487 Name: sysfs_close_device_tree
1489 Description: Function closes the device tree originating at the given
1492 Arguments: struct sysfs_device *devroot Device from which the device
1493 tree has to be closed
1495 Prototype: void sysfs_close_device_tree(struct sysfs_device *devroot)
1496 -------------------------------------------------------------------------------
1498 -------------------------------------------------------------------------------
1499 Name: sysfs_get_device_parent
1501 Description: Function returns the sysfs_device reference for the parent
1502 (if present) of the given sysfs_device.
1504 Arguments: struct sysfs_device *dev sysfs_device whose parent
1505 reference is required
1507 Returns: struct sysfs_device * on success
1508 NULL with error. Errno will be set with error, returning
1509 - EINVAL for invalid arguments
1511 Prototype: struct sysfs_device *sysfs_get_device_parent
1512 (struct sysfs_device *dev)
1513 -------------------------------------------------------------------------------
1515 -------------------------------------------------------------------------------
1516 Name: sysfs_get_root_devices
1518 Description: Function returns a list of devices under the given root device.
1520 Arguments: struct sysfs_root_device *root sysfs_root_device whose devices
1523 Returns: struct dlist * of sysfs_devices on success
1524 NULL with error. Errno will be set with error, returning
1525 - EINVAL for invalid arguments
1527 Prototype: struct dlist *sysfs_get_root_devices
1528 (struct sysfs_root_device *root)
1529 -------------------------------------------------------------------------------
1531 -------------------------------------------------------------------------------
1532 Name: sysfs_get_device_attr
1534 Description: Searches supplied device's attributes by name and returns
1537 Arguments: struct sysfs_device *dev Device to search
1538 const char *name Attribute name to find
1540 Returns: struct sysfs_attribute * with success
1541 NULL with error. Errno will be set with error, returning
1542 - EINVAL for invalid arguments
1544 Prototype: struct sysfs_attribute *sysfs_get_device_attr
1545 (struct sysfs_device *dev, const char *name)
1546 -------------------------------------------------------------------------------
1548 -------------------------------------------------------------------------------
1549 Name: sysfs_get_device_attributes
1551 Description: Function takes a sysfs_device structure and returns a list
1552 of attributes for the device.
1554 Arguments: struct sysfs_device *device Device for which
1555 attributes are required
1557 Returns: struct dlist * of attributes with success
1558 NULL with error. Errno will be set with error, returning
1559 - EINVAL for invalid arguments
1561 Prototype: struct dlist *sysfs_get_device_attributes
1562 (struct sysfs_device *device)
1563 -------------------------------------------------------------------------------
1565 -------------------------------------------------------------------------------
1566 Name: sysfs_refresh_device_attributes
1568 Description: Function refreshes the list of attributes for a given
1571 Arguments: struct sysfs_device *device Device whose attributes list
1574 Returns: struct dlist * of attributes with success
1575 NULL with error. Errno will be set with error, returning
1576 - EINVAL for invalid arguments
1578 Prototype: struct dlist *sysfs_refresh_device_attributes
1579 (struct sysfs_device *device)
1580 -------------------------------------------------------------------------------
1582 -------------------------------------------------------------------------------
1583 Name: sysfs_open_device
1585 Description: Given the name of the bus on which to look for, this function
1586 locates a given device and returns a sysfs_device structure
1587 corresponding to the requested device.
1589 Arguments: const char *bus Bus on which to search
1590 const char *bus_id Device to look for
1592 Returns: struct sysfs_device * with success
1593 NULL with error. Errno will be set with error, returning
1594 - EINVAL for invalid arguments
1596 Prototype: struct sysfs_device *sysfs_open_device
1597 (const char *bus, const char *bus_id)
1598 -------------------------------------------------------------------------------
1600 -------------------------------------------------------------------------------
1601 Name: sysfs_get_device_bus
1603 Description: Given a sysfs_device, this function fills in the bus this
1604 device is on in the sysfs_device->bus field.
1606 Arguments: struct sysfs_device *dev Device whose bus name to find
1608 Returns: 0 with success.
1609 -1 with error. Errno will be set with error, returning
1610 - EINVAL for invalid arguments
1612 Prototype: int sysfs_get_device_bus(struct sysfs_device *dev)
1613 -------------------------------------------------------------------------------
1615 -------------------------------------------------------------------------------
1616 Name: sysfs_open_device_attr
1618 Description: Function takes as arguments, the bus on which to search for a
1619 device, and an attribute of the device to open.
1622 1. The struct sysfs_attribute * obtained upon successful
1623 return from this function has to be closed by making
1624 a call to sysfs_close_attribute()
1626 Arguments: char *bus Bus on which to search
1627 char *bus_id Device to look for
1628 char *attrib Name of the attribute to open
1630 Returns: struct sysfs_attribute * with success.
1631 NULL with error. Errno will be set with error, returning
1632 - EINVAL for invalid arguments
1634 Prototype: struct sysfs_attribute *sysfs_open_device_attr
1635 (const char *bus, const char *bus_id, const char *attrib)
1636 -------------------------------------------------------------------------------
1639 6.7 Driver Functions
1640 --------------------
1642 Drivers are represented in sysfs under the /sys/bus/xxx/drivers (xxx being
1643 the bus type, such as "pci", "usb, and so on). Functions are provided to
1644 open and close drivers.
1646 -------------------------------------------------------------------------------
1647 Name: sysfs_open_driver_path
1649 Description: Opens driver at specific path.
1651 Arguments: const char *path Path to driver
1653 Returns: struct sysfs_driver * with success
1654 NULL with error. Errno will be set with error, returning
1655 - EINVAL for invalid arguments
1657 Prototype: struct sysfs_driver *sysfs_open_driver_path(const char *path)
1658 -------------------------------------------------------------------------------
1660 -------------------------------------------------------------------------------
1661 Name: sysfs_close_driver
1663 Description: Closes and cleans up sysfs_driver structure.
1665 Arguments: sysfs_driver *driver Driver structure to close
1667 Prototype: void sysfs_close_driver(struct sysfs_driver *driver)
1668 -------------------------------------------------------------------------------
1670 -------------------------------------------------------------------------------
1671 Name: sysfs_get_driver_devices
1673 Description: Function returns a list of devices that use this driver.
1675 Arguments: struct sysfs_driver *driver Driver whose devices list is
1678 Returns: struct dlist * of sysfs_devices on success
1679 NULL with error. Errno will be set with error, returning
1680 - EINVAL for invalid arguments
1682 Prototype: struct dlist *sysfs_get_driver_devices
1683 (struct sysfs_driver *driver)
1684 -------------------------------------------------------------------------------
1686 -------------------------------------------------------------------------------
1687 Name: sysfs_refresh_driver_devices
1689 Description: Function refreshes the list of devices that use this driver.
1691 Arguments: struct sysfs_driver *driver Driver whose devices list is
1692 required to be refreshed
1694 Returns: struct dlist * of sysfs_devices on success
1695 NULL with error. Errno will be set with error, returning
1696 - EINVAL for invalid arguments
1698 Prototype: struct dlist *sysfs_refresh_driver_devices
1699 (struct sysfs_driver *driver)
1700 -------------------------------------------------------------------------------
1702 -------------------------------------------------------------------------------
1703 Name: sysfs_get_driver_device
1705 Description: Function returns a sysfs_device reference for the device with
1706 "name" that uses this driver
1708 Arguments: struct sysfs_driver *driver Driver on which to search
1709 const char *name Name of the device to look for
1711 Returns: struct sysfs_device * corresponding to "name" on success
1712 NULL with error. Errno will be set with error, returning
1713 - EINVAL for invalid arguments
1715 Prototype: struct dlist *sysfs_get_driver_device
1716 (struct sysfs_driver *driver, const char *name)
1717 -------------------------------------------------------------------------------
1719 -------------------------------------------------------------------------------
1720 Name: sysfs_get_driver_attr
1722 Description: Searches supplied driver's attributes by name and returns
1725 Arguments: struct sysfs_driver *drv Driver to search
1726 const char *name Attribute name to find
1728 Returns: struct sysfs_attribute * with success
1729 NULL with error. Errno will be set with error, returning
1730 - EINVAL for invalid arguments
1732 Prototype: struct sysfs_attribute *sysfs_get_driver_attr
1733 (struct sysfs_driver *drv, const char *name)
1734 -------------------------------------------------------------------------------
1736 -------------------------------------------------------------------------------
1737 Name: sysfs_get_driver_attributes
1739 Description: Function takes a sysfs_driver structure and returns a list
1740 of attributes for the driver.
1742 Arguments: struct sysfs_driver *driver Driver for which attributes
1745 Returns: struct dlist * of attributes with success
1746 NULL with error. Errno will be set with error, returning
1747 - EINVAL for invalid arguments
1749 Prototype: struct dlist *sysfs_get_driver_attributes
1750 (struct sysfs_driver *driver)
1751 -------------------------------------------------------------------------------
1753 -------------------------------------------------------------------------------
1754 Name: sysfs_refresh_driver_attributes
1756 Description: Function refreshes the list of attributes for a given
1759 Arguments: struct sysfs_driver *driver Driver whose attributes list
1762 Returns: struct dlist * of attributes with success
1763 NULL with error. Errno will be set with error, returning
1764 - EINVAL for invalid arguments
1766 Prototype: struct dlist *sysfs_refresh_driver_attributes
1767 (struct sysfs_driver *driver)
1768 -------------------------------------------------------------------------------
1770 -------------------------------------------------------------------------------
1771 Name: sysfs_open_driver
1773 Description: Given the name of the bus on which to look for, this function
1774 locates a given driver and returns a sysfs_driver structure
1775 corresponding to the requested device.
1778 1. The sysfs_driver structure obtained upon successful return
1779 from this function has to be closed by calling
1780 sysfs_close_driver_by_name().
1781 2. Bus on which to look for this driver should be known prior
1782 to calling this function. Use sysfs_find_driver_bus()
1785 Arguments: const char *bus_name Bus on which to search
1786 const char *drv_name Driver name to look for
1788 Returns: struct sysfs_driver * with success
1789 NULL with error. Errno will be set with error, returning
1790 - EINVAL for invalid arguments
1792 Prototype: struct sysfs_driver *sysfs_open_driver(const char *bus_name,
1793 const char *drv_name)
1794 -------------------------------------------------------------------------------
1796 -------------------------------------------------------------------------------
1797 Name: sysfs_get_driver_links
1799 Description: Function returns a list of links for a given driver
1801 Arguments: struct sysfs_driver *driver Driver to get links from
1803 Returns: struct dlist * of links on success
1806 Prototype: struct dlist *sysfs_get_driver_links
1807 (struct sysfs_driver *driver)
1808 -------------------------------------------------------------------------------
1810 -------------------------------------------------------------------------------
1811 Name: sysfs_open_driver_attr
1813 Description: Function takes as arguments, the bus the driver is registered
1814 on, the driver name and the name of the attribute to open.
1817 1. The struct sysfs_attribute * obtained upon successful
1818 return from this function has to be closed by making
1819 a call to sysfs_close_attribute()
1821 Arguments: char *bus Bus on which driver is present
1822 char *drv Driver to look for
1823 char *attrib Name of the attribute to open
1825 Returns: struct sysfs_attribute * with success.
1826 NULL with error. Errno will be set with error, returning
1827 - EINVAL for invalid arguments
1829 Prototype: struct sysfs_attribute *sysfs_open_driver_attr
1830 (const char *bus, const char *drv, const char *attrib)
1831 -------------------------------------------------------------------------------
1837 Libsysfs uses (yet another) list implementation thanks to Eric J Bohm.
1840 7.1 Navigating a dlist
1841 ----------------------
1843 Some library functions return a dlist of devices/drivers/attributes, etc.
1844 To navigate the list returned the macro "dlist_for_each_data" is to be used.
1846 ------------------------------------------------------------------------------
1847 Function/Macro name: dlist_for_each_data
1849 Description: Walk the given list, returning a known data type/
1850 structure in each iteration.
1852 Arguments: struct dlist *list List pointer
1853 data_iterator Data type/structure variable
1854 contained in the list
1855 datatype Data type/structure contained
1858 Returns: On each iteration, "data_iterator" will contain a list
1859 element of "datatype"
1861 Usage example: The function sysfs_get_classdev_attributes() returns a
1862 dlist of attributes. To navigate the list:
1864 struct sysfs_attribute *attr = NULL;
1865 struct dlist *attrlist = NULL;
1869 attrlist = sysfs_get_classdev_attributes
1870 (struct sysfs_class_device *cdev)
1871 if (attrlist != NULL) {
1872 dlist_for_each_data(attrlist, attr,
1873 struct sysfs_attribute) {
1879 -------------------------------------------------------------------------------
1882 7.2 Custom sorting using dlist_sort_custom()
1883 --------------------------------------------
1885 As of release 1.2.0, libsysfs provides a new interface for custom sorting
1886 of dlists. The API dlist_sort_custom() has been added for this purpose.
1887 Applications that would like to define their own sorter function can now
1888 make use of this API.
1890 The sorter function must conform to the following prototype:
1892 int compare(void *a, void*b)
1894 dlist_sort_custom() expects that the compare function will:
1895 return >0 for a before b
1896 return <0 for b before a
1903 Accessing devices through libsysfs is supposed to mirror accessing devices
1904 in the filesystem it represents. Here's a typical order of operation:
1906 - get sysfs mount point
1907 - "open" sysfs category, ie. bus, class, or device
1908 - work with category
1909 - "close" sysfs category
1915 Version 1.0.0 of sysfsutils ships with a comprehensive testsuite. The testsuite
1916 shipped as part of the "test" directory of the sysfsutils source package,
1917 results in an executable "testlibsysfs" which will be installed in the
1918 /usr/local/bin directory. Some of the salient features of the testsuite are:
1920 a. Tests _every_ API exported by the library.
1921 b. Tests are performed for all possible combinations of input parameters.
1922 c. Detailed output is provided for the correct case.
1923 d. Facility to redirect output of the tests to a normal file.
1924 e. Number of iterations of tests can be specified.
1926 The testsuite comes with its own configuration file "libsysfs.conf" in the
1927 "test" directory. This file is used to generate a header file at the time
1928 the tests are built.
1930 To use the testsuite:
1932 a. Modify the variables libsysfs.conf file to appropriate values for your
1933 system. (The libsysfs.conf file contains comments describing what each
1934 variable stands for and, in some cases, how to determine an appropriate
1935 value for the system under test).
1937 b. Build and install the testsuite.
1939 c. Run the testsuite:
1941 testlibsysfs <number of iterations> <logfile>
1943 The default logfile is stdout.
1945 NOTE: If the libsysfs.conf file is changed, make sure to run "make clean" in
1946 the test directory and then a "make" for the changes to take effect.
1952 Libsysfs is meant to provide a stable application programming interface to
1953 sysfs. Applications can depend upon the library to access system devices
1954 and functions exposed through sysfs.