Operation and Use, Volume 2

Starting Xprofiler

You start Xprofiler by issuing the xprofiler command from the AIX command line. You also need to specify the executable, profile data file(s), and options, which you can do one of two ways. You can either specify them on the command line, with the xprofiler command, or you can issue the xprofiler command alone, then specify them from within the GUI. See Loading files from the Xprofiler GUI.

Under some circumstances you may have multiple profile data files (gmon.out files). You will have more than one of these files if you are profiling a parallel application, because a gmon.out file is created for each task in the application when it is run. If you are running a serial application, there may be times when you want to summarize the profiling results from multiple runs of the application. In these cases, you will need to specify each of the profile data files you want to profile with Xprofiler.

To start Xprofiler and specify the executable, profile data file(s), and options:

ENTER: xprofiler a.out gmon.out... [options]
where a.out is the binary executable file, gmon.out is the name of your profile data file(s), and options may be one or more of the options listed in Xprofiler command line options.

To print basic Xprofiler command syntax to the screen, use the -h or -? option with the xprofiler command from the command line. For example, xprofiler -h.

Xprofiler command line options

You can specify the same command line options with the xprofiler command that you do with gprof, plus one additional option (-disp_max), which is specific to Xprofiler. The command line options let you control the way Xprofiler displays the profiled output.

When you enter an option, there must be a space between the option and its corresponding value. For example,

-e main

You can specify the following options from either the Xprofiler GUI or the command line. See Specifying command line options (from the GUI) for more information.

The Xprofiler command line options are:

Table 5. Xprofiler Command Line Options

