1libacpi(3) Library Functions Manual libacpi(3)
2
6 libacpi - general purpose library for ACPI
7
9 #include <libacpi.h>
10
12 The libacpi library routines provide its users a method of reading ACPI
13 values in a comfortable way. This includes battery information, fan
14 states, thermal zones and AC states.
15 A program using these routines must be linked with -lacpi option.
17 To initialize this functionality you have to first allocate space for a
19 global_t structure
20 global_t *global = malloc (sizeof (global_t));
22 Now use the check_acpi_support() function to check if the system actu‐
25 ally supports ACPI. In case it does the function will return SUCCESS
26 or NOT_SUPPORTED on failure.
27 Now you can use the following functions to initialize the values you
29 get from the ACPI interface:
30 init_acpi_batt(global);
32 init_acpi_acadapt(global);
33 init_acpi_fan(global);
34 init_acpi_thermal(global);
35 To know if some of the features is not supported it is a good idea to
37 store the return values in some variable.
38 If you want to read non-static values the ACPI interface provides (for
40 example battery percentage), use the following functions to do this:
41 read_acpi_batt(int num)
43 read_acpi_zone(int num, global_t *globals);
44 read_acpi_fan(int num)
45 read_acpi_acstate(global_t *globals);
46 Since you can have more than one battery, fan and thermal zone, num is
48 the number you want to read, for example in a loop.
49 thermal_t *tp;
51 ....
52 for(i=0; i<global->thermal_count; i++){
53 read_acpi_zone(i, global);
54 tp = &thermals[i];
55 ...
56 }
57 Structures
59 struct fan_t
60 fan data
61 struct battery_t
62 information found about battery
63 struct thermal_t
64 information about thermal zone
65 struct adapter_t
66 information about ac adapater
67 struct global_t
68 global acpi structure
69 Functions
71 int init_acpi_batt (global_t *globals)
72 int init_acpi_acadapt (global_t *globals)
73 int init_acpi_thermal (global_t *globals)
74 int init_acpi_fan (global_t *globals)
75 int check_acpi_support (void)
76 int read_acpi_batt (const int num)
77 void read_acpi_acstate (global_t *globals)
78 int read_acpi_zone (const int num, global_t *globals)
79 int read_acpi_fan (const int num)
80 Variables
82 battery_t batteries [MAX_ITEMS]
83 thermal_t thermals [MAX_ITEMS]
84 fan_t fans [MAX_ITEMS]
85 Enumerations
87 enum { ITEM_EXCEED = -5, DISABLED = -4, NOT_PRESENT = -3, ALLOC_ERR
88 = -2, NOT_SUPPORTED = -1, SUCCESS }
89 enum power_state_t { P_AC, P_BATT, P_ERR }
90 enum thermal_state_t { T_CRIT, T_HOT, T_PASS, T_ACT, T_OK, T_ERR }
91 enum charge_state_t { C_CHARGE, C_DISCHARGE, C_CHARGED, C_NOINFO, C_ERR
92 }
93 enum batt_state_t { B_HIGH, B_MED, B_LOW, B_CRIT, B_HARD_CRIT, B_ERR }
94 enum thermal_mode_t { CO_ACT, CO_PASS, CO_CRIT, CO_ERR }
95 enum fan_state_t { F_ON, F_OFF, F_ERR }
96
98 Now follows a more detailed description of functions, structures and
99 enums.
100 Definition in file libacpi.h.
102
104 int check_acpi_support (void)
105 Checks if the system does support ACPI or not.
106 Returns:
108 SUCCESS if the system supports ACPI or, NOT_SUPPORTED.
109 int init_acpi_acadapt (global_t * globals)
111 Finds existing ac adapter and fills the adapt (in globa struct) struc‐
112 ture with the paths of the important files to parse.
113 Parameters:
115 globals pointer to global acpi structure
116 Returns: SUCCESS if everything is ok, NOT_SUPPORTED if no informa‐
118 tion can be found, ALLOC_ERR on allocation errors.
119 int init_acpi_batt (global_t * globals)
121 Finds existing batteries and fills the corresponding batteries struc‐
122 tures with the paths of the important files to parse.
123 Parameters:
125 globals pointer to global acpi structure
126 Returns: SUCCESS if everything is ok, NOT_SUPPORTED if no informa‐
128 tion can be found, ALLOC_ERR on allocation errors and ITEM_EXCEED
129 if there are more batteries found than MAX_ITEMS, this should never
130 happen.
131 int init_acpi_fan (global_t * globals)
133 Finds existing fans and fills corresponding fan structures with the
134 paths of the important files to parse for fan information.
135 Parameters:
137 globals pointer to global acpi structure
138 Returns: SUCCESS if everything is ok, NOT_SUPPORTED if no informa‐
140 tion can be found, ALLOC_ERR on allocation errors and ITEM_EXCEED
141 if there are more fans found than MAX_ITEMS, this should never hap‐
142 pen.
143 int init_acpi_thermal (global_t * globals)
145 Finds existing thermal zones and fills corresponding thermal structures
146 with the paths of the important files to parse for thermal information.
147 Parameters:
149 globals pointer to global acpi structure
150 Returns: SUCCESS if everything is ok, NOT_SUPPORTED if no informa‐
152 tion can be found, ALLOC_ERR on allocation errors and ITEM_EXCEED
153 if there are more thermal zones found than MAX_ITEMS, this should
154 never happen.
155 void read_acpi_acstate (global_t * globals)
157 Looks up if the ac adapter is plugged in or not and sets the values in
158 a struct
159 Parameters:
161 globals pointer to the global acpi structure
162 Referenced by init_acpi_acadapt().
164 int read_acpi_batt (const int num)
166 Gathers all information of a given battery and filling a struct with
167 it.
168 Parameters:
170 num number of battery
171 Returns: SUCCESS if everything is ok or ITEM_EXCEED if there is not
173 battery num.
174 int read_acpi_fan (const int num)
176 Gathers all information about given fan and sets the corresponding val‐
177 ues in a struct.
178 Parameters:
180 num number for the fan to read
181 Returns: SUCCESS if everything is ok, ITEM_EXCEED if there is not
183 fan num or NOT_SUPPORTED if the values can't be read. This should
184 not happen if the init function returned SUCCESS if the ACPI imple‐
185 mentation.
186 int read_acpi_zone (const int num, global_t * globals)
188 Gathers all information of a given thermal zone and sets the corre‐
189 sponding values in a struct.
190 Parameters:
192 num zone
193 globals pointer to global acpi struct, needed if there is just one
194 zone
195 Returns: SUCCESS if everything is ok, ITEM_EXCEED if there is not
197 thermal zone num or NOT_SUPPORTED if the values can't be read. This
198 should not happen if the init function returned SUCCESS if the ACPI
199 implementation.
200
203 possible function return values
204 Enumerator:
205 ITEM_EXCEED
207 maximum item count reached
208 DISABLED
210 features is disabled
211 NOT_PRESENT
213 something is not present
214 ALLOC_ERR
216 an error occurred while allocating space
217 NOT_SUPPORTED
219 a feature is not supported
220 SUCCESS
222 everything was fine
223 enum batt_state_t
225 Enumerator:
226 B_HIGH remaining battery life is high
228 B_MED remaining battery life is medium
230 B_LOW remaining battery life is low
232 B_CRIT remaining battery life is critical
234 B_HARD_CRIT
236 remaining battery life is hard critical, you have a few minutes
237 to charge
238 B_ERR some error occurred while reading the battery state
240 enum charge_state_t
242 Enumerator:
243 C_CHARGE
245 battery is currently charging
246 C_DISCHARGE
248 battery is currently discharging
249 C_CHARGED
251 battery is charged
252 C_NOINFO
254 hardware doesn't give information about the state
255 C_ERR some error occurred while reading the charge state
257 enum fan_state_t
259 fan states
260 Enumerator:
262 F_ON fan is on
264 F_OFF fan is off
266 F_ERR some error occurred with this fan
268 enum power_state_t
270 Enumerator:
271 P_AC if computer runs on AC
273 P_BATT if computer runs on battery
275 P_ERR no information can be found
277 enum thermal_mode_t
279 Enumerator:
280 CO_ACT fans will be turned after the temperature passes a critical
282 point
283 CO_PASS
285 devices will be put in a lower power state after a critical
286 point
287 CO_CRIT
289 system goes into suspend to disk if possible after a critical
290 temperature
291 CO_ERR some error occurred while reading the cooling mode
293 enum thermal_state_t
295 Enumerator:
296 T_CRIT zone reports critical temperature, will cause system to go to S4
298 T_HOT zone reports high temperature, will cause system to shutdown
300 immediately
301 T_PASS zone is on passive cooling
303 T_ACT zone is on active cooling, more power consumption
305 T_OK zone is ok
307 T_ERR some error occurred while reading the state of the zone
309
311 battery_t batteries[MAX_ITEMS]
312 Array for existing batteries, loop until globals->battery_count
313 fan_t fans[MAX_ITEMS]
315 Array for existing fans, loop until globals->fan_count
316 thermal_t thermals[MAX_ITEMS]
318 Array for existing thermal zones, loop until globals->thermal_count
319
321 The package ships a test-libacpi.c file which should be pretty self
322 explanatory. Also have a look into libacpi.h file and the doxygen doc‐
323 umentation in the doc/ directory.
324
326 See http://www.ngolde.de/libacpi.html
327
329 Write to nico (at) ngolde (dot) de for suggestions, hardware donations
330 (very welcome, my notebook doesn't support all features and I could
331 need a second battery), questions, fixes, bug reports, thanks, etc. :)
332 LIBACPI libacpi(3)