Provided by: ips_4.0-1_amd64 bug

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.

COMMAND INPUT WHILE RUNNING

       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.

PERFORMANCE

       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

                                                                                           IPS(1)