1.\" $OpenBSD: intro.3,v 1.84 2018/09/30 13:24:32 schwarze Exp $ 2.\" $NetBSD: intro.3,v 1.5 1995/05/10 22:46:24 jtc Exp $ 3.\" 4.\" Copyright (c) 1980, 1991, 1993 5.\" The Regents of the University of California. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. Neither the name of the University nor the names of its contributors 16.\" may be used to endorse or promote products derived from this software 17.\" without specific prior written permission. 18.\" 19.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 20.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 23.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29.\" SUCH DAMAGE. 30.\" 31.\" @(#)intro.3 8.1 (Berkeley) 6/5/93 32.\" 33.Dd $Mdocdate: September 30 2018 $ 34.Dt INTRO 3 35.Os 36.Sh NAME 37.Nm intro 38.Nd introduction to the C libraries 39.Sh SYNOPSIS 40.Nm cc 41.Op Ar flags 42.Ar 43.Op Fl llibrary 44.Sh DESCRIPTION 45The manual pages in section 3 provide an overview of the C library 46functions, their error returns, and other common definitions and concepts. 47Most of these functions are available from the C library, 48.Em libc . 49Other libraries, such as the math library, 50.Em libm , 51must be indicated at compile time with the 52.Fl l 53option of the compiler. 54.Pp 55The various libraries (followed by the loader flag): 56.Pp 57.Bl -tag -width "libkvm" -compact 58.It libc Pq Fl lc 59Standard C library functions. 60When using the C compiler 61.Xr cc 1 , 62it is not necessary to supply the loader flag 63.Fl lc 64for these functions. 65There are several 66.Dq libraries 67or groups of functions included inside of libc: the standard I/O routines, 68database routines, 69bit operators, 70string operators, 71character tests and character operators, 72DES encryption routines, 73storage allocation, 74time functions, 75signal handling, 76and more. 77.Pp 78.It libc++ Pq Fl lc++ 79LLVM standard C++ library. 80See 81.Xr clang 1 . 82Note: users do not normally have to explicitly link with this library. 83.Pp 84.It libc++abi Pq Fl lc++abi 85LLVM C++ runtime library. 86Note: users do not normally have to explicitly link with this library. 87.Pp 88.It libcrypto Pq Fl lcrypto 89The OpenSSL crypto library. 90Implements a range of cryptographic algorithms, 91providing such functionality as symmetric encryption, public key cryptography, 92and certificate handling. 93See 94.Xr crypto 3 . 95.Pp 96.It libcurses Pq Fl lcurses 97.It libncurses Pq Fl lncurses 98.It libncursesw Pq Fl lncursesw 99.It libtermcap Pq Fl ltermcap 100.It libtermlib Pq Fl ltermlib 101Terminal-independent screen management routines for two-dimensional 102non-bitmap display terminals. 103This implementation is 104.Dq new curses 105and is a replacement for 106.Bx 4.2 107classic curses. 108The libraries 109.Em libncurses , 110.Em libncursesw , 111.Em libtermcap , 112and 113.Em libtermlib 114are all hard links to 115.Em libcurses . 116This is for compatibility purposes only; 117new programs should link with 118.Fl lcurses . 119See 120.Xr curses 3 121and 122.Xr termcap 3 . 123.Pp 124.It libedit Pq Fl ledit 125Generic line editing and history functions, similar to those found in 126.Xr sh 1 . 127Functions using the 128.Em libedit 129library must be linked with the 130.Em libcurses 131library, i.e.\& 132.Fl ledit lcurses . 133See 134.Xr editline 3 . 135.Pp 136.It libevent Pq Fl levent 137Provides a mechanism to execute a function when a specific event on a 138file descriptor occurs or after a given time has passed. 139See 140.Xr event 3 . 141.Pp 142.It libexpat Pq Fl lexpat 143Library routines for parsing XML documents. 144.Pp 145.It libform Pq Fl lform 146.It libformw Pq Fl lformw 147Terminal-independent facilities for composing form screens on 148character-cell terminals. 149Functions using the 150.Em libform 151library must be linked with the 152.Em libcurses 153library, i.e.\& 154.Fl lform lcurses . 155.Em libformw 156is a hard link to 157.Em libform 158intended for use with 159.Em libncursesw 160wide-character functions. 161See 162.Xr form 3 . 163.Pp 164.It libfuse Pq Fl lfuse 165File system in userland library. 166See 167.Xr fuse_main 3 . 168.Pp 169.It libgcc Pq Fl lgcc 170GCC runtime support, 171including long arithmetic, propolice, 172and language independent exception support. 173Note: users do not normally have to explicitly link with this library. 174.Pp 175.It libiberty Pq Fl liberty 176Collection of subroutines missing in other operating systems, 177as well as the C++ demangler and other functions used by 178the GNU toolchain. 179.Pp 180.It libkeynote Pq Fl lkeynote 181System library for the keynote trust-management system. 182Trust-management systems provide standard, general-purpose mechanisms 183for specifying application security policies and credentials. 184Functions using the libkeynote library must be linked with the 185.Em libm 186and 187.Em libcrypto 188libraries, i.e.\& 189.Fl lkeynote lm lcrypto . 190See 191.Xr keynote 3 192and 193.Xr keynote 4 . 194.Pp 195.It libkvm Pq Fl lkvm 196Kernel memory interface library. 197Provides a uniform interface for accessing kernel virtual memory images, 198including live systems and crash dumps. 199See 200.Xr kvm 3 . 201.Pp 202.It libl Pq Fl l\&l 203.It libfl Pq Fl lfl 204The library for 205.Xr lex 1 , 206a lexical analyzer generator. 207The 208.Em libfl 209library 210is a hard link to 211.Em libl . 212.Pp 213.It libm Pq Fl lm 214Mathematical functions which comprise the C math library, 215.Em libm . 216.Pp 217.It libmenu Pq Fl lmenu 218.It libmenuw Pq Fl lmenuw 219Terminal-independent facilities for composing menu systems on 220character-cell terminals. 221Functions using the 222.Em libmenu 223library must be linked with the 224.Em libcurses 225library, i.e.\& 226.Fl lmenu lcurses . 227.Em libmenuw 228is a hard link to 229.Em libmenu 230intended for use with 231.Em libncursesw 232wide-character functions. 233See 234.Xr menu 3 . 235.Pp 236.It libossaudio Pq Fl lossaudio 237Provides an emulation of the OSS 238.Pq Linux 239audio interface. 240This is used only for porting programs. 241See 242.Xr ossaudio 3 . 243.Pp 244.It libpanel Pq Fl lpanel 245.It libpanelw Pq Fl lpanelw 246Terminal-independent facilities for stacked windows on 247character-cell terminals. 248Functions using the 249.Em libpanel 250library must be linked with the 251.Em libcurses 252library, i.e.\& 253.Fl lpanel lcurses . 254.Em libpanelw 255is a hard link to 256.Em libpanel 257intended for use with 258.Em libncursesw 259wide-character functions. 260See 261.Xr panel 3 . 262.Pp 263.It libpcap Pq Fl lpcap 264Packet capture library. 265All packets on the network, even those destined for other hosts, 266are accessible through this library. 267See 268.Xr pcap 3 . 269.Pp 270.It libperl Pq Fl lperl 271Support routines for 272.Xr perl 1 . 273.Pp 274.It libpthread Pq Fl lpthread 275.St -p1003.1-2001 276threads API. 277See 278.Xr pthreads 3 . 279.Pp 280.It libradius Pq Fl lradius 281Support routines for the RADIUS library. 282See 283.Xr radius_new_request_packet 3 . 284.Pp 285.It libreadline Pq Fl lreadline 286Command line editing interface. 287See 288.Xr readline 3 . 289.Pp 290.It librpcsvc Pq Fl lrpcsvc 291Generated by 292.Xr rpcgen 1 , 293containing stub functions for many common 294.Xr rpc 3 295protocols. 296.Pp 297.It libskey Pq Fl lskey 298Support library for the S/Key one time password 299.Pq OTP 300authentication toolkit. 301See 302.Xr skey 3 . 303.Pp 304.It libsndio Pq Fl lsndio 305Library for 306.Xr audio 4 307hardware and the 308.Xr aucat 1 309audio server. 310See 311.Xr sio_open 3 . 312.Pp 313.It libssl Pq Fl lssl 314The OpenSSL ssl library implements the Secure Sockets Layer 315.Pq SSL v3 316and Transport Layer Security 317.Pq TLS v1 318protocols. 319See 320.Xr ssl 3 . 321.Pp 322.It libstdc++ Pq Fl lstdc++ 323GNU standard C++ library. 324See 325.Xr g++ 1 . 326Note: users do not normally have to explicitly link with this library. 327.Pp 328.It libsupc++ Pq Fl lsupc++ 329GNU C++ runtime library. 330Note: users do not normally have to explicitly link with this library. 331.Pp 332.It libtls Pq Fl ltls 333A Transport Layer Security library with a clean and easy to use interface. 334See 335.Xr tls_init 3 . 336.Pp 337.It libusbhid Pq Fl lusbhid 338Routines to extract data from USB Human Interface Devices 339.Pq HIDs . 340See 341.Xr usbhid 3 . 342.Pp 343.It libutil Pq Fl lutil 344System utility functions. 345These are currently 346.Xr bcrypt_pbkdf 3 , 347.Xr check_expire 3 , 348.Xr fmt_scaled 3 , 349.Xr fparseln 3 , 350.Xr getmaxpartitions 3 , 351.Xr getrawpartition 3 , 352.Xr imsg_init 3 , 353.Xr isduid 3 , 354.Xr login 3 , 355.Xr login_fbtab 3 , 356.Xr ohash_init 3 , 357.Xr ohash_interval 3 , 358.Xr opendev 3 , 359.Xr opendisk 3 , 360.Xr openpty 3 , 361.Xr pidfile 3 , 362.Xr pkcs5_pbkdf2 3 , 363.Xr pw_init 3 , 364.Xr pw_lock 3 , 365.Xr readlabelfs 3 366and 367.Xr uucplock 3 . 368.Pp 369.It liby Pq Fl ly 370The library for 371.Xr yacc 1 , 372an LALR parser generator. 373.Pp 374.It libz Pq Fl lz 375General purpose data compression library. 376The functions in this library are documented in 377.Xr compress 3 . 378The data format is described in RFCs 1950 \- 1952. 379.El 380.Pp 381Platform-specific libraries: 382.Bl -tag -width "libkvm" 383.It libalpha Pq Fl lalpha 384Alpha I/O and memory access functions. 385See 386.Xr inb 2 . 387.It libamd64 Pq Fl lamd64 388AMD64 I/O and memory access functions. 389See 390.Xr amd64_iopl 2 . 391.It libi386 Pq Fl li386 392i386 I/O and memory access functions. 393See 394.Xr i386_iopl 2 . 395.El 396.Sh LIBRARY TYPES 397The system libraries are located in 398.Pa /usr/lib . 399Typically, a library will have a number of variants: 400.Bd -unfilled -offset indent 401libc.a 402libc_p.a 403libc.so.30.1 404.Ed 405.Pp 406Libraries with an 407.Sq .a 408suffix are static. 409When a program is linked against a library, all the library code 410will be linked into the binary. 411This means the binary can be run even when the libraries are unavailable. 412However, it can be inefficient with memory usage. 413The C compiler, 414.Xr cc 1 , 415can be instructed to link statically by specifying the 416.Fl static 417flag. 418.Pp 419Libraries with a 420.Sq _p.a 421suffix are profiling libraries. 422They contain extra information suitable for analysing programs, 423such as execution speed and call counts. 424This in turn can be interpreted by utilities such as 425.Xr gprof 1 . 426The C compiler, 427.Xr cc 1 , 428can be instructed to generate profiling code, 429or to link with profiling libraries, by specifying the 430.Fl pg 431flag. 432.Pp 433Libraries with a 434.Sq .so.X.Y 435suffix are dynamic libraries. 436When code is compiled dynamically, the library code that the application needs 437is not linked into the binary. 438Instead, data structures are added containing information about which dynamic 439libraries to link with. 440When the binary is executed, the run-time linker 441.Xr ld.so 1 442reads these data structures, and loads them at a virtual address using the 443.Xr mmap 2 444system call. 445.Pp 446.Sq X 447represents the major number of the library, and 448.Sq Y 449represents the minor number. 450In general, a binary will be able to use a dynamic library with a differing 451minor number, but the major numbers must match. 452In the example above, a binary linked with minor number 453.Sq 3 454would be linkable against libc.so.30.1, 455while a binary linked with major number 456.Sq 31 457would not. 458.Pp 459The advantages of dynamic libraries are that multiple instances of the same 460program can share address space, and the physical size of the binary is 461smaller. 462The disadvantage is the added complexity that comes with loading the 463libraries dynamically, and the extra time taken to load the libraries. 464Of course, if the libraries are not available, the binary will be unable 465to execute. 466The C compiler, 467.Xr cc 1 , 468can be instructed to link dynamically by specifying the 469.Fl shared 470flag, although on systems that support it, this will be the default and 471need not be specified. 472.Pp 473Shared libraries, as well as static libraries on architectures which produce 474position-independent executables 475.Pq PIEs 476by default, contain position-independent code 477.Pq PIC . 478Normally, compilers produce relocatable code. 479Relocatable code needs to be modified at run-time, depending on where in 480memory it is to be run. 481PIC code does not need to be modified at run-time, but is less efficient than 482relocatable code. 483The C compiler, 484.Xr cc 1 , 485can be instructed to generate PIC code by specifying the 486.Fl fpic 487or 488.Fl fPIC 489flags. 490.Pp 491With the exception of dynamic libraries, libraries are generated using the 492.Xr ar 1 493utility. 494The libraries contain an index to the contents of the library, 495stored within the library itself. 496The index lists each symbol defined by a member of a library that is a 497relocatable object file. 498This speeds up linking to the library, and allows routines in the library 499to call each other regardless of their placement within the library. 500The index is created by 501.Xr ranlib 1 502and can be viewed using 503.Xr nm 1 . 504.Pp 505The building of dynamic libraries can be prevented by setting the variable 506.Dv NOPIC 507in 508.Pa /etc/mk.conf . 509The building of profiling versions of libraries can 510be prevented by setting the variable 511.Dv NOPROFILE 512in 513.Pa /etc/mk.conf . 514See 515.Xr mk.conf 5 516for more details. 517.Sh SEE ALSO 518.Xr ar 1 , 519.Xr cc 1 , 520.Xr gprof 1 , 521.Xr ld 1 , 522.Xr ld.so 1 , 523.Xr nm 1 , 524.Xr ranlib 1 , 525.Xr mk.conf 5 526.Sh HISTORY 527An 528.Nm 529manual for section 3 first appeared in 530.At v7 . 531