INTRO(3-SVR4) RISC/os Reference Manual INTRO(3-SVR4)
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.]
(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 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).] This library is not
implemented as a shared object, and is not automati-
cally 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
Printed 11/19/92 Page 1
INTRO(3-SVR4) RISC/os Reference Manual INTRO(3-SVR4)
characters, the last of which is the null character. The
null string is a character array containing only the ter-
minating 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
ar(1), cc(1), ld(1), lint(1), nm(1), intro(2), intro(3M),
stdio(3S), math(5).
DIAGNOSTICS
For functions that return floating-point values, error han-
dling varies 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,
+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.
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 pro-
totypes 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 state-
ments. 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 defini-
tions for libm.) Use of lint is highly recommended.
Page 2 Printed 11/19/92
INTRO(3-SVR4) RISC/os Reference Manual INTRO(3-SVR4)
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 distinguish them
from symbolic names of other implementation-specific con-
stants 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 appli-
cation 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}.
Printed 11/19/92 Page 3