NAME¶
ips - intelligent process status
SYNOPSIS¶
ips [column-options] [select-options] [sort-options] [other-options]
[macro-names]
DESCRIPTION¶
Ips is an intelligent ps-like program which displays process or thread
status obtained from the
/proc filesystem. It has features to make
tracking of active, semi-active, and transient processes easy. It is extremely
configurable, but is still efficient.
Ips tries to consume as little
runtime as possible by only collecting as much information as is needed for
the particular display specified.
Ips normally displays the process status once and then exits, but it can
also act like a
top program to display process status repeatedly. The
output can be displayed line by line as for a dumb terminal, displayed through
the
curses library using cursor addressing, or displayed in a raw X11
window. The output can be colored to highlight rows of interest.
The information to be displayed about processes can be selected on a
column-by-column basis. Each column displayes one piece of information about
the processes. The set of columns to be displayed and their order may be
changed.
Processes can be selected for displaying based on the values of one or more
columns. Some selection criteria are pre-defined for efficiency and
convenience, such as the process id and user name. Other selection criteria
can be defined using general expressions which refer to any combination of the
column values.
The order that processes are displayed is based on sorting the values of one or
more columns. The set of columns to sort by, the order of the columns for
sorting, and whether each sorting is normal or reversed can be changed.
Arbitrary expressions based on the values of the columns can also be used for
sorting.
Process lines can be colored based on arbitrary expressions so as to highlight
the processes of interest. The foreground color, background color,
underlining, and boldness can be set for the output. The header lines can also
be colored.
Ips reads initilization files to define macros which make it easy to
specify useful combinations of configuration options. Therefore many different
output formats and short-cuts to common option combinations can be used.
Options to
ips are minus signs followed by short words or phrases.
Multiple options cannot be combined together following one minus sign (unlike
the case with many other utilities). Options are processed in the order that
they are given on the command line. Combinations of options which appear to do
conflicting actions are permitted. This is because each option merely modifies
the state left from the previous options. The state left after all the options
have been processed is the one which is actually executed.
SPECIFYING COLUMNS FOR OUTPUT¶
There are many columns of information which can be selected for display. Each
column displays one item of information about the displayed processes. The set
of columns and their order can be specified by the user.
Each column has a defined width, which is usually adequate to hold the widest
possible data item for that column. This width is just a default and can be
changed if desired. The data items shown within a column are left justified,
right justified, or centered within the column width according to the type of
column. In some cases the column width might not be adequate to show the
complete data item, and in this case the item is truncated to the column
width. Truncation is indicated by a vertical bar at the right edge of the
column. (The usual columns which require truncation are the
command and
environment columns, which displays the full command line or
environment string for a process.)
The
ips program enforces a limit on the total width used for displaying
of columns. If too many columns are selected for display, then one or more
columns from the right are removed until the remaining columns fit within the
total width. The width limit is usually implicitly set by the terminal or
window's width. But if desired, the width limit can be explicitly specified by
the user. (This is convenient if the
ips program's output is being
piped to another process, for example.)
If the final displayed column does not extend out to the total width limit, then
that column's width is extended to include the remaining columns. This allows
more of the data item to be seen before it requires truncation. (Typically,
the
command column is the rightmost column so as to take advantage of
these extra columns.)
The options for manipulating columns are
-col,
-addcol,
-remcol,
-sep,
-width,
-colwidth,
-vert,
and
-listcolumns.
The
-col option first clears any existing list of column names for
display, and then sets the new list of column names to be displayed as
specified. The columns are displayed in the order specified in the option. If
there is a duplicate column name in the list, then only the last use of the
column name is effective.
The
-addcol option adds the specified columns to the existing list of
column names to be displayed. The new columns are added in the order
specified, and by default are appended after previously existing columns in
the list. If any of the column names are already in the existing list, then
they are removed from the list before being added back into it. An argument
can be a number, in which case any later column names are inserted into the
list starting at the specified column number. Out of range column numbers are
silently changed to the nearest legal value. For example,
ips -addcol 2 uid
gid 999 percentcpu adds the user id column as column 2, the group id
column as column 3, and appends the percentage cpu column after all other
columns.
The
-remcol option removes the specified columns from the list of column
names, without caring whether or not the columns were in the list.
The
-sep option specifies the separation between adjacent columns in the
display. It has one argument, which is the number of spaces to insert between
each pair of columns. The default separation is 2 spaces.
The
-width option specifies the total width available for the display of
columns. It has one argument, which is the number of columns available. If
this option is not given and the output is to
stdout, then the width is
obtained from the kernel if
stdout is a terminal, or else is set to 80
columns if
stdout is not a terminal.
The
-colwidth option specifies the width of a particular column. It has
one or two arguments. The first argument is the name of the column whose width
is to be set. The second argument is the desired width of the column. If the
second argument is not given, then the column width is set to its default
value.
The
-vert option changes the output format from the default horizontal
one into a vertical one. In vertical format, the status for each process is
multi-line where each displayed value uses a complete line. The beginning of
each line contains the column heading and a colon character, unless the
-noheader option was used. Each value is left justified to the same
position on the line and can use the rest of the available output width. The
-sep option sets the number of spaces between the widest column header
and the beginning of the values. If multiple processes are being displayed,
then a blank line separates their status lines.
The
-listcolumns option simply lists the names of the available columns
and then exits. The heading for the column and the default width of the column
is also shown.
SELECTION OF PROCESSES FOR DISPLAY¶
The set of processes to be shown can be specified by a number of options. Each
of these options specifies a condition to be met. Processes will only be shown
which meet all of the specified conditions.
The options which specify conditions to be met are
-pid,
-user,
-group,
-my,
-noroot,
-noself,
-active,
-top, and
-cond.
The
-pid option is followed by one or more process ids, and restricts the
display to only the specified processes if they exist. Using this option
multiple times adds to the list of process ids to be shown.
The
-user option is followed by one or more user names or user ids, and
restricts the display to processes with those user ids if they exist. Using
this option multiple times adds to the list of users to be shown.
The
-group option is followed by one or more group names or group ids,
and restricts the display to processes with those group ids if they exist.
Using this option multiple times adds to the list of groups to be shown.
The
-program option is followed by one or more program names, and
restricts the display to processes having those program names if they exist. A
program name is the name of the executable file which started the process (as
displayed in the
program column). This is not always the same name as
shown in the command line arguments. Using this option multiple times adds to
the list of programs to be shown.
The
-my option only selects process which have my user id.
The
-noroot option disables selection of processes which run as root.
The
-noself option removes the
ips process from the display.
The
-active option only shows processes which are either running or which
have run recently.
The
-top option limits the display to a specified number of processes.
After displaying the specified number of processes, further ones are ignored.
If no argument is given to the option, then the height of the terminal or
window is used to limit the number of displayed processes.
The previous options can only select processes which match a small set of
possible conditions. The
-cond option is different, and understands
general expressions. The expression is specified in the argument following the
option. (The argument usually needs quoting to avoid being split into multiple
arguments or having its tokens interpreted by the shell.)
You can select processes matching a condition which is any combination of the
column values for the process. This is done by specifying an expression to be
evaluated for each process. If the result of the expression is non-zero or
non-null, then the process is selected. If the expression cannot be evaluated
(such as an attempt to divide by zero), then no error is generated but the
process will not be selected.
Most of the expression syntax from C can be applied to the column values, such
as arithmetic, comparisons, logical ANDs and ORs, the use of parentheses, the
question mark operator, and some built-in functions. Numeric and string
constants can be used within expressions. Numbers are usually decimal, but are
octal if started with a leading 0, and hex if started with a leading 0x.
Strings are enclosed in a pair of matching single or double quotes. Generally,
string values must be compared with string values, and numeric values compared
with numeric values. But in some cases numeric values can be converted to
strings for comparison.
Column values are represented in the expressions by their column names as listed
by the
-listcolumns option, where unique abbreviations are allowed.
Values from multiple columns can be used in the same expression, and can be
compared against each other. Some column values are numeric, whereas other
column values are strings.
The value obtained from using a column name is usually its
base value,
which is the unformatted primitive unit of information for the column. For
example, for runtimes, this is the number of
jiffies of runtime the
process has used (i.e., 100's of seconds). A base value can be either a
numeric or string value, depending on the column.
You can apply qualifiers to the column names to use alternate representations of
a column value. A qualifier is a word following the column name which is
separated from it by a period. The allowed qualifiers are
base,
show, and
test.
Using the
base qualifier is the same thing as using the column name by
itself (the base value).
Using the
show qualifier returns the column value as a string value which
is the same as is displayed for the column. So for example, for runtimes the
show value contains colons and periods separating hours, minutes, and
parts of seconds.
Using the
test qualifier returns a boolean value (1 for TRUE and 0 for
FALSE) indicating whether some useful aspect of the column is true. The
meaning of this test varies depending on the column. For example, for the
column showing the parent pid, the test returns whether or not the process has
a parent (i.e., not 0 or 1).
There are several functions that can be used within expressions. These are
min,
max,
abs,
strlen,
match,
cmp,
str, and
my.
The
min,
max, and
abs functions take numeric arguments, and
take the minimum of two numbers, the maximum of two numbers, or the absolute
value of a number.
The
strlen function returns length of the string argument, or if a number
was given, the length of the string representation of that number.
The
cmp function compares two arguments and returns -1, 0, or 1 according
to whether the first argument is less than, equal to, or greater than the
second argument. If both arguments are numeric, then the comparison is done on
their values. Otherwise, the comparison is done as a string, converting a
numeric argument to a string value if required.
The
match function takes two arguments which may be string or numeric
values. Numeric values are converted into the corresponding string value. The
first argument is a string value to be tested. The second argument is a
wildcard pattern to match against. The wildcard syntax is like filename
matching, so '?' means any single character, '*' means any sequence of
characters, and '[]' matches single occurances of the enclosed characters. The
function returns 1 if the string matches, and 0 if it does not.
The
-str function converts its argument to a string value.
The
my function takes one argument, which is a column name (possibly
qualified). It returns the value of that column for the
ips process
itself. For example,
my(ttyname) returns a string which is my
terminal name. In order to be of maximum use, the
uid,
user,
gid, and
group columns return the user's real group and user ids
for the
my function, even if the
ips program has been made
setuid.
Upper case names can be used within expressions, which are macro names to be
expanded into sub-expressions. These macro names are defined in the
initialization files. The expansion of the macro must be a complete expression
on its own, with proper use of parenthesis and operators. The macro name is
replaced with the result of evaluating the sub-expression, and so can be a
number or a string. The definition of a sub-expression can also contain macro
names which will also be evaluated.
SORTING OF DISPLAYED PROCESSES¶
The default sorting order of displayed processes is by their process id. But the
list of displayed processes can be sorted based on any combination of the
column values. The columns to be sorted by do not have to be restricted to the
set of columns which are being displayed.
The first specified sorting column is used to sort the processes. If two or more
processes have the same value for the first sorting column, then they are
sorted by the second specified sorting column (if specified). This process
continues as long as there are sorting columns specified and any processes
still need sorting. If any processes are still left with matching sorting
values after all the sorting columns have been used, then the process ids are
used for a final sort.
Sorting on a column can be either a normal sort, or a reverse sort. In a normal
sort, processes with smaller values will be displayed first. In a reverse
sort, processes with larger values will be displayed first. Values are
compared based on the type of column used for sorting. Some columns sort based
on integer values, and some sort based on string values. Even if the displayed
value is a string, the sorting may be based on the underlying integral
base value. (The
start-time column is an example.)
The
-sort,
-revsort,
-sortexpr,
-revsortexpr, and
-nosort options are used to specify sorting values.
The
-sort and
-revsort options are used to append columns to the
sorting list, either for normal sorting or for reverse sorting. They are
followed by the list of columns to be added for sorting.
The
-sortexpr and
-revsortexpr options append an arbitrary
expression to the sorting list, either for normal sorting or for reverse
sorting. The expression can be made up of column names, numbers, strings, and
operators, as in the
-cond option. Sorting is done on the result of the
expression which may be a numeric or string value.
The
-nosort removes all columns from the sorting list, leaving only the
default sort based on process id.
COLORING OF THE OUTPUT¶
By default, all of the output text from
ips is shown in the normal
foreground and background colors of the output method (e.g., black on white
for X11 output).
The information line, the header line, and the process rows can be individually
colored by specifying foreground colors, background colors, and attributes for
them.
The specification of a color is most generally given by string consisting of
three parts which are separated by slash characters. These three parts are a
foreground color name, a background color name, and attribute letters.
If only one slash is present then only a foreground and background color name is
given, with no attributes. If no slash is present then only a foreground color
name is given with no background name or attributes.
If a color name is empty or has the special value
default, then that
color is the default color of the output method.
The attribute letters can be either
'b' to indicate bold
(or bright) text, or else
'u' to indicated underlined
text, or else both.
Examples of color specifications are:
red,
/blue,
green/yellow,
default/default,
//u, and
red//bu.
These set a foreground of red with a default background, a default foreground
with a blue background, a foreground of green with a yellow background, a
default foreground and background, a default foreground and background with
the text underlined, and a red foreground with a default background with the
text underlined and made bold.
The available colors depends on the output method, as well as the naming
convention of the colors.
For X11 output, many colors are available and can be named explicitly or else
specified using 3 or 6 hexadecimal digits following a hash mark to give the
red, green, and blue components.
For curses and terminal output, up to 256 colors can be used (according to the
capabilities of the terminal). The colors are numeric values from 0 to 255,
with the first 8 being the primary colors, the next 8 being the secondary
colors, the last 20 or so being gray scale colors, and the others an arbitrary
color. Alternatively, the names of the eight primary colors can be used.
The information line can be colored using the
-infocolor option. The
header line can be colored using the
-headercolor option.
The process rows being output can be colored using one or more uses of the
-rowcolor option. This option takes two arguments. The first argument
is a color specification. The second argument is an expression to be evaluated
for the process being shown in the row, as in the
-cond option. If the
condition is true then the row will be colored in the specified color.
If multiple
-rowcolor options are used and multiple conditions match a
row, then the color of the last matching condition is used for the row.
Rows which are not matched by the conditions in any
-rowcolor option are
colored in the default foreground and background colors.
SPECIFYING THE DISPLAY METHOD¶
The output from
ips can be displayed using one of several different
methods. The
-once,
-loop,
-curses, and
-x11
options are used to specify which of the display methods are used. The default
option is
-once.
Both of the
-once and
-loop options specifies a display method
which writes the process status to
stdout line by line using no cursor
addressing sequences. Such output is suitable for saving to a file using
redirection of standard output or for processing in a pipeline. The difference
between the two options indicates whether or not the output is a once-only
snapshot or is to be repeated indefinitely in a loop. There is no limit to the
number of lines that can be written. The
-clear option can be used with
either of these options to write the standard ANSI clear screen escape
sequence before each display of the process status.
The
-curses option specifies a display method which uses the
curses(3) library for efficient updating of the screen using cursor
addressing sequences. This display uses the whole terminal screen. The screen
can be resized if desired. The number of lines of information is limited by
the size of the screen so that only a subset of the status might be visible at
one time. However, the display can be scrolled automatically or manually so
that eventually all of the status can be seen. The
ips program is in
looping mode for this display method. The program can be terminated by typing
the
q or
ESCAPE characters into the terminal.
The
-x11 option specifies a display method which uses a raw X11 window
(i.e., without using a terminal emulator such as
xterm). The window can
be resized if desired. The number of lines of information is limited by the
number of rows in the window so that only a subset of the status might be
visible at one time. However, the display can be scrolled automatically or
manually so that eventually all of the status can be seen. The
ips
program is in looping mode for this display method. The program can be
terminated by typing the
q or
ESCAPE characters into the window
or by closing the window using the window manager.
The
-display,
-geometry,
-font,
-foreground, and
-background options can be used to set the display name, window
geometry, font name, foreground color, and background color for the X11
window. If no display name is set then the default one using the
DISPLAY environment variable is used. The default window geometry is
150x50. The default font is the
fixed font, which is a mono-space
(i.e., fixed-width) font. If a different font is specified then it should also
be a mono-space font. The default foreground and background colors are
black and
white.
Note: The X11 display mode is optional and must have been compiled into
ips when it was built. This allows
ips to be built for systems
which have no X11 libraries installed. If your version of
ips does not
have X11 support, then the use of the
-x11 option will produce an error
message and fail.
For all of the looping display methods, the
-sleep option can be used to
set the sleep time in seconds between updates. (If not given, the default
sleep time is 10 seconds.) The argument to this option can be a fixed point
value, so that for example, a value of 0.5 specifies a sleep of 1/2 second.
The
-scroll and
-overlap options can be used for the curses and
X11 display modes. The
-scroll option sets the time interval in seconds
for automatic scolling of the display if more processes are displayed than
will fit. The default scroll time is 30 seconds. Note that the scrolling
interval does not affect how often the display is updated (use
-sleep
for that). It just means that when the display is next updated, if the
required time since the last scrolling had elapsed, then scrolling occurs for
that update. It might take many update cycles before scrolling allows all of
the process status to be seen. Scrolling wraps around, so that after the last
process has been seen in the display, then the next scrolled display will
return to the first process again. A scroll time of zero disables automatic
scrolling completely.
The
-overlap option specifies the number of lines of process status which
are duplicated when scrolling occurs. The default overlap is one line.
THREAD HANDLING¶
Depending on the options used, the
ips program shows either the status of
the processes in the system or the status of the threads in the system.
Without any options only processes are shown. In order to show thread
information, the
-showthreads option must be used.
Some processes only consist of one thread of execution, which is the case for
most simple programs which have no use for multi-threading. For these
processes, the showing of processes or threads gives the same results and
there are no problems in interpreting their status.
However, some processes contain more than one thread of execution. Threads share
many of their attributes with each other, such as their memory and opened
files, but have distinct program counters, stack pointers, runtime, and
process state. The threads of a process all have the same process id, but have
another id called the thread id (tid) which distinguishes them. One of the
threads is called the main thread and has a thread id which is the same as the
process id.
When
ips shows only processes, then the status shown for a process
consisting of multiple threads can be slightly misleading. The shared
attributes are shown correctly for the process. However, some of the distinct
status values are only those of the main thread, while those values for the
other threads are ignored. Examples of these values are the program counter
and the process state.
In particular, the process state can give very misleading status of the process.
If the main thread is sleeping, but another thread is constantly running, the
state of the process can be misleadingly reported as 'S'. In this case, the
runtime of the process increases quickly and is shown as active, however it
never appears to be running.
The runtime of a process is the sum of all of the runtimes of the individual
threads, and so is generally meaningful. Note that in a multi-cpu system where
multiple threads can simultaneously run, the runtime of a process can appear
to increase faster than the clock rate since multiple threads can contribute
the full elapsed time to the process runtime.
When
ips is showing thread status then all of the above problems are
avoided. Each thread of a process is then shown with its correct status. This
includes the program counter, the process state, and the runtime. In this
case, threads which are running will show their state as 'R' as expected. Also
note that when threads are shown, the display of the main thread is only that
of that particular thread, so that its runtime is no longer the sum of all of
the threads.
Even when only processes are being shown, the state information for the process
can optionally be more accurate than indicated above. If the
-usethreads option is used or if the
states column is used, then
the
ips program will examine the states of all of the theads of a
process, and select the most important state among all of the threads as the
state to show for the process as a whole. For example, the priority order of
the states starts with the 'R', 'D', and 'S' states so that, for example, if
any thread is running, then the state of the process is 'R' as expected.
The
states column shows all of the states of the threads of a process
using multiple letters and numeric counts. For example, a value of 'R3DS2'
indicates that there are three running threads, one thread in a disk I/O wait,
and two sleeping threads.
The curses and X11 display modes allow commands to be typed while they are
running. Commands are not visible as they are typed to the screen or window.
The commands are read character by character so that they are executed
immediately when complete without requiring a terminating newline. If the
command is one which affects the display then the current sleep is canceled so
that the display can show the result.
Some commands accept an optional numeric argument which is typed just prior to
the command. This numeric argument can be a non-negative integer value or a
non-negative fixed point number. Commands which only accept an integer value
ignore any fractional part. If a numeric argument is not given, the commands
will use a default value. If a numeric argument is typed, but you no longer
want to use it (as when you have made a typing mistake), then the backspace or
delete keys will totally remove any partially typed numeric argument. At this
point you can type in a new numeric argument (if desired).
The
s command sets the sleep time to the number of seconds specified in
the preceding numeric argument. The command accepts a fixed point value so
that sleeps less than one second are possible. If no argument is given then
the sleep time is set to the default value of 10 seconds.
The
a command sets the automatic scrolling time to the number of seconds
specified in the preceding numeric argument. If no argument is given then the
autoscroll time is set to the default value of 30 seconds. A value of 0
disables autoscrolling.
The
t and
b commands change the display to show the top or the
bottom of the process list. (These are the first and last pages of the
display.)
The
n and
p commands change the display to show the next or
previous page of the process list. If the next page is past the end of the
list then the first page is displayed. Similarly, if the previous page is
before the beginning of the list then the last page is displayed.
The
o command sets the number of lines of overlap between pages of data
to the value specified in the preceding numeric argument. If no argument is
given then the overlap value is set to the default value of 1 line.
The
i command enables or disables an information line at the top of the
display which shows the total number of process and threads in the system, the
number of threads or processes which are currently being shown, the sleep
time, the currently displayed page number, and if the display is frozen, an
indication of that fact. Without any arguments, the display of the information
line is toggled. A zero argument disables the line. A nonzero argument enables
the line.
The
h command enables or disables the column header line at the top of
the display. Without any arguments, the display of the header line is toggled.
A zero argument disables the header. A nonzero argument enables the header.
The
'f' command enables or disables the frozen state of the display.
Without any arguments, the frozen state is toggled. A nonzero argument freezes
the display. A zero argument unfreezes the display. While the display is
frozen, the
ips program simply waits for further commands (ignoring the
normal sleep and autoscroll times). The automatic collection of new process
data is disabled. Automatic scrolling is also disabled. However, commands can
still be typed while the display is frozen to perform scrolling or process
status updating on demand.
A
SPACE or
RETURN character updates the display immediately. New
process data will be collected for the display. This occurs even if the
display is currently frozen.
The
r command refreshes the contents of the display to fix any glitches.
This is mostly intended for curses use when other programs output to the
screen, or when the terminal emulator misbehaves.
A
q or
ESCAPE character quits
ips.
All other characters are illegal and ring the bell.
INITIALIZATION FILES AND MACROS¶
For convenience and to allow users to configure the output to their liking,
ips reads two initialization files on startup. The first of the files
to be read is the system initialization file
/etc/ips.init which is
used to set system defaults for
ips.
The second initialization file to be read is the user initialization file
$HOME/.ipsrc located in each user's home directory. This allows each
user to modify the system defaults for their own use. The reading of the
user's initialization file can be disabled by using the
-noinit option.
If used, this option must be the first option after the command name.
The contents of the initialization files are very simple. Each line of the file
can be blank, be a comment, or be a macro definition. If any line ends in a
backslash, then the backslash is replaced by a space and the next line is
appended to it. Comment lines have a hash mask character as their first
non-blank character. Comment lines and blank lines are ignored.
The first line of initialization files must consist of the word
#ips#,
otherwise an error message will be generated and the program will exit.
Macro definitions are used to replace single arguments on the command line with
possibly large replacement strings with many arguments. The replacement
strings can themselves use macros, and these new macros are also removed and
replaced. Macro replacement continues until either no more macros remain to be
replaced, or until the allowed macro depth is exceeded.
Macro names are usually distinguished from non-macros by the fact that macros
begin with upper case letters. Since column names are all in lower case, there
is no problem distinguishing between a column name and a macro name.
There are three different types of macros in
ips. These types are
distinguished by the location of the macro usage within the command line. The
three types of macros are commands, columns, and expressions. Command macros
define a list of command line options and their arguments. Column macros
define a list of column names. Expression macros define a sub-expression for
the
-cond,
-sortexpr, and
-revsortexpr options.
Because the meaning of these three types of macros differs so much, and the
replacement strings for the macros would generally make no sense if used for a
different type of macro, the three types of macros have independent name
spaces. This means that the same macro name could be defined three times, once
for each type of macro. (But this is probably bad practice).
To define a macro in an initialization file, you use one of the keywords
option,
column, or
expr, followed by the macro name and
the replacement strings for the macro, all on one line (taking into account
the use of backslashes to continue lines). The macro names must begin with an
upper case letter.
The
option keyword defines a macro as being one or more command line
options. The replacement string consists of a number of space separated
options and arguments as used on the command line, including the leading
hyphens for the options. Arguments for options must be contained within the
macro expansion itself. The macro expansion can itself contain macros which
will also be expanded into more options.
As the single exception to the requirement that macro names are in upper case,
if a word appears on the
ips command line which is not an option, and
which cannot be an argument for an option, then that word with its initial
letter converted to upper case is treated as an option macro to be expanded.
An important special case of this is a word typed immediately after the
ips program name. This is typically a macro name which defines a
particular format of display. For example, the command
ips top would
expand the option macro named
Top which could be defined to emulate the
output of the
top program.
The
column keyword defines a macro as being a list of column names. The
replacement string consists of a number of space separated column names. The
macro expansion can itself contain macros which will also be expanded into
more column names.
The
expr keyword defines a macro which is an expression used for the
-cond,
-sortexpr, or
-revsortexpr options. The
replacement string consists of a complete expression using numbers, strings,
column names, and possibly other macros which will also be expanded.
Here is an example of a valid initialization file:
#ips#
# The special command macro run by default
option SysInit -col pid parent user summary runtime command
# Definitions for other commands of interest
option Stop -cond Stop
option Cmd -col pid command -sep 1
option Env -col pid environment -sep 1
option Vert -vert -sep 1 -col All
option Mytty -cond Mytty
option Top -sep 1 -col pid user summary runtime \
percentcpu command -revsort percentcpu \
-revsort runorder -curses -clear -active
# Definitions for groups of columns
column Run runtime idletime percentcpu
column Regs eip esp
column Sigs signalcatch signalignore signalblock
column Size residentsetsize percentmemory size
column Stdio stdin stdout stderr
# All columns
column All pid parentpid uid user gid group \
processgroup ttyprocessgroup \
state flags nice priority realtimepriority policy \
systemtime usertime runtime childruntime \
threads percentcpu runorder \
residentsetsize size percentmemory \
active idletime starttime age realtimer \
eip esp waitchannel waitsymbol \
pagefaults minorpagefaults majorpagefaults \
pageswaps childpageswaps \
signalcatch signalignore signalblock \
ttyname ttydevice \
openfiles stdin stdout stderr stdio \
currentdirectory rootdirectory executable \
summary program command environment
# Definitions for expressions used in conditions
expr Me (uid == my(uid))
expr Server (uid < 100)
expr User !Server
expr Stop (state == 'T')
expr Mytty (ttydev == my(ttydev))
The special option macro names of
SysInit and
UserInit are
automatically expanded (if they are defined) at the start of every run of
ips. These macros are used to initialize parameters to default values.
Examples of this initialization is to specify the default list of columns to
be displayed and the default sleep time when looping. The
SysInit macro
definition is usually contained in the system initialization file, while the
UserInit macro definition is usually contained in the user's
initialization file. Parameters set by these macros can be modified by using
options on the command line.
USEFUL MACROS¶
The standard supplied system initialization file
/etc/ips.init contains
many macros of interest. This section describes some of the standard macros
which are provided. Remember that these macros can be used in lower case on
the command line.
Warning: These macros might not actually work on your system as described here
since they can be changed by the system administrator. The system
administrator may also have added other useful macros which are not described
here. You should examine the macro definitions in the initialization file in
order to make full use of
ips.
The default macro
SysInit adds a condition to only show your own
processes. So in order to see other user's processes, you must disable that
condition explicitly or else use a macro which disables it. The
Nocond
macro removes all conditions on the selection of processes allowing you to see
all processes.
The user name column is not shown by default. The
Long macro changes the
displayed columns to include the user name and the parent pid.
The
All macro combines the
Nocond and
Long macros to show
all processes in a nice display.
The
Pack macro shows many useful columns together including the user and
group ids, the state of stdio, and the process age.
The
Cmd and
Env macros show only the process id and the command
line or environment so that you can see much more of these columns than is
usual.
The
Files macro shows columns related to files, such as the number of
open files, the status of stdio, and the current and root directories.
The
Cpu macro shows a snapshot display of the currently active processes.
It has a two second sleep in order to detect running processes. The
Top
macro shows the same display format, but in a looping manner using
curses and including recently active processes.
The width of the runtime columns is not adequate to hold really large runtimes.
The
Widerun macro increases the width of these columns to show larger
runtimes.
The
Wide macro makes the output width be as large as possible, allowing
the showing of very long command lines or environments.
The
Vert macro sets the output format to vertical and shows every column
value.
The
Tty macro adds a condition to only show processes which are on a
terminal.
The
Mytty macro adds a condition to only show processes which are on your
own terminal.
The
Stop macro adds a condition to show stopped processes.
OTHER FEATURES¶
There are several other features of
ips which can be specified using
command line options. These options are
-default,
-read,
-initsleep,
-noheader,
-activetime,
-deathtime,
-synctime,
-listmacros,
-listcolumns,
-version,
-end, and
-help.
The
-default option is useful to reset parameters that have been set by
previous options. In particular, it is useful to reset parameters that have
been set by the initialization files. It accepts one or more option names
(without the leading hyphens). Any parameter set by the indicated option is
restored to its initial state as when the
ips program started. For
example,
-default pid removes any previous restriction on the process
ids that can be shown.
The output from the
-help option will briefly describe the use of the
remaining options.
COLUMN DESCRIPTIONS¶
Some of the columns for displaying are self-evident. But many of them need an
explanation, and this is done here. Due to the permissions on /proc, some of
the column values may not be available for every process. Columns marked as
restricted are only available if the process has your own user id, you
are running as root, or the
ips program itself is setuid to root.
The
state column shows the current state of the process. This is a single
letter, where 'R' is runnable, 'D' is disk I/O, 'T' is stopped, 'S' is
sleeping, 'Z' is zombie, and ' ' is dead (nonexistent).
The
eip and
esp columns show the instruction pointer and stack
pointer of the process. The instruction pointer is also known as the program
counter, or PC.
The
waitchannel column shows the hex address within the kernel that the
process is sleeping on. This is zero if the process is not sleeping. Usually,
different reasons for sleeping use different addresses.
The
waitsymbol column shows the symbolic address within the kernel that
the process is sleeping on. This is blank if the process is not sleeping.
The
program and
command columns show the program name and command
line of the process. The program name is just the name of the executable file
without any arguments. The command line shows the arguments that the program
was started with. If no command line arguments were supplied to the program,
then this column shows the program name enclosed in parenthesis.
The
idletime column shows the number of minutes that the process has been
idle. An idle process is one which has not (detectably) run at all in the
indicated interval. The idle time is only known by examining processes over
time, and so the true idle time of a process which existed before
ips
was run is not known. In these cases, the idle time is simply the amount of
time that
ips has been running, and the times are marked with a leading
plus sign.
The
active column shows whether or not the process has been active. It
shows one of the values "active" or "idle". This column is
provided mainly for use in sorting and selecting.
The
ttyname and
ttydevice columns show the controlling terminal of
the process, which is usually the terminal where the user logged into. The
device is the kernel's id for the terminal, and is just a number. The name is
found by searching /dev for a character device which has that same id and then
displaying the device name with the /dev removed.
The
user,
uid,
group, and
gid columns show the user
ids and group ids of a process. The uid and gid are the numeric ids as used by
the kernel. The user and group are the conversion of those ids to user names
and group names, as found in the /etc/passwd and /etc/group files.
The
percentcpu column shows the percentage of CPU time that the process
has used in a certain recent time interval called the sample interval. The
samples are taken at a maximum rate of five times a second according to the
current sleep time of the
ips program. The sample interval is a sliding
value so as to give an average cpu percentage over a specified number of
seconds. This makes the values less 'jumpy' than instantaneous cpu percentages
would give and act more like the system load averages. The sample interval is
set using the
-percentseconds option, which can have a value from 0 to
20. The default sample interval is 10 seconds. The percentage runtime is 100
times the quotient of the runtime used during the sample interval by the
sample interval itself. Note that for a multi-threaded process on a multi-cpu
system, the percentage runtime can reach multiples of 100.
The
residentsetsize column is the number of K of memory used by the
process. Pages of a process which are not in memory are not counted by this
column.
The
starttime and
age columns show the time at which the process
was created. The start time is the time of day the process started, and if the
process was in existence for over one day, then the number of days previously
that the process was started. The age is the number of minutes that the
process has existed, and is the difference between the current time and the
time that the process started.
The
flags column shows some kernel flags associated with the process, in
hex.
The
minorpagefaults,
majorpagefaults, and
pagefaults
columns show the number of minor page faults, major page faults, and the total
page faults of the process. Minor page faults are faults on pages that do not
require any disk I/O, which are copy on write or touching empty pages. Major
page faults are faults which require disk I/O, such as reading in of text file
pages or swap pages.
The
signalcatch,
signalignore, and
signalblock columns show
the state of signal handling for the process. Each of these value is a hex
value, where signal N is bit number N-1 (counting from bit 0 at the right).
Caught signals are those for which a signal handler is installed. Ignored
signals are those for which the process is ignoring signals. Blocked signals
are those which are pending delivery, but which the process has blocked from
being delivered.
The
openfiles column displays the number of open files that the process
has. This column is restricted.
The
runorder column shows the relative run order of the processes. The
run order is a monotonically increasing value representing the number of
process samplings that
ips has made since it started. Processes are
assigned the current run order value whenever they are seen to have been
active since the last sample. Processes with a larger run order value have run
more recently.
The
currentdirectory column gives the current working directory of the
process in the kernel's internal values of device number and inode number,
separated by a colon. The device number is in hex, and the inode number is in
decimal. This column is restricted.
The
rootdirectory column gives the root directory of the process in the
kernel's internal values of device number and inode number, separated by a
colon. The device number is in hex, and the inode number is in decimal. This
column is restricted.
The
executable column gives the device number and inode number of the
executable file for the process, separated by a colon. The device number is in
hex, and the inode number is in decimal. This column is restricted.
The
realtimer column shows the amount of time that the process wants to
sleep before being woken up. This is either just the number of seconds, or
else is the number of seconds and parts of seconds. This value does not
decrement as time passes, so you don't know when the sleep time will expire.
The
stdin,
stdout, and
stderr columns show the file names
associated with the stdin, stdout, or stderr file descriptors of the process.
These columns are restricted.
The
stdio column shows a summary of the files associated with the stdin,
stdout, or stderr file descriptors of the process. This is in the form of a
three character string with one character for each of the
stdin,
stdout, and
stderr file descriptors. The character is 'T' for a
terminal, 'P' for a pipe, 'S' for a socket, 'N' for /dev/null, 'F' for some
other file, and '-' for a closed file descriptor (or if the information is
unavailable). This column is restricted.
The
summary column shows many flag characters which summarize some of the
state of the process. This consists of a string of 14 characters, where each
character is either a dash or a letter. A letter indicates the specified
condition is true for that character position, whereas a dash indicates that
the condition is false for that character position.
Character 1 is the state of the process, except that if the process is sleeping,
then it is 'A' for recently active, or 'I' for idle, and if the process has
died (i.e., no longer existent), then it is '-'. Character 2 is 'W' if the
process has no resident memory, and is therefore swapped out. Character 3 is
'N' if the process has been niced, and is 'H' if the process has been given as
higher priority than normal. Character 4 is 'S' if the process is a session id
leader. Character 5 is 'P' if the process is a process group leader. Character
6 is 'T' if the process has a controlling terminal. Character 7 is 'F' if the
process is a foreground process, which means that its process group matches
its controlling terminal's process group. Character 8 is 'I' if the process
has no parent, meaning it is owned by
init. Character 9 is 'h' if the
process is catching SIGHUP or 'H' if the process is ignoring SIGHUP. Character
10 is 't' if the process is catching SIGTERM or 'T' if the process is ignoring
SIGTERM. Character 11 is 'U' if the process has your user id. Character 12 is
'G' if the process has your group id. Character 13 is 'R' if the process is
running as root. Character 14 shows the age of the process. It is 'N' for a
new process, 'M' for a process one minute old, 'F' for a process five minutes
old, 'T' for a process ten minutes old, 'H' for a process one hour old, 'D'
for a process one day old, and 'W' for a process one week old.
Some data is only collected if the columns using that data are used. Here 'used'
means either displaying, selecting on, or sorting by the column. Avoiding
columns when they are not required will save the time used to collect that
data.
Most process status is obtained by scanning the /proc directory looking for
filenames which are numeric (which are the process ids). For each of these
processes, the file /proc/<pid>/stat must be opened and read to collect
most of the process status.
If detailed thread information is requested, then the directories
/proc/<pid>/task must be scanned for filenames which are numeric (which
are the thread ids). For each of these threads, the file
/proc/<pid>/task/<tid>/stat must be opened and read to collect the
thread status.
Additional files in /proc might need to be read to get the full status that is
required.
Using the
-pid option will save much work, since then the scan of /proc
is avoided and only the specified process ids will be examined. Using
-noself avoids looking at our own process.
Using the
-my,
-user,
-group, and
-noroot options
will save time reading and parsing of the process status for the eliminated
processes, and stop collection of other data for the eliminated processes.
The
-top and
-cond options may save time by eliminating the
display of process information. But the information is still collected.
The
-synctime option changes the interval on which the full process
status is collected for inactive processes. (See the RISKS section below.)
Setting this to a shorter time interval will increase the runtime.
The
command column requires the opening and reading of
/proc/<pid>/cmdline whenever the process has changed state or when the
synctime has expired.
The
environment column requires the opening and reading of
/proc/<pid>/environ whenver the process has changed state or when the
synctime has expired.
The
active,
idletime, and
percentcpu columns and the
-active option require that the
ips program sample the processes
twice before displaying anything, with a small sleep between the two samples.
So there will be a delay before seeing anything.
The
ttyname column requires the reading of /dev to find the list of
character devices. This work adds a delay to the program before anything is
displayed. It is only required once per run.
The
openfiles column requires the reading of all the files in
/proc/<pid>/fd whenever the process has changed state or when the
synctime has expired.
The
stdin,
stdout,
stderr, and
stdio columns require
the link values of one or more of the /proc/<pid>/fd/<fd> files to
obtain their information whenever the process has changed state or when the
synctime has expired.
The
currentdirectory column requires the reading of the
/proc/<pid>/cwd file whenever the process has changed state or when the
synctime has expired.
The
rootdirectory column requires the reading of the
/proc/<pid>/root file whenever the process has changed state or when the
synctime has expired.
The
waitsymbol column requires the reading of the /proc/<pid>/wchan
file whenever the process has changed state or when the synctime has expired.
The
executable column requires the reading of the /proc/<pid>/exe
file whenever the process has changed state or when the synctime has expired.
RISKS¶
The determination of whether a process has been active since the last sample is
not completely foolproof. Some of the process data is only collected when a
process has been active, or else has not been collected for a while, and so
there is a small risk that the data is obsolete. The columns which are not
necessarily collected on every update are the ones which require examining
/proc files other than the main status file. These columns include the command
line, the environment, the current directory, and the number of opened files.
The
ips program checks many process status values to determine whether or
not a process has been active since the last sampling. If any of these differ
from the last sampling, then the process is active. These values are the
process state, runtime, flags, page faults, start time, stack pointer,
instruction pointer, and wait channel. New process are always active, and
processes whose state is 'R' or 'D' are always active.
It is possible that a process which wakes up for only a short time, does very
little and then goes back to sleep will appear to be inactive. (The kernel
only has a 1/100 second runtime resolution, and so the small runtime of the
process might not have been seen by the kernel.)
The
-synctime option can be used to reduce or expand this risk of showing
obsolete data. It accepts the number of seconds at which the complete status
of the process is collected even when it is idle. It defaults to one minute.
Setting the synctime to zero produces a status with no obsolete data.
The list of user names, group names, and device names are only collected when
ips is first started. Changes to the password file, group files, or
device files will not be seen while the program is running.
The data collected by
ips is dynamic. It can change even while the status
is being collected for a single process. So the data shown is only a snapshot
and is never absolutely consistent.
LIMITS¶
The following are some limits to the operation of
ips. These are
compile-time constants, and could be increased if required by recompiling the
program.
You can only specify 100 process ids for the
-pid option.
You can only specify 100 user names or ids for the
-user option.
You can only specify 100 group names or ids for the
-group option.
You can only have 1000 arguments on a command line.
The maximum output width is 31K characters, where K is 1024.
The maximum command string length is 10K.
The maximum environment string length is 20K.
The maximum program name string length is 32. This length is imposed by the
kernel which only has a buffer of this size.
The maximum separation between columns is 20 spaces.
The maximum depth of expansion of option macros is 20.
The maximum depth of expansion of expression macros is 20.
The maximum number of seconds for calculating cpu percentages is 20 seconds.
BUGS¶
The
-clear option clears the screen by outputting the ANSI escape
sequence for clearing the screen. If your terminal does not understand this
escape sequence then this option will not work correctly.
Proportional spaced fonts do not work correctly in the X11 display mode.
Using both of the
-vert and
-top options together without any
argument does nothing useful. The number of processes shown will be dependent
on the screen height, but the output will not be limited to the screen height
since each process status prints on multiple lines.
Pagination of output when using the
-vert option is not correct.
There are no quoting characters for macro definitions, so you cannot create
single arguments which contain blanks. This means that if you use the
-cond,
-sortexpr, or
-revsortexpr options in the macro
definition file, then the following expression must not contain any blanks.
However, you
can use blanks in the definition of an expression macro.
The specification of a window position for X11 using the
-geometry option
does not work correctly.
This program is dependent on the layout of the /proc file system which changes
depending on the kernel version. This particular version of
ips works
for kernel version 2.6.13.
FUTURES¶
I would like to allow macros to accept arguments enclosed in parenthesis, and
have those arguments substituted into the replacement string at the locations
matching parameter names for the macro.
I would like to allow user-defined columns where the user can define the format
of the data to be displayed using the results of expressions on other column
data.
CREDITS¶
Some of the knowledge on how to process and display the data from /proc was
obtained by reading the procps version 0.97 code by Michael K. Johnson.
The pattern matching code was adapted from code written by Ingo Wilken.
AUTHOR¶
David I. Bell
dbell@canb.auug.org.au
25 April 2010