LIST | NOLIST

Pragma equivalent

None.

Purpose

Produces a compiler listing file that includes a pseudo assembly listing.

Syntax

Defaults

NOLIST

In the z/OS® UNIX System Services environment, this option is turned on by specifying -V when using the c89, cc or c++ commands. -V produces all reports for the compiler, and binder, or prelinker, and directs them to stdout. To produce only the listing (and no other reports), and write the listing to a user-specified file, use the following command:

-Wc,"LIST(filename)"

Parameters

Sequential filename: Specifies the sequential data set file name for the compiler listing.
Partitioned data set: Specifies the partitioned data set for the compiler listing.
Partitioned data set (member): Specifies the partitioned data set (member) for the compiler listing.
z/OS UNIX System Services filename: Specifies the z/OS UNIX System Services file name for the compiler listing.
z/OS UNIX System Services directory: Specifies the z/OS UNIX System Services directory for the compiler listing.

Usage

When the LIST compiler option is in effect, the compiler is instructed to generate a listing of the machine instructions in the object module (in a format similar to assembler language instructions) in the compiler listing.

LIST(filename) places the compiler listing in the specified file. If you do not specify a file name for the LIST option, the compiler uses the SYSCPRT ddname if you allocated one. Otherwise, the compiler generates a file name as follows:

If you are compiling a data set, the compiler uses the source file name to form the name of the listing data set. The high-level qualifier is replaced with the userid under which the compiler is running, and .LIST is appended as the low-level qualifier.
If you are compiling a z/OS UNIX file, the compiler stores the listing in a file that has the name of the source file with a .lst extension. If you are linking with IPA and generating a z/OS UNIX executable, the name is instead based on the name of the executable.

The option -qlist= can be specified directly to indicate that no file name is specified. For example,

xlc -qlist= hello.c -c

is equivalent to

xlc -Wc,list() hello.c -c

When -qlist= is specified with -qipa, the listing file name will be based on the name of the output file. For example, if the output file name is a.out, the IPA listing file name will be a.out.lst.

The NOLIST option optionally takes a file name suboption. This file name then becomes the default. If you subsequently use the LIST option without a file name suboption, the compiler uses the file name that you specified in the earlier NOLIST. For example, the following specifications have the same effect:

c89 -Wc,"NOLIST(hello.list)" LIST

c89 -Wc,"LIST(hello.list)"

If you specify data set names in a C or C++ program, with the SOURCE, LIST or INLRPT options, all the listing sections are combined into the last data set name specified.

Notes:

Usage of information such as registers, pointers, data areas, and control blocks that are shown in the object listing are not programming interface information.
If you use the following form of the command in a JES3 batch environment where xxx is an unallocated data set, you may get undefined results.
```
LIST(xxx)
```
Statement line numbers exceeding 99999 will wrap back to 00000 for the generated assembly listing for the C/C++ source file. This may occur when the compiler LIST option is used.

IPA effects

If you specify the LIST option on the IPA compile step, the compiler saves information about the source file and line numbers in the IPA object file. This information is available during the IPA link step for use by the LIST or GONUMBER options.

If you do not specify the GONUMBER option on the IPA compile step, the object file produced contains the line number information for source files that contain function begin, function end, function call, and function return statements. This is the minimum line number information that the IPA compile step produces. You can then use the TEST option on the IPA link step to generate corresponding test hooks.

Refer to Interactions between compiler options and IPA suboptions and GONUMBER | NOGONUMBER for more information.

If you specify the LIST option, the IPA Link listing contains a Pseudo Assembly section for each partition that contains executable code. Data-only partitions do not generate a Pseudo Assembly listing section.

The source file and line number shown for each object code statement depend on the amount of detail the IPA compile step saves in the IPA object file, as follows:

If you specified the GONUMBER, LIST, IPA(GONUMBER), or IPA(LIST) option for the IPA compile step, the IPA link step accurately shows the source file and line number information.
If you did not specify any of these options on the IPA compile step, the source file and line number information in the IPA Link listing or GONUMBER tables consists only of the following:
- function entry, function exit, function call, and function call return source lines. This is the minimum line number information that the IPA compile step produces.
- All other object code statements have the file and line number of the function entry, function exit, function call, and function call return that was last encountered. This is similar to the situation of encountering source statements within a macro.

Predefined macros