This section describes functions found
in various libraries, other than those functions
that directly invoke
UNIX
system primitives,
which are described in Section 2 manual pages.
Function declarations can be obtained from the
#include files indicated on each page.
Certain major collections of functions are identified by a
letter after the section number;
however, all Section 3 manual pages are sorted together alphabetically,
without regard to this letter.
Some libraries are available in both a shared object version
and an archive version.
By default,
C programs will be linked with the shared object version of
the standard C library (functions in Sections 2, 3C, and 3S).
Other libraries can be searched by using the -l option
on your cc command line.
If a shared object version of the specified library exists,
it will be searched.
To force your executable to be linked with the archive version of all
libraries being searched, specify the -dn option on the cc
command line.
(See
cc(1)
for other overrides.
Also see
Programming in standard C and C++ in Programming in standard C and C++.)
(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, libc.so,
is searched at compile time by default.
Specify -dn on the cc command line to link with
the archive version of this library, libc.a, and the archive version
of all other libraries being searched.
(3curses)
This is the standard character user interface library, libcurses.a,
which complies with the Single UNIX® Specification, Version 2
standard.
It provides an API for character-based, terminal-independent screen
management.
See
Intro(3curses).
(3ocurses)
This is the traditional UNIX® System V Release 4 curses library, which
was the standard curses library in releases prior to UnixWare 7.0.1.
It has been moved from libcurses.a to libocurses.a.
These functions provide character user interface capabilities in five
libraries, all provided in archive versions.
They are not linked automatically by the C compilation system.
Specify -locurses on the cc command line to link with
all these functions.
In addition, to link with the forms, menus, panels, and tam functions, specify
-lform,
-lmenu,
-lpanel,
or
-ltam,
respectively.
Note that these libraries work only with the 3ocurses routines, and
not with the 3curses routines.
(See
curses(3ocurses),
forms(3ocurses),
menus(3ocurses),
panels(3ocurses),
and
tam(3ocurses)).
For a discussion of each of these capabilities, see
Character user interface programming in Character user interface programming.
(3S)
These functions constitute the
``standard
I/O
package''
(see
Intro(3S)),
and are part of the standard C library, as described above.
(3elf)
These functions constitute the Executable and Linking Format (ELF)
access library, libelf (see
Intro(3elf)).
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.
(3event)
These functions make up the event library libevent.
This library is not implemented as a shared object
and is not automatically linked by the C compilation system.
Specify -levent 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.
(3I)
These functions constitute the Identification and Authentication Facility
library, libiaf.
This library is implemented as a shared object, libiaf.so,
and an archive, libiaf.a.
It is not automatically linked by the C compilation system.
Specify -liaf on the cc command line
to link with the shared object version of the library.
Specify -dn -liaf on the cc command line to link with
the archive version of this library and the archive version
of all other libraries being searched.
(3M)
These functions constitute the math library, libm (see
math(5)).
This library is implemented as a shared object, libm.so,
and an archive, libm.a.
It is not automatically linked by the C compilation system.
Specify -lm on the cc command line to
link with the shared object version of the library.
Specify -dn -lm on the cc command line
to link with the archive version of this library and the
archive version of all other libraries being searched.
libm contains the full set of double-precision routines,
single-precision routines (designated by the suffix f)
that give better performance with less precision and long
double-precision routines (designated by the suffix l)
that give better precision than the single or double-precision
versions.
(3N)
The networking 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
UnixWare
Transport Interface.
These functions support both the older
TLI
semantics and the newer semantics of the
X/OPEN
Transport Interface (XTI).
The library entry points have their traditional names for the
TLI
functions, such as t_open.
For the
XTI
functions, however, the entry points have new names,
such as _xti_open.
When applications are compiled on
UnixWare
2.0, the
XTI
function names are translated to the
XTI
entry points by macros in the include file <xti.h>.
rexec
REXEC library interface
rpc
User-level Remote Procedure Call library
yp
Network Information Service functions
The libsocket library has two components: inet, containing
the Internet library routines, and socket, containing the Socket
Interface routines.
The libresolv library contains the resolver routines.
The standard networking libraries are implemented as shared objects
(libnsl.so, libresolv.so, and libsocket.so).
They are not automatically linked by the C compilation system.
To link with these libraries, specify the cc command line
cc [options] file [[-lresolv] -lsocket] -lnsl [-lthread]
The specified order of libraries on the cc line must be used to
insure correct linking and initialization of the libraries.
(3wide)
The functions in libw provide additional support for both
multibyte and 32-bit wide characters beyond those functions in (3C).
Some are provided only for compatibility.
For a discussion, see
``Internationalization'' in Programming with system calls and libraries.
This library is not implemented as a shared object
and is not automatically linked by the C compilation system.
Specify -lw on the cc command line to link with this library.
(3X)
Specialized libraries.
The files in which these libraries are found
are given on each Section 3X manual page.
(3bsd)
These functions are provided in the BSD Compatibility Package in three libraries:
libucb (for most (3) manual pages], libdbm (see
dbm(3bsd)),
and libmp (see
mp(3bsd)).
These libraries are not implemented as shared objects.
When C programs are compiled by invoking /usr/ucb/cc,
libucb is automatically linked by the C compilation system.
Even when /usr/ucb/cc is invoked,
libdbm and libmp are not automatically linked,
so specify -ldbm or -lmp on the /usr/ucb/cc command line
to link with these libraries.
Files
INCDIR
usually /usr/include
LIBDIR
usually /usr/ccs/lib
LIBDIR/libc.so
Compile-time Standard C Library
LIBDIR/libc.a
Compile-time Standard C Library (archive)
/usr/lib/libc.so.1
Run-time Standard C Library
LIBDIR/libcurses.a
ETI/curses Curses Library (archive)
LIBDIR/libelf.a
Executable and Linking Format Library (archive)
LIBDIR/libform.a
Form Library (archive)
LIBDIR/libgen.a
General-Purpose Library (archive)
/usr/lib/libiaf.so
Identification and Authentication Library
(shared object)
/usr/lib/libiaf.a
Identification and Authentication Library (archive)
/usr/lib/libm.so
Mathematical Library (shared object)
LIBDIR/libm.a
Mathematical Library (archive)
LIBDIR/libmenu.a
Menu Library (archive)
/usr/lib/libnsl.so
Network Services Library (shared object)
LIBDIR/libpanel.a
Panel Library (archive)
/usr/lib/libresolv.so
Internet Domain Name Server Library (shared object)
/usr/lib/libsocket.so
Sockets Interface Library (shared object)
LIBDIR/libtam.a
Tam Library (archive)
/usr/lib/libw.a
Multibyte/Wide Character Conversion Library (archive)
Return values
For functions that return a floating-point value, if an error occurs,
the value of errno will be one of the values represented by the manifest
constants EDOM or ERANGE (defined in math.h).
EDOM typically indicates a domain error: one of the input values
was not in the domain of the function.
ERANGE typically indicates a range error: the calculated result
was either too big or too small to be represented by the data type
returned by the function.
Functions that result in a range error typically return zero for underflow
or a value that will compare equal to ±HUGE_VAL for overflow.
HUGE_VAL is defined in math.h.
On systems that support IEEE infinity, HUGE_VAL is infinity.
If the system supports IEEE NaN (not-a-number), functions that
result in a domain error typically return NaN.
Such functions may also raise one of the IEEE floating-point exceptions.
On systems that do not support IEEE NaN, functions
that result in a domain error typically return zero.
The error behavior for programs compiled with the -Xt (transitional)
compilation mode is different (see
cc(1)).
In that case, these functions typically return zero instead
of IEEE NaN for domain errors and a value that will compare
equal to ±HUGE instead of ±HUGE_VAL for overflows.
HUGE is defined in math.h.
Definitions
A character (except a multibyte character; see
mbchar(3C))
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
XTI functions to send and receive data and information.
netbuf is defined in sys/xti.h as follows:
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 to provide information to an XTI function, the
caller must set the value of len.
maxlen generally has significance only when buf is used to
receive output from the XTI function.
In this case, the caller uses maxlen to specify the maximum
value of len that can be set by the function.
If maxlen is not large enough to hold the returned information,
a TBUFOVFLW error will generally result.
However, certain functions may return part of the data and not
generate an error.
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 an object of 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}.
Applications should restrict their use of the standard
I/O
package (see
Intro(3S))
to the
interfaces documented on the Section 3S manual pages.
They should not depend on individual members of the internal structures found in
stdio.h.