ld - Link object files

Format

ld [-cVv]
[-b option[,option]...]...
[-e function]
[-f filename]...
[-L directory]...
[-l libname]...
[-Oname[,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 The binder in 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 standard output 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 ENTRY in 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 Object library utility in z/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.
-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 standard output.
-v
This verbose option causes pseudo-JCL to be written to standard output 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.

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.

_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 Binder return codes in 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 standard error. 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: 
"4"
Following are the values:
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 
"LIBRARY"
which means that new data sets are created as type PDSE.
_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

  1. Messages generated from the use of the ld command are provided in IEW messages (IEW5000 - IEW5057) in z/OS MVS System Messages, Vol 8 (IEF-IGD).
  2. 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 
    CEESTART
    or, for AMODE 64 code, 
    CELQSTRT
    -O _LD_ORDER 
    CEESTART
    or, for AMODE 64 code, 
    CELQSTRT
    -S _LD_SYSLIB 
    //'CEE.SCEELKEX':
//'CEE.SCEELKED':
//'CBC.SCCNOBJ':
//'SYS1.CSSLIB'
    or installation equivalent names
    -u _LD_EXTRA_SYMBOL 
    CEEMAIN
    or, for AMODE 64 code, 
    CELQMAIN
    file.a _LD_OPERANDS 
    //CEE.SCEEOBJ
  3. 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.
  4. To be able to specify an operand that begins with a dash (-), you must use the double dash (--) end-of-options delimiter.
  5. 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.
  6. 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
    All operands are processed in the order they are specified.
  7. 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.
  8. 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, seeCommonly used environment variables in z/OS UNIX System Services Planning. It is also described under the sh command.
    • _LD_DAMP_NAME
  9. 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
  10. 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
  11. 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
  12. 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
  13. The following environment variable is for specification of the SPACE parameter, and supports only the syntax as shown, 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
  14. 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
  15. The following environment variables can be at most 127 characters in length:
    • _LD_DCBU
    • _LD_DCB80
    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.
  16. 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

ld uses the following localization environment variables:
  • LANG
  • LC_ALL
  • LC_CTYPE
  • LC_MESSAGES

Exit values

0
Successful completion.
>0
An error occurred during processing.

Related information

c89