Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
INTRO(3)	       FreeBSD Library Functions Manual		      INTRO(3)

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	func-
     tions, 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):

     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 func-
	     tions.  There are several ``libraries'' or	groups of functions
	     included inside of	libc: the standard I/O routines, database rou-
	     tines, bit	operators, string operators, character tests and char-
	     acter operators, DES encryption routines, storage allocation,
	     time functions, signal handling, and more.

     libcompat (-lcompat)
	     Functions which are obsolete but are available for	compatibility
	     with 4.3BSD.  In particular, a number of system call interfaces
	     provided in previous releases of BSD have been included for
	     source code compatibility.	 Use of	these routines should, for the
	     most part,	be avoided.  The manual	page entry for each compati-
	     bility routine indicates the proper interface to use.

     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-dimen-
	     sional 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 pur-
	     poses 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).

     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).

     libgcc (-lgcc)
	     GCC runtime support, including long arithmetic, propolice,	and
	     language independent exception support.  Note: users do not nor-
	     mally have	to explicitly link with	this library.

     libgssapi (-lgssapi)
	     The Generic Security Service Application Program Interface
	     (GSS-API) provides	security services to callers in	a generic
	     fashion.  See gssapi(3).

     libiberty (-liberty)
	     Collection	of subroutines missing in other	operating systems, as
	     well as the C++ demangler and other functions used	by the GNU
	     toolchain.

     libkadm5clnt (-lkadm5clnt)
	     Kerberos administration client library, for talking to a Kerberos
	     database.	Clients	communicate via	the network.

     libkadm5srv (-lkadm5srv)
	     Kerberos administration server library, for talking to a Kerberos
	     database.	Servers	talk directly to the database.

     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).

     libkrb5 (-lkrb5)
     libasn1 (-lasn1)
     libcom_err	(-lcom_err)
     libhdb (-lhdb)
     libkafs (-lkafs)
	     Kerberos 5	libraries.  The	libraries libasn1, libcom_err, libhdb,
	     and libkafs are all hard links to libkrb5.	 See krb5(3).

     libkvm (-lkvm)
	     Kernel memory interface library.  Provides	a uniform interface
	     for accessing kernel virtual memory images, including live	sys-
	     tems 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)
     libmenuw (-lmenuw)
	     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).

     libmilter (-lmilter)
	     The sendmail(8) mail filter API.  See the documentation in
	     /usr/share/doc/html/milter/.

     libobjc (-lobjc)
	     Library for Objective C, an object-oriented superset of ANSI C.
	     Use this to compile Objective C programs.

     libocurses	(-locurses)
     libotermcap (-lotermcap)
	     Routines to provide the user with a method	of updating screens
	     with reasonable optimisation.  The	ocurses(3) library is compati-
	     ble with the curses library provided in 4.3.  libotermcap is the
	     4.3-compatible termcap library, and is a hard link	to libocurses.
	     See otermcap(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-charcter 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).

     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) authentica-
	     tion toolkit.  See	skey(3).

     libsndio (-lsndio)
	     Library for audio(4) hardware and the aucat(1) audio server.  See
	     sio_open(3).

     libsqlite3	(-lsqlite3)
	     SQL database library.  See	sqlite3(1).

     libssl (-lssl)
	     The OpenSSL ssl library implements	the Secure Sockets Layer (SSL
	     v2/v3) and	Transport Layer	Security (TLS v1) protocols.  See
	     ssl(3).

     libstdc++ (-lstdc++)
	     GCC subroutine library for	C++.  See c++(1).  Note: users do not
	     normally have to explicitly link with this	library.

     libsupc++ (-lsupc++)
	     (non GCC 2.95 systems only) C++ core language support (excep-
	     tions, new, typeinfo).  Note: users do not	normally have to
	     explicitly	link with this library.

     libusbhid (-lusbhid)
	     Routines to extract data from USB Human Interface Devices (HIDs).
	     See usbhid(3).

     libutil (-lutil)
	     System utility functions.	These are currently check_expire(3),
	     fmt_scaled(3), fparseln(3), getmaxpartitions(3),
	     getrawpartition(3), imsg_init(3), login(3), login_fbtab(3),
	     opendev(3), opendisk(3), openpty(3), pidfile(3), pkcs5_pbkdf2(3),
	     pw_init(3), pw_lock(3), readlabelfs(3) and	uucplock(3).

     libwrap (-lwrap)
	     TCP wrapper access	control	library.  See hosts_access(3) and
	     rfc1413(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_get_ioperm(2)
	     and amd64_iopl(2).

     libarm (-larm)
	     ARM I/O and memory	access functions.  See arm_drain_writebuf(2)
	     and arm_sync_icache(2).

     libi386 (-li386)
	     i386 I/O and memory access	functions.  See	i386_get_ioperm(2),
	     i386_get_ldt(2), i386_iopl(2), and	i386_vm86(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	pro-
     filing 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 pro-
     duce position-independent executables (PIEs) by default, contain posi-
     tion-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 com-
     piler, 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 vari-
     able 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), gcc-local(1), gprof(1), ld(1), ld.so(1), nm(1), ranlib(1),
     mk.conf(5)

HISTORY
     An	intro manual appeared in Version 7 AT&T	UNIX.

FreeBSD	10.1		       November	23, 2014		  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | LIBRARY TYPES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=intro&sektion=3&manpath=OpenBSD+5.3>

home | help