Use this flag:	To:	For example:
-b	Suppresses the printing of the field descriptions for the Flat Profile, Call Graph Profile, and Function Index reports when they are written to a file with the Save As option of the File menu.	To suppress printing of the field descriptions for the Flat Profile, Call Graph Profile, and Function Index reports in the saved file: file, ENTER xprofiler -b a.out gmon.out
-s	If multiple gmon.out files are specified when Xprofiler is started, produces the gmon.sum profile data file. The gmon.sum file represents the sum of the profile information in all the specified profile files. Note that if you specify a single gmon.out file, the gmon.sum file contains the same data as the gmon.out file.	To write the sum of the data from three profile data files, gmon.out.1, gmon.out.2, and gmon.out.3, into a file called gmon.sum: ENTER xprofiler -s a.out gmon.out.1 gmon.out.2 gmon.out.3
-z	Includes functions that have both zero CPU usage and no call counts in the Flat Profile, Call Graph Profile, and Function Index reports. A function will not have a call count if the file that contains its definition was not compiled with the -pg option, which is common with system library files.	To include all functions used by the application, in the Flat Profile, Call Graph Profile, and Function Index reports, that have zero CPU usage and no call counts: ENTER xprofiler -z a.out gmon.out
-a	Adds alternative paths to search for source code and library files, or changes the current path search order. When using this command line option, you can use the "at" symbol (@) to represent the default file path, in order to specify that other paths be searched before the default path.	To set the alternative file search path(s) so that Xprofiler searches pathA, the default path, then pathB: ENTER xprofiler -a pathA:@:pathB
-c	Loads the specified configuration file. If the -c option is used on the command line, the configuration file name specified with it will appear in the Configuration File (-c): text field in the Load Files Dialog, and the Selection field of the Load Configuration File Dialog. When both the -c and -disp_max options are specified on the command line, the -disp_max option is ignored, but the value that was specified with it will appear in the Initial Display (-disp_max): field in the Load Files Dialog, the next time it is opened.	To load the configuration file: ENTER xprofiler a.out gmon.out -c config_file_name
-disp_max	Sets the number of function boxes that Xprofiler initially displays in the function call tree. The value supplied with this flag can be any integer between 0 and 5,000. Xprofiler displays the function boxes for the most CPU-intensive functions through the number you specify. For instance, if you specify 50, Xprofiler displays the function boxes for the 50 functions in your program that consume the most CPU. After this, you can change the number of function boxes that are displayed via the Filter menu options. This flag has no effect on the content of any of the Xprofiler reports.	To display the function boxes for only 50 most CPU-intensive functions in the function call tree: ENTER xprofiler -disp_max 50 a.out gmon.out
-e	De-emphasizes the general appearance of the function box(es) for the specified function(s) in the function call tree, and limits the number of entries for these function in the Call Graph Profile report. This also applies to the specified function's descendants, as long as they have not been called by non-specified functions. In the function call tree, the function box(es) for the specified function(s) appears greyed-out. Its size and the content of the label remain the same. This also applies to descendant functions, as long as they have not been called by non-specified functions. In the Call Graph Profile report, an entry for the specified function only appears where it is a child of another function, or as a parent of a function that also has at least one non-specified function as its parent. The information for this entry remains unchanged. Entries for descendants of the specified function do not appear unless they have been called by at least one non-specified function in the program.	To deemphasize the appearance of the function boxes for foo and bar, as well as their qualifying descendants in the function call tree, and limit their entries in the Call Graph Profile report: ENTER xprofiler -e foo -e bar a.out gmon.out
-E	Changes the general appearance and label information of the function box(es) for the specified function(s) in the function call tree. Also limits the number of entries for these functions in the Call Graph Profile report, and changes the CPU data associated with them. These results also apply to the specified function's descendants, as long as they have not been called by non-specified functions in the program. In the function call tree, the function box for the specified function appears greyed-out, and its size and shape also changes so that it appears as a square of the smallest allowable size. In addition, the CPU time shown in the function box label, appears as 0 (zero). The same applies to function boxes for descendant functions, as long as they have not been called by non-specified functions. This option also causes the CPU time spent by the specified function to be deducted from the left side CPU total in the label of the function box for each of the specified function's ancestors. In the Call Graph Profile report, an entry for the specified function only appears where it is a child of another function, or as a parent of a function that also has at least one non-specified function as its parent. When this is the case, the time in the self and descendants columns for this entry is set to 0 (zero). In addition, the amount of time that was in the descendants column for the specified function is subtracted from the time listed under the descendants column for the profiled function. As a result, be aware that the value listed in the % time column for most profiled functions in this report will change.	To change the display and label information for foo and bar, as well as their qualifying descendants in the function call tree, and limit their entries and data in the Call Graph Profile report: ENTER xprofiler -E foo -E bar a.out gmon.out
-f	De-emphasizes the general appearance of all function boxes in the function call tree, except for that of the specified function(s) and its descendant(s). In addition, the number of entries in the Call Graph Profile report for the non-specified functions and non-descendant functions is limited. The -f flag overrides the -e flag. In the function call tree, all function boxes except for that of the specified function(s) and its descendant(s) appear greyed-out. The size of these boxes and the content of their labels remain the same. For the specified function(s), and its descendant(s), the appearance of the function boxes and labels remain the same. In the Call Graph Profile report, an entry for a non-specified or non-descendant function only appears where it is a parent or child of a specified function or one of its descendants. All information for this entry remains the same.	To de-emphasize the display of function boxes for all functions in the function call tree except for foo, bar, and their descendants, and limit their types if entries in the Call Graph Profile report: ENTER xprofiler -f foo -f bar a.out gmon.out
-F	Changes the general appearance and label information of all function boxes in the function call tree except for that of the specified function(s) and its descendants. In addition, the number of entries in the Call Graph Profile report for the non-specified and non-descendant functions is limited, and the CPU data associated with them is changed. The -F flag overrides the -E flag. In the function call tree, all function boxes except for that of the specified function(s) and its descendant(s) appear greyed-out. The size and shape of these boxes also changes so that they appear as squares of the smallest allowable size. In addition, the CPU time shown in the function box label, appears as 0 (zero). In the Call Graph Profile report, an entry for a non-specified or non-descendant function only appears where it is a parent or child of a specified function or one of its descendants. When this is the case, the time in the self and descendants columns for this entry is set to 0 (zero). As a result, be aware that the value listed in the % time column for most profiled functions in this report will change.	To change the display and label information of the function boxes for all functions except the functions foo and bar and their descendants, and limit their types of entries and data in the Call Graph Profile: ENTER xprofiler -F foo -F bar a.out gmon.out
-L	Sets the pathname for locating shared libraries. If you plan to specify multiple paths, use the Set File Search Path option of the File menu on the Xprofiler GUI. See Setting the file search sequence for information.	To specify /lib/profiled/libc.a:shr.o as an alternate pathname for your shared libraries: ENTER xprofiler -L /lib/profiled/libc.a:shr.o

After you issue the xprofiler command, the Xprofiler main window appears, and displays your application's data.

Loading files from the Xprofiler GUI

If you issue the xprofiler command without specifying an executable file, a profile data file, or options, you may do so from within the Xprofiler GUI. You use the Load File option of the File menu to do this.

When you issue the xprofiler command alone, the Xprofiler main window appears. Since you did not load an executable or specify a profile data file, the window will be empty.

If you issue the xprofiler command with the -h option only, Xprofiler displays the syntax for the command and then exits.

Figure 2. Xprofiler Main Window with No Executables Loaded

