library update and description of lib formats;

corrections/suggestions millert@

1 files changed, 533 insertions, 95 deletions

diff --git a/share/man/man3/intro.3 b/share/man/man3/intro.3
index b07aad2a836..c550d91cc7d 100644
--- a/share/man/man3/intro.3
+++ b/share/man/man3/intro.3
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: intro.3,v 1.17 2003/07/25 09:25:48 jmc Exp $
+.\"	$OpenBSD: intro.3,v 1.18 2003/08/27 07:50:13 jmc Exp $
 .\"	$NetBSD: intro.3,v 1.5 1995/05/10 22:46:24 jtc Exp $
 .\"
 .\" Copyright (c) 1980, 1991, 1993
@@ -36,6 +36,11 @@
 .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.
@@ -48,13 +53,21 @@ must be indicated at compile time with the
 option of the compiler.
 .Pp
 The various libraries (followed by the loader flag):
-.Bl -tag -width Ds
-.It libc Pq Fl l Ns Ar c
+.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 l Ns Ar c
+.Fl lc
 for these functions.
 There are several
 .Dq libraries
@@ -70,12 +83,8 @@ storage allocation,
 time functions,
 signal handling,
 and more.
-.It libcurses Pq Fl l Ns Ar curses
-Terminal independent screen management routines for two-dimensional
-non-bitmap display terminals.
-See
-.Xr curses 3 .
-.It libcompat Pq Fl l Ns Ar compat
+.Pp
+.It libcompat Pq Fl lcompat
 Functions which are obsolete but are available for compatibility with
 .Bx 4.3 .
 In particular, a number of system call interfaces provided in previous
@@ -85,49 +94,501 @@ 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.
-.It libkvm Pq Fl l Ns Ar kvm
-Kernel virtual interface library.
+.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 libcurses++ Pq Fl lcurses++
+C++ interface to ncurses routines.
+See
+.Xr curses 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 libform Pq Fl lform
+Terminal-independant 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 libgssapi Pq Fl lgssapi
+The Generic Security Service Application Program Interface
+.Pq GSS-API
+provides security services to callers in a generic fashion.
+.\" See
+.\" .Xr gssapi 3 .
+.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 libkadm5clnt Pq Fl lkadm5clnt
+Kerberos administration client library,
+for talking to a Kerberos database.
+Clients communicate via the network.
+.Pp
+.It libkadm5srv Pq Fl lkadm5srv
+Kerberos administration server library,
+for talking to a Kerberos database.
+Servers talk directly to the database.
+.Pp
+.It libkeynote Pq Fl 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
+.Em libm
+and
+.Em libcrypto
+libraries, i.e.\&
+.Fl lkeynote lm lcrypto .
+See
+.Xr keynote 3
+and
+.Xr keynote 4 .
+.Pp
+.It libkrb5 Pq Fl lkrb5
+.It libasn1 Pq Fl lasn1
+.It libcom_err Pq Fl lcom_err
+.It libhdb Pq Fl lhdb
+.It libkafs Pq Fl lkafs
+Kerberos 5 libraries.
+The libraries
+.Em libasn1 ,
+.Em libcom_err ,
+.Em libhdb ,
+and
+.Em libkafs
+are all hard links to
+.Em libkrb5 .
+See
+.Sq info heimdal .
+.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 .
-.It libl Pq Fl l Ns Ar l
+.Pp
+.It libl Pq Fl l\&l
+.It libfl Pq Fl lfl
 The library for
-.Xr lex 1 .
-.It libm Pq Fl l Ns Ar m
-The math library,
+.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 .
-.It libpthread Pq Ar -pthread
+.Pp
+.It libmenu Pq Fl lmenu
+Terminal-independant 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 libmmalloc Pq Fl lmmalloc
+GNU memory-mapped malloc package.
+In this implementation,
+.Xr mmap 2
+is used to obtain memory from the system,
+rather than
+.Xr sbrk 2 .
+See
+.Sq info mmalloc .
+.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 libossaudio Pq Fl lossaudio
+Provides an emulation of the OSS
+.Pq Linux
+audio interface.
+This is used only for porting programs.
+See
+.Xr ossaudio 3 .
+.Pp
+.It libpanel Pq Fl lpanel
+Terminal-independant 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 libpcap Pq Fl lpcap
+Packet capture library.
+All packets on the network, even those destined for other hosts,
+are accessible through this library.
+See
+.Xr pcap 3 .
+.Pp
+.It libperl Pq Fl lperl
+Support routines for
+.Xr perl 1 .
+.Pp
+.It libpthread Pq Fl pthread
 .St -p1003.1-01
