Man page - libacpi(3)

Packages contains this manual

Manual

libacpi

NAME
SYNOPSIS
DESCRIPTION
Structures
Functions
Variables
Enumerations
Detailed Description
Function Documentation
int check_acpi_support (void)
int init_acpi_acadapt (global_t * globals)
int init_acpi_batt (global_t * globals)
int init_acpi_fan (global_t * globals)
int init_acpi_thermal (global_t * globals)
void read_acpi_acstate (global_t * globals)
int read_acpi_batt (const int num)
int read_acpi_fan (const int num)
int read_acpi_zone (const int num, global_t * globals)
Enumeration Type Documentation
possible function return values
enum batt_state_t
enum charge_state_t
enum fan_state_t
enum power_state_t
enum thermal_mode_t
enum thermal_state_t
Variable Documentation
battery_t batteries[MAX_ITEMS]
fan_t fans[MAX_ITEMS]
thermal_t thermals[MAX_ITEMS]
Additional information
Homepage
Author

NAME

libacpi - general purpose library for ACPI

SYNOPSIS

#include <libacpi.h>

DESCRIPTION

The libacpi library routines provide its users a method of reading ACPI values in a comfortable way. This includes battery information, fan states, thermal zones and AC states.

A program using these routines must be linked with -lacpi option.

To initialize this functionality you have to first allocate space for a global_t structure

global_t *global = malloc (sizeof (global_t));

Now use the check_acpi_support() function to check if the system actually supports ACPI. In case it does the function will return SUCCESS or NOT_SUPPORTED on failure.

Now you can use the following functions to initialize the values you get from the ACPI interface:

init_acpi_batt(global);
init_acpi_acadapt(global);
init_acpi_fan(global);
init_acpi_thermal(global);

To know if some of the features is not supported it is a good idea to store the return values in some variable.

If you want to read non-static values the ACPI interface provides (for example battery percentage), use the following functions to do this:

read_acpi_batt(int num)
read_acpi_zone(int num, global_t *globals);
read_acpi_fan(int num)
read_acpi_acstate(global_t *globals);

Since you can have more than one battery, fan and thermal zone, num is the number you want to read, for example in a loop.

thermal_t *tp;
....
for(i=0; i<global->thermal_count; i++){
read_acpi_zone(i, global);
tp = &thermals[i];
...
}

Structures

struct fan_t
fan data
struct battery_t
information found about battery
struct thermal_t
information about thermal zone
struct adapter_t
information about ac adapter
struct global_t
global acpi structure

Functions

int init_acpi_batt ( global_t *globals)
int init_acpi_acadapt ( global_t *globals)
int init_acpi_thermal ( global_t *globals)
int init_acpi_fan ( global_t *globals)
int check_acpi_support (void)
int read_acpi_batt (const int num)
void read_acpi_acstate ( global_t *globals)
int read_acpi_zone (const int num, global_t *globals)
int read_acpi_fan (const int num)

Variables

battery_t batteries [MAX_ITEMS]
thermal_t thermals [MAX_ITEMS]
fan_t fans [MAX_ITEMS]

Enumerations

enum { ITEM_EXCEED = -5, DISABLED = -4, NOT_PRESENT = -3, ALLOC_ERR = -2, NOT_SUPPORTED = -1, SUCCESS }
enum power_state_t { P_AC , P_BATT , P_ERR }
enum thermal_state_t { T_CRIT , T_HOT , T_PASS , T_ACT , T_OK , T_ERR }
enum charge_state_t { C_CHARGE , C_DISCHARGE , C_CHARGED , C_NOINFO , C_ERR }
enum batt_state_t { B_HIGH , B_MED , B_LOW , B_CRIT , B_HARD_CRIT , B_ERR }
enum thermal_mode_t { CO_ACT , CO_PASS , CO_CRIT , CO_ERR }
enum fan_state_t { F_ON , F_OFF , F_ERR }

Detailed Description

Now follows a more detailed description of functions, structures and enums.

Definition in file libacpi.h .

Function Documentation

int check_acpi_support (void)

Checks if the system does support ACPI or not.

Returns:

SUCCESS if the system supports ACPI or, NOT_SUPPORTED.

int init_acpi_acadapt (global_t * globals)

Finds existing ac adapter and fills the adapt (in globa struct) structure with the paths of the important files to parse.

Parameters:

globals pointer to global acpi structure

Returns:

SUCCESS if everything is ok, NOT_SUPPORTED if no information can be found, ALLOC_ERR on allocation errors.

int init_acpi_batt (global_t * globals)

Finds existing batteries and fills the corresponding batteries structures with the paths of the important files to parse.

Parameters:

globals pointer to global acpi structure

Returns:

