git: 914cb28ba291 - stable/13 - Document library types in the intro(3) manual page

From: Gordon Bergling <>
Date: Fri, 08 Dec 2023 21:57:49 UTC
The branch stable/13 has been updated by gbe:


commit 914cb28ba29175552d7afab4a2e0f1af59e21e8f
Author:     Gordon Bergling <>
AuthorDate: 2023-11-16 09:48:09 +0000
Commit:     Gordon Bergling <>
CommitDate: 2023-12-08 21:57:32 +0000

    Document library types in the intro(3) manual page
    Add a paragraph about library types to the intro(3)
    manual page. Document library types, locations
    and versioning.
    Reviewed by:    emaste, jilles, mhorne,
    Obtained from:  OpenBSD (partial)
    Differential Revision:
    (cherry picked from commit 54611b7cc69cee34e7bcdc2324a9159e7543a125)
 share/man/man3/intro.3 | 97 ++++++++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 94 insertions(+), 3 deletions(-)

diff --git a/share/man/man3/intro.3 b/share/man/man3/intro.3
index c36ab620bed3..bfae9093af93 100644
--- a/share/man/man3/intro.3
+++ b/share/man/man3/intro.3
@@ -26,8 +26,7 @@
 .\"     @(#)intro.3	8.1 (Berkeley) 6/5/93
-.Dd November 7, 2022
+.Dd November 16, 2023
 .Dt INTRO 3
@@ -278,13 +277,105 @@ the math library
 .It Pa /usr/lib/libm_p.a
 the math library compiled for profiling
+The system libraries are located in
+.Pa /lib
+.Pa /usr/lib .
+A library has the following naming convention:
+.Bd -unfilled -offset indent
+Libraries with an
+.Sq .a
+suffix are static.
+When a program is linked against a static library, all necessary library code
+will be included in the binary.
+This means the binary can be run even when the libraries are unavailable.
+However, it can be inefficient with both disk space and memory usage
+during execution.
+The C compiler,
+.Xr cc 1 ,
+can be instructed to link statically by specifying the
+.Fl static
+Libraries with a
+.Sq .so.X
+suffix are dynamic libraries.
+When code is linked dynamically, the library code that the application needs
+is not included in the binary.
+Instead, data structures are added containing information about which dynamic
+libraries to link with.
+When the binary is executed, the run-time linker
+.Xr 1
+reads these data structures and loads them into the
+process virtual address space.
+.Xr rtld 1
+loads the shared libraries when the program is executed.
+.Sq X
+represents the library version number of the library.
+In the example above, a binary linked with
+would not be usable on a system where only
+is available.
+The advantages of dynamic libraries are that multiple instances of the same
+library can share address space, and the physical size of the binary is
+A namespace per shared library is available via hidden visibility,
+allowing multiple compilation units in a library to share things without
+making them available to other libraries.
+It is possible to load libraries dynamically via
+.Xr dlopen 3 .
+The disadvantage is the added complexity that comes with loading the
+libraries dynamically, and the extra time taken to load the libraries.
+Of course, if the libraries are not available, the binary will be unable
+to execute.
+Calls across shared libraries are also slightly slower and cannot be
+inlined, not even with link time optimization.
+The C compiler,
+.Xr cc 1 ,
+can be instructed to link dynamically by specifying the
+.Fl shared
+Shared libraries, as well as static libraries on architectures which produce
+position-independent executables
+.Pq PIEs
+by default, contain position-independent code
+.Pq PIC .
+Normally, compilers produce relocatable code.
+Relocatable code needs to be modified at run-time, depending on where in
+memory it is to be run.
+The C compiler,
+.Xr cc 1 ,
+can be instructed to generate PIC code by specifying the
+.Fl fPIC
+Static libraries are generated using the
+.Xr ar 1
+The libraries contain an index to the contents of the library,
+stored within the library itself.
+The index lists each symbol defined by a member of a library that is a
+relocatable object file.
+This speeds up linking to the library, and allows routines in the library
+to call each other regardless of their placement within the library.
+.Xr ar 1 ,
 .Xr cc 1 ,
 .Xr ld 1 ,
 .Xr nm 1 ,
 .Xr intro 2 ,
 .Xr math 3 ,
-.Xr stdio 3
+.Xr stdio 3 ,
+.Xr make.conf 5 ,
+.Xr src.conf 5