Re: [PATCH] Resend: Add a new chapter on the dynamic linker

[Joseph Myers <joseph at codesourcery dot com>]

On Thu, 12 Oct 2017, Ben Woodard wrote:

>     Add a new chapter covering dynamic linking to the glibc manual. Remove
>     previous placeholder documents.
> 
>     Can we restart the review process on this with the intent of this
>     getting merged. It has been through review once and all concerns
>     were addressed however this patch was never merged.

The following are just a few observations of things I noticed from looking 
at this document (each should be considered globally as the issue may 
appear many times but just be noted once).  This is *not* a general review 
of the patch.  I agree that dynamic linking should be documented in the 
glibc manual, and think the general outline of this document is 
reasonable.

A high-level design principle of dynamic linking is that things that work 
with static linking should also work with dynamic linking.  This has 
implications for the main program being able to reference functions and 
variables in a shared library without it being known at compile time 
whether those will come from a shared library or elsewhere in the main 
executable.  The less obvious consequences (e.g. regarding how the static 
linker handles references to variables with aliases) are off-topic for 
this manual, but maybe it makes sense to talk explicitly about how it's 
not known when the executable is compiled whether symbols will come from a 
shared library.  (Especially as this is different from some non-ELF models 
that may require e.g. dllimport markers.)

> +On every operating system currently supported by @theglibc{}, the
> +operating system provides a facility for run time dynamic

Adjective "run-time" (when referring to the time at which the program is 
run, as opposed to the C runtime library; see GCC's codingconventions.html 
for different variants of "run time", "run-time" and "runtime" and when 
each is correct).  Likewise elsewhere (and for other such adjectives).

> +linking. This facility is implemented by @theglibc{}'s dynamic linker.
> +This benefits the operating system by allowing the resident RAM used
> +by libraries to be shared between processes. Runtime dynamic linking

General observation, two spaces after "." in Texinfo source.

> +Because run time linking is so intimately involved with the lauching

"launching".  Running a spell check in this document would be a good idea.

> +The same run time dynamic linking capability which allows applications
> +to be loaded along with their libraries at initial execution time has
> +also been made available to application programmers through a group of
> +run time dynamic linker function explained below. This facility is

"functions".

> +The run time dynamic linker also provides several mechanisms which
> +allow the system administrator or user to modify its operation when
> +running an application. Many of the tools to modify glibc's run time

"@theglibc{}'s".

> +outside of a particular compilation unit. If you link object files
> +then the linker is able to find the location of referenced symbols or
> +functions in other compilation unit's object files, insert them into

"units'", as you're referring to the object files of multiple compilation 
units.

> +Libraries are a special kind object file which include the partially

"kind of object file".

> +linked aggregation of many compilation unit's object files. You can

"units'".

> +to run the executable. The shared libraries needed by am executable or

"an executable".

> +a library are stored in dynamic section of the ELF header. The list of

"the dynamic section".

> +The full set libraries needed by an executable or a library and all of

"set of libraries".

> +implementing the the @code{la_objsearch()} function.

GNU style does not use () when referring to a function.

> +@findex la_objsearch
> +
> +If a library listed as NEEDED includes a slash in its name, then it is
> +assumed to be either an absolute or relative pathname as is often the
> +case when a library is specified on the command line. When a pathname
> +is found as the target of the NEEDED section it is resolved as such.

The GNU Coding Standards say to use "file name", not "pathname".

> +@vindex LD_LIBRARY_PATH
> +@cindex RPATH
> +@cindex DT_RPATH
> +Sometimes a library's location will be explicitly referenced using a
> +deprecated feature called a RPATH. Specifying the location of a

"an RPATH".

> +library using RPATHs is not recommended for a variety of reasons
> +including the fact that it its extremely high precedence makes it

"it its" -> "its".

> +Very occasionally RPATH and RUNPATH may include some macros that will
> +be expanded before objects search is performed in the directories
> +specified. Users are encouraged to look at the linux ld.so man page
> +for more details.

"Linux" should only be used strictly to refer to the kernel.  This is 
nothing to do with the kernel.  I don't think referring to GNU/Linux is 
really right here either; $ORIGIN at least ought to be documented in this 
manual rather than relying on some third-party documentation.

> +@pindex ldconfig
> +@cindex ld.so.conf
> +@command{ldconfig} will cache the location of the libraries in the trusted
> +library directories (@file{/lib} and @file{/usr/lib} and also
> +@file{/lib64} and @file{/usr/lib64} on 64bit systems). The operating

There are more library directory variants for different ports of glibc - 
some have lib32 or libx32 (and AArch64 ILP32, not yet included in glibc, 
has libilp32).

> +@node Finding a Symbol
> +@subsection Finding a Symbol
> +When two objects are linked dynamically, the location of symbols which
> +are referenced in one object file which exist an an other object file

"in another".

> +cannot be resolved until run time. This is because the location within
> +a process's address space where a library will be loaded is
> +intentionally slightly non-deterministic to make hacking more
> +difficult and because different applications can load the same object

Although the GNU Coding Standards don't specifically say that "hacking" 
should not be used to refer to breaking into computers, I think we can 
take it as obvious, especially given the usage of "hacker" therein.

> +@node Binding a Variable
> +@subsection Binding a Variable
> +Binding a variable is the process of patching the location of a symbol
> +in the processes current address space into the code which refers to
> +it. There might be hundreds if not thousands of uses of a particular
> +variabletherefore patching in the location into every one of those

"variable therefore".

> +flags that this region is both wriable and dynamically allocated. At

"writable".

This section seems to be missing any discussion of the case of the main 
(non-PIC) program accessing a variable in a shared library (and how the 
copy of the variable in the program ends up as the main copy in that 
case).

> +The way this is accomplished is through another section of read-only
> +executable code called the Procedure Linkage Table, or PLT. The
> +executing code calls a tiny bit of stub code in the PLT. This stub
> +code jumps to the location of an associated entry in the GOT. This is

It jumps to a location *pointed to* by a GOT entry.  It does not jump into 
the GOT (which is writable and should not be executable).

> +After a function is bound, the entry in the GOT pointed to by the PLT
> +stub code will contain the address of the function in the process's
> +address space. Before the function is bound, usually at the time when
> +the object is loaded, the dynamic later inserts value in the GOT that

"dynamic linker inserts a value".

> +it is loaded before the dynamic linker object @code{ld_linux} is

The dynamic linker object has lots of different names on different 
systems.

> +@node la_objsearch
> +@subsection la_objsearch
> +@deftypefun char *la_objsearch(const char *@var{name}, uintptr_t *@var{cookie}, unsigned int @var{flag})
> +@safety{@prelim{}@mtsafe{}@assafe{}@acunsafe{}}
> +@findex la_objsearch
> +
> +Within a run time linker audit library @code{la_obsearch()} is

la_objsearch or la_obsearch?  (And avoiding (), as elsewhere.)

> +@var{LA_SER_ORIG} This is the original name either found in the ELF
> +dynamic header or the parameter passed in by dlopen(3).

@code{dlopen}, don't use man-page section references.

> +@var{LA_SER_CONFIG} This is the name found in

@var is for metasyntactic variables, not for any literal source code 
string.

> +expected. This will only happen if ldconfig has never been run or if

@command{ldconfig}.

> +@findex dlclose
> +When the libraries are loaded as part of the standard process startup,
> +they are not closed when a process exits therefore this function is
> +not called except as a result of @code{dlclose()}

Missing trailing ".".

-- 
Joseph S. Myers
joseph@codesourcery.com