From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.gentoo.org (woodpecker.gentoo.org [140.211.166.183]) by sourceware.org (Postfix) with ESMTP id B552B3858D1E for ; Fri, 4 Aug 2023 23:43:58 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org B552B3858D1E Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gentoo.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gentoo.org References: User-agent: mu4e 1.10.4; emacs 30.0.50 From: Arsen =?utf-8?Q?Arsenovi=C4=87?= To: Florian Weimer Cc: libc-alpha@sourceware.org Subject: Re: [PATCH 2/3] manual: Document ld.so --list-diagnostics output Date: Sat, 05 Aug 2023 01:33:50 +0200 In-reply-to: Message-ID: <86tttez83s.fsf@gentoo.org> MIME-Version: 1.0 Content-Type: multipart/signed; boundary="=-=-="; micalg=pgp-sha512; protocol="application/pgp-signature" X-Spam-Status: No, score=-9.6 required=5.0 tests=BAYES_00,GIT_PATCH_0,JMQ_SPF_NEUTRAL,KAM_DMARC_STATUS,RCVD_IN_MSPIKE_H3,RCVD_IN_MSPIKE_WL,SPF_HELO_PASS,SPF_PASS,TXREP autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: --=-=-= Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable Hi Florian, Florian Weimer writes: > --- > manual/dynlink.texi | 279 ++++++++++++++++++++++++++++++++++++++++++++ > 1 file changed, 279 insertions(+) > > diff --git a/manual/dynlink.texi b/manual/dynlink.texi > index 45bf5a5b55..fc2cd2f0a4 100644 > --- a/manual/dynlink.texi > +++ b/manual/dynlink.texi > @@ -13,9 +13,288 @@ as plugins) later at run time. > Dynamic linkers are sometimes called @dfn{dynamic loaders}. >=20=20 > @menu > +* Dynamic Linker Invocation:: Explicit invocation of the dynamic linke= r. > * Dynamic Linker Introspection:: Interfaces for querying mapping info= rmation. > @end menu >=20=20 > +@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 > +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=3D0x1000 > +The system page size is 4096 bytes. > + > +@item env[0x14]=3D"LANG=3Den_US.UTF-8" > +This item indicates that the 21st environment variable at process > +startup contains a setting for @code{LANG}. > + > +@item env_filtered[0x22]=3D"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=3D"/usr" > +This means that @theglibc{} was configured with @code{--prefix=3D/usr}. > + > +@item path.system_dirs[0x0]=3D"/lib64/" > +@itemx path.system_dirs[0x1]=3D"/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 > +sequences 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) independently 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 =3D %x30-39 / %x61-6f ; lowercase a-f only > +ALPHA =3D %x41-5a / %x61-7a / %x7f ; letters and underscore > +ALPHA-NUMERIC =3D ALPHA / %x30-39 / "_" > +DQUOTE =3D %x22 ; " > + > +; Numbers are always hexadecimal and use a 0x prefix. > +hex-value-prefix =3D %x30 %x78 > +hex-value =3D hex-value-prefix 1*HEXDIG > + > +; Strings use octal escape sequences and \\, \". > +string-char =3D %x20-21 / %x23-5c / %x5d-7e ; printable but not "\ > +string-quoted-octal =3D %x30-33 2*2%x30-37 > +string-quoted =3D "\" ("\" / DQUOTE / string-quoted-octal) > +string-value =3D DQUOTE *(string-char / string-quoted) DQUOTE > + > +value =3D hex-value / string-value > + > +label =3D ALPHA *ALPHA-NUMERIC > +index =3D "[" hex-value "]" > +subscript =3D label [index] > + > +line =3D subscript *("." subscript) "=3D" value > +@end smallexample > + > +Output lines can be parsed with the following Python function. It > +assumes lines formatted according to the ABNF @code{line} production > +above. > + > +@c PYTHON-START > +@smallexample > +def parse_line(line): > + """Parse a line of --list-diagnostics output. > + > + This function returns a pair (SUBSCRIPTS, VALUE). VALUE is either > + a byte string or an integer. SUBSCRIPT is a tuple of (LABEL, > + INDEX) pairs, where LABEL is a field identifier (a string), and > + INDEX is an integer or None, to indicate that this field is not > + indexed. > + > + """ > + > + # Extract the list of subscripts before the value. > + idx =3D 0 > + subscripts =3D [] > + while line[idx] !=3D '=3D': > + start_idx =3D idx > + > + # Extract the label. > + while line[idx] not in '[.=3D': > + idx +=3D 1 > + label =3D line[start_idx:idx] > + > + if line[idx] =3D=3D '[': > + # Subscript with a 0x index. > + assert label > + close_bracket =3D line.index(']', idx) > + index =3D line[idx + 1:close_bracket] > + assert index.startswith('0x') > + index =3D int(index, 0) > + subscripts.append((label, index)) > + idx =3D close_bracket + 1 > + else: # '.' or '=3D'. > + if label: > + subscripts.append((label, None)) > + if line[idx] =3D=3D '.': > + idx +=3D 1 > + > + # The value is either a string or a 0x number. > + value =3D line[idx + 1:] > + if value[0] =3D=3D '"': > + # Decode the escaped string into a byte string. > + assert value[-1] =3D=3D '"' > + idx =3D 1 > + result =3D [] > + while True: > + ch =3D value[idx] > + if ch =3D=3D '\\': > + if value[idx + 1] in '"\\': > + result.append(ord(value[idx + 1])) > + idx +=3D 2 > + else: > + result.append(int(value[idx + 1:idx + 4], 8)) > + idx +=3D 4 > + elif ch =3D=3D '"': > + assert idx =3D=3D len(value) - 1 > + break > + else: > + result.append(ord(value[idx])) > + idx +=3D 1 > + value =3D bytes(result) > + else: > + # Convert the value into an integer. > + assert value.startswith('0x') > + value =3D int(value, 0) > + return (tuple(subscripts), 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. > + > +@table @code > +@item dl_dst_lib=3D@var{string} > +The @code{$LIB} dynamic string token expands to @var{string}. > + > +@item dl_hwcap=3D@var{integer} > +@itemx dl_hwcap2=3D@var{integer} > +@cindex HWCAP (diagnostics) > +The HWCAP and HWCAP2 values, as returned for @code{getauxval}, and as > +used in other places depending on the architecture. Please put indices before @items they refer to. I've recently gone over all GCC manuals to correct for this exact error, as we've made some upstream changes to Texinfo rely on index-then-item ordering to provide a nice pilcrow anchor for copyable links. See https://inbox.sourceware.org/gcc-patches/20230223102714.3606058-3-arsen@aar= sen.me/ for some context, as well as the GCC docs for the resulting pilcrows (note that there's no Texinfo release which will demonstrate this yet, so we use a snapshot for GCC). > +@item dl_pagesize=3D@var{integer} > +@cindex page size (diagnostics) > +The system page size is @var{integer} bytes. > + > +@item dl_platform=3D@var{string} > +The @code{$PLATFORM} dynamic string token expands to @var{string}. > + > +@item dso.libc=3D@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}]=3D@var{string} > +@itemx env_filtered[@var{index}]=3D@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{=3D} (assumi= ng > +that it was present), variables under @code{env_filtered} do not. > + > +@item path.prefix=3D@var{string} > +This indicates that @theglibc{} was configured using > +@samp{--prefix=3D@var{string}}. > + > +@item path.sysconfdir=3D@var{string} > +@Theglibc{} was configured (perhaps implicitly) with > +@samp{--sysconfdir=3D@var{string}} (typically @code{/etc}). > + > +@item path.system_dirs[@var{index}]=3D@var{string} > +These items list the elements of the built-in array that describes the > +default library search path. The value @var{string} a directory file > +name with a trailing @samp{/}. > + > +@item path.rtld=3D@var{string} > +This string indicates the application binary interface (ABI) file name > +of the run-time dynamic linker. > + > +@item version.release=3D"stable" > +@itemx version.release=3D"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. > + > +@item version.version=3D"@var{major}.@var{minor}" > +@itemx version.version=3D"@var{major}.@var{minor}.9000" > +@cindex version (diagnostics) > +@Theglibc{} version. Development releases end in @samp{.9000}. > + > +@item auxv[@var{index}].a_type=3D@var{type} > +@itemx auxv[@var{index}].a_val=3D@var{integer} > +@itemx auxv[@var{index}].a_val_string=3D@var{string} > +@cindex auxiliary vector (diagnostics) > +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=3D@var{string} > +@itemx uname.nodename=3D@var{string} > +@itemx uname.release=3D@var{string} > +@itemx uname.version=3D@var{string} > +@itemx uname.machine=3D@var{string} > +@itemx uname.domain=3D@var{string} > +These Linux-specific items show the values of @code{struct utsname}, as > +reported by the @code{uname} function. @xref{Platform Type}. > + > +@item x86.cpu_features.@dots{} > +@cindex CPUID (diagnostics) > +These items are specific to the i386 and x86-64 architectures. They > +reflect supported CPU feature and information on cache geometry, mostly > +collected using the @code{CPUID} instruction. > +@end table > + > @node Dynamic Linker Introspection > @section Dynamic Linker Introspection Thank you! Have a lovely night. =2D-=20 Arsen Arsenovi=C4=87 --=-=-= Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iOcEARYKAI8WIQT+4rPRE/wAoxYtYGFSwpQwHqLEkwUCZM2NN18UgAAAAAAuAChp c3N1ZXItZnByQG5vdGF0aW9ucy5vcGVucGdwLmZpZnRoaG9yc2VtYW4ubmV0RkVF MkIzRDExM0ZDMDBBMzE2MkQ2MDYxNTJDMjk0MzAxRUEyQzQ5MxEcYXJzZW5AZ2Vu dG9vLm9yZwAKCRBSwpQwHqLEk8J5AP9gRdNKGs5iSCWCBgEh6OSQA3EpKcg9/w1Q 8dru+YjJxAD/QvgPGZbbX5xKG22Xb6Li02uKhH07ZJGr36IgUvZuTwY= =Rp6z -----END PGP SIGNATURE----- --=-=-=--