View figure.

Select the File menu, and then the Load File option. The Load Files Dialog window appears.

Figure 3. Load Files Dialog Window

View figure.

The Load Files Dialog window lets you specify your application's executable, and its corresponding profile data (gmon.out) files. When you load a file, you can also specify the various command line options that let you control the way Xprofiler displays the profiled data.

To load the files for the application you wish to profile, you need to specify the:

Binary Executable (required)
Profile Data File(s) (required)
Command Line Options (optional)

Specifying the binary executable

You specify the binary executable from the Binary Executable File of the Load Files Dialog window. The Binary Executable File area looks similar to this:

Figure 4. Binary Executable File Area

View figure.

Use the scroll bars of the Directories and Files selection boxes to locate the executable file you wish to load. By default, all the files in the directory from which you invoked Xprofiler appear in the Files selection box. To select a file, click on it with the left mouse button.

To make locating your binary executable files easier, the Binary Executable File area includes a Filter button. Filtering lets you limit the files that are displayed in the Files selection box to those of a specific directory or of a specific type. For information on using the Filter, see Using the dialog window filters.

Specifying the profile data file(s)

You specify the profile data file(s) from the gmon.out Profile Data File(s) area of the Load Files Dialog window. The gmon.out Profile Data File(s) area looks similar to this:

Figure 5. gmon.out Profile Data File(s) Area

View figure.

When you started Xprofiler, with the xprofiler command, you were not required to indicate the name of the profile data file (which is probably why you are specifying it from the GUI). If you did not specify a profile data file, Xprofiler searches your directory for the presence of a file named gmon.out and, if found, places it in the Selection field of the gmon.out Profile File(s) area, as the default. Xprofiler then uses this file as input, even if it is not related to the binary executable file you specify. Since this will cause Xprofiler to display incorrect data, it is important that you enter the correct file into this field. So, if the profile data file you wish to use is named something other than what appears in the Selection field, you must replace it with the correct file name, as follows.

Use the scroll bars of the Directories and Files selection boxes to locate one or more of the profile data (gmon.out) files you wish to specify. The file you use does not have to be named gmon.out, and you may specify more than one profile data file. To select a file, click on it with the left mouse button. You can select multiple files by holding down the <Ctrl> key and clicking on each one with the left mouse button. To select multiple consecutive files, press and hold the left mouse button over the first file, and then drag the mouse over the other files. To de-select a file, press and hold the <Ctrl> key while clicking on the file.

To make locating your output files easier, the gmon.out Profile File(s) area includes a Filter button. Filtering lets you limit the files that get displayed in the Files selection box to those in a specific directory or of a specific type. For information on using the Filter, see Using the dialog window filters.

Specifying command line options (from the GUI)

You specify command line options from the Command Line Options area of the Load Files Dialog window. The Command Line Options area looks similar to this:

Figure 6. Command Line Options Area

View figure.

You may specify one or more options as follows:

Table 6. Xprofiler GUI Command Line Options

