.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "GSTACK 1"
.TH GSTACK 1 2026-05-10 gdb-17.2 "GNU Development Tools"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
gstack \- Print a stack trace of a running program
.SH SYNOPSIS
.IX Header "SYNOPSIS"
gstack [\-h | \-\-help] [\-v | \-\-version] \fIpid\fR
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Print a stack trace of a running program with process ID \fIpid\fR.  If the process
is multi-threaded, \fBgstack\fR outputs backtraces for every thread which exists
in the process.
.PP
The script invokes GDB, attaches to the given process ID, prints the stack trace,
and detaches from the process.
.PP
\&\fBgstack\fR exits with non-zero status if \f(CW\*(C`gdb\*(C'\fR was unable to attach to
the given process ID for any reason, such as a non-existent process ID or
insufficient privileges to attach to the process.
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-\-help\fR 4
.IX Item "--help"
.PD 0
.IP \fB\-h\fR 4
.IX Item "-h"
.PD
List all options, with brief explanations.
.IP \fB\-\-version\fR 4
.IX Item "--version"
.PD 0
.IP \fB\-v\fR 4
.IX Item "-v"
.PD
Print version information and then exit.
.SH ENVIRONMENT
.IX Header "ENVIRONMENT"
.IP \fBAWK\fR 4
.IX Item "AWK"
Full file name for an Awk interpreter to use.  If not set, \fBPATH\fR will be
searched for an \f(CW\*(C`awk\*(C'\fR program.
.IP \fBGDB\fR 4
.IX Item "GDB"
Full file name for a GDB executable to use to generate stack backtraces.
If not set, \fBPATH\fR will be searched for a \f(CW\*(C`gdb\*(C'\fR program.
.IP \fBGDBARGS\fR 4
.IX Item "GDBARGS"
Optional arguments to be passed to the \f(CW\*(C`gdb\*(C'\fR program.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
The full documentation for GDB is maintained as a Texinfo manual.
If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and GDB's Texinfo
documentation are properly installed at your site, the command
.PP
.Vb 1
\&        info gdb
.Ve
.PP
should give you access to the complete manual.
.PP
\&\fIUsing GDB: A Guide to the GNU Source-Level Debugger\fR,
Richard M. Stallman and Roland H. Pesch, July 1991.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 1988\-2025 Free Software Foundation, Inc.
.PP
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with the
Invariant Sections being "Free Software" and "Free Software Needs
Free Documentation", with the Front-Cover Texts being "A GNU Manual,"
and with the Back-Cover Texts as in (a) below.
.PP
(a) The FSF's Back-Cover Text is: "You are free to copy and modify
this GNU Manual.  Buying copies from GNU Press supports the FSF in
developing GNU and promoting software freedom."