.\" Copyright (C) 1998, 1999  Adrian Baugh <adrian.baugh@keble.ox.ac.uk>

.\" Copyright (C) 2007, 2009, 2013  Jean Delvare <jdelvare@suse.de>

.\" based on sensors.h, part of libsensors by Frodo Looijaard

.\" libsensors is distributed under the LGPL

.\"

.\" Permission is granted to make and distribute verbatim copies of this

.\" manual provided the copyright notice and this permission notice are

.\" preserved on all copies.

.\"

.\" Permission is granted to copy and distribute modified versions of this

.\" manual under the conditions for verbatim copying, provided that the

.\" entire resulting derived work is distributed under the terms of a

.\" permission notice identical to this one

.\" 

.\" Since the Linux kernel and libraries are constantly changing, this

.\" manual page may be incorrect or out-of-date.  The author(s) assume no

.\" responsibility for errors or omissions, or for damages resulting from

.\" the use of the information contained herein.  The author(s) may not

.\" have taken the same level of care in the production of this manual,

.\" which is licensed free of charge, as they might when working

.\" professionally.

.\" 

.\" Formatted or processed versions of this manual, if unaccompanied by

.\" the source, must acknowledge the copyright and authors of this work.

.\"

.\" References consulted:

.\"     libsensors source code

.TH libsensors 3  "September 2013" "lm-sensors 3" "Linux Programmer's Manual"

.SH NAME

libsensors \- publicly accessible functions provided by the sensors library

.SH SYNOPSIS

.nf

.B #include <sensors/sensors.h>

/* Library initialization and clean-up */

.BI "int sensors_init(FILE *" input ");"

.B void sensors_cleanup(void);

.BI "const char *" libsensors_version ";"

/* Chip name handling */

.BI "int sensors_parse_chip_name(const char *" orig_name ","

.BI "                            sensors_chip_name *" res ");"

.BI "void sensors_free_chip_name(sensors_chip_name *" chip ");"

.BI "int sensors_snprintf_chip_name(char *" str ", size_t " size ","

.BI "                               const sensors_chip_name *" chip ");"

.BI "const char *sensors_get_adapter_name(const sensors_bus_id *" bus ");"

/* Chips and features enumeration */

.B const sensors_chip_name *

.BI "sensors_get_detected_chips(const sensors_chip_name *" match ","

.BI "                           int *" nr ");"

.B const sensors_feature *

.BI "sensors_get_features(const sensors_chip_name *" name ","

.BI "                     int *" nr ");"

.B const sensors_subfeature *

.BI "sensors_get_all_subfeatures(const sensors_chip_name *" name ","

.BI "                            const sensors_feature *" feature ","

.BI "                            int *" nr ");"

.B const sensors_subfeature *

.BI "sensors_get_subfeature(const sensors_chip_name *" name ","

.BI "                       const sensors_feature *" feature ","

.BI "                       sensors_subfeature_type " type ");"

/* Features access */

.BI "char *sensors_get_label(const sensors_chip_name *" name ","

.BI "                        const sensors_feature *" feature ");"

.BI "int sensors_get_value(const sensors_chip_name *" name ", int " subfeat_nr ","

.BI "                      double *" value ");"

.BI "int sensors_set_value(const sensors_chip_name *" name ", int " subfeat_nr ","

.BI "                      double " value ");"

.BI "int sensors_do_chip_sets(const sensors_chip_name *" name ");"

.B #include <sensors/error.h>

/* Error decoding */

.BI "const char *sensors_strerror(int " errnum ");"

/* Error handlers */

.BI "void (*sensors_parse_error) (const char *" err ", int " lineno ");"

.BI "void (*sensors_parse_error_wfn) (const char *" err ","

.BI "                                 const char *" filename ", int " lineno ");"

.BI "void (*sensors_fatal_error) (const char *" proc ", const char *" err ");"

.fi

.SH DESCRIPTION

.B sensors_init()

loads the configuration file and the detected chips list. If this returns a

value unequal to zero, you are in trouble; you can not assume anything will

be initialized properly. If you want to reload the configuration file, or

load a different configuration file, call sensors_cleanup() below before

calling sensors_init() again. This means you can't load multiple configuration

files at once by calling sensors_init() multiple times.

The configuration file format is described in sensors.conf(5).

If FILE is NULL, the default configuration files are used (see the FILES

section below). Most applications will want to do that.

.B sensors_cleanup()

cleans everything up: you can't access anything after this, until the next sensors_init() call!

.B libsensors_version

is a string representing the version of libsensors.

.B sensors_parse_chip_name()

parses a chip name to the internal representation. Return 0 on success,

<0 on error. Make sure to call sensors_free_chip_name() when you're done

with the data.

.B sensors_free_chip_name()

frees the memory that may have been allocated for the internal

representation of a chip name. You only have to call this for chip

names which do not originate from libsensors itself (that is, chip

names which were generated by sensors_parse_chip_name()).

.B sensors_snprintf_chip_name()

prints a chip name from its internal representation. Note that chip should

not contain wildcard values! Return the number of characters printed on

success (same as snprintf), <0 on error.

