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.