intro(3) intro(3)
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 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++.]
(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) 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 -lcurses 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. [See
curses(3curses), forms(3curses), menus(3curses),
panels(3curses), and tam(3curses)]. For a
discussion of each of these capabilities, see
Character User Interface Programming.
Copyright 1994 Novell, Inc. Page 1
intro(3) intro(3)
(3S) These functions constitute the ``standard I/O
package'' [see stdio(3S)], and are part of the
standard C library, as described above.
(3E) These functions constitute the Executable and
Linking Format (ELF) access library, libelf [see
elf(3E)]. 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.
(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 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.
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.
(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.
Copyright 1994 Novell, Inc. Page 2
intro(3) intro(3)
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.
Copyright 1994 Novell, Inc. Page 3
intro(3) intro(3)
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.
(3W) 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 the chapter
``Internationalization'' of the book 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
Copyright 1994 Novell, Inc. Page 4
intro(3) intro(3)
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)
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
Copyright 1994 Novell, Inc. Page 5
intro(3) intro(3)
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.
REFERENCES
ar(1), cc(1), curses(3curses), dbm(3BSD), elf(3E),
forms(3curses), intro(2), ld(1), lint(1), math(5), mbchar(3C),
menus(3curses), mp(3BSD), nm(1), panels(3curses), stdio(3S),
tam(3curses)
Programming in Standard C and C++
Programming with System Calls and Libraries
Copyright 1994 Novell, Inc. Page 6
intro(3) intro(3)
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 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
Copyright 1994 Novell, Inc. Page 7
intro(3) intro(3)
greater than {ARG_MAX}.
Applications should restrict their use of the standard I/O
package [see stdio(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.
Copyright 1994 Novell, Inc. Page 8