.B sensors_get_adapter_name()

returns the adapter name of a bus type, number pair, as used within the

sensors_chip_name structure. If it could not be found, it returns NULL.

Adapters describe how a monitoring chip is hooked up to the system.

This is particularly relevant for I2C/SMBus sensor chips (bus type "i2c"),

which must be accessed over an I2C/SMBus controller. Each such controller

has a different number, assigned by the system at initialization time,

so that they can be referenced individually.

Super\-I/O or CPU\-embedded sensors, on the other hand, can be accessed

directly and technically don't use any adapter. They have only a bus type

but no bus number, and sensors_get_adapter_name() will return a generic

adapter name for them.

.B sensors_get_detected_chips()

returns all detected chips that match a given chip name,

one by one. If no chip name is provided, all detected chips are returned.

To start at the beginning of the list, use 0 for nr; NULL is returned if

we are at the end of the list. Do not try to change these chip names, as

they point to internal structures!

.B sensors_get_features()

returns all main features of a specific chip. nr is an internally

used variable. Set it to zero to start at the begin of the list. If no

more features are found NULL is returned.

Do not try to change the returned structure; you will corrupt internal

data structures.

.B sensors_get_all_subfeatures()

returns all subfeatures of a given main feature. nr is an internally

used variable. Set it to zero to start at the begin of the list. If no

more subfeatures are found NULL is returned.

Do not try to change the returned structure; you will corrupt internal

data structures.

.B sensors_get_subfeature()

returns the subfeature of the given type for a given main feature,

if it exists, NULL otherwise.

Do not try to change the returned structure; you will corrupt internal

data structures.

.B sensors_get_label()

looks up the label which belongs to this chip. Note that chip should not

contain wildcard values! The returned string is newly allocated (free it

yourself). On failure, NULL is returned.

If no label exists for this feature, its name is returned itself.

.B sensors_get_value()

Reads the value of a subfeature of a certain chip. Note that chip should not

contain wildcard values! This function will return 0 on success, and <0 on

failure.

.B sensors_set_value()

sets the value of a subfeature of a certain chip. Note that chip should not

contain wildcard values! This function will return 0 on success, and <0 on

failure.

.B sensors_do_chip_sets()

executes all set statements for this particular chip. The chip may contain

wildcards!  This function will return 0 on success, and <0 on failure.

.B sensors_strerror()

returns a pointer to a string which describes the error.

errnum may be negative (the corresponding positive error is returned).

You may not modify the result!

.B sensors_parse_error()

and

.B sensors_parse_error_wfn()

are functions which are called when a parse error is detected. Give them

new values, and your own functions are called instead of the default (which

print to stderr). These functions may terminate the program, but they

usually output an error and return. The first function is the original

one, the second one was added later when support for multiple

configuration files was added.

The library code now only calls the second function. However, for

backwards compatibility, if an application provides a custom handling

function for the first function but not the second, then all parse

errors will be reported using the first function (that is, the filename

is never reported.)

Note that filename can be NULL (if filename isn't known) and lineno

can be 0 (if the error occurs before the actual parsing starts.)

.B sensors_fatal_error()

Is a function which is called when an immediately fatal error (like no

memory left) is detected. Give it a new value, and your own function

is called instead of the default (which prints to stderr and ends

the program). Never let it return!

.SH DATA STRUCTURES

Structure \fBsensors_chip_name\fR contains information related to a

specific chip.

\fBtypedef struct sensors_chip_name {

.br

	sensors_bus_id bus;

.br

} sensors_chip_name;\fP

There are other members not documented here, which are only meant for

libsensors internal use.

Structure \fBsensors_feature\fR contains information related to a given

feature of a specific chip:

\fBtypedef struct sensors_feature {

.br

	const char *name;

.br

	int number;

.br

	sensors_feature_type type;

.br

} sensors_feature;\fP

There are other members not documented here, which are only meant for

libsensors internal use.

Structure \fBsensors_subfeature\fR contains information related to a given

subfeature of a specific chip feature:

\fBtypedef struct sensors_subfeature {

.br

	const char *name;

.br

	int number;

.br

	sensors_subfeature_type type;

.br

	int mapping;

.br

	unsigned int flags;

.br

} sensors_subfeature;\fP

The flags field is a bitfield, its value is a combination of

\fBSENSORS_MODE_R\fR (readable), \fBSENSORS_MODE_W\fR (writable) and

\fBSENSORS_COMPUTE_MAPPING\fR (affected by the computation rules of the

main feature).

.SH FILES

.I /etc/sensors3.conf

.br

.I /etc/sensors.conf

.RS

The system-wide

.BR libsensors (3)

configuration file. /etc/sensors3.conf is tried first, and if it doesn't exist,

/etc/sensors.conf is used instead.

.RE

.I /etc/sensors.d

.RS

A directory where you can put additional libsensors configuration files.

Files found in this directory will be processed in alphabetical order after

the default configuration file. Files with names that start with a dot are

ignored.

.RE

.SH SEE ALSO

sensors.conf(5)

.SH AUTHOR

Frodo Looijaard, Jean Delvare and others

http://www.lm-sensors.org/