libsensors(3)

🎀 libsensors — publicly accessible functions provided by the sensors library 🎀

okay bestie, come SIT. this is libsensors(3), straight out of the Linux Programmer's Manual, and it's literally the whole friend group of functions the sensors library lets you call. it's giving "backstage pass to all your hardware sensors" energy and i am obsessed 💖

---

✨ SYNOPSIS ✨

#include <sensors/sensors.h>

/* Library initialization and clean-up */
int sensors_init(FILE *input);
void sensors_cleanup(void);
const char *libsensors_version;

/* Chip name handling */
int sensors_parse_chip_name(const char *orig_name,
                            sensors_chip_name *res);
void sensors_free_chip_name(sensors_chip_name *chip);
int sensors_snprintf_chip_name(char *str, size_t size,
                               const sensors_chip_name *chip);
const char *sensors_get_adapter_name(const sensors_bus_id *bus);

/* Chips and features enumeration */
const sensors_chip_name *
sensors_get_detected_chips(const sensors_chip_name *match,
                           int *nr);
const sensors_feature *
sensors_get_features(const sensors_chip_name *name,
                     int *nr);
const sensors_subfeature *
sensors_get_all_subfeatures(const sensors_chip_name *name,
                            const sensors_feature *feature,
                            int *nr);
const sensors_subfeature *
sensors_get_subfeature(const sensors_chip_name *name,
                       const sensors_feature *feature,
                       sensors_subfeature_type type);

/* Features access */
char *sensors_get_label(const sensors_chip_name *name,
                        const sensors_feature *feature);
int sensors_get_value(const sensors_chip_name *name, int subfeat_nr,
                      double *value);
int sensors_set_value(const sensors_chip_name *name, int subfeat_nr,
                      double value);
int sensors_do_chip_sets(const sensors_chip_name *name);

#include <sensors/error.h>

/* Error decoding */
const char *sensors_strerror(int errnum);

/* Error handlers */
void (*sensors_parse_error) (const char *err, int lineno);
void (*sensors_parse_error_wfn) (const char *err,
                                 const char *filename, int lineno);
void (*sensors_fatal_error) (const char *proc, const char *err);

---

💅 DESCRIPTION 💅

🌟 getting started & shutting down 🌟

sensors_init() loads the config file AND the detected chips list, in one go. if it hands you back anything that isn't zero, bestie you're in trouble — do NOT assume anything got initialized properly. and listen: if you wanna reload the config file, or load a different one, you gotta call sensors_cleanup() (down below) before you call sensors_init() again. which means no, you can't load multiple config files at once by spamming sensors_init() multiple times. it's not that kind of party. 🙅‍♀️

the config file format is described over in sensors.conf(5), go peek.

