libsysfs/libsysfs.txt

   1
   2         System Utilities sysfs Library - libsysfs
   3         =========================================
   4
   5 Version: 1.2.0
   6 September 13, 2004
   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 Calling Conventions in Libsysfs
  26    6.2 Utility Functions
  27    6.3 Filesystem Functions
  28        6.3.1 Attribute Functions
  29        6.3.2 Directory Link Functions
  30        6.3.3 Directory Functions
  31    6.4 Bus Functions
  32    6.5 Class Functions
  33    6.6 Device Functions
  34    6.7 Driver Functions
  35 7. Dlists
  36    7.1 Navigating a dlist
  37    7.2 Custom sorting using dlist_sort_custom()
  38 8. Usage
  39 9. Testsuite
  40 10. Conclusion
  41
  42
  43 1. Introduction
  44 ---------------
  45
  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.
  51
  52
  53 2. Requirements
  54 ---------------
  55
  56 The library must satisfy the following requirements:
  57
  58 - It must provide a stable programming interfaces that applications can
  59   be built upon.
  60
  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.
  64
  65 - It must provide access to all system devices and information exposed
  66   by sysfs.
  67
  68 - It must provide a function to find sysfs' current mount point.
  69
  70 - It must provide a function for udev to retrieve a device's major and
  71   minor numbers.
  72
  73
  74 3. Definitions
  75 --------------
  76
  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:
  83
  84         http://www.kernel.org/pub/linux/kernel/people/mochel/doc/
  85
  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:
  91
  92         http://www.kernel.org/pub/linux/utils/kernel/hotplug/
  93
  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
  99   name devices.
 100
 101
 102 4. Overview
 103 -----------
 104
 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.
 113
 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.
 119
 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.
 126
 127 A paper on Libsysfs was presented at Linux.Conf.Au 2004 (Adelaide, January
 128 2004). The paper is available online at:
 129
 130 http://oss.software.ibm.com/linux/papers/libsysfs/libsysfs-linuxconfau2004.pdf
 131
 132
 133 5. Data Structures
 134 ------------------
 135
 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.
 141
 142 The library will provide standard definitions for working with sysfs
 143 and devices, here's some examples:
 144
 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"
 153
 154 The library uses some definitions to mark maximum size of a sysfs name or
 155 path length:
 156
 157 #define SYSFS_PATH_MAX          255
 158 #define SYSFS_NAME_LEN          50
 159 #define SYSFS_BUS_ID_SIZE       20
 160
 161
 162 NOTE:
 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
 171         structures.
 172
 173
 174 5.1 Directory and Attribute Data Structures
 175 -------------------------------------------
 176
 177 The library implements structures to represent sysfs directories, links,
 178 and files.
 179
 180
 181 5.1.1 Attribute Structure
 182 -------------------------
 183
 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:
 187
 188 struct sysfs_attribute {
 189         char name[SYSFS_NAME_LEN];
 190         char path[SYSFS_PATH_MAX];
 191         char *value;
 192         unsigned short len;             /* value length */
 193         unsigned short method;          /* show and store */
 194 };
 195
 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)
 199 and/or store(write).
 200
 201
 202 5.1.2 Link Structure
 203 --------------------
 204
 205 Symbolic links are used in sysfs to link bus or class views with
 206 particular devices.
 207
 208 struct sysfs_link {
 209         char name[SYSFS_NAME_LEN];
 210         char path[SYSFS_PATH_MAX];
 211         char target[SYSFS_PATH_MAX];
 212 };
 213
 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".
 216
 217
 218 5.1.3 Directory Structure
 219 -------------------------
 220
 221 The directory structure represents a sysfs directory:
 222
 223 struct sysfs_directory {
 224         char name[SYSFS_NAME_LEN];
 225         char path[SYSFS_PATH_MAX];
 226
 227         /* Private: for internal use only */
 228         struct dlist *subdirs;
 229         struct dlist *links;
 230         struct dlist *attributes;
 231 };
 232
 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.
 238
 239
 240 5.2 Bus Data Structure
 241 ----------------------
 242
 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:
 245
 246 struct sysfs_bus {
 247         char name[SYSFS_NAME_LEN];
 248         char path[SYSFS_PATH_MAX];
 249
 250         /* Private: for internal use only */
 251         struct dlist *drivers;
 252         struct dlist *devices;
 253         struct sysfs_directory *directory;
 254 };
 255
 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:
 263
 264 struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus)
 265 struct sysfs_attribute *sysfs_get_bus_attribute(struct sysfs_bus *bus,
 266                                                 char *attrname)
 267
 268
 269 5.3 Class Data Structures
 270 -------------------------
 271
 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.
 275
 276 struct sysfs_class {
 277         char name[SYSFS_NAME_LEN];
 278         char path[SYSFS_PATH_MAX];
 279
 280         /* Private: for internal use only */
 281         struct dlist *devices;
 282         struct sysfs_directory *directory;
 283 };
 284
 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).
 288
 289 struct sysfs_class_device {
 290         char name[SYSFS_NAME_LEN];
 291         char path[SYSFS_PATH_MAX];
 292         char classname[SYSFS_NAME_LEN];
 293
 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;
 299 };
 300
 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:
 309
 310 struct dlist *sysfs_get_classdev_attributes(struct sysfs_class_device *cdev);
 311
 312
 313 5.4 Root Device Data Structure
 314 ------------------------------
 315
 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.
 319
 320 struct sysfs_root_device {
 321         char name[SYSFS_NAME_LEN];
 322         char path[SYSFS_PATH_MAX];
 323
 324         /* Private: for internal use only */
 325         struct dlist *devices;
 326         struct sysfs_directory *directory;
 327 };
 328
 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.
 333
 334
 335 5.5 Device Data Structure
 336 -------------------------
 337
 338 The sysfs_device structure represents a system device that's exposed
 339 in sysfs under the /sys/devices directory structure.
 340
 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];
 347
 348         /* Private: for internal use only */
 349         struct sysfs_device *parent;
 350         struct dlist *children;
 351         struct sysfs_directory *directory;
 352 };
 353
 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:
 361
 362 struct sysfs_attribute *sysfs_get_device_attribute(struct sysfs_device *dev,
 363                                                 const char *name)
 364 struct dlist *sysfs_get_device_attributes(struct sysfs_device *device)
 365
 366
 367 5.6 Driver Data Structure
 368 -------------------------
 369
 370 The sysfs_driver structure represents a device driver.
 371
 372 struct sysfs_driver {
 373         char name[SYSFS_NAME_LEN];
 374         char path[SYSFS_PATH_MAX];
 375
 376         /* Private: for internal use only */
 377         struct dlist *devices;
 378         struct sysfs_directory *directory;
 379 };
 380
 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:
 386
 387 struct dlist *sysfs_get_driver_attributes(struct sysfs_driver *driver)
 388
 389
 390 6. Functions
 391 ------------
 392
 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.
 397
 398
 399 6.1 Calling Conventions in Libsysfs
 400 -----------------------------------
 401
 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:
 404
 405         a. All "open" APIs have a corresponding "close" API.
 406         b. References obtained using "get" calls should not be closed
 407                 explicitly.
 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.
 411
 412
 413 6.2 Utility Functions
 414 ---------------------
 415
 416 The library will provide a few utility functions for working with sysfs.
 417
 418 -------------------------------------------------------------------------------
 419 Name:           sysfs_get_mnt_path
 420
 421 Description:    Function finds the mount path for filesystem type "sysfs".
 422
 423 Arguments:      char *mnt_path          Mount path buffer
 424                 size_t len              Size of mount path buffer
 425
 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
 429                                 if len is zero
 430
 431 Prototype:      sysfs_get_mnt_path(char *mnt_path, size_t len);
 432 -------------------------------------------------------------------------------
 433
 434 -------------------------------------------------------------------------------
 435 Name:           sysfs_get_name_from_path
 436
 437 Description:    Function returns the last directory or file name from the
 438                 included path.
 439
 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
 443
 444 Returns:        0 with success.
 445                 -1 on Error. Errno will be set with error, returning
 446                         - EINVAL for invalid arguments
 447
 448 Prototype:      int sysfs_get_name_from_path(const char *path,
 449                                         char *name, size_t *len)
 450 -------------------------------------------------------------------------------
 451
 452 -------------------------------------------------------------------------------
 453 Name:           sysfs_get_link
 454
 455 Description:    Sysfs readlink function, reads the link at supplied path
 456                 and returns its target path.
 457
 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
 461
 462 Returns:        0 with success
 463                 -1 with error. Errno will be set with error, returning
 464                         - EINVAL for invalid arguments
 465
 466 Prototype:      int sysfs_get_link(const char *path, char *target, size_t len)
 467 -------------------------------------------------------------------------------
 468
 469 -------------------------------------------------------------------------------
 470 Name:           sysfs_open_subsystem_list
 471
 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.
 475
 476                 sysfs_close_list() has to be called to free the list obtained
 477                 from this call.
 478
 479 Arguments:      char *name              Subsystem to open, like "bus"..
 480
 481 Returns:        dlist of entries for the subsystem on success
 482                 NULL with error indicating the "name" subsystem is invalid.
 483
 484 Prototype:      struct dlist *sysfs_open_subsystem_list(char *name)
 485 -------------------------------------------------------------------------------
 486
 487 -------------------------------------------------------------------------------
 488 Name:           sysfs_open_bus_devices_list
 489
 490 Description:    Function returns the list of devices on the given bus.
 491
 492                 sysfs_close_list() has to be called to free the list obtained
 493                 from this call.
 494
 495 Arguments:      char *name              Bus name to open "pci"/"scsi"/"usb"..
 496
 497 Returns:        dlist of device names for the given bus on success
 498                 NULL with error indicating the bus is not supported.
 499
 500 Prototype:      struct dlist *sysfs_open_bus_devices_list(char *name)
 501 -------------------------------------------------------------------------------
 502
 503 -------------------------------------------------------------------------------
 504 Name:           sysfs_close_list
 505
 506 Description:    Closes a given dlist. This can be used as a generic list close
 507                 routine.
 508
 509 Arguments:      struct dlist *list      List to be closed
 510
 511 Prototype:      void sysfs_close_list(struct dlist *list)
 512 -------------------------------------------------------------------------------
 513
 514 -------------------------------------------------------------------------------
 515 Name:           sysfs_path_is_dir
 516
 517 Description:    Utility function to verify if a given path is to a directory.
 518
 519 Arguments:      const char *path        Path to verify
 520
 521 Returns:        0 on success, 1 on error
 522                         - EINVAL for invalid arguments
 523
 524 Prototype:      int sysfs_path_is_dir(const char *path)
 525 -------------------------------------------------------------------------------
 526
 527 -------------------------------------------------------------------------------
 528 Name:           sysfs_path_is_file
 529
 530 Description:    Utility function to verify if a given path is to a file.
 531
 532 Arguments:      const char *path        Path to verify
 533
 534 Returns:        0 on success, 1 on error
 535                         - EINVAL for invalid arguments
 536
 537 Prototype:      int sysfs_path_is_file(const char *path)
 538 -------------------------------------------------------------------------------
 539
 540 -------------------------------------------------------------------------------
 541 Name:           sysfs_path_is_link
 542
 543 Description:    Utility function to verify if a given path is to a link.
 544
 545 Arguments:      const char *path        Path to verify
 546
 547 Returns:        0 on success, 1 on error
 548                         - EINVAL for invalid arguments
 549
 550 Prototype:      int sysfs_path_is_link(const char *path)
 551 -------------------------------------------------------------------------------
 552
 553
 554 6.3 Filesystem Functions
 555 ------------------------
 556
 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.
 560
 561
 562 6.3.1 Attribute Functions
 563 -------------------------
 564
 565 Along with the usual open, read, and close functions, libsysfs provides
 566 a couple other functions for accessing attribute values.
 567
 568 -------------------------------------------------------------------------------
 569 Name:           sysfs_open_attribute
 570
 571 Description:    Opens up a file in sysfs and creates a sysfs_attribute
 572                 structure. File isn't read with this function.
 573
 574 Arguments:      const char *path        File/Attribute's path
 575
 576 Returns:        struct sysfs_attribute * with success.
 577                 NULL with error. Errno will be set with error, returning
 578                         - EINVAL for invalid arguments
 579
 580 Prototype:      struct sysfs_attribute *sysfs_open_attribute(const char *path)
 581 -------------------------------------------------------------------------------
 582
 583 -------------------------------------------------------------------------------
 584 Name:           sysfs_close_attribute
 585
 586 Description:    Cleans up and closes sysfs_attribute structure.
 587
 588 Arguments:      struct sysfs_attribute *sysattr Attribute to close
 589
 590 Prototype:      void sysfs_close_attribute(struct sysfs_attribute *sysattr)
 591 -------------------------------------------------------------------------------
 592
 593 -------------------------------------------------------------------------------
 594 Name:           sysfs_read_dir_attributes
 595
 596 Description:    Reads the given sysfs_directory to create a list of attributes.
 597
 598 Arguments:      struct sysfs_directory *sysdir  sysfs_directory whose
 599                                                 attributes to read
 600
 601 Returns:        struct dlist * of attributes on success
 602                 NULL with error. Errno will be set on error, returning EINVAL
 603                                 for invalid arguments
 604
 605 Prototype:      struct dlist *sysfs_read_dir_attributes
 606                                         (struct sysfs_directory *sysdir)
 607 -------------------------------------------------------------------------------
 608
 609 -------------------------------------------------------------------------------
 610 Name:           sysfs_refresh_dir_attributes
 611
 612 Description:    Given a list sysfs_directory, this function refreshes the list
 613                 of attributes for the given directory.
 614
 615 Arguments:      struct sysfs_directory *sysdir  sysfs_ directory whose
 616                                                 attributes list to refresh
 617
 618 Returns:        0 with success.
 619                 1 with error. Errno will be set on error, returning EINVAL
 620                                 for invalid arguments
 621
 622 Prototype:      int sysfs_refresh_dir_attributes(struct sysfs_directory *sysdir)
 623 -------------------------------------------------------------------------------
 624
 625 -------------------------------------------------------------------------------
 626 Name:           sysfs_get_dir_attributes
 627
 628 Description:    Returns a list of attributes for the given sysfs_directory.
 629
 630 Arguments:      struct sysfs_directory *sysdir  sysfs_directory whose
 631                                                 attributes list to return
 632
 633 Returns:        struct dlist * of attributes with success
 634                 NULL with error. Errno will be set on error, returning EINVAL
 635                                 for invalid arguments
 636
 637 Prototype:      struct dlist *sysfs_read_dir_attributes
 638                                         (struct sysfs_directory *sysdir)
 639 -------------------------------------------------------------------------------
 640
 641 -------------------------------------------------------------------------------
 642 Name:           sysfs_read_attribute
 643
 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.
 648
 649 Arguments:      struct sysfs_attribute *sysattr         Attribute to read
 650
 651 Returns:        0 with success.
 652                 -1 with error. Errno will be set with error, returning
 653                         - EINVAL for invalid arguments
 654
 655 Prototype:      int sysfs_read_attribute(struct sysfs_attribute *sysattr)
 656 -------------------------------------------------------------------------------
 657
 658 -------------------------------------------------------------------------------
 659 Name:           sysfs_write_attribute
 660
 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.
 667
 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"
 671
 672 Returns:        0 with success.
 673                 -1 with error. Errno will be set with error, returning
 674                         - EINVAL for invalid arguments
 675
 676 Prototype:      int sysfs_write_attribute(struct sysfs_attribute *sysattr,
 677                                 const char *new_value, size_t len)
 678 -------------------------------------------------------------------------------
 679
 680 -------------------------------------------------------------------------------
 681 Name:           sysfs_read_attribute_value
 682
 683 Description:    Given a path to a specific attribute, function reads and
 684                 returns its value to the supplied value buffer.
 685
 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
 689
 690 Returns:        0 with success.
 691                 -1 with error. Errno will be set with error, returning
 692                         - EINVAL for invalid arguments
 693
 694 Prototype:      int sysfs_read_attribute_value(const char *attrpath,
 695                                         char *value, size_t vsize)
 696 -------------------------------------------------------------------------------
 697
 698 -------------------------------------------------------------------------------
 699 Name:           sysfs_get_value_from_attributes
 700
 701 Description:    Function takes a single or linked list of sysfs attribute
 702                 structures and returns the value of the specified attribute
 703                 name.
 704
 705 Arguments:      struct dlist *attr      Attribute list to search through
 706                 const char *name        Name of attribute whose value
 707                                         to retrieve
 708
 709 Returns:        char * attribute value with success.
 710                 NULL with error. Errno will be set with error, returning
 711                         - EINVAL for invalid arguments
 712
 713 Prototype:      char *sysfs_get_value_from_attributes
 714                         (struct sysfs_attribute *attr, const char *name)
 715 -------------------------------------------------------------------------------
 716
 717 -------------------------------------------------------------------------------
 718 Name:           sysfs_get_directory_attribute
 719
 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.
 723
 724 Arguments:      struct sysfs_directory *dir     Directory in which to search
 725                 char *attrname                  Attribute name to look for
 726
 727 Returns:        struct sysfs_attribute on success.
 728                 NULL with error. Errno will be set with error, returning
 729                         - EINVAL for invalid arguments
 730
 731 Prototype:      struct sysfs_attribute *sysfs_get_directory_attribute
 732                         (struct sysfs_directory *dir, char *attrname)
 733 -------------------------------------------------------------------------------
 734
 735
 736 6.3.2 Link Functions
 737 --------------------
 738
 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.
 744
 745 -------------------------------------------------------------------------------
 746 Name:           sysfs_open_link
 747
 748 Description:    Opens a directory link.
 749
 750 Arguments:      const char *linkpath            Path to link
 751
 752 Returns:        struct sysfs_link * with success.
 753                 NULL with error. Errno will be set with error, returning
 754                         - EINVAL for invalid arguments
 755
 756 Prototype:      struct sysfs_link *sysfs_open_link(const char *linkpath)
 757 -------------------------------------------------------------------------------
 758
 759 -------------------------------------------------------------------------------
 760 Name:           sysfs_close_link
 761
 762 Description:    Closes a directory link structure.
 763
 764 Arguments:      struct sysfs_link *ln           Link to close
 765
 766 Prototype:      void sysfs_close_link(struct sysfs_link *ln)
 767 -------------------------------------------------------------------------------
 768
 769 -------------------------------------------------------------------------------
 770 Name:           sysfs_read_dir_links
 771
 772 Description:    Reads the given sysfs_directory to create a list of links.
 773
 774 Arguments:      struct sysfs_directory *sysdir  sysfs_directory whose
 775                                                 links to read
 776
 777 Returns:        struct dlist * of links with success
 778                 NULL with error. Errno will be set on error, returning EINVAL
 779                                 for invalid arguments
 780
 781 Prototype:      struct dlist *sysfs_read_dir_links
 782                                         (struct sysfs_directory *sysdir)
 783 -------------------------------------------------------------------------------
 784
 785 -------------------------------------------------------------------------------
 786 Name:           sysfs_get_dir_links
 787
 788 Description:    Returns a list of links for the given sysfs_directory.
 789
 790 Arguments:      struct sysfs_directory *sysdir  sysfs_directory whose
 791                                                 list of links to return
 792
 793 Returns:        struct dlist * of links with success
 794                 NULL with error. Errno will be set on error, returning EINVAL
 795                                 for invalid arguments
 796
 797 Prototype:      struct dlist *sysfs_read_dir_links
 798                                         (struct sysfs_directory *sysdir)
 799 -------------------------------------------------------------------------------
 800
 801 -------------------------------------------------------------------------------
 802 Name:           sysfs_get_directory_link
 803
 804 Description:    Function walks the list of links for the given sysfs directory
 805                 and returns the sysfs_link structure for the specified link
 806                 name.
 807
 808 Arguments:      struct sysfs_directory *dir     Directory in which to search
 809                 char *linkname                  Link name to look for
 810
 811 Returns:        struct sysfs_link * with success.
 812                 NULL with error. Errno will be set with error, returning
 813                         - EINVAL for invalid arguments
 814
 815 Prototype:      struct sysfs_link *sysfs_get_directory_link
 816                         (struct sysfs_directory *dir, char *linkname)
 817 -------------------------------------------------------------------------------
 818
 819 -------------------------------------------------------------------------------
 820 Name:           sysfs_get_subdirectory_link
 821
 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.
 825
 826 Arguments:      struct sysfs_directory *dir     Directory in which to search
 827                 char *linkname                  Link name to look for
 828
 829 Returns:        struct sysfs_link * with success.
 830                 NULL with error. Errno will be set with error, returning
 831                         - EINVAL for invalid arguments
 832
 833 Prototype:      struct sysfs_link *sysfs_get_subdirectory_link
 834                         (struct sysfs_directory *dir, char *linkname)
 835 -------------------------------------------------------------------------------
 836
 837 -------------------------------------------------------------------------------
 838 Name:           sysfs_refresh_dir_links
 839
 840 Description:    Given a list sysfs_directory, this function refreshes the list
 841                 of links under the given directory.
 842
 843 Arguments:      struct sysfs_directory *sysdir  sysfs_ directory whose
 844                                                 links list to refresh
 845
 846 Returns:        0 with success.
 847                 1 with error. Errno will be set on error, returning EINVAL
 848                                 for invalid arguments
 849
 850 Prototype:      int sysfs_refresh_dir_links(struct sysfs_directory *sysdir)
 851 -------------------------------------------------------------------------------
 852
 853
 854 6.3.3 Directory Functions
 855 -------------------------
 856
 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
 862 up.
 863
 864 -------------------------------------------------------------------------------
 865 Name:           sysfs_open_directory
 866
 867 Description:    Opens a sysfs directory at a specific path
 868
 869 Arguments:      const char *path        Directory path to open
 870
 871 Returns:        struct sysfs_directory * with success.
 872                 NULL with error. Errno will be set with error, returning
 873                         - EINVAL for invalid arguments
 874
 875 Prototype:      struct sysfs_directory *sysfs_open_directory(const char *path)
 876 -------------------------------------------------------------------------------
 877
 878 -------------------------------------------------------------------------------
 879 Name:           sysfs_close_directory
 880
 881 Description:    Closes specific directory, its subdirectories, links, and
 882                 files.
 883
 884 Arguments:      struct sysfs_directory *sysdir  Directory to close
 885
 886 Prototype:      void sysfs_close_directory(struct sysfs_directory *sysdir)
 887 -------------------------------------------------------------------------------
 888
 889 -------------------------------------------------------------------------------
 890 Name:           sysfs_read_dir_subdirs
 891
 892 Description:    Reads the given sysfs_directory to create a list of subdirs.
 893
 894 Arguments:      struct sysfs_directory *sysdir  sysfs_directory whose
 895                                                 subdirs have to be read
 896
 897 Returns:        struct dlist * of links with success
 898                 NULL with error. Errno will be set on error, returning EINVAL
 899                                 for invalid arguments
 900
 901 Prototype:      struct dlist *sysfs_read_dir_subdirs
 902                                         (struct sysfs_directory *sysdir)
 903 -------------------------------------------------------------------------------
 904
 905 -------------------------------------------------------------------------------
 906 Name:           sysfs_read_directory
 907
 908 Description:    Read the supplied directory. Reading fills in the directory's
 909                 contents like subdirectories, links, and attributes.
 910
 911 Arguments:      struct sysfs_directory *sysdir  Directory to read
 912
 913 Returns:        0 with success.
 914                 -1 with error. Errno will be set with error, returning
 915                         - EINVAL for invalid arguments
 916
 917 Prototype:      int sysfs_read_directory(struct sysfs_directory *sysdir)
 918 -------------------------------------------------------------------------------
 919
 920 -------------------------------------------------------------------------------
 921 Name:           sysfs_read_all_subdirs
 922
 923 Description:    Reads all subdirs under a given supplied directory.
 924
 925 Arguments:      struct sysfs_directory *sysdir  Directory to read
 926
 927 Returns:        0 with success.
 928                 -1 with error. Errno will be set with error, returning
 929                         - EINVAL for invalid arguments
 930
 931 Prototype:      int sysfs_read_all_subdirs(struct sysfs_directory *sysdir)
 932 -------------------------------------------------------------------------------
 933
 934 -------------------------------------------------------------------------------
 935 Name:           sysfs_get_subdirectory
 936
 937 Description:    Function walks the directory tree for the given directory and
 938                 returns a sysfs_directory structure for the specified directory
 939                 name.
 940
 941 Arguments:      struct sysfs_directory *dir     Directory in which to search
 942                 char *subname                   Name of directory to look for
 943
 944 Returns:        struct sysfs_directory with success.
 945                 NULL with error. Errno will be set with error, returning
 946                         - EINVAL for invalid arguments
 947
 948 Prototype:      struct sysfs_directory *sysfs_get_subdirectory
 949                                 (struct sysfs_directory *dir, char *subname)
 950 -------------------------------------------------------------------------------
 951
 952 -------------------------------------------------------------------------------
 953 Name:           sysfs_get_dir_subdirs
 954
 955 Description:    Returns a list of subdirs for the given sysfs_directory.
 956
 957 Arguments:      struct sysfs_directory *sysdir  sysfs_directory whose
 958                                                 subdirectories list to return
 959
 960 Returns:        struct dlist * of directories with success
 961                 NULL with error. Errno will be set on error, returning EINVAL
 962                                 for invalid arguments
 963
 964 Prototype:      struct dlist *sysfs_read_dir_subdirs
 965                                         (struct sysfs_directory *sysdir)
 966 -------------------------------------------------------------------------------
 967
 968 -------------------------------------------------------------------------------
 969 Name:           sysfs_refresh_dir_subdirs
 970
 971 Description:    Given a list sysfs_directory, this function refreshes the list
 972                 of subdirectories under the given directory.
 973
 974 Arguments:      struct sysfs_directory *sysdir  sysfs_ directory whose
 975                                                 subdirs list to refresh
 976
 977 Returns:        0 with success.
 978                 1 with error. Errno will be set on error, returning EINVAL
 979                                 for invalid arguments
 980
 981 Prototype:      int sysfs_refresh_dir_subdirs(struct sysfs_directory *sysdir)
 982 -------------------------------------------------------------------------------
 983
 984
 985 6.4 Bus Functions
 986 -----------------
 987
 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.
 994
 995 -------------------------------------------------------------------------------
 996 Name:           sysfs_open_bus
 997
 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.
