1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
|
<table class="head">
<tr>
<td class="head-ltitle">INTRO(3)</td>
<td class="head-vol">Library Functions Manual</td>
<td class="head-rtitle">INTRO(3)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">intro</code> —
<span class="Nd">introduction to the C libraries</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<table class="Nm">
<tr>
<td><code class="Nm">cc</code></td>
<td>[<var class="Ar">flags</var>] <var class="Ar">file ...</var>
[<code class="Fl">-llibrary</code>]</td>
</tr>
</table>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">This section provides 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, <i class="Em">libc</i>. Other
libraries, such as the math library, <i class="Em">libm</i>, must be
indicated at compile time with the <code class="Fl">-l</code> option of the
compiler.</p>
<p class="Pp">The various libraries (followed by the loader flag):</p>
<dl class="Bl-tag">
<dt id="libbluetooth"><a class="permalink" href="#libbluetooth"><i class="Em">libbluetooth</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">bluetooth</var>) The bluetooth
library. See <a class="Xr">bluetooth(3)</a>.</dd>
<dt id="libc"><a class="permalink" href="#libc"><i class="Em">libc</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">c</var>) Standard C library
functions. When using the C compiler <a class="Xr">cc(1)</a>, it is not
necessary to supply the loader flag
<code class="Fl">-l</code><var class="Ar">c</var> for these functions.
There are several `libraries' or groups of functions included inside of
<i class="Em">libc</i>:
<dl class="Bl-tag">
<dt>standard I/O routines</dt>
<dd>see <a class="Xr">stdio(3)</a></dd>
<dt>database routines</dt>
<dd>see <a class="Xr">db(3)</a></dd>
<dt>bit string operators</dt>
<dd>see <a class="Xr">bitstring(3)</a></dd>
<dt>bit and byte utilities</dt>
<dd>see <a class="Xr">stdbit(3)</a></dd>
<dt>string operators</dt>
<dd>see <a class="Xr">string(3)</a> and <a class="Xr">bstring(3)</a></dd>
<dt>character tests and character operators</dt>
<dd>see <a class="Xr">ctype(3)</a></dd>
<dt>storage allocation</dt>
<dd>see <a class="Xr">mpool(3)</a></dd>
<dt>regular-expressions</dt>
<dd>see <a class="Xr">regex(3)</a></dd>
<dt>remote procedure calls (RPC)</dt>
<dd>see <a class="Xr">rpc(3)</a></dd>
<dt>time functions</dt>
<dd>see <a class="Xr">time(3)</a></dd>
<dt>signal handling</dt>
<dd>see <a class="Xr">signal(3)</a></dd>
</dl>
</dd>
<dt id="libcalendar"><a class="permalink" href="#libcalendar"><i class="Em">libcalendar</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">calendar</var>) The calendar
arithmetic library. See <a class="Xr">calendar(3)</a>.</dd>
<dt id="libcam"><a class="permalink" href="#libcam"><i class="Em">libcam</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">cam</var>) The common access
method user library. See <a class="Xr">cam(3)</a>.</dd>
<dt id="libcrypt"><a class="permalink" href="#libcrypt"><i class="Em">libcrypt</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">crypt</var>) The crypt library.
See <a class="Xr">crypt(3)</a>.</dd>
<dt id="libcurses"><a class="permalink" href="#libcurses"><i class="Em">libcurses</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">curses</var>
<code class="Fl">-l</code><var class="Ar">termcap</var>) Terminal
independent screen management routines for two dimensional non-bitmap
display terminals. See <a class="Xr">ncurses(3)</a>.</dd>
<dt id="libcuse"><a class="permalink" href="#libcuse"><i class="Em">libcuse</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">cuse</var>) The userland
character device library. See <a class="Xr">cuse(3)</a>.</dd>
<dt id="libcompat"><a class="permalink" href="#libcompat"><i class="Em">libcompat</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">compat</var>) Functions which
are obsolete but are available for compatibility with
<span class="Ux">4.3BSD</span>. In particular, a number of system call
interfaces provided in previous releases of <span class="Ux">BSD</span>
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.</dd>
<dt id="libdevinfo"><a class="permalink" href="#libdevinfo"><i class="Em">libdevinfo</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">devinfo</var>) The Device and
Resource Information Utility library. See
<a class="Xr">devinfo(3)</a>.</dd>
<dt id="libdevstat"><a class="permalink" href="#libdevstat"><i class="Em">libdevstat</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">devstat</var>) The Device
Statistics library. See <a class="Xr">devstat(3)</a>.</dd>
<dt id="libdwarf"><a class="permalink" href="#libdwarf"><i class="Em">libdwarf</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">dwarf</var>) The DWARF access
library. See <a class="Xr">dwarf(3)</a>.</dd>
<dt id="libelf"><a class="permalink" href="#libelf"><i class="Em">libelf</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">elf</var>) The ELF access
library. See <a class="Xr">elf(3)</a>.</dd>
<dt id="libfetch"><a class="permalink" href="#libfetch"><i class="Em">libfetch</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">fetch</var>) The file transfer
library. See <a class="Xr">fetch(3)</a>.</dd>
<dt id="libfigpar"><a class="permalink" href="#libfigpar"><i class="Em">libfigpar</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">figpar</var>) The configuration
file parsing library. See <a class="Xr">figpar(3)</a>.</dd>
<dt id="libgpio"><a class="permalink" href="#libgpio"><i class="Em">libgpio</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">gpio</var>) The general-purpose
input output library (GPIO). See <a class="Xr">gpio(3)</a>.</dd>
<dt id="libgssapi"><a class="permalink" href="#libgssapi"><i class="Em">libgssapi</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">gssapi</var>) The generic
security service application programming interface. See
<a class="Xr">gssapi(3)</a>.</dd>
<dt id="libjail"><a class="permalink" href="#libjail"><i class="Em">libjail</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">jail</var>) The jail library.
See <a class="Xr">jail(3)</a>.</dd>
<dt id="libkvm"><a class="permalink" href="#libkvm"><i class="Em">libkvm</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">kvm</var>) Functions used to
access kernel memory are in this library. They can be used against both a
running system and a crash dump. See <a class="Xr">kvm(3)</a>.</dd>
<dt id="libl"><a class="permalink" href="#libl"><i class="Em">libl</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">l</var>) The library for
<a class="Xr">lex(1)</a>.</dd>
<dt id="libm"><a class="permalink" href="#libm"><i class="Em">libm</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">m</var>) The math library. See
<a class="Xr">math(3)</a>.</dd>
<dt id="libmd"><a class="permalink" href="#libmd"><i class="Em">libmd</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">md</var>) The message digest
library. See <a class="Xr">md4(3)</a>, <a class="Xr">md5(3)</a>,
<a class="Xr">sha(3)</a>, <a class="Xr">sha256(3)</a>,
<a class="Xr">sha512(3)</a>, <a class="Xr">ripemd(3)</a>,
<a class="Xr">skein(3)</a>.</dd>
<dt id="libmp"><a class="permalink" href="#libmp"><i class="Em">libmp</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">mp</var>)</dd>
<dt id="libpam"><a class="permalink" href="#libpam"><i class="Em">libpam</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">pam</var>) The pluggable
authentication module library. See <a class="Xr">pam(3)</a>.</dd>
<dt id="libpcap"><a class="permalink" href="#libpcap"><i class="Em">libpcap</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">pcap</var>) The packet capture
library. See <a class="Xr">pcap(3)</a>.</dd>
<dt id="libpmc"><a class="permalink" href="#libpmc"><i class="Em">libpmc</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">pmc</var>) The performance
counters library. See <a class="Xr">pmc(3)</a>.</dd>
<dt id="libpthread"><a class="permalink" href="#libpthread"><i class="Em">libpthread</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">pthread</var>) The POSIX
threads library. See <a class="Xr">pthread(3)</a>.</dd>
<dt id="libstdthreads"><a class="permalink" href="#libstdthreads"><i class="Em">libstdthreads</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">stdthreads</var>) The ISO C11
standard <code class="In"><<a class="In">threads.h</a>></code>
library. See <a class="Xr">thrd_create(3)</a>.</dd>
<dt id="libsysdecode"><a class="permalink" href="#libsysdecode"><i class="Em">libsysdecode</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">sysdecode</var>) The system
argument decoding library. See <a class="Xr">sysdecode(3)</a>.</dd>
<dt id="libtermcap"><a class="permalink" href="#libtermcap"><i class="Em">libtermcap</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">termcap</var>) The terminal
independent operation library package. See
<a class="Xr">termcap(3)</a>.</dd>
<dt id="libusb"><a class="permalink" href="#libusb"><i class="Em">libusb</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">usb</var>) The USB access
library. See <a class="Xr">usb(3)</a>.</dd>
<dt id="libvgl"><a class="permalink" href="#libvgl"><i class="Em">libvgl</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">vgl</var>) The video graphics
library. See <a class="Xr">vgl(3)</a>.</dd>
<dt id="liby"><a class="permalink" href="#liby"><i class="Em">liby</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">y</var>) The library for
<a class="Xr">yacc(1)</a>.</dd>
<dt id="libz"><a class="permalink" href="#libz"><i class="Em">libz</i></a></dt>
<dd>(<code class="Fl">-l</code><var class="Ar">z</var>) The general-purpose
data compression library. See <a class="Xr">zlib(3)</a>.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="FILES"><a class="permalink" href="#FILES">FILES</a></h1>
<dl class="Bl-tag Bl-compact">
<dt><span class="Pa">/usr/lib/libc.a</span></dt>
<dd>the C library</dd>
<dt><span class="Pa">/usr/lib/libm.a</span></dt>
<dd>the math library</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="LIBRARY_TYPES"><a class="permalink" href="#LIBRARY_TYPES">LIBRARY
TYPES</a></h1>
<p class="Pp">The system libraries are located in <span class="Pa">/lib</span>
and <span class="Pa">/usr/lib</span>. A library has the following naming
convention:</p>
<div class="Bd Pp Bd-indent">
<pre>libc.so.7</pre>
</div>
<p class="Pp">Libraries with an ‘.a’ suffix are static. When a
program is linked against a static library, all necessary library code will
be included in the binary. This means the binary can be run even when the
libraries are unavailable. However, it can be inefficient with both disk
space and memory usage during execution. The C compiler,
<a class="Xr">cc(1)</a>, can be instructed to link statically by specifying
the <code class="Fl">-static</code> flag.</p>
<p class="Pp">Libraries with a ‘.so.X’ suffix are dynamic
libraries. When code is linked dynamically, the library code that the
application needs is not included in 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 <a class="Xr">ld.so(1)</a>
reads these data structures and loads them into the process virtual address
space. <a class="Xr">rtld(1)</a> loads the shared libraries when the program
is executed.</p>
<p class="Pp">‘X’ represents the library version number of the
library. In the example above, a binary linked with
<span class="Pa">libc.so.8</span> would not be usable on a system where only
<span class="Pa">libc.so.7</span> is available.</p>
<p class="Pp">The advantages of dynamic libraries are that multiple instances of
the same library can share address space, and the physical size of the
binary is smaller. A namespace per shared library is available via hidden
visibility, allowing multiple compilation units in a library to share things
without making them available to other libraries. It is possible to load
libraries dynamically via <a class="Xr">dlopen(3)</a>. 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. Calls across shared
libraries are also slightly slower and cannot be inlined, not even with link
time optimization. The C compiler, <a class="Xr">cc(1)</a>, can be
instructed to link dynamically by specifying the
<code class="Fl">-shared</code> flag.</p>
<p class="Pp">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. The C compiler, <a class="Xr">cc(1)</a>, can be
instructed to generate PIC code by specifying the
<code class="Fl">-fPIC</code> flag.</p>
<p class="Pp">Static libraries are generated using the <a class="Xr">ar(1)</a>
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.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">ar(1)</a>, <a class="Xr">cc(1)</a>,
<a class="Xr">ld(1)</a>, <a class="Xr">nm(1)</a>,
<a class="Xr">intro(2)</a>, <a class="Xr">math(3)</a>,
<a class="Xr">stdio(3)</a>, <a class="Xr">make.conf(5)</a>,
<a class="Xr">src.conf(5)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">An <code class="Nm">intro</code> manual appeared in
<span class="Ux">Version 7 AT&T UNIX</span>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">November 10, 2025</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
