| 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 [ options ] command [ arg... ] |
| 14 | \e bbbb iiiiiii 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} 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}). |
| 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 | \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 | |
| 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$ |