1@c ----------------------------------------------------------------------------
2@c This is the Texinfo source file for the gp-display-src man page.
3@c
4@c Author: Ruud van der Pas
5@c ----------------------------------------------------------------------------
6@ifset man
7\input texinfo @c -*-texinfo-*-
8@setfilename gp-display-src
9@settitle Display source code and optionally disassembly of the target object
10@include gp-macros.texi
11@end ifset
12
13@c ----------------------------------------------------------------------------
14@c This is from the man-pages(7) man page
15@c
16@c "The list below shows conventional or suggested sections.  Most manual pages
17@c  should include at least the highlighted sections.  Arrange a new manual
18@c  page so that sections are placed in the order shown in the list."
19@c
20@c              NAME
21@c              SYNOPSIS
22@c              CONFIGURATION    [Normally only in Section 4]
23@c              DESCRIPTION
24@c              OPTIONS          [Normally only in Sections 1, 8]
25@c              EXIT STATUS      [Normally only in Sections 1, 8]
26@c              RETURN VALUE     [Normally only in Sections 2, 3]
27@c              ERRORS           [Typically only in Sections 2, 3]
28@c              ENVIRONMENT
29@c              FILES
30@c              VERSIONS         [Normally only in Sections 2, 3]
31@c              ATTRIBUTES       [Normally only in Sections 2, 3]
32@c              CONFORMING TO
33@c              NOTES
34@c              BUGS
35@c              EXAMPLES
36@c              AUTHORS          [Discouraged]
37@c              REPORTING BUGS   [Not used in man-pages]
38@c              COPYRIGHT        [Not used in man-pages]
39@c              SEE ALSO
40@c
41@c This is what the texi2pod.pl tool recognizes:
42@c
43@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES
44@c               BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) {
45@c
46@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which
47@c makes sense and adhered to for the other formats.
48@c ----------------------------------------------------------------------------
49
50@c ----------------------------------------------------------------------------
51@c NAME section
52@c ----------------------------------------------------------------------------
53
54@ManPageStart{NAME}
55@c man begin NAME
56
57gp-display-src - Display the source code, optionally interleaved with the
58disassembly of the target object
59
60@c man end
61@ManPageEnd{}
62
63@c ----------------------------------------------------------------------------
64@c SYNOPSIS section
65@c ----------------------------------------------------------------------------
66
67@ManPageStart{SYNOPSIS}
68@c man begin SYNOPSIS
69
70@command{gprofng display src} [@var{option(s)}] @var{target-file}
71
72@c man end
73@ManPageEnd{}
74
75@c ----------------------------------------------------------------------------
76@c DESCRIPTION section
77@c ----------------------------------------------------------------------------
78
79@ManPageStart{DESCRIPTION}
80@c man begin DESCRIPTION
81
82Display the source code listing, or source code interleaved with disassembly
83code, as extracted from the target file (an executable, shared object, object
84file, or a Java .class file).
85
86For example, this command displays the source code and disassembly listing for
87a function called @samp{mxv_core} that is part of object file @samp{mxv.o}:
88
89@smallexample
90$ gprofng display src -disasm mxv_core mxv.o
91@end smallexample
92
93To list the source code and disassembly for all the functions in this file,
94use the following command:
95
96@smallexample
97$ gprofng display src -disasm all -1 mxv.o
98@end smallexample
99
100The @var{target-file} is the name of an executable, a shared object, an object
101file (.o), or a Java .class file.
102
103If no options are given, the source code listing of the @var{target-file}
104is shown.  This is equivalent to @samp{-source all -1}.  If this information
105is not available, a message to this extent is printed.
106
107@c man end
108@ManPageEnd{}
109
110@c ----------------------------------------------------------------------------
111@c OPTIONS section
112@c ----------------------------------------------------------------------------
113
114@ManPageStart{OPTIONS}
115@c man begin OPTIONS
116
117@table @gcctabopt
118
119@item --version
120@ifclear man
121@IndexSubentry{Options, @code{--version}}
122@end ifclear
123
124Print the version number and exit.
125
126@item --help
127@ifclear man
128@IndexSubentry{Options, @code{--help}}
129@end ifclear
130
131Print usage information and exit.
132
133@item -functions
134@ifclear man
135@IndexSubentry{Options,  @code{-functions}}
136@IndexSubentry{Commands, @code{functions}}
137@end ifclear
138List all the functions from the given object.
139
140@item -source @var{item} @var{tag}
141@ifclear man
142@IndexSubentry{Options, @code{-source}}
143@IndexSubentry{Commands, @code{source}}
144@end ifclear
145Show the source code for @var{item} in @var{target-file}.  The @var{tag}
146is used to differentiate in case there are multiple occurences with the same
147name.
148See the @samp{NOTES} section for the definition of @var{item} and @var{tag}.
149
150@item -disasm @var{item} @var{tag}
151@ifclear man
152@IndexSubentry{Options,  @code{-disasm}}
153@IndexSubentry{Commands, @code{disasm}}
154@end ifclear
155Include the disassembly in the source listing.  The default listing does not
156include the disassembly.  If the source code is not available, show a listing
157of the disassembly only.
158See the @samp{NOTES} section for the definition of @var{item} and @var{tag}.
159
160@item -outfile @var{filename}
161@ifclear man
162@IndexSubentry{Options,  @code{-outfile}}
163@IndexSubentry{Commands, @code{outfile}}
164@end ifclear
165Write results to file @var{filename}.  A dash (@minus{}) writes to stdout.
166This is also the default.  Note that this option only affects those options
167included to the right of the option.
168
169@end table
170
171@c man end
172@ManPageEnd{}
173
174@c ----------------------------------------------------------------------------
175@c NOTES section
176@c ----------------------------------------------------------------------------
177
178@ManPageStart{NOTES}
179@c man begin NOTES
180
181Use @var{item} to specify the name of a function, or of a source or object
182file that was used to build the executable, or shared object.
183
184The @var{tag} is an index used to determine which item is being referred
185to when multiple functions have the same name.  It is required, but will
186be ignored if not necessary to resolve the function.
187
188The @var{item} may also be specified in the form @samp{function`file`}, in
189which case the source or disassembly of the named function in the source
190context of the named file will be used.
191
192The special @var{item} and @var{tag} combination @samp{all -1}, is used to
193indicate generating the source, or disassembly, for all functions in the
194@var{target-file}.
195
196@c man end
197@ManPageEnd{}
198
199@c ----------------------------------------------------------------------------
200@c SEEALSO section
201@c ----------------------------------------------------------------------------
202
203@ManPageStart{SEE ALSO}
204@c man begin SEEALSO
205
206gprofng(1),
207gp-archive(1),
208gp-collect-app(1),
209gp-display-gui(1),
210gp-display-html(1),
211gp-display-text(1)
212
213@iftex
214@vspace{1}
215@end iftex
216
217The user guide for gprofng is maintained as a Texinfo manual.  If the info
218and gprofng programs are correctly installed, the command
219@command{info gprofng} should give access to this document.
220
221@c man end
222@ManPageEnd{}
223
224@c ----------------------------------------------------------------------------
225@c COPYRIGHT section
226@c ----------------------------------------------------------------------------
227
228@ManPageStart{COPYRIGHT}
229@c man begin COPYRIGHT
230
231Copyright @copyright{} 2022-2024 Free Software Foundation, Inc.
232
233Permission is granted to copy, distribute and/or modify this document
234under the terms of the GNU Free Documentation License, Version 1.3
235or any later version published by the Free Software Foundation;
236with no Invariant Sections, with no Front-Cover Texts, and with no
237Back-Cover Texts.  A copy of the license is included in the
238section entitled ``GNU Free Documentation License''.
239
240@c man end
241@ManPageEnd{}
242
243@c ----------------------------------------------------------------------------
244@c If this text is used for a man page, exit.  Otherwise we need to continue.
245@c ----------------------------------------------------------------------------
246
247@ifset man
248@bye
249@end ifset
250