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 IRIX 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.
In general, routines in these libraries are not MP or MT (multi-threaded)
safe, and therefore must be explictly protected by one of the
synchronization primitives in the users code. Exceptions are noted in
the man pages. See section 3P below.
(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.1.
(3G) These functions constitute the IRIS Graphics Library which are
documented in the Graphics Library User's Guide. The -lgl and -lm
flags should be specified to access the graphics library.
Declarations for these functions may be obtained from the include
file <gl.h>. <device.h> and <get.h> define other constants used by
the Graphics Library.
(3M) These functions constitute the Math Library, libm. Use the -lm
option to cc(1) or ld(1) to have the link editor search this
library. Declarations for these functions may be obtained from the
include file <math.h>.
(3S) These functions constitute the ``standard I/O package'' (see
stdio(3S)). These functions are in the standard C library libc,
already mentioned. Declarations for these functions may be
obtained from the include file <stdio.h>.
(3G) These functions constitute the general-purpose library, libgen.
This library is implemented as a shared object and an archive, and
is not automatically linked by the C compilation system. Specify
-lgen on the cc command line to link with this library.
Declarations for these functions may be obtained from the include
file <libgen.h>.
(3B) IRIX supports many 4.3BSD system calls and library routines. To
get the maximum Berkeley compatibility, use the following compile
line:
cc -D_BSD_COMPAT -o prog prog.c -lbsd
-DBSDSIGNALS on the compile line specifically selects the
Berkeley signal routines and -DBSDTIME selects the Berkeley
Page 1
intro(3) intro(3)
time-of-day routines. Both are a subset of the compatibility
specified by -DBSDCOMPAT.
The following 4.3BSD standard C Library routines in libbsd have
different arguments or conflicting semantics with the routines in
IRIX libc having the same names: dup2, getgroups, getpgrp,
setgroups, setpgrp. To compile and link a program that calls the
BSD version of any of these routines, use a command of the form:
cc prog.c -lbsd
See the "BSD Compatibility" section below for more details.
(3N) There are actually 3 types of networking in IRIX.
1) BSD sockets implemented in the kernel, along with SUN RPC and
NIS (YP). The functions that implement these calls are in libc
[see (3C) section above].
2) SVR4-style STREAMS/TLI networking (not sockets), along with
SVR4-style RPC. SVR4-style RPC doesn't work with sockets, only
with the TLI. Also, SVR4-style networking does not support NIS
[see intro(3N)]. The functions that implement these calls are in
libnsl, and to use them, the code must be compiled with :
cc -D_SVR4_TIRPC prog.c -lnsl
3) SVR4 emulation of sockets. This is an implementation of
sockets entirely in a library (libsocket) that sits on top of
libnsl. There are no header file differences for libsocket. The
MIPS ABI-compliant programs that use sockets must (in order to be
ABI-compliant) link with libsocket. There is no NIS support for
programs linked with libsocket [see intro(3N)]. To compile such a
program, use:
cc prog.c -lsocket
(3Y) Remote Procedure Call (RPC) and NIS support routines. These
functions are in the standard C library libc, already mentioned.
(3R) Remote Procedure Call services built on top of the Sun RPC protocol.
To compile and link a program that calls any of these routines, use
a command of the form:
cc prog.c -lrpcsvc
(3P) These functions constitute the parallel processing interfaces. They
comprise standard C library thread safe functions and POSIX threads
interfaces. IRIX supports two threading models: sproc(2), process
level threads (IRIX, proprietary) and pthreads(3P) (POSIX threads).
Page 2
intro(3) intro(3)
The models are quite different and cannot interact in the same
program; an sproc program cannot create pthreads and vice-versa.
Thread safe interfaces may be accessed by multiple threads or
processes simultaneously and are guaranteed to behave correctly.
In the sproc model no locking or single threading is done until the
program makes the first call to sproc(). The usconfig(3P) interface
can be used to alter the thread safe behavior of these routines.
Sproc programs wishing to do parallel processing should define the
feature test macros SGIMPSOURCE and SGIREENTRANTFUNCTIONS.
SGIMPSOURCE changes the errno variable from a global to a per
thread private variable. It also makes certain macros and function
prototypes visible.
Pthread programs should enable the thread safe options including
reentrant functions and per thread errno by setting the POSIX
feature test macro, POSIXCSOURCE to the value 199506L or greater;
the file <pthread.h> enables these options automatically.
The following calls have been single threaded so that multiple
shared processes accessing them simultaneously will function
correctly: getc, putc, fgetc, fputc, ungetc, getw, putw, gets,
fgets, puts, fputs, fopen, fdopen, freopen, ftell, rewind, feof,
clearerr, ferror, setbuf, setlinebuf, setbuffer, setvbuf, fclose,
fflush, fread, fwrite, fseek, fgetpos, fsetpos, flockfile,
funlockfile, tempnam, tmpnam, tmpfile, mktemp, mkstemp, popen,
pclose, atexit, printf, fprintf, vprintf, vfprintf, scanf, fscanf,
opendir, readdir, scandir, seekdir, closedir, telldir, dup2, srand,
rand, addsev, addseverity, fmtmsg, setcat, gettxt, lfmt, localeconv,
nl_langinfo, pfmt, setlabel, setlocale, strftime, strxfrm, strcoll,
vlfmt, vpfmt malloc, free, calloc, realloc, mallopt, memalign
acreate, amalloc, afree, acalloc, arealloc, amallopt.
SGIREENTRANTFUNCTIONS enables prototypes and definitions for
reentrant versions of functions that are not thread safe by
definition (usually due to returning pointers to static data).
These alternatives are named func_r and are described on the same
manual page as the original, unsafe version.
Functions that return pointers to static data are not reentrant.
When there is no alternative interface threads must provide their
own synchronization. The following functions have non-obvious
side-effects with respect to reentrancy. setlocale modifies many
tables and static data. In particular, any strings returned by
strerror and gettxt will no longer be valid. setlocale also can
affect other tables such as character class, collating sequence and
numeric separator, which many routines access. To be safe, no
thread should be using any standard C library service when a change
to the locale must be made.
Page 3
intro(3) intro(3)
(3T) These primitives implement a general terminal interface that
provides control over asynchronous communications ports. These are
all in the standard C library.
(3W) These functions constitute the wide-character library libw. The
functions are used to convert between multibyte and 32-bit wide
characters, respectively. This library is implemented as a shared
object and an archive and is not automatically linked by the C
compilation system. Specify -lw on the cc command line to link with
this library. Declarations for these functions may be obtained from
the include file <widec.h>.
(3X) Various specialized libraries. The files in which these libraries
are found are given on the appropriate pages.
BSD COMPATIBILITY
As described in the discussion of Section 3B above,
cc -D_BSD_COMPAT -o prog prog.c -lbsd
selects maximum compatibility with BSD. The -lbsd directive specifies
that libbsd.a be searched before libc.a, which selects the BSD versions
of functions that reside in both libraries (duplicated because of
identical names yet differing semantics or arguments). The routines that
fall into this category are listed in the (3B) section above. The BSD
versions may also be selected on a case-by-case basis by prefixing the
function name with BSD when calling it in the program (e.g. BSDsetpgrp).
Specifying -DBSDCOMPAT or -DBSDSIGNALS on the compile line links with
the BSD versions of the signal routines (kill, killpg, sigblock, signal,
sigpause, sigsetmask, and sigvec). The program must include <signal.h>
or <sys/signal.h>. Note that a "#define _BSD_COMPAT" or "#define
_BSD_SIGNALS" placed in the source program before the inclusion of the
signal header file has the same effect as specifying the corresponding -D
compile option.
Specifying -DBSDCOMPAT or -DBSDTIME on the compile line links with
the BSD versions of the gettimeofday and gettimeofday routines. The
program must include <sys/time.h>. The "#define _BSD_COMPAT" or "#define
_BSD_TIME" must be placed in the source program before the inclusion the
time header file if the -D compile option is not specified.
Defining BSDCOMPAT gives the following additional BSD compatibility
features over and above that given by BSDSIGNALSand BSDTIME: you get
the BSD version of setjmp(3) and including <sys/types.h> will cause
several additional macros and typedefs to be defined (e.g. major, minor,
makedev for dealing with device numbers). BSDCOMPAT may affect more
things in future releases.
The System V and BSD versions of the directory routines (opendir,
seekdir, etc.) differ greatly; inclusion of <dirent.h> at the top of the
your program selects the System V routines, <sys/dir.h> selects the BSD
set. See also directory(3C) and directory_bsd(3B).
Page 4
intro(3) intro(3)
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. A string is a designation for a null-terminated
character array. 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/lib
LIBDIR/libbsd.a BSD Compatibility library
LIBDIR/libm.a Math library
LIBDIR/libnsl.so Network Services library
LIBDIR/libgen.{so,a} Misc routines
LIBDIR/libgl.so GL library
LIBDIR/librpcsvc.{so,a} RPC services library
LIBDIR/libsocket.so Sockets Interface library
LIBDIR/libpthread.so POSIX thread library
LIBDIR/libw.{so,a} Wide character library
/usr/lib/libc.so.1 Runtime Linker/Standard C library
SEE ALSO
ar(1), cc(1), ld(1), nm(1), intro(2), usinit(3P), pthread(3P),
flockfile(3S), stdio(3S)
Graphics Library User's Guide
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
Page 5
intro(3) intro(3)
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}.
Page 6