-threads (see
-.Xr pthreads 3 )
-API and thread scheduler.
+threads API and thread scheduler.
 Threaded applications should use
-.Ar -pthread
+.Fl pthread
 not
-.Fl l Ns Ar pthread .
-.It libtermcap Pq Fl l Ns Ar termcap
-The terminal independent operation library package.
-(See
-.Xr termcap 3 . )
+.Fl lpthread .
+See
+.Xr pthreads 3 .
+.Pp
+.It libreadline Pq Fl lreadline
+Command line editing interface.
+See
+.Xr readline 3 .
+.Pp
+.It libresolv Pq Fl lresolv
+The
+.Xr resolver 3
+routines are included in
+.Em libc .
+This is just an empty library for legacy applications that want to link with
+.Fl lresolv .
+.Pp
+.It librpcsvc Pq Fl lrpcsvc
+Generated by
+.Xr rpcgen 1 ,
+containing stub functions for many common
+.Xr rpc 3
+protocols.
+.Pp
+.It libsectok Pq Fl lsectok
+Library for communicating with ISO 7816 smartcards.
+See
+.Xr sectok 3 .
+.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 .
+.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_getconf 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 the header file
+.Aq Pa zlib.h .
+The data format is described in RFCs 1950 \- 1952.
 .El
+.Pp
+Platform-specific libraries:
+.Pp
+.Bl -tag -width "libkvm" -compact
+.It libalpha Pq Fl lalpha
+Alpha I/O and memory access functions.
+See
+.Xr inb 2 .
+.Pp
+.It libi386 Pq Fl li386
+i386 I/O and memory access functions.
+See
+.Xr i386_get_ioperm 2 ,
+.Xr i386_set_ioperm 2 ,
+.Xr i386_get_ldt 2 ,
+.Xr i386_set_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-independant 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/libasn1.a
 .It Pa /usr/lib/libbfd.a
 .It Pa /usr/lib/libc.a
-C library.
+.It Pa /usr/lib/libcom_err.a
 .It Pa /usr/lib/libcompat.a
-4.3 compatibility library.
 .It Pa /usr/lib/libcrypto.a
-.Xr ssl 8
-support library.
 .It Pa /usr/lib/libcurses++.a
-C++
-.Xr curses 3
-library.
 .It Pa /usr/lib/libcurses.a
-.Xr curses 3
-library.
 .It Pa /usr/lib/libdes.a
 .It Pa /usr/lib/libedit.a
 .It Pa /usr/lib/libevent.a
@@ -136,85 +597,34 @@ library.
 .It Pa /usr/lib/libfrtbegin.a
 .It Pa /usr/lib/libg2c.a
 .It Pa /usr/lib/libgssapi.a
+.It Pa /usr/lib/libhdb.a
 .It Pa /usr/lib/libiberty.a
 .It Pa /usr/lib/libkadm5clnt.a
 .It Pa /usr/lib/libkadm5srv.a
+.It Pa /usr/lib/libkafs.a
 .It Pa /usr/lib/libkeynote.a
-.El
-.Bl -tag -width 6n -compact
 .It Pa /usr/lib/libkrb5.a
-.Bl -tag -width Ds -compact
-.It Pa /usr/lib/libasn1.a
-.It Pa /usr/lib/libcom_err.a
-.It Pa /usr/lib/libhdb.a
-.It Pa /usr/lib/libkafs.a
-.El
-.El
-.Bl -tag -width /usr/lib/libotermcap.a -compact
 .It Pa /usr/lib/libkvm.a
