NAME
intro
—
introduction to the C
libraries
SYNOPSIS
cc |
[flags] file ...
[-llibrary ] |
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,
libc.
Other libraries, such as the math library, libm, must be
indicated at compile time with the -l
option of the
compiler.
The various libraries (followed by the loader flag):
- libLLVM (
-lLLVM
) - LLVM components in a single library.
- libc (
-lc
) - Standard C library functions. When using the C compiler
cc(1), it is not necessary to supply the loader flag
-lc
for these functions. There are several “libraries” or groups of functions included inside of libc: the standard I/O routines, database routines, bit operators, string operators, character tests and character operators, cryptographic routines, storage allocation, time functions, signal handling, and more. - libc++ (
-lc++
) - LLVM standard C++ library. See clang(1). Note: users do not normally have to explicitly link with this library.
- libc++abi (
-lc++abi
) - LLVM C++ runtime library. Note: users do not normally have to explicitly link with this library.
- libcrypto (
-lcrypto
) - The OpenSSL crypto library. Implements a range of cryptographic algorithms, providing such functionality as symmetric encryption, public key cryptography, and certificate handling. See crypto(3).
- libcurses (
-lcurses
) - libncurses (
-lncurses
) - libncursesw (
-lncursesw
) - libtermcap (
-ltermcap
) - libtermlib (
-ltermlib
) - Terminal-independent screen management routines for two-dimensional
non-bitmap display terminals. This implementation is “new
curses” and is a replacement for 4.2BSD
classic curses. The libraries
libncurses,
libncursesw,
libtermcap,
and
libtermlib
are all hard links to libcurses. This is for
compatibility purposes only; new programs should link with
-lcurses
. See curses(3) and termcap(3). - libedit (
-ledit
) - Generic line editing and history functions, similar to those found in
sh(1). Functions using the
libedit library
must be linked with the libcurses library, i.e.
-ledit
-lcurses
. See editline(3). - libelf (
-lelf
) - Library routines for manipulating ELF objects. See elf(3).
- libevent (
-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 event(3).
- libexpat (
-lexpat
) - Library routines for parsing XML documents.
- libform (
-lform
) - libformw (
-lformw
) - Terminal-independent facilities for composing form screens on
character-cell terminals. Functions using the libform
library must be linked with the libcurses library, i.e.
-lform
-lcurses
. libformw is a hard link to libform intended for use with libncursesw wide-character functions. See form(3). - libfuse (
-lfuse
) - File system in userland library. See fuse_main(3).
- libgcc (
-lgcc
) - GCC runtime support, including long arithmetic, propolice, and language independent exception support. Note: users do not normally have to explicitly link with this library.
- libiberty (
-liberty
) - Collection of subroutines missing in other operating systems, as well as the C++ demangler and other functions used by the GNU toolchain.
- libkeynote (
-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 libm and
libcrypto
libraries, i.e.
-lkeynote
-lm
-lcrypto
. See keynote(3) and keynote(4). - libkvm (
-lkvm
) - Kernel memory interface library. Provides a uniform interface for accessing kernel virtual memory images, including live systems and crash dumps. See kvm(3).
- libl (
-ll
) - libfl (
-lfl
) - The library for lex(1), a lexical analyzer generator. The libfl library is a hard link to libl.
- libm (
-lm
) - Mathematical functions which comprise the C math library, libm.
- libmenu (
-lmenu
) - Terminal-independent facilities for composing menu systems on
character-cell terminals. Functions using the libmenu
library must be linked with the libcurses library, i.e.
-lmenu
-lcurses
. libmenuw is a hard link to libmenu intended for use with libncursesw wide-character functions. See menu(3). - libossaudio (
-lossaudio
) - Provides an emulation of the OSS (Linux) audio interface. This is used only for porting programs. See ossaudio(3).
- libpanel (
-lpanel
) - libpanelw (
-lpanelw
) - Terminal-independent facilities for stacked windows on character-cell
terminals. Functions using the libpanel library must be
linked with the libcurses library, i.e.
-lpanel
-lcurses
. libpanelw is a hard link to libpanel intended for use with libncursesw wide-character functions. See panel(3). - libpcap (
-lpcap
) - Packet capture library. All packets on the network, even those destined for other hosts, are accessible through this library. See pcap(3).
- libperl (
-lperl
) - Support routines for perl(1).
- libpthread (
-lpthread
) - IEEE Std 1003.1-2001 (“POSIX.1”) threads API. See pthreads(3).
- libradius (
-lradius
) - Support routines for the RADIUS library. See radius_new_request_packet(3).
- libreadline (
-lreadline
) - Command line editing interface. See readline(3).
- librpcsvc (
-lrpcsvc
) - Generated by rpcgen(1), containing stub functions for many common rpc(3) protocols.
- libskey (
-lskey
) - Support library for the S/Key one time password (OTP) authentication toolkit. See skey(3).
- libsndio (
-lsndio
) - Library for audio(4) hardware and the aucat(1) audio server. See sio_open(3).
- libssl (
-lssl
) - The OpenSSL ssl library implements the Secure Sockets Layer (SSL v3) and Transport Layer Security (TLS v1) protocols. See ssl(3).
- libstdc++ (
-lstdc++
) - GNU standard C++ library. See g++(1). Note: users do not normally have to explicitly link with this library.
- libsupc++ (
-lsupc++
) - GNU C++ runtime library. Note: users do not normally have to explicitly link with this library.
- libtls (
-ltls
) - A Transport Layer Security library with a clean and easy to use interface. See tls_init(3).
- libusbhid (
-lusbhid
) - Routines to extract data from USB Human Interface Devices (HIDs). See usbhid(3).
- libutil (
-lutil
) - System utility functions. These are currently bcrypt_pbkdf(3), check_expire(3), fmt_scaled(3), fparseln(3), getmaxpartitions(3), getrawpartition(3), imsg_init(3), isduid(3), login(3), login_fbtab(3), ohash_init(3), ohash_interval(3), opendev(3), opendisk(3), openpty(3), pidfile(3), pkcs5_pbkdf2(3), pw_init(3), pw_lock(3), readlabelfs(3) and uucplock(3).
- liby (
-ly
) - The library for yacc(1), an LALR parser generator.
- libz (
-lz
) - General purpose data compression library. The functions in this library are documented in compress(3). The data format is described in RFCs 1950 - 1952.
Platform-specific libraries:
- libalpha (
-lalpha
) - Alpha I/O and memory access functions. See inb(2).
- libamd64 (
-lamd64
) - AMD64 I/O and memory access functions. See amd64_iopl(2).
- libi386 (
-li386
) - i386 I/O and memory access functions. See i386_iopl(2).
LIBRARY TYPES
The system libraries are located in /usr/lib. Typically, a library will have a number of variants:
libc.a libc_p.a libc.so.30.1
Libraries with an ‘.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, cc(1), can be instructed to link statically by specifying the
-static
flag.
Libraries with a ‘_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
gprof(1). The C compiler,
cc(1),
can be instructed to generate profiling code, or to link with profiling
libraries, by specifying the -pg
flag.
Libraries with a ‘.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 ld.so(1) reads these data structures, and loads them at a virtual address using the mmap(2) system call.
‘X’ represents the major number of the library, and ‘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 ‘3’ would be linkable against libc.so.30.1, while a binary linked with major number ‘31’ would not.
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,
cc(1),
can be instructed to link dynamically by specifying the
-shared
flag, although on systems that support it,
this will be the default and need not be specified.
Shared libraries, as well as static libraries on architectures
which produce position-independent executables (PIEs) by default, contain
position-independent code (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. The C compiler,
cc(1),
can be instructed to generate PIC code by specifying the
-fpic
or -fPIC
flags.
With the exception of dynamic libraries, libraries are generated using the 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 ranlib(1) and can be viewed using nm(1).
The building of dynamic libraries can be prevented by setting the
variable NOPIC
in
/etc/mk.conf. The building of profiling versions of
libraries can be prevented by setting the variable
NOPROFILE
in /etc/mk.conf.
See mk.conf(5) for more details.
SEE ALSO
ar(1), cc(1), gprof(1), ld(1), ld.so(1), nm(1), ranlib(1), mk.conf(5)
HISTORY
An intro
manual for section 3 first
appeared in Version 7 AT&T UNIX.