xref: /openbsd-src/share/man/man3/intro.3 (revision d1df930ffab53da22f3324c32bed7ac5709915e6)
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