Category
Listings, messages and compiler
information
Purpose
Produces a compiler listing file
that includes a pseudo assembly listing.
Syntax
.-NOLIS-.
>>-+-LIS---+---------------------------------------------------->
>--+-----------------------------------------------+-----------><
'-(--+-Sequential filename-----------------+--)-'
+-Partitioned data set----------------+
+-Partitioned data set (member)-------+
+-z/OS UNIX System Services filename--+
'-z/OS UNIX System Services directory-'
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.