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 adapater
       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 informa-
       tion.

       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 doc-
       umentation 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								libacpi(3)