summaryrefslogtreecommitdiff
path: root/doc/s6-ps.html
blob: 710b94e6d2256f9ff7a585b7fb711b28eeae6d4c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
<html>
  <head>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <meta http-equiv="Content-Language" content="en" />
    <title>s6-linux-utils: the s6-ps program</title>
    <meta name="Description" content="s6-linux-utils: the s6-ps program" />
    <meta name="Keywords" content="s6 linux administration root utilities ps proc procps process list" />
    <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> -->
  </head>
<body>

<p>
<a href="index.html">s6-linux-utils</a><br />
<a href="//skarnet.org/software/">Software</a><br />
<a href="//skarnet.org/">skarnet.org</a>
</p>

<h1> The <tt>s6-ps</tt> program </h1>

<p>
 <tt>s6-ps</tt> shows a list of processes on the system.
</p>

<h2> Interface </h2>

<pre>
     s6-ps [ -H ] [ -w spacing ] [ -W chanfile ] [ -l | -o <em>field</em>,<em>field</em>,... ]
</pre>

<ul>
 <li> s6-ps assumes the <em>proc</em> filesystem is mounted on <tt>/proc</tt>.
It scans <tt>/proc</tt> for a list of all processes on the system. </li>
 <li> It prints a header line, then information about the processes it has found,
one process per line. Then it exits 0. </li>
 <li> If s6-ps is not allowed to read a field, it will print <tt>*</tt> (a star) instead
of the field's content. <tt>-</tt> (a dash) means the field is unapplicable here,
for instance the "tty" field for a process that has no controlling terminal. </li>
</ul>

<h2> Options </h2>

<ul>
 <li> <tt>-H</tt>&nbsp;: tree. s6-ps will display he process list as a tree,
as <tt>ps f</tt> does. It will print kernel processes first, then user processes.
By default, the processes are simply ordered by increasing pid number, without
care for the process hierarchy. </li>
 <li> <tt>-w&nbsp;<em>spacing</em></tt>&nbsp;: leave at least <em>spacing</em>
space characters between two adjacent fields. Minimum is 1, default is 2,
maximum is 256. </li>
 <li> <tt>-W&nbsp;<em>wchanfile</em></tt>&nbsp;: force <em>wchanfile</em> as the
file listing kernel addresses for WCHAN fields. By default, s6-ps tries to use
<tt>/proc/kallsyms</tt>, <tt>/boot/System.map-`uname -r`</tt>, and
<tt>/boot/System.map</tt>, in that order. </li>
 <li> <tt>-l</tt>&nbsp;: long. Equivalent to
<tt>-o user,pid,cpcpu,pmem,vsize,rss,tty,s,start,cttime,args</tt>. </li>
 <li> <tt>-o&nbsp;<em>fieldlist</em></tt>&nbsp;: list of fields to print.
<em>fieldlist</em> must be a comma-separated list of fields, without spaces.
Fields cannot be duplicated. They will be printed in the given order.
The valid field names are listed below. The default field list is
<tt>user,pid,tty,s,start,args</tt>. </li>
</ul>

<h2> Fields </h2>

<p>
 The <tt>-o</tt> option makes it possible to customize s6-ps's output. Here are the
recognized <em>field</em> keywords and the corresponding field they display.
</p>

<ul>
 <li> <tt>pid</tt>&nbsp: the process id number. </li>
 <li> <tt>comm</tt>&nbsp: the command name as known by the kernel. </li>
 <li> <tt>s</tt>&nbsp: the one-character state of the process, then <tt>s</tt>
if the process is a session leader or <tt>+</tt> if it is a foreground
process group leader, then <tt>N</tt> if
the process is niced or <tt>&lt;</tt> if it is anti-niced. Unlike ps, s6-ps
cannot tell whether a process has locked memory pages or not. </li>
 <li> <tt>ppid</tt>&nbsp: the parent process' pid. </li>
 <li> <tt>pgrp</tt>&nbsp: the process group number. </li>
 <li> <tt>sess</tt>&nbsp: the session leader's pid. </li>
 <li> <tt>tty</tt>&nbsp: the name of the process's controlling terminal.</li>
 <li> <tt>tpgid</tt>&nbsp: the pid of the foreground process group. </li>
 <li> <tt>utime</tt>&nbsp: the time the process spent in user mode. </li>
 <li> <tt>stime</tt>&nbsp: the time the process spent in kernel mode. </li>
 <li> <tt>cutime</tt>&nbsp: the time spent in user mode by the process <em>and</em>
all its dead children. </li>
 <li> <tt>cstime</tt>&nbsp: the time spent in kernel mode by the process <em>and</em>
all its dead children. </li>
 <li> <tt>prio</tt>&nbsp: the process' priority as computed by the kernel. </li>
 <li> <tt>nice</tt>&nbsp: the process' nice value. </li>
 <li> <tt>thcount</tt>&nbsp: the number of threads in the process. </li>
 <li> <tt>start</tt>&nbsp: the start time of the process. </li>
 <li> <tt>vsize</tt>&nbsp: the virtual memory size of the process. </li>
 <li> <tt>rss</tt>&nbsp: the resident set size of the process. </li>
 <li> <tt>rsslimit</tt>&nbsp: the maximum rss allowed for the process. </li>
 <li> <tt>psr</tt>&nbsp: the number of the CPU  the process is running on. </li>
 <li> <tt>rtprio</tt>&nbsp: the real-time priority of the process. </li>
 <li> <tt>policy</tt>&nbsp: the real-time policy of the process - a symbolic name. </li>
 <li> <tt>user</tt>&nbsp: the user the process is running as. </li>
 <li> <tt>group</tt>&nbsp: the group the process is running as. </li>
 <li> <tt>pmem</tt>&nbsp: the percentage of the available virtual memory the process
is using. Be aware that it is a very rough estimate: determining exactly how much memory
a process is using is a complex task. </li>
 <li> <tt>wchan</tt>&nbsp: the name or address of the kernel function where the
proces is sleeping. It is actually very rare that a kernel is configured to properly
export that value, because it incurs a small performance cost. </li>
 <li> <tt>args</tt>&nbsp: the command line of the process. </li>
 <li> <tt>env</tt>&nbsp: the process environment. s6-ps can normally only print
the environment for processes running as the same user, or if it is run as root.
Be aware that the environment is usually quite large, and will create very long
lines, likely to mess up the display on a standard terminal. </li>
</li>
 <li> <tt>pcpu</tt>&nbsp: the percentage of CPU used by the process (total cpu time
divided by total running time). It is a mean value and does not reflect current CPU
usage. </li>
 <li> <tt>ttime</tt>&nbsp: total CPU time used by the process (user + kernel mode). </li>
 <li> <tt>cttime</tt>&nbsp: total CPU time used by the process and all its dead
children (user + kernel mode). </li>
 <li> <tt>tstart</tt>&nbsp: the start time of the process as a
<a href="http://cr.yp.to/libtai/tai64.html">TAI64N</a> value. </li>
 <li> <tt>cpcpu</tt>&nbsp: the percentage of CPU used by the process and its dead
children (total cpu time
divided by total running time). It is a mean value and does not reflect current CPU
usage. </li>
</ul>

</body>
</html>