.TH BATSIGNAL 1 batsignal\-1.8.0
.SH NAME
batsignal \- battery monitor daemon
.SH SYNOPSIS
.B batsignal
.RB [ OPTIONS ]
.SH DESCRIPTION
batsignal is a lightweight battery daemon written in C that notifies the user about battery states.
It is intended for minimal window managers, but can be used in any environment that supports desktop notifications via libnotify.
.SH OPTIONS
.TP
.B \-h
Display help
.TP
.B \-v
Display version information
.TP
.B \-b
Run batsignal as background daemon
.TP
.B \-o
Check battery once and exit
.TP
.B \-i
Ignore missing battery errors
.TP
.B \-e
Cause notifications to expire
.TP
.B \-N
Disable desktop notifications
.TP
.B \-w LEVEL
Battery warning LEVEL (default 15). 0 disables this level
.TP
.B \-c LEVEL
Critical battery LEVEL (default 5). 0 disables this level
.TP
.B \-d LEVEL
Battery danger LEVEL (default 2). 0 disables this level
.TP
.B \-f LEVEL
Battery full LEVEL (default 0). 0 disables this level
.TP
.B \-p
Show a message when the battery begins charging or discharging
.TP
.B \-W MESSAGE
Show MESSAGE when battery is at warning level
.TP
.B \-C MESSAGE
Show MESSAGE when battery is at critical level
.TP
.B \-D COMMAND
Run COMMAND when battery is at danger level
.TP
.B \-F MESSAGE
Show MESSAGE when battery is at full level
.TP
.B \-P MESSAGE
Show MESSAGE when battery is charging, if -p option is set
.TP
.B \-U MESSAGE
Show MESSAGE when battery is discharging, if -p option is set
.TP
.B \-M COMMAND
Send each message using COMMAND
.TP
.B \-n NAME
Battery device NAME - multiple batteries may be separated by commas (default BAT0)
.TP
.B \-m SECONDS
Minimum number of SECONDS (default 60) to wait between battery checks.
Settings SECONDS to 0 disables polling and waits for the USR1 signal before checking battery level.
Prefixing SECONDS with a + (ex: -m +10) will force a check at SECONDS intervals, regardless of battery level.
.TP
.B \-a APP_NAME
App name used in notifications (default: batsignal)
.TP
.B \-I ICON
Display specified ICON in notifications
.SH CONFIGURATION
Options can be passed to batsignal as command arguments or placed in a configuration file.
Options from the configuration file will be applied first and then may be overridden by command line as arguments.
.P
The configuration file should include option arguments as documented above, one argument per line.
Lines beginning with # and empty lines are ignored.
For example, to specify a warning level of 30 and run as a background daemon, the following configuration file could be used:
.RS
.P
# Run in background
.br
-b
.br
# Use warning level of 30
.br
-w
.br
30
.RE
.P
The following paths are checked in sequence for a configuration file:
.IP \[bu]
.B BATSIGNAL_CONFIG
environment variable (if present)
.IP \[bu]
$HOME/.config/batsignal (or the config base specificed in XDG_CONFIG_HOME)
.IP \[bu]
$HOME/.batsignal
.IP \[bu]
/usr/local/etc/batsignal
.IP \[bu]
/etc/batsignal
.SH ENVIRONMENT
.TP
.B BATSIGNAL_CONFIG
Sets the option configuration file path.
.TP
.B XDG_CONFIG_HOME
The base path for the XDG config directory. Used in the option file search.
.SH SIGNALS
batsignal responds to the following signals:
.TP
.B SIGUSR1
Sending the process SIGUSR1 will cause an immediate battery check to be performed.
.SH NOTES
In most cases, batsignal will perform fewer battery state checks while the battery is discharging and the level of charge is not near a warning level.
This frequency is affected by the multiplier (-m) option and is never less than <multiplier> seconds.
If the "full" level (-f) is set or charge/discharge messages are enabled (-p), batsignal will instead check the battery state every <multiplier> seconds regardless of level of charge.
.P
If the "full" level (-f) is set, the battery full notification will be triggered at the given level of charge or when the battery status changes to full, whichever occurs first.
.P
The message COMMAND passed with -M is a C printf-style format string.
It can use two string placeholders (%s) that will be replaced by the message text and the current battery level.
Be sure to test the command - invalid format strings may cause batsignal to crash.
.br
Ex: -M "wall 'Battery warning: %s - Level is %s'"
.SH COPYRIGHT
Copyright 2018-2024 Corey Hinshaw
.br
Copyright 2016-2017 Aaron Marcher
.br
License: ISC License