1@c ---------------------------------------------------------------------------- 2@c This is the Texinfo source file for the gprofng man page. 3@c 4@c Author: Ruud van der Pas 5@c ---------------------------------------------------------------------------- 6@ifset man 7\input texinfo @c -*-texinfo-*- 8@setfilename gprofng 9@settitle The next generation GNU application profiling tool 10@include gp-macros.texi 11@end ifset 12 13@c @ManPageStart{NAME} 14@c @ManPageStart{SYNOPSIS} 15@c @ManPageStart{DESCRIPTION} 16@c @ManPageStart{OPTIONS} 17@c @ManPageStart{NOTES} 18@c @ManPageStart{SEEALSO} 19@c @ManPageStart{COPYRIGHT} 20 21@c ---------------------------------------------------------------------------- 22@c This is from the man-pages(7) man page 23@c 24@c "The list below shows conventional or suggested sections. Most manual pages 25@c should include at least the highlighted sections. Arrange a new manual 26@c page so that sections are placed in the order shown in the list." 27@c 28@c NAME 29@c SYNOPSIS 30@c CONFIGURATION [Normally only in Section 4] 31@c DESCRIPTION 32@c OPTIONS [Normally only in Sections 1, 8] 33@c EXIT STATUS [Normally only in Sections 1, 8] 34@c RETURN VALUE [Normally only in Sections 2, 3] 35@c ERRORS [Typically only in Sections 2, 3] 36@c ENVIRONMENT 37@c FILES 38@c VERSIONS [Normally only in Sections 2, 3] 39@c ATTRIBUTES [Normally only in Sections 2, 3] 40@c CONFORMING TO 41@c NOTES 42@c BUGS 43@c EXAMPLES 44@c AUTHORS [Discouraged] 45@c REPORTING BUGS [Not used in man-pages] 46@c COPYRIGHT [Not used in man-pages] 47@c SEE ALSO 48@c 49@c This is what the texi2pod.pl tool recognizes: 50@c 51@c for $sect (qw(NAME SYNOPSIS TARGET DESCRIPTION OPTIONS ENVIRONMENT FILES 52@c BUGS NOTES FOOTNOTES SEEALSO AUTHOR COPYRIGHT)) { 53@c 54@c What is interesting is that it places "SEE ALSO" before "COPYRIGHT", which 55@c makes sense and adhered to for the other formats. 56@c ---------------------------------------------------------------------------- 57 58@c ---------------------------------------------------------------------------- 59@c NAME section 60@c ---------------------------------------------------------------------------- 61 62@ManPageStart{NAME} 63@c man begin NAME 64 65gprofng - The driver for the gprofng application profiling tool 66 67@c man end 68@ManPageEnd{} 69 70@c ---------------------------------------------------------------------------- 71@c SYNOPSIS section 72@c ---------------------------------------------------------------------------- 73 74@ManPageStart{SYNOPSIS} 75@c man begin SYNOPSIS 76 77@command{gprofng} [@var{option(s)}] @var{action} [@var{qualifier}] 78[@var{option(s)}] @var{target} [@var{options}] 79 80@c man end 81@ManPageEnd{} 82 83@c ---------------------------------------------------------------------------- 84@c DESCRIPTION section 85@c ---------------------------------------------------------------------------- 86 87@ManPageStart{DESCRIPTION} 88@c man begin DESCRIPTION 89 90This is the driver for the gprofng tools suite to gather and analyze 91performance data. 92 93The driver executes the @var{action} specified. An example of an action is 94@samp{collect} to collect performance data. Depending on the action, a 95@var{qualifier} may be needed to further define the command. 96The last item is the @var{target} that the command applies to. 97 98There are three places where options are supported. The driver supports 99options. These can be found below. The @var{action}, possibly in combination 100with the @var{qualifier} also supports options. A description of these can be 101found in the man page for the command. Any options needed to execute the 102target command should follow the target name. 103 104For example, to collect performance data for an application called 105@command{a.out} and store the results in experiment directory @samp{mydata.er}, 106the following command may be used: 107 108@smallexample 109$ gprofng collect app -o mydata.er a.out -t 2 110@end smallexample 111 112In this example, the action is @samp{collect}, the qualifier is @samp{app}, 113the single argument to the command is @code{-o mydata.er} and the target is 114@command{a.out}. The target command is invoked with the @samp{-t 2} option. 115 116If gprofng is executed without any additional option, action, or target, a 117usage overview is printed. 118 119@c man end 120@ManPageEnd{} 121 122@c ---------------------------------------------------------------------------- 123@c OPTIONS section 124@c ---------------------------------------------------------------------------- 125 126@ManPageStart{OPTIONS} 127@c man begin OPTIONS 128 129@table @gcctabopt 130 131@item @var{--version} 132@ifclear man 133@IndexSubentry{Options, @code{--version}} 134@end ifclear 135Print the version number and exit. 136 137@item @var{--help} 138@ifclear man 139@IndexSubentry{Options, @code{--help}} 140@end ifclear 141Print usage information and exit. 142 143@end table 144 145@c man end 146@ManPageEnd{} 147 148@c ---------------------------------------------------------------------------- 149@c ENVIRONMENT SECTION 150@c ---------------------------------------------------------------------------- 151 152@ManPageStart{ENVIRONMENT} 153@c man begin ENVIRONMENT 154 155The following environment variables are supported: 156 157@table @samp 158 159@item @env{GPROFNG_MAX_CALL_STACK_DEPTH} 160 161@ifclear man 162@cindex Environment variables 163@end ifclear 164 165Set the depth of the call stack (default is 256). 166 167@item @env{GPROFNG_USE_JAVA_OPTIONS} 168 169@ifclear man 170@cindex Environment variables 171@end ifclear 172 173May be set when profiling a C/C++ application that uses dlopen() to execute 174Java code. 175 176@c -- deferred @item @env{GPROFNG_SSH_REMOTE_DISPLAY} 177@c -- deferred Use this variable to define the ssh command executed by the 178@c -- remote display tool. 179 180@c -- deferred @item @env{GPROFNG_SKIP_VALIDATION} 181@c -- deferred Set this variable to disable checking hardware, system, and 182@c -- Java versions. 183 184@item @env{GPROFNG_ALLOW_CORE_DUMP} 185 186@ifclear man 187@cindex Environment variables 188@end ifclear 189 190Set this variable to allow a core file to be generated; otherwise an error 191report is created on @samp{/tmp}. 192 193@item @env{GPROFNG_ARCHIVE} 194 195@ifclear man 196@cindex Environment variables 197@end ifclear 198 199Use this variable to define the settings for automatic archiving upon 200experiment recording completion. 201 202@item @env{GPROFNG_ARCHIVE_COMMON_DIR} 203 204@ifclear man 205@cindex Environment variables 206@end ifclear 207 208Set this variable to the location of the common archive. 209 210@item @env{GPROFNG_JAVA_MAX_CALL_STACK_DEPTH} 211 212@ifclear man 213@cindex Environment variables 214@end ifclear 215 216Set the depth of the Java call stack; the default is 256; set to 0 to disable 217capturing of call stacks. 218 219@item @env{GPROFNG_JAVA_NATIVE_MAX_CALL_STACK_DEPTH} 220 221@ifclear man 222@cindex Environment variables 223@end ifclear 224 225Set the depth of the Java native call stack; the default is 256; set to 0 to 226disable capturing of call stacks (JNI and assembly call stacks are not 227captured). 228 229@item @env{GPROFNG_SYSCONFDIR} 230 231@ifclear man 232@cindex Environment variables 233@end ifclear 234 235Set the path to the @file{gprofng.rc} configuration file. By default, this 236file is placed in the @file{etc} subdirectory of the binutils installation 237directory. In case an RPM has been used for the installation, this file is 238in directory @file{/etc}. 239 240When building and installing from the source, the user can set the path 241to this configuration file to a non-default location. If this is the case, 242the user may set the @code{GPROFNG_SYSCONFDIR} environment variable to point 243to this location. 244 245Otherwise, the @command{gp-display-text}, @command{gp-display-src}, and 246@command{gp-archive} tools cannot find this file. 247 248@end table 249 250@c man end 251@ManPageEnd{} 252 253@c ---------------------------------------------------------------------------- 254@c NOTES section 255@c ---------------------------------------------------------------------------- 256 257@ManPageStart{NOTES} 258@c man begin NOTES 259 260The gprofng driver supports the following commands. 261 262@iftex 263@vspace{1} 264@end iftex 265 266@c The man pages for the commands below can be viewed using the command name 267@c with "gprofng" replaced by "gp" and the spaces replaced by a dash ("-"). 268@c For example the man page name for "gprofng collect app" is "gp-collect-app". 269 270@i{Collect performance data:} 271 272@table @code 273 274@item gprofng collect app 275Collect application performance data. 276 277@end table 278 279@i{Display the performance results:} 280 281@table @code 282 283@item gprofng display text 284Display the performance data in ASCII format. 285 286@item gprofng display html 287Generate an HTML file from one or more experiments. 288 289@item gprofng display gui 290Start the GUI. Note that this tool is not available by default and needs to 291be installed seperately. 292 293@end table 294 295@i{Miscellaneous commands:} 296 297@table @code 298 299@item gprofng display src 300Display source or disassembly with compiler annotations. 301 302@item gprofng archive 303Include binaries and source code in an experiment directory. 304 305@end table 306 307It is also possible to invoke the lower level commands directly, but since 308these are subject to change, in particular the options, we recommend to 309use the driver. 310 311@c man end 312@ManPageEnd{} 313 314@c ---------------------------------------------------------------------------- 315@c SEEALSO section 316@c ---------------------------------------------------------------------------- 317 318@ManPageStart{SEE ALSO} 319@c man begin SEEALSO 320 321gp-archive(1), 322gp-collect-app(1), 323gp-display-gui(1), 324gp-display-html(1), 325gp-display-src(1), 326gp-display-text(1) 327 328@iftex 329@vspace{1} 330@end iftex 331 332Each gprofng command also supports the @option{--help} option. This lists the 333options and a short description for each option. 334 335For example this displays the options supported on the 336@command{gprofng collect app} command: 337 338@smallexample 339$ gprofng collect app --help 340@end smallexample 341 342The user guide for gprofng is maintained as a Texinfo manual. If the 343@command{info} and @command{gprofng} programs are correctly installed, the 344command @command{info gprofng} should give access to this document. 345 346@c man end 347@ManPageEnd{} 348 349@c ---------------------------------------------------------------------------- 350@c COPYRIGHT section 351@c ---------------------------------------------------------------------------- 352 353@ManPageStart{COPYRIGHT} 354@c man begin COPYRIGHT 355 356Copyright @copyright{} 2022-2024 Free Software Foundation, Inc. 357 358Permission is granted to copy, distribute and/or modify this document 359under the terms of the GNU Free Documentation License, Version 1.3 360or any later version published by the Free Software Foundation; 361with no Invariant Sections, with no Front-Cover Texts, and with no 362Back-Cover Texts. A copy of the license is included in the 363section entitled ``GNU Free Documentation License''. 364 365@c man end 366@ManPageEnd{} 367 368@c ---------------------------------------------------------------------------- 369@c If this text is used for a man page, exit. Otherwise we need to continue. 370@c ---------------------------------------------------------------------------- 371 372@ifset man 373@bye 374@end ifset 375