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 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 Guide 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.
Some of the AT&T 3B2 SVR4 documentation set guides include duplicates
of relevant manpages. In this documentation set, all manpages may be
found in the appropriate Reference Manual and, with the exception of
the Programmer's Guide: XWIN Graphical Windowing System the
Programmer's Guide: OPEN LOOK Graphical User Interface, are and the
OPEN LOOK Graphical User Interface User's Guide, are never duplicated
in the guides.
7/91 Page 1
intro(3) intro(3)
The Reference Manual pages are divided as follows: User's Reference
Manual: Section 1 and all subsections (except 1M). System
Administrator's Reference Manual: Sections 1M, 7 and 8. Programmer's
Reference Manual: Section 2 through 6.
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.
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
intro(2), intro(3M), stdio(3S), math(5).
ar(1), cc(1), ld(1), lint(1), nm(1) in the User's Reference Manual.
The ``C Compilation System'' chapter in the ANSI C and Programming
Support Tools Guide.
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, +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.)
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.
Page 2 7/91
intro(3) intro(3)
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}.
7/91 Page 3