1proc(1)                          User Commands                         proc(1)
2
3
4

NAME

6       proc,  pflags,  pcred,  pldd,  psig, pstack, pfiles, pwdx, pstop, prun,
7       pwait, ptime - proc tools
8

SYNOPSIS

10       /usr/bin/pflags [-r] pid | core [/lwp] ...
11
12
13       /usr/bin/pcred [pid | core]...
14
15
16       /usr/bin/pcred [-u user/uid] [-g group/gid] [-G grouplist] pid...
17
18
19       /usr/bin/pcred -l login pid...
20
21
22       /usr/bin/pldd [-Fl] [pid | core]...
23
24
25       /usr/bin/psig [-n] pid...
26
27
28       /usr/bin/pstack [-F] pid | core [/lwp] ...
29
30
31       /usr/bin/pfiles [-Fn] pid...
32
33
34       /usr/bin/pwdx pid...
35
36
37       /usr/bin/pstop pid[/lwp] ...
38
39
40       /usr/bin/prun pid[/lwp] ...
41
42
43       /usr/bin/pwait [-v] pid...
44
45
46       /usr/bin/ptime [-Fm] [-p] pid...
47
48
49       /usr/bin/ptime [-m]command [arg]...
50
51

DESCRIPTION

53       The proc tools are utilities  that  exercise  features  of  /proc  (see
54       proc(4)). Most of them take a list of process-ids (pid). The tools that
55       do take process-ids also accept /proc/nnn as a process-id, so the shell
56       expansion /proc/* can be used to specify all processes in the system.
57
58
59       Some of the proc tools can also be applied to core files (see core(4)).
60       The tools that apply to core files accept a list of either process  IDs
61       or names of core files or both.
62
63
64       Some  of  the  proc  tools can operate on individual threads. Users can
65       examine only selected threads by appending /thread-id to the process-id
66       or core. Multiple threads can be selected using the - and , delimiters.
67       For example /1,2,7-9 examines threads 1, 2, 7, 8, and 9.
68
69
70       See WARNINGS.
71
72       pflags    Print the /proc tracing flags, the pending and held  signals,
73                 and other /proc status information for each process or speci‐
74                 fied lwps in each process.
75
76
77       pcred     Print or set the credentials (effective, real, saved UIDs and
78                 GIDs) of each process.
79
80
81       pldd      List  the dynamic libraries linked into each process, includ‐
82                 ing shared objects explicitly attached using dlopen(3C).  See
83                 also ldd(1).
84
85
86       psig      List  the  signal  actions  and handlers of each process. See
87                 signal.h(3HEAD).
88
89
90       pstack    Print a hex+symbolic stack trace for each process  or  speci‐
91                 fied lwps in each process.
92
93
94       pfiles    Report  fstat(2)  and fcntl(2) information for all open files
95                 in each process. For network endpoints, the local  (and  peer
96                 if connected) address information is also provided. For sock‐
97                 ets, the socket type, socket options  and  send  and  receive
98                 buffer  sizes  are  also provided. In addition, a path to the
99                 file  is  reported  if  the  information  is  available  from
100                 /proc/pid/path. This is not necessarily the same name used to
101                 open the file. See proc(4) for more information.
102
103
104       pwdx      Print the current working directory of each process.
105
106
107       pstop     Stop each process or the specified lwps (PR_REQUESTED stop).
108
109
110       prun      Set running each process or the specified lwps  (the  inverse
111                 of pstop).
112
113
114       pwait     Wait for all of the specified processes to terminate.
115
116
117       ptime     Time the command, like time(1), but using microstate account‐
118                 ing for reproducible precision. Unlike time(1),  children  of
119                 the command are not timed.
120
121                 If  the  -p pid version is used, display a snapshot of timing
122                 statistics for the specified pid.
123
124

OPTIONS

126       The following general options are supported:
127
128       -F    Force. Grabs the target process even if another process has  con‐
129             trol.
130
131
132       -n    (psig  and pfiles only) Sets non-verbose mode. psig displays sig‐
133             nal handler addresses rather than names. pfiles does not  display
134             verbose  information  for  each  file descriptor. Instead, pfiles
135             limits its output to the information that would be  retrieved  if
136             the process applied fstat(2) to each of its file descriptors.
137
138
139       -r    (pflags  only)  If  the  process is stopped, displays its machine
140             registers.
141
142
143       -v    (pwait only) Verbose. Reports terminations to standard output.
144
145
146
147       In addition to  the  general  options,  pcred  supports  the  following
148       options:
149
150       -g group/gid    Sets the real, effective, and saved group ids (GIDs) of
151                       the target processes to the specified value.
152
153
154       -G grouplist    Sets the supplementary GIDs of the  target  process  to
155                       the  specified list of groups. The supplementary groups
156                       should be specified as a comma-separated list of  group
157                       names ids. An empty list clears the supplementary group
158                       list of the target processes.
159
160
161       -l login        Sets the real, effective, and saved UIDs of the  target
162                       processes  to  the UID of the specified login. Sets the
163                       real, effective, and saved GIDs of the target processes
164                       to  the GID of the specified login. Sets the supplemen‐
165                       tary group list to the supplementary groups list of the
166                       specified login.
167
168
169       -u user/uid     Sets  the real, effective, and saved user ids (UIDs) of
170                       the target processes to the specified value.
171
172
173
174       In addition to the general options, pldd supports the following option:
175
176       -l    Shows unresolved dynamic linker map names.
177
178
179
180       In addition to  the  general  options,  ptime  supports  the  following
181       options:
182
183       -m        Display the full set of microstate accounting statistics.
184
185                 The displayed fields are as follows:
186
187                 real    Wall clock time.
188
189
190                 user    User level CPU time.
191
192
193                 sys     System call CPU time.
194
195
196                 trap    Other system trap CPU time.
197
198
199                 tflt    Text page fault sleep time.
200
201
202                 dflt    Data page fault sleep time.
203
204
205                 kflt    Kernel page fault sleep time.
206
207
208                 lock    User lock wait sleep time.
209
210
211                 slp     All other sleep time.
212
213
214                 lat     CPU latency (wait) time.
215
216
217                 stop    Stopped time.
218
219
220
221       -p pid    Displays  a  snapshot  of timing statistics for the specified
222                 pid.
223
224
225
226       To set the credentials of another process, a process must  have  suffi‐
227       cient  privilege  to  change  its user and group ids to those specified
228       according to the rules laid out in setuid(2) and it  must  have  suffi‐
229       cient privilege to control the target process.
230

USAGE

232       These  proc tools stop their target processes while inspecting them and
233       reporting the results: pfiles, pldd, and pstack. A process can do noth‐
234       ing  while  it  is  stopped.  Thus,  for  example,  if  the X server is
235       inspected by one of these proc tools running in a window  under  the  X
236       server's control, the whole window system can become deadlocked because
237       the proc tool would be attempting to print its results to a window that
238       cannot  be  refreshed.  Logging  in  from  from  another  system  using
239       rlogin(1) and killing the offending proc tool would clear up the  dead‐
240       lock in this case.
241
242
243       See WARNINGS.
244
245
246       Caution  should  be exercised when using the -F flag. Imposing two con‐
247       trolling processes on one victim process can lead to chaos.  Safety  is
248       assured  only if the primary controlling process, typically a debugger,
249       has stopped the victim process and the primary controlling  process  is
250       doing  nothing  at  the moment of application of the proc tool in ques‐
251       tion.
252
253
254       Some of the proc tools can also be applied to core files, as  shown  by
255       the  synopsis above. A core file is a snapshot of a process's state and
256       is produced by the kernel prior to terminating a process with a  signal
257       or  by  the gcore(1) utility. Some of the proc tools can need to derive
258       the name of the executable corresponding to the  process  which  dumped
259       core  or  the  names  of  shared libraries associated with the process.
260       These files are needed, for example, to provide symbol  table  informa‐
261       tion  for  pstack(1).  If the proc tool in question is unable to locate
262       the needed executable or shared library,  some  symbol  information  is
263       unavailable  for  display. Similarly, if a core file from one operating
264       system release is examined on a different operating system release, the
265       run-time link-editor debugging interface (librtld_db) cannot be able to
266       initialize. In this case, symbol information for  shared  libraries  is
267       not available.
268

EXIT STATUS

270       The following exit values are returned:
271
272       0           Successful operation.
273
274
275       non-zero    An error has occurred.
276
277

FILES

279       /proc/*    process files
280
281

ATTRIBUTES

283       See attributes(5) for descriptions of the following attributes:
284
285
286
287
288       ┌─────────────────────────────┬─────────────────────────────┐
289       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
290       ├─────────────────────────────┼─────────────────────────────┤
291       │Availability                 │SUNWesu                      │
292       ├─────────────────────────────┼─────────────────────────────┤
293       │Interface Stability          │See below.                   │
294       └─────────────────────────────┴─────────────────────────────┘
295
296
297       The human readable output is Uncommitted. The options are Committed.
298

SEE ALSO

300       gcore(1),  ldd(1),  pargs(1),  pgrep(1),  pkill(1), plimit(1), pmap(1),
301       preap(1),  ps(1),  ptree(1),  ppgsz(1),  pwd(1),  rlogin(1),   time(1),
302       truss(1),  wait(1),  fcntl(2),  fstat(2),  setuid(2),  dlopen(3C), sig‐
303       nal.h(3HEAD), core(4), proc(4), process(4), attributes(5), zones(5)
304

WARNINGS

306       The following proc tools stop their target processes  while  inspecting
307       them and reporting the results: pfiles, pldd, and pstack. However, even
308       if pstack operates on an individual thread, it stops the whole process.
309
310
311       A process or thread can do nothing while  it  is  stopped.  Stopping  a
312       heavily  used process or thread in a production environment, even for a
313       short amount of time, can cause severe bottlenecks and  even  hangs  of
314       these  processes  or  threads, causing them to be unavailable to users.
315       Some databases could also terminate abnormally. Thus,  for  example,  a
316       database  server  under  heavy load could hang when one of the database
317       processes or threads is traced using the above  mentioned  proc  tools.
318       Because  of  this,  stopping  a  UNIX process or thread in a production
319       environment should be avoided.
320
321
322       A process or thread being stopped by these tools can be  identified  by
323       issuing  /usr/bin/ps  -eflL  and  looking  for "T" in the first column.
324       Notice that certain processes, for example "sched", can  show  the  "T"
325       status by default most of the time.
326
327
328       The  process ID returned for locked files on network file systems might
329       not be meaningful.
330
331
332
333SunOS 5.11                        10 Dec 2008                          proc(1)
Impressum