Use this flag:	To:	For example:
-b (button)	Suppresses the printing of the field descriptions for the Flat Profile, Call Graph Profile, and Function Index reports when they are written to a file with the Save As option of the File menu.	To suppress printing of the field descriptions for the Flat Profile, Call Graph Profile, and Function Index reports in the saved file, set the -b button to the pressed-in position.
-s (button)	If multiple gmon.out files are specified in the gmon.out Profile File(s) area, produces the gmon.sum profile data file. The gmon.sum file represents the sum of the profile information in all the specified profile files. Note that if you specify a single gmon.out file, the gmon.sum file contains the same data as the gmon.out file.	To write the sum of the data from three profile data files, gmon.out.1, gmon.out.2, and gmon.out.3, into a file called gmon.sum, set the -s button to the pressed-in position to activate this option.
-z (button)	Includes functions that have both zero CPU usage and no call counts in the Flat Profile, Call Graph Profile, and Function Index reports. A function will not have a call count if the file that contains its definition was not compiled with the -pg option, which is common with system library files.	To include all functions used by the application, in the Flat Profile, Call Graph Profile, and Function Index reports, that have zero CPU usage and no call counts, set the -z button to the pressed-in position to activate this option.
-a (field)	Adds alternative paths to search for source code and library files, or changes the current path search order. After clicking on the OK button, any modifications to this field are also made to the Enter Alt File Search Paths: field of the Alt File Search Path Dialog window. If both the Load Files Dialog window and the Alt File Search Path Dialog window are opened at the same time, when you make path changes in the Alt File Search Path Dialog and click the OK button, these changes are also made to the Load Files Dialog window. Also, when both of these windows are open concurrently, clicking on the OK or Cancel buttons in the Load Files Dialog causes both windows to close. If you wish to restore the Alt File Search Path(s) (-a): field to the same state as when the Load Files Dialog window was opened, click on the Reset button. You can use the "at" symbol (@) with this option to represent the default file path, in order to specify that other paths be searched before the default path.	To set the alternative file search path(s) so that Xprofiler searches pathA, the default path, then pathB, type pathA:@:pathB in the Alt File Search Path(s) (-a) field.
-c (field)	Loads the specified configuration file. If the -c option was used on the command line, or a configuration file had been previously loaded with the Load Files Dialog or Load Configuration File Dialog windows, the name of the most recently loaded file will appear in the Configuration File (-c): text field in the Load Files Dialog, as well as the Selection field of the Load Configuration File Dialog. If both the Load Files Dialog and Load Configuration File Dialog windows are open at the same time, when you specify a configuration file in the Load Configuration File Dialog and then click the OK button, the name of the specified file also appears in the Load Files Dialog. Also, when both of these windows are open concurrently, clicking on the OK or Cancel buttons in the Load Files Dialog causes both windows to close. When entries are made to both the Configuration File (-c): and Initial Display (-disp_max): fields in the Load Files Dialog, the value in the Initial Display (-disp_max): field is ignored, but is retained the next time this window is opened. If you wish to retrieve the file name that was in the Configuration File (-c): field when the Load Files Dialog window was opened, click on the Reset button.	To load the configuration file, type gmon.out in the Configuration File (-c) field.
-disp_max (field)	Sets the number of function boxes that Xprofiler initially displays in the function call tree. The value supplied with this flag can be any integer between 0 and 5,000. Xprofiler displays the function boxes for the most CPU-intensive functions through the number you specify. For instance, if you specify 50, Xprofiler displays the function boxes for the 50 functions in your program that consume the most CPU. After this, you can change the number of function boxes that are displayed via the Filter menu options. This flag has no effect on the content of any of the Xprofiler reports.	To display the function boxes for only 50 most CPU-intensive functions in the function call tree, type 50 in the Init Display (-disp_max) field
-e (field)	De-emphasizes the general appearance of the function box(es) for the specified function(s) in the function call tree, and limits the number of entries for these function in the Call Graph Profile report. This also applies to the specified function's descendants, as long as they have not been called by non-specified functions. In the function call tree, the function box(es) for the specified function(s) appears greyed-out. Its size and the content of the label remain the same. This also applies to descendant functions, as long as they have not been called by non-specified functions. In the Call Graph Profile report, an entry for the specified function only appears where it is a child of another function, or as a parent of a function that also has at least one non-specified function as its parent. The information for this entry remains unchanged. Entries for descendants of the specified function do not appear unless they have been called by at least one non-specified function in the program.	To de-emphasize the appearance of the function boxes for foo and bar, as well as their qualifying descendants in the function call tree, and limit their entries in the Call Graph Profile report, type foo and bar in the Exclude Routines (-e) field. You specify multiple functions by separating each one with a space.
-E (field)	Changes the general appearance and label information of the function box(es) for the specified function(s) in the function call tree. Also limits the number of entries for these functions in the Call Graph Profile report, and changes the CPU data associated with them. These results also apply to the specified function's descendants, as long as they have not been called by non-specified functions in the program. In the function call tree, the function box for the specified function appears greyed-out, and its size and shape also changes so that it appears as a square of the smallest allowable size. In addition, the CPU time shown in the function box label, appears as 0 (zero). The same applies to function boxes for descendant functions, as long as they have not been called by non-specified functions. This option also causes the CPU time spent by the specified function to be deducted from the left side CPU total in the label of the function box for each of the specified function's ancestors. In the Call Graph Profile report, an entry for the specified function only appears where it is a child of another function, or as a parent of a function that also has at least one non-specified function as its parent. When this is the case, the time in the self and descendants columns for this entry is set to 0 (zero). In addition, the amount of time that was in the descendants column for the specified function is subtracted from the time listed under the descendants column for the profiled function. As a result, be aware that the value listed in the % time column for most profiled functions in this report will change.	To change the display and label information for foo and bar, as well as their qualifying descendants in the function call tree, and limit their entries and data in the Call Graph Profile report, type foo and bar in the Exclude Routines (-E) field. You specify multiple functions by separating each one with a space.
-f (field)	De-emphasizes the general appearance of all function boxes in the function call tree, except for that of the specified function(s) and its descendant(s). In addition, the number of entries in the Call Graph Profile report for the non-specified functions and non-descendant functions is limited. The -f flag overrides the -e flag. In the function call tree, all function boxes except for that of the specified function(s) and its descendant(s) appear greyed-out. The size of these boxes and the content of their labels remain the same. For the specified function(s), and its descendants, the appearance of the function boxes and labels remain the same. In the Call Graph Profile report, an entry for a non-specified or non-descendant function only appears where it is a parent or child of a specified function or one of its descendants. All information for this entry remains the same.	To de-emphasize the display of function boxes for all functions in the function call tree except for foo, bar, and their descendants, and limit their types if entries in the Call Graph Profile report, type foo and bar in the Include Routines (-f) field. You specify multiple functions by separating each one with a space.
-F (field)	Changes the general appearance and label information of all function boxes in the function call tree except for that of the specified function(s) and its descendants. In addition, the number of entries in the Call Graph Profile report for the non-specified and non-descendant functions is limited, and the CPU data associated with them is changed. The -F flag overrides the -E flag. In the function call tree, all function boxes except for that of the specified function(s) and its descendant(s) appear greyed-out. The size and shape of these boxes changes so that they appear as squares of the smallest allowable size. In addition, the CPU time shown in the function box label, appears as 0 (zero). In the Call Graph Profile report, an entry for a non-specified or non-descendant function only appears where it is a parent or child of a specified function or one of its descendants. When this is the case, the time in the self and descendants columns for this entry is set to 0 (zero). As a result, be aware that the value listed in the % time column for most profiled functions in this report will change.	To change the display and label information of the function boxes for all functions except the functions foo and bar and their descendants, and limit their types of entries and data in the Call Graph Profile, type foo and bar in the Include Routines (-F) field. You specify multiple functions by separating each one with a space.
-L (field)	Sets the alternate pathname for locating shared objects. If you plan to specify multiple paths, use the Set File Search Path option of the File menu on the Xprofiler GUI. See Setting the file search sequence for information.	Type the alternate library pathname in this field.

