root/lm-sensors/trunk/lib/libsensors.3 @ 5844

Revision 5844, 9.8 KB (checked in by khali, 4 years ago)

Change libsensors license from GPL to LGPL.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
Line 
1.\" Copyright (C) 1998, 1999  Adrian Baugh <adrian.baugh@keble.ox.ac.uk>
2.\" Copyright (C) 2007, 2009  Jean Delvare <khali@linux-fr.org>
3.\" based on sensors.h, part of libsensors by Frodo Looijaard
4.\" libsensors is distributed under the LGPL
5.\"
6.\" Permission is granted to make and distribute verbatim copies of this
7.\" manual provided the copyright notice and this permission notice are
8.\" preserved on all copies.
9.\"
10.\" Permission is granted to copy and distribute modified versions of this
11.\" manual under the conditions for verbatim copying, provided that the
12.\" entire resulting derived work is distributed under the terms of a
13.\" permission notice identical to this one
14.\"
15.\" Since the Linux kernel and libraries are constantly changing, this
16.\" manual page may be incorrect or out-of-date.  The author(s) assume no
17.\" responsibility for errors or omissions, or for damages resulting from
18.\" the use of the information contained herein.  The author(s) may not
19.\" have taken the same level of care in the production of this manual,
20.\" which is licensed free of charge, as they might when working
21.\" professionally.
22.\"
23.\" Formatted or processed versions of this manual, if unaccompanied by
24.\" the source, must acknowledge the copyright and authors of this work.
25.\"
26.\" References consulted:
27.\"     libsensors source code
28.TH libsensors 3  "February 2009" "lm-sensors 3" "Linux Programmer's Manual"
29
30.SH NAME
31libsensors \- publicly accessible functions provided by the sensors library
32
33.SH SYNOPSIS
34.nf
35.B #include <sensors/sensors.h>
36
37/* Library initialization and clean-up */
38.BI "int sensors_init(FILE *" input ");"
39.B void sensors_cleanup(void);
40.BI "const char *" libsensors_version ";"
41
42/* Chip name handling */
43.BI "int sensors_parse_chip_name(const char *" orig_name ","
44.BI "                            sensors_chip_name *" res ");"
45.BI "void sensors_free_chip_name(sensors_chip_name *" chip ");"
46.BI "int sensors_snprintf_chip_name(char *" str ", size_t " size ","
47.BI "                               const sensors_chip_name *" chip ");"
48.BI "const char *sensors_get_adapter_name(const sensors_bus_id *" bus ");"
49
50/* Chips and features enumeration */
51.B const sensors_chip_name *
52.BI "sensors_get_detected_chips(const sensors_chip_name *" match ","
53.BI "                           int *" nr ");"
54.B const sensors_feature *
55.BI "sensors_get_features(const sensors_chip_name *" name ","
56.BI "                     int *" nr ");"
57.B const sensors_subfeature *
58.BI "sensors_get_all_subfeatures(const sensors_chip_name *" name ","
59.BI "                            const sensors_feature *" feature ","
60.BI "                            int *" nr ");"
61.B const sensors_subfeature *
62.BI "sensors_get_subfeature(const sensors_chip_name *" name ","
63.BI "                       const sensors_feature *" feature ","
64.BI "                       sensors_subfeature_type " type ");"
65
66/* Features access */
67.BI "char *sensors_get_label(const sensors_chip_name *" name ","
68.BI "                        const sensors_feature *" feature ");"
69.BI "int sensors_get_value(const sensors_chip_name *" name ", int " subfeat_nr ","
70.BI "                      double *" value ");"
71.BI "int sensors_set_value(const sensors_chip_name *" name ", int " subfeat_nr ","
72.BI "                      double " value ");"
73.BI "int sensors_do_chip_sets(const sensors_chip_name *" name ");"
74
75.B #include <sensors/error.h>
76
77/* Error decoding */
78.BI "const char *sensors_strerror(int " errnum ");"
79
80/* Error handlers */
81.BI "void (*sensors_parse_error) (const char *" err ", int " lineno ");"
82.BI "void (*sensors_parse_error_wfn) (const char *" err ","
83.BI "                                 const char *" filename ", int " lineno ");"
84.BI "void (*sensors_fatal_error) (const char *" proc ", const char *" err ");"
85.fi
86
87.SH DESCRIPTION
88.B sensors_init()
89loads the configuration file and the detected chips list. If this returns a
90value unequal to zero, you are in trouble; you can not assume anything will
91be initialized properly. If you want to reload the configuration file, call
92sensors_cleanup() below before calling sensors_init() again.
93
94If FILE is NULL, the default configuration files are used (see the FILES
95section below). Most applications will want to do that.
96
97.B sensors_cleanup()
98cleans everything up: you can't access anything after this, until the next sensors_init() call!
99
100.B libsensors_version
101is a string representing the version of libsensors.
102
103.B sensors_parse_chip_name()
104parses a chip name to the internal representation. Return 0 on success,
105<0 on error. Make sure to call sensors_free_chip_name() when you're done
106with the data.
107
108.B sensors_free_chip_name()
109frees the memory that may have been allocated for the internal
110representation of a chip name. You only have to call this for chip
111names which do not originate from libsensors itself (that is, chip
112names which were generated by sensors_parse_chip_name()).
113
114.B sensors_snprintf_chip_name()
115prints a chip name from its internal representation. Note that chip should
116not contain wildcard values! Return the number of characters printed on
117success (same as snprintf), <0 on error.
118
119.B sensors_get_adapter_name()
120returns the adapter name of a bus number, as used within the
121sensors_chip_name structure. If it could not be found, it returns NULL.
122
123.B sensors_get_detected_chips()
124returns all detected chips that match a given chip name,
125one by one. If no chip name is provided, all detected chips are returned.
126To start at the beginning of the list, use 0 for nr; NULL is returned if
127we are at the end of the list. Do not try to change these chip names, as
128they point to internal structures!
129
130.B sensors_get_features()
131returns all main features of a specific chip. nr is an internally
132used variable. Set it to zero to start at the begin of the list. If no
133more features are found NULL is returned.
134Do not try to change the returned structure; you will corrupt internal
135data structures.
136
137.B sensors_get_all_subfeatures()
138returns all subfeatures of a given main feature. nr is an internally
139used variable. Set it to zero to start at the begin of the list. If no
140more subfeatures are found NULL is returned.
141Do not try to change the returned structure; you will corrupt internal
142data structures.
143
144.B sensors_get_subfeature()
145returns the subfeature of the given type for a given main feature,
146if it exists, NULL otherwise.
147Do not try to change the returned structure; you will corrupt internal
148data structures.
149
150.B sensors_get_label()
151looks up the label which belongs to this chip. Note that chip should not
152contain wildcard values! The returned string is newly allocated (free it
153yourself). On failure, NULL is returned.
154If no label exists for this feature, its name is returned itself.
155
156.B sensors_get_value()
157Reads the value of a subfeature of a certain chip. Note that chip should not
158contain wildcard values! This function will return 0 on success, and <0 on
159failure.
160
161.B sensors_set_value()
162sets the value of a subfeature of a certain chip. Note that chip should not
163contain wildcard values! This function will return 0 on success, and <0 on
164failure.
165
166.B sensors_do_chip_sets()
167executes all set statements for this particular chip. The chip may contain
168wildcards!  This function will return 0 on success, and <0 on failure.
169
170.B sensors_strerror()
171returns a pointer to a string which describes the error.
172errnum may be negative (the corresponding positive error is returned).
173You may not modify the result!
174
175.B sensors_parse_error()
176and
177.B sensors_parse_error_wfn()
178are functions which are called when a parse error is detected. Give them
179new values, and your own functions are called instead of the default (which
180print to stderr). These functions may terminate the program, but they
181usually output an error and return. The first function is the original
182one, the second one was added later when support for multiple
183configuration files was added.
184The library code now only calls the second function. However, for
185backwards compatibility, if an application provides a custom handling
186function for the first function but not the second, then all parse
187errors will be reported using the first function (that is, the filename
188is never reported.)
189Note that filename can be NULL (if filename isn't known) and lineno
190can be 0 (if the error occurs before the actual parsing starts.)
191
192.B sensors_fatal_error()
193Is a function which is called when an immediately fatal error (like no
194memory left) is detected. Give it a new value, and your own function
195is called instead of the default (which prints to stderr and ends
196the program). Never let it return!
197
198.SH DATA STRUCTURES
199
200Structure \fBsensors_feature\fR contains information related to a given
201feature of a specific chip:
202
203\fBtypedef struct sensors_feature {
204.br
205        const char *name;
206.br
207        int number;
208.br
209        sensors_feature_type type;
210.br
211} sensors_feature;\fP
212
213There are other members not documented here, which are only meant for
214libsensors internal use.
215
216Structure \fBsensors_subfeature\fR contains information related to a given
217subfeature of a specific chip feature:
218
219\fBtypedef struct sensors_subfeature {
220.br
221        const char *name;
222.br
223        int number;
224.br
225        sensors_subfeature_type type;
226.br
227        int mapping;
228.br
229        unsigned int flags;
230.br
231} sensors_subfeature;\fP
232
233The flags field is a bitfield, its value is a combination of
234\fBSENSORS_MODE_R\fR (readable), \fBSENSORS_MODE_W\fR (writable) and
235\fBSENSORS_COMPUTE_MAPPING\fR (affected by the computation rules of the
236main feature).
237
238.SH FILES
239.I /etc/sensors3.conf
240.br
241.I /etc/sensors.conf
242.RS
243The system-wide
244.BR libsensors (3)
245configuration file. /etc/sensors3.conf is tried first, and if it doesn't exist,
246/etc/sensors.conf is used instead.
247.RE
248
249.I /etc/sensors.d
250.RS
251A directory where you can put additional libsensors configuration files.
252Files found in this directory will be processed in alphabetical order after
253the default configuration file. Files with names that start with a dot are
254ignored.
255.RE
256
257.SH SEE ALSO
258sensors.conf(5)
259
260.SH AUTHOR
261Frodo Looijaard and the lm_sensors group
262http://www.lm-sensors.org/
263
Note: See TracBrowser for help on using the browser.