diff options
Diffstat (limited to 'static/freebsd/man3/intro.3 3.html')
| -rw-r--r-- | static/freebsd/man3/intro.3 3.html | 262 |
1 files changed, 262 insertions, 0 deletions
diff --git a/static/freebsd/man3/intro.3 3.html b/static/freebsd/man3/intro.3 3.html new file mode 100644 index 00000000..fc96555d --- /dev/null +++ b/static/freebsd/man3/intro.3 3.html @@ -0,0 +1,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> |