1f7c0ae1 |
1 | \cfg{man-identity}{pid}{1}{2012-11-30}{Simon Tatham}{Simon Tatham} |
2 | |
3 | \define{dash} \u2013{-} |
4 | |
5 | \title Man page for \c{pid} |
6 | |
7 | \U NAME |
8 | |
9 | \c{pid} \dash find the pid of a running program or script |
10 | |
11 | \U SYNOPSIS |
12 | |
d1bc4fef |
13 | \c pid [ options ] command [ arg... ] |
14 | \e bbbb iiiiiii iiiiiii iii |
1f7c0ae1 |
15 | |
16 | \U DESCRIPTION |
17 | |
18 | \cw{pid} is a program for finding the PID (process ID) of a currently |
19 | running program. This is useful if you need to send a signal to a |
20 | program you're running, or attach \cw{strace}(\e{1}) or a debugger to |
21 | it, or look in its \cw{/proc} entry. |
22 | |
23 | \cw{pid} tries to \q{do what you meant}. If you run \cw{pid emacs}, it |
24 | will find processes whose first command-line word is either \cw{emacs} |
25 | or ends in \cw{/emacs} (so it will match things like |
26 | \cw{/usr/local/bin/emacs} too). But if you run \cw{pid scriptname}, |
27 | where \cw{scriptname} is the name of a shell script or Perl script, it |
28 | will find processes whose command line looks like \cw{sh scriptname} |
29 | or \cw{perl -w scriptname}. If the script has forked into multiple |
30 | processes (as shell scripts sometimes do while executing complex |
31 | pipelines), \cw{pid} will go further and automatically narrow down to |
32 | the parent process of the whole lot. (That's done on a \q{best guess} |
33 | basis \dash there's no genuinely reliable way to tell if one process |
34 | has forked from another without \cw{exec}-ing anything afterwards.) |
35 | |
36 | By default, \cw{pid} outputs exactly one process ID, or the word |
37 | \cq{NONE} or \cq{MULTIPLE} if it finds no matching process or more |
38 | than one. This is a mode suitable for use as an argument to |
39 | \cw{strace} (which expects exactly one process ID after its \cw{-p} |
8f9d00c3 |
40 | argument) or \cw{gdb} or \cw{after} (which expect a single pid as an |
41 | argument); the \cq{NONE} or \cq{MULTIPLE} answers will provoke a |
42 | command-line parsing error rather than trying to trace the wrong |
43 | process or expanding to a less obviously wrong command line. Use the |
44 | \cw{-a} option to instead make \cw{pid} output a full list of pids |
45 | that match (e.g. if you want to pass them all to \cw{kill}(\e{1}). |
1f7c0ae1 |
46 | |
47 | You can also provide arguments to the command you're searching for, to |
48 | narrow your search further. For example, if you have several |
49 | \cw{emacs} processes editing different files, \cw{pid emacs foo.c} |
50 | will find just the one that was invoked with a particular filename on |
51 | its command line. |
52 | |
53 | \U OPTIONS |
54 | |
55 | \dt \cw{-a} |
56 | |
57 | \dd Report all pids that match the search, instead of printing |
58 | \cq{MULTIPLE} if there is more than one. This also disables the |
59 | behaviour of filtering out apparent forks of the same script. |
60 | |
d1bc4fef |
61 | \dt \cw{-U} |
62 | |
63 | \dd Report pids belonging to any user. By default, \cw{pid} will only |
64 | report processes owned by the same user as the one running it (except |
65 | when root, when it defaults to reporting everybody's). |
66 | |
1f7c0ae1 |
67 | \U BUGS |
68 | |
69 | \cw{pid} is currently completely specific to the Linux kernel, since |
70 | it depends on a Linux-style \cw{/proc}. It could be enhanced to deal |
71 | with other process-finding mechanisms, but so far this has not been |
72 | done. |
73 | |
74 | The whole idea of \cw{pid} is non-rigorous, so there will undoubtedly |
75 | be strange behaviour in corner cases of various kinds. The aim is to |
76 | do the right thing in most common cases. |
77 | |
78 | The current list of programs that \cw{pid} recognises as interpreters |
79 | for scripting languages is hardwired and there is no way to override |
80 | it. |
81 | |
82 | \U LICENCE |
83 | |
84 | \cw{pid} is free software, distributed under the MIT licence. Type |
85 | \cw{pid --licence} to see the full licence text. |
86 | |
87 | \versionid $Id$ |