intro(3) UNIX System V 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 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, and the ``C Compilation System'' chapter of the
Programmer's Guide: ANSI C and Programming Support Tools for a
discussion.]
(3S) These functions constitute the ``standard I/O package'' [see
stdio(3S)].
(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. [See intro(3M)
and 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.
(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
10/89 Page 1
intro(3) UNIX System V intro(3)
an error. The macro NULL is defined in stdio.h. Types of the form
sizet are defined in the appropriate header files.
FILES
INCDIR usually /usr/include
LIBDIR usually /usr/ccs/lib
LIBDIR/libc.so
LIBDIR/libc.a
LIBDIR/libgen.a
LIBDIR/libm.a
LIBDIR/libsfm.sa
/usr/lib/libc.so.1
SEE ALSO
ar(1), cc(1), ld(1), lint(1), nm(1), intro(2), intro(3M), stdio(3S),
math(5).
The ``C Compilation System'' chapter in the Programmer's Guide: ANSI C
and Programming Support Tools.
DIAGNOSTICS
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, +HUGEVAL is
returned instead of +HUGE. (HUGEVAL and HUGE are defined in math.h to
be infinity and the largest-magnitude single-precision number,
respectively.)
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
Page 2 10/89
intro(3) UNIX System V intro(3)
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}.
10/89 Page 3