libacpi(3)

📦 version 0.2, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 libacpi(3) 💖

okay bestie, welcome to libacpi — it's a Library Functions Manual situation and it is the general purpose library for ACPI. she's iconic, she's tiny, she's literally gonna tell you your battery percentage. let's get into it 🦋

✨ NAME ✨

libacpi — general purpose library for ACPI. that's it, that's the girl.

🌸 SYNOPSIS 🌸

#include <libacpi.h>

🎀 DESCRIPTION 🎀

so the libacpi library routines give you a way to read ACPI values in a comfortable way. comfortable!! like a lil weighted blanket for your sysfs. that includes:

battery information
fan states
thermal zones
AC states

a program using these routines must be linked with the -lacpi option. don't forget it, she will not link herself 💅

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. vibe check complete ✨

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. lowkey essential, ngl.

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. grab a snack, we're going deep 🫶

Definition in file libacpi.h.

👑 Function Documentation 👑

`int check_acpi_support (void)`

checks if the system does support ACPI or not. the ultimate "do you even go here" moment.

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. (yes the original says "globa", she's quirky like that, we keep it 💀)

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. are you charging or are you free? 🔌

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

bestie if you see B_HARD_CRIT go find a charger. like now. 🪫😭

`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. iykyk 📚✨

🌐 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. :) — yes that's a direct quote and yes he's literally asking for a second battery, respect the hustle 💖

that's the whole page bestie, go read your battery like a main character 👑

LIBACPI · libacpi(3) — mwah, no notes, periodt 💅✨

📦 where this page comes from

debian bookworm: libacpi-dev 0.2-7 · MIT
debian trixie: libacpi-dev 0.2-7 · MIT
ubuntu jammy: libacpi-dev 0.2-7 · MIT
ubuntu noble: libacpi-dev 0.2-7build1 · MIT
ubuntu questing: libacpi-dev 0.2-7build1
ubuntu resolute: libacpi-dev 0.2-7build2 · MIT
ubuntu stonking: libacpi-dev 0.2-7build2 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms