diff --git a/share/man/man3/intro.3 b/share/man/man3/intro.3 --- a/share/man/man3/intro.3 +++ b/share/man/man3/intro.3 @@ -28,7 +28,7 @@ .\" @(#)intro.3 8.1 (Berkeley) 6/5/93 .\" $FreeBSD$ .\" -.Dd December 18, 2021 +.Dd September 15, 2022 .Dt INTRO 3 .Os .Sh NAME @@ -272,13 +272,132 @@ .It Pa /usr/lib/libm_p.a the math library compiled for profiling .El +.Sh LIBRARY TYPES +The system libraries are located in +.Pa /usr/lib . +Typically, a library will have a number of variants: +.Bd -unfilled -offset indent +libc.a +libc_p.a +libc.so.30.1 +.Ed +.Pp +Libraries with an +.Sq .a +suffix are static. +When a program is linked against a library, all the library code +will be linked into the binary. +This means the binary can be run even when the libraries are unavailable. +However, it can be inefficient with memory usage. +The C compiler, +.Xr cc 1 , +can be instructed to link statically by specifying the +.Fl static +flag. +.Pp +Libraries with a +.Sq _p.a +suffix are profiling libraries. +They contain extra information suitable for analysing programs, +such as execution speed and call counts. +This in turn can be interpreted by utilities such as +.Xr gprof 1 . +The C compiler, +.Xr cc 1 , +can be instructed to generate profiling code, +or to link with profiling libraries, by specifying the +.Fl pg +flag. +.Pp +Libraries with a +.Sq .so.X.Y +suffix are dynamic libraries. +When code is compiled dynamically, the library code that the application needs +is not linked into 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 ld.so 1 +reads these data structures, and loads them at a virtual address using the +.Xr mmap 2 +system call. +.Pp +.Sq X +represents the major number of the library, and +.Sq Y +represents the minor number. +In general, a binary will be able to use a dynamic library with a differing +minor number, but the major numbers must match. +In the example above, a binary linked with minor number +.Sq 3 +would be linkable against libc.so.30.1, +while a binary linked with major number +.Sq 31 +would not. +.Pp +The advantages of dynamic libraries are that multiple instances of the same +program can share address space, and the physical size of the binary is +smaller. +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. +The C compiler, +.Xr cc 1 , +can be instructed to link dynamically by specifying the +.Fl shared +flag, although on systems that support it, this will be the default and +need not be specified. +.Pp +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. +PIC code does not need to be modified at run-time, but is less efficient than +relocatable code. +The C compiler, +.Xr cc 1 , +can be instructed to generate PIC code by specifying the +.Fl fpic +or +.Fl fPIC +flags. +.Pp +With the exception of dynamic libraries, libraries are generated using the +.Xr ar 1 +utility. +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. +The index is created by +.Xr ranlib 1 +and can be viewed using +.Xr nm 1 . +.Pp +The building of profiling versions of libraries can +be prevented by setting the variable +.Dv WITHOUT_PROFILE +in +.Pa /etc/src.conf . +See +.Xr make.conf 5 +for more details. .Sh SEE ALSO .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 .Sh HISTORY An .Nm