---
name: "libacpi"
section: "3"
platform: "linux"
package: "libacpi-dev"
version: "0.2-7"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/libacpi"
---

# libacpi(3)

general purpose library for ACPI

## 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. :)*