diff options
Diffstat (limited to 'manual/intro.texi')
| -rw-r--r-- | manual/intro.texi | 689 |
1 files changed, 689 insertions, 0 deletions
diff --git a/manual/intro.texi b/manual/intro.texi new file mode 100644 index 0000000000..19f04a1474 --- /dev/null +++ b/manual/intro.texi @@ -0,0 +1,689 @@ +@node Introduction, Error Reporting, Top, Top +@chapter Introduction + +The C language provides no built-in facilities for performing such +common operations as input/output, memory management, string +manipulation, and the like. Instead, these facilities are defined +in a standard @dfn{library}, which you compile and link with your +programs. +@cindex library + +The GNU C library, described in this document, defines all of the +library functions that are specified by the ANSI C standard, as well as +additional features specific to POSIX and other derivatives of the Unix +operating system, and extensions specific to the GNU system. + +The purpose of this manual is to tell you how to use the facilities +of the GNU library. We have mentioned which features belong to which +standards to help you identify things that are potentially nonportable +to other systems. But the emphasis in this manual is not on strict +portability. + +@menu +* Getting Started:: What this manual is for and how to use it. +* Standards and Portability:: Standards and sources upon which the GNU + C library is based. +* Using the Library:: Some practical uses for the library. +* Roadmap to the Manual:: Overview of the remaining chapters in + this manual. +@end menu + +@node Getting Started, Standards and Portability, , Introduction +@section Getting Started + +This manual is written with the assumption that you are at least +somewhat familiar with the C programming language and basic programming +concepts. Specifically, familiarity with ANSI standard C +(@pxref{ANSI C}), rather than ``traditional'' pre-ANSI C dialects, is +assumed. + +The GNU C library includes several @dfn{header files}, each of which +provides definitions and declarations for a group of related facilities; +this information is used by the C compiler when processing your program. +For example, the header file @file{stdio.h} declares facilities for +performing input and output, and the header file @file{string.h} +declares string processing utilities. The organization of this manual +generally follows the same division as the header files. + +If you are reading this manual for the first time, you should read all +of the introductory material and skim the remaining chapters. There are +a @emph{lot} of functions in the GNU C library and it's not realistic to +expect that you will be able to remember exactly @emph{how} to use each +and every one of them. It's more important to become generally familiar +with the kinds of facilities that the library provides, so that when you +are writing your programs you can recognize @emph{when} to make use of +library functions, and @emph{where} in this manual you can find more +specific information about them. + + +@node Standards and Portability, Using the Library, Getting Started, Introduction +@section Standards and Portability +@cindex standards + +This section discusses the various standards and other sources that the +GNU C library is based upon. These sources include the ANSI C and +POSIX standards, and the System V and Berkeley Unix implementations. + +The primary focus of this manual is to tell you how to make effective +use of the GNU library facilities. But if you are concerned about +making your programs compatible with these standards, or portable to +operating systems other than GNU, this can affect how you use the +library. This section gives you an overview of these standards, so that +you will know what they are when they are mentioned in other parts of +the manual. + +@xref{Library Summary}, for an alphabetical list of the functions and +other symbols provided by the library. This list also states which +standards each function or symbol comes from. + +@menu +* ANSI C:: The American National Standard for the + C programming language. +* POSIX:: The IEEE 1003 standards for operating + systems. +* Berkeley Unix:: BSD and SunOS. +* SVID:: The System V Interface Description. +@end menu + +@node ANSI C, POSIX, , Standards and Portability +@subsection ANSI C +@cindex ANSI C + +The GNU C library is compatible with the C standard adopted by the +American National Standards Institute (ANSI): +@cite{American National Standard X3.159-1989---``ANSI C''}. +The header files and library facilities that make up the GNU library are +a superset of those specified by the ANSI C standard.@refill + +@pindex gcc +If you are concerned about strict adherence to the ANSI C standard, you +should use the @samp{-ansi} option when you compile your programs with +the GNU C compiler. This tells the compiler to define @emph{only} ANSI +standard features from the library header files, unless you explicitly +ask for additional features. @xref{Feature Test Macros}, for +information on how to do this. + +Being able to restrict the library to include only ANSI C features is +important because ANSI C puts limitations on what names can be defined +by the library implementation, and the GNU extensions don't fit these +limitations. @xref{Reserved Names}, for more information about these +restrictions. + +This manual does not attempt to give you complete details on the +differences between ANSI C and older dialects. It gives advice on how +to write programs to work portably under multiple C dialects, but does +not aim for completeness. + +@node POSIX, Berkeley Unix, ANSI C, Standards and Portability +@subsection POSIX (The Portable Operating System Interface) +@cindex POSIX +@cindex POSIX.1 +@cindex IEEE Std 1003.1 +@cindex POSIX.2 +@cindex IEEE Std 1003.2 + +The GNU library is also compatible with the IEEE @dfn{POSIX} family of +standards, known more formally as the @dfn{Portable Operating System +Interface for Computer Environments}. POSIX is derived mostly from +various versions of the Unix operating system. + +The library facilities specified by the POSIX standards are a superset +of those required by ANSI C; POSIX specifies additional features for +ANSI C functions, as well as specifying new additional functions. In +general, the additional requirements and functionality defined by the +POSIX standards are aimed at providing lower-level support for a +particular kind of operating system environment, rather than general +programming language support which can run in many diverse operating +system environments.@refill + +The GNU C library implements all of the functions specified in +@cite{IEEE Std 1003.1-1990, the POSIX System Application Program +Interface}, commonly referred to as POSIX.1. The primary extensions to +the ANSI C facilities specified by this standard include file system +interface primitives (@pxref{File System Interface}), device-specific +terminal control functions (@pxref{Low-Level Terminal Interface}), and +process control functions (@pxref{Processes}). + +Some facilities from @cite{IEEE Std 1003.2-1992, the POSIX Shell and +Utilities standard} (POSIX.2) are also implemented in the GNU library. +These include utilities for dealing with regular expressions and other +pattern matching facilities (@pxref{Pattern Matching}). + +@comment Roland sez: +@comment The GNU C library as it stands conforms to 1003.2 draft 11, which +@comment specifies: +@comment +@comment Several new macros in <limits.h>. +@comment popen, pclose +@comment <regex.h> (which is not yet fully implemented--wait on this) +@comment fnmatch +@comment getopt +@comment <glob.h> +@comment <wordexp.h> (not yet implemented) +@comment confstr + + +@node Berkeley Unix, SVID, POSIX, Standards and Portability +@subsection Berkeley Unix +@cindex BSD Unix +@cindex 4.@var{n} BSD Unix +@cindex Berkeley Unix +@cindex SunOS +@cindex Unix, Berkeley + +The GNU C library defines facilities from some versions of Unix which +are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD, +and 4.4 BSD Unix systems (also known as @dfn{Berkeley Unix}) and from +@dfn{SunOS} (a popular 4.2 BSD derivative that includes some Unix System +V functionality). These systems support most of the ANSI and POSIX +facilities, and 4.4 BSD and newer releases of SunOS in fact support them all. + +The BSD facilities include symbolic links (@pxref{Symbolic Links}), the +@code{select} function (@pxref{Waiting for I/O}), the BSD signal +functions (@pxref{BSD Signal Handling}), and sockets (@pxref{Sockets}). + +@node SVID, , Berkeley Unix, Standards and Portability +@subsection SVID (The System V Interface Description) +@cindex SVID +@cindex System V Unix +@cindex Unix, System V + +The @dfn{System V Interface Description} (SVID) is a document describing +the AT&T Unix System V operating system. It is to some extent a +superset of the POSIX standard (@pxref{POSIX}). + +The GNU C library defines some of the facilities required by the SVID +that are not also required by the ANSI or POSIX standards, for +compatibility with System V Unix and other Unix systems (such as +SunOS) which include these facilities. However, many of the more +obscure and less generally useful facilities required by the SVID are +not included. (In fact, Unix System V itself does not provide them all.) + +@c !!! mention sysv ipc/shmem when it is there. + + +@node Using the Library, Roadmap to the Manual, Standards and Portability, Introduction +@section Using the Library + +This section describes some of the practical issues involved in using +the GNU C library. + +@menu +* Header Files:: How to include the header files in your + programs. +* Macro Definitions:: Some functions in the library may really + be implemented as macros. +* Reserved Names:: The C standard reserves some names for + the library, and some for users. +* Feature Test Macros:: How to control what names are defined. +@end menu + +@node Header Files, Macro Definitions, , Using the Library +@subsection Header Files +@cindex header files + +Libraries for use by C programs really consist of two parts: @dfn{header +files} that define types and macros and declare variables and +functions; and the actual library or @dfn{archive} that contains the +definitions of the variables and functions. + +(Recall that in C, a @dfn{declaration} merely provides information that +a function or variable exists and gives its type. For a function +declaration, information about the types of its arguments might be +provided as well. The purpose of declarations is to allow the compiler +to correctly process references to the declared variables and functions. +A @dfn{definition}, on the other hand, actually allocates storage for a +variable or says what a function does.) +@cindex definition (compared to declaration) +@cindex declaration (compared to definition) + +In order to use the facilities in the GNU C library, you should be sure +that your program source files include the appropriate header files. +This is so that the compiler has declarations of these facilities +available and can correctly process references to them. Once your +program has been compiled, the linker resolves these references to +the actual definitions provided in the archive file. + +Header files are included into a program source file by the +@samp{#include} preprocessor directive. The C language supports two +forms of this directive; the first, + +@smallexample +#include "@var{header}" +@end smallexample + +@noindent +is typically used to include a header file @var{header} that you write +yourself; this would contain definitions and declarations describing the +interfaces between the different parts of your particular application. +By contrast, + +@smallexample +#include <file.h> +@end smallexample + +@noindent +is typically used to include a header file @file{file.h} that contains +definitions and declarations for a standard library. This file would +normally be installed in a standard place by your system administrator. +You should use this second form for the C library header files. + +Typically, @samp{#include} directives are placed at the top of the C +source file, before any other code. If you begin your source files with +some comments explaining what the code in the file does (a good idea), +put the @samp{#include} directives immediately afterwards, following the +feature test macro definition (@pxref{Feature Test Macros}). + +For more information about the use of header files and @samp{#include} +directives, @pxref{Header Files,,, cpp.info, The GNU C Preprocessor +Manual}.@refill + +The GNU C library provides several header files, each of which contains +the type and macro definitions and variable and function declarations +for a group of related facilities. This means that your programs may +need to include several header files, depending on exactly which +facilities you are using. + +Some library header files include other library header files +automatically. However, as a matter of programming style, you should +not rely on this; it is better to explicitly include all the header +files required for the library facilities you are using. The GNU C +library header files have been written in such a way that it doesn't +matter if a header file is accidentally included more than once; +including a header file a second time has no effect. Likewise, if your +program needs to include multiple header files, the order in which they +are included doesn't matter. + +@strong{Compatibility Note:} Inclusion of standard header files in any +order and any number of times works in any ANSI C implementation. +However, this has traditionally not been the case in many older C +implementations. + +Strictly speaking, you don't @emph{have to} include a header file to use +a function it declares; you could declare the function explicitly +yourself, according to the specifications in this manual. But it is +usually better to include the header file because it may define types +and macros that are not otherwise available and because it may define +more efficient macro replacements for some functions. It is also a sure +way to have the correct declaration. + +@node Macro Definitions, Reserved Names, Header Files, Using the Library +@subsection Macro Definitions of Functions +@cindex shadowing functions with macros +@cindex removing macros that shadow functions +@cindex undefining macros that shadow functions + +If we describe something as a function in this manual, it may have a +macro definition as well. This normally has no effect on how your +program runs---the macro definition does the same thing as the function +would. In particular, macro equivalents for library functions evaluate +arguments exactly once, in the same way that a function call would. The +main reason for these macro definitions is that sometimes they can +produce an inline expansion that is considerably faster than an actual +function call. + +Taking the address of a library function works even if it is also +defined as a macro. This is because, in this context, the name of the +function isn't followed by the left parenthesis that is syntactically +necessary to recognize a macro call. + +You might occasionally want to avoid using the macro definition of a +function---perhaps to make your program easier to debug. There are +two ways you can do this: + +@itemize @bullet +@item +You can avoid a macro definition in a specific use by enclosing the name +of the function in parentheses. This works because the name of the +function doesn't appear in a syntactic context where it is recognizable +as a macro call. + +@item +You can suppress any macro definition for a whole source file by using +the @samp{#undef} preprocessor directive, unless otherwise stated +explicitly in the description of that facility. +@end itemize + +For example, suppose the header file @file{stdlib.h} declares a function +named @code{abs} with + +@smallexample +extern int abs (int); +@end smallexample + +@noindent +and also provides a macro definition for @code{abs}. Then, in: + +@smallexample +#include <stdlib.h> +int f (int *i) @{ return (abs (++*i)); @} +@end smallexample + +@noindent +the reference to @code{abs} might refer to either a macro or a function. +On the other hand, in each of the following examples the reference is +to a function and not a macro. + +@smallexample +#include <stdlib.h> +int g (int *i) @{ return ((abs)(++*i)); @} + +#undef abs +int h (int *i) @{ return (abs (++*i)); @} +@end smallexample + +Since macro definitions that double for a function behave in +exactly the same way as the actual function version, there is usually no +need for any of these methods. In fact, removing macro definitions usually +just makes your program slower. + + +@node Reserved Names, Feature Test Macros, Macro Definitions, Using the Library +@subsection Reserved Names +@cindex reserved names +@cindex name space + +The names of all library types, macros, variables and functions that +come from the ANSI C standard are reserved unconditionally; your program +@strong{may not} redefine these names. All other library names are +reserved if your program explicitly includes the header file that +defines or declares them. There are several reasons for these +restrictions: + +@itemize @bullet +@item +Other people reading your code could get very confused if you were using +a function named @code{exit} to do something completely different from +what the standard @code{exit} function does, for example. Preventing +this situation helps to make your programs easier to understand and +contributes to modularity and maintainability. + +@item +It avoids the possibility of a user accidentally redefining a library +function that is called by other library functions. If redefinition +were allowed, those other functions would not work properly. + +@item +It allows the compiler to do whatever special optimizations it pleases +on calls to these functions, without the possibility that they may have +been redefined by the user. Some library facilities, such as those for +dealing with variadic arguments (@pxref{Variadic Functions}) +and non-local exits (@pxref{Non-Local Exits}), actually require a +considerable amount of cooperation on the part of the C compiler, and +implementationally it might be easier for the compiler to treat these as +built-in parts of the language. +@end itemize + +In addition to the names documented in this manual, reserved names +include all external identifiers (global functions and variables) that +begin with an underscore (@samp{_}) and all identifiers regardless of +use that begin with either two underscores or an underscore followed by +a capital letter are reserved names. This is so that the library and +header files can define functions, variables, and macros for internal +purposes without risk of conflict with names in user programs. + +Some additional classes of identifier names are reserved for future +extensions to the C language or the POSIX.1 environment. While using these +names for your own purposes right now might not cause a problem, they do +raise the possibility of conflict with future versions of the C +or POSIX standards, so you should avoid these names. + +@itemize @bullet +@item +Names beginning with a capital @samp{E} followed a digit or uppercase +letter may be used for additional error code names. @xref{Error +Reporting}. + +@item +Names that begin with either @samp{is} or @samp{to} followed by a +lowercase letter may be used for additional character testing and +conversion functions. @xref{Character Handling}. + +@item +Names that begin with @samp{LC_} followed by an uppercase letter may be +used for additional macros specifying locale attributes. +@xref{Locales}. + +@item +Names of all existing mathematics functions (@pxref{Mathematics}) +suffixed with @samp{f} or @samp{l} are reserved for corresponding +functions that operate on @code{float} and @code{long double} arguments, +respectively. + +@item +Names that begin with @samp{SIG} followed by an uppercase letter are +reserved for additional signal names. @xref{Standard Signals}. + +@item +Names that begin with @samp{SIG_} followed by an uppercase letter are +reserved for additional signal actions. @xref{Basic Signal Handling}. + +@item +Names beginning with @samp{str}, @samp{mem}, or @samp{wcs} followed by a +lowercase letter are reserved for additional string and array functions. +@xref{String and Array Utilities}. + +@item +Names that end with @samp{_t} are reserved for additional type names. +@end itemize + +In addition, some individual header files reserve names beyond +those that they actually define. You only need to worry about these +restrictions if your program includes that particular header file. + +@itemize @bullet +@item +The header file @file{dirent.h} reserves names prefixed with +@samp{d_}. +@pindex dirent.h + +@item +The header file @file{fcntl.h} reserves names prefixed with +@samp{l_}, @samp{F_}, @samp{O_}, and @samp{S_}. +@pindex fcntl.h + +@item +The header file @file{grp.h} reserves names prefixed with @samp{gr_}. +@pindex grp.h + +@item +The header file @file{limits.h} reserves names suffixed with @samp{_MAX}. +@pindex limits.h + +@item +The header file @file{pwd.h} reserves names prefixed with @samp{pw_}. +@pindex pwd.h + +@item +The header file @file{signal.h} reserves names prefixed with @samp{sa_} +and @samp{SA_}. +@pindex signal.h + +@item +The header file @file{sys/stat.h} reserves names prefixed with @samp{st_} +and @samp{S_}. +@pindex sys/stat.h + +@item +The header file @file{sys/times.h} reserves names prefixed with @samp{tms_}. +@pindex sys/times.h + +@item +The header file @file{termios.h} reserves names prefixed with @samp{c_}, +@samp{V}, @samp{I}, @samp{O}, and @samp{TC}; and names prefixed with +@samp{B} followed by a digit. +@pindex termios.h +@end itemize + +@comment Include the section on Creature Nest Macros. +@comment It is in a separate file so it can be formatted into ../NOTES. +@include creature.texi + +@node Roadmap to the Manual, , Using the Library, Introduction +@section Roadmap to the Manual + +Here is an overview of the contents of the remaining chapters of +this manual. + +@itemize @bullet +@item +@ref{Error Reporting}, describes how errors detected by the library +are reported. + +@item +@ref{Language Features}, contains information about library support for +standard parts of the C language, including things like the @code{sizeof} +operator and the symbolic constant @code{NULL}, how to write functions +accepting variable numbers of arguments, and constants describing the +ranges and other properties of the numerical types. There is also a simple +debugging mechanism which allows you to put assertions in your code, and +have diagnostic messages printed if the tests fail. + +@item +@ref{Memory Allocation}, describes the GNU library's facilities for +dynamic allocation of storage. If you do not know in advance how much +storage your program needs, you can allocate it dynamically instead, +and manipulate it via pointers. + +@item +@ref{Character Handling}, contains information about character +classification functions (such as @code{isspace}) and functions for +performing case conversion. + +@item +@ref{String and Array Utilities}, has descriptions of functions for +manipulating strings (null-terminated character arrays) and general +byte arrays, including operations such as copying and comparison. + +@item +@ref{I/O Overview}, gives an overall look at the input and output +facilities in the library, and contains information about basic concepts +such as file names. + +@item +@ref{I/O on Streams}, describes I/O operations involving streams (or +@w{@code{FILE *}} objects). These are the normal C library functions +from @file{stdio.h}. + +@item +@ref{Low-Level I/O}, contains information about I/O operations +on file descriptors. File descriptors are a lower-level mechanism +specific to the Unix family of operating systems. + +@item +@ref{File System Interface}, has descriptions of operations on entire +files, such as functions for deleting and renaming them and for creating +new directories. This chapter also contains information about how you +can access the attributes of a file, such as its owner and file protection +modes. + +@item +@ref{Pipes and FIFOs}, contains information about simple interprocess +communication mechanisms. Pipes allow communication between two related +processes (such as between a parent and child), while FIFOs allow +communication between processes sharing a common file system on the same +machine. + +@item +@ref{Sockets}, describes a more complicated interprocess communication +mechanism that allows processes running on different machines to +communicate over a network. This chapter also contains information about +Internet host addressing and how to use the system network databases. + +@item +@ref{Low-Level Terminal Interface}, describes how you can change the +attributes of a terminal device. If you want to disable echo of +characters typed by the user, for example, read this chapter. + +@item +@ref{Mathematics}, contains information about the math library +functions. These include things like random-number generators and +remainder functions on integers as well as the usual trigonometric and +exponential functions on floating-point numbers. + +@item +@ref{Arithmetic,, Low-Level Arithmetic Functions}, describes functions +for simple arithmetic, analysis of floating-point values, and reading +numbers from strings. + +@item +@ref{Searching and Sorting}, contains information about functions +for searching and sorting arrays. You can use these functions on any +kind of array by providing an appropriate comparison function. + +@item +@ref{Pattern Matching}, presents functions for matching regular expressions +and shell file name patterns, and for expanding words as the shell does. + +@item +@ref{Date and Time}, describes functions for measuring both calendar time +and CPU time, as well as functions for setting alarms and timers. + +@item +@ref{Extended Characters}, contains information about manipulating +characters and strings using character sets larger than will fit in +the usual @code{char} data type. + +@item +@ref{Locales}, describes how selecting a particular country +or language affects the behavior of the library. For example, the locale +affects collation sequences for strings and how monetary values are +formatted. + +@item +@ref{Non-Local Exits}, contains descriptions of the @code{setjmp} and +@code{longjmp} functions. These functions provide a facility for +@code{goto}-like jumps which can jump from one function to another. + +@item +@ref{Signal Handling}, tells you all about signals---what they are, +how to establish a handler that is called when a particular kind of +signal is delivered, and how to prevent signals from arriving during +critical sections of your program. + +@item +@ref{Process Startup}, tells how your programs can access their +command-line arguments and environment variables. + +@item +@ref{Processes}, contains information about how to start new processes +and run programs. + +@item +@ref{Job Control}, describes functions for manipulating process groups +and the controlling terminal. This material is probably only of +interest if you are writing a shell or other program which handles job +control specially. + +@item +@ref{User Database}, and @ref{Group Database}, tell you how to access +the system user and group databases. + +@item +@ref{System Information}, describes functions for getting information +about the hardware and software configuration your program is executing +under. + +@item +@ref{System Configuration}, tells you how you can get information about +various operating system limits. Most of these parameters are provided for +compatibility with POSIX. + +@item +@ref{Library Summary}, gives a summary of all the functions, variables, and +macros in the library, with complete data types and function prototypes, +and says what standard or system each is derived from. + +@item +@ref{Maintenance}, explains how to build and install the GNU C library on +your system, how to report any bugs you might find, and how to add new +functions or port the library to a new system. +@end itemize + +If you already know the name of the facility you are interested in, you +can look it up in @ref{Library Summary}. This gives you a summary of +its syntax and a pointer to where you can find a more detailed +description. This appendix is particularly useful if you just want to +verify the order and type of arguments to a function, for example. It +also tells you what standard or system each function, variable, or macro +is derived from. |