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

Revision 5653, 7.7 KB (checked in by khali, 6 years ago)

Document function sensors_snprintf_chip_name.

  • 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 GPL
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 "int sensors_snprintf_chip_name(char *" str ", size_t " size ","
46.BI "                               const sensors_chip_name *" chip ");"
47.BI "const char *sensors_get_adapter_name(const sensors_bus_id *" bus ");"
48
49/* Chips and features enumeration */
50.B const sensors_chip_name *
51.BI "sensors_get_detected_chips(const sensors_chip_name *" match ","
52.BI "                           int *" nr ");"
53.B const sensors_feature *
54.BI "sensors_get_features(const sensors_chip_name *" name ","
55.BI "                     int *" nr ");"
56.B const sensors_subfeature *
57.BI "sensors_get_all_subfeatures(const sensors_chip_name *" name ","
58.BI "                            const sensors_feature *" feature ","
59.BI "                            int *" nr ");"
60.B const sensors_subfeature *
61.BI "sensors_get_subfeature(const sensors_chip_name *" name ","
62.BI "                       const sensors_feature *" feature ","
63.BI "                       sensors_subfeature_type " type ");"
64
65/* Features access */
66.BI "char *sensors_get_label(const sensors_chip_name *" name ","
67.BI "                        const sensors_feature *" feature ");"
68.BI "int sensors_get_value(const sensors_chip_name *" name ", int " subfeat_nr ","
69.BI "                      double *" value ");"
70.BI "int sensors_set_value(const sensors_chip_name *" name ", int " subfeat_nr ","
71.BI "                      double " value ");"
72.BI "int sensors_do_chip_sets(const sensors_chip_name *" name ");"
73.fi
74
75.SH DESCRIPTION
76.B sensors_init()
77loads the configuration file and the detected chips list. If this returns a
78value unequal to zero, you are in trouble; you can not assume anything will
79be initialized properly. If you want to reload the configuration file, call
80sensors_cleanup() below before calling sensors_init() again.
81
82If FILE is NULL, the default configuration files are used (see the FILES
83section below). Most applications will want to do that.
84
85.B sensors_cleanup()
86cleans everything up: you can't access anything after this, until the next sensors_init() call!
87
88.B libsensors_version
89is a string representing the version of libsensors.
90
91.B sensors_parse_chip_name()
92parses a chip name to the internal representation. Return 0 on success,
93<0 on error.
94
95.B sensors_snprintf_chip_name()
96prints a chip name from its internal representation. Note that chip should
97not contain wildcard values! Return the number of characters printed on
98success (same as snprintf), <0 on error.
99
100.B sensors_get_adapter_name()
101returns the adapter name of a bus number, as used within the
102sensors_chip_name structure. If it could not be found, it returns NULL.
103
104.B sensors_get_detected_chips()
105returns all detected chips that match a given chip name,
106one by one. If no chip name is provided, all detected chips are returned.
107To start at the beginning of the list, use 0 for nr; NULL is returned if
108we are at the end of the list. Do not try to change these chip names, as
109they point to internal structures!
110
111.B sensors_get_features()
112returns all main features of a specific chip. nr is an internally
113used variable. Set it to zero to start at the begin of the list. If no
114more features are found NULL is returned.
115Do not try to change the returned structure; you will corrupt internal
116data structures.
117
118.B sensors_get_all_subfeatures()
119returns all subfeatures of a given main feature. nr is an internally
120used variable. Set it to zero to start at the begin of the list. If no
121more subfeatures are found NULL is returned.
122Do not try to change the returned structure; you will corrupt internal
123data structures.
124
125.B sensors_get_subfeature()
126returns the subfeature of the given type for a given main feature,
127if it exists, NULL otherwise.
128Do not try to change the returned structure; you will corrupt internal
129data structures.
130
131.B sensors_get_label()
132looks up the label which belongs to this chip. Note that chip should not
133contain wildcard values! The returned string is newly allocated (free it
134yourself). On failure, NULL is returned.
135If no label exists for this feature, its name is returned itself.
136
137.B sensors_get_value()
138Reads the value of a subfeature of a certain chip. Note that chip should not
139contain wildcard values! This function will return 0 on success, and <0 on
140failure.
141
142.B sensors_set_value()
143sets the value of a subfeature of a certain chip. Note that chip should not
144contain wildcard values! This function will return 0 on success, and <0 on
145failure.
146
147.B sensors_do_chip_sets()
148executes all set statements for this particular chip. The chip may contain
149wildcards!  This function will return 0 on success, and <0 on failure.
150
151.SH DATA STRUCTURES
152
153Structure \fBsensors_feature\fR contains information related to a given
154feature of a specific chip:
155
156\fBtypedef struct sensors_feature {
157.br
158        const char *name;
159.br
160        int number;
161.br
162        sensors_feature_type type;
163.br
164} sensors_feature;\fP
165
166There are other members not documented here, which are only meant for
167libsensors internal use.
168
169Structure \fBsensors_subfeature\fR contains information related to a given
170subfeature of a specific chip feature:
171
172\fBtypedef struct sensors_subfeature {
173.br
174        const char *name;
175.br
176        int number;
177.br
178        sensors_subfeature_type type;
179.br
180        int mapping;
181.br
182        unsigned int flags;
183.br
184} sensors_subfeature;\fP
185
186The flags field is a bitfield, its value is a combination of
187\fBSENSORS_MODE_R\fR (readable), \fBSENSORS_MODE_W\fR (writable) and
188\fBSENSORS_COMPUTE_MAPPING\fR (affected by the computation rules of the
189main feature).
190
191.SH FILES
192.I /etc/sensors3.conf
193.br
194.I /etc/sensors.conf
195.RS
196The system-wide
197.BR libsensors (3)
198configuration file. /etc/sensors3.conf is tried first, and if it doesn't exist,
199/etc/sensors.conf is used instead.
200.RE
201
202.I /etc/sensors.d
203.RS
204A directory where you can put additional libsensors configuration files.
205Files found in this directory will be processed in alphabetical order after
206the default configuration file. Files with names that start with a dot are
207ignored.
208.RE
209
210.SH SEE ALSO
211sensors.conf(5)
212
213.SH AUTHOR
214Frodo Looijaard and the lm_sensors group
215http://www.lm-sensors.org/
216
Note: See TracBrowser for help on using the browser.