NAME

perpls - persistent process service lister

SYNOPSIS

perpls [-hV] [-b basedir ] [-cGgrt] [ sv ... ]

DESCRIPTION

perpls is used to list the current status of each sv argument monitored by an active perpd(8) supervisor.

perpls looks for sv in the directory basedir if given with the -b option, or as set in the PERP_BASE environmental variable, or in the current directory if neither of the previous is given. If no sv is given, perpls reports on all the subdirectories found in the base directory not beginning with `.'.

For each service sv, perpls prints a single line reporting on the status of the service. The report for each service is given in a format similar to the following:

# perpls foo
[+ +++ +++]  foo  uptime: 5s/5s  pids: 278/269

The line begins with a ``panel'' for the service, followed by the name of the service sv, followed by the current uptimes for the main/log processes, followed by the pids for the main/log processes.

The ``panel'' is a compact representation of the service status. It is displayed as a sequence of nine-characters within square brackets: a single character for the status of the perpd(8) supervisor itself, followed by a pair of triple-character sequences representing the main and log processes under its supervision.

The following characters are used in the panel:

+: Ok. The process is up and running. In the first position, shows that the perpd(8) supervisor itself is up and running. If the panel is all `+', it means all systems are go.
.: Down. The process is currently down.

# perpctl down foo && perpls foo
[+ ... +++]  foo  uptime: -s/90s  pids -/269

!: Attention. Appears in the first position of a triplet sequence when the service is currently in a state it doesn't want to be in. There is a problem somewhere, often indicating that a runscript is not executable. For example, a service currently down but ``wants'' to be up:

# perpctl down foo
# chmod -x foo/rc.main
# perpctl up foo && perpls foo
[+ !.. +++]  foo  uptime: -s/90s  pids 299/269

o: Once. Appears in the second position of a triplet sequence when the process is up and running, but flagged to run only once:

# perpctl once foo && perpls foo
[+ +o+ +++]  foo  uptime: 90s/90s  pids 278/269

p: Paused. Appears in the third position of a triplet sequence when the process is currently paused:

# perpctl pause foo && perpls foo
[+ ++p +++]  foo  uptime: 90s/90s  pids 278/269

r: Resetting. Appears in the third position of a triplet sequence when the service is currently resetting:

# perpctl pause foo && perpls foo
[+ ++r +++]  foo  uptime: 1s/90s  pids 299/269

-: Not active/available. In the first position of the panel, indicates the service definition sv is not active. The rest of the panel will be filled by `-' characters, and no reporting will appear for uptimes and pids.

# chmod -t foo && perpls foo
[- --- ---]  foo

E: Error. Appears only in the first position for overall status. Displayed when a problem was encountered in finding the sv argument or its perpd(8) supervisor. The rest of the panel will be filled by `-' characters, and followed by a diagnostic message describing the error:

# perpls foo
[E --- ---]  foo  error: failure stat() on service directory (ENOENT)

Colorized Listings

On terminals with color support, perpls may display a ``colorized'' listing when given the -G option on the command line, or if PERPLS_COLORS is defined with a capability string in the environment. The colorization is applied to the sv name in the report according to the status found for the service. Colorization is based on ANSI (ISO 6429) color sequences, selected from a capability table that defines the following entries (default values shown in parentheses):

df: Default (df=00). Applied when a capability is otherwise undefined.
na: Not active (na=00). Applied when a service is not activated.
an: Active-normal (an=01). Applied when the main service is active and running normally.
ar: Active-resetting (ar=01;33). Applied when the main service is resetting.
ap: Active-paused (ap=01;33). Applied when the main service is paused.
ad: Active-down (ad=01;34). Applied when the main service is down.
wu: Want-up (wu=01;33). Applied when the main service is down but wants up.
wd: Want-down (wd=01;33). Applied when the main service is up but wants down.
er: Error (er=01;31). Applied when an error encountered.
ex: Exception (ex=01;31). Applied when an exceptional condition encountered.

In a default installation, the capability table will be predefined with the following string:

"df=00:na=00:an=01:ar=01;33:ap=01;33:\ ad=01;34:wu=01;33:wd=01;33:er=01;31:ex=01;31"

OPTIONS

-b basedir: Base directory. Look for sv in basedir.
-c: Current directory. Look for sv in the current directory, even if PERP_BASE is defined in the environment.
-g: No color. Do not colorize listing, even if PERPLS_COLORS is defined in the environment.
-G: Colorize. Display a colorized listing. Use the capability table given by PERPLS_COLORS if defined in the environment, or use a built-in capability table if PERPLS_COLORS is not defined.
-h: Help. Print a brief usage message to stderr and exit.
-K: Capability. Print the current capability table for colorized listings and exit. The environment variable PERPLS_COLORS must be defined. Otherwise this option must be combined with the -G option to display the built-in capability table.
-r: Reverse sort. Display the listing in reverse order. Normally the listing appears in the order of sv given on the command line, or in alphabetical order if no sv are given. The -r option lists in the reverse of this order. This option may be combined with the -t option.
-t: Uptime. Display the listing ordered by uptime of the main service, shortest uptimes first. May be combined with the -r option to display longest uptimes first.
-V: Version. Print the version number to stderr and exit.

AUTHOR