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 explicitly 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 -D_BSD_SIGNALS on the compile line specifically selects the Berkeley signal routines and -D_BSD_TIME selects the Berkeley time-of-day routines. Both are a subset of the compatibility specified by -D_BSD_COMPAT. 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). 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 _SGI_MP_SOURCE and _SGI_REENTRANT_FUNCTIONS. _SGI_MP_SOURCE 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, _POSIX_C_SOURCE 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. _SGI_REENTRANT_FUNCTIONS 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. (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 -D_BSD_COMPAT or -D_BSD_SIGNALS 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 -D_BSD_COMPAT or -D_BSD_TIME 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 _BSD_COMPAT gives the following additional BSD compatibility features over and above that given by _BSD_SIGNALSand _BSD_TIME: 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). _BSD_COMPAT 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). 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 size_t 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} Miscellaneous 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 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