libacpi(3) | Library Functions Manual | libacpi(3) |
NAME¶
libacpi - general purpose library for ACPISYNOPSIS¶
#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 structureglobal_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
Functions¶
int init_acpi_batt (global_t *globals)
Variables¶
battery_t batteries [MAX_ITEMS]
Enumerations¶
enum { ITEM_EXCEED = -5, DISABLED = -4, NOT_PRESENT = -3, ALLOC_ERR = -2, NOT_SUPPORTED = -1, SUCCESS }
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_countfan_t fans[MAX_ITEMS]¶
Array for existing fans, loop until globals->fan_countthermal_t thermals[MAX_ITEMS]¶
Array for existing thermal zones, loop until globals->thermal_countAdditional 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.htmlAuthor¶
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 |