libacpi(3) Library Functions Manual libacpi(3)

libacpi - general purpose library for ACPI

#include <libacpi.h>

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];
...
}


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


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)


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


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 }

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

Definition in file libacpi.h.

Checks if the system does support ACPI or not.

Returns:

SUCCESS if the system supports ACPI or, NOT_SUPPORTED.

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.

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.

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.

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.

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().

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.

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.

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.

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

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

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.

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

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