sysfs-rs

[!IMPORTANT] Please note that this crate is very incomplete, and will not be considered stable for quite some time. The public API is subject to change, drastically. As more sysfs attributes are wrapped and documented, it may be desireable to change the organizational structure to offer a more homogeneous and consistent developer experience.

What is this?

This crate embodies three core goals:

1. Provide safe functions and types for (eventually) all of Linux's sysfs attributes in a well-organized hierarchy.

2. Document each sysfs attribute, as well as the types of data being read from and written to these attributes. Information about sysfs is spread around everywhere, from comments in source code to discussion threads in mailing lists. This crate aims to aggregate that knowledge, and make it easily digestible.

3. Provide attribute macro helpers and transformation functions to generate accessors for any given sysfs attribute. Since sysfs is quite large and individual attributes are difficult to discover and get right, this crate's internal macros are exported for other developers, so that they may define attributes and modules which are missing in this crate.

   • Please contribute attribute definitions!

See the Wikipedia page and the Kernel documentation for more information about Linux's sysfs.

How do I use it?

First, there are some modules defined for sysfs directories whose attributes have already been wrapped. Browse the documentation in the crate's sysfs::api module to see if it has what you need. There are getter functions, for example sysfs::api::psu::power_supply::capacity, which reads the charge level of the battery as an f32 percentage value (0.00 .. 1.00). Then there are setters, which serialize and write typed data to a sysfs attribute file, such as sysfs::api::psu::power_supply::set_charge_behavior.

Second, if there is no wrapper already defined in this crate's sysfs::api module, feel free to implement your own! See the documentation on items in sysfs::lib and the source code of existing modules (such as sysfs::api::cpu) for an idea of how to get started. Also, contributions to the api module are very much welcome and appreciated!