1001
1002 Arguments:      const char *name        Bus name to open, like "pci"...
1003
1004 Returns:        struct sysfs_bus * with success
1005                 NULL with error. Errno will be set with error, returning
1006                         - EINVAL for invalid arguments
1007
1008 Prototype:      struct sysfs_bus *sysfs_open_bus(const char *name)
1009 -------------------------------------------------------------------------------
1010
1011 -------------------------------------------------------------------------------
1012 Name:           sysfs_close_bus
1013
1014 Description:    Function closes up the sysfs_bus structure including its
1015                 devices, drivers, and directory.
1016
1017 Arguments:      sysfs_bus *bus          Bus structure to close
1018
1019 Prototype:      void sysfs_close_bus(struct sysfs_bus *bus)
1020 -------------------------------------------------------------------------------
1021
1022 -------------------------------------------------------------------------------
1023 Name:           sysfs_get_bus_devices
1024
1025 Description:    Function returns a list of devices that are registered with
1026                 this bus.
1027
1028 Arguments:      struct sysfs_bus *bus   Bus whose devices list to return
1029
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
1033
1034 Prototype:      struct dlist *sysfs_get_bus_devices(struct sysfs_bus *bus)
1035 -------------------------------------------------------------------------------
1036
1037 -------------------------------------------------------------------------------
1038 Name:           sysfs_get_bus_drivers
1039
1040 Description:    Function returns a list of drivers that are registered with
1041                 this bus.
1042
1043 Arguments:      struct sysfs_bus *bus   Bus whose drivers list to return
1044
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
1048
1049 Prototype:      struct dlist *sysfs_get_bus_drivers(struct sysfs_bus *bus)
1050 -------------------------------------------------------------------------------
1051
1052 -------------------------------------------------------------------------------
1053 Name:           sysfs_get_bus_device
1054
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.
1059
1060 Arguments:      struct sysfs_bus *bus   Bus structure on which to search
1061                 char *id                Device to look for
1062
1063 Returns:        struct sysfs_device * with success
1064                 NULL with error. Errno will be set with error, returning
1065                         - EINVAL for invalid arguments
1066
1067 Prototype:      struct sysfs_device *sysfs_get_bus_device
1068                                 (struct sysfs_bus *bus, char *id)
1069 -------------------------------------------------------------------------------
1070
1071 -------------------------------------------------------------------------------
1072 Name:           sysfs_get_bus_driver
1073
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.
1078
1079 Arguments:      struct sysfs_bus *bus   Bus structure on which to search
1080                 char *drvname           Driver to look for
1081
1082 Returns:        struct sysfs_driver * with success
1083                 NULL with error. Errno will be set with error, returning
1084                         - EINVAL for invalid arguments
1085
1086 Prototype:      struct sysfs_device *sysfs_get_bus_driver
1087                                 (struct sysfs_bus *bus, char *drvname)
1088 -------------------------------------------------------------------------------
1089
1090 -------------------------------------------------------------------------------
1091 Name:           sysfs_get_bus_attributes
1092
1093 Description:    Function takes a sysfs_bus structure and returns a list of
1094                 attributes for the bus.
1095
1096 Arguments:      struct sysfs_bus *bus   Bus for which attributes are required
1097
1098 Returns:        struct dlist * of attributes with success
1099                 NULL with error. Errno will be set with error, returning
1100                         - EINVAL for invalid arguments
1101
1102 Prototype:      struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus)
1103 -------------------------------------------------------------------------------
1104
1105 -------------------------------------------------------------------------------
1106 Name:           sysfs_get_bus_attribute
1107
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.
1111
1112 Arguments:      struct sysfs_bus *bus           Bus structure on which to search
1113                 char *attrname                  Attribute to look for
1114
1115 Returns:        struct sysfs_attribute * with success
1116                 NULL with error. Errno will be set with error, returning
1117                         - EINVAL for invalid arguments
1118
1119 Prototype:      struct sysfs_attribute *sysfs_get_bus_attribute
1120                                 (struct sysfs_bus *bus, char *attrname)
1121 -------------------------------------------------------------------------------
1122
1123 -------------------------------------------------------------------------------
1124 Name:           sysfs_refresh_bus_attributes
1125
1126 Description:    Function refreshes the list of attributes for a given sysfs_bus
1127
1128 Arguments:      struct sysfs_bus *bus   Bus whose attributes list to refresh
1129
1130 Returns:        struct dlist * of attributes with success
1131                 NULL with error. Errno will be set with error, returning
1132                         - EINVAL for invalid arguments
1133
1134 Prototype:      struct dlist *sysfs_get_bus_attributes(struct sysfs_bus *bus)
1135 -------------------------------------------------------------------------------
1136
1137 -------------------------------------------------------------------------------
1138 Name:           sysfs_find_driver_bus
1139
1140 Description:    Given the name of a driver, this function finds the name of the
1141                 bus the driver is on
1142
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
1146
1147 Returns:        0 with success.
1148                 -1 with error. Errno will be set with error, returning
1149                         - EINVAL for invalid arguments
1150
1151 Prototype:      int sysfs_find_driver_bus(const char *driver,
1152                                         char *busname, size_t bsize)
1153 -------------------------------------------------------------------------------
1154
1155
1156 6.5 Class Functions
1157 -------------------
1158
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.
1166
1167 -------------------------------------------------------------------------------
1168 Name:           sysfs_open_class
1169
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.
1173
1174 Arguments:      const char *name        Class name to open, like "net"..
1175
1176 Returns:        struct sysfs_class * with success
1177                 NULL with error. Errno will be set with error, returning
1178                         - EINVAL for invalid arguments
1179
1180 Prototype:      struct sysfs_class *sysfs_open_class(const char *name)
1181 -------------------------------------------------------------------------------
1182
1183 -------------------------------------------------------------------------------
1184 Name:           sysfs_close_class
1185
1186 Description:    Function closes up the sysfs_class structure including its
1187                 class devices.
1188
1189 Arguments:      sysfs_class *cls        Class structure to close
1190
1191 Prototype:      void sysfs_close_class(struct sysfs_class *cls);
1192 -------------------------------------------------------------------------------
1193
1194 -------------------------------------------------------------------------------
1195 Name:           sysfs_open_class_device_path
1196
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.
1200
1201 Arguments:      const char *path        Path to class device
1202
1203 Returns:        struct sysfs_class_device * with success
1204                 NULL with error. Errno will be set with error, returning
1205                         - EINVAL for invalid arguments
1206
1207 Prototype:      struct sysfs_class_device *sysfs_open_class_device_path
1208                                         (const char *path)
1209 -------------------------------------------------------------------------------
1210
1211 -------------------------------------------------------------------------------
1212 Name:           sysfs_close_class_device
1213
1214 Description:    Function closes up the sysfs_class_device structure.
1215
1216 Arguments:      sysfs_class_device *dev Class device structure to close
1217
1218 Prototype:      void sysfs_close_class_device(struct sysfs_class_device *dev)
1219 -------------------------------------------------------------------------------
1220
1221 -------------------------------------------------------------------------------
1222 Name:           sysfs_get_class_device
1223
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.
1228
1229 Arguments:      struct sysfs_class *cls         Class on which to search
1230                 char *name                      Class device "name" to look for
1231
1232 Returns:        struct sysfs_class_device * with success
1233                 NULL with error. Errno will be set with error, returning
1234                         - EINVAL for invalid arguments
1235
1236 Prototype:      struct sysfs_class_device *sysfs_get_class_device
1237                                 (struct sysfs_class *cls, char *name)
1238 -------------------------------------------------------------------------------
1239
1240 -------------------------------------------------------------------------------
1241 Name:           sysfs_get_class_devices
1242
1243 Description:    Function returns a list of class devices for the given class.
1244
1245 Arguments:      struct sysfs_class *cls         Class whose class device list
1246                                                 is required
1247
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
1251
1252 Prototype:      struct dlist *sysfs_get_class_devices(struct sysfs_class *cls)
1253 -------------------------------------------------------------------------------
1254
1255 -------------------------------------------------------------------------------
1256 Name:           sysfs_open_class_device
1257
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.
1261
1262         NOTE:
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
1267                    this function.
1268
1269 Arguments:      const char *classname   Class on which to search
1270                 char *name              Class device "name" to open
1271
1272 Returns:        struct sysfs_class_device * with success
1273                 NULL with error. Errno will be set with error, returning
1274                         - EINVAL for invalid arguments
1275
1276 Prototype:      struct sysfs_class_device *sysfs_open_class_device
1277                         (const char *classname, char *name)
1278 -------------------------------------------------------------------------------
1279
1280 -------------------------------------------------------------------------------
1281 Name:           sysfs_get_classdev_device
1282
1283 Description:    Function returns the sysfs_device reference (if present) for the
1284                 given class device.
1285
1286 Arguments:      struct sysfs_class_device *clsdev       Class device whose
1287                                                         sysfs_device reference
1288                                                         is required
1289
1290 Returns:        struct sysfs_device * on success
1291                 NULL with error. Errno will be set with error, returning
1292                         - EINVAL for invalid arguments
1293
1294 Prototype:      struct sysfs_device *sysfs_get_classdev_device
1295                                         (struct sysfs_class_device *clsdev)
1296 -------------------------------------------------------------------------------
1297
1298 -------------------------------------------------------------------------------
1299 Name:           sysfs_get_classdev_driver
1300
1301 Description:    Function returns the sysfs_driver reference (if present) for
1302                 the given class device.
1303
1304 Arguments:      struct sysfs_class_device *clsdev       Class device whose
1305                                                         sysfs_driver reference
1306                                                         is required
1307
1308 Returns:        struct sysfs_driver * on success
1309                 NULL with error. Errno will be set with error, returning
1310                         - EINVAL for invalid arguments
1311
1312 Prototype:      struct sysfs_driver *sysfs_get_classdev_driver
1313                                         (struct sysfs_class_device *clsdev)
1314 -------------------------------------------------------------------------------
1315
1316 -------------------------------------------------------------------------------
1317 Name:           sysfs_get_classdev_parent
1318
1319 Description:    Function returns the sysfs_class_device reference for the
1320                 parent (if present) of the given class device.
1321
1322 Arguments:      struct sysfs_class_device *clsdev       Class device whose
1323                                                         parent reference
1324                                                         is required
1325
1326 Returns:        struct sysfs_class_device * on success
1327                 NULL with error. Errno will be set with error, returning
1328                         - EINVAL for invalid arguments
1329
1330 Prototype:      struct sysfs_class_device *sysfs_get_classdev_parent
1331                                         (struct sysfs_class_device *clsdev)
1332 -------------------------------------------------------------------------------
1333
1334 -------------------------------------------------------------------------------
1335 Name:           sysfs_get_classdev_attributes
1336
1337 Description:    Function takes a sysfs_class_device structure and returns a
1338                 list of attributes for the class device.
1339
1340 Arguments:      struct sysfs_class_device *cdev         Class device for which
1341                                                         attributes are required
1342
1343 Returns:        struct dlist * of attributes with success
1344                 NULL with error. Errno will be set with error, returning
1345                         - EINVAL for invalid arguments
1346
1347 Prototype:      struct dlist *sysfs_get_classdev_attributes
1348                                         (struct sysfs_class_device *cdev)
1349 -------------------------------------------------------------------------------
1350
1351 -------------------------------------------------------------------------------
1352 Name:           sysfs_get_classdev_attr
1353
1354 Description:    Searches supplied class device's attributes by name and returns
1355                 the attribute.
1356
1357 Arguments:      struct sysfs_class_device *clsdev       Device to search
1358                 const char *name                        Attribute name to find
1359
1360 Returns:        struct sysfs_attribute * with success
1361                 NULL with error. Errno will be set with error, returning
1362                         - EINVAL for invalid arguments
1363
1364 Prototype:      struct sysfs_attribute *sysfs_get_classdev_attr
1365                 (struct sysfs_class_device *clsdev, const char *name)
1366 -------------------------------------------------------------------------------
1367
1368 -------------------------------------------------------------------------------
1369 Name:           sysfs_refresh_classdev_attributes
1370
1371 Description:    Function refreshes the list of attributes for a given
1372                 sysfs_class_device.
1373
1374 Arguments:      struct sysfs_class_device *cdev Class device whose attributes
1375                                                 list to refresh
1376
1377 Returns:        struct dlist * of attributes with success
1378                 NULL with error. Errno will be set with error, returning
1379                         - EINVAL for invalid arguments
1380
1381 Prototype:      struct dlist *sysfs_get_classdev_attributes
1382                                         (struct sysfs_class_device *cdev)
1383 -------------------------------------------------------------------------------
1384
1385 -------------------------------------------------------------------------------
1386 Name:           sysfs_open_classdev_attr
1387
1388 Description:    Function takes as arguments, a the name of the class, the class
1389                 device name and the name of the required attribute.
1390
1391         NOTE:
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()
1395
1396 Arguments:      char *classname         Class name on which to search
1397                 char *dev               Name of the class device
1398                 char *attrib            Attribute to open
1399
1400 Returns:        struct sysfs_attribute * with success.
1401                 NULL with error. Errno will be set with error, returning
1402                         - EINVAL for invalid arguments
1403
1404 Prototype:      struct sysfs_attribute *sysfs_write_classdev_attr
1405                         (const char *classname, const char *dev,
1406                                                         const char *attrib)
1407 -------------------------------------------------------------------------------
1408
1409
1410 6.6 Device Functions
1411 --------------------
1412
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.
1418
1419 -------------------------------------------------------------------------------
1420 Name:           sysfs_open_device_path
1421
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
1424                 structure.
1425
1426 Arguments:      const char *path        Path to device
1427
1428 Returns:        struct sysfs_device * with success
1429                 NULL with error. Errno will be set with error, returning
1430                         - EINVAL for invalid arguments
1431
1432 Prototype:      struct sysfs_device *sysfs_open_device_path(const char *path)
1433 -------------------------------------------------------------------------------
1434
1435 -------------------------------------------------------------------------------
1436 Name:           sysfs_close_device
1437
1438 Description:    Function closes up the sysfs_device structure.
1439
1440 Arguments:      sysfs_device *dev               Device structure to close
1441
1442 Prototype:      void sysfs_close_device(struct sysfs_device *dev)
1443 -------------------------------------------------------------------------------
1444
1445 -------------------------------------------------------------------------------
1446 Name:           sysfs_open_root_device
1447
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.
1451
1452 Arguments:      const char *name        Name of the root device to open
1453
1454 Returns:        struct sysfs_root_device * with success
1455                 NULL with error. Errno will be set with error, returning
1456                         - EINVAL for invalid arguments
1457
1458 Prototype:      struct sysfs_device *sysfs_open_root_device(const char *name)
1459 -------------------------------------------------------------------------------
1460
1461 -------------------------------------------------------------------------------
1462 Name:           sysfs_close_root_device
1463
1464 Description:    Function closes up the sysfs_root_device structure including the
1465                 devices in the root device tree.
1466
1467 Arguments:      sysfs_device *root      Root device structure to close
1468
1469 Prototype:      void sysfs_close_root_device(struct sysfs_root_device *root)
1470 -------------------------------------------------------------------------------
1471
1472 -------------------------------------------------------------------------------
1473 Name:           sysfs_open_device_tree
1474
1475 Description:    Function opens up the device tree at the specified path.
1476
1477 Arguments:      const char *path        Path at which to open the device tree
1478
1479 Returns:        struct sysfs_device * with success
1480                 NULL with error, Errno will be set with error, returning
1481                         - EINVAL for invalid arguments
1482
1483 Prototype:      struct sysfs_device *sysfs_open_device_tree(const char *path)
1484 -------------------------------------------------------------------------------
1485
1486 -------------------------------------------------------------------------------
1487 Name:           sysfs_close_device_tree
1488
1489 Description:    Function closes the device tree originating at the given
1490                 sysfs_device.
1491
1492 Arguments:      struct sysfs_device *devroot    Device from which the device
1493                                                 tree has to be closed
1494
1495 Prototype:      void sysfs_close_device_tree(struct sysfs_device *devroot)
1496 -------------------------------------------------------------------------------
1497
1498 -------------------------------------------------------------------------------
1499 Name:           sysfs_get_device_parent
1500
1501 Description:    Function returns the sysfs_device reference for the parent
1502                 (if present) of the given sysfs_device.
1503
1504 Arguments:      struct sysfs_device *dev        sysfs_device whose parent
1505                                                 reference is required
1506
1507 Returns:        struct sysfs_device * on success
1508                 NULL with error. Errno will be set with error, returning
1509                         - EINVAL for invalid arguments
1510
1511 Prototype:      struct sysfs_device *sysfs_get_device_parent
1512                                                 (struct sysfs_device *dev)
1513 -------------------------------------------------------------------------------
1514
1515 -------------------------------------------------------------------------------
1516 Name:           sysfs_get_root_devices
1517
1518 Description:    Function returns a list of devices under the given root device.
1519
1520 Arguments:      struct sysfs_root_device *root  sysfs_root_device whose devices
1521                                                 list is required
1522
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
1526
1527 Prototype:      struct dlist *sysfs_get_root_devices
1528                                         (struct sysfs_root_device *root)
1529 -------------------------------------------------------------------------------
1530
1531 -------------------------------------------------------------------------------
1532 Name:           sysfs_get_device_attr
1533
1534 Description:    Searches supplied device's attributes by name and returns
1535                 the attribute.
1536
1537 Arguments:      struct sysfs_device *dev        Device to search
1538                 const char *name                Attribute name to find
1539
1540 Returns:        struct sysfs_attribute * with success
1541                 NULL with error. Errno will be set with error, returning
1542                         - EINVAL for invalid arguments
1543
1544 Prototype:      struct sysfs_attribute *sysfs_get_device_attr
1545                         (struct sysfs_device *dev, const char *name)
1546 -------------------------------------------------------------------------------
1547
1548 -------------------------------------------------------------------------------
1549 Name:           sysfs_get_device_attributes
1550
1551 Description:    Function takes a sysfs_device structure and returns a list
1552                 of attributes for the device.
1553
1554 Arguments:      struct sysfs_device *device     Device for which
1555                                                 attributes are required
1556
1557 Returns:        struct dlist * of attributes with success
1558                 NULL with error. Errno will be set with error, returning
1559                         - EINVAL for invalid arguments
1560
1561 Prototype:      struct dlist *sysfs_get_device_attributes
1562                                         (struct sysfs_device *device)
1563 -------------------------------------------------------------------------------
1564
1565 -------------------------------------------------------------------------------
1566 Name:           sysfs_refresh_device_attributes
1567
1568 Description:    Function refreshes the list of attributes for a given
1569                 sysfs_device.
1570
1571 Arguments:      struct sysfs_device *device     Device whose attributes list
1572                                                 to refresh
1573
1574 Returns:        struct dlist * of attributes with success
1575                 NULL with error. Errno will be set with error, returning
1576                         - EINVAL for invalid arguments
1577
1578 Prototype:      struct dlist *sysfs_refresh_device_attributes
1579                                         (struct sysfs_device *device)
1580 -------------------------------------------------------------------------------
1581
1582 -------------------------------------------------------------------------------
1583 Name:           sysfs_open_device
1584
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.
1588
1589 Arguments:      const char *bus         Bus on which to search
1590                 const char *bus_id      Device to look for
1591
1592 Returns:        struct sysfs_device * with success
1593                 NULL with error. Errno will be set with error, returning
1594                         - EINVAL for invalid arguments
1595
1596 Prototype:      struct sysfs_device *sysfs_open_device
1597                         (const char *bus, const char *bus_id)
1598 -------------------------------------------------------------------------------
1599
1600 -------------------------------------------------------------------------------
1601 Name:           sysfs_get_device_bus
1602
1603 Description:    Given a sysfs_device, this function fills in the bus this
1604                 device is on in the sysfs_device->bus field.
1605
1606 Arguments:      struct sysfs_device *dev        Device whose bus name to find
1607
1608 Returns:        0 with success.
1609                 -1 with error. Errno will be set with error, returning
1610                         - EINVAL for invalid arguments
1611
1612 Prototype:      int sysfs_get_device_bus(struct sysfs_device *dev)
1613 -------------------------------------------------------------------------------
1614
1615 -------------------------------------------------------------------------------
1616 Name:           sysfs_open_device_attr
1617
1618 Description:    Function takes as arguments, the bus on which to search for a
1619                 device, and an attribute of the device to open.
1620
1621         NOTE:
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()
1625
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
1629
1630 Returns:        struct sysfs_attribute * with success.
1631                 NULL with error. Errno will be set with error, returning
1632                         - EINVAL for invalid arguments
1633
1634 Prototype:      struct sysfs_attribute *sysfs_open_device_attr
1635                 (const char *bus, const char *bus_id, const char *attrib)
1636 -------------------------------------------------------------------------------
1637
1638
1639 6.7 Driver Functions
1640 --------------------
1641
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.
1645
1646 -------------------------------------------------------------------------------
1647 Name:           sysfs_open_driver_path
1648
1649 Description:    Opens driver at specific path.
1650
1651 Arguments:      const char *path        Path to driver
1652
1653 Returns:        struct sysfs_driver * with success
1654                 NULL with error. Errno will be set with error, returning
1655                         - EINVAL for invalid arguments
1656
1657 Prototype:      struct sysfs_driver *sysfs_open_driver_path(const char *path)
1658 -------------------------------------------------------------------------------
1659
1660 -------------------------------------------------------------------------------
1661 Name:           sysfs_close_driver
1662
1663 Description:    Closes and cleans up sysfs_driver structure.
1664
1665 Arguments:      sysfs_driver *driver    Driver structure to close
1666
1667 Prototype:      void sysfs_close_driver(struct sysfs_driver *driver)
1668 -------------------------------------------------------------------------------
1669
1670 -------------------------------------------------------------------------------
1671 Name:           sysfs_get_driver_devices
1672
1673 Description:    Function returns a list of devices that use this driver.
1674
1675 Arguments:      struct sysfs_driver *driver     Driver whose devices list is
1676                                                 required
1677
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
1681
1682 Prototype:      struct dlist *sysfs_get_driver_devices
1683                                         (struct sysfs_driver *driver)
1684 -------------------------------------------------------------------------------
1685
1686 -------------------------------------------------------------------------------
1687 Name:           sysfs_refresh_driver_devices
1688
1689 Description:    Function refreshes the list of devices that use this driver.
1690
1691 Arguments:      struct sysfs_driver *driver     Driver whose devices list is
1692                                                 required to be refreshed
1693
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
1697
1698 Prototype:      struct dlist *sysfs_refresh_driver_devices
1699                                         (struct sysfs_driver *driver)
1700 -------------------------------------------------------------------------------
1701
1702 -------------------------------------------------------------------------------
1703 Name:           sysfs_get_driver_device
1704
1705 Description:    Function returns a sysfs_device reference for the device with
1706                 "name" that uses this driver
1707
1708 Arguments:      struct sysfs_driver *driver     Driver on which to search
1709                 const char *name                Name of the device to look for
1710
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
1714
1715 Prototype:      struct dlist *sysfs_get_driver_device
1716                         (struct sysfs_driver *driver, const char *name)
1717 -------------------------------------------------------------------------------
1718
1719 -------------------------------------------------------------------------------
1720 Name:           sysfs_get_driver_attr
1721
1722 Description:    Searches supplied driver's attributes by name and returns
1723                 the attribute.
1724
1725 Arguments:      struct sysfs_driver *drv        Driver to search
1726                 const char *name                Attribute name to find
1727
1728 Returns:        struct sysfs_attribute * with success
1729                 NULL with error. Errno will be set with error, returning
1730                         - EINVAL for invalid arguments
1731
1732 Prototype:      struct sysfs_attribute *sysfs_get_driver_attr
1733                         (struct sysfs_driver *drv, const char *name)
1734 -------------------------------------------------------------------------------
1735
1736 -------------------------------------------------------------------------------
1737 Name:           sysfs_get_driver_attributes
1738
1739 Description:    Function takes a sysfs_driver structure and returns a list
1740                 of attributes for the driver.
1741
1742 Arguments:      struct sysfs_driver *driver     Driver for which attributes
1743                                                 are required
1744
1745 Returns:        struct dlist * of attributes with success
1746                 NULL with error. Errno will be set with error, returning
1747                         - EINVAL for invalid arguments
1748
1749 Prototype:      struct dlist *sysfs_get_driver_attributes
1750                                         (struct sysfs_driver *driver)
1751 -------------------------------------------------------------------------------
1752
1753 -------------------------------------------------------------------------------
1754 Name:           sysfs_refresh_driver_attributes
1755
1756 Description:    Function refreshes the list of attributes for a given
1757                 sysfs_driver.
1758
1759 Arguments:      struct sysfs_driver *driver     Driver whose attributes list
1760                                                 to refresh
1761
1762 Returns:        struct dlist * of attributes with success
1763                 NULL with error. Errno will be set with error, returning
1764                         - EINVAL for invalid arguments
1765
1766 Prototype:      struct dlist *sysfs_refresh_driver_attributes
1767                                         (struct sysfs_driver *driver)
1768 -------------------------------------------------------------------------------
1769
1770 -------------------------------------------------------------------------------
1771 Name:           sysfs_open_driver
1772
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.
1776
1777         NOTE:
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()
1783                    to determine this.
1784
1785 Arguments:      const char *bus_name    Bus on which to search
1786                 const char *drv_name    Driver name to look for
1787
1788 Returns:        struct sysfs_driver * with success
1789                 NULL with error. Errno will be set with error, returning
1790                         - EINVAL for invalid arguments
1791
1792 Prototype:      struct sysfs_driver *sysfs_open_driver(const char *bus_name,
1793                                                         const char *drv_name)
1794 -------------------------------------------------------------------------------
1795
1796 -------------------------------------------------------------------------------
1797 Name:           sysfs_get_driver_links
1798
1799 Description:    Function returns a list of links for a given driver
1800
1801 Arguments:      struct sysfs_driver *driver     Driver to get links from
1802
1803 Returns:        struct dlist * of links on success
1804                 NULL with error
1805
1806 Prototype:      struct dlist *sysfs_get_driver_links
1807                                                 (struct sysfs_driver *driver)
1808 -------------------------------------------------------------------------------
1809
1810 -------------------------------------------------------------------------------
1811 Name:           sysfs_open_driver_attr
1812
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.
1815
1816         NOTE:
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()
1820
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
1824
1825 Returns:        struct sysfs_attribute * with success.
1826                 NULL with error. Errno will be set with error, returning
1827                         - EINVAL for invalid arguments
1828
1829 Prototype:      struct sysfs_attribute *sysfs_open_driver_attr
1830                         (const char *bus, const char *drv, const char *attrib)
1831 -------------------------------------------------------------------------------
1832
1833
1834 7 Dlists
1835 --------
1836
1837 Libsysfs uses (yet another) list implementation thanks to Eric J Bohm.
1838
1839
1840 7.1 Navigating a dlist
1841 ----------------------
1842
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.
1845
1846 ------------------------------------------------------------------------------
1847 Function/Macro name:    dlist_for_each_data
1848
1849 Description:            Walk the given list, returning a known data type/
1850                         structure in each iteration.
1851
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
1856                                                 in the list
1857
1858 Returns:                On each iteration, "data_iterator" will contain a list
1859                         element of "datatype"
1860
1861 Usage example:          The function sysfs_get_classdev_attributes() returns a
1862                         dlist of attributes. To navigate the list:
1863
1864                         struct sysfs_attribute *attr = NULL;
1865                         struct dlist *attrlist = NULL;
1866                         .
1867                         .
1868                         .
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) {
1874                                 .
1875                                 .
1876                                 .
1877                                 }
1878                         }
1879 -------------------------------------------------------------------------------
1880
1881
1882 7.2 Custom sorting using dlist_sort_custom()
1883 --------------------------------------------
1884
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.
1889
1890 The sorter function must conform to the following prototype:
1891
1892         int compare(void *a, void*b)
1893
1894 dlist_sort_custom() expects that the compare function will:
1895         return >0 for a before b
1896         return <0 for b before a
1897         return  0 for a == b
1898
1899
1900 8. Usage
1901 --------
1902
1903 Accessing devices through libsysfs is supposed to mirror accessing devices
1904 in the filesystem it represents. Here's a typical order of operation:
1905
1906         - get sysfs mount point
1907         - "open" sysfs category, ie. bus, class, or device
1908         - work with category
1909         - "close" sysfs category
1910
1911
1912 9. Testsuite
1913 ------------
1914
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:
1919
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.
1925
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.
1929
1930 To use the testsuite:
1931
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).
1936
1937 b. Build and install the testsuite.
1938
1939 c. Run the testsuite:
1940
1941         testlibsysfs <number of iterations> <logfile>
1942
1943 The default logfile is stdout.
1944
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.
1947
1948
1949 10. Conclusion
1950 --------------
1951
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.