intro(3) LIBRARY FUNCTIONS 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 compila-
tion 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 Compila-
tion System'' chapter of the Programmer's Guide: ANSI
C and Programming Support Tools for a discussion.]
(3S) These functions constitute the ``standard I/O pack-
age'' [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 com-
pilation 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).] These libraries are not
implemented as shared objects, and are not automati-
cally linked by the C compilation system. Use the -l
option on the cc command line to access the libm
library as follows:
-lm Search the regular math library, libm.
(3X) Specialized libraries. The files in which these
libraries are found are given on the appropriate
pages.
1
intro(3) LIBRARY FUNCTIONS intro(3)
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 char-
acters, 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 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
Error handling varies, for functions that return floating-
point values, according to compilation mode. Under the -Xt
(default) option to cc, these functions return the conven-
tional values 0, +HUGE, or NaN when the function is unde-
fined 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 com-
piler to check for correct usage of these functions in the
2
intro(3) LIBRARY FUNCTIONS intro(3)
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 Sec-
tions 2, 3C, and 3S are checked automatically. Other defin-
itions 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 sup-
port the development of network services and data communica-
tion 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 dis-
tinguish them from symbolic names of other implementation-
specific constants that are accessible to application pro-
grams 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 par-
ticular 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}.
3