if FILE is NULL, the default config files get used (check the FILES section below, it's right there). most applications will want to do exactly that. slay.

sensors_cleanup() cleans everything up. after this you can't access anything, like, at all — not until the next sensors_init() call! 👑

libsensors_version is a string representing the version of libsensors. cute lil flex.

🦋 chip name handling 🦋

sensors_parse_chip_name() parses a chip name into the internal representation. returns 0 on success, <0 on error. and make sure you call sensors_free_chip_name() when you're done with the data — don't leave it hanging, that's rude.

sensors_free_chip_name() frees the memory that may have been allocated for the internal representation of a chip name. you only have to call this for chip names which do not originate from libsensors itself — i.e. the ones that were generated by sensors_parse_chip_name().

sensors_snprintf_chip_name() prints a chip name from its internal representation. heads up: chip should not contain wildcard values! returns the number of characters printed on success (same as snprintf), <0 on error.

sensors_get_adapter_name() returns the adapter name of a bus type / number pair, as used within the sensors_chip_name structure. if it couldn't be found, it returns NULL. tragic, but okay.

adapters describe how a monitoring chip is hooked up to the system. this is particularly relevant for I2C/SMBus sensor chips (bus type "i2c"), which must be accessed over an I2C/SMBus controller. each such controller has a different number, assigned by the system at initialization time, so that they can be referenced individually. iykyk.

super-I/O or CPU-embedded sensors, on the other hand, can be accessed directly and technically don't use any adapter. they have only a bus type but no bus number, and sensors_get_adapter_name() will return a generic adapter name for them. no bus number, no problem ✨

🌈 chips & features enumeration 🌈

sensors_get_detected_chips() returns all detected chips that match a given chip name, one by one. if no chip name is provided, all detected chips are returned. to start at the beginning of the list, use 0 for nr; NULL is returned if we are at the end of the list. and do NOT try to change these chip names, because they point to internal structures! hands off the merchandise 🙈

sensors_get_features() returns all main features of a specific chip. nr is an internally used variable. set it to zero to start at the begin of the list. if no more features are found NULL is returned. do not try to change the returned structure; you will corrupt internal data structures. i'm serious, the vibes will be ruined.

sensors_get_all_subfeatures() returns all subfeatures of a given main feature. nr is an internally used variable. set it to zero to start at the begin of the list. if no more subfeatures are found NULL is returned. do not try to change the returned structure; you will corrupt internal data structures.

sensors_get_subfeature() returns the subfeature of the given type for a given main feature, if it exists, NULL otherwise. do not try to change the returned structure; you will corrupt internal data structures.

💖 features access 💖

sensors_get_label() looks up the label which belongs to this chip. note that chip should not contain wildcard values! the returned string is newly allocated (so free it yourself, bestie, it's yours now). on failure, NULL is returned. and if no label exists for this feature, its name is returned itself. self-titled era 💅

sensors_get_value() reads the value of a subfeature of a certain chip. note that chip should not contain wildcard values! this function will return 0 on success, and <0 on failure.

sensors_set_value() sets the value of a subfeature of a certain chip. note that chip should not contain wildcard values! this function will return 0 on success, and <0 on failure.

sensors_do_chip_sets() executes all set statements for this particular chip. the chip may contain wildcards here! this function will return 0 on success, and <0 on failure.

🧚 error decoding & handlers 🧚

sensors_strerror() returns a pointer to a string which describes the error. errnum may be negative (the corresponding positive error is returned). you may not modify the result! that string is not yours, it's a loaner.

sensors_parse_error() and sensors_parse_error_wfn() are functions which are called when a parse error is detected. give them new values, and your own functions are called instead of the default (which print to stderr). these functions may terminate the program, but they usually output an error and return. the first function is the original one, the second one was added later when support for multiple configuration files was added. the library code now only calls the second function. however, for backwards compatibility, if an application provides a custom handling function for the first function but not the second, then all parse errors will be reported using the first function (that is, the filename is never reported.) note that filename can be NULL (if filename isn't known) and lineno can be 0 (if the error occurs before the actual parsing starts.) keeping it retro 🫶

sensors_fatal_error() is a function which is called when an immediately fatal error (like no memory left) is detected. give it a new value, and your own function is called instead of the default (which prints to stderr and ends the program). Never let it return! never ever. that's the whole rule.

---

🌸 DATA STRUCTURES 🌸

sensors_chip_name

structure sensors_chip_name contains information related to a specific chip.

typedef struct sensors_chip_name {
     sensors_bus_id bus;
} sensors_chip_name;

there are other members not documented here, which are only meant for libsensors internal use. no peeking behind the curtain ✨

sensors_feature

structure sensors_feature contains information related to a given feature of a specific chip:

typedef struct sensors_feature {
     const char *name;
     int number;
     sensors_feature_type type;
} sensors_feature;

there are other members not documented here, which are only meant for libsensors internal use.

sensors_subfeature

structure sensors_subfeature contains information related to a given subfeature of a specific chip feature:

typedef struct sensors_subfeature {
     const char *name;
     int number;
     sensors_subfeature_type type;
     int mapping;
     unsigned int flags;
} sensors_subfeature;

the flags field is a bitfield, its value is a combination of SENSORS_MODE_R (readable), SENSORS_MODE_W (writable) and SENSORS_COMPUTE_MAPPING (affected by the computation rules of the main feature). read it, write it, compute it, the whole trifecta 💅

---

🍓 FILES 🍓

• /etc/sensors3.conf
• /etc/sensors.conf

the system-wide libsensors(3) configuration file. /etc/sensors3.conf is tried first, and if it doesn't exist, /etc/sensors.conf is used instead. first come, first served 💖

• /etc/sensors.d

a directory where you can put additional libsensors configuration files. files found in this directory will be processed in alphabetical order after the default configuration file. files with names that start with a dot are ignored. sorry to the hidden files, it's not personal 🎀

---

👑 SEE ALSO 👑

sensors.conf(5)

---

🌟 AUTHOR 🌟

Frodo Looijaard, Jean Delvare and others https://hwmon.wiki.kernel.org/lm_sensors

---

and that's the whole page, bestie. this one shipped with lm-sensors 3, dated September 2013 — vintage but still iconic fr fr. now go read your sensors, hydrate, and remember: never let sensors_fatal_error return. mwah 💜🦋✨