.\" $OpenBSD: intro.3,v 1.25 2004/07/13 21:09:48 millert Exp $ .\" $NetBSD: intro.3,v 1.5 1995/05/10 22:46:24 jtc Exp $ .\" .\" Copyright (c) 1980, 1991, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" 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 .\" SUCH DAMAGE. .\" .\" @(#)intro.3 8.1 (Berkeley) 6/5/93 .\" .Dd June 5, 1993 .Dt INTRO 3 .Os .Sh NAME .Nm intro .Nd introduction to the C libraries .Sh SYNOPSIS .Nm cc .Op Ar flags .Ar file ... .Op Fl llibrary .Sh DESCRIPTION The manual pages in section 3 provide an overview of the C library functions, their error returns, and other common definitions and concepts. Most of these functions are available from the C library, .Em libc . Other libraries, such as the math library, .Em libm , must be indicated at compile time with the .Fl l option of the compiler. .Pp The various libraries (followed by the loader flag): .Pp .Bl -tag -width "libkvm" -compact .It libbfd Pq Fl lbfd GNU binary file descriptor library. Allows applications to operate on object files, regardless of the object file format. See .Sq info bfd . .Pp .It libc Pq Fl lc Standard C library functions. When using the C compiler .Xr cc 1 , it is not necessary to supply the loader flag .Fl lc for these functions. There are several .Dq libraries or groups of functions included inside of libc: the standard .Tn I/O routines, database routines, bit operators, string operators, character tests and character operators, DES encryption routines, storage allocation, time functions, signal handling, and more. .Pp .It libcompat Pq Fl lcompat Functions which are obsolete but are available for compatibility with .Bx 4.3 . In particular, a number of system call interfaces provided in previous releases of .Bx have been included for source code compatibility. Use of these routines should, for the most part, be avoided. The manual page entry for each compatibility routine indicates the proper interface to use. .Pp .It libcrypto Pq Fl lcrypto The OpenSSL crypto library. Implements a range of cryptographic algorithms, providing such functionality as symmetric encryption, public key cryptography, and certificate handling. See .Xr crypto 3 . .Pp .It libcurses Pq Fl lcurses .It libncurses Pq Fl lncurses .It libtermcap Pq Fl ltermcap .It libtermlib Pq Fl ltermlib Terminal-independent screen management routines for two-dimensional non-bitmap display terminals. This implementation is .Dq new curses and is a replacement for .Bx 4.2 classic curses. The libraries .Em libncurses , .Em libtermcap , and .Em libtermlib are all hard links to .Em libcurses . This is for compatibility purposes only; new programs should link with .Fl lcurses . See .Xr curses 3 and .Xr termcap 3 . .Pp .It libcurses++ Pq Fl lcurses++ C++ interface to ncurses routines. See .Xr curses 3 . .Pp .It libdes Pq Fl ldes Implementation of the .Tn DES encryption algorithm. See .Xr des_crypt 3 . .Pp .It libedit Pq Fl ledit Generic line editing and history functions, similar to those found in .Xr sh 1 . Functions using the .Em libedit library must be linked with the .Em libcurses library, i.e.\& .Fl ledit lcurses . See .Xr editline 3 . .Pp .It libevent Pq Fl levent Provides a mechanism to execute a function when a specific event on a file descriptor occurs or after a given time has passed. See .Xr event 3 . .Pp .It libform Pq Fl lform Terminal-independent facilities for composing form screens on character-cell terminals. Functions using the .Em libform library must be linked with the .Em libcurses library, i.e.\& .Fl lform lcurses . See .Xr form 3 . .Pp .It libfrtbegin Pq Fl lfrtbegin .It libg2c Pq Fl lg2c Support routines for Fortran functions. These two libraries were separated to allow linking Fortran code with other languages on ELF platforms. See .Xr g77 1 . .Pp .It libgssapi Pq Fl lgssapi The Generic Security Service Application Program Interface .Pq GSS-API provides security services to callers in a generic fashion. .\" See .\" .Xr gssapi 3 . .Pp .It libiberty Pq Fl liberty Collection of subroutines missing in other operating systems, as well as the C++ demangler and other functions used by the GNU toolchain. .Pp .It libkadm5clnt Pq Fl lkadm5clnt Kerberos administration client library, for talking to a Kerberos database. Clients communicate via the network. .Pp .It libkadm5srv Pq Fl lkadm5srv Kerberos administration server library, for talking to a Kerberos database. Servers talk directly to the database. .Pp .It libkeynote Pq Fl lkeynote System library for the keynote trust-management system. Trust-management systems provide standard, general-purpose mechanisms for specifying application security policies and credentials. Functions using the libkeynote library must be linked with the .Em libm and .Em libcrypto libraries, i.e.\& .Fl lkeynote lm lcrypto . See .Xr keynote 3 and .Xr keynote 4 . .Pp .It libkrb5 Pq Fl lkrb5 .It libasn1 Pq Fl lasn1 .It libcom_err Pq Fl lcom_err .It libhdb Pq Fl lhdb .It libkafs Pq Fl lkafs Kerberos 5 libraries. The libraries .Em libasn1 , .Em libcom_err , .Em libhdb , and .Em libkafs are all hard links to .Em libkrb5 . See .Sq info heimdal . .Pp .It libkvm Pq Fl lkvm Kernel memory interface library. Provides a uniform interface for accessing kernel virtual memory images, including live systems and crash dumps. See .Xr kvm 3 . .Pp .It libl Pq Fl l\&l .It libfl Pq Fl lfl The library for .Xr lex 1 , a lexical analyzer generator. The .Em libfl library is a hard link to .Em libl . .Pp .It libm Pq Fl lm Mathematical functions which comprise the C math library, .Em libm . See .Xr math 3 . .Pp .It libmenu Pq Fl lmenu Terminal-independent facilities for composing menu systems on character-cell terminals. Functions using the .Em libmenu library must be linked with the .Em libcurses library, i.e.\& .Fl lmenu lcurses . See .Xr menu 3 . .Pp .It libmilter Pq Fl lmilter The .Xr sendmail 8 mail filter API. See the documentation in .Pa /usr/share/doc/html/milter/ . .Pp .It libmmalloc Pq Fl lmmalloc GNU memory-mapped malloc package. In this implementation, .Xr mmap 2 is used to obtain memory from the system, rather than .Xr sbrk 2 . See .Sq info mmalloc . .Pp .It libobjc Pq Fl lobjc Library for Objective C, an object-oriented superset of ANSI C. Use this to compile Objective C programs. .Pp .It libocurses Pq Fl locurses .It libotermcap Pq Fl lotermcap Routines to provide the user with a method of updating screens with reasonable optimisation. The .Xr ocurses 3 library is compatible with the .Em curses library provided in 4.3. .Em libotermcap is the 4.3-compatible .Em termcap library, and is a hard link to .Em libocurses . See .Xr otermcap 3 . .Pp .It libopcodes Pq Fl lopcodes GNU opcode library. .Pp .It libossaudio Pq Fl lossaudio Provides an emulation of the OSS .Pq Linux audio interface. This is used only for porting programs. See .Xr ossaudio 3 . .Pp .It libpanel Pq Fl lpanel Terminal-independent facilities for stacked windows on character-cell terminals. Functions using the .Em libpanel library must be linked with the .Em libcurses library, i.e.\& .Fl lpanel lcurses . See .Xr panel 3 . .Pp .It libpcap Pq Fl lpcap Packet capture library. All packets on the network, even those destined for other hosts, are accessible through this library. See .Xr pcap 3 . .Pp .It libperl Pq Fl lperl Support routines for .Xr perl 1 . .Pp .It libpthread Pq Fl pthread .St -p1003.1-2001 threads API and thread scheduler. Threaded applications should use .Fl pthread not .Fl lpthread . See .Xr pthreads 3 . .Pp .It libreadline Pq Fl lreadline Command line editing interface. See .Xr readline 3 . .Pp .It libresolv Pq Fl lresolv The .Xr resolver 3 routines are included in .Em libc . This is just an empty library for legacy applications that want to link with .Fl lresolv . .Pp .It librpcsvc Pq Fl lrpcsvc Generated by .Xr rpcgen 1 , containing stub functions for many common .Xr rpc 3 protocols. .Pp .It libsectok Pq Fl lsectok Library for communicating with ISO 7816 smartcards. See .Xr sectok 3 . .Pp .It libskey Pq Fl lskey Support library for the S/Key one time password .Pq OTP authentication toolkit. See .Xr skey 3 . .Pp .It libssl Pq Fl lssl The OpenSSL ssl library implements the Secure Sockets Layer .Pq SSL v2/v3 and Transport Layer Security .Pq TLS \&v1 protocols. See .Xr ssl 3 . .Pp .It libstdc++ Pq Fl lstdc++ GCC subroutine library for C++. See .Xr c++ 1 . .Pp .It libusbhid Pq Fl lusbhid Routines to extract data from USB Human Interface Devices .Pq HIDs . See .Xr usbhid 3 . .Pp .It libutil Pq Fl lutil System utility functions. These are currently .Xr check_expire 3 , .Xr fmt_scaled 3 , .Xr fparseln 3 , .Xr getmaxpartitions 3 , .Xr getrawpartition 3 , .Xr login 3 , .Xr login_fbtab 3 , .Xr opendev 3 , .Xr opendisk 3 , .Xr openpty 3 , .Xr pidfile 3 , .Xr pw_init 3 , .Xr pw_lock 3 , .Xr readlabelfs 3 and .Xr uucplock 3 . .Pp .It libwrap Pq Fl lwrap TCP wrapper access control library. See .Xr hosts_access 3 and .Xr rfc1413 3 . .Pp .It liby Pq Fl ly The library for .Xr yacc 1 , an LALR parser generator. .Pp .It libz Pq Fl lz General purpose data compression library. The functions in this library are documented in .Xr compress 3 . The data format is described in RFCs 1950 \- 1952. .El .Pp Platform-specific libraries: .Pp .Bl -tag -width "libkvm" -compact .It libalpha Pq Fl lalpha Alpha I/O and memory access functions. See .Xr inb 2 . .Pp .It libamd64 Pq Fl lamd64 AMD64 I/O and memory access functions. See .Xr amd64_get_ioperm 2 , .Xr amd64_get_ldt 2 , .Xr amd64_get_mtrr 2 , .Xr amd64_iopl 2 , and .Xr amd64_vm86 2 . .Pp .It libi386 Pq Fl li386 i386 I/O and memory access functions. See .Xr i386_get_ioperm 2 , .Xr i386_get_ldt 2 , .Xr i386_iopl 2 , and .Xr i386_vm86 2 . .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.so.30.1 libc_p.a libc_pic.a .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 .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 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 _pic.a suffix 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. PIC code is used by shared libraries, which can make them slower. The C compiler, .Xr cc 1 , can be instructed to generate PIC code, or to link with PIC libraries, 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 PIC versions of libraries and dynamic libraries can be prevented by setting the variable .Dv NOPIC in .Pa /etc/mk.conf . The building of profiling versions of libraries and/or dynamic libraries can be prevented by setting the variable .Dv NOPROFILE in .Pa /etc/mk.conf . See .Xr mk.conf 5 for more details. .Sh FILES .Bl -tag -width /usr/lib/libotermcap.a -compact .It Pa /usr/lib/libasn1.a .It Pa /usr/lib/libbfd.a .It Pa /usr/lib/libc.a .It Pa /usr/lib/libcom_err.a .It Pa /usr/lib/libcompat.a .It Pa /usr/lib/libcrypto.a .It Pa /usr/lib/libcurses++.a .It Pa /usr/lib/libcurses.a .It Pa /usr/lib/libdes.a .It Pa /usr/lib/libedit.a .It Pa /usr/lib/libevent.a .It Pa /usr/lib/libfl.a .It Pa /usr/lib/libform.a .It Pa /usr/lib/libfrtbegin.a .It Pa /usr/lib/libg2c.a .It Pa /usr/lib/libgssapi.a .It Pa /usr/lib/libhdb.a .It Pa /usr/lib/libiberty.a .It Pa /usr/lib/libkadm5clnt.a .It Pa /usr/lib/libkadm5srv.a .It Pa /usr/lib/libkafs.a .It Pa /usr/lib/libkeynote.a .It Pa /usr/lib/libkrb5.a .It Pa /usr/lib/libkvm.a .It Pa /usr/lib/libl.a .It Pa /usr/lib/libm.a .It Pa /usr/lib/libmenu.a .It Pa /usr/lib/libmilter.a .It Pa /usr/lib/libmmalloc.a .It Pa /usr/lib/libncurses.a .It Pa /usr/lib/libobjc.a .It Pa /usr/lib/libocurses.a .It Pa /usr/lib/libopcodes.a .It Pa /usr/lib/libossaudio.a .It Pa /usr/lib/libotermcap.a .It Pa /usr/lib/libpanel.a .It Pa /usr/lib/libpcap.a .It Pa /usr/lib/libperl.a .It Pa /usr/lib/libpthread.a .It Pa /usr/lib/libreadline.a .It Pa /usr/lib/libresolv.a .It Pa /usr/lib/librpcsvc.a .It Pa /usr/lib/libsectok.a .It Pa /usr/lib/libskey.a .It Pa /usr/lib/libssl.a .It Pa /usr/lib/libstdc++.a .It Pa /usr/lib/libtermcap.a .It Pa /usr/lib/libtermlib.a .It Pa /usr/lib/libusbhid.a .It Pa /usr/lib/libutil.a .It Pa /usr/lib/libwrap.a .It Pa /usr/lib/liby.a .It Pa /usr/lib/libz.a .Pp .It Pa /usr/lib/libalpha.a .It Pa /usr/lib/libamd64.a .It Pa /usr/lib/libi386.a .El .Sh SEE ALSO .Xr ar 1 , .Xr c++ 1 , .Xr cc 1 , .Xr g77 1 , .Xr gcc-local 1 , .Xr gprof 1 , .Xr ld 1 , .Xr ld.so 1 , .Xr lex 1 , .Xr nm 1 , .Xr perl 1 , .Xr ranlib 1 , .Xr yacc 1 , .Xr intro 2 , .Xr compress 3 , .Xr crypto 3 , .Xr curses 3 , .Xr des_crypt 3 , .Xr editline 3 , .Xr event 3 , .Xr form 3 , .Xr hosts_access 3 , .Xr keynote 3 , .Xr kvm 3 , .Xr math 3 , .Xr menu 3 , .Xr ocurses 3 , .Xr ossaudio 3 , .Xr panel 3 , .Xr pcap 3 , .Xr pthreads 3 , .Xr readline 3 , .Xr resolver 3 , .Xr rfc1413 3 , .Xr rpc 3 , .Xr sectok 3 , .Xr skey 3 , .Xr ssl 3 , .Xr stdio 3 , .Xr termcap 3 , .Xr usbhid 3 , .Xr keynote 4 , .Xr mk.conf 5 .Sh HISTORY An .Nm manual appeared in .At v7 .