1libsensors(3)              Linux Programmer's Manual             libsensors(3)
2
3
4

NAME

6       libsensors  -  publicly  accessible  functions  provided by the sensors
7       library
8
9

SYNOPSIS

11       #include <sensors/sensors.h>
12
13       /* Library initialization and clean-up */
14       int sensors_init(FILE *input);
15       void sensors_cleanup(void);
16       const char *libsensors_version;
17
18       /* 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
26       /* 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
42       /* 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
51       #include <sensors/error.h>
52
53       /* Error decoding */
54       const char *sensors_strerror(int errnum);
55
56       /* 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
62

DESCRIPTION

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
72       The configuration file format is described in sensors.conf(5).
73
74       If FILE is NULL, the default configuration  files  are  used  (see  the
75       FILES section below). Most applications will want to do that.
76
77       sensors_cleanup() cleans everything up: you can't access anything after
78       this, until the next sensors_init() call!
79
80       libsensors_version is a string representing the version of libsensors.
81
82       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
86       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
91       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
96       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
100       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
106       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
111       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
117       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
123       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
129       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
133       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
138       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
142       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
146       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
150       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
154       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
168       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
173

DATA STRUCTURES

175       Structure  sensors_feature contains information related to a given fea‐
176       ture of a specific chip:
177
178       typedef struct sensors_feature {
179            const char *name;
180            int number;
181            sensors_feature_type type;
182       } sensors_feature;
183
184       There are other members not documented here, which are only  meant  for
185       libsensors internal use.
186
187       Structure  sensors_subfeature  contains  information related to a given
188       subfeature of a specific chip feature:
189
190       typedef struct sensors_subfeature {
191            const char *name;
192            int number;
193            sensors_subfeature_type type;
194            int mapping;
195            unsigned int flags;
196       } sensors_subfeature;
197
198       The flags field is a bitfield, its  value  is  a  combination  of  SEN‐
199       SORS_MODE_R  (readable),  SENSORS_MODE_W  (writable)  and  SENSORS_COM‐
200       PUTE_MAPPING (affected by the computation rules of the main feature).
201
202

FILES

204       /etc/sensors3.conf
205       /etc/sensors.conf
206              The  system-wide  libsensors(3)  configuration  file.  /etc/sen‐
207              sors3.conf  is  tried  first, and if it doesn't exist, /etc/sen‐
208              sors.conf is used instead.
209
210       /etc/sensors.d
211              A directory where you can put additional  libsensors  configura‐
212              tion  files.  Files found in this directory will be processed in
213              alphabetical order after the default configuration  file.  Files
214              with names that start with a dot are ignored.
215
216

SEE ALSO

218       sensors.conf(5)
219
220

AUTHOR

222       Frodo Looijaard, Jean Delvare and others http://www.lm-sensors.org/
223
224
225
226
227lm-sensors 3                    September 2013                   libsensors(3)
Impressum