-.Xr kvm 3
-kernel virtual memory access library.
 .It Pa /usr/lib/libl.a
 .It Pa /usr/lib/libm.a
-.Xr math 3
-library.
 .It Pa /usr/lib/libmenu.a
 .It Pa /usr/lib/libmmalloc.a
 .It Pa /usr/lib/libncurses.a
 .It Pa /usr/lib/libobjc.a
 .It Pa /usr/lib/libocurses.a
-The
-.Xr ocurses 3
-library is compatible with the
-.Em curses
-library provided in 4.3.
 .It Pa /usr/lib/libopcodes.a
 .It Pa /usr/lib/libossaudio.a
 .It Pa /usr/lib/libotermcap.a
-4.3-compatible termcap library.
-For use with
-.Xo
-.Xr ocurses 3
-.Pf ( i.e., Fl l Ns Ar ocurses
-.Fl l Ns Ar otermcap ) .
-.Xc
 .It Pa /usr/lib/libpanel.a
-.Xr panel 3
-library for use with
-.Xo
-.Xr curses 3
-.Pf ( i.e., Fl l Ns Ar panel
-.Fl l Ns Ar curses ) .
-.Xc
 .It Pa /usr/lib/libpcap.a
-.Xr pcap 3
-library.
 .It Pa /usr/lib/libperl.a
 .It Pa /usr/lib/libpthread.a
-.St -p1003.1-01
-threads library (see
-.Xr pthreads 3 ) .
 .It Pa /usr/lib/libreadline.a
 .It Pa /usr/lib/libresolv.a
-The
-.Xr resolver 3
-routines are included in
-.Em libc .
-For legacy applications, this library contains only those functions.
 .It Pa /usr/lib/librpcsvc.a
-Generated by
-.Xr rpcgen 1 ,
-containing stub functions for many common
-.Xr rpc 3
-protocols.
 .It Pa /usr/lib/libsectok.a
 .It Pa /usr/lib/libskey.a
-Support library for the
-.Xr skey 1
-authentication toolkit.
 .It Pa /usr/lib/libssl.a
-.Xr ssl 8
-support library.
 .It Pa /usr/lib/libstdc++.a
 .It Pa /usr/lib/libtermcap.a
 .It Pa /usr/lib/libtermlib.a
@@ -224,23 +634,51 @@ support library.
 .It Pa /usr/lib/liby.a
 .It Pa /usr/lib/libz.a
 .Pp
+.It Pa /usr/lib/libalpha.a
 .It Pa /usr/lib/libi386.a
 .El
-.\" Must talk about shared libraries, _p profiled libraries, and how to tell the
-.\" C compiler to use them, and any other issues.
 .Sh SEE ALSO
+.Xr ar 1 ,
+.Xr c++ 1 ,
 .Xr cc 1 ,
+.Xr g77 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 crypto 3 ,
+.Xr curses 3 ,
+.Xr des_crypt 3 ,
+.Xr editline 3 ,
+.Xr event 3 ,
+.Xr form 3 ,
+.Xr hosts_access 3 ,
+.Xr keynote 3 ,
+.Xr kvm 3 ,
 .Xr math 3 ,
+.Xr menu 3 ,
+.Xr ocurses 3 ,
+.Xr ossaudio 3 ,
+.Xr panel 3 ,
+.Xr pcap 3 ,
 .Xr pthreads 3 ,
-.Xr stdio 3
-.\" .Sh LIST OF FUNCTIONS
-.\" .Bl -column "strncasecmpxxx" "system"
-.\" .Sy Name	Description
-.\" .El
+.Xr readline 3 ,
+.Xr resolver 3 ,
+.Xr rfc1413 3 ,
+.Xr rpc 3 ,
+.Xr sectok 3 ,
+.Xr skey 3 ,
+.Xr ssl 3 ,
+.Xr stdio 3 ,
+.Xr termcap 3 ,
+.Xr usbhid 3 ,
+.Xr keynote 4 ,
+.Xr mk.conf 5
 .Sh HISTORY
 An
 .Nm