.\" $FreeBSD$
.\" $Id: pstack.1,v 1.2 2002/10/02 09:53:47 pmedwards Exp $
.\"
.Dd Oct 2, 2002
.Dt PSTACK 1
.Os
.Sh NAME
.Nm pstack
.Nd get stack traces of threads in a running process
.Sh SYNOPSIS
.Nm
.Op Fl a Ar arg-count
.Op Fl e Ar executable-file
.Op Fl f Ar frame-count
.Op Fl o
.Op Fl O
.Op Fl t
.Op Fl v
.Ar pid | core
.Nm
.Op Fl d Ar elf-file
.Sh DESCRIPTION
Displays the stack traces of each thread in the running process with process
id
.Ar pid
or from the core file
.Ar core
.Pp
Options are as follows:
.Bl -tag -width Fl
.It Fl a Ar arg-count
Attempt to read
.Ar arg-count
word-size arguments from the stack for each frame.
.It Fl f Ar frame-count
Do not attempt to read any more than
.Ar frame-count
stack frames for each stack.
.It Fl d
Causes
.Nm
to print a dump of the ELF information in an object file,
and exit.
.It Fl e Ar file
Specify an alternate executable to use for locating symbols in the
process.  This is useful if the process was started from a stripped
version of an executable, and you have the unstripped version
available. If examining a corefile, this argument is required.
.It Fl n
Don't stop and resume the target process. This can confuse or crash
.Nm
if the stack changes as it is being read, but means that pstack has
less of an effect (and chance to crash) the target process
.It Fl o
For each stack frame, display the name of the object in which the current
function lies
.It Fl O
For each stack frame, display the full path to the object in which
the current function lies
.It Fl t
Display the amount of time that the process was suspended by
.Nm
.It Fl v
verbose. Display debugging and diagnostics.
.El
.Sh SEE ALSO
.Xr procfs 5
.Xr ptrace 2
.Sh BUGS
.Nm
Works for x86 32-bit ELF executables only for the moment. (ie, no
a.out support, and no Alpha support).
It is also very dependent on the current FreeBSD threads implementation. 
.Pp
Because of a bug in
.Xr ptrace 2
,
.Nm
needs to send the target process a SIGCONT to re-awaken it.  This
is not normally an issue, but may cause problems for some processes
that catch SIGCONT, and use it in non-obvious ways.
A fix for the FreeBSD ptrace() interface is available from the
FreeBSD PR database, in kern/35175. Adding "-DKERN_35175_FIXED" to CFLAGS when
compiling
.Nm
will stop it sending the SIGCONT its targets.
.Pp
Because of a non-obvious interaction between wait(), ptrace() and
processes started with rfork(RFLINUXTHPN), there's some hackery
involved in detecting that the child process has been stopped
successfully by
.Nm
Adding "-DMISC_39201_FIXED" to CFLAGS when compiling
.Nm
removes the associated hackery.
.Sh AUTHORS
Peter Edwards <pmedwards@eircom.net>