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 | |
13 | \c pid [ -a ] command [ arg... ] |
14 | \e bbbb bb iiiiiii iii |
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} |
40 | argument) or \cw{gdb} (which expects a single pid too); the \cq{NONE} |
41 | or \cq{MULTIPLE} answers will provoke a command-line parsing error |
42 | rather than trying to trace the wrong process or expanding to a less |
43 | obviously wrong command line. Use the \cw{-a} option to instead make |
44 | \cw{pid} output a full list of pids that match (e.g. if you want to |
45 | pass them all to \cw{kill}(\e{1}). |
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 | |
61 | \U BUGS |
62 | |
63 | \cw{pid} is currently completely specific to the Linux kernel, since |
64 | it depends on a Linux-style \cw{/proc}. It could be enhanced to deal |
65 | with other process-finding mechanisms, but so far this has not been |
66 | done. |
67 | |
68 | The whole idea of \cw{pid} is non-rigorous, so there will undoubtedly |
69 | be strange behaviour in corner cases of various kinds. The aim is to |
70 | do the right thing in most common cases. |
71 | |
72 | The current list of programs that \cw{pid} recognises as interpreters |
73 | for scripting languages is hardwired and there is no way to override |
74 | it. |
75 | |
76 | \U LICENCE |
77 | |
78 | \cw{pid} is free software, distributed under the MIT licence. Type |
79 | \cw{pid --licence} to see the full licence text. |
80 | |
81 | \versionid $Id$ |