pwrd(ADM)

pwrd -- Power Management event router and servicing daemon

Syntax

/etc/pwr/bin/pwrd [ -j ] [ -f pmspecial ] [ -a actionfile ] [ -c scriptfile ] [ -e
eventsfile ] ...

Description

The pwrd daemon routes and services Power Management (PM) events defined by the eventsfile(s) according to the rules listed in the actionfile. Typical PM events include:

warning that battery power is running low
suggestions to ``freeze'' the system by placing it in a state of suspended animation
notification that peripherals are (or are not) being used
commands in response to these and other events

Most systems cannot generate or use this information to conserve power unless they are equipped with an ``APM'' (Advanced Power Management) facility in the firmware BIOS. Therefore, the entire PM system including pwrd is usually only run on APM-equipped machines.

The options include:

-a actionfile: The file describing the actions to take on defined PM events. Only one -a option can be specified. If no -a option is specified, then the default is the file defined by ACTIONS in /etc/default/pwr, or /etc/pwr/sys/actions when no file is defined. The actionfile format is described in pwraction(F).
-c scriptfile: Bourne shell script(see sh(C)) which dispatches actionfile-defined commands upon receipt of an event. If no -c option is specified, the default script is the file defined by EXECUTE in /etc/default/pwr, or /etc/pwr/sys/pwrscript when no file is defined.
-e eventsfile: A file defining some PM events. As many -e options as necessary can be specified to define all relevant PM events. If no -e options are specified, then the default eventsfile(s) are those in the comma (,) separated list defined by EVENTS in /etc/default/pwr, or /etc/pwr/sys/events when no list is defined. The eventsfile format is described in pwrevents(F).
-f pmspecial: The pwr(HW) special file via which pwrd sends and receives PM events. The default is /dev/pwr/pm. Only one -f option can be specified.
-j: Do not detach and run in the background. Normally, pwrd creates a new session and runs in the background without any controlling terminal. The -j option suppresses this initialization.

pwrd reads PM events from the pmspecial file and from anonymous STREAMS pipes connected to previously-spawned children servicing defined actions. Some signals, typically sent by kill(C), are also interpreted as PM events.

When an event is received from any source it is routed according to the event's destination address(es):

Addresses which should be ignored are ignored.
If addressed to a specific process by its process ID (PID) and pwrd has a child with that PID, send the event through the associated connection unless the action was defined with the noforward attribute.
If addressed by the name of an action (label) that started a child process to which pwrd still has an open connection, send the event through each matching open connection unless the action was defined with the noforward attribute. The actual children need no longer exist.
If addressed by a name which does not match any action, and the event did not originally come from the pmspecial file, send the event through that file.
If addressed to a STREAMS module, device driver, or with an APM device ID and the event did not originally come from the pmspecial file, send the event through that file.
If addressed to ``any'' process (or specifically by PID to the pwrd daemon), start a copy of each matching action as described below. The event is not passed through any existing open connections to any children.

Events cannot be forwarded to addresses which do not match of any of the above conditions. pwrd prints a message and ignores such destination addresses.

To start matching actions, pwrd must determine the event's name. An event's name is determined by comparing its value against the eventsfile(s)-defined events. The event's name determines which actions in actionfile to execute. The actions are executed in the order listed in actionfile.

Some signals are treated as PM events addressed specifically to pwrd. These signal PM events include:

Signal Number Signal Name PM event Type Default action

1 SIGHUP signal/HUP conf nothing run

2 SIGINT signal/INT conf nothing run

3 SIGQUIT signal/QUIT conf nothing run

14 SIGALRM signal/ALRM req retry tasks which failed to start

15 SIGTERM signal/TERM sys first starts exit, second forces

16 SIGUSR1 signal/USR1 conf nothing run

17 SIGUSR2 signal/USR2 conf nothing run

18 SIGCHLD signal/CHLD req clean up completed service scripts

19 SIGPWR signal/PWR sys imminent power failure!

22 SIGPOLL signal/POLL req service new PM event

Signal Number	Signal Name	PM event	Type	Default action
1	SIGHUP	signal/HUP	conf	nothing run
2	SIGINT	signal/INT	conf	nothing run
3	SIGQUIT	signal/QUIT	conf	nothing run
14	SIGALRM	signal/ALRM	req	retry tasks which failed to start
15	SIGTERM	signal/TERM	sys	first starts exit, second forces
16	SIGUSR1	signal/USR1	conf	nothing run
17	SIGUSR2	signal/USR2	conf	nothing run
18	SIGCHLD	signal/CHLD	req	clean up completed service scripts
19	SIGPWR	signal/PWR	sys	imminent power failure!
22	SIGPOLL	signal/POLL	req	service new PM event

The conf(igurable) signal PM events are available for use by system administrators. The sys(tem) events are used by the operating system and may be modified with caution. The req(uired) events are used by pwrd itself and should not be modified.

Several other PM events are internally generated by pwrd, addressed to itself:

PM event Cause

pwrd/startup pwrd initialization (always the first PM event)

pwrd/terminate pwrd is shutting down

PM event	Cause
pwrd/startup	pwrd initialization (always the first PM event)
pwrd/terminate	pwrd is shutting down

pwrd/type events not defined in the eventsfile(s) are neither generated nor understood. The defined value of each signal/type events should be the corresponding signal number. The defined value of each pwrd/type event is arbitrary.

Exit values

Arbitrary exit(S) codes are possible by using the exit cmd defined in pwraction(F). When pwrd is trying to start up, the possible exit codes include:

1: An illegal argument was given; or there were errors in the pwraction or pwrevent file(s).
2: Missing, unknown, or extraneous arguments were given.
10: The pwr special file could not be opened for reading and writing.
11: The pwr special file is not behaving correctly.
15: An ioctl(S) of the pwr special file unexpectedly failed, which may mean uapm(HW) is not installed.
20: malloc(S) failed; pwrd could not allocate some memory, such as (but not limited to) that needed to store the defined actions.
21: An unexpected error occurred.
24: fork(S) failed; pwrd could not detach and run in the background.
30: A pwraction or pwrevents file could not be opened for reading.
35: /dev/null could not be opened.
42: /dev/spx could not be opened to create a STREAMS pipe.
50: There were error(s) in the pwraction or pwrevents file(s).
54: Another pwrd daemon is currently running.
55: An unexpected error occurred when testing for the presence of optional system features or registering as the PM daemon.
56: boot did not supply any information about this machine's BIOS-APM firmware. Either the machine has none, boot was configured not to supply the information, or uapm has been disabled.

pwrd attempts to report on all errors in the actionfile and eventsfile(s) before refusing to start.

Limitations

BIOS-APM firmware from different manufacturers varies considerably in both operation and efficacy. What may be a safe or useful sequence of commands on one machine may be ineffectual or worse on another.

pwrd should log its messages (including a date-time stamp) to a file or use either log(M) or syslogd(ADM).

There should be a standard procedure for PM-aware applications to ``attach'' to pwrd and receive (and generate) PM messages of interest to them (such as ``the system is about to freeze'' or ``Ok to freeze the system now since I have finished checkpointing myself''). Currently all PM-aware applications install their own action(s) in the actionfile.

Files