Use on_ac_power Safely in Shell Checks

You will finish with a shell check that distinguishes mains power, battery power and an undetermined result. The examples use on_ac_power from powermgmt-base version 1.37ubuntu0.1, installed on this machine. Allow about ten minutes. You need a shell and a system on which the command is installed.

This is a read-only test. It does not switch power sources, suspend the computer, change charging settings or talk to a power-management daemon. No elevated privileges are normally required.

1. Confirm the command is installed

Find the executable before building it into a script:

$ command -v on_ac_power
/usr/sbin/on_ac_power

The command has no options. The installed manual page describes it as a test for abundant power, such as AC mains or a USB charger, rather than a test for a particular type of plug or adapter. If command -v prints nothing, stop and install the package through your normal distribution process. Do not copy a similarly named script into a system directory just to make this check pass.

Checkpoint: the path must resolve to an executable supplied by powermgmt-base. Verify the package record if you need to document the installation:

$ dpkg-query -W -f='${Package} ${Version}\n' powermgmt-base
powermgmt-base 1.37ubuntu0.1

2. Read the result interactively

Run the command on its own:

$ on_ac_power
$ status=$?
$ printf 'on_ac_power status: %s\n' "$status"
on_ac_power status: 0

The normal command is quiet. Its exit status is the result:

• 0 means the system is on mains or another power source the kernel treats as abundant.
• 1 means the system is not on mains power, normally battery power.
• 255 means the power status could not be determined.

The second command must follow on_ac_power immediately. Any command inserted between them changes $? and hides the result you meant to inspect.

3. Put the test in a script

Use the status directly instead of parsing output. This version preserves the distinction between battery power and an unknown answer:

if on_ac_power; then
    printf '%s\n' 'Running on mains or charger power'
else
    status=$?
    case "$status" in
        1)  printf '%s\n' 'Running on battery power' ;;
        255) printf '%s\n' 'Power source is unknown' >&2 ;;
        *)  printf 'on_ac_power failed with status %s\n' "$status" >&2; exit "$status" ;;
    esac
fi

This is a useful pattern for a script that should warn before starting an optional, power-hungry operation. It does not make a policy decision for you. Decide separately whether an unknown result should allow, warn or block the operation.

Do not write only if ! on_ac_power when status 1 and status 255 have different consequences. The negation changes the shell condition and makes it less obvious which original status you need to handle.

4. Handle machines with no power sensor

The most common surprise is status 255 on a desktop or server. The manual says that the vast majority of these systems have no power sensors, so they report unknown even though their power supply is normally fixed mains power. Status 255 is also false in the shell. That means this apparently simple test is unsafe when written as an unconditional gate:

if on_ac_power; then
    run_the_operation
else
    refuse_to_run
fi

On a sensorless server, that code refuses to run because unknown is treated as false. If your operational assumption is that an unknown result should count as mains power, say so explicitly:

on_ac_power
status=$?
case "$status" in
    0)   printf '%s\n' 'Mains or charger power detected' ;;
    1)   printf '%s\n' 'Battery power detected' >&2; exit 1 ;;
    255) printf '%s\n' 'Power unknown; continuing as configured' ;;
    *)   printf 'Unexpected power-check status %s\n' "$status" >&2; exit 2 ;;
esac

That interpretation is a local policy, not a claim that the machine has been measured. Record it in the script's documentation and choose the safer behaviour for work that could interrupt a laptop or consume its remaining charge.

5. Know what the command cannot tell you

on_ac_power reports only information known to the kernel. It does not query userspace services such as NUT, and it does not tell you the battery percentage, charging rate, adapter identity or remaining runtime. A successful status therefore answers one narrow question: the kernel sees abundant power.

It also does not prove that a battery is healthy or that an external charger is delivering the expected current. Use the relevant hardware or monitoring tool for those questions. Keep this command as a small pre-flight check rather than treating it as a complete power-management interface.