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, call sensors_cleanup() below before
68 calling sensors_init() again.
69 If FILE is NULL, the default configuration files are used (see the
71 FILES section below). Most applications will want to do that.
72 sensors_cleanup() cleans everything up: you can't access anything after
74 this, until the next sensors_init() call!
75 libsensors_version is a string representing the version of libsensors.
77 sensors_parse_chip_name() parses a chip name to the internal represen‐
79 tation. Return 0 on success, <0 on error. Make sure to call sen‐
80 sors_free_chip_name() when you're done with the data.
81 sensors_free_chip_name() frees the memory that may have been allocated
83 for the internal representation of a chip name. You only have to call
84 this for chip names which do not originate from libsensors itself (that
85 is, chip names which were generated by sensors_parse_chip_name()).
86 sensors_snprintf_chip_name() prints a chip name from its internal rep‐
88 resentation. Note that chip should not contain wildcard values! Return
89 the number of characters printed on success (same as snprintf), <0 on
90 error.
91 sensors_get_adapter_name() returns the adapter name of a bus number, as
93 used within the sensors_chip_name structure. If it could not be found,
94 it returns NULL.
95 sensors_get_detected_chips() returns all detected chips that match a
97 given chip name, one by one. If no chip name is provided, all detected
98 chips are returned. To start at the beginning of the list, use 0 for
99 nr; NULL is returned if we are at the end of the list. Do not try to
100 change these chip names, as they point to internal structures!
101 sensors_get_features() returns all main features of a specific chip. nr
103 is an internally used variable. Set it to zero to start at the begin of
104 the list. If no more features are found NULL is returned. Do not try
105 to change the returned structure; you will corrupt internal data struc‐
106 tures.
107 sensors_get_all_subfeatures() returns all subfeatures of a given main
109 feature. nr is an internally used variable. Set it to zero to start at
110 the begin of the list. If no more subfeatures are found NULL is
111 returned. Do not try to change the returned structure; you will cor‐
112 rupt internal data structures.
113 sensors_get_subfeature() returns the subfeature of the given type for a
115 given main feature, if it exists, NULL otherwise. Do not try to change
116 the returned structure; you will corrupt internal data structures.
117 sensors_get_label() looks up the label which belongs to this chip. Note
119 that chip should not contain wildcard values! The returned string is
120 newly allocated (free it yourself). On failure, NULL is returned. If
121 no label exists for this feature, its name is returned itself.
122 sensors_get_value() Reads the value of a subfeature of a certain chip.
124 Note that chip should not contain wildcard values! This function will
125 return 0 on success, and <0 on failure.
126 sensors_set_value() sets the value of a subfeature of a certain chip.
128 Note that chip should not contain wildcard values! This function will
129 return 0 on success, and <0 on failure.
130 sensors_do_chip_sets() executes all set statements for this particular
132 chip. The chip may contain wildcards! This function will return 0 on
133 success, and <0 on failure.
134 sensors_strerror() returns a pointer to a string which describes the
136 error. errnum may be negative (the corresponding positive error is
137 returned). You may not modify the result!
138 sensors_parse_error() and sensors_parse_error_wfn() are functions which
140 are called when a parse error is detected. Give them new values, and
141 your own functions are called instead of the default (which print to
142 stderr). These functions may terminate the program, but they usually
143 output an error and return. The first function is the original one, the
144 second one was added later when support for multiple configuration
145 files was added. The library code now only calls the second function.
146 However, for backwards compatibility, if an application provides a cus‐
147 tom handling function for the first function but not the second, then
148 all parse errors will be reported using the first function (that is,
149 the filename is never reported.) Note that filename can be NULL (if
150 filename isn't known) and lineno can be 0 (if the error occurs before
151 the actual parsing starts.)
152 sensors_fatal_error() Is a function which is called when an immediately
154 fatal error (like no memory left) is detected. Give it a new value, and
155 your own function is called instead of the default (which prints to
156 stderr and ends the program). Never let it return!
157
160 Structure sensors_feature contains information related to a given fea‐
161 ture of a specific chip:
162 typedef struct sensors_feature {
164 const char *name;
165 int number;
166 sensors_feature_type type;
167 } sensors_feature;
168 There are other members not documented here, which are only meant for
170 libsensors internal use.
171 Structure sensors_subfeature contains information related to a given
173 subfeature of a specific chip feature:
174 typedef struct sensors_subfeature {
176 const char *name;
177 int number;
178 sensors_subfeature_type type;
179 int mapping;
180 unsigned int flags;
181 } sensors_subfeature;
182 The flags field is a bitfield, its value is a combination of SEN‐
184 SORS_MODE_R (readable), SENSORS_MODE_W (writable) and SENSORS_COM‐
185 PUTE_MAPPING (affected by the computation rules of the main feature).
186
189 /etc/sensors3.conf
190 /etc/sensors.conf
191 The system-wide libsensors(3) configuration file. /etc/sen‐
192 sors3.conf is tried first, and if it doesn't exist, /etc/sen‐
193 sors.conf is used instead.
194 /etc/sensors.d
196 A directory where you can put additional libsensors configura‐
197 tion files. Files found in this directory will be processed in
198 alphabetical order after the default configuration file. Files
199 with names that start with a dot are ignored.
200
203 sensors.conf(5)
204
207 Frodo Looijaard and the lm_sensors group http://www.lm-sensors.org/
208lm-sensors 3 February 2009 libsensors(3)