xref: /openbsd-src/share/man/man3/intro.3 (revision f2395cb1695a5673b88774467a81d72810ba4db7)
1*f2395cb1Sjmc.\"	$OpenBSD: intro.3,v 1.100 2024/05/09 17:57:36 jmc Exp $
2df930be7Sderaadt.\"	$NetBSD: intro.3,v 1.5 1995/05/10 22:46:24 jtc Exp $
3df930be7Sderaadt.\"
4df930be7Sderaadt.\" Copyright (c) 1980, 1991, 1993
5df930be7Sderaadt.\"	The Regents of the University of California.  All rights reserved.
6df930be7Sderaadt.\"
7df930be7Sderaadt.\" Redistribution and use in source and binary forms, with or without
8df930be7Sderaadt.\" modification, are permitted provided that the following conditions
9df930be7Sderaadt.\" are met:
10df930be7Sderaadt.\" 1. Redistributions of source code must retain the above copyright
11df930be7Sderaadt.\"    notice, this list of conditions and the following disclaimer.
12df930be7Sderaadt.\" 2. Redistributions in binary form must reproduce the above copyright
13df930be7Sderaadt.\"    notice, this list of conditions and the following disclaimer in the
14df930be7Sderaadt.\"    documentation and/or other materials provided with the distribution.
1529295d1cSmillert.\" 3. Neither the name of the University nor the names of its contributors
16df930be7Sderaadt.\"    may be used to endorse or promote products derived from this software
17df930be7Sderaadt.\"    without specific prior written permission.
18df930be7Sderaadt.\"
19df930be7Sderaadt.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20df930be7Sderaadt.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21df930be7Sderaadt.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22df930be7Sderaadt.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23df930be7Sderaadt.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24df930be7Sderaadt.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25df930be7Sderaadt.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26df930be7Sderaadt.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27df930be7Sderaadt.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28df930be7Sderaadt.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29df930be7Sderaadt.\" SUCH DAMAGE.
30df930be7Sderaadt.\"
31df930be7Sderaadt.\"     @(#)intro.3	8.1 (Berkeley) 6/5/93
32df930be7Sderaadt.\"
33c24bf1a9Sjmc.Dd $Mdocdate: May 9 2024 $
34df930be7Sderaadt.Dt INTRO 3
35c0e8509eSaaron.Os
36df930be7Sderaadt.Sh NAME
37df930be7Sderaadt.Nm intro
38df930be7Sderaadt.Nd introduction to the C libraries
39cb0e3432Sjmc.Sh SYNOPSIS
40cb0e3432Sjmc.Nm cc
41cb0e3432Sjmc.Op Ar flags
42db414fdbSsobrado.Ar
43cb0e3432Sjmc.Op Fl llibrary
44df930be7Sderaadt.Sh DESCRIPTION
4557686ba8ShekoThe manual pages in section 3 provide an overview of the C library
4657686ba8Shekofunctions, their error returns, and other common definitions and concepts.
47df930be7SderaadtMost of these functions are available from the C library,
48df930be7Sderaadt.Em libc .
49df930be7SderaadtOther libraries, such as the math library,
50df930be7Sderaadt.Em libm ,
51df930be7Sderaadtmust be indicated at compile time with the
52df930be7Sderaadt.Fl l
53df930be7Sderaadtoption of the compiler.
54df930be7Sderaadt.Pp
55df930be7SderaadtThe various libraries (followed by the loader flag):
56cb0e3432Sjmc.Pp
57cb0e3432Sjmc.Bl -tag -width "libkvm" -compact
58b7184b48Sjsg.It libLLVM Pq Fl lLLVM
598d7b361fSjmcLLVM components in a single library.
608d7b361fSjmc.Pp
61fc115562Smartijn.It libagentx Pq Fl lagentx
62fc115562SmartijnAgentX client library.
63fc115562SmartijnUsed for applications to export metrics to AgentX capable snmp daemons.
64fc115562SmartijnSee
65bf6393cfSjmc.Xr agentx 3 .
66fc115562Smartijn.Pp
67cb0e3432Sjmc.It libc Pq Fl lc
68df930be7SderaadtStandard C library functions.
69df930be7SderaadtWhen using the C compiler
70df930be7Sderaadt.Xr cc 1 ,
71431305c8Saaronit is not necessary to supply the loader flag
72cb0e3432Sjmc.Fl lc
73df930be7Sderaadtfor these functions.
74c0e8509eSaaronThere are several
75c0e8509eSaaron.Dq libraries
76fefab8afSjmcor groups of functions included inside of libc: the standard I/O routines,
77df930be7Sderaadtdatabase routines,
78df930be7Sderaadtbit operators,
79df930be7Sderaadtstring operators,
80df930be7Sderaadtcharacter tests and character operators,
810d042477Sderaadtcryptographic routines,
82431305c8Saaronstorage allocation,
83431305c8Saarontime functions,
84431305c8Saaronsignal handling,
85431305c8Saaronand more.
86cb0e3432Sjmc.Pp
871a628d9fSjmc.It libc++ Pq Fl lc++
881a628d9fSjmcLLVM standard C++ library.
891a628d9fSjmcNote: users do not normally have to explicitly link with this library.
901a628d9fSjmc.Pp
911a628d9fSjmc.It libc++abi Pq Fl lc++abi
921a628d9fSjmcLLVM C++ runtime library.
931a628d9fSjmcNote: users do not normally have to explicitly link with this library.
941a628d9fSjmc.Pp
95870fb7e2Sjsg.It libcbor Pq Fl lcbor
96870fb7e2SjsgAn implementation of the Concise Binary Object Representation
97870fb7e2Sjsg.Pq CBOR
98870fb7e2Sjsgencoding format defined in RFC 7049.
99870fb7e2Sjsg.Pp
100cb0e3432Sjmc.It libcrypto Pq Fl lcrypto
1018fad29a3StbProvides functionality such as symmetric encryption, public key cryptography,
1028fad29a3Stbdigests, message authentication codes,
103cb0e3432Sjmcand certificate handling.
104cb0e3432SjmcSee
105cb0e3432Sjmc.Xr crypto 3 .
106cb0e3432Sjmc.Pp
107cb0e3432Sjmc.It libcurses Pq Fl lcurses
108cb0e3432Sjmc.It libncurses Pq Fl lncurses
109ee9a4f08Sjmc.It libncursesw Pq Fl lncursesw
110cb0e3432Sjmc.It libtermcap Pq Fl ltermcap
111cb0e3432Sjmc.It libtermlib Pq Fl ltermlib
112cb0e3432SjmcTerminal-independent screen management routines for two-dimensional
113cb0e3432Sjmcnon-bitmap display terminals.
114cb0e3432SjmcThis implementation is
115cb0e3432Sjmc.Dq new curses
116cb0e3432Sjmcand is a replacement for
117cb0e3432Sjmc.Bx 4.2
118cb0e3432Sjmcclassic curses.
119cb0e3432SjmcThe libraries
120cb0e3432Sjmc.Em libncurses ,
121ee9a4f08Sjmc.Em libncursesw ,
122cb0e3432Sjmc.Em libtermcap ,
123cb0e3432Sjmcand
124cb0e3432Sjmc.Em libtermlib
125cb0e3432Sjmcare all hard links to
126cb0e3432Sjmc.Em libcurses .
127cb0e3432SjmcThis is for compatibility purposes only;
128cb0e3432Sjmcnew programs should link with
129cb0e3432Sjmc.Fl lcurses .
130cb0e3432SjmcSee
131cb0e3432Sjmc.Xr curses 3
132cb0e3432Sjmcand
133cb0e3432Sjmc.Xr termcap 3 .
134cb0e3432Sjmc.Pp
135cb0e3432Sjmc.It libedit Pq Fl ledit
136cb0e3432SjmcGeneric line editing and history functions, similar to those found in
137cb0e3432Sjmc.Xr sh 1 .
138cb0e3432SjmcFunctions using the
139cb0e3432Sjmc.Em libedit
140cb0e3432Sjmclibrary must be linked with the
141cb0e3432Sjmc.Em libcurses
142cb0e3432Sjmclibrary, i.e.\&
143cb0e3432Sjmc.Fl ledit lcurses .
144cb0e3432SjmcSee
145cb0e3432Sjmc.Xr editline 3 .
146cb0e3432Sjmc.Pp
147affae2b4Sjmc.It libelf Pq Fl lelf
148affae2b4SjmcLibrary routines for manipulating ELF objects.
149affae2b4SjmcSee
150affae2b4Sjmc.Xr elf 3 .
151affae2b4Sjmc.Pp
152cb0e3432Sjmc.It libevent Pq Fl levent
153cb0e3432SjmcProvides a mechanism to execute a function when a specific event on a
154cb0e3432Sjmcfile descriptor occurs or after a given time has passed.
155cb0e3432SjmcSee
156cb0e3432Sjmc.Xr event 3 .
157cb0e3432Sjmc.Pp
15866e500ceSmortimer.It libexecinfo Pq Fl lexecinfo
15966e500ceSmortimerLibrary providing backtrace functions.
160272e85c6SjmcSee
161272e85c6Sjmc.Xr backtrace 3 .
16266e500ceSmortimer.Pp
16386d79740Sjmc.It libexpat Pq Fl lexpat
16486d79740SjmcLibrary routines for parsing XML documents.
16586d79740Sjmc.Pp
166870fb7e2Sjsg.It libfido2 Pq Fl lfido2
167870fb7e2SjsgLibrary for communication with U2F/FIDO2 devices over USB.
168870fb7e2Sjsg.Pp
169cb0e3432Sjmc.It libform Pq Fl lform
170ee9a4f08Sjmc.It libformw Pq Fl lformw
171bb2a3fd1SjmcTerminal-independent facilities for composing form screens on
172cb0e3432Sjmccharacter-cell terminals.
173cb0e3432SjmcFunctions using the
174cb0e3432Sjmc.Em libform
175cb0e3432Sjmclibrary must be linked with the
176cb0e3432Sjmc.Em libcurses
177cb0e3432Sjmclibrary, i.e.\&
178cb0e3432Sjmc.Fl lform lcurses .
179ee9a4f08Sjmc.Em libformw
180ee9a4f08Sjmcis a hard link to
181ee9a4f08Sjmc.Em libform
182ee9a4f08Sjmcintended for use with
183ee9a4f08Sjmc.Em libncursesw
184ee9a4f08Sjmcwide-character functions.
185cb0e3432SjmcSee
186cb0e3432Sjmc.Xr form 3 .
187cb0e3432Sjmc.Pp
1881b361a55Spascal.It libfuse Pq Fl lfuse
1891b361a55SpascalFile system in userland library.
1901b361a55SpascalSee
1911b361a55Spascal.Xr fuse_main 3 .
1921b361a55Spascal.Pp
19336d10346Sjmc.It libgcc Pq Fl lgcc
19436d10346SjmcGCC runtime support,
19536d10346Sjmcincluding long arithmetic, propolice,
19636d10346Sjmcand language independent exception support.
19736d10346SjmcNote: users do not normally have to explicitly link with this library.
19836d10346Sjmc.Pp
199cb0e3432Sjmc.It libiberty Pq Fl liberty
200cb0e3432SjmcCollection of subroutines missing in other operating systems,
201cb0e3432Sjmcas well as the C++ demangler and other functions used by
202cb0e3432Sjmcthe GNU toolchain.
203cb0e3432Sjmc.Pp
204cb0e3432Sjmc.It libkeynote Pq Fl lkeynote
205cb0e3432SjmcSystem library for the keynote trust-management system.
206cb0e3432SjmcTrust-management systems provide standard, general-purpose mechanisms
207cb0e3432Sjmcfor specifying application security policies and credentials.
208cb0e3432SjmcFunctions using the libkeynote library must be linked with the
209cb0e3432Sjmc.Em libm
210cb0e3432Sjmcand
211cb0e3432Sjmc.Em libcrypto
212cb0e3432Sjmclibraries, i.e.\&
213cb0e3432Sjmc.Fl lkeynote lm lcrypto .
214cb0e3432SjmcSee
215cb0e3432Sjmc.Xr keynote 3
216cb0e3432Sjmcand
217cb0e3432Sjmc.Xr keynote 4 .
218cb0e3432Sjmc.Pp
219cb0e3432Sjmc.It libkvm Pq Fl lkvm
220cb0e3432SjmcKernel memory interface library.
221cb0e3432SjmcProvides a uniform interface for accessing kernel virtual memory images,
222cb0e3432Sjmcincluding live systems and crash dumps.
2231f53fde1SaaronSee
224f934ae79Sderaadt.Xr kvm 3 .
225cb0e3432Sjmc.Pp
226cb0e3432Sjmc.It libl Pq Fl l\&l
227cb0e3432Sjmc.It libfl Pq Fl lfl
228df930be7SderaadtThe library for
229cb0e3432Sjmc.Xr lex 1 ,
230cb0e3432Sjmca lexical analyzer generator.
231cb0e3432SjmcThe
232cb0e3432Sjmc.Em libfl
233cb0e3432Sjmclibrary
234cb0e3432Sjmcis a hard link to
235cb0e3432Sjmc.Em libl .
236cb0e3432Sjmc.Pp
237cb0e3432Sjmc.It libm Pq Fl lm
238cb0e3432SjmcMathematical functions which comprise the C math library,
2391f53fde1Saaron.Em libm .
240cb0e3432Sjmc.Pp
241cb0e3432Sjmc.It libmenu Pq Fl lmenu
242ee9a4f08Sjmc.It libmenuw Pq Fl lmenuw
243bb2a3fd1SjmcTerminal-independent facilities for composing menu systems on
244cb0e3432Sjmccharacter-cell terminals.
245cb0e3432SjmcFunctions using the
246cb0e3432Sjmc.Em libmenu
247cb0e3432Sjmclibrary must be linked with the
248cb0e3432Sjmc.Em libcurses
249cb0e3432Sjmclibrary, i.e.\&
250cb0e3432Sjmc.Fl lmenu lcurses .
251ee9a4f08Sjmc.Em libmenuw
252ee9a4f08Sjmcis a hard link to
253ee9a4f08Sjmc.Em libmenu
254ee9a4f08Sjmcintended for use with
255ee9a4f08Sjmc.Em libncursesw
256ee9a4f08Sjmcwide-character functions.
257cb0e3432SjmcSee
258cb0e3432Sjmc.Xr menu 3 .
259cb0e3432Sjmc.Pp
260cb0e3432Sjmc.It libossaudio Pq Fl lossaudio
261cb0e3432SjmcProvides an emulation of the OSS
262cb0e3432Sjmc.Pq Linux
263cb0e3432Sjmcaudio interface.
264cb0e3432SjmcThis is used only for porting programs.
265cb0e3432SjmcSee
266cb0e3432Sjmc.Xr ossaudio 3 .
267cb0e3432Sjmc.Pp
268cb0e3432Sjmc.It libpanel Pq Fl lpanel
269ee9a4f08Sjmc.It libpanelw Pq Fl lpanelw
270bb2a3fd1SjmcTerminal-independent facilities for stacked windows on
271cb0e3432Sjmccharacter-cell terminals.
272cb0e3432SjmcFunctions using the
273cb0e3432Sjmc.Em libpanel
274cb0e3432Sjmclibrary must be linked with the
275cb0e3432Sjmc.Em libcurses
276cb0e3432Sjmclibrary, i.e.\&
277cb0e3432Sjmc.Fl lpanel lcurses .
278ee9a4f08Sjmc.Em libpanelw
279ee9a4f08Sjmcis a hard link to
280ee9a4f08Sjmc.Em libpanel
281ee9a4f08Sjmcintended for use with
282ee9a4f08Sjmc.Em libncursesw
2837d120d02Ssobradowide-character functions.
284cb0e3432SjmcSee
285cb0e3432Sjmc.Xr panel 3 .
286cb0e3432Sjmc.Pp
287cb0e3432Sjmc.It libpcap Pq Fl lpcap
288cb0e3432SjmcPacket capture library.
289cb0e3432SjmcAll packets on the network, even those destined for other hosts,
290cb0e3432Sjmcare accessible through this library.
291cb0e3432SjmcSee
29250f49510Sjmc.Xr pcap_open_live 3 .
293cb0e3432Sjmc.Pp
294cb0e3432Sjmc.It libperl Pq Fl lperl
295cb0e3432SjmcSupport routines for
296cb0e3432Sjmc.Xr perl 1 .
297cb0e3432Sjmc.Pp
2980fca2728Sbrad.It libpthread Pq Fl lpthread
2997a5684e3Sjmc.St -p1003.1-2001
3000fca2728Sbradthreads API.
301cb0e3432SjmcSee
302cb0e3432Sjmc.Xr pthreads 3 .
303cb0e3432Sjmc.Pp
304d155ab1eSjmc.It libradius Pq Fl lradius
305bc976a56SjmcSupport routines for the RADIUS library.
306bc976a56SjmcSee
307bc976a56Sjmc.Xr radius_new_request_packet 3 .
308d155ab1eSjmc.Pp
309cb0e3432Sjmc.It libreadline Pq Fl lreadline
310cb0e3432SjmcCommand line editing interface.
311cb0e3432SjmcSee
312cb0e3432Sjmc.Xr readline 3 .
313cb0e3432Sjmc.Pp
314cb0e3432Sjmc.It librpcsvc Pq Fl lrpcsvc
315cb0e3432SjmcGenerated by
316cb0e3432Sjmc.Xr rpcgen 1 ,
317cb0e3432Sjmccontaining stub functions for many common
318cb0e3432Sjmc.Xr rpc 3
319cb0e3432Sjmcprotocols.
320cb0e3432Sjmc.Pp
321cb0e3432Sjmc.It libskey Pq Fl lskey
322cb0e3432SjmcSupport library for the S/Key one time password
323cb0e3432Sjmc.Pq OTP
324cb0e3432Sjmcauthentication toolkit.
325cb0e3432SjmcSee
326cb0e3432Sjmc.Xr skey 3 .
327cb0e3432Sjmc.Pp
328a07b61edSjmc.It libsndio Pq Fl lsndio
329a07b61edSjmcLibrary for
330a07b61edSjmc.Xr audio 4
331a07b61edSjmchardware and the
3321807be72Sjmc.Xr sndiod 8
333a07b61edSjmcaudio server.
334a07b61edSjmcSee
335a07b61edSjmc.Xr sio_open 3 .
336a07b61edSjmc.Pp
337cb0e3432Sjmc.It libssl Pq Fl lssl
3388fad29a3StbImplements the Transport Layer Security
3398fad29a3Stb.Pq TLS
340*f2395cb1Sjmcprotocol, the successor to the Secure Sockets Layer (SSL) protocol.
341cb0e3432SjmcSee
342cb0e3432Sjmc.Xr ssl 3 .
343cb0e3432Sjmc.Pp
344cb0e3432Sjmc.It libstdc++ Pq Fl lstdc++
3451a628d9fSjmcGNU standard C++ library.
34636d10346SjmcNote: users do not normally have to explicitly link with this library.
34736d10346Sjmc.Pp
34836d10346Sjmc.It libsupc++ Pq Fl lsupc++
3491a628d9fSjmcGNU C++ runtime library.
35036d10346SjmcNote: users do not normally have to explicitly link with this library.
351cb0e3432Sjmc.Pp
35253b8e70eSanton.It libtls Pq Fl ltls
353d8cfd65dSjsingA Transport Layer Security library with a clean and easy to use interface.
354d8cfd65dSjsingSee
355d8cfd65dSjsing.Xr tls_init 3 .
356d8cfd65dSjsing.Pp
357cb0e3432Sjmc.It libusbhid Pq Fl lusbhid
358cb0e3432SjmcRoutines to extract data from USB Human Interface Devices
359cb0e3432Sjmc.Pq HIDs .
360cb0e3432SjmcSee
361cb0e3432Sjmc.Xr usbhid 3 .
362cb0e3432Sjmc.Pp
363cb0e3432Sjmc.It libutil Pq Fl lutil
364cb0e3432SjmcSystem utility functions.
365cb0e3432Sjmc.Pp
366cb0e3432Sjmc.It liby Pq Fl ly
367cb0e3432SjmcThe library for
368cb0e3432Sjmc.Xr yacc 1 ,
369cb0e3432Sjmcan LALR parser generator.
370cb0e3432Sjmc.Pp
371cb0e3432Sjmc.It libz Pq Fl lz
372cb0e3432SjmcGeneral purpose data compression library.
373dba20346SjmcThe functions in this library are documented in
374dba20346Sjmc.Xr compress 3 .
375cb0e3432SjmcThe data format is described in RFCs 1950 \- 1952.
376df930be7Sderaadt.El
377cb0e3432Sjmc.Pp
378cb0e3432SjmcPlatform-specific libraries:
3799d0b4071Sjmc.Bl -tag -width "libkvm"
380cb0e3432Sjmc.It libalpha Pq Fl lalpha
381cb0e3432SjmcAlpha I/O and memory access functions.
382cb0e3432SjmcSee
383cb0e3432Sjmc.Xr inb 2 .
384a9c6593cSjmc.It libamd64 Pq Fl lamd64
385a9c6593cSjmcAMD64 I/O and memory access functions.
386a9c6593cSjmcSee
387b756b2e6Sjmc.Xr amd64_iopl 2 .
388cb0e3432Sjmc.It libi386 Pq Fl li386
389cb0e3432Sjmci386 I/O and memory access functions.
390cb0e3432SjmcSee
391f53b17adSjmc.Xr i386_iopl 2 .
392cb0e3432Sjmc.El
393cb0e3432Sjmc.Sh LIBRARY TYPES
394cb0e3432SjmcThe system libraries are located in
395cb0e3432Sjmc.Pa /usr/lib .
396cb0e3432SjmcTypically, a library will have a number of variants:
397cb0e3432Sjmc.Bd -unfilled -offset indent
398cb0e3432Sjmclibc.a
399cb0e3432Sjmclibc_p.a
4002f5ee3f7Spascallibc.so.30.1
401cb0e3432Sjmc.Ed
402cb0e3432Sjmc.Pp
403cb0e3432SjmcLibraries with an
404cb0e3432Sjmc.Sq .a
405cb0e3432Sjmcsuffix are static.
406cb0e3432SjmcWhen a program is linked against a library, all the library code
407cb0e3432Sjmcwill be linked into the binary.
408cb0e3432SjmcThis means the binary can be run even when the libraries are unavailable.
409cb0e3432SjmcHowever, it can be inefficient with memory usage.
410cb0e3432SjmcThe C compiler,
411cb0e3432Sjmc.Xr cc 1 ,
412cb0e3432Sjmccan be instructed to link statically by specifying the
413cb0e3432Sjmc.Fl static
414cb0e3432Sjmcflag.
415cb0e3432Sjmc.Pp
416cb0e3432SjmcLibraries with a
4172f5ee3f7Spascal.Sq _p.a
4182f5ee3f7Spascalsuffix are profiling libraries.
4192f5ee3f7SpascalThey contain extra information suitable for analysing programs,
4202f5ee3f7Spascalsuch as execution speed and call counts.
4212f5ee3f7SpascalThis in turn can be interpreted by utilities such as
4222f5ee3f7Spascal.Xr gprof 1 .
4232f5ee3f7SpascalThe C compiler,
4242f5ee3f7Spascal.Xr cc 1 ,
4252f5ee3f7Spascalcan be instructed to generate profiling code,
4262f5ee3f7Spascalor to link with profiling libraries, by specifying the
4272f5ee3f7Spascal.Fl pg
4282f5ee3f7Spascalflag.
4292f5ee3f7Spascal.Pp
4302f5ee3f7SpascalLibraries with a
431cb0e3432Sjmc.Sq .so.X.Y
432cb0e3432Sjmcsuffix are dynamic libraries.
433cb0e3432SjmcWhen code is compiled dynamically, the library code that the application needs
434cb0e3432Sjmcis not linked into the binary.
435cb0e3432SjmcInstead, data structures are added containing information about which dynamic
436cb0e3432Sjmclibraries to link with.
437cb0e3432SjmcWhen the binary is executed, the run-time linker
438cb0e3432Sjmc.Xr ld.so 1
439cb0e3432Sjmcreads these data structures, and loads them at a virtual address using the
440cb0e3432Sjmc.Xr mmap 2
441cb0e3432Sjmcsystem call.
442cb0e3432Sjmc.Pp
443cb0e3432Sjmc.Sq X
444cb0e3432Sjmcrepresents the major number of the library, and
445cb0e3432Sjmc.Sq Y
446cb0e3432Sjmcrepresents the minor number.
447cb0e3432SjmcIn general, a binary will be able to use a dynamic library with a differing
448cb0e3432Sjmcminor number, but the major numbers must match.
449cb0e3432SjmcIn the example above, a binary linked with minor number
450cb0e3432Sjmc.Sq 3
451cb0e3432Sjmcwould be linkable against libc.so.30.1,
452cb0e3432Sjmcwhile a binary linked with major number
453cb0e3432Sjmc.Sq 31
454cb0e3432Sjmcwould not.
455cb0e3432Sjmc.Pp
456cb0e3432SjmcThe advantages of dynamic libraries are that multiple instances of the same
457cb0e3432Sjmcprogram can share address space, and the physical size of the binary is
458cb0e3432Sjmcsmaller.
459cb0e3432SjmcThe disadvantage is the added complexity that comes with loading the
460cb0e3432Sjmclibraries dynamically, and the extra time taken to load the libraries.
461cb0e3432SjmcOf course, if the libraries are not available, the binary will be unable
462cb0e3432Sjmcto execute.
463cb0e3432SjmcThe C compiler,
464cb0e3432Sjmc.Xr cc 1 ,
465cb0e3432Sjmccan be instructed to link dynamically by specifying the
466cb0e3432Sjmc.Fl shared
467cb0e3432Sjmcflag, although on systems that support it, this will be the default and
468cb0e3432Sjmcneed not be specified.
469cb0e3432Sjmc.Pp
470eb5cced9SpascalShared libraries, as well as static libraries on architectures which produce
471eb5cced9Spascalposition-independent executables
472eb5cced9Spascal.Pq PIEs
4732f5ee3f7Spascalby default, contain position-independent code
474cb0e3432Sjmc.Pq PIC .
475cb0e3432SjmcNormally, compilers produce relocatable code.
476cb0e3432SjmcRelocatable code needs to be modified at run-time, depending on where in
477cb0e3432Sjmcmemory it is to be run.
478cb0e3432SjmcPIC code does not need to be modified at run-time, but is less efficient than
479cb0e3432Sjmcrelocatable code.
480cb0e3432SjmcThe C compiler,
481cb0e3432Sjmc.Xr cc 1 ,
4822f5ee3f7Spascalcan be instructed to generate PIC code by specifying the
483cb0e3432Sjmc.Fl fpic
484cb0e3432Sjmcor
485cb0e3432Sjmc.Fl fPIC
486cb0e3432Sjmcflags.
487cb0e3432Sjmc.Pp
488cb0e3432SjmcWith the exception of dynamic libraries, libraries are generated using the
489cb0e3432Sjmc.Xr ar 1
490cb0e3432Sjmcutility.
491cb0e3432SjmcThe libraries contain an index to the contents of the library,
492cb0e3432Sjmcstored within the library itself.
493cb0e3432SjmcThe index lists each symbol defined by a member of a library that is a
494cb0e3432Sjmcrelocatable object file.
495cb0e3432SjmcThis speeds up linking to the library, and allows routines in the library
496cb0e3432Sjmcto call each other regardless of their placement within the library.
497cb0e3432SjmcThe index is created by
498cb0e3432Sjmc.Xr ranlib 1
499cb0e3432Sjmcand can be viewed using
500cb0e3432Sjmc.Xr nm 1 .
501cb0e3432Sjmc.Pp
5022f5ee3f7SpascalThe building of dynamic libraries can be prevented by setting the variable
503cb0e3432Sjmc.Dv NOPIC
504cb0e3432Sjmcin
505cb0e3432Sjmc.Pa /etc/mk.conf .
5062f5ee3f7SpascalThe building of profiling versions of libraries can
507cb0e3432Sjmcbe prevented by setting the variable
508cb0e3432Sjmc.Dv NOPROFILE
509cb0e3432Sjmcin
510cb0e3432Sjmc.Pa /etc/mk.conf .
511cb0e3432SjmcSee
512cb0e3432Sjmc.Xr mk.conf 5
513cb0e3432Sjmcfor more details.
514df930be7Sderaadt.Sh SEE ALSO
515cb0e3432Sjmc.Xr ar 1 ,
516df930be7Sderaadt.Xr cc 1 ,
517cb0e3432Sjmc.Xr gprof 1 ,
51808fd3e85Spascal.Xr ld 1 ,
519f934ae79Sderaadt.Xr ld.so 1 ,
52092efb735Sd.Xr nm 1 ,
521cb0e3432Sjmc.Xr ranlib 1 ,
522cb0e3432Sjmc.Xr mk.conf 5
523df930be7Sderaadt.Sh HISTORY
524df930be7SderaadtAn
525fbd19cc4Saaron.Nm
5266bebbfa9Sschwarzemanual for section 3 first appeared in
527df930be7Sderaadt.At v7 .
528