'\" te .\" Copyright 1989 AT&T .\" Copyright (c) 1998, 2015, Oracle and/or its affiliates. All rights reserved. .TH ld 1 "14 January 2015" "SunOS 5.11" "User Commands" .SH NAME ld \- link-editor for object files .SH SYNOPSIS .LP .nf \fBld\fR [\fB-32\fR | \fB-64\fR] [\fB-B\fR direct | nodirect] [\fB-B\fR dynamic | static] [\fB-B\fR eliminate[=\fImode\fR] | local[=\fImode\fR]] [\fB-B\fR reduce] [\fB-c\fR \fIname\fR] [\fB-C\fR] [\fB-D\fR [\fB!\fR]\fItoken1\fR,[\fB!\fR]\fItoken2\fR,...] [\fB-e\fR \fIepsym\fR] [\fB-f\fR \fIname\fR | \fB-F\fR \fIname\fR] [\fB-G\fR] [\fB-h\fR \fIname\fR] [\fB-i\fR] [\fB-l\fR \fIx\fR] [\fB-L\fR \fIpath\fR] [\fB-m\fR] [\fB-M\fR \fImapfile\fR] [\fB-N\fR \fIstring\fR] [\fB-o\fR \fIoutfile\fR] [\fB-p\fR \fIauditlib\fR] [\fB-P\fR \fIauditlib\fR] [\fB-Q\fR y | n] [\fB-r\fR] [\fB-R\fR \fIpath\fR] [\fB-s\fR] [\fB-S\fR \fIsupportlib\fR] [\fB-u\fR \fIsymname\fR] [\fB-V\fR] [\fB-z\fR allextract | defaultextract | weakextract ] [\fB-z\fR ancillary[=\fIoutfile\fR]] [\fB-z\fR aslr[=\fImode\fR]] [\fB-z\fR assert-deflib[=\fIlibname\fR]] [\fB-z\fR compress-sections[=\fIcmp-type\fR]] [\fB-z\fR deferred | nodeferred] [\fB-z\fR defs | nodefs] [\fB-z\fR direct | nodirect] [\fB-z\fR discard-unused=\fIitem1\fR,\fIitem2\fR,...] [\fB-z\fR endfiltee] [\fB-z\fR fatal-warnings | nofatal-warnings] [\fB-z\fR finiarray=\fIfunction\fR] [\fB-z\fR globalaudit] [\fB-z\fR guidance[=\fIitem1\fR,\fIitem2\fR,...]] [\fB-z\fR help] [\fB-z\fR ignore | record] [\fB-z\fR initarray=\fIfunction\fR] [\fB-z\fR initfirst] [\fB-z\fR interpose] [\fB-z\fR lazyload | nolazyload] [\fB-z\fR ld32=\fIarg1\fR,\fIarg2\fR,...] [\fB-z\fR ld64=\fIarg1\fR,\fIarg2\fR,...] [\fB-z\fR loadfltr] [\fB-z\fR mapfile-add=\fIname\fR] [\fB-z\fR nodelete] [\fB-z\fR nodlopen] [\fB-z\fR nxheap[=\fImode\fR]] [\fB-z\fR nxstack[=\fImode\fR]] [\fB-z\fR parent=\fIobject\fR] [\fB-z\fR preinitarray=\fIfunction\fR] [\fB-z\fR rescan-now] [\fB-z\fR rescan-start ... \fB-z\fR rescan-end] [\fB-z\fR strip-class=[\fB!\fR]\fIclass1\fR,[\fB!\fR]\fIclass2\fR,...] [\fB-z\fR stub] [\fB-z\fR symbolcap] [\fB-z\fR target=sparc | x86] [\fB-z\fR text | textwarn | textoff] [\fB-z\fR type=\fIobject-type\fR] [\fB-z\fR verbose] [\fB-z\fR wrap=\fIsymbol\fR] \fIfilename\fR ... .fi .SH DESCRIPTION .sp .LP The link-editor, \fBld\fR, combines relocatable object files by resolving symbol references to symbol definitions, together with performing relocations. In all cases, the default output of the link-editor is left in the file \fBa.out\fR. See NOTES. .sp .LP The link-editor has a large number of options. Those options that are relevant to modern programming practices are defined in the SYNOPSIS, and described in the sections that follow. Other options are less commonly used, and are described under the SECONDARY OPTIONS section. .sp .LP The link-editor takes a variety of input files, typically generated from compilers, assemblers, or previous invocations of the link-editor. The link-editor concatenates and interprets the data within these input files to form an output file. The output file that is produced is one of the following basic types. .RS +4 .TP .ie t \(bu .el o \fBDynamic Executable\fR - A concatenation of input relocatable objects that requires intervention by the runtime linker, \fBld.so.1\fR(1), to produce a runnable process. Dynamic executables typically have one or more dependencies in the form of shared objects. .sp A dynamic executable is created when the \fB-z\fR \fBtype=exec\fR option is used, or is the default when no other options that control the output file type are provided. .RE .RS +4 .TP .ie t \(bu .el o \fBPosition-independent Executable\fR - A special case of a shared object, that specifies an interpreter. Position-independent executables should be created from position-independent code. Unlike a dynamic executable, which requires a fixed address space for execution, a position-independent executable can be loaded at an arbitrary address chosen by \fBexec\fR(2). .sp A position-independent executable is created when the \fB-z\fR \fBtype=pie\fR option is used. .RE .RS +4 .TP .ie t \(bu .el o \fBRelocatable Object\fR - A concatenation of input relocatable objects that can be used in subsequent link-edit phases. .sp A relocatable object is created when the \fB-z\fR \fBtype=reloc\fR option, or \fB-r\fR option are used. .RE .RS +4 .TP .ie t \(bu .el o \fBShared Object\fR - A concatenation of input relocatable objects that provide services that can be bound to a dynamic executable at runtime. Shared objects should be created from position-independent code. Shared objects can have dependencies on other shared objects. .sp A shared object is created when the \fB-z\fR \fBtype=shared\fR option, or \fB-G\fR option are used. .RE .sp .LP The link-editor operates in one of two modes, dynamic or static. Dynamic linking mode is the default and provides for the creation of dynamic executables, shared objects, and position-independent executables. This dynamic linking environment tightly couples the work of the link-editor and the runtime linker, \fBld.so.1\fR(1). Both of these utilities, together with their related technologies and utilities, are extensively documented in the \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .sp .LP Static linking mode provides for the creation of relocatable objects. Modern versions of the Oracle Solaris operating system do not support the creation of static executables. See \fBStatic Executables\fR. All discussion in this section assumes dynamic linking, or static linking with the \fB-ztype=reloc\fR or \fB-r\fR options. .sp .LP If any argument is a library, the link-editor, by default, searches the library exactly once at the point the library is encountered on the command line. The library can be either a shared object or relocatable archive. See \fBar\fR(1). .sp .LP A shared object consists of an indivisible, whole unit that has been generated by a previous link-edit of one or more input files. When the link-editor processes a shared object, the entire contents of the shared object become a logical part of the resulting output file image. The shared object is not physically copied during the link-edit as its actual inclusion is deferred until process execution. This logical inclusion means that all symbol entries defined in the shared object are made available to the link-editing process. See Chapter 4, \fIShared Objects,\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .sp .LP For an archive library, the link-editor, by default, loads only those archive members that define an unresolved external reference. The link-editor searches the symbol table of the archive library sequentially to resolve external references that can be satisfied by archive members. This search is repeated until no external references can be resolved by the archive. Thus, the order of members in the library is functionally unimportant, unless multiple archive members exist that define the same external symbol. See also the \fB-z\fR \fBallextract\fR option. Archive libraries that have interdependencies can require multiple command line definitions, or the use of one of the \fB-z rescan\fR options. See \fIArchive Processing\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .sp .LP The link-editor is a \fBcross\fR link-editor, able to link 32-bit objects or 64-bit objects, for SPARC or x86 targets. The link-editor uses the \fBELF\fR class and machine type of the first relocatable object on the command line to govern the mode in which to operate. The mixing of 32-bit objects and 64-bit objects is not permitted. Similarly, only objects of a single machine type are allowed. See the \fB-32\fR, \fB-64\fR and \fB-z target\fR options. .SS "Static Executables" .sp .LP The creation of static executables has been discouraged for many releases. In fact, 64-bit system archive libraries have never been provided with Solaris. Because a static executable is built against system archive libraries, the executable contains system implementation details. This self-containment has a number of drawbacks. .RS +4 .TP .ie t \(bu .el o The executable is immune to the benefits of system patches delivered as shared objects. The executable therefore, must be rebuilt to take advantage of many system improvements. .RE .RS +4 .TP .ie t \(bu .el o The ability of the executable to run on future releases can be compromised. .RE .RS +4 .TP .ie t \(bu .el o The duplication of system implementation details negatively affects system performance. .RE .sp .LP Starting with Oracle Solaris 10, 32-bit system archive libraries are no longer provided. Without these libraries, specifically \fBlibc.a\fR, the creation of static executables is no longer achievable without access to undocumented and changeable system details. However, the capability of the link-editor to process static linking options, and the processing of archive libraries, remains unchanged. .SS "Option Processing" .sp .LP Typically, link-edits are completely specified using command line options. However, a variety of environment variables are provided to augment command line processing. These variables provide for supplying options that might clash with compiler options. These variables also provide for overriding, or unsetting, the command line options that are embedded in scripts and build environments. .sp .LP Any inconsistencies between command line options result in a fatal error condition. Any inconsistencies that involve an option provided by an environment variable result in a warning, and the first option taking precedence. .sp .LP Options are interpreted from the environment and the command line in the following order. .RS +4 .TP .ie t \(bu .el o From the \fBLD_OPTIONS\fR environment variable. .RE .RS +4 .TP .ie t \(bu .el o From the command line. .RE .RS +4 .TP .ie t \(bu .el o From the \fBLD_UNSET\fR environment variable. .RE .sp .LP The output object type is determined from these three components. This object type is then used to investigate any \fBLD_{object-type}_UNSET\fR, and \fBLD_{object-type}_OPTIONS\fR environment variables to remove, or add, options specific to the object type being built. The \fIobject-type\fR provides the types, in uppercase, defined by the \fB-z type\fR option, and is one of \fBEXEC\fR, \fBPIE\fR, \fBRELOC\fR or \fBSHARED\fR. For example, the \fBLD_EXEC_OPTIONS\fR option is interpreted when the output file type is a dynamic executable. These environment variables are processed in the following order. .RS +4 .TP .ie t \(bu .el o From the \fBLD_{object-type}_UNSET\fR environment variable. .RE .RS +4 .TP .ie t \(bu .el o From the \fBLD_{object-type}_OPTIONS\fR environment variable. .RE .sp .LP Any command line options that are inconsistent with this output object type result in a fatal error condition. Any inconsistent option provided by an environment variable results in a warning, and the option being ignored. .sp .LP Any \fBUNSET\fR operation is accompanied with a warning notification. Any other option processing warnings can be promoted to a fatal error condition by setting the \fB-z fatal-warnings\fR option. .SH OPTIONS .sp .LP The following options are supported. .sp .ne 2 .mk .na \fB\fB-32\fR | \fB-64\fR\fR .ad .br .na \fB\fB-m32\fR | \fB-m64\fR\fR .ad .sp .6 .RS 4n Create a 32-bit, or 64-bit object. .sp By default, the class of the object being generated is determined from the first \fBELF\fR object processed from the command line. If no objects are specified, the class is determined by the first object encountered within the first archive processed from the command line. If there are no objects or archives, the link-editor creates a 32-bit object. .sp The \fB-64\fR option is required to create a 64-bit object solely from a \fBmapfile\fR. .sp The \fB-32\fR or \fB-64\fR options can also be used in the rare case of linking entirely from an archive that contains a mixture of 32 and 64-bit objects. If the first object in the archive is not the class of the object that is required to be created, then the \fB-32\fR or \fB-64\fR option can be used to direct the link-editor. .RE .sp .ne 2 .mk .na \fB\fB-B\fR \fBdirect\fR | \fBnodirect\fR\fR .ad .sp .6 .RS 4n These options govern direct binding. \fB-B\fR \fBdirect\fR establishes direct binding information by recording the relationship between a symbol reference and the dependency that provides the symbol definition. In addition, direct binding information can be established between a symbol reference and an associated definition within the object being created. The runtime linker uses this information to search directly for a symbol in the associated object rather than to carry out a default symbol search. .sp Direct binding information can only be established to dependencies specified with the link-edit. Thus, the \fB-z\fR \fBdefs\fR option should also be added. Objects that wish to interpose on symbols in a direct binding environment should identify themselves as interposers with the \fB-z\fR \fBinterpose\fR option. The use of \fB-B\fR \fBdirect\fR also enables \fB-z\fR \fBlazyload\fR for all dependencies. .sp The \fB-B\fR \fBnodirect\fR option prevents any direct binding to the interfaces offered by the object being created. The object being created can continue to directly bind to external interfaces by specifying the \fB-z\fR \fBdirect\fR option. See Chapter 6, \fIDirect Bindings,\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-B\fR \fBdynamic\fR | \fBstatic\fR\fR .ad .sp .6 .RS 4n These options govern library inclusion. \fB-B\fR \fBdynamic\fR allows a \fB-l\fR option library search to expand to a shared object and an archive library name. This option is valid, and the default, in dynamic mode only. \fB-B\fR \fBstatic\fR restricts a \fB-l\fR option library search to expand to archive library names only. These options can be specified any number of times on the command line as toggles. If the \fB-B\fR \fBstatic\fR option is given, no shared objects are accepted until \fB-B\fR \fBdynamic\fR is seen. See the \fB-l\fR option. .RE .sp .ne 2 .mk .na \fB\fB-B\fR \fBeliminate[=\fImode\fR]\fR | \fBlocal[=\fImode\fR]\fR\fR .ad .sp .6 .RS 4n Causes any symbols that default to global binding, to be eliminated from the symbol table, or reduced to local visibility. A global symbol that has a \fBSTV_DEFAULT\fR visibility, can be reduced to a more restrictive visibility by the link-editor. A global symbol that has any other \fBSTV_\fR visibility is considered to have an explicit visibility. An explicit visibility is honored by the link-editor, and can not be modified. See \fISymbol Visibility\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. A symbols visibility can be explicitly defined through compiler directives, or through \fBmapfiles\fR that define version or interface definitions. .sp \fBMapfile\fR version and interface definitions can contain \fIauto-elimination\fR or \fIauto-reduction\fR directives. See \fISYMBOL_SCOPE and SYMBOL_VERSION Directives\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. These directives result in symbols that are not explicitly defined in a \fBmapfile\fR, or do not define an explicit visibility, to be eliminated or reduced to local, respectively. Besides any explicit symbol definitions, symbol elimination or reduction can also be affected by the type of object being produced, as described in the paragraphs that follow. The \fB-B\fR \fBeliminate\fR option requests the same symbol elimination as the \fBmapfile\fR \fIauto-elimination\fR directive. The \fB-B\fR \fBlocal\fR option requests the same symbol reduction as the \fBmapfile\fR \fIauto-reduction\fR directive. .sp Either option can be qualified with a mode, \fBexternal\fR, or \fBnoexternal\fR, to control the selection of eliminated or reduced global symbols. This fine-tuning is usually unnecessary, as the link-editor defaults to the appropriate mode for the type of object being produced, \fBexternal\fR for executables, and \fBnoexternal\fR for shared objects. .sp When building a dynamic object, it can be necessary to ensure that some symbols remain global so that they can be referenced from external dependencies. This is particularly true for dynamic executables. When building an executable, relocatable objects are contributed by the compilation environment that provide for runtime process initialization. These relocatable objects can contain global symbols that are referenced from system dependencies. These symbols should remain global regardless of any auto-elimination or auto-reduction symbol techniques, so as not to compromise runtime execution. .sp Defining the \fBmode\fR as \fBexternal\fR results in the analysis of any external dependencies to determine if any symbol reference from the dependency might bind to a symbol definition within the object being built. Any global symbol that satisfies such a binding is not eliminated or reduced to local. This mode is the default when producing a dynamic executable. .sp Defining the \fBmode\fR as \fBnoexternal\fR circumvents the analysis of any external dependencies, and results in the reduction of all symbols that are not explicitly defined in a \fBmapfile\fR, or do not define an explicit visibility. This mode is the default when producing a shared object. .sp See also the \fB-B\fR \fBreduce\fR option. .RE .sp .ne 2 .mk .na \fB\fB-B\fR \fBreduce\fR\fR .ad .sp .6 .RS 4n When generating a relocatable object, causes the reduction of symbolic information defined by any symbol visibility attribute, or through \fBmapfiles\fR that define version or interface definitions. By default, when a relocatable object is generated, visibility attributes, version definitions, or interface definitions are only recorded in the output image. Visibility attributes, or \fBmapfile\fR version or interface definitions, are always applied to any symbolic information when creating a dynamic executable or shared object. .RE .sp .ne 2 .mk .na \fB\fB-c\fR \fIname\fR\fR .ad .sp .6 .RS 4n Records the configuration file \fIname\fR for use at runtime. Configuration files can be employed to alter default search paths, provide a directory cache, together with providing alternative object dependencies. See \fBcrle\fR(1). This option is only available when creating a dynamic executable or position-independent executable. .RE .sp .ne 2 .mk .na \fB\fB-C\fR\fR .ad .sp .6 .RS 4n Demangles C++ symbol names displayed in diagnostic messages. .RE .sp .ne 2 .mk .na \fB\fB-D\fR [\fB!\fR]\fItoken1\fR,[\fB!\fR]\fItoken2\fR,...\fR .ad .sp .6 .RS 4n Prints debugging information as specified by each \fItoken\fR, to the standard error. The special token \fBhelp\fR indicates the full list of tokens available. See \fIDebugging Aids\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-e\fR \fIepsym\fR\fR .ad .br .na \fB\fB--entry\fR \fIepsym\fR\fR .ad .sp .6 .RS 4n Sets the entry point address for the output file to be the symbol \fIepsym\fR. .RE .sp .ne 2 .mk .na \fB\fB-f\fR \fIname\fR\fR .ad .br .na \fB\fB--auxiliary\fR \fIname\fR\fR .ad .sp .6 .RS 4n Used only when building a shared object. Specifies that the symbol table of the shared object is used as an auxiliary filter on the symbol table of the shared object specified by \fIname\fR. Multiple instances of this option are allowed. This option can not be combined with the \fB-F\fR option. See \fIGenerating Auxiliary Filters\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-F\fR \fIname\fR\fR .ad .br .na \fB\fB--filter\fR \fIname\fR\fR .ad .sp .6 .RS 4n Used only when building a shared object. Specifies that the symbol table of the shared object is used as a filter on the symbol table of the shared object specified by \fIname\fR. Multiple instances of this option are allowed. This option can not be combined with the \fB-f\fR option. See \fIGenerating Standard Filters\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-G\fR\fR .ad .br .na \fB\fB-shared\fR\fR .ad .sp .6 .RS 4n In dynamic mode only, produces a shared object. Undefined symbols are allowed. See also the \fB-ztype=shared\fR option. See Chapter 4, \fIShared Objects,\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-h\fR \fIname\fR\fR .ad .br .na \fB\fB-soname\fR \fIname\fR\fR .ad .sp .6 .RS 4n In dynamic mode only, when building a shared object, records \fIname\fR in the object's dynamic section. \fIname\fR is recorded in any dynamic objects that are linked with this object rather than the object's file system name. Accordingly, \fIname\fR is used by the runtime linker as the name of the shared object to search for at runtime. See \fIRecording a Shared Object Name\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-i\fR\fR .ad .sp .6 .RS 4n Ignores \fBLD_LIBRARY_PATH\fR. This option is useful when an \fBLD_LIBRARY_PATH\fR setting is in effect to influence the runtime library search, which would interfere with the link-editing being performed. .RE .sp .ne 2 .mk .na \fB\fB-l\fR \fIx\fR\fR .ad .br .na \fB\fB--library\fR \fIx\fR\fR .ad .sp .6 .RS 4n Searches a library \fBlib\fR\fIx\fR\fB\&.so\fR or \fBlib\fR\fIx\fR\fB\&.a\fR, the conventional names for shared object and archive libraries, respectively. In dynamic mode, unless the \fB-B\fR \fBstatic\fR option is in effect, the link-editor searches each directory specified in the library search path for a \fBlib\fR\fIx\fR\fB\&.so\fR or \fBlib\fR\fIx\fR\fB\&.a\fR file. The directory search stops at the first directory containing either. The link-editor chooses the file ending in \fB\&.so\fR if \fB-l\fR\fIx\fR expands to two files with names of the form \fBlib\fR\fIx\fR\fB\&.so\fR and \fBlib\fR\fIx\fR\fB\&.a\fR. If no \fBlib\fR\fIx\fR\fB\&.so\fR is found, then the link-editor accepts \fBlib\fR\fIx\fR\fB\&.a\fR. In static mode, or when the \fB-B\fR \fBstatic\fR option is in effect, the link-editor selects only the file ending in \fB\&.a\fR. The link-editor searches a library when the library is encountered, so the placement of \fB-l\fR is significant. See \fILinking With Additional Libraries\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-L\fR \fIpath\fR\fR .ad .br .na \fB\fB--library-path\fR \fIpath\fR\fR .ad .sp .6 .RS 4n Adds \fIpath\fR to the library search directories. The link-editor searches for libraries first in any directories specified by the \fB-L\fR options and then in the standard directories. This option is useful only if the option precedes the \fB-l\fR options to which the \fB-L\fR option applies. See \fIDirectories Searched by the Link-Editor\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .sp The environment variable \fBLD_LIBRARY_PATH\fR can be used to supplement the library search path, however the \fB-L\fR option is recommended, as the environment variable is also interpreted by the runtime environment. See \fBLD_LIBRARY_PATH\fR under ENVIRONMENT VARIABLES. .RE .sp .ne 2 .mk .na \fB\fB-m\fR\fR .ad .sp .6 .RS 4n Produces a memory map or listing of the input/output sections, together with any non-fatal multiply-defined symbols, on the standard output. .RE .sp .ne 2 .mk .na \fB\fB-M\fR \fImapfile\fR\fR .ad .sp .6 .RS 4n Reads \fImapfile\fR as a text file of directives to the link-editor. This option can be specified multiple times. If \fImapfile\fR is a directory, then all regular files, as defined by \fBstat\fR(2), within the directory are processed. See Chapter 9, \fIMapfiles,\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. Example \fBmapfiles\fR are provided in \fB/usr/lib/ld\fR. See also FILES. .RE .sp .ne 2 .mk .na \fB\fB-N\fR \fIstring\fR\fR .ad .sp .6 .RS 4n This option causes a \fBDT_NEEDED\fR entry to be added to the \fB\&.dynamic\fR section of the object being built. The value of the \fBDT_NEEDED\fR string is the \fIstring\fR that is specified on the command line. This option is position dependent, and the \fBDT_NEEDED\fR \fB\&.dynamic\fR entry is relative to the other dynamic dependencies discovered on the link-edit line. This option is useful for specifying dependencies within device driver relocatable objects when combined with the \fB-dy\fR and \fB-r\fR options. .RE .sp .ne 2 .mk .na \fB\fB-o\fR \fIoutfile\fR\fR .ad .br .na \fB\fB--output\fR \fIoutfile\fR\fR .ad .sp .6 .RS 4n Produces an output object file that is named \fIoutfile\fR. The name of the default object file is \fBa.out\fR. .RE .sp .ne 2 .mk .na \fB\fB-p\fR \fIauditlib\fR\fR .ad .sp .6 .RS 4n Identifies an audit library, \fIauditlib\fR. This audit library is used to audit the object being created at runtime. A shared object identified as requiring auditing with the \fB-p\fR option, has this requirement inherited by any object that specifies the shared object as a dependency. See the \fB-P\fR option. See also \fIRuntime Linker Auditing Interface\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-P\fR \fIauditlib\fR\fR .ad .sp .6 .RS 4n Identifies an audit library, \fIauditlib\fR. This audit library is used to audit the dependencies of the object being created at runtime. Dependency auditing can also be inherited from dependencies that are identified as requiring auditing. See the \fB-p\fR option, and the \fB-z\fR \fBglobalaudit\fR option. See also \fIRuntime Linker Auditing Interface\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-Q\fR \fBy\fR | \fBn\fR\fR .ad .sp .6 .RS 4n Under \fB-Q\fR \fBy\fR, an \fBident\fR string is added to the \fB\&.comment\fR section of the output file. This string identifies the version of the the link-editor used to create the file. This results in multiple link-editor \fBidents\fR when there have been multiple linking steps, such as when using the link-editor \fB-ztype=reloc\fR or \fB-r\fR options. This identification is identical with the default action of the \fBcc\fR command. \fB-Q\fR \fBn\fR suppresses version identification. \fB\&.comment\fR sections can be manipulated by the \fBmcs\fR(1) utility. .RE .sp .ne 2 .mk .na \fB\fB-r\fR\fR .ad .br .na \fB\fB--relocatable\fR\fR .ad .sp .6 .RS 4n Combines relocatable objects to produce one relocatable object file. The link-editor does not complain about unresolved references. This option cannot be used with the \fB-a\fR option. See also the \fB-ztype=reloc\fR option. .RE .sp .ne 2 .mk .na \fB\fB-R\fR \fIpath\fR\fR .ad .br .na \fB\fB-rpath\fR \fIpath\fR\fR .ad .sp .6 .RS 4n A colon-separated list of directories used to specify library search directories to the runtime linker. If present and not NULL, the path is recorded in the output object file and passed to the runtime linker. Multiple instances of this option are concatenated together with each \fIpath\fR separated by a colon. See \fIDirectories Searched by the Runtime Linker\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .sp The use of a runpath within an associated object is preferable to setting global search paths such as through the \fBLD_LIBRARY_PATH\fR environment variable. Only the runpaths that are necessary to find the objects dependencies should be recorded. \fBldd\fR(1) can also be used to discover unused runpaths in dynamic objects, when used with the \fB-U\fR option. .sp Various tokens can also be supplied with a runpath that provide a flexible means of identifying system capabilities or an objects location. See Chapter 11, \fIEstablishing Dependencies with Dynamic String Tokens,\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. The \fB$ORIGIN\fR token is especially useful in allowing dynamic objects to be relocated to different locations in the file system. .RE .sp .ne 2 .mk .na \fB\fB-s\fR\fR .ad .br .na \fB\fB--strip-all\fR\fR .ad .sp .6 .RS 4n Strip any symbolic information from the output file. These options are equivalent to using the \fB-z strip-class\fR option with the \fBdebug\fR and \fBsymbol\fR class identifiers. See also the \fB-z\fR \fBredlocsym\fR and \fB-z\fR \fBnoldynsym\fR options. .RE .sp .ne 2 .mk .na \fB\fB-S\fR \fIsupportlib\fR\fR .ad .sp .6 .RS 4n The shared object \fIsupportlib\fR is loaded with the link-editor and given information regarding the linking process. Shared objects that are defined by using the \fB-S\fR option can also be supplied using the \fBSGS_SUPPORT\fR environment variable. See \fILink-Editor Support Interface\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-u\fR \fIsymname\fR\fR .ad .br .na \fB\fB--undefined\fR \fIsymname\fR\fR .ad .sp .6 .RS 4n Enters \fIsymname\fR as an undefined symbol in the symbol table. This option is useful for loading entirely from an archive library. In this instance, an unresolved reference is needed to force the loading of the first routine. The placement of this option on the command line is significant. This option must be placed before the library that defines the symbol. See \fIDefining Additional Symbols with the -u option\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-V\fR\fR .ad .br .na \fB\fB--version\fR\fR .ad .sp .6 .RS 4n Outputs a message giving information about the version of the link-editor being used. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBallextract\fR | \fBdefaultextract\fR | \fBweakextract\fR\fR .ad .br .na \fB\fB--whole-archive\fR | \fB--no-whole-archive\fR\fR .ad .sp .6 .RS 4n Alters the extraction criteria of objects from any archives that follow. By default, archive members are extracted to satisfy undefined references and to promote tentative definitions with data definitions. Weak symbol references do not trigger extraction. Under the \fB-z\fR \fBallextract\fR or \fB--whole-archive\fR options, all archive members are extracted from the archive. Under \fB-z\fR \fBweakextract\fR, weak references trigger archive extraction. The \fB-z\fR \fBdefaultextract\fR or \fB--no-whole-archive\fR options provide a means of returning to the default following use of the former extract options. See \fIArchive Processing\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBancillary[=\fIoutfile\fR]\fR\fR .ad .sp .6 .RS 4n Specifies an ancillary output file, which will receive any non-allocable sections that would normally be added to the output object. Non-allocable sections are not required at runtime, and are primarily for use by debuggers and other observability tools. If \fIoutfile\fR is present, the ancillary file is created with the given name. If \fIoutfile\fR is not present, the ancillary file is given the same name as the primary output file with the addition of a \fB\&.anc\fR suffix. See \fIAncillary Objects\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .sp The \fB-z\fR \fBancillary\fR option is quietly ignored if used in conjunction with the \fB-z\fR \fBstub\fR option. The \fB-z\fR \fBancillary\fR option is also ignored if specified without \fIoutfile\fR, and the output file specified via the \fB-o\fR option is a device special file such as \fB/dev/null\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBaslr[=\fImode\fR]\fR\fR .ad .sp .6 .RS 4n Specifies the Address Space Layout Randomization (ASLR) behavior for a process. The mode value can be set to \fBenable\fR or \fBdisable\fR. If mode is omitted, ASLR is enabled. This option is only available when creating a dynamic executable or position-independent executable. See \fBsxadm\fR(1M). .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBassert-deflib[=\fIlibname\fR]\fR\fR .ad .sp .6 .RS 4n Enables warning messages for libraries specified with the \fB-l\fR command line option that are found by examining the default search paths provided by the link-editor. If a \fIlibname\fR value is provided, the default library warning feature is enabled, and the specified library is added to a list of libraries for which no warnings will be issued. Multiple \fB-z\fR \fBassert-deflib\fR options can be specified in order to specify multiple libraries for which warnings should not be issued. .sp The \fIlibname\fR value should be the name of the library file, as found by the link-editor, without any path components. For example, the following enables default library warnings, and excludes the standard C library. .sp .in +2 .nf $ \fBld ... -z assert-deflib=libc.so ...\fR .fi .in -2 .sp \fB-z\fR \fBassert-deflib\fR is a specialized option, primarily of interest in build environments where multiple objects with the same name exist and tight control over the library used is required. This option is not intended for general use. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBcompress-sections[=\fIcmp-type\fR]\fR\fR .ad .br .na \fB\fB--compress-debug-sections\fR \fIcmp-type\fR\fR .ad .sp .6 .RS 4n Enables the compression of annotate and debug output sections. The following values for \fIcmp-type\fR are recognized. .sp .ne 2 .mk .na \fB\fBnone\fR\fR .ad .sp .6 .RS 4n No compression is done. This is equivalent to not specifying the \fB-z\fR \fBcompress-sections\fR option. .RE .sp .ne 2 .mk .na \fB\fBzlib\fR\fR .ad .sp .6 .RS 4n Compress candidate sections using \fBZLIB\fR compression. The resulting output sections will have the \fBSHF_COMPRESSED\fR section flag set to identify the use of compression. .RE .sp .ne 2 .mk .na \fB\fBzlib-gnu\fR\fR .ad .sp .6 .RS 4n Compress all candidate sections using \fBZLIB\fR compression, using the \fBGNU\fR section compression format. This format requires candidate sections to have a name that begins with \fB\&.debug\fR. The resulting sections are renamed to start with \fB\&.zdebug\fR to identify the use of compression. .RE If \fIcmp-type\fR is omitted, the \fBzlib\fR style is used. The link-editor will quietly skip compression for any section that would be larger in compressed form than the original non-compressed data. .sp To be a candidate for compression, a section must be non-allocable, and belong to one of the following classes. .sp .ne 2 .mk .na \fB\fBannotate\fR\fR .ad .sp .6 .RS 4n Annotate sections provide information that is used by memory access tools, and coverage related tools. These sections are identified by having a \fBSHT_SUNW_ANNOTATE\fR section type. .RE .sp .ne 2 .mk .na \fB\fBdebug\fR\fR .ad .sp .6 .RS 4n Debug sections are identified by having a \fB\&.compcom\fR, \fB\&.line\fR, \fB\&.stab*\fR, \fB\&.debug*\fR, or \fB\&.zdebug*\fR section name. These sections are also identified by having an \fBSHT_PROGBITS\fR or \fBSHT_SUNW_DEBUG*\fR section type. .RE The \fBzlib-gnu\fR compression type is limited to sections with a name that starts with \fB\&.debug\fR. When \fBzlib-gnu\fR is used, sections that would otherwise be candidates for compression are not compressed. The underlying \fBZLIB\fR compression is identical for the \fBzlib\fR and \fBzlib-gnu\fR styles, and both formats deliver the same amount of compression for a given input section. The two styles differ in the selection of candidate sections, the format of the compression header, and in how compressed sections are identified. See \fICompressed Debug Sections\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. Unless there is a specific requirement to use the \fBzlib-gnu\fR style, the more general default \fBzlib\fR style is recommended. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBdeferred\fR | \fBnodeferred\fR\fR .ad .sp .6 .RS 4n Enables or disables the marking of dynamic dependencies as deferred. Dynamic dependencies which are marked \fBdeferred\fR, are also marked as lazy loadable, and are not loaded at initial process start-up. The loading of deferred dependencies is delayed until process execution, when the first binding to a deferred reference is made. Unlike basic lazy loadable dependencies, deferred dependencies are not processed as part of \fBLD_BIND_NOW\fR processing, or through \fBdlopen\fR(3C) with the \fBRTLD_NOW\fR flag. See \fITesting for Functionality\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .sp The use of deferred dependencies, together with \fBdlsym\fR(3C) and the \fBRTLD_PROBE\fR handle, provides a flexible mechanism, and natural coding style, for testing for functionality. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBdefs\fR | \fBnodefs\fR\fR .ad .br .na \fB\fB--no-undefined\fR\fR .ad .sp .6 .RS 4n The \fB-z\fR \fBdefs\fR option and the \fB--no-undefined\fR option force a fatal error if any undefined symbols remain at the end of the link. This mode is the default when an executable is built. For historic reasons, this mode is \fBnot\fR the default when building a shared object. Use of the \fB-z\fR \fBdefs\fR option is recommended, as this mode assures the object being built is self-contained. A self-contained object has all symbolic references resolved internally, or to the object's immediate dependencies. .sp The \fB-z\fR \fBnodefs\fR option allows undefined symbols. For historic reasons, this mode is the default when a shared object is built. When used with executables, the behavior of references to such undefined symbols is unspecified. Use of the \fB-z\fR \fBnodefs\fR option is not recommended. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBdirect\fR | \fBnodirect\fR\fR .ad .sp .6 .RS 4n Enables or disables direct binding to any dependencies that follow on the command line. These options allow finer control over direct binding than the global counterpart \fB-B\fR \fBdirect\fR. The \fB-z\fR \fBdirect\fR option also differs from the \fB-B\fR \fBdirect\fR option in the following areas. Direct binding information is not established between a symbol reference and an associated definition within the object being created. Lazy loading is not enabled. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBdiscard-unused=\fR\fIitem1\fR\fB,\fR\fIitem2\fR\fB,...\fR\fR .ad .sp .6 .RS 4n By default, the link-editor discards unused, empty sections. Other categories of input material can be determined to be unused during the link-edit. The \fB-z discard-unused\fR option enables the automatic removal of such items. The following \fIitem\fR tokens are recognized. .sp .ne 2 .mk .na \fBsections\fR .ad .sp .6 .RS 4n Unused sections are discarded from the output file created from the link-edit. .RE .sp .ne 2 .mk .na \fBfiles\fR .ad .sp .6 .RS 4n Unused relocatable object files are discarded from the output file created from the link-edit. .sp An input relocatable object file is determined to be unused if all allocatable sections provided by the relocatable object are unused. See also the "Non-Required Relocatable Object Files" discussion of the \fB-z guidance\fR option. .RE .sp .ne 2 .mk .na \fBdependencies\fR .ad .sp .6 .RS 4n Unused, explicit, shared object dependencies are not recorded in the output file created from the link-edit. .sp An explicit dependency is one that is defined on the command line, either using the path name, or more commonly by using the \fB-l\fR option. Explicit dependencies can depend on other objects, which are referred to as implicit dependencies. An explicit dependency is determined to be unused if two conditions are true. .RS +4 .TP .ie t \(bu .el o No global symbols that are provided by the dependency are referenced from the object being built. .RE .RS +4 .TP .ie t \(bu .el o The dependency does not compensate for the requirements of any implicit dependencies. .RE See also the "Non-Required or Compensating Dependencies" discussion of the \fB-z guidance\fR option. .RE .sp .ne 2 .mk .na \fBnone\fR .ad .sp .6 .RS 4n Disables all unused processing, including the default action of removing unused, empty sections. .RE See also \fIRemoving Unused Material\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBendfiltee\fR\fR .ad .sp .6 .RS 4n Marks a filtee so that when processed by a filter, the filtee terminates any further filtee searches by the filter. See \fIReducing Capability Filtee Searches\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBfatal-warnings\fR | \fBnofatal-warnings\fR\fR .ad .br .na \fB\fB--fatal-warnings\fR | \fB--no-fatal-warnings\fR\fR .ad .sp .6 .RS 4n The \fB-z\fR \fBfatal-warnings\fR and the \fB--fatal-warnings\fR option cause the link-editor to treat warnings as fatal errors. .sp The \fB-z\fR \fBnofatal-warnings\fR and the \fB--no-fatal-warnings\fR option cause the link-editor to treat warnings as non-fatal. This is the default behavior. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBfiniarray=\fR\fIfunction\fR\fR .ad .sp .6 .RS 4n Appends an entry to the \fB\&.fini_array\fR section of the object being built. If no \fB\&.fini_array\fR section is present, a section is created. The new entry is initialized to point to \fIfunction\fR. See \fIInitialization and Termination Sections\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBglobalaudit\fR\fR .ad .sp .6 .RS 4n This option supplements an audit library definition that has been recorded with the \fB-P\fR option. This option is only available when creating a dynamic executable or position-independent executable. Audit libraries that are defined within an object with the \fB-P\fR option typically allow for the auditing of the immediate dependencies of the object. The \fB-z\fR \fBglobalaudit\fR promotes the auditor to a global auditor, thus allowing the auditing of all dependencies. See \fIInvoking the Auditing Interface\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .sp An auditor established with the \fB-P\fR option and the \fB-z\fR \fBglobalaudit\fR option, is equivalent to the auditor being established with the \fBLD_AUDIT\fR environment variable. See \fBld.so.1\fR(1). .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBguidance[=\fR\fIitem1\fR\fB,\fR\fIitem2\fR\fB,...]\fR\fR .ad .sp .6 .RS 4n Provide guidance messages to suggest the link-editor options that can improve the quality of the resulting object, or which are otherwise considered to be beneficial. The specific guidance offered is subject to change over time as the system evolves. Obsolete guidance offered by older versions of the link-editor may be dropped in new versions. Similarly, new guidance may be added to new versions of the link-editor. Guidance therefore always represents current best practices. .sp It is possible to enable guidance, while preventing specific guidance messages, by providing a list of \fIitem\fR tokens, representing the class of guidance to be suppressed. In this way, unwanted advice can be suppressed without losing the benefit of other guidance. Unrecognized \fIitem\fR tokens are quietly ignored by the link-editor, allowing a given command line to be executed on a variety of older or newer versions of Solaris. .sp The guidance offered by the current version of the link-editor, and the \fIitem\fR tokens used to disable these messages, are as follows. .sp .ne 2 .mk .na \fBSpecify Required Dependencies\fR .ad .sp .6 .RS 4n Dynamic executables and shared objects should explicitly define all of the dependencies they require. Guidance recommends the use of the \fB-z\fR \fBdefs\fR option, should any symbol references remain unsatisfied when building dynamic objects. This guidance can be disabled with \fB-z\fR \fBguidance=nodefs\fR. .RE .sp .ne 2 .mk .na \fBDo Not Specify Non-Required or Compensating Dependencies\fR .ad .sp .6 .RS 4n Dynamic executables and shared objects should not define any explicit dependencies that do not satisfy the symbol references made by the dynamic object. Guidance recommends that non-required, or unused dependencies, be removed. Unused dependencies, can fall into one of two categories. .RS +4 .TP .ie t \(bu .el o Explicit dependencies that satisfy no symbol references. .RE .RS +4 .TP .ie t \(bu .el o Explicit dependencies that satisfy no symbol references from the dynamic object being built, but that compensate for implicit dependencies. See the "dependencies" discussion of the \fB-z discard-unused\fR option. .RE Guidance for both of these categories can be disabled with \fB-z guidance=nounused-dependencies\fR, or the synonym \fB-z guidance=nounused\fR. Guidance for compensating dependencies can be disabled with \fB-z guidance=nounused-compensators\fR. .sp See also \fIRemoving Unused Material\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fBDo Not Specify Non-Required Relocatable Object Files\fR .ad .sp .6 .RS 4n The output file being created should not contain any information from a relocatable object whose allocatable sections are not referenced by any other objects involved with the link-edit. Guidance recommends that unused relocatable objects be removed. This guidance can be disabled with \fB-z guidance=nounused-files\fR. .sp See also \fIRemoving Unused Material\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fBLazy Loading\fR .ad .sp .6 .RS 4n Dependencies should be identified for lazy loading. Guidance recommends the use of the \fB-z\fR \fBlazyload\fR option should any dependency be processed before either a \fB-z\fR \fBlazyload\fR or \fB-z\fR \fBnolazyload\fR option is encountered. This guidance can be disabled with \fB-z\fR \fBguidance=nolazyload\fR. .RE .sp .ne 2 .mk .na \fBDirect Bindings\fR .ad .sp .6 .RS 4n Dependencies should be referenced with direct bindings. Guidance recommends the use of the \fB-B\fR \fBdirect\fR, or \fB-z\fR \fBdirect\fR options should any dependency be processed before either of these options, or the \fB-z\fR \fBnodirect\fR option is encountered. This guidance can be disabled with \fB-z\fR \fBguidance=nodirect\fR. .RE .sp .ne 2 .mk .na \fBPure Text Segment\fR .ad .sp .6 .RS 4n Dynamic objects should not contain relocations to non-writable, allocable sections. Guidance recommends compiling objects with Position Independent Code (PIC) should any relocations against the text segment remain, and neither the \fB-z\fR \fBtextwarn\fR or \fB-z\fR \fBtextoff\fR options are encountered. This guidance can be disabled with \fB-z\fR \fBguidance=notext\fR. .RE .sp .ne 2 .mk .na \fBMapfile Syntax\fR .ad .sp .6 .RS 4n All \fBmapfiles\fR should use the version 2 \fBmapfile\fR syntax. Guidance recommends the use of the version 2 syntax should any \fBmapfiles\fR be encountered that use the version 1 syntax. This guidance can be disabled with \fB-z\fR \fBguidance=nomapfile\fR. .RE .sp .ne 2 .mk .na \fBLibrary Search Path\fR .ad .sp .6 .RS 4n Inappropriate dependencies that are encountered by the link-editor are quietly ignored. For example, a 32-bit dependency that is encountered when generating a 64-bit object is ignored. These dependencies can result from incorrect search path settings, such as supplying an incorrect \fB-L\fR option. Although benign, this dependency processing is wasteful, and might hide a build problem that should be solved. Guidance recommends the removal of any inappropriate dependencies. This guidance can be disabled with \fB-z\fR \fBguidance=nolibpath\fR. .RE In addition, \fB-z\fR \fBguidance=noall\fR can be used to entirely disable the guidance feature. See Chapter 5, \fILink-Editor Quick Reference,\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR for more information on guidance and advice for building better objects. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBhelp\fR\fR .ad .br .na \fB\fB--help\fR\fR .ad .sp .6 .RS 4n Print a summary of the command line options on the standard output and exit. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBignore\fR | \fBrecord\fR\fR .ad .br .na \fB\fB--as-needed\fR | \fB--no-as-needed\fR\fR .ad .sp .6 .RS 4n Ignores, or records, shared object dependencies that are not referenced as part of the link-edit. These options are positional options, used to toggle how the link-editor handles unreferenced dependencies encountered on the command line. When \fB-z\fR \fBignore\fR is encountered, any subsequent unreferenced dependencies are quietly ignored. When \fB-z\fR \fBrecord\fR is encountered, all dependencies are recorded without regard to whether the dependency is referenced or not. .sp By default, the link-editor records all dependencies whether or not the dependency is referenced. The non-positional \fB-z\fR \fBdiscard-unused=dependencies\fR option can be used to alter this initial default. Once the initial setting is established, \fB-z\fR \fBignore\fR and \fB-z\fR \fBrecord\fR can be used to alter the default behavior. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBinitarray=\fR\fIfunction\fR\fR .ad .sp .6 .RS 4n Appends an entry to the \fB\&.init_array\fR section of the object being built. If no \fB\&.init_array\fR section is present, a section is created. The new entry is initialized to point to \fIfunction\fR. See \fIInitialization and Termination Sections\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBinitfirst\fR\fR .ad .sp .6 .RS 4n Marks the object so that its runtime initialization occurs before the runtime initialization of any other objects brought into the process at the same time. In addition, the object runtime finalization occurs after the runtime finalization of any other objects removed from the process at the same time. This option is only meaningful when building a shared object. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBinterpose\fR\fR .ad .sp .6 .RS 4n Marks the object as an interposer. At runtime, an object is identified as an explicit interposer if the object has been tagged using the \fB-z interpose\fR option. An explicit interposer is also established when an object is loaded using the \fBLD_PRELOAD\fR environment variable. See \fBld.so.1\fR(1). Implicit interposition can occur because of the load order of objects, however, this implicit interposition is unknown to the runtime linker. Explicit interposition can ensure that interposition takes place regardless of the order in which objects are loaded. Explicit interposition also ensures that the runtime linker searches for symbols in any explicit interposers when direct bindings are in effect. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBlazyload\fR | \fBnolazyload\fR\fR .ad .sp .6 .RS 4n Enables or disables the marking of dynamic dependencies to be lazily loaded. Dynamic dependencies which are marked \fBlazyload\fR are not loaded at initial process start-up. These dependencies are delayed until the first binding to the object is made. \fBNote:\fR Lazy loading requires the correct declaration of dependencies, together with associated runpaths for each dynamic object used within a process. See \fILazy Loading of Dynamic Dependencies\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBld32\fR=\fIarg1\fR,\fIarg2\fR,...\fR .ad .br .na \fB\fB-z\fR \fBld64\fR=\fIarg1\fR,\fIarg2\fR,...\fR .ad .sp .6 .RS 4n The \fB-z\fR \fB32\fR and \fB-z\fR \fB64\fR options are used to specify options that are only interpreted when running the 32-bit or 64-bit class of the link-editor, respectively. .sp For example, support libraries are class specific, so the correct class of support library can be ensured using: .sp .in +2 .nf $ \fBld ... -z ld32=-Saudit32.so.1 -z ld64=-Saudit64.so.1 ...\fR .fi .in -2 .sp Prior to Solaris 12, the class of link-editor that was executed was determined by the class of the \fBELF\fR object being created. Now, the class of the link-editor that is executed is always 64-bit. These options are maintained for backward compatibility with older versions of Solaris. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBloadfltr\fR\fR .ad .sp .6 .RS 4n Marks a filter to indicate that filtees must be processed immediately at runtime. Normally, filter processing is delayed until a symbol reference is bound to the filter. The runtime processing of an object that contains this flag mimics that which occurs if the \fBLD_LOADFLTR\fR environment variable is in effect. See \fBld.so.1\fR(1). .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBmapfile-add=\fR\fIname\fR\fR .ad .sp .6 .RS 4n Adds \fIname\fR to the list of known \fBmapfile\fR conditional input expression predicates. This option is equivalent to placing the following lines at the top of the first \fBmapfile\fR read by the link-editor. .sp .in +2 .nf $mapfile_version 2 $add \fIname\fR .fi .in -2 Names entered via \fB-z mapfile-add\fR can be used with \fBmapfile\fR \fB$if\fR and \fB$elif\fR directives to conditionally process \fBmapfile\fR input. See Chapter 9, \fIMapfiles,\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBnodelete\fR\fR .ad .sp .6 .RS 4n Marks the object as non-deletable at runtime. This mode is similar to adding the object to the process by using \fBdlopen\fR(3C) with the \fBRTLD_NODELETE\fR mode. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBnodlopen\fR\fR .ad .sp .6 .RS 4n Marks the object as not available to \fBdlopen\fR(3C), either as the object specified by the \fBdlopen()\fR, or as any form of dependency required by the object specified by the \fBdlopen()\fR. This option is only meaningful when building a shared object. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBnxheap[=\fImode\fR]\fR\fR .ad .sp .6 .RS 4n Specifies a non-executable heap (NXHEAP) requirement for a process. The mode value can be set to \fBenable\fR or \fBdisable\fR. If mode is omitted, NXHEAP is enabled. This option is only available when creating a dynamic executable or position-independent executable. See \fBsxadm\fR(1M). .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBnxstack[=\fImode\fR]\fR\fR .ad .sp .6 .RS 4n Specifies a non-executable stack (NXSTACK) requirement for a process. The mode value can be set to \fBenable\fR or \fBdisable\fR. If mode is omitted, NXSTACK is enabled. This option is only available when creating a dynamic executable or position-independent executable. See \fBsxadm\fR(1M). .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBparent=\fIobject\fR\fR\fR .ad .sp .6 .RS 4n Specifies a \fIparent\fR object, which can be an executable or shared object, against which to link the output object. This option is typically used when creating \fIplugin\fR shared objects intended to be loaded by an executable at runtime via the \fBdlopen()\fR function. The symbol table from the parent object is used to satisfy references from the \fBplugin\fR object. See \fIParent Objects\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBpreinitarray=\fR\fIfunction\fR\fR .ad .sp .6 .RS 4n Appends an entry to the \fB\&.preinit_array\fR section of the object being built. If no \fB\&.preinit_array\fR section is present, a section is created. The new entry is initialized to point to \fIfunction\fR. See \fIInitialization and Termination Sections\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBrescan-now\fR\fR .ad .sp .6 .RS 4n These options rescan the archive files that are provided to the link-edit. By default, archives are processed once as the archives appear on the command line. Archives are traditionally specified at the end of the command line so that their symbol definitions resolve any preceding references. However, specifying archives multiple times to satisfy their own interdependencies can be necessary. .sp \fB-z\fR \fBrescan-now\fR is a positional option, and is processed by the link-editor immediately when encountered on the command line. All archives seen on the command line up to that point are immediately reprocessed in an attempt to locate additional archive members that resolve symbol references. This archive rescanning is repeated until a pass over the archives occurs in which no new members are extracted. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBrescan-start\fR ... \fB-z\fR \fBrescan-end\fR\fR .ad .br .na \fB\fB--start-group\fR ... \fB--end-group\fR\fR .ad .br .na \fB\fB-(\fR ... \fB-)\fR\fR .ad .sp .6 .RS 4n Defines an archive rescan group. This is a positional construct, and is processed by the link-editor immediately upon encountering the closing delimiter option. Archives found within the group delimiter options are reprocessed as a group in an attempt to locate additional archive members that resolve symbol references. This archive rescanning is repeated until a pass over the archives On the occurs in which no new members are extracted. Archive rescan groups cannot be nested. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBstrip-class=\fR[\fB!\fR]\fIclass1\fR\fB,\fR[\fB!\fR]\fIclass2\fR\fB,...\fR\fR .ad .sp .6 .RS 4n Strip a specific class of section from any input objects, preventing these sections from being added to the output file. This option provides fine grained control over the sections that can be omitted from the output file. .sp The strip class descriptions that follow only apply to non-allocatable sections. .sp Each class token can be prepended with a '\fB!\fR' to indicate that the class should not be removed. This definition can be useful when combined with the \fBnonalloc\fR class. For example, using '\fB-z\fR \fBstrip-class=nonalloc,!note\fR' removes all non-allocatable sections except for the note section. .sp Stripped sections are completely removed from the output object. The use of the \fB-z\fR \fBancillary\fR option alters this behavior with regard to the non-dynamic symbol table \fB\&.symtab\fR, and the sections related to it. By default, the symbol table is written to both the primary and ancillary objects. If stripped, the symbol table is written to the ancillary object only, and is marked as absent in the primary object. If \fB\&.symtab\fR is stripped from an object without the use of \fB-z\fR \fBancillary\fR, the section is completely removed in the usual manner. .sp The following classes of section can be defined. .sp .ne 2 .mk .na \fB\fBnonalloc\fR\fR .ad .sp .6 .RS 4n Strip any non-allocatable section. These sections are identified as not including the \fBSHF_ALLOC\fR section flag. This class encapsulates all of the other classes, except for the \fBsymbol\fR class. The \fBnonalloc\fR class is often sufficient by itself to remove any unwanted sections. .RE .sp .ne 2 .mk .na \fB\fBannotate\fR\fR .ad .sp .6 .RS 4n Strip any annotation section. These sections provide information that is used by memory access tools, and coverage related tools. These sections are identified by having a \fBSHT_SUNW_ANNOTATE\fR section type. .RE .sp .ne 2 .mk .na \fB\fBcomment\fR\fR .ad .sp .6 .RS 4n Strip any comment section. These sections are identified by having a \fB\&.comment\fR section name. Alternatively, the \fBmcs\fR(1) utility is commonly used to manipulate comment sections. .RE .sp .ne 2 .mk .na \fB\fBdebug\fR\fR .ad .sp .6 .RS 4n Strip sections commonly used to contain debugging data. These sections are identified by having a \fB\&.compcom\fR, \fB\&.line\fR, \fB\&.stab*\fR, \fB\&.debug*\fR, or \fB\&.zdebug*\fR section name. These sections are also identified by having a \fBSHT_SUNW_DEBUG*\fR section type. .RE .sp .ne 2 .mk .na \fB\fBexclude\fR\fR .ad .sp .6 .RS 4n Strip any excludable section. These sections are identified by having a \fBSHF_EXCLUDE\fR section flag. This class can be useful when creating a relocatable object. By default, such sections are automatically excluded when a dynamic executable or shared object is created, and are retained when creating a relocatable object. .RE .sp .ne 2 .mk .na \fB\fBnote\fR\fR .ad .sp .6 .RS 4n Strip any note section. These sections are identified by having a \fBSHT_NOTE\fR section type. .RE .sp .ne 2 .mk .na \fB\fBsymbol\fR\fR .ad .sp .6 .RS 4n Strip any non-allocatable symbol table and string table sections, providing the output file is not a relocatable object. These sections are identified by having a \fBSHT_SYMTAB\fR section type. Any associated string table is also removed. .RE .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBstub\fR\fR .ad .sp .6 .RS 4n Produces a stub shared object. A stub object is a shared object, built entirely from \fBmapfiles\fR, that supplies the same linking interface as the real object, while containing no code or data. Stub objects cannot be used at runtime. However, an application can be built against a stub object, where the stub object provides the real object name to be used at runtime, and then use the real object at runtime. .sp Stub objects can only be produced for shared objects, and a \fBmapfile\fR defining the global symbols to be exported must be supplied. The \fB-ztype=shared\fR or \fB-G\fR option, and the \fB-M\fR options are therefore required when \fB-z\fR \fBstub\fR is used. When building a stub object, the link-editor ignores any object or library files specified on the command line, and these files need not exist in order to build a stub. Since the compilation step can be omitted, and because the link-editor has relatively little work to do, stub objects can be built very quickly. .sp See \fIStub Objects\fR in \fILinkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBsymbolcap\fR\fR .ad .sp .6 .RS 4n Convert a relocatable object that defines object capabilities into a relocatable object that defines symbol capabilities. See \fIConverting Object Capabilities to Symbol Capabilities\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBtarget=sparc | x86\fR \fI\fR\fR .ad .sp .6 .RS 4n Specifies the machine type for the output object. Supported targets are SPARC and x86. The 32-bit machine type for the specified target is used unless the \fB-64\fR option is also present, in which case the corresponding 64-bit machine type is used. By default, the machine type of the object being generated is determined from the first \fBELF\fR object processed from the command line. If no objects are specified, the machine type is determined by the first object encountered within the first archive processed from the command line. If there are no objects or archives, the link-editor assumes the native machine. This option is useful when creating an object directly with the link-editor whose input is solely from a \fBmapfile\fR. See the \fB-M\fR option. It can also be useful in the rare case of linking entirely from an archive that contains objects of different machine types for which the first object is not of the desired machine type. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBtext\fR | \fBtextoff\fR | \fBtextwarn\fR\fR .ad .sp .6 .RS 4n These options can be used in dynamic mode only. The \fB-z\fR \fBtext\fR option forces a fatal error if any relocations against non-writable, allocatable sections remain. For historic reasons, this mode is not the default when building an executable or shared object. However, its use is recommended to ensure that the text segment of the dynamic object being built is shareable between multiple running processes. A shared text segment incurs the least relocation overhead when loaded into memory. See \fIPosition-Independent Code\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .sp The \fB-z\fR \fBtextoff\fR option allows relocations against all allocatable sections, including non-writable ones. This mode is the default when building a shared object. .sp The \fB-z\fR \fBtextwarn\fR option lists a warning if any relocations against non-writable, allocatable sections remain. This mode is the default when building an executable. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBtype=\fIobject-type\fR\fR\fR .ad .sp .6 .RS 4n Specify the type of object to create. The following object-types are available. .sp .ne 2 .mk .na \fB\fBexec\fR\fR .ad .sp .6 .RS 4n A dynamic executable. .RE .sp .ne 2 .mk .na \fB\fBpie\fR\fR .ad .sp .6 .RS 4n A position-independent executable. This option also asserts the \fB-ztext\fR option. .RE .sp .ne 2 .mk .na \fB\fBreloc\fR\fR .ad .sp .6 .RS 4n A relocatable object. This is equivalent to specifying the \fB-r\fR option. .RE .sp .ne 2 .mk .na \fB\fBshared\fR\fR .ad .sp .6 .RS 4n A shared object. This is equivalent to specifying the \fB-G\fR option. This option also asserts the \fB-ztext\fR option. .RE .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBverbose\fR\fR .ad .sp .6 .RS 4n This option provides additional warning diagnostics during a link-edit. Presently, this option enables the following warnings. .RS +4 .TP .ie t \(bu .el o Suspicious use of displacement relocations. .RE .RS +4 .TP .ie t \(bu .el o Restricted use of static \fBTLS\fR relocations when building shared objects. .RE .RS +4 .TP .ie t \(bu .el o Symbol visibility inconsistencies. .RE In the future, this option might be enhanced to provide additional diagnostics that are deemed too noisy to be generated by default. .RE .sp .ne 2 .mk .na \fB\fB-z\fR\fBwrap=\fR\fIsymbol\fR\fR .ad .br .na \fB\fB-wrap=\fR\fIsymbol\fR\fR .ad .br .na \fB\fB--wrap=\fR\fIsymbol\fR\fR .ad .sp .6 .RS 4n Rename undefined references to \fIsymbol\fR in order to allow wrapper code to be linked into the output object without having to modify source code. When the \fB-z wrap\fR option is specified, all undefined references to \fIsymbol\fR are modified to reference \fB__wrap_\fR\fIsymbol\fR, and all references to \fB__real_\fR\fIsymbol\fR are modified to reference \fIsymbol\fR. You are expected to provide an object containing the \fB__wrap_\fR\fIsymbol\fR function. This wrapper function can call \fB__real_\fR\fIsymbol\fR in order to reference the actual function being wrapped. .sp The following is an example of a wrapper for the \fBmalloc\fR(3C) function. .sp .in +2 .nf void * __wrap_malloc(size_t c) { (void) printf("malloc called with %zu\en", c); return (__real_malloc(c)); } .fi .in -2 If other code is linked with this file using \fB-z\fR \fBwrap=malloc\fR to compile all the objects, then all calls to \fBmalloc\fR call the function \fB__wrap_malloc\fR instead. The call to \fB__real_malloc\fR calls the real \fBmalloc\fR function. .sp The real and wrapped functions should be maintained in separate source files. Otherwise, the compiler or assembler may resolve the call instead of leaving that operation for the link-editor to carry out, and prevent the wrap from occurring. .RE .SH SECONDARY OPTIONS .sp .LP The following options are less commonly used. These options provide for backward compatibility, very specialized features, or options that have been superseded with improved variants. .sp .ne 2 .mk .na \fB\fB-a\fR\fR .ad .sp .6 .RS 4n In static mode only, produces a static executable file. Undefined references are not permitted. This option is the default behavior for static mode. The \fB-a\fR option can not be used with the \fB-ztype=reloc\fR or \fB-r\fR options. See \fBStatic Executables\fR under DESCRIPTION. .RE .sp .ne 2 .mk .na \fB\fB-b\fR\fR .ad .sp .6 .RS 4n In dynamic mode only, provides no special processing for dynamic executable relocations that reference symbols in shared objects. Without the \fB-b\fR option, the link-editor applies techniques within a dynamic executable so that the text segment can remain read-only. One technique is the creation of special position-independent relocations for references to functions that are defined in shared objects. Another technique arranges for data objects that are defined in shared objects to be copied into the memory image of an executable at runtime. .sp The \fB-b\fR option is intended for specialized dynamic objects and is not recommended for general use. Its use suppresses all specialized processing required to ensure an object's shareability, and can even prevent the relocation of 64-bit executables. .RE .sp .ne 2 .mk .na \fB\fB-B\fR \fBgroup\fR\fR .ad .sp .6 .RS 4n Establishes a shared object and its dependencies as a group. Objects within the group are bound to other members of the group at runtime. This mode is similar to adding the object to the process by using \fBdlopen\fR(3C) with the \fBRTLD_GROUP\fR mode. An object that has an explicit dependency on a object identified as a group, becomes a member of the group. .sp As the group must be self contained, use of the \fB-B\fR \fBgroup\fR option also asserts the \fB-z\fR \fBdefs\fR option. .sp Establishing a group provides a primitive means of controlling the binding of a group of objects. However, better control can be accomplished with direct bindings. See the \fB-B\fR \fBdirect\fR option. .RE .sp .ne 2 .mk .na \fB\fB-B\fR \fBsymbolic\fR\fR .ad .sp .6 .RS 4n In dynamic mode only. When building a shared object, binds references to global symbols to their definitions, if available, within the object. Normally, references to global symbols within shared objects are not bound until runtime, even if definitions are available. This model allows definitions of the same symbol in an executable or other shared object to override the object's own definition. The link-editor issues warnings for undefined symbols unless \fB-z\fR \fBdefs\fR overrides. .sp The \fB-B\fR \fBsymbolic\fR option is intended for specialized dynamic objects and is not recommended for general use. To reduce the runtime relocation processing that is required an object, the creation of a version definition is recommended, together with the use of direct bindings. See the \fB-B\fR \fBdirect\fR option. .RE .sp .ne 2 .mk .na \fB\fB-d\fR \fBy\fR | \fBn\fR\fR .ad .sp .6 .RS 4n When \fB-d\fR \fBy\fR, the default, is specified, the link-editor uses dynamic linking. When \fB-d\fR \fBn\fR is specified, the link-editor uses static linking. See \fBStatic Executables\fR under DESCRIPTION, and \fB-B\fR \fBdynamic\fR|\fBstatic\fR. .RE .sp .ne 2 .mk .na \fB\fB-I\fR \fIname\fR\fR .ad .br .na \fB\fB--dynamic-linker\fR \fIname\fR\fR .ad .sp .6 .RS 4n When building an executable, uses \fIname\fR as the path name of the interpreter to be written into the program header. The default in static mode is no interpreter. In dynamic mode, the default is the name of the runtime linker, \fBld.so.1\fR(1). Either case can be overridden by \fB-I\fR \fIname\fR. \fBexec\fR(2) loads this interpreter when the \fBa.out\fR is loaded, and passes control to the interpreter rather than to the \fBa.out\fR directly. .RE .sp .ne 2 .mk .na \fB\fB-t\fR\fR .ad .sp .6 .RS 4n Turns off the warning for multiply-defined tentative (common block) data symbols that have different sizes or different alignments. This option is equivalent to specifying the \fB-z\fR \fBrelax=common\fR option. .RE .sp .ne 2 .mk .na \fB\fB-Wl,\fR\fIoption\fR\fR .ad .sp .6 .RS 4n The \fB-Wl,\fR option provides a means of passing link-editor options through a compiler driver. The compiler driver typically strips the \fB-Wl,\fR and passes the remaining option to the link-editor. Instances have occurred, particularly when building complex portable software, in which the link-editor has been called directly with the entire \fB-Wl,\fR option. To provide flexibility in such situations, the link-editor strips the \fB-Wl,\fR and interprets and remaining option. As such options are usually not under a users control, any unrecognized \fB-W\fR options result in a warning, rather than a fatal error, and the option being ignored. .RE .sp .ne 2 .mk .na \fB\fB-Y\fR \fBP,\fR\fIdirlist\fR\fR .ad .sp .6 .RS 4n Changes the default directories used for finding libraries. \fIdirlist\fR is a colon-separated path list. There should be no need to change the default search paths. Default search paths can change in newer releases of the operating system. Use of this option to explicitly dictate complete search paths run the risk of becoming incompatible with newer releases of the operating system. This option is maintained to support the historical use of some compiler drivers. Although supported, such use is not recommended. Additional search paths that are required for a link-edit should be provided with the \fB-L\fR option. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBabsexec\fR\fR .ad .sp .6 .RS 4n Used only when building a dynamic executable. Specifies that references to external absolute symbols should be resolved immediately instead of being left for resolution at runtime. In very specialized circumstances, this option removes text relocations that can result in excessive swap space demands by an executable. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBaltexec64\fR\fR .ad .sp .6 .RS 4n Execute the 64-bit link-editor. Prior to Solaris 11, the class of link-editor that was executed was determined by the class of \fBELF\fR object being created. Now, the class of the link-editor that is executed is always 64-bit. This option is maintained for backward compatibility with older versions of Solaris. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBcombreloc\fR | \fBnocombreloc\fR\fR .ad .sp .6 .RS 4n By default, the link-editor combines multiple relocation sections when building executables or shared objects. This section combination differs from relocatable objects, in which relocation sections are maintained in a one-to-one relationship with the sections to which the relocations must be applied. The \fB-z\fR \fBnocombreloc\fR option disables this merging of relocation sections, and preserves the one-to-one relationship found in the original relocatable objects. .sp The link-editor sorts the entries of data relocation sections by their symbol reference. This sorting reduces runtime symbol lookup. When multiple relocation sections are combined, this sorting produces the least possible relocation overhead when objects are loaded into memory, and speeds the runtime loading of dynamic objects. .sp Historically, the individual relocation sections were carried over to any executable or shared object, and the \fB-z\fR \fBcombreloc\fR option was required to enable the relocation section merging previously described. Relocation section merging is now the default. The \fB-z\fR \fBcombreloc\fR option is still accepted for the benefit of old build environments, but the option is unnecessary, and has no effect. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBgroupperm\fR | \fBnogroupperm\fR\fR .ad .sp .6 .RS 4n Assigns, or deassigns each dependency that follows to a unique group. The assignment of a dependency to a group has the same effect as if the dependency had been built using the \fB-B\fR \fBgroup\fR option. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBmuldefs\fR\fR .ad .br .na \fB\fB--allow-multiple-definition\fR\fR .ad .sp .6 .RS 4n Allows multiple, global, symbol definitions. By default, multiple symbol definitions that occur between relocatable objects result in a fatal error condition. This option suppresses the error condition, allowing the first symbol definition to be taken. Specialized compiler options, or high levels of compiler optimization, can circumvent the use of this option. See \fIFatal Resolutions\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBnocompstrtab\fR\fR .ad .sp .6 .RS 4n Disables the compression of \fBELF\fR string tables, and comment sections. By default, string compression is applied to \fBSHT_STRTAB\fR sections, to \fBSHT_PROGBITS\fR sections that have their \fBSHF_MERGE\fR and \fBSHF_STRINGS\fR section flags set, and to comment sections. .sp The \fBmcs\fR(1) utility, together with \fB-c\fR option, can be used to compress comment sections after an object has been built. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBnodefaultlib\fR\fR .ad .sp .6 .RS 4n Marks the object so that the runtime default library search path, used after any \fBLD_LIBRARY_PATH\fR or runpaths, is ignored. This option implies that all dependencies of the object can be satisfied from its runpath. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBnodump\fR\fR .ad .sp .6 .RS 4n This option was historically used to mark the object as not available to \fBdldump\fR(3C). The \fB-z\fR \fBnodump\fR option is still accepted, but the option is unnecessary, and has no effect. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBnoldynsym\fR\fR .ad .sp .6 .RS 4n Prevents the inclusion of a \fB\&.SUNW_ldynsym\fR section in a dynamic executable or shared object. The \fB\&.SUNW_ldynsym\fR section augments the \fB\&.dynsym\fR section by providing symbols for local functions. Local function symbols allow debuggers to display local function names in stack traces from stripped programs. Similarly, \fBdladdr\fR(3C) is able to supply more accurate results. .sp The \fB-z\fR \fBnoldynsym\fR option also prevents the inclusion of the two symbol sort sections that are related to the \fB\&.SUNW_ldynsym\fR section. The \fB\&.SUNW_dynsymsort\fR section provides sorted access to regular function and variable symbols. The \fB\&.SUNW_dyntlssort\fR section provides sorted access to thread local storage (\fBTLS\fR) variable symbols. .sp The \fB\&.SUNW_ldynsym\fR, \fB\&.SUNW_dynsymsort\fR, and \fB\&.SUNW_dyntlssort\fR sections, which becomes part of the allocable text segment of the resulting file, cannot be removed by \fBstrip\fR(1). Therefore, the \fB-z\fR \fBnoldynsym\fR option is the only way to prevent their inclusion. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBnopartial\fR\fR .ad .sp .6 .RS 4n Partially initialized symbols, that are defined within relocatable objects, are expanded in the output file being generated. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBnoversion\fR\fR .ad .sp .6 .RS 4n Eliminates versioning information. Version sections or associated \fB\&.dynamic\fR section entries are not generated in the output image. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBnow\fR\fR .ad .sp .6 .RS 4n Marks the object as requiring non-lazy runtime binding. This mode is similar to adding the object to the process by using \fBdlopen\fR(3C) with the \fBRTLD_NOW\fR mode. This mode is also similar to having the \fBLD_BIND_NOW\fR environment variable in effect. See \fBld.so.1\fR(1). .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBorigin\fR\fR .ad .sp .6 .RS 4n Marks the object as requiring immediate \fB$ORIGIN\fR processing at runtime. This option is only maintained for historic compatibility, as the runtime analysis of objects to provide for \fB$ORIGIN\fR processing is now default. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBredlocsym\fR\fR .ad .sp .6 .RS 4n Eliminates all local symbols except for the \fISECT\fR symbols from the symbol table \fBSHT_SYMTAB\fR. All relocations that refer to local symbols are updated to refer to the corresponding \fISECT\fR symbol. This option allows specialized objects to greatly reduce their symbol table sizes. See also the \fB-z\fR \fBstrip-class\fR and \fB-z\fR \fBnoldynsym\fR options. .sp Although useful for special objects such as those used within the operating system kernel, the \fB-z\fR \fBredlocsym\fR option is not recommended for general use. The size of the symbol table \fBSHT_SYMTAB\fR does not effect runtime behavior, and the elimination of local symbols can negatively effect process observability. Eliminated local symbols can reduce the debugging information that is generated using the compiler drivers \fB-g\fR option. Eliminated local symbols will also remove the information normally written to the \fB\&.SUNW_ldynsym\fR section, reducing the effectiveness of debuggers and tools such as \fBpstack\fR(1) and \fBtruss\fR(1). .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBrelax=\fR\fIitem1\fR\fB,\fR\fIitem2\fR\fB,...\fR\fR .ad .sp .6 .RS 4n The link-editor performs validity checks in order to ensure that the resulting output object is valid and usable at runtime. In addition, the link-editor can transition a variety of relocations to generate more optimal instruction sequences. .sp The \fB-z\fR \fBrelax\fR option can be used to relax these operations in order to produce an output object that would otherwise be rejected. .LP Note - .sp .RS 2 Disabling validity checks can result in the creation of a corrupt or otherwise unusable object. The \fB-z\fR \fBrelax\fR option is a specialized option, mainly of interest to compiler authors, and is not intended for general use. .RE The following \fBitem\fR tokens are recognized. .sp .ne 2 .mk .na \fB\fBcomdat\fR\fR .ad .sp .6 .RS 4n A relocation that remains against a symbol that has been eliminated as part of a \fBCOMDAT\fR section, results in a fatal error. The \fB-z\fR \fBrelax=comdat\fR option redirects such relocations to an equivalent symbol in a retained \fBCOMDAT\fR section. .RE .sp .ne 2 .mk .na \fB\fBcommon\fR\fR .ad .sp .6 .RS 4n Multiply-defined tentative data symbols, that have different sizes or different alignments, produce a warning. These conditions typically originate from Fortran common blocks. The \fB-z\fR \fBrelax=common\fR option disables this warning. .RE .sp .ne 2 .mk .na \fB\fBsecadj\fR\fR .ad .sp .6 .RS 4n \fBELF\fR objects require certain sections to be adjacent to each other in a specified order in the output object. This automatic layout can be disrupted by link-editor \fBmapfiles\fR that explicitly layout sections. An invalid layout results in a fatal error. The \fB-z\fR \fBrelax=secadj\fR option suppresses layout verification. .RE .sp .ne 2 .mk .na \fB\fBsymbound\fR\fR .ad .sp .6 .RS 4n Symbols that refer to data beyond the bounds of their associated section can result in invalid memory accesses. Such symbols result in a fatal error. The \fB-z\fR \fBrelax=symbound\fR option suppresses this error condition. .RE .sp .ne 2 .mk .na \fB\fBtransdisp\fR\fR .ad .sp .6 .RS 4n On SPARC, a family of \fBGOTDATA\fR relocations provide access to data relative to the Global Offset Table (\fBGOT\fR). Locally bound data items allow the link-editor to transition the associated code sequence to provide a more optimized access model. However, this model only provides for accessing the data within +/- 2 Gbytes of the \fBGOT\fR address. A relocation that exceeds this limit results in a fatal error. In the rare case that a data reference exceeds this limit, the \fB-z\fR \fBrelax=transdisp\fR option can be used to adjust \fBGOTOP\fR access model transitions. This relaxation removes the address range limit at the expense of a slightly less optimal code sequence. .RE .sp .ne 2 .mk .na \fB\fBtranstls\fR\fR .ad .sp .6 .RS 4n Thread-Local Storage (\fBTLS\fR) access provides numerous models for data access. See \fIThread-Local Storage Access Models\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. The link-editor can transition the associated code sequence based off the output file being created, and a symbols visibility. The \fB-z\fR \fBrelax=transtls\fR option suppresses \fBTLS\fR access model transitions. .RE .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBrelaxreloc\fR\fR .ad .sp .6 .RS 4n This option is equivalent to specifying the \fB-z\fR \fBrelax=comdat\fR option. .RE .sp .ne 2 .mk .na \fB\fB-z\fR \fBrescan\fR\fR .ad .sp .6 .RS 4n A position independent option that causes a rescan of the archive files that are provided to the link-edit. The link-editor defers the rescan operation until after it has processed the entire command line, and then initiates a final rescan operation over all archives seen on the command line. The \fB-z\fR \fBrescan\fR operation can interact incorrectly with objects that contain initialization (\&.init) or finalization (\&.fini) sections, preventing the code in those sections from running. For this reason, \fB-z\fR \fBrescan\fR is deprecated, and use of \fB-z\fR \fBrescan-now\fR is advised. .RE .SH ENVIRONMENT VARIABLES .sp .LP The following environment variables are recognized by the link-editor. Additional environment variables, prefixed with \fBLD_\fR, are available for use with the runtime linker. See \fBld.so.1\fR(1). .sp .ne 2 .mk .na \fB\fBLD_ALTEXEC\fR\fR .ad .sp .6 .RS 4n An alternative link-editor path name. The link-editor executes, and passes control to this alternative link-editor. This environment variable provides a generic means of overriding the default link-editor that is called from the various compiler drivers. .RE .sp .ne 2 .mk .na \fB\fBLD_LIBRARY_PATH\fR\fR .ad .sp .6 .RS 4n A list of directories in which to search for the libraries specified using the \fB-l\fR option. Multiple directories are separated by a colon. In the most general case, this environment variable contains two directory lists separated by a semicolon. .sp .in +2 .nf \fIdirlist1\fR\fB;\fR\fIdirlist2\fR .fi .in -2 .sp If the link-editor is called with any number of occurrences of \fB-L\fR, as in: .sp .in +2 .nf $ \fBld ... -L\fIpath1\fR ... -L\fIpathn\fR ...\fR .fi .in -2 .sp then the search path ordering is: .sp .in +2 .nf \fB\fIdirlist1 path1\fR ... \fIpathn dirlist2\fR LIBPATH\fR .fi .in -2 .sp When the list of directories does not contain a semicolon, the list is interpreted as \fIdirlist2\fR. .sp The \fBLD_LIBRARY_PATH\fR environment variable also affects the runtime linkers search for dynamic dependencies. .sp This environment variable can be specified with a _32 or _64 suffix. This makes the environment variable specific, respectively, to 32-bit or 64-bit processes and overrides any non-suffixed version of the environment variable that is in effect. .RE .sp .ne 2 .mk .na \fB\fBLD_NOEXEC_64\fR\fR .ad .sp .6 .RS 4n Prior to Solaris 12, the class of the link-editor that was executed was determined by the class of the underlying system, and could be 32-bit or 64-bit. The \fBLD_NOEXEC_64\fR environment variable was used to suppress the automatic execution of the 64-bit link-editor. In current systems, the link-editor is always 64-bit, and \fBLD_NOEXEC_64\fR is ignored and has no effect. This variable is maintained for backward compatibility with older versions of Solaris. .RE .sp .ne 2 .mk .na \fB\fBLD_OPTIONS\fR, \fBLD_UNSET\fR, \fBLD_{object-type}_UNSET\fR, \fBLD_{object-type}_OPTIONS\fR\fR .ad .sp .6 .RS 4n These environment variables provide a means of adding additional options, or removing existing options, from the link-editor command line. The \fIobject-type\fR provides the types, in uppercase, defined by the \fB-z type\fR option, and is one of \fBEXEC\fR, \fBPIE\fR, \fBRELOC\fR or \fBSHARED\fR. These variables provide for overriding, or unsetting, the command line options that are embedded in scripts and build environments. See OPTION PROCESSING. .RE .sp .ne 2 .mk .na \fB\fBLD_RUN_PATH\fR\fR .ad .sp .6 .RS 4n An alternative mechanism for specifying a runpath to the link-editor. See the \fB-R\fR option. If both \fBLD_RUN_PATH\fR and the \fB-R\fR option are specified, \fB-R\fR supersedes. .RE .sp .ne 2 .mk .na \fB\fBSGS_SUPPORT\fR\fR .ad .sp .6 .RS 4n Provides a colon-separated list of shared objects that are loaded with the link-editor and given information regarding the linking process. This environment variable can be specified with a _32 or _64 suffix. This makes the environment variable specific, respectively, to the 32-bit or 64-bit class of the link-editor and overrides any non-suffixed version of the environment variable that is in effect. See the \fB-S\fR option. .RE .sp .LP Notice that environment variable-names that begin with the characters '\fBLD_\fR' are reserved for possible future enhancements to \fBld\fR and \fBld.so.1\fR(1). .SH FILES .sp .ne 2 .mk .na \fB\fBlib\fIx\fR.so\fR\fR .ad .RS 15n .rt shared object libraries. .RE .sp .ne 2 .mk .na \fB\fBlib\fIx\fR.a\fR\fR .ad .RS 15n .rt archive libraries. .RE .sp .ne 2 .mk .na \fB\fBa.out\fR\fR .ad .RS 15n .rt default output file. .RE .sp .ne 2 .mk .na \fB\fILIBPATH\fR\fR .ad .RS 15n .rt For 32-bit libraries, the default search path is \fB/lib\fR, followed by \fB/usr/lib\fR. For 64-bit libraries, the default search path is \fB/lib/64\fR, followed by \fB/usr/lib/64\fR. .RE .sp .ne 2 .mk .na \fB\fB/usr/lib/ld\fR\fR .ad .RS 15n .rt A directory containing several \fBmapfiles\fR that can be used during link-editing. These \fBmapfiles\fR provide various capabilities, such as defining memory layouts, aligning bss, and defining non-executable stacks. .RE .SH ATTRIBUTES .sp .LP See \fBattributes\fR(5) for descriptions of the following attributes: .sp .sp .TS tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) . ATTRIBUTE TYPEATTRIBUTE VALUE _ Availabilitysystem/linker _ Interface StabilityCommitted .TE .SH SEE ALSO .sp .LP \fBas\fR(1), \fBcrle\fR(1), \fBelfcompress\fR(1), \fBgprof\fR(1), \fBld.so.1\fR(1), \fBldd\fR(1), \fBmcs\fR(1), \fBpvs\fR(1), \fBstrip\fR(1), \fBsxadm\fR(1M), \fBexec\fR(2), \fBstat\fR(2), \fBzlib\fR(3), \fBdlopen\fR(3C), \fBdldump\fR(3C), \fBelf\fR(3ELF), \fBar.h\fR(3HEAD), \fBa.out\fR(4), \fBattributes\fR(5) .sp .LP \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR .SH NOTES .sp .LP Default options applied by the link-editor are maintained for historic reasons. In today's programming environment, where dynamic objects dominate, alternative defaults would often make more sense. However, historic defaults must be maintained to ensure compatibility with existing program development environments. Historic defaults are called out wherever possible in this manual. For a description of the current recommended options, see Chapter 5, \fILink-Editor Quick Reference,\fR in \fIOracle Solaris 11.3 Linkers and Libraries Guide\fR. .sp .LP If the file being created by the link-editor already exists, the file is unlinked after all input files have been processed. A new file with the specified name is then created. This allows the link-editor to create a new version of the file, while simultaneously allowing existing processes that are accessing the old file contents to continue running. If the old file has no other links, the disk space of the removed file is freed when the last process referencing the file terminates. .sp .LP The behavior of the link-editor when the file being created already exists was changed with Oracle Solaris 11. In older versions, the existing file was rewritten in place, an approach with the potential to corrupt any running processes that is using the file. This change has an implication for output files that have multiple hard links in the file system. Previously, all links would remain intact, with all links accessing the new file contents. The new link-editor behavior \fBbreaks\fR such links, with the result that only the specified output file name references the new file. All the other links continue to reference the old file. To ensure consistent behavior, applications that rely on multiple hard links to linker output files should explicitly remove and relink the other file names.