Once you have specified the binary executable, the profile data file, and any command line options you wish to use, press the OK button to save the changes and close the dialog window. Xprofiler loads your application and displays its performance data.

Setting the file search sequence

You can specify where you want Xprofiler to look for your library files and source code files by using the Set File Search Paths option of the File menu. By default, Xprofiler searches the default paths first and then any alternative paths you specify.

Default paths

For library files, Xprofiler uses the paths recorded in the specified gmon.out file(s). If you use the -L command line option, the path you specify with this option will be used instead of those in the gmon.out file.

Note:: -L allows only one path to be specified and you can use this option only once.

For source code files, the paths recorded in the specified a.out file are used.

Alternative paths

These are the paths you specify with the Set File Search Paths option of the File menu.

For library files, if everything else failed, the search will be extended to the path(s) specified by the LIBPATH environment variable associated with the executable.

To specify alternative path(s), do the following:

Select the File menu, and then the Set File Search Paths option. The Alt File Search Path Dialog window appears.
Enter the name of the path in the Enter Alt File Search Path(s) text field. You can specify more than one path by separating each with colon (:) or a space.
Notes:
1. You can use the "at" symbol (@) with this option to represent the default file path, in order to specify that other paths be searched before the default path. For example, to set the alternative file search path(s) so that Xprofiler searches pathA, the default path, then pathB, type pathA:@:pathB in the Alt File Search Path(s) (-a) field.
2. If @ is used in the alternative search path, the two buttons in the Alt File Search Path Dialog will be greyed out, and have no effect on the search order.
Click on the OK button. The paths you specified in the text field become the alternative paths.

Changing the search sequence

You can change the order of the search sequence for library files and source code files via the Set File Search Paths option of the File menu. To change the search sequence, do the following:

Select the File menu, and then the Set File Search Paths option. The Alt File Search Path Dialog window appears.
To indicate the file search should use alternative paths first, click on the Check alternative path(s) first button.
Click on the OK button. This changes the search sequence to the:
1. Alternative paths
2. Default paths
3. Path(s) specified in LIBPATH (library files only)

To return the search sequence back to its default order, repeat steps 1 through 3, but in step 2 above, click on the Check default path(s) first button. When the action is confirmed (by clicking on the OK button), the search sequence will start with the default paths again.

Keep in mind that if a file is found in one of the alternative paths or a path in LIBPATH, this path now becomes the default path for this file throughout the current Xprofiler session (until you exit this Xprofiler session or load a new set of data).

[ Top of Page | Previous Page | Next Page | Table of Contents | Index ]