SUCCESS if everything is ok, NOT_SUPPORTED if no information can be found, ALLOC_ERR on allocation errors and ITEM_EXCEED if there are more batteries found than MAX_ITEMS, this should never happen.

int init_acpi_fan (global_t * globals)

Finds existing fans and fills corresponding fan structures with the paths of the important files to parse for fan information.

Parameters:

globals pointer to global acpi structure

Returns:

SUCCESS if everything is ok, NOT_SUPPORTED if no information can be found, ALLOC_ERR on allocation errors and ITEM_EXCEED if there are more fans found than MAX_ITEMS, this should never happen.

int init_acpi_thermal (global_t * globals)

Finds existing thermal zones and fills corresponding thermal structures with the paths of the important files to parse for thermal information.

Parameters:

globals pointer to global acpi structure

Returns:

SUCCESS if everything is ok, NOT_SUPPORTED if no information can be found, ALLOC_ERR on allocation errors and ITEM_EXCEED if there are more thermal zones found than MAX_ITEMS, this should never happen.

void read_acpi_acstate (global_t * globals)

Looks up if the ac adapter is plugged in or not and sets the values in a struct

Parameters:

globals pointer to the global acpi structure

Referenced by init_acpi_acadapt().

int read_acpi_batt (const int num)

Gathers all information of a given battery and filling a struct with it.

Parameters:

num number of battery

Returns:

SUCCESS if everything is ok or ITEM_EXCEED if there is not battery num.

int read_acpi_fan (const int num)

Gathers all information about given fan and sets the corresponding values in a struct.

Parameters:

num number for the fan to read

Returns:

SUCCESS if everything is ok, ITEM_EXCEED if there is not fan num or NOT_SUPPORTED if the values can’t be read. This should not happen if the init function returned SUCCESS if the ACPI implementation.

int read_acpi_zone (const int num, global_t * globals)

Gathers all information of a given thermal zone and sets the corresponding values in a struct.

Parameters:

num zone
globals pointer to global acpi struct, needed if there is just one zone

Returns:

SUCCESS if everything is ok, ITEM_EXCEED if there is not thermal zone num or NOT_SUPPORTED if the values can’t be read. This should not happen if the init function returned SUCCESS if the ACPI implementation.

Enumeration Type Documentation

possible function return values

Enumerator:
ITEM_EXCEED

maximum item count reached

DISABLED

features is disabled

NOT_PRESENT

something is not present

ALLOC_ERR

an error occurred while allocating space

NOT_SUPPORTED

a feature is not supported

SUCCESS

everything was fine

enum batt_state_t

Enumerator:

B_HIGH

remaining battery life is high

B_MED

remaining battery life is medium

B_LOW

remaining battery life is low

B_CRIT

remaining battery life is critical

B_HARD_CRIT

remaining battery life is hard critical, you have a few minutes to charge

B_ERR

some error occurred while reading the battery state

enum charge_state_t

Enumerator:
C_CHARGE

battery is currently charging

C_DISCHARGE

battery is currently discharging

C_CHARGED

battery is charged

C_NOINFO

hardware doesn’t give information about the state

C_ERR

some error occurred while reading the charge state

enum fan_state_t

fan states

Enumerator:

F_ON

fan is on

F_OFF

fan is off

F_ERR

some error occurred with this fan

enum power_state_t

Enumerator:

P_AC

if computer runs on AC

P_BATT

if computer runs on battery

P_ERR

no information can be found

enum thermal_mode_t

Enumerator:

CO_ACT

fans will be turned after the temperature passes a critical point

CO_PASS

devices will be put in a lower power state after a critical point

CO_CRIT

system goes into suspend to disk if possible after a critical temperature

CO_ERR

some error occurred while reading the cooling mode

enum thermal_state_t

Enumerator:

T_CRIT

zone reports critical temperature, will cause system to go to S4

T_HOT

zone reports high temperature, will cause system to shutdown immediately

T_PASS

zone is on passive cooling

T_ACT

zone is on active cooling, more power consumption

T_OK

zone is ok

T_ERR

some error occurred while reading the state of the zone

Variable Documentation

battery_t batteries[MAX_ITEMS]

Array for existing batteries, loop until globals->battery_count

fan_t fans[MAX_ITEMS]

Array for existing fans, loop until globals->fan_count

thermal_t thermals[MAX_ITEMS]

Array for existing thermal zones, loop until globals->thermal_count

Additional information

The package ships a test-libacpi.c file which should be pretty self explanatory. Also have a look into libacpi.h file and the doxygen documentation in the doc/ directory.

Homepage

See http://www.ngolde.de/libacpi.html

Author

Write to nico (at) ngolde (dot) de for suggestions, hardware donations (very welcome, my notebook doesn’t support all features and I could need a second battery), questions, fixes, bug reports, thanks, etc. :)