Scroll to navigation

libacpi(3) Library Functions Manual libacpi(3)

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:

maximum item count reached
features is disabled
something is not present
an error occurred while allocating space
a feature is not supported
everything was fine

enum batt_state_t

Enumerator:

remaining battery life is high
remaining battery life is medium
remaining battery life is low
remaining battery life is critical
remaining battery life is hard critical, you have a few minutes to charge
some error occurred while reading the battery state

enum charge_state_t

Enumerator:

battery is currently charging
battery is currently discharging
battery is charged
hardware doesn't give information about the state
some error occurred while reading the charge state

enum fan_state_t

fan states

Enumerator:

fan is on
fan is off
some error occurred with this fan

enum power_state_t

Enumerator:

if computer runs on AC
if computer runs on battery
no information can be found

enum thermal_mode_t

Enumerator:

fans will be turned after the temperature passes a critical point
devices will be put in a lower power state after a critical point
system goes into suspend to disk if possible after a critical temperature
some error occurred while reading the cooling mode

enum thermal_state_t

Enumerator:

zone reports critical temperature, will cause system to go to S4
zone reports high temperature, will cause system to shutdown immediately
zone is on passive cooling
zone is on active cooling, more power consumption
zone is ok
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. :)

LIBACPI