intro(3) intro(3)NAME intro - introduction to subroutines and libraries SYNOPSIS #include <stdio.h> FILE *stdin, *stdout, *stderr #include <math.h> DESCRIPTION This section describes functions found in various libraries, other than those functions that directly invoke system prim- itives (described in Section 2 of this volume). Major col- lections 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 loaded by the C compiler cc(1). The link editor ld(1) searches this library under the -lc flag option. Some functions require de- clarations that can be included in the program being compiled by adding the line #include <header-filename> The appropriate header file is indicated in the synopsis of a function description. (3F) These functions constitute the Fortran intrinsic func- tion library libF77 and are automatically available to the Fortran programmer. They require no special invo- cation of the compiler. These functions are flagged with the (3F) suffix on the associated manual page en- tries and appear in their own alphabetically organized subsection at the end of this section. (3M) These functions constitute the Math Library libm. They are automatically loaded as needed by the Fortran com- piler f77(1). They are not automatically loaded by the C compiler cc(1); however, the link editor searches this library under the -lm flag option. Declarations for these functions may be obtained from the header file <math.h>. (3N) These functions are networking routines and, unless otherwise noted, are found in the Standard C Library libc.a. (3P) These functions provide POSIX functionality and are found in libposix.a. The POSIX environment is April, 1990 1
intro(3) intro(3)described in the A/UX Guide to POSIX and A/UX Program- ming Languages and Tools, Volume 1. (3X) These functions pertain to various specialized li- braries. The files in which these libraries are found are given on the appropriate pages. (3S) These functions constitute the standard I/0 package. An introduction to this package follows under the head- ing ``STANDARD I/O.'' The functions are in the Stan- dard C Library libc. Declarations should be obtained from the include file <stdio.h>. 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, represented in the C language as \0. A character array is a sequence of characters. A null-terminated character array 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 null character. A null pointer is the value that is obtained by casting 0 into a pointer. The C language guarantees that this value will not match that of any legitimate pointer, so many functions that return pointers return it to indicate an error. NULL is defined as 0 in <stdio.h>; the user can include an original definition if <stdio.h> is not being used. Many groups of Fortran intrinsic functions have ``generic'' function names that do not require explicit or implicit type declarations. The type of the function is determined by the type of its argument(s). For example, the generic function max returns an integer value if given integer arguments (max0), a real value if given real arguments (amax1), or a double-precision value if given double-precision arguments (dmax1). STANDARD I/O The functions described in the entries of subclass (3S) in this manual provide an efficient, user-level I/O buffering scheme. The functions are in the library libc and declara- tions should be obtained from the header file <stdio.h>. The I/O function may be grouped into the following categories: file access, file status, input, output, and miscellaneous. For lists of the functions in each category, refer to the library sections of A/UX Programming Languages and Tools, Volume 1. The inline macros getc(3S) and putc(3S) handle characters quickly. The macros getchar and putchar, and the higher-level routines fgetc, fgets, fprintf, fputc, fputs, fread, fscanf, fwrite, gets, getw, 2 April, 1990
intro(3) intro(3)printf, puts, putw, and scanf all use getc and putc; these macros and routinges can be freely intermixed. A file with associated buffering is called a stream and is declared to be a pointer to a defined type FILE. fopen(3S) creates certain descriptive data for a stream and returns a pointer to designate the stream in all further transactions. Normally, there are three open streams with constant pointers declared in the <stdio.h> header file and associat- ed with the standard open files: stdin standard input file stdout standard output file stderr standard error file Note: Invalid stream pointers cause serious errors, including possible program termination. Individual function descriptions describe the possible error con- ditions. A constant NULL (0) designates a nonexistent pointer. An integer constant EOF (-1) is returned upon an end-of-file or error by most integer functions that deal with streams (see the individual descriptions for details). An integer constant BUFSIZ specifies the size of the buffers used by the particular implementation. Any program that uses this package must include the header file of pertinent macro definitions, as follows: #include <stdio.h> The functions and constants mentioned in the (3S) entries are declared in the header file <stdio.h> and need no furth- er declaration. The constants and the following functions are implemented as macros: getc, getchar, putc, putchar, feof, ferror, clearerr, and fileno. Redeclaration of these names is perilous. For descriptions and examples of header files, refer to ``The Standard C Library (libc),'' ``The C Math Library,'' and ``The C Object Library,'' in A/UX Programming Languages and Tools, Volume 1. RPC SERVICE LIBRARY These functions are part of the Remote Process Control (RPC) service library librpcsvc. To have the link editor load this library, use the -lrpcsvc option of cc. Declarations for these functions may be obtained from various include files within <rpcsvc/*.h>. April, 1990 3
intro(3) intro(3)RETURN VALUE Functions in the C and Math Libraries (3C and 3M) may return the conventional values 0 or +-HUGE (the largest-magnitude, double-precision floating-point numbers; HUGE is defined in the <math.h> header file) when the function is undefined for the given arguments or when the value is not representable. In these cases, the external variable errno (see intro(2)) is set to the value EDOM or ERANGE. Because many of the Fortran intrinsic functions use the routines found in the Math Library, the same conventions apply. FILES /lib/libc.a /usr/lib/libF77.a /lib/libm.a SEE ALSO ar(1), cc(1), f77(1), ld(1), lint(1), nm(1), open(2), close(2), lseek(2), pipe(2), read(2), write(2), ctermid(3S), cuserid(3S), fclose(3S), ferror(3S), fopen(3S), fread(3S), fseek(3S), getc(3S), gets(3S), popen(3S), printf(3S), putc(3S), puts(3S), scanf(3S), setbuf(3S), system(3S), tmpfile(3S), tmpnam(3S), ungetc(3S), math(5). A/UX Programming Languages and Tools, Volume 1. WARNINGS Many of the functions in the libraries call or refer to oth- er functions and external variables described in this sec- tion and in Section 2 (System Calls). If a program inadver- tently defines a function or external variable with the same name, the presumed library version of the function or exter- nal variable may not be loaded. The lint(1) program checker reports name conflicts of this kind as ``multiple declara- tions'' of the names in question. Definitions for sections 2, 3C, and 3S are checked automatically. Other definitions can be included by using the -l option. (For example, -lm includes definitions for libm, the Math Library, section 3M). The use of lint is highly recommended. 4 April, 1990