libsensors(3) Linux Programmer's Manual libsensors(3)NAMElibsensors - publicly accessible functions provided by the sensors
library
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);
DESCRIPTIONsensors_init() loads the configuration file and the detected chips
list. If this returns a value unequal to zero, you are in trouble; you
can not assume anything will be initialized properly. If you want to
reload the configuration file, or load a different configuration file,
call sensors_cleanup() below before calling sensors_init() again. This
means you can't load multiple configuration files at once by calling
sensors_init() multiple times.
The configuration file format is described in sensors.conf(5).
If FILE is NULL, the default configuration files are used (see the
FILES section below). Most applications will want to do that.
sensors_cleanup() cleans everything up: you can't access anything after
this, until the next sensors_init() call!
libsensors_version is a string representing the version of libsensors.
sensors_parse_chip_name() parses a chip name to the internal represen‐
tation. Return 0 on success, <0 on error. Make sure to call sen‐
sors_free_chip_name() when you're done with the data.
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 (that
is, chip names which were generated by sensors_parse_chip_name()).
sensors_snprintf_chip_name() prints a chip name from its internal rep‐
resentation. Note that chip should not contain wildcard values! Return
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, num‐
ber pair, as used within the sensors_chip_name structure. If it could
not be found, it returns NULL.
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 initial‐
ization time, so that they can be referenced individually.
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.
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. Do not try to
change these chip names, as they point to internal structures!
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 struc‐
tures.
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 cor‐
rupt 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.
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 (free it yourself). On failure, NULL is returned. If
no label exists for this feature, its name is returned itself.
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! This function will return 0 on
success, and <0 on failure.
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!
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 cus‐
tom 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.)
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!
DATA STRUCTURES
Structure sensors_feature contains information related to a given fea‐
ture 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.
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 SEN‐
SORS_MODE_R (readable), SENSORS_MODE_W (writable) and SENSORS_COM‐
PUTE_MAPPING (affected by the computation rules of the main feature).
FILES
/etc/sensors3.conf
/etc/sensors.conf
The system-wide libsensors(3) configuration file. /etc/sen‐
sors3.conf is tried first, and if it doesn't exist, /etc/sen‐
sors.conf is used instead.
/etc/sensors.d
A directory where you can put additional libsensors configura‐
tion 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.
SEE ALSOsensors.conf(5)AUTHOR
Frodo Looijaard, Jean Delvare and others http://www.lm-sensors.org/
lm-sensors 3 September 2013 libsensors(3)
