intro.texi

一个C源代码分析器

@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.  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 standard, 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.

@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.
This material is probably only of interest if you are writing a shell.

@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.