pwraction(F)

Format

Description

The four fields are:

label

A unique string used for identification purposes only. The label cannot contain colons, spaces, or tabs.

pmevent[,pmevent . . .]

A comma-separated list of PM event names or extended regular expressions. The format of each pmevent is described below. At least one pmevent must be specified.

[attribute[,attribute . . .]]

A comma separated list of optional control information. The possible attributes and their format is described below. The list may be empty.

cmd[,arg . . .]

An optional cmd (with optional arguments) that will be executed when a PM event matches one or more of the listed pmevents. The possible cmds are listed below. Nothing is run unless a cmd is specified.

PM event processing

Each PM event is identified by two positive numbers; its class and its type. Each class number is assigned a unique name by a pwrevents file. This file also assigns a unique name to each type number in a named class.

Sending a PM event to the pwrd daemon causes the following steps to occur:

1. The PM event's numeric class value is converted into its unique defined name. If no class name is defined then this PM event is considered ``undefined'' and is called ``?''; an invented name defined with the undefined class' numeric value.

2. The event's type value is converted into its unique name defined within the event's class. If no type name is defined then this PM event is considered undefined and is called ``?''; an invented name defined with the undefined type's numeric value.

3. The pwraction file is searched for actions whose pmevents match the PM event, either by name (including ``?''), numeric value, or virtue of being previously matched. Each match is called a task.

4. Each task (matching action) is entered (enqueued) on the appropriate queue. There are two queues of tasks waiting to be run: the hipri queue and the normal queue. Tasks are added to the end of queue unless the first attribute is specified. Tasks are never added to a stopped (disabled) queue unless the always attribute is specified. See ``Matched PM event attributes'' for more details. Which queue is used is specified by the queue attribute. If the task cannot be enqueued, an error is logged.

5. After all tasks have been enqueued, every task (from first on the queue to last) in the hipri queue is started. Tasks which successfully start are considered to be running and removed from the queue.

6. If the hipri queue is empty (that is, all tasks queued there are now running) then the first task on the normal queue is started. If it starts, the task is considered running, removed from the queue, and this step repeated until either the normal queue is empty or the (new) first task fails to start.

   Tasks which fail to start are left on the queue to be retried later unless the attributes specify otherwise. The interval between retries gradually lengthens.

An exit code is saved after each enqueuing, starting, and completion (See exit(S) for more details). The last saved code is the default status used by the idle and exit cmds described in the section ``Running matching PM events''. An exit code of 0 (zero) means success; non-zero codes indicate failure.

Matching PM events

A simple name is either ``?'' or a name defined in a pwrevents file previously read by the pwrd command.

Defined names may contain only letters, digits, underscore (_), and dash (-). Defined names must start with a letter or underscore. A simple name only matches a named class or type.

A numeric value matches the class or type defined to be the same value. The special pattern ``~'' matches all defined classes or types matched by any action in this file.

Anything else is assumed to be an extended regular expression (ERE) as defined in regexp(M). Extended regular expressions match all classes or types whose name is matched by the ERE. An extended regular expression cannot contain commas or slashes (/).

Matches are inverted by preceding class or type with ``!''. That is, class/!type matches all PM events in class except for type.

Three notable patterns are:

?/.

match every type in an undefined class

class/?

match undefined types within a class

class/!~

match all types within the class that have not been previously matched

Running matching PM events

Single-quoting preserves all characters while backslash escapes are processed inside double quotes. This is analogous to the Bourne and Korn shells (see sh(C) and ksh(C)). Newlines should be avoided.

The cmds include:

! pipeline

The pipeline, which is the reminder of the line and not subject to above quoting rules, is a Bourne shell command to be run by the scriptfile specified by the -a option of pwrd.

The scriptfile has four arguments:

• the specified shell command pipeline

• this action's label

• the name of the matching event

• the name of STREAMS file containing the actual event

The default scriptfile, /etc/pwr/sys/pwrscript, executes the first argument (pipeline).

Within pipeline, $1 is the label, $2 is the matching event's name, and $3 is the special file. The environment variable PWRD_PID contains the PID of the dispatching pwrd daemon process. The default scriptfile defines environment variable PWRTASK_PID as the PID to which pwrd will route subsequent PM messages (via the special file). The !cmd starts only if the child process which runs the shell successfully fork(S)s. It completes when that child dies and has been cleaned up by the wait cmd (below). In the interim between start and completion, pwrd processes other PM events. Different pipelines are typically run via the normal queue on most PM events.

exit [ status ]

The daemon quits with exit code status. If no status is specified, the last saved code from enqueuing, starting, or completion is assumed. This is typically run as the last task on the normal queue in response to a pwrd/terminate event.

idle [ status ]

