230 lines
8.3 KiB
Diff
230 lines
8.3 KiB
Diff
commit f21962ddfc8bb23e92597da1f98e313dbde11cc1
|
|
Author: Florian Weimer <fweimer@redhat.com>
|
|
Date: Fri Aug 25 14:15:28 2023 +0200
|
|
|
|
manual: Document ld.so --list-diagnostics output
|
|
|
|
Reviewed-by: Adhemerval Zanella <adhemerval.zanella@linaro.org>
|
|
|
|
diff --git a/manual/dynlink.texi b/manual/dynlink.texi
|
|
index 45bf5a5b55..df41c56bfc 100644
|
|
--- a/manual/dynlink.texi
|
|
+++ b/manual/dynlink.texi
|
|
@@ -13,9 +13,216 @@ as plugins) later at run time.
|
|
Dynamic linkers are sometimes called @dfn{dynamic loaders}.
|
|
|
|
@menu
|
|
+* Dynamic Linker Invocation:: Explicit invocation of the dynamic linker.
|
|
* Dynamic Linker Introspection:: Interfaces for querying mapping information.
|
|
@end menu
|
|
|
|
+@node Dynamic Linker Invocation
|
|
+
|
|
+@cindex program interpreter
|
|
+When a dynamically linked program starts, the operating system
|
|
+automatically loads the dynamic linker along with the program.
|
|
+@Theglibc{} also supports invoking the dynamic linker explicitly to
|
|
+launch a program. This command uses the implied dynamic linker
|
|
+(also sometimes called the @dfn{program interpreter}):
|
|
+
|
|
+@smallexample
|
|
+sh -c 'echo "Hello, world!"'
|
|
+@end smallexample
|
|
+
|
|
+This command specifies the dynamic linker explicitly:
|
|
+
|
|
+@smallexample
|
|
+ld.so /bin/sh -c 'echo "Hello, world!"'
|
|
+@end smallexample
|
|
+
|
|
+Note that @command{ld.so} does not search the @env{PATH} environment
|
|
+variable, so the full file name of the executable needs to be specified.
|
|
+
|
|
+The @command{ld.so} program supports various options. Options start
|
|
+@samp{--} and need to come before the program that is being launched.
|
|
+Some of the supported options are listed below.
|
|
+
|
|
+@table @code
|
|
+@item --list-diagnostics
|
|
+Print system diagnostic information in a machine-readable format.
|
|
+@xref{Dynamic Linker Diagnostics}.
|
|
+@end table
|
|
+
|
|
+@menu
|
|
+* Dynamic Linker Diagnostics:: Obtaining system diagnostic information.
|
|
+@end menu
|
|
+
|
|
+@node Dynamic Linker Diagnostics
|
|
+@section Dynamic Linker Diagnostics
|
|
+@cindex diagnostics (dynamic linker)
|
|
+
|
|
+The @samp{ld.so --list-diagnostics} produces machine-readable
|
|
+diagnostics output. This output contains system data that affects the
|
|
+behavior of @theglibc{}, and potentially application behavior as well.
|
|
+
|
|
+The exact set of diagnostic items can change between releases of
|
|
+@theglibc{}. The output format itself is not expected to change
|
|
+radically.
|
|
+
|
|
+The following table shows some example lines that can be written by the
|
|
+diagnostics command.
|
|
+
|
|
+@table @code
|
|
+@item dl_pagesize=0x1000
|
|
+The system page size is 4096 bytes.
|
|
+
|
|
+@item env[0x14]="LANG=en_US.UTF-8"
|
|
+This item indicates that the 21st environment variable at process
|
|
+startup contains a setting for @code{LANG}.
|
|
+
|
|
+@item env_filtered[0x22]="DISPLAY"
|
|
+The 35th environment variable is @code{DISPLAY}. Its value is not
|
|
+included in the output for privacy reasons because it is not recognized
|
|
+as harmless by the diagnostics code.
|
|
+
|
|
+@item path.prefix="/usr"
|
|
+This means that @theglibc{} was configured with @code{--prefix=/usr}.
|
|
+
|
|
+@item path.system_dirs[0x0]="/lib64/"
|
|
+@itemx path.system_dirs[0x1]="/usr/lib64/"
|
|
+The built-in dynamic linker search path contains two directories,
|
|
+@code{/lib64} and @code{/usr/lib64}.
|
|
+@end table
|
|
+
|
|
+@subsection Dynamic Linker Diagnostics Output Format
|
|
+
|
|
+As seen above, diagnostic lines assign values (integers or strings) to a
|
|
+sequence of labeled subscripts, separated by @samp{.}. Some subscripts
|
|
+have integer indices associated with them. The subscript indices are
|
|
+not necessarily contiguous or small, so an associative array should be
|
|
+used to store them. Currently, all integers fit into the 64-bit
|
|
+unsigned integer range. Every access path to a value has a fixed type
|
|
+(string or integer) independent of subscript index values. Likewise,
|
|
+whether a subscript is indexed does not depend on previous indices (but
|
|
+may depend on previous subscript labels).
|
|
+
|
|
+A syntax description in ABNF (RFC 5234) follows. Note that
|
|
+@code{%x30-39} denotes the range of decimal digits. Diagnostic output
|
|
+lines are expected to match the @code{line} production.
|
|
+
|
|
+@c ABNF-START
|
|
+@smallexample
|
|
+HEXDIG = %x30-39 / %x61-6f ; lowercase a-f only
|
|
+ALPHA = %x41-5a / %x61-7a / %x7f ; letters and underscore
|
|
+ALPHA-NUMERIC = ALPHA / %x30-39 / "_"
|
|
+DQUOTE = %x22 ; "
|
|
+
|
|
+; Numbers are always hexadecimal and use a 0x prefix.
|
|
+hex-value-prefix = %x30 %x78
|
|
+hex-value = hex-value-prefix 1*HEXDIG
|
|
+
|
|
+; Strings use octal escape sequences and \\, \".
|
|
+string-char = %x20-21 / %x23-5c / %x5d-7e ; printable but not "\
|
|
+string-quoted-octal = %x30-33 2*2%x30-37
|
|
+string-quoted = "\" ("\" / DQUOTE / string-quoted-octal)
|
|
+string-value = DQUOTE *(string-char / string-quoted) DQUOTE
|
|
+
|
|
+value = hex-value / string-value
|
|
+
|
|
+label = ALPHA *ALPHA-NUMERIC
|
|
+index = "[" hex-value "]"
|
|
+subscript = label [index]
|
|
+
|
|
+line = subscript *("." subscript) "=" value
|
|
+@end smallexample
|
|
+
|
|
+@subsection Dynamic Linker Diagnostics Values
|
|
+
|
|
+As mentioned above, the set of diagnostics may change between
|
|
+@theglibc{} releases. Nevertheless, the following table documents a few
|
|
+common diagnostic items. All numbers are in hexadecimal, with a
|
|
+@samp{0x} prefix.
|
|
+
|
|
+@table @code
|
|
+@item dl_dst_lib=@var{string}
|
|
+The @code{$LIB} dynamic string token expands to @var{string}.
|
|
+
|
|
+@cindex HWCAP (diagnostics)
|
|
+@item dl_hwcap=@var{integer}
|
|
+@itemx dl_hwcap2=@var{integer}
|
|
+The HWCAP and HWCAP2 values, as returned for @code{getauxval}, and as
|
|
+used in other places depending on the architecture.
|
|
+
|
|
+@cindex page size (diagnostics)
|
|
+@item dl_pagesize=@var{integer}
|
|
+The system page size is @var{integer} bytes.
|
|
+
|
|
+@item dl_platform=@var{string}
|
|
+The @code{$PLATFORM} dynamic string token expands to @var{string}.
|
|
+
|
|
+@item dso.libc=@var{string}
|
|
+This is the soname of the shared @code{libc} object that is part of
|
|
+@theglibc{}. On most architectures, this is @code{libc.so.6}.
|
|
+
|
|
+@item env[@var{index}]=@var{string}
|
|
+@itemx env_filtered[@var{index}]=@var{string}
|
|
+An environment variable from the process environment. The integer
|
|
+@var{index} is the array index in the environment array. Variables
|
|
+under @code{env} include the variable value after the @samp{=} (assuming
|
|
+that it was present), variables under @code{env_filtered} do not.
|
|
+
|
|
+@item path.prefix=@var{string}
|
|
+This indicates that @theglibc{} was configured using
|
|
+@samp{--prefix=@var{string}}.
|
|
+
|
|
+@item path.sysconfdir=@var{string}
|
|
+@Theglibc{} was configured (perhaps implicitly) with
|
|
+@samp{--sysconfdir=@var{string}} (typically @code{/etc}).
|
|
+
|
|
+@item path.system_dirs[@var{index}]=@var{string}
|
|
+These items list the elements of the built-in array that describes the
|
|
+default library search path. The value @var{string} is a directory file
|
|
+name with a trailing @samp{/}.
|
|
+
|
|
+@item path.rtld=@var{string}
|
|
+This string indicates the application binary interface (ABI) file name
|
|
+of the run-time dynamic linker.
|
|
+
|
|
+@item version.release="stable"
|
|
+@itemx version.release="development"
|
|
+The value @code{"stable"} indicates that this build of @theglibc{} is
|
|
+from a release branch. Releases labeled as @code{"development"} are
|
|
+unreleased development versions.
|
|
+
|
|
+@cindex version (diagnostics)
|
|
+@item version.version="@var{major}.@var{minor}"
|
|
+@itemx version.version="@var{major}.@var{minor}.9000"
|
|
+@Theglibc{} version. Development releases end in @samp{.9000}.
|
|
+
|
|
+@cindex auxiliary vector (diagnostics)
|
|
+@item auxv[@var{index}].a_type=@var{type}
|
|
+@itemx auxv[@var{index}].a_val=@var{integer}
|
|
+@itemx auxv[@var{index}].a_val_string=@var{string}
|
|
+An entry in the auxiliary vector (specific to Linux). The values
|
|
+@var{type} (an integer) and @var{integer} correspond to the members of
|
|
+@code{struct auxv}. If the value is a string, @code{a_val_string} is
|
|
+used instead of @code{a_val}, so that values have consistent types.
|
|
+
|
|
+The @code{AT_HWCAP} and @code{AT_HWCAP2} values in this output do not
|
|
+reflect adjustment by @theglibc{}.
|
|
+
|
|
+@item uname.sysname=@var{string}
|
|
+@itemx uname.nodename=@var{string}
|
|
+@itemx uname.release=@var{string}
|
|
+@itemx uname.version=@var{string}
|
|
+@itemx uname.machine=@var{string}
|
|
+@itemx uname.domain=@var{string}
|
|
+These Linux-specific items show the values of @code{struct utsname}, as
|
|
+reported by the @code{uname} function. @xref{Platform Type}.
|
|
+
|
|
+@cindex CPUID (diagnostics)
|
|
+@item x86.cpu_features.@dots{}
|
|
+These items are specific to the i386 and x86-64 architectures. They
|
|
+reflect supported CPU features and information on cache geometry, mostly
|
|
+collected using the @code{CPUID} instruction.
|
|
+@end table
|
|
+
|
|
@node Dynamic Linker Introspection
|
|
@section Dynamic Linker Introspection
|
|
|