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