NAME

intro − introduction to functions and libraries

DESCRIPTION

This section describes functions found in various libraries, other than those ­functions that directly invoke UNIX system primitives, which are described in Section 2 of this volume.  Function declarations can be obtained from the ­#include files indicated on each page.  Certain major collections are identified by a letter after the section number:

(3C) These functions, together with those of Section 2 and those marked (3S), constitute the standard C library, libc, which is automatically linked by the C compilation system.  The standard C library is implemented as a shared object, libc.so, and an archive, libc.a.  C programs are linked with the shared object version of the standard C library by default.  Specify −dn on the cc command line to link with the archive version.  See cc(1) for other overrides. 

(3E) These functions constitute the ELF access library, libelf.  This library is not implemented as a shared object, and is not automatically linked by the C compilation system.  Specify −lelf on the cc command line to link with this library. 

(3G) These functions constitute the general-purpose library, libgen.  This library is not implemented as a shared object, and is not automatically linked by the C compilation system.  Specify −lgen on the cc command line to link with this library. 

(3M) These functions constitute the math library, libm.  Declarations for these functions may be obtained from the #include file math.h. [See math(5).]

libm is not automatically loaded by the C compilation system; use the −l option to cc to access the library. 

libm contains the full set of double-precision routines plus some single-precision routines (designated by the suffix f) that give better performance with less precision.  Selected routines are hand-optimized for performance.  The optimized routines include sin, cos, tan, atan, atan2, exp, log, log10, pow, and sqrt and their single-precision equivalents. 

This library is not implemented as a shared object, and is not automatically linked by the C compilation system.  Specify −lm on the cc command line to link with this library. 

(3N) These functions are contained in three libraries: the Network Services library, libnsl; the Sockets Interface library, libsocket; and the Internet Domain Name Server library, libresolv. 

The following functions constitute the libnsl library:

cr1 cr1 authentication library

cs Connection Server library interface

des Data Encryption Standards library

netdir Network Directory functions.  This contains look-up functions and the access point to network directory libraries for various network transports. 

netselect
Network Selection routines. These functions manipulate the /etc/netconfig file and return entries. 

nsl Transport Library Interface (TLI).  These functions contain the implementation of X/OPEN’s Transport Level Interface. 

rexec REXEC library interface

rpc User-level Remote Procedure Call library

saf Service Access Facility library

yp Network Information Service functions

The libsocket library has two components: inet, containing the Inernet library routines, and socket, containing the Socket Interface routines.  The libresolv library contains the resolver routines. 

The standard networking libraries are implemented as a shared object (libnsl.so and libsocket.so) or archive file (libresolv.a).  To link with these libraries, specify the cc command line with -lnsl, -lsocket, or -lresolv, respectively. 

(3S) These functions constitute the “standard I/O package” [see stdio(3S)]. 

(3X) Specialized libraries.  The files in which these libraries are found are given on the appropriate pages. 

DEFINITIONS

A character is any bit pattern able to fit into a byte on the machine.  The null character is a character with value 0, conventionally represented in the C language as \0.  A character array is a sequence of characters.  A null-terminated character array (a string) is a sequence of characters, the last of which is the null character.  The null string is a character array containing only the terminating null character.  A NULL pointer is the value that is obtained by casting 0 into a pointer.  C guarantees that this value will not match that of any legitimate pointer, so many functions that return pointers return NULL to indicate an error.  The macro NULL is defined in stdio.h.  Types of the form size_t are defined in the appropriate header files. 

In the Network Services library, netbuf is a structure used in various TLI functions to send and receive data and information.  netbuf is defined in sys/tiuser.h, and includes the following members:

struct netbuf {
unsigned int maxlen;  /∗ The physical size of the buffer ∗/
unsigned int len; /∗ The number of bytes in the buffer ∗/
char ∗buf;  /∗ Points to user input and/or output buffer ∗/
};

If netbuf is used for output, the function will set the user value of len on return.  maxlen generally has significance only when buf is used to receive output from the TLI function.  In this case, it specifies the maximum value of len that can be set by the function.  If maxlen is not large enough to hold the returned information, an TBUFOVFLW error will generally result.  However, certain functions may return part of the data and not generate an error. 

FILES

INCDIRusually /usr/include
LIBDIRusually /usr/ccs/lib
LIBDIR/libc.so
LIBDIR/libc.a
LIBDIR/libgen.a
LIBDIR/libm.a
LIBDIR/libnsl.so
LIBDIR/libresolv.a
LIBDIR/libsfm.sa
LIBDIR/libsocket.so
/usr/lib/libc.so.1

SEE ALSO

ar(1), cc(1), ld(1), lint(1), nm(1), intro(2), stdio(3S), math(5),

DIAGNOSTICS

Math Library (libm) Only

For functions that return floating-point values, error handling varies according to compilation mode.  Under the −Xt (default) option to cc, these functions return the conventional values 0, ±HUGE, or NaN when the function is undefined for the given arguments or when the value is not representable.  In the −Xa and −Xc compilation modes, ±HUGE_VAL is returned instead of ±HUGE.  (HUGE_VAL and HUGE are defined in math.h to be infinity and the largest-magnitude single-precision number, respectively.)  In every case, the external variable errno [see intro(2)] is set to the value EDOM or ERANGE, although the value may vary for a given error depending on compilation mode. 

NOTES

None of the functions, external variables, or macros should be redefined in the user’s programs.  Any other name may be redefined without affecting the behavior of other library functions, but such redefinition may conflict with a declaration in an included header file. 

The header files in INCDIR provide function prototypes (function declarations including the types of arguments) for most of the functions listed in this manual.  Function prototypes allow the compiler to check for correct usage of these functions in the user’s program.  The lint program checker may also be used and will report discrepancies even if the header files are not included with #include statements.  Definitions for Sections 2, 3C, and 3S are checked automatically.  Other definitions can be included by using the −l option to lint.  (For example, −lm includes definitions for libm.)  Use of lint is highly recommended. 

Users should carefully note the difference between STREAMS and stream.  STREAMS is a set of kernel mechanisms that support the development of network services and data communication drivers.  It is composed of utility routines, kernel facilities, and a set of data structures.  A stream is a file with its associated buffering.  It is declared to be a pointer to a type FILE defined in stdio.h.  In detailed definitions of components, it is sometimes necessary to refer to symbolic names that are implementation-specific, but which are not necessarily expected to be accessible to an application program. Many of these symbolic names describe boundary conditions and system limits.

In this section, for readability, these implementation-specific values are given symbolic names.  These names always appear enclosed in curly brackets to distinguish them from symbolic names of other implementation-specific constants that are accessible to application programs by header files.  These names are not necessarily accessible to an application program through a header file, although they may be defined in the documentation for a particular system. 

In general, a portable application program should not refer to these symbolic names in its code.  For example, an application program would not be expected to test the length of an argument list given to a routine to determine if it was greater than {ARG_MAX}.