1libsensors(3) Linux Programmer's Manual libsensors(3)
2
6 libsensors - publicly accessible functions provided by the sensors
7 library
8
11 #include <sensors/sensors.h>
12 /* Library initialization and clean-up */
14 int sensors_init(FILE *input);
15 void sensors_cleanup(void);
16 const char *libsensors_version;
17 /* Chip name handling */
19 int sensors_parse_chip_name(const char *orig_name,
20 sensors_chip_name *res);
21 void sensors_free_chip_name(sensors_chip_name *chip);
22 int sensors_snprintf_chip_name(char *str, size_t size,
23 const sensors_chip_name *chip);
24 const char *sensors_get_adapter_name(const sensors_bus_id *bus);
25 /* Chips and features enumeration */
27 const sensors_chip_name *
28 sensors_get_detected_chips(const sensors_chip_name *match,
29 int *nr);
30 const sensors_feature *
31 sensors_get_features(const sensors_chip_name *name,
32 int *nr);
33 const sensors_subfeature *
34 sensors_get_all_subfeatures(const sensors_chip_name *name,
35 const sensors_feature *feature,
36 int *nr);
37 const sensors_subfeature *
38 sensors_get_subfeature(const sensors_chip_name *name,
39 const sensors_feature *feature,
40 sensors_subfeature_type type);
41 /* Features access */
43 char *sensors_get_label(const sensors_chip_name *name,
44 const sensors_feature *feature);
45 int sensors_get_value(const sensors_chip_name *name, int subfeat_nr,
46 double *value);
47 int sensors_set_value(const sensors_chip_name *name, int subfeat_nr,
48 double value);
49 int sensors_do_chip_sets(const sensors_chip_name *name);
50 #include <sensors/error.h>
52 /* Error decoding */
54 const char *sensors_strerror(int errnum);
55 /* Error handlers */
57 void (*sensors_parse_error) (const char *err, int lineno);
58 void (*sensors_parse_error_wfn) (const char *err,
59 const char *filename, int lineno);
60 void (*sensors_fatal_error) (const char *proc, const char *err);
61
64 sensors_init() loads the configuration file and the detected chips
65 list. If this returns a value unequal to zero, you are in trouble; you
66 can not assume anything will be initialized properly. If you want to
67 reload the configuration file, or load a different configuration file,
68 call sensors_cleanup() below before calling sensors_init() again. This
69 means you can't load multiple configuration files at once by calling
70 sensors_init() multiple times.
71 The configuration file format is described in sensors.conf(5).
73 If FILE is NULL, the default configuration files are used (see the
75 FILES section below). Most applications will want to do that.
76 sensors_cleanup() cleans everything up: you can't access anything after
78 this, until the next sensors_init() call!
79 libsensors_version is a string representing the version of libsensors.
81 sensors_parse_chip_name() parses a chip name to the internal represen‐
83 tation. Return 0 on success, <0 on error. Make sure to call sen‐
84 sors_free_chip_name() when you're done with the data.
85 sensors_free_chip_name() frees the memory that may have been allocated
87 for the internal representation of a chip name. You only have to call
88 this for chip names which do not originate from libsensors itself (that
89 is, chip names which were generated by sensors_parse_chip_name()).
90 sensors_snprintf_chip_name() prints a chip name from its internal rep‐
92 resentation. Note that chip should not contain wildcard values! Return
93 the number of characters printed on success (same as snprintf), <0 on
94 error.
95 sensors_get_adapter_name() returns the adapter name of a bus type, num‐
97 ber pair, as used within the sensors_chip_name structure. If it could
98 not be found, it returns NULL.
99 Adapters describe how a monitoring chip is hooked up to the system.
101 This is particularly relevant for I2C/SMBus sensor chips (bus type
102 "i2c"), which must be accessed over an I2C/SMBus controller. Each such
103 controller has a different number, assigned by the system at initial‐
104 ization time, so that they can be referenced individually.
105 Super-I/O or CPU-embedded sensors, on the other hand, can be accessed
107 directly and technically don't use any adapter. They have only a bus
108 type but no bus number, and sensors_get_adapter_name() will return a
109 generic adapter name for them.
110 sensors_get_detected_chips() returns all detected chips that match a
112 given chip name, one by one. If no chip name is provided, all detected
113 chips are returned. To start at the beginning of the list, use 0 for
114 nr; NULL is returned if we are at the end of the list. Do not try to
115 change these chip names, as they point to internal structures!
116 sensors_get_features() returns all main features of a specific chip. nr
118 is an internally used variable. Set it to zero to start at the begin of
119 the list. If no more features are found NULL is returned. Do not try
120 to change the returned structure; you will corrupt internal data struc‐
121 tures.
122 sensors_get_all_subfeatures() returns all subfeatures of a given main
124 feature. nr is an internally used variable. Set it to zero to start at
125 the begin of the list. If no more subfeatures are found NULL is
126 returned. Do not try to change the returned structure; you will cor‐
127 rupt internal data structures.
128 sensors_get_subfeature() returns the subfeature of the given type for a
130 given main feature, if it exists, NULL otherwise. Do not try to change
131 the returned structure; you will corrupt internal data structures.
132 sensors_get_label() looks up the label which belongs to this chip. Note
134 that chip should not contain wildcard values! The returned string is
135 newly allocated (free it yourself). On failure, NULL is returned. If
136 no label exists for this feature, its name is returned itself.
137 sensors_get_value() Reads the value of a subfeature of a certain chip.
139 Note that chip should not contain wildcard values! This function will
140 return 0 on success, and <0 on failure.
141 sensors_set_value() sets the value of a subfeature of a certain chip.
143 Note that chip should not contain wildcard values! This function will
144 return 0 on success, and <0 on failure.
145 sensors_do_chip_sets() executes all set statements for this particular
147 chip. The chip may contain wildcards! This function will return 0 on
148 success, and <0 on failure.
149 sensors_strerror() returns a pointer to a string which describes the
151 error. errnum may be negative (the corresponding positive error is
152 returned). You may not modify the result!
153 sensors_parse_error() and sensors_parse_error_wfn() are functions which
155 are called when a parse error is detected. Give them new values, and
156 your own functions are called instead of the default (which print to
157 stderr). These functions may terminate the program, but they usually
158 output an error and return. The first function is the original one, the
159 second one was added later when support for multiple configuration
160 files was added. The library code now only calls the second function.
161 However, for backwards compatibility, if an application provides a cus‐
162 tom handling function for the first function but not the second, then
163 all parse errors will be reported using the first function (that is,
164 the filename is never reported.) Note that filename can be NULL (if
165 filename isn't known) and lineno can be 0 (if the error occurs before
166 the actual parsing starts.)
167 sensors_fatal_error() Is a function which is called when an immediately
169 fatal error (like no memory left) is detected. Give it a new value, and
170 your own function is called instead of the default (which prints to
171 stderr and ends the program). Never let it return!
172
175 Structure sensors_chip_name contains information related to a specific
176 chip.
177 typedef struct sensors_chip_name {
179 sensors_bus_id bus;
180 } sensors_chip_name;
181 There are other members not documented here, which are only meant for
183 libsensors internal use.
184 Structure sensors_feature contains information related to a given fea‐
186 ture of a specific chip:
187 typedef struct sensors_feature {
189 const char *name;
190 int number;
191 sensors_feature_type type;
192 } sensors_feature;
193 There are other members not documented here, which are only meant for
195 libsensors internal use.
196 Structure sensors_subfeature contains information related to a given
198 subfeature of a specific chip feature:
199 typedef struct sensors_subfeature {
201 const char *name;
202 int number;
203 sensors_subfeature_type type;
204 int mapping;
205 unsigned int flags;
206 } sensors_subfeature;
207 The flags field is a bitfield, its value is a combination of SEN‐
209 SORS_MODE_R (readable), SENSORS_MODE_W (writable) and SENSORS_COM‐
210 PUTE_MAPPING (affected by the computation rules of the main feature).
211
214 /etc/sensors3.conf
215 /etc/sensors.conf
216 The system-wide libsensors(3) configuration file. /etc/sen‐
217 sors3.conf is tried first, and if it doesn't exist, /etc/sen‐
218 sors.conf is used instead.
219 /etc/sensors.d
221 A directory where you can put additional libsensors configura‐
222 tion files. Files found in this directory will be processed in
223 alphabetical order after the default configuration file. Files
224 with names that start with a dot are ignored.
225
228 sensors.conf(5)
229
232 Frodo Looijaard, Jean Delvare and others http://www.lm-sensors.org/
233lm-sensors 3 September 2013 libsensors(3)