buildtools/binutils/gprofng/doc/gp-display-src.1

.\" -*- 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 "GP-DISPLAY-SRC.1 1"
.TH GP-DISPLAY-SRC.1 1 2023-07-30 binutils-2.41 "User Commands"
.\" 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
gprofng display src \- Display the source code, optionally interleaved with the disassembly of the target object
.SH SYNOPSIS
.IX Header "SYNOPSIS"
\&\fBgprofng display src\fR [\fIoption(s)\fR] \fItarget_file\fR
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Display the source code listing, or source code interleaved with disassembly code,
as extracted from the target file (an executable, shared object, object file, or a
Java .class file).
.PP
For example, this command displays the source code and disassembly listing for a
function called \fBmxv_core\fR that is part of object file \fBmxv.o\fR:
.PP
.Vb 1
\&        $ gprofng display src \-disasm mxv_core mxv.o
.Ve
.PP
To list the source code and disassembly for all the functions in this file,
use the following command:
.PP
.Vb 1
\&        $ gprofng display src \-disasm all \-1 mxv.o
.Ve
.PP
The \fItarget_file\fR is the name of an executable, a shared object, an object
file (.o), or a Java .class file.
.PP
If no options are given, the source code listing of the \fItarget_file\fR
is shown.  This is equivalent to \fB\-source all \-1\fR.  If this information
is not available, a message to this extent is printed.
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-\-version\fR 4
.IX Item "--version"
Print the version number and exit.
.IP \fB\-\-help\fR 4
.IX Item "--help"
Print usage information and exit.
.IP \fB\-functions\fR 4
.IX Item "-functions"
List all the functions from the given object.
.IP "\fB\-source\fR \fIitem\fR\fB \fR\fItag\fR" 4
.IX Item "-source item tag"
Show the source code for \fIitem\fR in \fItarget_file\fR.  The \fItag\fR
is used to differentiate in case there are multiple occurences with the same
name.
See the \fBNOTES\fR section for the definition of \fIitem\fR and \fItag\fR.
.IP "\fB\-disasm\fR \fIitem\fR\fB \fR\fItag\fR" 4
.IX Item "-disasm item tag"
Include the disassembly in the source listing. The default listing does not
include the disassembly. If the source code is not available, show a listing
of the disassembly only.
See the \fBNOTES\fR section for the definition of \fIitem\fR and \fItag\fR.
.IP "\fB\-outfile\fR \fIfilename\fR" 4
.IX Item "-outfile filename"
Write results to file \fIfilename\fR.  A dash (\-) writes to stdout. This is also
the default. Note that this option only affects those options included to the
right of this option.
.SH NOTES
.IX Header "NOTES"
Use \fIitem\fR to specify the name of a function, or of a source or object
file that was used to build the executable, or shared object.
.PP
The \fItag\fR is an index used to determine which item is being referred
to when multiple functions have the same name. It is required, but will
be ignored if not necessary to resolve the function.
.PP
The \fIitem\fR may also be specified in the form \fBfunction`file`\fR, in
which case the source or disassembly of the named function in the source
context of the named file will be used.
.PP
The special \fIitem\fR and \fItag\fR combination \fBall \-1\fR, is used to
indicate generating the source, or disassembly, for all functions in the
\&\fItarget_file\fR.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBgprofng\fR\|(1), \fBgp\-archive\fR\|(1), \fBgp\-collect\-app\fR\|(1), \fBgp\-display\-html\fR\|(1), \fBgp\-display\-text\fR\|(1)
.PP
The user guide for gprofng is maintained as a Texinfo manual.  If the info
and gprofng programs are correctly installed, the command
\&\fBinfo gprofng\fR should give access to this document.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright (c) 2022\-2023 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 no Invariant Sections, with no Front-Cover Texts, and with no
Back-Cover Texts.  A copy of the license is included in the
section entitled "GNU Free Documentation License".