ld — Link object files
Related information
Format
ld [–cVv]
[–b option[,option]…]…
[–e function]
[–f filename]…
[–L directory]…
[–l libname]…
[–O name[,name]…]
[–o outfile]
[–S syslibdset]…
[–u function]
[–x sidefile]
[file.o ] … [file.a ] … [file.x]… [–l libname] …
Description
The ld utility combines object files and archive files into an output executable file, resolving external references. ld runs the Program Management Binder.
To export the trace output to a z/OS UNIX file, use the _LD_DEBUG_TRACE environment variable.
Options
- -b option[,option]…
- Specifies options to be passed to the binder. For more information about the binder and its options, see z/OS MVS Program Management: User's Guide and Reference. Binder options that are not specified will take the binder default, except when other ld options affect binder options.
- –c
- Causes pseudo-JCL to be written to stdout without actually running
the binder. Pseudo-JCL provides information about exactly which binder
options are being passed, and also which data sets are being used.
Also see –v.
- -e function
- Specifies the name of the function to be used as the entry point
of the program.
The default value of the -e option is affected by the setting of environment variable _LD_ENTRY_POINT (see Environment Variables). If the -e option is not specified and _LD_ENTRY_POINT is null, or if function is null, the default rules of the binder will determine the entry point of the program. For more information about the binder and the ENTRY control statement, see z/OS MVS Program Management: User's Guide and Reference.
Also see -O.
- -f filename
- Specifies a file that contains a list of the names of object and archive files to be used as input. The listed files will be used in addition to any files specified as operands.
- -L directory
- Specifies the directories to be used to search for archive libraries that are specified by the -l operand. The directories are searched in the order specified, and then in the directories that are specified by the _LD_LIBDIRS environment variable or its default. You cannot specify an MVS™ data set as an archive library directory.
- -l libname
- Specifies the name of an archive library. ld searches
for the file lib libname.a in
the directories specified on the -L option
and then in the directories specified by the _LD_LIBDIRS environment
variable or its default. The first occurrence of the archive library
is used.
You can also specify an MVS data set; you must specify the full data set name, because there are no rules for searching library directories.
The data set specified must be a C370LIB object library or a load library. If a data set specified as a library has undefined (U) record format, then it is assumed to be a load library. For more information about the object library utility, see z/OS XL C/C++ User's Guidez/OS XL C/C++ User's Guide.
- -O name[, name]…
- Specifies the name of the code topic to be ordered to the beginning of the executable. The binder control statement order will be generated. The default value of -O can be provided by the environment variable _LD_ORDER (see Environment Variables).
- -o outfile
- Specifies the name of the executable file produced by ld. The default output file is a.out.
- -S syslibdset
- Specifies the name of a system library (SYSLIB) data set that will be used to resolve symbols.
- -u function
- Specifies the name of the function to be added to the list of external symbols to be resolved. This option can be useful if the only input is archive libraries. If this option is not specified, no external symbol is added.
- -V
- This verbose option produces binder listings and directs them to stdout.
- -v
- This verbose option causes pseudo-JCL to be written to stdout before the binder is run. It provides information about exactly which binder options are being passed, and also which data sets are being used.
- -X sidefile
- Specifies the name of a sidedeck file or data set that ld will write to when producing a DLL (dynamic link library).
Operands
- file.a
- Specifies the name of an archive file, as produced by the ar command, to be used by the binder for resolving external references. To specify an MVS data set name, precede the name with double slash (//), in which case the last qualifier of the data set name must be LIB. The data set specified must be a C370LIB object library or a load library. See the description of the –l libname operand for more information about using data sets as libraries.
- file.o
- Specifies the name of an object file, produced by the C/C++
run-time compiler
or assembler, to be link-edited.
To specify an MVS data set name to be link-edited, precede the file name with double slash (//), in which case the last qualifier of the data set name must be OBJ.
If a partitioned data set is specified, more than one member name can be specified by separating each with a comma. For example:ld //file.OBJ(mem1,mem2,mem3)
- file.x
- Specifies the name of a definition sidedeck produced by ld when
creating a DLL (dynamic link library), and used by ld when
linking an application using the DLL. See the description of side-deck
processing in z/OS MVS Program Management: User's Guide and Reference.
To specify an MVS data set name, precede the file name with double slash (//), in which case the last qualifier of the data set name must be EXP.
If a partitioned data set is specified, more than one member name can be specified by separating each with a comma. For example:ld //file.EXP(mem1,mem2,mem3)
Environment variables
You can use environment variables to specify necessary system and operational information to ld. When a particular environment variable is not set, ld uses the default shown. For information about the JCL parameters that are used in these environment variables, see z/OS MVS JCL User's Guide.
- _LD_ACCEPTABLE_RC
- The
maximum allowed return code (result) of the binder invocation. If
the result is between zero and this value (inclusive), then it is
treated internally by ld exactly as if it
were a zero result, except that message IEW5033 might be issued. For
more information about binder return codes, see z/OS MVS Program Management: User's Guide and Reference.
The default value is:
"4"
- _LD_ASUFFIX
- The
suffix by which ld recognizes an archive
file. This environment variable does not affect the treatment of archive libraries
specified as -l operands, which are always
prefixed with lib and suffixed with .a. The default value is:
"a"
- _LD_ASUFFIX_HOST
- The
suffix by which ld recognizes a library
data set. This environment variable does not affect the treatment
of data set libraries specified as -l operands,
which are always used exactly as specified. The default value is:
"LIB"
- _LD_DAMPLEVEL
- The
minimum severity level of dynamic allocation messages returned by
dynamic allocation message processing. Messages with severity greater
than or equal to this number are written to stderr. However, if the
number is out of the range shown here (that is, less than 0 or
greater than 8), thenld dynamic
allocation message processing is disabled. The default value is:
Following are the values:"4"
- 0
- Informational
- 1–4
- Warning
- 5–8
- Severe
- _LD_DAMPNAME
- The
name of the dynamic allocation message processing program called by ld.
It must be a member of a data set in the search order used for MVS programs. The default dynamic
allocation message processing program is described in z/OS MVS Programming: Authorized Assembler Services Guide.
The default value is:
"IEFDB476"
- _LD_DCBU
- The
DCB parameters used by ld for data sets
with the attributes of record format undefined and data set organization
partitioned. This DCB is used by ld for
the output file when it is to be written to a data set. The default
value is:
"(RECFM=U,LRECL=0,BLKSIZE=6144,DSORG=PO)"
- _LD_DCB80
- The
DCB parameters used by ld for data sets
with the attributes of record format fixed blocked and logical record
length 80. The default value is:
"(RECFM=FB,LRECL=80,BLKSIZE=5680)"
- _LD_DEBUG_DUMP
- The
name of a data set to be used for capturing diagnosis data during
execution of the binder. An unformatted dump is written to this data
set by the binder when it encounters a binder ABEND situation (usually accompanied
by message IEW2900W) or when the binder option DUMP is specified.
The data set must have been created before ld is invoked,
and must be created with RECFM=VBA and LRECL=125. If this environment
variable is null, the binder dump will not be captured. The default
value is
"" (null)
- _LD_DEBUG_TRACE
- The
name of a data set or UNIX file to be used for capturing diagnosis
data during the execution of the binder. An unformatted trace is written
to the data set or UNIX file, as applicable, by the binder. If the
variable begins with two leading slashes, it is a data set name. In
this case, this data set must have been created before ld was invoked,
and must be created with RECFM=VB and LRECL=84. If this environment
variable is null, the binder trace will not be captured. The default
value is
"" (null)
The trace output file can be a z/OS UNIX file. The binder writes the unformatted trace to the data set. If the file name does not have a leading slash, the file name is treated as a UNIX file name with relative directory. If the file name has a leading slash, it is treated as a UNIX file name with absolute directory.
- _LD_ENTRY_POINT
- The
value to be used as the -e option if -e is
not specified. The default value is
"" (null)
- _LD_EXTRA_SYMBOL
- The
value to be used as the -u option if -u is
not specified. The default value is
"" (null)
- _LD_LIBDIRS_
- The directories
that are used by ld as the default place
to search for archive libraries that are specified using the –l operand.
The default value is:
"/lib /usr/lib"
- _LD_ORDER
- The
value to be used as the -O option if -O is
not specified. The default value is
"" (null)
- _LD_NEW_DATACLAS
- The
DATACLAS parameter that is used by ld for
any new data sets it creates. The default value is
"" (null)
- _LD_NEW_DSNTYPE
- The
DSNTYPE parameter that is used by ld for
any new data sets it creates. The default value is
which means that new data sets are created as type PDSE."LIBRARY"
- _LD_NEW_MGMTCLAS
- The
MGMTCLAS parameter that is used by ld for
any new data sets it creates. The default value is
"" (null)
- _LD_NEW_SPACE
- The
SPACE parameter that is used by ld for any
new data sets it creates. The default value is
"" (null)
- _LD_NEW_STORCLAS
- The
STORCLAS parameter that is used by ld for
any new data sets it creates. The default value is
"" (null)
- _LD_NEW_UNIT
- The
UNIT parameter that is used by ld for any
new data sets it creates. The default value is
"" (null)
- _LD_OPERANDS
- These
operands are parsed as if they were specified after all other operands
on the ld command line. The default value is
"" (null)
- _LD_OPTIONS
- These
options are parsed as if they were specified after all other operands
on the ld command line. The default value is
"" (null)
- _LD_OSUFFIX
- The
suffix by which ld recognizes an object
file. The default value is
"o"
- _LD_OSUFFIX_HOST
- The
suffix by which ld recognizes an object
data set. The default value is
"OBJ"
- _LD_SYSLIB
- The
system library data set concatenation to be used to resolve symbols.
The default value is:
" " (null)
- _LD_SYSIX
- The
system definition sidedeck list to be used to resolve symbols. A definition sidedeck
contains link-editing phase IMPORT control statements naming symbols
that are exported by a DLL. The default value is
"" (null)
- _LD_XSUFFIX
- The
suffix by which ld recognizes a definition sidedeck
file of exported symbols. The default value is
"x"
- _LD_XSUFFIXHOST
- The
suffix by which ld recognizes a definition sidedeck
data set of exported symbols. The default value is
"EXP"
Usage notes
- Messages generated from the use of the ld command are provided in z/OS MVS System Messages, Vol 8 (IEF-IGD).
- ld provides similar function to the
link-edit step of the c89 command. It does
not provide any functions of the compile and assembly phases of c89,
nor any steps of the link-edit phase except for the link-edit step --ld merely
calls the program management binder. The other main difference is
that c89 has default settings that are designed
for linking an object file that is produced by the C/C++
run-time compiler
for execution in the Language Environment®, whereas the default settings of ld do
not include compiler or environment assumptions, and it can therefore
be more easily used to link objects from other compilers or that are
destined for environments other than Language Environment. You can use ld options, operands, or environment variables to cause ld to create executable modules that are compatible with those c89 produces by default:
Option or operand Environment variable Value for c89 compatibility -e _LD_ENTRY_POINT
or, for AMODE 64 code,CEESTART
CELQSTRT
-O _LD_ORDER
or, for AMODE 64 code,CEESTART
CELQSTRT
-S _LD_SYSLIB
or installation equivalent names//'CEE.SCEELKEX': //'CEE.SCEELKED': //'CBC.SCCNOBJ': //'SYS1.CSSLIB'
-u _LD_EXTRA_SYMBOL
or, for AMODE 64 code,CEEMAIN
CELQMAIN
file.a _LD_OPERANDS //CEE.SCEEOBJ
- When a data set name is specified, the argument must start with double-slash (//) followed by the data set name. If the name is enclosed in single quotation marks, it is assumed to be fully qualified and is taken as is. Otherwise, the user login name followed by a period is prefixed.
- To be able to specify an operand that begins with a dash (-), you must use the double dash (--) end-of-options delimiter.
- When ld is invoked from the shell, any option-arguments or operands specified that contain characters with special meaning to the shell must be escaped. For example, source files that are specified as PDS member names contain parentheses; and if they are specified as fully qualified names, they contain single quotation marks. To escape these special characters, either enclose the option-argument or operand in double quotation marks, or precede each character with a backslash.
- Options and arguments are processed in the order read (from left
to right). Where there are conflicts, the last specification is used.
If options that require arguments are specified more than once, the
last specification is used except as follows:
- -b
- Binder options are appended in the order they are specified
- -f
- Each file is processed when the -f option is encountered
- -L
- Library directories are appended in the order they are specified
- -l
- Libraries are searched when the -l option is encountered
- -S
- SYSLIB data sets are appended in the order they are specified
- Because archive library files are searched when their names are encountered, the placement of -l operands and file.a operands is significant. You may have to specify a library multiple times on the command string, if subsequent specification of file.o files requires that additional symbols be resolved from that library.
- The following environment variable specifies the name of an MVS program to be executed and can
be at most eight characters in length. You can dynamically alter
the search order used to find MVS programs
by using the STEPLIB environment variable. For more information about
the STEPLIB environment variable, see the section on commonly used environment
variables in z/OS UNIX System Services Planning.
It is also described under the sh command.
- _LD_DAMP_NAME
- The following environment variables can be at most 15 characters
in length. Do not specify any periods (.) when setting these environment
variables because they would then never match their corresponding
operands:
- _LD_ASUFFIX
- _LD_ASUFFIX_HOST
- _LD_OSUFFIX
- _LD_OSUFFIX_HOST
- _LD_XSUFFIX
- _LD_XSUFFIX_HOST
- The following environment variable is a parsed colon-delimited
data set name, and represents a data set concatenation or a data set
list:
- _LD_SYSLIB
- The following environment variables specify the names of MVS databases and can be at most 44
characters in length:
- _LD_DEBUG_DUMP
- _LD_DEBUG_TRACE
- The following environment variables can be at most 63 characters
in length:
- _LD_NEW_DATACLAS
- _LD_NEW_DSNTYPE
- _LD_NEW_MGMTCLAS
- _LD_NEW_SPACE
- _LD_NEW_STORCLAS
- _LD_NEW_UNIT
- The following environment variable is for specification of the
SPACE parameter, and supports only the syntax as shown below, including
all commas and parentheses (example: "(,(10,10,10))"). PRIMARY is
the number of tracks of primary to be allocated, SECONDARY the number
of secondary tracks, and DIRBLOCKS the number of directory blocks.
DIRBLKS must be specified even when it is not needed.
- _LD_NEW_SPACE
- The following environment variable is for specification of the
DSNTYPE parameter, and supports only the sub-parameters LIBRARY or
PDS (or null for the default, LIBRARY):
- _LD_NEW_DSNTYPE
- The following environment variables can be at most 127 characters
in length:
- _LD_DCBU
- _LD_DCB80
Restriction: These environment variables are for specification of DCB information, and support only the following DCB subparameters, with the noted restrictions:- RECFM
- Incorrect values are ignored.
- LRECL
- None
- BLKSIZE
- None
- DSORG
- Incorrect values are treated as if no value had been specified.
- The following environment variables are parsed as blank-delimited
words, and therefore no embedded blanks or other white space is allowed
in the value specified. The maximum length of each word is 1024 characters:
- _LD_LIBDIRS
- _LD_OPTIONS
- _LD_OPERANDS
Localization
- LANG
- LC_ALL
- LC_CTYPE
- LC_MESSAGES
See Localization for more information.
Exit values
- 0
- Successful completion.
- >0
- An error occurred during processing.
Related information
c89