mdw@git.distorted.org.uk Git - sgt/utils/blob - pid/pid.but

   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$