.\"	$FabBSD$
.\"	$OpenBSD: intro.3,v 1.36 2008/06/10 07:01:01 jmc 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 $Mdocdate: June 10 2008 $
.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 libcnc Pq Fl lcnc
Machine control functions.
Provides a simple programmatic interface to the FabBSD kernel's machine
control facilities.
.Pp
.It libcompat Pq Fl lcompat
Functions which are obsolete but are available for compatibility with
previous FabBSD releases.
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 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 libexpat Pq Fl lexpat
Library routines for parsing XML documents.
.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 libgcc Pq Fl 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.
.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 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 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 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 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 .
Note: users do not normally have to explicitly link with this library.
.Pp
.It libreadline Pq Fl lreadline
Command line editing interface.
See
.Xr readline 3 .
.Pp
.It librpcsvc Pq Fl lrpcsvc
Generated by
.Xr rpcgen 1 ,
containing stub functions for many common
.Xr rpc 3
protocols.
.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 .
Note: users do not normally have to explicitly link with this library.
.Pp
.It libsupc++ Pq Fl lsupc++
(GCC 3.3.x systems only)
C++ core language support
(exceptions, new, typeinfo).
Note: users do not normally have to explicitly link with this library.
.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:
.Bl -tag -width "libkvm"
.It libalpha Pq Fl lalpha
Alpha I/O and memory access functions.
See
.Xr inb 2 .
.It libamd64 Pq Fl lamd64
AMD64 I/O and memory access functions.
See
.Xr amd64_get_ioperm 2
and
.Xr amd64_iopl 2 .
.It libarm Pq Fl larm
ARM I/O and memory access functions.
See
.Xr arm_drain_writebuf 2
and
.Xr arm_sync_icache 2 .
.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/libbfd.a
.It Pa /usr/lib/libc.a
.It Pa /usr/lib/libcnc.a
.It Pa /usr/lib/libcompat.a
.It Pa /usr/lib/libcrypto.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/libexpat.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/gcc-lib/${ARCH}-unknown-fabbsd${OSREV}/${GCCREV}/fpic/libgcc.a
.It Pa /usr/lib/libiberty.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/libncurses.a
.It Pa /usr/lib/libobjc.a
.It Pa /usr/lib/libocurses.a
.It Pa /usr/lib/libopcodes.a
.It Pa /usr/lib/libotermcap.a
.It Pa /usr/lib/libpanel.a
.It Pa /usr/lib/libperl.a
.It Pa /usr/lib/libpthread.a
.It Pa /usr/lib/libreadline.a
.It Pa /usr/lib/librpcsvc.a
.It Pa /usr/lib/libskey.a
.It Pa /usr/lib/libssl.a
.It Pa /usr/lib/libstdc++.a
.It Pa /usr/lib/libsupc++.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/libarm.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 cnc 3 ,
.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 kvm 3 ,
.Xr math 3 ,
.Xr menu 3 ,
.Xr ocurses 3 ,
.Xr panel 3 ,
.Xr pthreads 3 ,
.Xr readline 3 ,
.Xr rfc1413 3 ,
.Xr rpc 3 ,
.Xr skey 3 ,
.Xr ssl 3 ,
.Xr stdio 3 ,
.Xr termcap 3 ,
.Xr usbhid 3 ,
.Xr mk.conf 5
.Sh HISTORY
An
.Nm
manual appeared in
.At v7 .