chiark / gitweb /
[PATCH] Update writing udev rules docs
[elogind.git] / docs / libsysfs.txt
1
2         System Utilities sysfs Library - libsysfs
3         =========================================
4
5 Version: 0.4.0 
6 December 16, 2003
7
8 Contents
9 --------
10 1. Introduction
11 2. Requirements
12 3. Definitions
13 4. Overview
14 5. Data Structures
15    5.1 Directory and Attribute Data Structures
16        5.1.1 Attribute Structure
17        5.1.2 Link 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
24 6. Functions
25    6.1 Utility Functions
26    6.2 Filesystem Functions
27        6.2.1 Attribute Functions
28        6.2.2 Directory Link Functions
29        6.2.3 Directory Functions
30    6.3 Bus Functions
31    6.4 Class Functions
32    6.5 Device Functions
33    6.6 Driver Functions
34 7. Navigating a dlist
35 8. Usage
36 9. Conclusion
37
38
39 1. Introduction
40 ---------------
41
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. 
47
48
49 2. Requirements
50 ---------------
51
52 The library must satisfy the following requirements:
53
54 - It must provide a stable programming interfaces that applications can
55   be built upon. 
56
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.
60
61 - It must provide access to all system devices and information exposed
62   by sysfs.
63
64 - It must provide a function to find sysfs' current mount point.
65
66 - It must provide a function for udev to retrieve a device's major and
67   minor numbers.
68
69
70 3. Definitions
71 --------------
72
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:
79
80         http://www.kernel.org/pub/linux/kernel/people/mochel/doc/
81
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:
87
88         http://www.kernel.org/pub/linux/utils/kernel/hotplug/
89
90
91 4. Overview
92 -----------
93
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.
102
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.
108
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.
115
116
117 5. Data Structures
118 ------------------
119
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.
125
126 The library will provide standard definitions for working with sysfs
127 and devices, here's some examples:
128
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_NAME        "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"
142
143 The library uses some definitions to mark maximum size of a sysfs name or
144 path length:
145
146 #define SYSFS_PATH_MAX          255
147 #define SYSFS_NAME_LEN          50
148 #define SYSFS_BUS_ID_SIZE       20
149
150
151 NOTE:
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).
157
158 5.1 Directory and Attribute Data Structures
159 -------------------------------------------
160
161 The library implements structures to represent sysfs directories, links, 
162 and files. 
163
164
165 5.1.1 Attribute Structure
166 -------------------------
167
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:
171
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];
178 };
179
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) 
183 and/or store(write). 
184
185
186 5.1.2 Link Structure
187 --------------------
188
189 Symbolic links are used in sysfs to link bus or class views with 
190 particular devices. 
191
192 struct sysfs_link {
193         unsigned char name[SYSFS_NAME_LEN];
194         unsigned char path[SYSFS_PATH_MAX];
195         unsigned char target[SYSFS_PATH_MAX];
196 };
197
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".
200
201
202 5.1.3 Directory Structure
203 -------------------------
204
205 The directory structure represents a sysfs directory:
206
207 struct sysfs_directory {
208         struct dlist *subdirs;
209         struct dlist *links;
210         struct dlist *attributes;
211         unsigned char name[SYSFS_NAME_LEN];
212         unsigned char path[SYSFS_PATH_MAX];
213 };
214
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.
220
221
222 5.2 Bus Data Structure
223 ----------------------
224
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:
227
228 struct sysfs_bus {
229         unsigned char name[SYSFS_NAME_LEN];
230         unsigned char path[SYSFS_PATH_MAX];
231
232         /* internal use only */
233         struct dlist *drivers;
234         struct dlist *devices;
235         struct sysfs_directory *directory;
236 };
237
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:
245
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)
249
250
251 5.3 Class Data Structures
252 -------------------------
253
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.
257
258 struct sysfs_class {
259         unsigned char name[SYSFS_NAME_LEN];
260         unsigned char path[SYSFS_PATH_MAX];
261
262         /* for internal use only */
263         struct dlist *devices;
264         struct sysfs_directory *directory;
265 };
266
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). 
270
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];
275
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;
281 };
282
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:
291
292 struct dlist *sysfs_get_classdev_attributes(struct sysfs_class_device *cdev);
293
294
295 5.4 Root Device Data Structure
296 ------------------------------
297
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. 
301
302 struct sysfs_root_device {
303         unsigned char name[SYSFS_NAME_LEN];
304         unsigned char path[SYSFS_PATH_MAX];
305
306         /* for internal use only */
307         struct dlist *devices;
308         struct sysfs_directory *directory;
309 };
310
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. 
315
316
317 5.5 Device Data Structure
318 -------------------------
319
320 The sysfs_device structure represents a system device that's exposed
321 in sysfs under the /sys/devices directory structure.
322
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];
329
330         /* for internal use only */
331         struct sysfs_device *parent;
332         struct dlist *children;
333         struct sysfs_directory *directory;
334 };
335
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:
343
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)
347
348
349 5.6 Driver Data Structure
350 -------------------------
351
352 The sysfs_driver structure represents a device driver.
353
354 struct sysfs_driver {
355         unsigned char name[SYSFS_NAME_LEN];
356         unsigned char path[SYSFS_PATH_MAX];
357
358         /* for internal use only */
359         struct dlist *devices;
360         struct sysfs_directory *directory;
361 };
362
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:
368
369 struct dlist *sysfs_get_driver_attributes(struct sysfs_driver *driver)
370
371
372 6. Functions
373 ------------
374
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.
379
380
381 6.1 Utility Functions
382 ---------------------
383
384 The library will provide a few utility functions for working with sysfs.
385
386 -------------------------------------------------------------------------------
387 Name:           sysfs_get_mnt_path
388
389 Description:    Function finds the mount path for filesystem type "sysfs".
390
391 Arguments:      unsigned char *mnt_path         Mount path buffer
392                 size_t len                      Size of mount path buffer       
393
394 Returns:        Zero with success.
395                 -1 with error. Errno will be set with error:
396                         - EINVAL for invalid argument, if buffer is NULL.
397
398 Prototype:      sysfs_get_mnt_path(unsigned char *mnt_path, size_t len);
399 -------------------------------------------------------------------------------
400
401 -------------------------------------------------------------------------------
402 Name:           sysfs_get_name_from_path
403
404 Description:    Function returns the last directory or file name from the
405                 included path.
406
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
410
411 Returns:        0 with success.
412                 -1 on Error. Errno will be set with error, returning
413                         - EINVAL for invalid arguments
414
415 Prototype:      int sysfs_get_name_from_path(const unsigned char *path, 
416                                         unsigned char *name, size_t *len)
417 -------------------------------------------------------------------------------
418
419 -------------------------------------------------------------------------------
420 Name:           sysfs_get_link
421
422 Description:    Sysfs readlink function, reads the link at supplied path
423                 and returns its target path.
424
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
428
429 Returns:        0 with success 
430                 -1 with error. Errno will be set with error, returning
431                         - EINVAL for invalid arguments
432
433 Prototype:      int sysfs_get_link(const unsigned char *path, 
434                                         unsigned char *target, size_t len)
435 -------------------------------------------------------------------------------
436
437 -------------------------------------------------------------------------------
438 Name:           sysfs_open_subsystem_list
439
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.
443
444                 sysfs_close_list() has to be called to free the list obtained
445                 from this call.
446
447 Arguments:      unsigned char *name             Subsystem to open, like "bus"..
448
449 Returns:        dlist of entries for the subsystem on success
450                 NULL with error indicating the "name" subsystem is invalid.
451
452 Prototype:      struct dlist *sysfs_open_subsystem_list(unsigned char *name)
453 -------------------------------------------------------------------------------
454
455 -------------------------------------------------------------------------------
456 Name:           sysfs_open_bus_devices_list
457
458 Description:    Function returns the list of devices on the given bus. 
459
460                 sysfs_close_list() has to be called to free the list obtained
461                 from this call.
462
463 Arguments:      unsigned char *name             Bus name to open "pci"/"scsi"/"usb"..
464
465 Returns:        dlist of device names for the given bus on success
466                 NULL with error indicating the bus is not supported.
467
468 Prototype:      struct dlist *sysfs_open_bus_devices_list(unsigned char *name)
469 -------------------------------------------------------------------------------
470
471 -------------------------------------------------------------------------------
472 Name:           sysfs_close_list
473
474 Description:    Closes a given dlist. This can be used as a generic list close
475                 routine.
476
477 Arguments:      struct dlist *list              List to be closed
478
479 Prototype:      void sysfs_close_list(struct dlist *list)
480 -------------------------------------------------------------------------------
481
482 -------------------------------------------------------------------------------
483 Name:           sysfs_path_is_dir
484
485 Description:    Utility function to verify if a given path is to a directory.
486
487 Arguments:      unsigned char *path             Path to verify
488
489 Returns:        0 on success, 1 on error
490                         - EINVAL for invalid arguments
491
492 Prototype:      int sysfs_path_is_dir(unsigned char *path)
493 -------------------------------------------------------------------------------
494
495 -------------------------------------------------------------------------------
496 Name:           sysfs_path_is_file
497
498 Description:    Utility function to verify if a given path is to a file.
499
500 Arguments:      unsigned char *path             Path to verify
501
502 Returns:        0 on success, 1 on error
503                         - EINVAL for invalid arguments
504
505 Prototype:      int sysfs_path_is_file(unsigned char *path)
506 -------------------------------------------------------------------------------
507
508 -------------------------------------------------------------------------------
509 Name:           sysfs_path_is_link
510
511 Description:    Utility function to verify if a given path is to a link.
512
513 Arguments:      unsigned char *path             Path to verify
514
515 Returns:        0 on success, 1 on error
516                         - EINVAL for invalid arguments
517
518 Prototype:      int sysfs_path_is_link(unsigned char *path)
519 -------------------------------------------------------------------------------
520
521 6.2 Filesystem Functions
522 ------------------------
523
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. 
527
528 6.2.1 Attribute Functions
529 -------------------------
530
531 Along with the usual open, read, and close functions, libsysfs provides
532 a couple other functions for accessing attribute values. 
533
534 -------------------------------------------------------------------------------
535 Name:           sysfs_open_attribute
536
537 Description:    Opens up a file in sysfs and creates a sysfs_attribute
538                 structure. File isn't read with this function.
539
540 Arguments:      const unsigned char *path       File/Attribute's path
541
542 Returns:        struct sysfs_attribute * with success.
543                 NULL with error. Errno will be set with error, returning
544                         - EINVAL for invalid arguments
545
546 Prototype:      struct sysfs_attribute *sysfs_open_attribute
547                                         (const unsigned char *path)
548 -------------------------------------------------------------------------------
549
550 -------------------------------------------------------------------------------
551 Name:           sysfs_close_attribute
552
553 Description:    Cleans up and closes sysfs_attribute structure.
554
555 Arguments:      struct sysfs_attribute *sysattr Attribute to close
556
557 Prototype:      void sysfs_close_attribute(struct sysfs_attribute *sysattr)
558 -------------------------------------------------------------------------------
559
560 -------------------------------------------------------------------------------
561 Name:           sysfs_read_dir_attributes
562
563 Description:    Reads the given sysfs_directory to create a list of attributes.
564
565 Arguments:      struct sysfs_directory *sysdir  sysfs_directory whose 
566                                                 attributes to read
567
568 Returns:        struct dlist * of attributes on success
569                 NULL with error. Errno will be set on error, returning EINVAL
570                                 for invalid arguments
571                 
572 Prototype:      struct dlist *sysfs_read_dir_attributes
573                                         (struct sysfs_directory *sysdir)
574 -------------------------------------------------------------------------------
575
576 -------------------------------------------------------------------------------
577 Name:           sysfs_refresh_attributes
578
579 Description:    Given a list of attributes, this function refreshes the values
580                 of attributes in the list.
581
582 Arguments:      struct dlist *attrlist          list of attributes to refresh
583
584 Returns:        0 with success.
585                 1 with error. Errno will be set on error, returning EINVAL
586                                 for invalid arguments
587
588 Prototype:      int sysfs_refresh_attributes(struct dlist *attrlist)
589 -------------------------------------------------------------------------------
590
591 -------------------------------------------------------------------------------
592 Name:           sysfs_read_attribute
593
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.
598
599 Arguments:      struct sysfs_attribute *sysattr Attribute to read
600
601 Returns:        0 with success.
602                 -1 with error. Errno will be set with error, returning
603                         - EINVAL for invalid arguments
604
605 Prototype:      int sysfs_read_attribute(struct sysfs_attribute *sysattr)
606 -------------------------------------------------------------------------------
607
608 -------------------------------------------------------------------------------
609 Name:           sysfs_write_attribute
610
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.
616
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"
620
621 Returns:        0 with success.
622                 -1 with error. Errno will be set with error, returning 
623                         - EINVAL for invalid arguments
624
625 Prototype:      int sysfs_write_attribute(struct sysfs_attribute *sysattr,
626                                 const unsigned char *new_value, size_t len)
627 -------------------------------------------------------------------------------
628
629 -------------------------------------------------------------------------------
630 Name:           sysfs_read_attribute_value
631
632 Description:    Given a path to a specific attribute, function reads and
633                 returns its value to the supplied value buffer.
634
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
638
639 Returns:        0 with success.
640                 -1 with error. Errno will be set with error, returning
641                         - EINVAL for invalid arguments
642
643 Prototype:      int sysfs_read_attribute_value(const unsigned char *attrpath, 
644                                         unsigned char *value, size_t vsize)
645 -------------------------------------------------------------------------------
646
647 -------------------------------------------------------------------------------
648 Name:           sysfs_get_value_from_attributes
649
650 Description:    Function takes a single or linked list of sysfs attribute
651                 structures and returns the value of the specified attribute
652                 name.
653
654 Arguments:      struct sysfs_attribute *attr 
655                                           Attribute list to search through
656                 const unsigned char *name Name of attribute to return value
657
658 Returns:        unsigned char * attribute value with success.
659                 NULL with error. Errno will be set with error, returning
660                         - EINVAL for invalid arguments
661
662 Prototype:      unsigned char *sysfs_get_value_from_attributes
663                 (struct sysfs_attribute *attr, const unsigned char * name)
664 -------------------------------------------------------------------------------
665
666 -------------------------------------------------------------------------------
667 Name:           sysfs_get_directory_attribute
668
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.
672
673 Arguments:      struct sysfs_directory *dir     Directory in which to search
674                 unsigned char *attrname         Attribute name to look for
675
676 Returns:        struct sysfs_attribute on success.
677                 NULL with error. Errno will be set with error, returning
678                         - EINVAL for invalid arguments
679
680 Prototype:      struct sysfs_attribute *sysfs_get_directory_attribute
681                         (struct sysfs_directory *dir, unsigned char *attrname)
682 -------------------------------------------------------------------------------
683                 
684
685 6.2.2 Link Functions
686 --------------------
687
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.
693
694 -------------------------------------------------------------------------------
695 Name:           sysfs_open_link
696
697 Description:    Opens a directory link. 
698
699 Arguments:      const unsigned char *linkpath           Path to link
700
701 Returns:        struct sysfs_link * with success.
702                 NULL with error. Errno will be set with error, returning
703                         - EINVAL for invalid arguments
704
705 Prototype:      struct sysfs_link *sysfs_open_link
706                                         (const unsigned char *linkpath)
707 -------------------------------------------------------------------------------
708
709 -------------------------------------------------------------------------------
710 Name:           sysfs_close_link
711
712 Description:    Closes a directory link structure.
713
714 Arguments:      struct sysfs_link *ln                   Link to close
715
716 Prototype:      void sysfs_close_link(struct sysfs_link *ln)
717 -------------------------------------------------------------------------------
718
719 -------------------------------------------------------------------------------
720 Name:           sysfs_read_dir_links
721
722 Description:    Reads the given sysfs_directory to create a list of links.
723
724 Arguments:      struct sysfs_directory *sysdir  sysfs_directory whose 
725                                                 links to read
726
727 Returns:        struct dlist * of links with success
728                 NULL with error. Errno will be set on error, returning EINVAL
729                                 for invalid arguments
730                 
731 Prototype:      struct dlist *sysfs_read_dir_links
732                                         (struct sysfs_directory *sysdir)
733 -------------------------------------------------------------------------------
734
735 -------------------------------------------------------------------------------
736 Name:           sysfs_get_directory_link
737
738 Description:    Function walks the list of links for the given sysfs directory 
739                 and returns the sysfs_link structure for the specified link 
740                 name.
741
742 Arguments:      struct sysfs_directory *dir     Directory in which to search
743                 unsigned char *linkname         Link name to look for
744
745 Returns:        struct sysfs_link * with success.
746                 NULL with error. Errno will be set with error, returning
747                         - EINVAL for invalid arguments
748
749 Prototype:      struct sysfs_link *sysfs_get_directory_link
750                         (struct sysfs_directory *dir, unsigned char *linkname)
751 -------------------------------------------------------------------------------
752
753 -------------------------------------------------------------------------------
754 Name:           sysfs_get_subdirectory_link
755
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.
759
760 Arguments:      struct sysfs_directory *dir     Directory in which to search
761                 unsigned char *linkname         Link name to look for
762
763 Returns:        struct sysfs_link * with success.
764                 NULL with error. Errno will be set with error, returning
765                         - EINVAL for invalid arguments
766
767 Prototype:      struct sysfs_link *sysfs_get_subdirectory_link
768                         (struct sysfs_directory *dir, unsigned char *linkname)
769 -------------------------------------------------------------------------------
770
771
772 6.2.3 Directory Functions
773 -------------------------
774
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
780 up.
781
782 -------------------------------------------------------------------------------
783 Name:           sysfs_open_directory
784
785 Description:    Opens a sysfs directory at a specific path
786
787 Arguments:      const unsigned char *path       Directory path to open
788
789 Returns:        struct sysfs_directory * with success.
790                 NULL with error. Errno will be set with error, returning
791                         - EINVAL for invalid arguments
792
793 Prototype:      struct sysfs_directory *sysfs_open_directory
794                                                 (const unsigned char *path)
795 -------------------------------------------------------------------------------
796
797 -------------------------------------------------------------------------------
798 Name:           sysfs_close_directory
799
800 Description:    Closes specific directory, its subdirectories, links, and
801                 files.
802
803 Arguments:      struct sysfs_directory *sysdir  Directory to close
804
805 Prototype:      void sysfs_close_directory(struct sysfs_directory *sysdir)
806 -------------------------------------------------------------------------------
807
808 -------------------------------------------------------------------------------
809 Name:           sysfs_read_dir_subdirs
810
811 Description:    Reads the given sysfs_directory to create a list of subdirs.
812
813 Arguments:      struct sysfs_directory *sysdir  sysfs_directory whose 
814                                                 subdirs have to be read
815
816 Returns:        struct dlist * of links with success
817                 NULL with error. Errno will be set on error, returning EINVAL
818                                 for invalid arguments
819                 
820 Prototype:      struct dlist *sysfs_read_dir_subdirs
821                                         (struct sysfs_directory *sysdir)
822 -------------------------------------------------------------------------------
823
824 -------------------------------------------------------------------------------
825 Name:           sysfs_read_directory
826
827 Description:    Read the supplied directory. Reading fills in the directory's
828                 contents like subdirectories, links, and attributes.
829
830 Arguments:      struct sysfs_directory *sysdir  Directory to read
831
832 Returns:        0 with success.
833                 -1 with error. Errno will be set with error, returning
834                         - EINVAL for invalid arguments
835
836 Prototype:      int sysfs_read_directory(struct sysfs_directory *sysdir)
837 -------------------------------------------------------------------------------
838
839 -------------------------------------------------------------------------------
840 Name:           sysfs_read_all_subdirs
841
842 Description:    Reads all subdirs under a given supplied directory. 
843
844 Arguments:      struct sysfs_directory *sysdir  Directory to read
845
846 Returns:        0 with success.
847                 -1 with error. Errno will be set with error, returning
848                         - EINVAL for invalid arguments
849
850 Prototype:      int sysfs_read_all_subdirs(struct sysfs_directory *sysdir)
851 -------------------------------------------------------------------------------
852
853 -------------------------------------------------------------------------------
854 Name:           sysfs_get_subdirectory
855
856 Description:    Function walks the directory tree for the given directory and
857                 returns a sysfs_directory structure for the specified directory
858                 name.
859
860 Arguments:      struct sysfs_directory *dir     Directory in which to search
861                 unsigned char *subname          Name of directory to look for
862
863 Returns:        struct sysfs_directory with success.
864                 NULL with error. Errno will be set with error, returning
865                         - EINVAL for invalid arguments
866 -------------------------------------------------------------------------------
867
868
869 6.3 Bus Functions
870 -----------------
871
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.
878
879 -------------------------------------------------------------------------------
880 Name:           sysfs_open_bus
881
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.
885
886 Arguments:      const unsigned char *name       Bus name to open, like "pci"...
887
888 Returns:        struct sysfs_bus * with success 
889                 NULL with error. Errno will be set with error, returning
890                         - EINVAL for invalid arguments
891
892 Prototype:      struct sysfs_bus *sysfs_open_bus(const unsigned char *name)
893 -------------------------------------------------------------------------------
894
895 -------------------------------------------------------------------------------
896 Name:           sysfs_close_bus
897
898 Description:    Function closes up the sysfs_bus structure including its
899                 devices, drivers, and directory.
900
901 Arguments:      sysfs_bus *bus          Bus structure to close
902
903 Prototype:      void sysfs_close_bus(struct sysfs_bus *bus)
904 -------------------------------------------------------------------------------
905
906 -------------------------------------------------------------------------------
907 Name:           sysfs_get_bus_devices
908
909 Description:    Function returns a list of devices that are registered with
910                 this bus.
911
912 Arguments:      struct sysfs_bus *bus   Bus whose devices list to return
913
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
917
918 Prototype:      struct dlist *sysfs_get_bus_devices(struct sysfs_bus *bus)
919 -------------------------------------------------------------------------------
920
921 -------------------------------------------------------------------------------
922 Name:           sysfs_get_bus_drivers
923
924 Description:    Function returns a list of drivers that are registered with
925                 this bus.
926
927 Arguments:      struct sysfs_bus *bus   Bus whose drivers list to return
928
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
932
933 Prototype:      struct dlist *sysfs_get_bus_drivers(struct sysfs_bus *bus)
934 -------------------------------------------------------------------------------
935
936 -------------------------------------------------------------------------------
937 Name:           sysfs_get_bus_device
938
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.
943
944 Arguments:      struct sysfs_bus *bus   Bus structure on which to search
945                 unsigned char *id       Device to look for
946
947 Returns:        struct sysfs_device * with success 
948                 NULL with error. Errno will be set with error, returning
949                         - EINVAL for invalid arguments
950
951 Prototype:      struct sysfs_device *sysfs_get_bus_device
952                                 (struct sysfs_bus *bus, unsigned char *id)
953 -------------------------------------------------------------------------------
954
955 -------------------------------------------------------------------------------
956 Name:           sysfs_get_bus_driver
957
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.
962
963 Arguments:      struct sysfs_bus *bus   Bus structure on which to search
964                 unsigned char *drvname  Driver to look for
965
966 Returns:        struct sysfs_driver * with success 
967                 NULL with error. Errno will be set with error, returning
968                         - EINVAL for invalid arguments
969
970 Prototype:      struct sysfs_device *sysfs_get_bus_driver
971                                 (struct sysfs_bus *bus, unsigned char *drvname)
972 -------------------------------------------------------------------------------
973
974 -------------------------------------------------------------------------------
975 Name:           sysfs_get_bus_attributes
976
977 Description:    Function takes a sysfs_bus structure and returns a list of
978                 attributes for the bus.
979
980 Arguments:      struct sysfs_bus *bus   Bus for which attributes are required
981
982 Returns:        struct dlist * of attributes with success 
983                 NULL with error. Errno will be set with error, returning
984                         - EINVAL for invalid arguments
985
986 Prototype:      struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus)
987 -------------------------------------------------------------------------------
988
989 -------------------------------------------------------------------------------
990 Name:           sysfs_get_bus_attribute
991
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.
995
996 Arguments:      struct sysfs_bus *bus           Bus structure on which to search
997                 unsigned char *attrname         Attribute to look for
998
999 Returns:        struct sysfs_attribute * with success
1000                 NULL with error. Errno will be set with error, returning
1001                         - EINVAL for invalid arguments
1002
1003 Prototype:      struct sysfs_attribute *sysfs_get_bus_attribute
1004                                 (struct sysfs_bus *bus, unsigned char *attrname)
1005 -------------------------------------------------------------------------------
1006
1007 -------------------------------------------------------------------------------
1008 Name:           sysfs_open_bus_device
1009
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.
1013
1014         NOTE:   
1015                 1. The sysfs_device structure obtained upon successful return 
1016                    from this function has to be closed by calling 
1017                    sysfs_close_device().
1018
1019 Arguments:      unsigned char *busname          Bus on which to search
1020                 unsigned char *dev_id           Name of the device to look for
1021
1022 Returns:        struct sysfs_device * on success
1023                 NULL with error. Errno will be set with error, returning
1024                         - EINVAL for invalid arguments
1025         
1026 Prototype:      struct sysfs_device *sysfs_open_bus_device
1027                                 (unsigned char *busname, unsigned char *dev_id)
1028 -------------------------------------------------------------------------------
1029
1030 -------------------------------------------------------------------------------
1031 Name:           sysfs_find_driver_bus
1032
1033 Description:    Given the name of a driver, this function finds the name of the
1034                 bus the driver is on
1035
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
1039
1040 Returns:        0 with success.
1041                 -1 with error. Errno will be set with error, returning
1042                         - EINVAL for invalid arguments
1043
1044 Prototype:      int sysfs_find_driver_bus(const unsigned char *driver,
1045                                         unsigned char *busname, size_t bsize)
1046 -------------------------------------------------------------------------------
1047
1048
1049 6.4 Class Functions
1050 -------------------
1051
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.
1059
1060 -------------------------------------------------------------------------------
1061 Name:           sysfs_open_class
1062
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.
1066
1067 Arguments:      const unsigned char *name       Class name to open, like "net"..
1068
1069 Returns:        struct sysfs_class * with success 
1070                 NULL with error. Errno will be set with error, returning
1071                         - EINVAL for invalid arguments
1072
1073 Prototype:      struct sysfs_class *sysfs_open_class(const unsigned char *name)
1074 -------------------------------------------------------------------------------
1075
1076 -------------------------------------------------------------------------------
1077 Name:           sysfs_close_class
1078
1079 Description:    Function closes up the sysfs_class structure including its
1080                 class devices.
1081
1082 Arguments:      sysfs_class *class      Class structure to close
1083
1084 Prototype:      void sysfs_close_class(struct sysfs_class *class);
1085 -------------------------------------------------------------------------------
1086
1087 -------------------------------------------------------------------------------
1088 Name:           sysfs_open_class_device_path
1089
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.
1093
1094 Arguments:      const unsigned char *path       Path to class device
1095
1096 Returns:        struct sysfs_class_device * with success 
1097                 NULL with error. Errno will be set with error, returning
1098                         - EINVAL for invalid arguments
1099
1100 Prototype:      struct sysfs_class_device *sysfs_open_class_device_path
1101                                         (const unsigned char *path)
1102 -------------------------------------------------------------------------------
1103
1104 -------------------------------------------------------------------------------
1105 Name:           sysfs_close_class_device
1106
1107 Description:    Function closes up the sysfs_class_device structure.
1108
1109 Arguments:      sysfs_class_device *dev Class device structure to close
1110
1111 Prototype:      void sysfs_close_class_device(struct sysfs_class_device *dev)
1112 -------------------------------------------------------------------------------
1113
1114 -------------------------------------------------------------------------------
1115 Name:           sysfs_get_class_device
1116
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.
1121
1122 Arguments:      struct sysfs_class *class       Class on which to search
1123                 unsigned_char *name             Class device "name" to look for
1124
1125 Returns:        struct sysfs_class_device * with success 
1126                 NULL with error. Errno will be set with error, returning
1127                         - EINVAL for invalid arguments
1128
1129 Prototype:      struct sysfs_class_device *sysfs_get_class_device
1130                                 (struct sysfs_class *class, unsigned char *name)
1131 -------------------------------------------------------------------------------
1132
1133 -------------------------------------------------------------------------------
1134 Name:           sysfs_get_class_devices
1135
1136 Description:    Function returns a list of class devices for the given class.
1137
1138 Arguments:      struct sysfs_class *cls         Class whose class device list
1139                                                 is required
1140
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
1144
1145 Prototype:      struct dlist *sysfs_get_class_devices(struct sysfs_class *cls)
1146 -------------------------------------------------------------------------------
1147
1148 -------------------------------------------------------------------------------
1149 Name:           sysfs_open_class_device
1150
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.
1154
1155         NOTE:   
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
1160                    this function. 
1161
1162 Arguments:      const unsigned char *classname  Class on which to search
1163                 unsigned char *name             Class device "name" to open
1164
1165 Returns:        struct sysfs_class_device * with success 
1166                 NULL with error. Errno will be set with error, returning
1167                         - EINVAL for invalid arguments
1168
1169 Prototype:      struct sysfs_class_device *sysfs_open_class_device
1170                         (const unsigned char *classname, unsigned char *class)
1171 -------------------------------------------------------------------------------
1172
1173 -------------------------------------------------------------------------------
1174 Name:           sysfs_get_classdev_device
1175
1176 Description:    Function returns the sysfs_device reference (if present) for the 
1177                 given class device.
1178
1179 Arguments:      struct sysfs_class_device *clsdev       Class device whose
1180                                                         sysfs_device reference
1181                                                         is required
1182
1183 Returns:        struct sysfs_device * on success
1184                 NULL with error. Errno will be set with error, returning
1185                         - EINVAL for invalid arguments
1186                 
1187 Prototype:      struct sysfs_device *sysfs_get_classdev_device
1188                                         (struct sysfs_class_device *clsdev)
1189 -------------------------------------------------------------------------------
1190
1191 -------------------------------------------------------------------------------
1192 Name:           sysfs_get_classdev_driver
1193
1194 Description:    Function returns the sysfs_driver reference (if present) for the 
1195                 given class device.
1196
1197 Arguments:      struct sysfs_class_device *clsdev       Class device whose
1198                                                         sysfs_driver reference
1199                                                         is required
1200
1201 Returns:        struct sysfs_driver * on success
1202                 NULL with error. Errno will be set with error, returning
1203                         - EINVAL for invalid arguments
1204                 
1205 Prototype:      struct sysfs_driver *sysfs_get_classdev_driver
1206                                         (struct sysfs_class_device *clsdev)
1207 -------------------------------------------------------------------------------
1208
1209 -------------------------------------------------------------------------------
1210 Name:           sysfs_get_classdev_parent
1211
1212 Description:    Function returns the sysfs_class_device reference for the parent 
1213                 (if present) of the given class device.
1214
1215 Arguments:      struct sysfs_class_device *clsdev       Class device whose
1216                                                         parent reference
1217                                                         is required
1218
1219 Returns:        struct sysfs_class_device * on success
1220                 NULL with error. Errno will be set with error, returning
1221                         - EINVAL for invalid arguments
1222                 
1223 Prototype:      struct sysfs_class_device *sysfs_get_classdev_parent
1224                                         (struct sysfs_class_device *clsdev)
1225 -------------------------------------------------------------------------------
1226
1227 -------------------------------------------------------------------------------
1228 Name:           sysfs_get_classdev_attributes
1229
1230 Description:    Function takes a sysfs_class_device structure and returns a list 
1231                 of attributes for the class device.
1232
1233 Arguments:      struct sysfs_class_device *cdev         Class device for which 
1234                                                         attributes are required
1235
1236 Returns:        struct dlist * of attributes with success 
1237                 NULL with error. Errno will be set with error, returning
1238                         - EINVAL for invalid arguments
1239
1240 Prototype:      struct dlist *sysfs_get_classdev_attributes
1241                                         (struct sysfs_class_device *cdev)
1242 -------------------------------------------------------------------------------
1243
1244 -------------------------------------------------------------------------------
1245 Name:           sysfs_get_classdev_attr
1246
1247 Description:    Searches supplied class device's attributes by name and returns
1248                 the attribute.
1249         
1250 Arguments:      struct sysfs_class_device *clsdev       Device to search
1251                 const unsigned char *name               Attribute name to find
1252
1253 Returns:        struct sysfs_attribute * with success 
1254                 NULL with error. Errno will be set with error, returning
1255                         - EINVAL for invalid arguments
1256
1257 Prototype:      struct sysfs_attribute *sysfs_get_classdev_attr
1258                 (struct sysfs_class_device *clsdev, const unsigned char *name)
1259 -------------------------------------------------------------------------------
1260
1261 -------------------------------------------------------------------------------
1262 Name:           sysfs_open_classdev_attr
1263
1264 Description:    Function takes as arguments, a the name of the class, the class
1265                 device name and the name of the required attribute.
1266
1267         NOTE:
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()
1271
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
1275
1276 Returns:        struct sysfs_attribute * with success.
1277                 NULL with error. Errno will be set with error, returning
1278                         - EINVAL for invalid arguments
1279
1280 Prototype:      struct sysfs_attribute *sysfs_write_classdev_attr
1281                         (const unsigned char *classname, const unsigned char *dev,
1282                                                 const unsigned char *attrib)
1283 -------------------------------------------------------------------------------
1284
1285
1286 6.5 Device Functions
1287 --------------------
1288
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. 
1294
1295 -------------------------------------------------------------------------------
1296 Name:           sysfs_open_device_path
1297
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
1300                 structure.
1301
1302 Arguments:      const unsigned char *path       Path to device
1303
1304 Returns:        struct sysfs_device * with success 
1305                 NULL with error. Errno will be set with error, returning
1306                         - EINVAL for invalid arguments
1307
1308 Prototype:      struct sysfs_device *sysfs_open_device_path
1309                                 (const unsigned char *path)
1310 -------------------------------------------------------------------------------
1311
1312 -------------------------------------------------------------------------------
1313 Name:           sysfs_close_device
1314
1315 Description:    Function closes up the sysfs_device structure.
1316
1317 Arguments:      sysfs_device *dev               Device structure to close
1318
1319 Prototype:      void sysfs_close_device(struct sysfs_device *dev)
1320 -------------------------------------------------------------------------------
1321
1322 -------------------------------------------------------------------------------
1323 Name:           sysfs_open_root_device
1324
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.
1328
1329 Arguments:      const unsigned char *name       Name of the root device to open
1330
1331 Returns:        struct sysfs_root_device * with success 
1332                 NULL with error. Errno will be set with error, returning
1333                         - EINVAL for invalid arguments
1334
1335 Prototype:      struct sysfs_device *sysfs_open_root_device
1336                                 (const unsigned char *name)
1337 -------------------------------------------------------------------------------
1338
1339 -------------------------------------------------------------------------------
1340 Name:           sysfs_close_root_device
1341
1342 Description:    Function closes up the sysfs_root_device structure including the
1343                 devices in the root device tree.
1344
1345 Arguments:      sysfs_device *root      Root device structure to close
1346
1347 Prototype:      void sysfs_close_root_device(struct sysfs_root_device *root)
1348 -------------------------------------------------------------------------------
1349
1350 -------------------------------------------------------------------------------
1351 Name:           sysfs_get_device_parent
1352
1353 Description:    Function returns the sysfs_device reference for the parent 
1354                 (if present) of the given sysfs_device.
1355
1356 Arguments:      struct sysfs_device *dev        sysfs_device whose parent 
1357                                                 reference is required
1358
1359 Returns:        struct sysfs_device * on success
1360                 NULL with error. Errno will be set with error, returning
1361                         - EINVAL for invalid arguments
1362                 
1363 Prototype:      struct sysfs_device *sysfs_get_device_parent
1364                                         (struct sysfs_device *dev)
1365 -------------------------------------------------------------------------------
1366
1367 -------------------------------------------------------------------------------
1368 Name:           sysfs_get_root_devices
1369
1370 Description:    Function returns a list of devices under the given root device.
1371
1372 Arguments:      struct sysfs_root_device *root  sysfs_root_device whose devices
1373                                                 list is required
1374
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
1378
1379 Prototype:      struct dlist *sysfs_get_root_devices
1380                                         (struct sysfs_root_device *root)
1381 -------------------------------------------------------------------------------
1382
1383 -------------------------------------------------------------------------------
1384 Name:           sysfs_get_device_attr
1385
1386 Description:    Searches supplied device's attributes by name and returns
1387                 the attribute.
1388
1389 Arguments:      struct sysfs_device *dev        Device to search
1390                 const unsigned char *name       Attribute name to find
1391
1392 Returns:        struct sysfs_attribute * with success 
1393                 NULL with error. Errno will be set with error, returning
1394                         - EINVAL for invalid arguments
1395
1396 Prototype:      struct sysfs_attribute *sysfs_get_device_attr
1397                         (struct sysfs_device *dev, const unsigned char *name)
1398 -------------------------------------------------------------------------------
1399
1400 -------------------------------------------------------------------------------
1401 Name:           sysfs_get_device_attributes
1402
1403 Description:    Function takes a sysfs_device structure and returns a list 
1404                 of attributes for the device.
1405
1406 Arguments:      struct sysfs_device *device             Device for which 
1407                                                         attributes are required
1408
1409 Returns:        struct dlist * of attributes with success 
1410                 NULL with error. Errno will be set with error, returning
1411                         - EINVAL for invalid arguments
1412
1413 Prototype:      struct dlist *sysfs_get_device_attributes
1414                                         (struct sysfs_device *device)
1415 -------------------------------------------------------------------------------
1416
1417 -------------------------------------------------------------------------------
1418 Name:           sysfs_open_device
1419
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.
1423
1424 Arguments:      const unsigned char *bus_id     Device to look for
1425                 const unsigned char *bus        Bus on which to search
1426
1427 Returns:        struct sysfs_device * with success 
1428                 NULL with error. Errno will be set with error, returning
1429                         - EINVAL for invalid arguments
1430
1431 Prototype:      struct sysfs_device *sysfs_open_device
1432                         (const unsigned char *bus_id, const unsigned char *bus)
1433 -------------------------------------------------------------------------------
1434
1435 -------------------------------------------------------------------------------
1436 Name:           sysfs_open_device_attr
1437
1438 Description:    Function takes as arguments, the bus on which to search for a 
1439                 device, and an attribute of the device to open. 
1440
1441         NOTE:
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()
1445
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
1449
1450 Returns:        struct sysfs_attribute * with success.
1451                 NULL with error. Errno will be set with error, returning
1452                         - EINVAL for invalid arguments
1453
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 -------------------------------------------------------------------------------
1458
1459
1460 6.6 Driver Functions
1461 --------------------
1462
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.
1466
1467 -------------------------------------------------------------------------------
1468 Name:           sysfs_open_driver_path
1469
1470 Description:    Opens driver at specific path.
1471
1472 Arguments:      const unsigned char *path       Path to driver
1473
1474 Returns:        struct sysfs_driver * with success 
1475                 NULL with error. Errno will be set with error, returning
1476                         - EINVAL for invalid arguments
1477
1478 Prototype:      struct sysfs_driver *sysfs_open_driver_path
1479                                 (const unsigned char *path)
1480 -------------------------------------------------------------------------------
1481
1482 -------------------------------------------------------------------------------
1483 Name:           sysfs_close_driver
1484
1485 Description:    Closes and cleans up sysfs_driver structure.
1486
1487 Arguments:      sysfs_driver *driver    Driver structure to close
1488
1489 Prototype:      void sysfs_close_driver(struct sysfs_driver *driver)
1490 -------------------------------------------------------------------------------
1491
1492 -------------------------------------------------------------------------------
1493 Name:           sysfs_get_driver_devices
1494
1495 Description:    Function returns a list of devices that use this driver.
1496
1497 Arguments:      struct sysfs_driver *driver     Driver whose devices list is
1498                                                 required
1499
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
1503
1504 Prototype:      struct dlist *sysfs_get_driver_devices
1505                                         (struct sysfs_driver *driver)
1506 -------------------------------------------------------------------------------
1507
1508 -------------------------------------------------------------------------------
1509 Name:           sysfs_get_driver_device
1510
1511 Description:    Function returns a sysfs_device reference for the device with 
1512                 "name" that uses this driver
1513
1514 Arguments:      struct sysfs_driver *driver     Driver on which to search
1515                 const unsigned char *name       Name of the device to look for
1516
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
1520
1521 Prototype:      struct dlist *sysfs_get_driver_device
1522                         (struct sysfs_driver *driver, const unsigned char *name)
1523 -------------------------------------------------------------------------------
1524
1525 -------------------------------------------------------------------------------
1526 Name:           sysfs_get_driver_attr
1527
1528 Description:    Searches supplied driver's attributes by name and returns
1529                 the attribute.
1530
1531 Arguments:      struct sysfs_driver *drv        Driver to search
1532                 const unsigned char *name       Attribute name to find
1533
1534 Returns:        struct sysfs_attribute * with success 
1535                 NULL with error. Errno will be set with error, returning
1536                         - EINVAL for invalid arguments
1537
1538 Prototype:      struct sysfs_attribute *sysfs_get_driver_attr
1539                         (struct sysfs_driver *drv, const unsigned char *name)
1540 -------------------------------------------------------------------------------
1541
1542 -------------------------------------------------------------------------------
1543 Name:           sysfs_get_driver_attributes
1544
1545 Description:    Function takes a sysfs_driver structure and returns a list 
1546                 of attributes for the driver.
1547
1548 Arguments:      struct sysfs_driver *driver             Driver for which 
1549                                                         attributes are required
1550
1551 Returns:        struct dlist * of attributes with success 
1552                 NULL with error. Errno will be set with error, returning
1553                         - EINVAL for invalid arguments
1554
1555 Prototype:      struct dlist *sysfs_get_driver_attributes
1556                                         (struct sysfs_driver *driver)
1557 -------------------------------------------------------------------------------
1558
1559 -------------------------------------------------------------------------------
1560 Name:           sysfs_open_driver
1561
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.
1565
1566         NOTE:   
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() 
1572                    to determine this.
1573
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"
1577
1578 Returns:        struct sysfs_driver * with success 
1579                 NULL with error. Errno will be set with error, returning
1580                         - EINVAL for invalid arguments
1581
1582 Prototype:      struct sysfs_driver *sysfs_open_driver
1583                                 (const unsigned char *drv_name,
1584                                         const unsigned char *bus, size_t bsize)
1585 -------------------------------------------------------------------------------
1586
1587 -------------------------------------------------------------------------------
1588 Name:           sysfs_get_driver_links
1589
1590 Description:    Function returns a list of links for a given driver 
1591
1592 Arguments:      struct sysfs_driver *driver     Driver to get links from
1593
1594 Returns:        struct dlist * of links on success
1595                 NULL with error
1596
1597 Prototype:      struct dlist *sysfs_get_driver_links
1598                                                 (struct sysfs_driver *driver)
1599 -------------------------------------------------------------------------------
1600
1601 -------------------------------------------------------------------------------
1602 Name:           sysfs_open_driver_attr
1603
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.
1606         
1607         NOTE:
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()
1611
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
1615
1616 Returns:        struct sysfs_attribute * with success.
1617                 NULL with error. Errno will be set with error, returning
1618                         - EINVAL for invalid arguments
1619
1620 Prototype:      struct sysfs_attribute *sysfs_open_driver_attr
1621                         (const unsigned char *bus, const unsigned char *drv,
1622                                                 const unsigned char *attrib)
1623 -------------------------------------------------------------------------------
1624
1625
1626 7. Navigating a dlist
1627 ---------------------
1628
1629 Libsysfs uses (yet another) list implementation thanks to Eric J Bohm.
1630
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.
1633
1634 ------------------------------------------------------------------------------
1635 Function/Macro name:    dlist_for_each_data
1636
1637 Description:            Walk the given list, returning a known data type/
1638                         structure in each iteration.
1639
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
1644                                                 in the list
1645
1646 Returns:                On each iteration, "data_iterator" will contain a list
1647                         element of "datatype"
1648
1649 Usage example:          The function sysfs_get_classdev_attributes() returns a
1650                         dlist of attributes. To navigate the list:
1651                                 
1652                         struct sysfs_attribute *attr = NULL;
1653                         struct dlist *attrlist = NULL;
1654                         .
1655                         .
1656                         .
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) {
1662                                 .
1663                                 .
1664                                 .
1665                                 }
1666                         }
1667 -------------------------------------------------------------------------------
1668
1669
1670 8. Usage
1671 --------
1672
1673 Accessing devices through libsysfs is supposed to mirror accessing devices
1674 in the filesystem it represents. Here's a typical order of operation:
1675
1676         - get sysfs mount point
1677         - "open" sysfs category, ie. bus, class, or device
1678         - work with category
1679         - "close" sysfs category
1680
1681
1682 9. Conclusion
1683 -------------
1684
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.