Changeset View
Standalone View
share/man/man3/intro.3
Show All 20 Lines | |||||||||||||||||||||||||||
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | ||||||||||||||||||||||||||
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | ||||||||||||||||||||||||||
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | ||||||||||||||||||||||||||
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | ||||||||||||||||||||||||||
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | ||||||||||||||||||||||||||
.\" SUCH DAMAGE. | .\" SUCH DAMAGE. | ||||||||||||||||||||||||||
.\" | .\" | ||||||||||||||||||||||||||
.\" @(#)intro.3 8.1 (Berkeley) 6/5/93 | .\" @(#)intro.3 8.1 (Berkeley) 6/5/93 | ||||||||||||||||||||||||||
.\" | .Dd November 16, 2023 | ||||||||||||||||||||||||||
.Dd November 7, 2022 | |||||||||||||||||||||||||||
.Dt INTRO 3 | .Dt INTRO 3 | ||||||||||||||||||||||||||
.Os | .Os | ||||||||||||||||||||||||||
.Sh NAME | .Sh NAME | ||||||||||||||||||||||||||
.Nm intro | .Nm intro | ||||||||||||||||||||||||||
.Nd introduction to the C libraries | .Nd introduction to the C libraries | ||||||||||||||||||||||||||
.Sh SYNOPSIS | .Sh SYNOPSIS | ||||||||||||||||||||||||||
.Nm cc | .Nm cc | ||||||||||||||||||||||||||
.Op Ar flags | .Op Ar flags | ||||||||||||||||||||||||||
▲ Show 20 Lines • Show All 234 Lines • ▼ Show 20 Lines | |||||||||||||||||||||||||||
the C library | the C library | ||||||||||||||||||||||||||
.It Pa /usr/lib/libc_p.a | .It Pa /usr/lib/libc_p.a | ||||||||||||||||||||||||||
the C library compiled for profiling | the C library compiled for profiling | ||||||||||||||||||||||||||
.It Pa /usr/lib/libm.a | .It Pa /usr/lib/libm.a | ||||||||||||||||||||||||||
the math library | the math library | ||||||||||||||||||||||||||
.It Pa /usr/lib/libm_p.a | .It Pa /usr/lib/libm_p.a | ||||||||||||||||||||||||||
the math library compiled for profiling | the math library compiled for profiling | ||||||||||||||||||||||||||
.El | .El | ||||||||||||||||||||||||||
.Sh LIBRARY TYPES | |||||||||||||||||||||||||||
The system libraries are located in | |||||||||||||||||||||||||||
.Pa /lib | |||||||||||||||||||||||||||
pauamma_gundo.com: /lib too maybe? | |||||||||||||||||||||||||||
and | |||||||||||||||||||||||||||
.Pa /usr/lib . | |||||||||||||||||||||||||||
A library has the following naming convention: | |||||||||||||||||||||||||||
.Bd -unfilled -offset indent | |||||||||||||||||||||||||||
Done Inline Actionswe don't/wont have these any longer emaste: we don't/wont have these any longer | |||||||||||||||||||||||||||
Done Inline ActionsAre they gone in 12.3 and 13.1? If not, then either no MFC or wait until no supported 12.x or 13.x has them anymore. pauamma_gundo.com: Are they gone in 12.3 and 13.1? If not, then either no MFC or wait until no supported 12.x or… | |||||||||||||||||||||||||||
libc.so.7 | |||||||||||||||||||||||||||
Done Inline ActionsOur .so numbers are not usually this high and we typically don't have major/minor components -- e.g. ours is /lib/libc.so.7. Note also that this example is in /lib, not /usr/lib. /usr/lib/libc.so is a symlink to that, and is what is actually used in the linking process. emaste: Our .so numbers are not usually this high and we typically don't have major/minor components… | |||||||||||||||||||||||||||
.Ed | |||||||||||||||||||||||||||
Not Done Inline ActionsIs this incomplete? I think I don't understand what this is meant to show. mhorne: Is this incomplete? I think I don't understand what this is meant to show. | |||||||||||||||||||||||||||
Done Inline ActionsIn a former version of this differential there where profiling versions descriptions, which was removed a while ago in FreeBSD. I would suggest to rewrite Typically, a library will have a number of variants: to A library has the following naming convention: gbe: In a former version of this differential there where profiling versions descriptions, which was… | |||||||||||||||||||||||||||
Not Done Inline ActionsOkay I understand. Still, the naming convention is explained in detail in the paragraphs following. It is strange to present the single arbitrary library name in an indented block like this. I think it could be removed, but I leave it to your judgement to decide what to do. mhorne: Okay I understand. Still, the naming convention is explained in detail in the paragraphs… | |||||||||||||||||||||||||||
.Pp | |||||||||||||||||||||||||||
Libraries with an | |||||||||||||||||||||||||||
.Sq .a | |||||||||||||||||||||||||||
suffix are static. | |||||||||||||||||||||||||||
When a program is linked against a static library, all necessary library code | |||||||||||||||||||||||||||
Done Inline Actions... linked against a static library, ... rpokala: ... linked against a static library, ... | |||||||||||||||||||||||||||
will be included in the binary. | |||||||||||||||||||||||||||
Done Inline ActionsDuring static linking only the necessary object files are linked in, not the whole library. Perhaps "all necessary library code" would be better? jilles: During static linking only the necessary object files are linked in, not the whole library. | |||||||||||||||||||||||||||
Done Inline Actions
Otherwise you are saying, "when it is linked, it will be linked". mhorne: Otherwise you are saying, "when it is linked, it will be linked". | |||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||
Done Inline Actionsit can be inefficient with both disk space and memory usage during execution emaste: it can be inefficient with both disk space and memory usage during execution | |||||||||||||||||||||||||||
during execution. | |||||||||||||||||||||||||||
The C compiler, | |||||||||||||||||||||||||||
.Xr cc 1 , | |||||||||||||||||||||||||||
can be instructed to link statically by specifying the | |||||||||||||||||||||||||||
.Fl static | |||||||||||||||||||||||||||
flag. | |||||||||||||||||||||||||||
.Pp | |||||||||||||||||||||||||||
Libraries with a | |||||||||||||||||||||||||||
.Sq .so.X | |||||||||||||||||||||||||||
Done Inline ActionsAs far as I understand, profiling libraries are somewhat obsolete in FreeBSD. For example, pmcstat(8) doesn't need them. However, they still exist so they need to be described here. jilles: As far as I understand, profiling libraries are somewhat obsolete in FreeBSD. For example… | |||||||||||||||||||||||||||
Done Inline ActionsThey aren't built by default any longer, so there's no point in documenting them for 14. emaste: They aren't built by default any longer, so there's no point in documenting them for 14.
| |||||||||||||||||||||||||||
suffix are dynamic libraries. | |||||||||||||||||||||||||||
When code is linked dynamically, the library code that the application needs | |||||||||||||||||||||||||||
Done Inline ActionsShould it be "linked dynamically"? mhorne: Should it be "linked dynamically"? | |||||||||||||||||||||||||||
is not included in the binary. | |||||||||||||||||||||||||||
Done Inline Actions
mhorne: | |||||||||||||||||||||||||||
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 into the | |||||||||||||||||||||||||||
process virtual address space. | |||||||||||||||||||||||||||
.Xr rtld 1 | |||||||||||||||||||||||||||
loads the shared libraries when the program is executed. | |||||||||||||||||||||||||||
.Pp | |||||||||||||||||||||||||||
.Sq X | |||||||||||||||||||||||||||
represents the library version number of the library. | |||||||||||||||||||||||||||
In the example above, a binary linked with | |||||||||||||||||||||||||||
.Pa libc.so.8 | |||||||||||||||||||||||||||
would not be usable on a system where only | |||||||||||||||||||||||||||
.Pa libc.so.7 | |||||||||||||||||||||||||||
is available. | |||||||||||||||||||||||||||
.Pp | |||||||||||||||||||||||||||
The advantages of dynamic libraries are that multiple instances of the same | |||||||||||||||||||||||||||
Done Inline Actions
Unless you mean they get loaded at a specific address. (Aren't shared libraries supposed to be position-independent?) Alternatively, "loads them into the process' virtual address space". pauamma_gundo.com: Unless you mean they get loaded at a specific address. (Aren't shared libraries supposed to be… | |||||||||||||||||||||||||||
Done Inline Actions
pauamma_gundo.com: | |||||||||||||||||||||||||||
library can share address space, and the physical size of the binary is | |||||||||||||||||||||||||||
Done Inline ActionsI'm not sure there's value in specifying mmap here, IMO it's sufficient to mention that rtld loads the shared libraries when the program is executed. emaste: I'm not sure there's value in specifying mmap here, IMO it's sufficient to mention that rtld… | |||||||||||||||||||||||||||
smaller. | |||||||||||||||||||||||||||
Not Done Inline ActionsAs written, it's not clear what ld.so does and what rtld does; they are both described as loading the libraries when the program is executed. rpokala: As written, it's not clear what `ld.so` does and what `rtld` does; they are both described as… | |||||||||||||||||||||||||||
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 | |||||||||||||||||||||||||||
Done Inline ActionsI'd say either "version number" or "library version number" emaste: I'd say either "version number" or "library version number"
"library number" to me suggests… | |||||||||||||||||||||||||||
.Xr dlopen 3 . | |||||||||||||||||||||||||||
Done Inline Actions
mhorne: | |||||||||||||||||||||||||||
Done Inline ActionsGood catch! :) gbe: Good catch! :) | |||||||||||||||||||||||||||
Done Inline Actions
mhorne: | |||||||||||||||||||||||||||
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. | |||||||||||||||||||||||||||
Not Done Inline ActionsWe probably need to document symbol versioning, too emaste: We probably need to document symbol versioning, too | |||||||||||||||||||||||||||
Calls across shared libraries are also slightly slower and cannot be | |||||||||||||||||||||||||||
inlined, not even with link time optimization. | |||||||||||||||||||||||||||
The C compiler, | |||||||||||||||||||||||||||
Done Inline Actionss/program/library/? emaste: s/program/library/?
| |||||||||||||||||||||||||||
.Xr cc 1 , | |||||||||||||||||||||||||||
Done Inline Actions
7 is from emaste's example above and 8 is the equivalent of 31 in the original. pauamma_gundo.com: 7 is from emaste's example above and 8 is the equivalent of 31 in the original. | |||||||||||||||||||||||||||
can be instructed to link dynamically by specifying the | |||||||||||||||||||||||||||
.Fl shared | |||||||||||||||||||||||||||
flag. | |||||||||||||||||||||||||||
.Pp | |||||||||||||||||||||||||||
Done Inline ActionsMore advantages: 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 dlopen(3). jilles: More advantages: a namespace per shared library is available via hidden visibility, allowing… | |||||||||||||||||||||||||||
Shared libraries, as well as static libraries on architectures which produce | |||||||||||||||||||||||||||
position-independent executables | |||||||||||||||||||||||||||
Done Inline ActionsAnother disadvantage: calls across shared libraries are also slightly slower and cannot be inlined (not even with link time optimization). jilles: Another disadvantage: calls across shared libraries are also slightly slower and cannot be… | |||||||||||||||||||||||||||
.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, | |||||||||||||||||||||||||||
Done Inline ActionsDoes FreeBSD have a supported configuration without shared libraries? I expect no? jilles: Does FreeBSD have a supported configuration without shared libraries? I expect no? | |||||||||||||||||||||||||||
Done Inline ActionsNo, so I don't think we need to say "on systems that support it." -shared is the default and the only case I am aware of that it would be necessary is if some CFLAGS contained -static and it needed to be overridden. emaste: No, so I don't think we need to say "on systems that support it."
`-shared` is the default and… | |||||||||||||||||||||||||||
.Xr cc 1 , | |||||||||||||||||||||||||||
can be instructed to generate PIC code by specifying the | |||||||||||||||||||||||||||
.Fl fPIC | |||||||||||||||||||||||||||
flag. | |||||||||||||||||||||||||||
.Pp | |||||||||||||||||||||||||||
Not Done Inline Actions.a for PIE binaries is something that we still need to resolve emaste: .a for PIE binaries is something that we still need to resolve | |||||||||||||||||||||||||||
Static 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 | |||||||||||||||||||||||||||
Done Inline Actionson modern ISAs this isn't really true, it's primarily i386 where this is an issue emaste: on modern ISAs this isn't really true, it's primarily i386 where this is an issue | |||||||||||||||||||||||||||
relocatable object file. | |||||||||||||||||||||||||||
Not Done Inline ActionsThis section does not explain the difference between PIC and relocatable code. rpokala: This section does not explain the difference between PIC and relocatable code. | |||||||||||||||||||||||||||
This speeds up linking to the library, and allows routines in the library | |||||||||||||||||||||||||||
to call each other regardless of their placement within the library. | |||||||||||||||||||||||||||
.Sh SEE ALSO | .Sh SEE ALSO | ||||||||||||||||||||||||||
.Xr ar 1 , | |||||||||||||||||||||||||||
Done Inline Actions
ranlib too if not removed per emaste's abovre=ve pauamma_gundo.com: ranlib too if not removed per emaste's abovre=ve | |||||||||||||||||||||||||||
.Xr cc 1 , | .Xr cc 1 , | ||||||||||||||||||||||||||
.Xr ld 1 , | .Xr ld 1 , | ||||||||||||||||||||||||||
Done Inline ActionsAre -fpic and -fPIC literally identical? If so, pick one, and don't mention the other. rpokala: Are `-fpic` and `-fPIC` literally identical? If so, pick one, and don't mention the other. | |||||||||||||||||||||||||||
Done Inline ActionsThe common way of working is to use -fPIC only; on certain architectures, -fpic generates slightly more efficient code if the resulting file is smaller than an architecture-dependent size. I'd say -fpic need not be mentioned here. What should perhaps be mentioned is -fPIE which generates position-independent code for executables. That is, it makes the code position-independent but still assumes that it will be linked into an executable and not a shared library. This might be slightly more efficient. jilles: The common way of working is to use `-fPIC` only; on certain architectures, `-fpic` generates… | |||||||||||||||||||||||||||
.Xr nm 1 , | .Xr nm 1 , | ||||||||||||||||||||||||||
.Xr intro 2 , | .Xr intro 2 , | ||||||||||||||||||||||||||
.Xr math 3 , | .Xr math 3 , | ||||||||||||||||||||||||||
Done Inline ActionsThere are only two classes of libraries, so this seems a bit of an odd phrasing. emaste: There are only two classes of libraries, so this seems a bit of an odd phrasing. | |||||||||||||||||||||||||||
Done Inline Actions
Or whatever they're called. pauamma_gundo.com: Or whatever they're called. | |||||||||||||||||||||||||||
.Xr stdio 3 | .Xr stdio 3 , | ||||||||||||||||||||||||||
.Xr make.conf 5 , | |||||||||||||||||||||||||||
.Xr src.conf 5 | |||||||||||||||||||||||||||
Done Inline ActionsWhy? mhorne: Why? | |||||||||||||||||||||||||||
Done Inline ActionsFor reference of options I think. I can remove it, if necessary. gbe: For reference of options I think. I can remove it, if necessary. | |||||||||||||||||||||||||||
Done Inline ActionsThe choice is yours, but it does not seem clearly relevant to me. mhorne: The choice is yours, but it does not seem clearly relevant to me. | |||||||||||||||||||||||||||
.Sh HISTORY | .Sh HISTORY | ||||||||||||||||||||||||||
An | An | ||||||||||||||||||||||||||
.Nm | .Nm | ||||||||||||||||||||||||||
Not Done Inline ActionsCan a library have members that aren't relocatable files? pauamma_gundo.com: Can a library have members that aren't relocatable files? | |||||||||||||||||||||||||||
manual appeared in | manual appeared in | ||||||||||||||||||||||||||
.At v7 . | .At v7 . | ||||||||||||||||||||||||||
Done Inline Actionsthis isn't really true, the index is generally created by passing the s flag to ar. ranlib is really only of historical interest emaste: this isn't really true, the index is generally created by passing the `s` flag to `ar`. ranlib… | |||||||||||||||||||||||||||
Done Inline ActionsNote that this option is documented as deprecated and will be removed. emaste: Note that this option is documented as deprecated and will be removed. |
/lib too maybe?