Fails to start until all previously enqueued tasks have completed. Once started, it completes immediately with code status. If no status is specified, the last saved code from enqueuing, starting, or completion is assumed. This is typically run as the next-to-last task on the normal queue in response to a pwrd/terminate event.

lock -u | -tdp

Locks or unlocks pwrd into core. The options have the following effect:

-u

unlocks pwrd

-t

locks text (code)

-d

locks data and stack

-p

locks the entire pwrd process

No pwrd children are affected (other than possibly being forced to swap or not being able to obtain sufficient memory because pwrd is locked into what is available). Typically this is not used.

read

Check to see if any new PM events have been sent to the daemon. The event is forwarded to the proper destination(s). If the event is addressed to the daemon (or to any process), all matching actions (tasks) are enqueued for running. The read cmd always starts, never hangs waiting for an event, and completes when all tasks for all new events are enqueued. Typically this is run on the hipri queue run in response to a signal/POLL event.

sched [policy@]priority

Sets the operating system scheduling parameters for the pwrd daemon process and all subsequently-spawned children (except those which specify their own sched=attribute). The policy is the method the operating system uses to choose this process to run (and influences how long the process subsequently runs):

nice

Traditional nice(S) round-robin scheduling. The numerically lower the priority the more likely this process is to be chosen; once chosen the process runs for up to one second.

other

Same as nice except the priority values are in the natural order: The numerically greater is the priority, the more important is the process.

rr

Strict round-robin. Every process at the same priority is run in turn.

fifo

First-in-first-out. The highest priority process runs until it chooses not to.

value

The identifying number of some other system-defined scheduling policy.

The legal priority values depend on the policy. A priority of max makes the process the most important possible within the policy; similarly, min makes the process the least important within the policy. If no policy is specified the priority of the policy currently in use is changed. The sched cmd is typically not used.

start

Enable both queues. Allow any task to enqueue. The start cmd always starts and completes immediately. Typically this is not used.

stop

Disable both queues. Prevent all tasks except those with the always attribute from enqueuing. The stop cmd always starts and completes immediately. Typically run on the hipri queue in response to a pwrd/terminate event.

term

Initiate a termination sequence. The first term cmd generates the PM event pwrd/terminate. Any subsequent term causes the daemon to immediately exit with status 3. term always starts and completes immediately. Typically run on the hipri queue (even when stopped) in response to a signal/TERM event.

wait

Check to see if any children spawned using ! have died and clean up after all which have. The wait cmd never hangs waiting for a child to die and completes as soon as all dead children have been cleaned up. Typically run as the first event on the hipri queue (even when stopped) in response to a signal/TERM event.

Matched PM event attributes

always

Enqueue the task even if the queue is stopped. By default, tasks cannot be enqueued on stopped queues.

first

Enqueue the task as first on the queue. By default, tasks are added to the end of the queue.

noforward

PM events addressed to this ! cmd (either by PID or label name) are not to be routed to the running child(ren); they are ignored instead.

queue=q

Enqueue the task on the queue q. Either hipri or normal. By default, tasks are enqueued on the queue corresponding to the priority of the STREAMS message containing the PM event.

limit=maxtasks

The maximum number of times an action may be running simultaneously. The task fails to start when this limit is exceeded. By default an action may run an unlimited number of times in parallel.

retry=maxretries

The maximum number of times an attempt is made to start a task before logging an error and discarding the task. The first retry is attempted one second later, the second two seconds after the first retry, the third three seconds after the second retry, and so on. The default is to keep retrying without limit.

sched=[policy@]priority

Set the operating system scheduling parameters for the child process which runs the associated ! cmd. The syntax is the same as the sched cmd.

Examples

Shut down the entire system in two minutes after pwrd is sent a SIGPWR signal, which commonly indicates an A/C mains power failure (and impending UPS battery failure). The shutdown process is run as the most important timesharing process (which in practice makes it the most important on the system while giving up time to so other processes can run).

   blackout:signal/PWR,apm/batteries-are-low:\
           sched=other@max:\
           !exec /etc/shutdown -y -g2 -f"Power failure"

   my-idler:my/idle,signal/USR1,apm/suggest-idling-system::\
           [ "X`who | wc -l`" = X0 ] && \
           exec pwrsend -f "$3" apm=system set/idle

This particular example may not be too effective since the exec of pwrsend will queue an update of the last time that pwrsend was accessed. This time is written to the disc several seconds later. Consequently, the disc may spin down as the system is idled, but will then spin up again to update the access time.

Warning

Limitations

Specifying numeric class or type values is pointless as they only match if that value is defined to have a name. It is easier to use the name.

The undefined simple name ``?'' only matches itself. That is, ``~'' , ``!~'', and any extended regular expression never match ``?''.

Files

/etc/pwr/sys/actions

default PM actions read by pwrd

See also