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