1: @node Introduction, Error Reporting, Top, Top
    2: @chapter Introduction
    3: @c %MENU% Purpose of the GNU C Library
    4: 
    5: The C language provides no built-in facilities for performing such
    6: common operations as input/output, memory management, string
    7: manipulation, and the like.  Instead, these facilities are defined
    8: in a standard @dfn{library}, which you compile and link with your
    9: programs.
   10: @cindex library
   11: 
   12: The GNU C library, described in this document, defines all of the
   13: library functions that are specified by the @w{ISO C} standard, as well as
   14: additional features specific to POSIX and other derivatives of the Unix
   15: operating system, and extensions specific to the GNU system.
   16: 
   17: The purpose of this manual is to tell you how to use the facilities
   18: of the GNU library.  We have mentioned which features belong to which
   19: standards to help you identify things that are potentially non-portable
   20: to other systems.  But the emphasis in this manual is not on strict
   21: portability.
   22: 
   23: @menu
   24: * Getting Started::             What this manual is for and how to use it.
   25: * Standards and Portability::   Standards and sources upon which the GNU
   26:                                  C library is based.
   27: * Using the Library::           Some practical uses for the library.
   28: * Roadmap to the Manual::       Overview of the remaining chapters in
   29:                                  this manual.
   30: @end menu
   31: 
   32: @node Getting Started, Standards and Portability,  , Introduction
   33: @section Getting Started
   34: 
   35: This manual is written with the assumption that you are at least
   36: somewhat familiar with the C programming language and basic programming
   37: concepts.  Specifically, familiarity with ISO standard C
   38: (@pxref{ISO C}), rather than ``traditional'' pre-ISO C dialects, is
   39: assumed.
   40: 
   41: The GNU C library includes several @dfn{header files}, each of which
   42: provides definitions and declarations for a group of related facilities;
   43: this information is used by the C compiler when processing your program.
   44: For example, the header file @file{stdio.h} declares facilities for
   45: performing input and output, and the header file @file{string.h}
   46: declares string processing utilities.  The organization of this manual
   47: generally follows the same division as the header files.
   48: 
   49: If you are reading this manual for the first time, you should read all
   50: of the introductory material and skim the remaining chapters.  There are
   51: a @emph{lot} of functions in the GNU C library and it's not realistic to
   52: expect that you will be able to remember exactly @emph{how} to use each
   53: and every one of them.  It's more important to become generally familiar
   54: with the kinds of facilities that the library provides, so that when you
   55: are writing your programs you can recognize @emph{when} to make use of
   56: library functions, and @emph{where} in this manual you can find more
   57: specific information about them.
   58: 
   59: 
   60: @node Standards and Portability, Using the Library, Getting Started, Introduction
   61: @section Standards and Portability
   62: @cindex standards
   63: 
   64: This section discusses the various standards and other sources that the
   65: GNU C library is based upon.  These sources include the @w{ISO C} and
   66: POSIX standards, and the System V and Berkeley Unix implementations.
   67: 
   68: The primary focus of this manual is to tell you how to make effective
   69: use of the GNU library facilities.  But if you are concerned about
   70: making your programs compatible with these standards, or portable to
   71: operating systems other than GNU, this can affect how you use the
   72: library.  This section gives you an overview of these standards, so that
   73: you will know what they are when they are mentioned in other parts of
   74: the manual.
   75: 
   76: @xref{Library Summary}, for an alphabetical list of the functions and
   77: other symbols provided by the library.  This list also states which
   78: standards each function or symbol comes from.
   79: 
   80: @menu
   81: * ISO C::                       The international standard for the C
   82:                                  programming language.
   83: * POSIX::                       The ISO/IEC 9945 (aka IEEE 1003) standards
   84:                                  for operating systems.
   85: * Berkeley Unix::               BSD and SunOS.
   86: * SVID::                        The System V Interface Description.
   87: * XPG::                         The X/Open Portability Guide.
   88: @end menu
   89: 
   90: @node ISO C, POSIX,  , Standards and Portability
   91: @subsection ISO C
   92: @cindex ISO C
   93: 
   94: The GNU C library is compatible with the C standard adopted by the
   95: American National Standards Institute (ANSI):
   96: @cite{American National Standard X3.159-1989---``ANSI C''} and later
   97: by the International Standardization Organization (ISO):
   98: @cite{ISO/IEC 9899:1990, ``Programming languages---C''}.
   99: We here refer to the standard as @w{ISO C} since this is the more
  100: general standard in respect of ratification.
  101: The header files and library facilities that make up the GNU library are
  102: a superset of those specified by the @w{ISO C} standard.@refill
  103: 
  104: @pindex gcc
  105: If you are concerned about strict adherence to the @w{ISO C} standard, you
  106: should use the @samp{-ansi} option when you compile your programs with
  107: the GNU C compiler.  This tells the compiler to define @emph{only} ISO
  108: standard features from the library header files, unless you explicitly
  109: ask for additional features.  @xref{Feature Test Macros}, for
  110: information on how to do this.
  111: 
  112: Being able to restrict the library to include only @w{ISO C} features is
  113: important because @w{ISO C} puts limitations on what names can be defined
  114: by the library implementation, and the GNU extensions don't fit these
  115: limitations.  @xref{Reserved Names}, for more information about these
  116: restrictions.
  117: 
  118: This manual does not attempt to give you complete details on the
  119: differences between @w{ISO C} and older dialects.  It gives advice on how
  120: to write programs to work portably under multiple C dialects, but does
  121: not aim for completeness.
  122: 
  123: 
  124: @node POSIX, Berkeley Unix, ISO C, Standards and Portability
  125: @subsection POSIX (The Portable Operating System Interface)
  126: @cindex POSIX
  127: @cindex POSIX.1
  128: @cindex IEEE Std 1003.1
  129: @cindex ISO/IEC 9945-1
  130: @cindex POSIX.2
  131: @cindex IEEE Std 1003.2
  132: @cindex ISO/IEC 9945-2
  133: 
  134: The GNU library is also compatible with the ISO @dfn{POSIX} family of
  135: standards, known more formally as the @dfn{Portable Operating System
  136: Interface for Computer Environments} (ISO/IEC 9945).  They were also
  137: published as ANSI/IEEE Std 1003.  POSIX is derived mostly from various
  138: versions of the Unix operating system.
  139: 
  140: The library facilities specified by the POSIX standards are a superset
  141: of those required by @w{ISO C}; POSIX specifies additional features for
  142: @w{ISO C} functions, as well as specifying new additional functions.  In
  143: general, the additional requirements and functionality defined by the
  144: POSIX standards are aimed at providing lower-level support for a
  145: particular kind of operating system environment, rather than general
  146: programming language support which can run in many diverse operating
  147: system environments.@refill
  148: 
  149: The GNU C library implements all of the functions specified in
  150: @cite{ISO/IEC 9945-1:1996, the POSIX System Application Program
  151: Interface}, commonly referred to as POSIX.1.  The primary extensions to
  152: the @w{ISO C} facilities specified by this standard include file system
  153: interface primitives (@pxref{File System Interface}), device-specific
  154: terminal control functions (@pxref{Low-Level Terminal Interface}), and
  155: process control functions (@pxref{Processes}).
  156: 
  157: Some facilities from @cite{ISO/IEC 9945-2:1993, the POSIX Shell and
  158: Utilities standard} (POSIX.2) are also implemented in the GNU library.
  159: These include utilities for dealing with regular expressions and other
  160: pattern matching facilities (@pxref{Pattern Matching}).
  161: 
  162: @comment Roland sez:
  163: @comment The GNU C library as it stands conforms to 1003.2 draft 11, which
  164: @comment specifies:
  165: @comment
  166: @comment Several new macros in <limits.h>.
  167: @comment popen, pclose
  168: @comment <regex.h> (which is not yet fully implemented--wait on this)
  169: @comment fnmatch
  170: @comment getopt
  171: @comment <glob.h>
  172: @comment <wordexp.h> (not yet implemented)
  173: @comment confstr
  174: 
  175: 
  176: @node Berkeley Unix, SVID, POSIX, Standards and Portability
  177: @subsection Berkeley Unix
  178: @cindex BSD Unix
  179: @cindex 4.@var{n} BSD Unix
  180: @cindex Berkeley Unix
  181: @cindex SunOS
  182: @cindex Unix, Berkeley
  183: 
  184: The GNU C library defines facilities from some versions of Unix which
  185: are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD,
  186: and 4.4 BSD Unix systems (also known as @dfn{Berkeley Unix}) and from
  187: @dfn{SunOS} (a popular 4.2 BSD derivative that includes some Unix System
  188: V functionality).  These systems support most of the @w{ISO C} and POSIX
  189: facilities, and 4.4 BSD and newer releases of SunOS in fact support them all.
  190: 
  191: The BSD facilities include symbolic links (@pxref{Symbolic Links}), the
  192: @code{select} function (@pxref{Waiting for I/O}), the BSD signal
  193: functions (@pxref{BSD Signal Handling}), and sockets (@pxref{Sockets}).
  194: 
  195: @node SVID, XPG, Berkeley Unix, Standards and Portability
  196: @subsection SVID (The System V Interface Description)
  197: @cindex SVID
  198: @cindex System V Unix
  199: @cindex Unix, System V
  200: 
  201: The @dfn{System V Interface Description} (SVID) is a document describing
  202: the AT&T Unix System V operating system.  It is to some extent a
  203: superset of the POSIX standard (@pxref{POSIX}).
  204: 
  205: The GNU C library defines most of the facilities required by the SVID
  206: that are not also required by the @w{ISO C} or POSIX standards, for
  207: compatibility with  System V Unix and other Unix systems (such as
  208: SunOS) which include these facilities.  However, many of the more
  209: obscure and less generally useful facilities required by the SVID are
  210: not included.  (In fact, Unix System V itself does not provide them all.)
  211: 
  212: The supported facilities from System V include the methods for
  213: inter-process communication and shared memory, the @code{hsearch} and
  214: @code{drand48} families of functions, @code{fmtmsg} and several of the
  215: mathematical functions.
  216: 
  217: @node XPG, , SVID, Standards and Portability
  218: @subsection XPG (The X/Open Portability Guide)
  219: 
  220: The X/Open Portability Guide, published by the X/Open Company, Ltd., is
  221: a more general standard than POSIX.  X/Open owns the Unix copyright and
  222: the XPG specifies the requirements for systems which are intended to be
  223: a Unix system.
  224: 
  225: The GNU C library complies to the X/Open Portability Guide, Issue 4.2,
  226: with all extensions common to XSI (X/Open System Interface)
  227: compliant systems and also all X/Open UNIX extensions.
  228: 
  229: The additions on top of POSIX are mainly derived from functionality
  230: available in @w{System V} and BSD systems.  Some of the really bad
  231: mistakes in @w{System V} systems were corrected, though.  Since
  232: fulfilling the XPG standard with the Unix extensions is a
  233: precondition for getting the Unix brand chances are good that the
  234: functionality is available on commercial systems.
  235: 
  236: 
  237: @node Using the Library, Roadmap to the Manual, Standards and Portability, Introduction
  238: @section Using the Library
  239: 
  240: This section describes some of the practical issues involved in using
  241: the GNU C library.
  242: 
  243: @menu
  244: * Header Files::                How to include the header files in your
  245:                                  programs.
  246: * Macro Definitions::           Some functions in the library may really
  247:                                  be implemented as macros.
  248: * Reserved Names::              The C standard reserves some names for
  249:                                  the library, and some for users.
  250: * Feature Test Macros::         How to control what names are defined.
  251: @end menu
  252: 
  253: @node Header Files, Macro Definitions,  , Using the Library
  254: @subsection Header Files
  255: @cindex header files
  256: 
  257: Libraries for use by C programs really consist of two parts: @dfn{header
  258: files} that define types and macros and declare variables and
  259: functions; and the actual library or @dfn{archive} that contains the
  260: definitions of the variables and functions.
  261: 
  262: (Recall that in C, a @dfn{declaration} merely provides information that
  263: a function or variable exists and gives its type.  For a function
  264: declaration, information about the types of its arguments might be
  265: provided as well.  The purpose of declarations is to allow the compiler
  266: to correctly process references to the declared variables and functions.
  267: A @dfn{definition}, on the other hand, actually allocates storage for a
  268: variable or says what a function does.)
  269: @cindex definition (compared to declaration)
  270: @cindex declaration (compared to definition)
  271: 
  272: In order to use the facilities in the GNU C library, you should be sure
  273: that your program source files include the appropriate header files.
  274: This is so that the compiler has declarations of these facilities
  275: available and can correctly process references to them.  Once your
  276: program has been compiled, the linker resolves these references to
  277: the actual definitions provided in the archive file.
  278: 
  279: Header files are included into a program source file by the
  280: @samp{#include} preprocessor directive.  The C language supports two
  281: forms of this directive; the first,
  282: 
  283: @smallexample
  284: #include "@var{header}"
  285: @end smallexample
  286: 
  287: @noindent
  288: is typically used to include a header file @var{header} that you write
  289: yourself; this would contain definitions and declarations describing the
  290: interfaces between the different parts of your particular application.
  291: By contrast,
  292: 
  293: @smallexample
  294: #include <file.h>
  295: @end smallexample
  296: 
  297: @noindent
  298: is typically used to include a header file @file{file.h} that contains
  299: definitions and declarations for a standard library.  This file would
  300: normally be installed in a standard place by your system administrator.
  301: You should use this second form for the C library header files.
  302: 
  303: Typically, @samp{#include} directives are placed at the top of the C
  304: source file, before any other code.  If you begin your source files with
  305: some comments explaining what the code in the file does (a good idea),
  306: put the @samp{#include} directives immediately afterwards, following the
  307: feature test macro definition (@pxref{Feature Test Macros}).
  308: 
  309: For more information about the use of header files and @samp{#include}
  310: directives, @pxref{Header Files,,, cpp.info, The GNU C Preprocessor
  311: Manual}.@refill
  312: 
  313: The GNU C library provides several header files, each of which contains
  314: the type and macro definitions and variable and function declarations
  315: for a group of related facilities.  This means that your programs may
  316: need to include several header files, depending on exactly which
  317: facilities you are using.
  318: 
  319: Some library header files include other library header files
  320: automatically.  However, as a matter of programming style, you should
  321: not rely on this; it is better to explicitly include all the header
  322: files required for the library facilities you are using.  The GNU C
  323: library header files have been written in such a way that it doesn't
  324: matter if a header file is accidentally included more than once;
  325: including a header file a second time has no effect.  Likewise, if your
  326: program needs to include multiple header files, the order in which they
  327: are included doesn't matter.
  328: 
  329: @strong{Compatibility Note:} Inclusion of standard header files in any
  330: order and any number of times works in any @w{ISO C} implementation.
  331: However, this has traditionally not been the case in many older C
  332: implementations.
  333: 
  334: Strictly speaking, you don't @emph{have to} include a header file to use
  335: a function it declares; you could declare the function explicitly
  336: yourself, according to the specifications in this manual.  But it is
  337: usually better to include the header file because it may define types
  338: and macros that are not otherwise available and because it may define
  339: more efficient macro replacements for some functions.  It is also a sure
  340: way to have the correct declaration.
  341: 
  342: @node Macro Definitions, Reserved Names, Header Files, Using the Library
  343: @subsection Macro Definitions of Functions
  344: @cindex shadowing functions with macros
  345: @cindex removing macros that shadow functions
  346: @cindex undefining macros that shadow functions
  347: 
  348: If we describe something as a function in this manual, it may have a
  349: macro definition as well.  This normally has no effect on how your
  350: program runs---the macro definition does the same thing as the function
  351: would.  In particular, macro equivalents for library functions evaluate
  352: arguments exactly once, in the same way that a function call would.  The
  353: main reason for these macro definitions is that sometimes they can
  354: produce an inline expansion that is considerably faster than an actual
  355: function call.
  356: 
  357: Taking the address of a library function works even if it is also
  358: defined as a macro.  This is because, in this context, the name of the
  359: function isn't followed by the left parenthesis that is syntactically
  360: necessary to recognize a macro call.
  361: 
  362: You might occasionally want to avoid using the macro definition of a
  363: function---perhaps to make your program easier to debug.  There are
  364: two ways you can do this:
  365: 
  366: @itemize @bullet
  367: @item
  368: You can avoid a macro definition in a specific use by enclosing the name
  369: of the function in parentheses.  This works because the name of the
  370: function doesn't appear in a syntactic context where it is recognizable
  371: as a macro call.
  372: 
  373: @item
  374: You can suppress any macro definition for a whole source file by using
  375: the @samp{#undef} preprocessor directive, unless otherwise stated
  376: explicitly in the description of that facility.
  377: @end itemize
  378: 
  379: For example, suppose the header file @file{stdlib.h} declares a function
  380: named @code{abs} with
  381: 
  382: @smallexample
  383: extern int abs (int);
  384: @end smallexample
  385: 
  386: @noindent
  387: and also provides a macro definition for @code{abs}.  Then, in:
  388: 
  389: @smallexample
  390: #include <stdlib.h>
  391: int f (int *i) @{ return abs (++*i); @}
  392: @end smallexample
  393: 
  394: @noindent
  395: the reference to @code{abs} might refer to either a macro or a function.
  396: On the other hand, in each of the following examples the reference is
  397: to a function and not a macro.
  398: 
  399: @smallexample
  400: #include <stdlib.h>
  401: int g (int *i) @{ return (abs) (++*i); @}
  402: 
  403: #undef abs
  404: int h (int *i) @{ return abs (++*i); @}
  405: @end smallexample
  406: 
  407: Since macro definitions that double for a function behave in
  408: exactly the same way as the actual function version, there is usually no
  409: need for any of these methods.  In fact, removing macro definitions usually
  410: just makes your program slower.
  411: 
  412: 
  413: @node Reserved Names, Feature Test Macros, Macro Definitions, Using the Library
  414: @subsection Reserved Names
  415: @cindex reserved names
  416: @cindex name space
  417: 
  418: The names of all library types, macros, variables and functions that
  419: come from the @w{ISO C} standard are reserved unconditionally; your program
  420: @strong{may not} redefine these names.  All other library names are
  421: reserved if your program explicitly includes the header file that
  422: defines or declares them.  There are several reasons for these
  423: restrictions:
  424: 
  425: @itemize @bullet
  426: @item
  427: Other people reading your code could get very confused if you were using
  428: a function named @code{exit} to do something completely different from
  429: what the standard @code{exit} function does, for example.  Preventing
  430: this situation helps to make your programs easier to understand and
  431: contributes to modularity and maintainability.
  432: 
  433: @item
  434: It avoids the possibility of a user accidentally redefining a library
  435: function that is called by other library functions.  If redefinition
  436: were allowed, those other functions would not work properly.
  437: 
  438: @item
  439: It allows the compiler to do whatever special optimizations it pleases
  440: on calls to these functions, without the possibility that they may have
  441: been redefined by the user.  Some library facilities, such as those for
  442: dealing with variadic arguments (@pxref{Variadic Functions})
  443: and non-local exits (@pxref{Non-Local Exits}), actually require a
  444: considerable amount of cooperation on the part of the C compiler, and
  445: with respect to the implementation, it might be easier for the compiler
  446: to treat these as built-in parts of the language.
  447: @end itemize
  448: 
  449: In addition to the names documented in this manual, reserved names
  450: include all external identifiers (global functions and variables) that
  451: begin with an underscore (@samp{_}) and all identifiers regardless of
  452: use that begin with either two underscores or an underscore followed by
  453: a capital letter are reserved names.  This is so that the library and
  454: header files can define functions, variables, and macros for internal
  455: purposes without risk of conflict with names in user programs.
  456: 
  457: Some additional classes of identifier names are reserved for future
  458: extensions to the C language or the POSIX.1 environment.  While using these
  459: names for your own purposes right now might not cause a problem, they do
  460: raise the possibility of conflict with future versions of the C
  461: or POSIX standards, so you should avoid these names.
  462: 
  463: @itemize @bullet
  464: @item
  465: Names beginning with a capital @samp{E} followed a digit or uppercase
  466: letter may be used for additional error code names.  @xref{Error
  467: Reporting}.
  468: 
  469: @item
  470: Names that begin with either @samp{is} or @samp{to} followed by a
  471: lowercase letter may be used for additional character testing and
  472: conversion functions.  @xref{Character Handling}.
  473: 
  474: @item
  475: Names that begin with @samp{LC_} followed by an uppercase letter may be
  476: used for additional macros specifying locale attributes.
  477: @xref{Locales}.
  478: 
  479: @item
  480: Names of all existing mathematics functions (@pxref{Mathematics})
  481: suffixed with @samp{f} or @samp{l} are reserved for corresponding
  482: functions that operate on @code{float} and @code{long double} arguments,
  483: respectively.
  484: 
  485: @item
  486: Names that begin with @samp{SIG} followed by an uppercase letter are
  487: reserved for additional signal names.  @xref{Standard Signals}.
  488: 
  489: @item
  490: Names that begin with @samp{SIG_} followed by an uppercase letter are
  491: reserved for additional signal actions.  @xref{Basic Signal Handling}.
  492: 
  493: @item
  494: Names beginning with @samp{str}, @samp{mem}, or @samp{wcs} followed by a
  495: lowercase letter are reserved for additional string and array functions.
  496: @xref{String and Array Utilities}.
  497: 
  498: @item
  499: Names that end with @samp{_t} are reserved for additional type names.
  500: @end itemize
  501: 
  502: In addition, some individual header files reserve names beyond
  503: those that they actually define.  You only need to worry about these
  504: restrictions if your program includes that particular header file.
  505: 
  506: @itemize @bullet
  507: @item
  508: The header file @file{dirent.h} reserves names prefixed with
  509: @samp{d_}.
  510: @pindex dirent.h
  511: 
  512: @item
  513: The header file @file{fcntl.h} reserves names prefixed with
  514: @samp{l_}, @samp{F_}, @samp{O_}, and @samp{S_}.
  515: @pindex fcntl.h
  516: 
  517: @item
  518: The header file @file{grp.h} reserves names prefixed with @samp{gr_}.
  519: @pindex grp.h
  520: 
  521: @item
  522: The header file @file{limits.h} reserves names suffixed with @samp{_MAX}.
  523: @pindex limits.h
  524: 
  525: @item
  526: The header file @file{pwd.h} reserves names prefixed with @samp{pw_}.
  527: @pindex pwd.h
  528: 
  529: @item
  530: The header file @file{signal.h} reserves names prefixed with @samp{sa_}
  531: and @samp{SA_}.
  532: @pindex signal.h
  533: 
  534: @item
  535: The header file @file{sys/stat.h} reserves names prefixed with @samp{st_}
  536: and @samp{S_}.
  537: @pindex sys/stat.h
  538: 
  539: @item
  540: The header file @file{sys/times.h} reserves names prefixed with @samp{tms_}.
  541: @pindex sys/times.h
  542: 
  543: @item
  544: The header file @file{termios.h} reserves names prefixed with @samp{c_},
  545: @samp{V}, @samp{I}, @samp{O}, and @samp{TC}; and names prefixed with
  546: @samp{B} followed by a digit.
  547: @pindex termios.h
  548: @end itemize
  549: 
  550: @comment Include the section on Creature Nest Macros.
  551: @comment It is in a separate file so it can be formatted into ../NOTES.
  552: @include creature.texi
  553: 
  554: @node Roadmap to the Manual,  , Using the Library, Introduction
  555: @section Roadmap to the Manual
  556: 
  557: Here is an overview of the contents of the remaining chapters of
  558: this manual.
  559: 
  560: @itemize @bullet
  561: @item
  562: @ref{Error Reporting}, describes how errors detected by the library
  563: are reported.
  564: 
  565: @item
  566: @ref{Language Features}, contains information about library support for
  567: standard parts of the C language, including things like the @code{sizeof}
  568: operator and the symbolic constant @code{NULL}, how to write functions
  569: accepting variable numbers of arguments, and constants describing the
  570: ranges and other properties of the numerical types.  There is also a simple
  571: debugging mechanism which allows you to put assertions in your code, and
  572: have diagnostic messages printed if the tests fail.
  573: 
  574: @item
  575: @ref{Memory}, describes the GNU library's facilities for managing and
  576: using virtual and real memory, including dynamic allocation of virtual
  577: memory.  If you do not know in advance how much memory your program
  578: needs, you can allocate it dynamically instead, and manipulate it via
  579: pointers.
  580: 
  581: @item
  582: @ref{Character Handling}, contains information about character
  583: classification functions (such as @code{isspace}) and functions for
  584: performing case conversion.
  585: 
  586: @item
  587: @ref{String and Array Utilities}, has descriptions of functions for
  588: manipulating strings (null-terminated character arrays) and general
  589: byte arrays, including operations such as copying and comparison.
  590: 
  591: @item
  592: @ref{I/O Overview}, gives an overall look at the input and output
  593: facilities in the library, and contains information about basic concepts
  594: such as file names.
  595: 
  596: @item
  597: @ref{I/O on Streams}, describes I/O operations involving streams (or
  598: @w{@code{FILE *}} objects).  These are the normal C library functions
  599: from @file{stdio.h}.
  600: 
  601: @item
  602: @ref{Low-Level I/O}, contains information about I/O operations
  603: on file descriptors.  File descriptors are a lower-level mechanism
  604: specific to the Unix family of operating systems.
  605: 
  606: @item
  607: @ref{File System Interface}, has descriptions of operations on entire
  608: files, such as functions for deleting and renaming them and for creating
  609: new directories.  This chapter also contains information about how you
  610: can access the attributes of a file, such as its owner and file protection
  611: modes.
  612: 
  613: @item
  614: @ref{Pipes and FIFOs}, contains information about simple interprocess
  615: communication mechanisms.  Pipes allow communication between two related
  616: processes (such as between a parent and child), while FIFOs allow
  617: communication between processes sharing a common file system on the same
  618: machine.
  619: 
  620: @item
  621: @ref{Sockets}, describes a more complicated interprocess communication
  622: mechanism that allows processes running on different machines to
  623: communicate over a network.  This chapter also contains information about
  624: Internet host addressing and how to use the system network databases.
  625: 
  626: @item
  627: @ref{Low-Level Terminal Interface}, describes how you can change the
  628: attributes of a terminal device.  If you want to disable echo of
  629: characters typed by the user, for example, read this chapter.
  630: 
  631: @item
  632: @ref{Mathematics}, contains information about the math library
  633: functions.  These include things like random-number generators and
  634: remainder functions on integers as well as the usual trigonometric and
  635: exponential functions on floating-point numbers.
  636: 
  637: @item
  638: @ref{Arithmetic,, Low-Level Arithmetic Functions}, describes functions
  639: for simple arithmetic, analysis of floating-point values, and reading
  640: numbers from strings.
  641: 
  642: @item
  643: @ref{Searching and Sorting}, contains information about functions
  644: for searching and sorting arrays.  You can use these functions on any
  645: kind of array by providing an appropriate comparison function.
  646: 
  647: @item
  648: @ref{Pattern Matching}, presents functions for matching regular expressions
  649: and shell file name patterns, and for expanding words as the shell does.
  650: 
  651: @item
  652: @ref{Date and Time}, describes functions for measuring both calendar time
  653: and CPU time, as well as functions for setting alarms and timers.
  654: 
  655: @item
  656: @ref{Character Set Handling}, contains information about manipulating
  657: characters and strings using character sets larger than will fit in
  658: the usual @code{char} data type.
  659: 
  660: @item
  661: @ref{Locales}, describes how selecting a particular country
  662: or language affects the behavior of the library.  For example, the locale
  663: affects collation sequences for strings and how monetary values are
  664: formatted.
  665: 
  666: @item
  667: @ref{Non-Local Exits}, contains descriptions of the @code{setjmp} and
  668: @code{longjmp} functions.  These functions provide a facility for
  669: @code{goto}-like jumps which can jump from one function to another.
  670: 
  671: @item
  672: @ref{Signal Handling}, tells you all about signals---what they are,
  673: how to establish a handler that is called when a particular kind of
  674: signal is delivered, and how to prevent signals from arriving during
  675: critical sections of your program.
  676: 
  677: @item
  678: @ref{Program Basics}, tells how your programs can access their
  679: command-line arguments and environment variables.
  680: 
  681: @item
  682: @ref{Processes}, contains information about how to start new processes
  683: and run programs.
  684: 
  685: @item
  686: @ref{Job Control}, describes functions for manipulating process groups
  687: and the controlling terminal.  This material is probably only of
  688: interest if you are writing a shell or other program which handles job
  689: control specially.
  690: 
  691: @item
  692: @ref{Name Service Switch}, describes the services which are available
  693: for looking up names in the system databases, how to determine which
  694: service is used for which database, and how these services are
  695: implemented so that contributors can design their own services.
  696: 
  697: @item
  698: @ref{User Database}, and @ref{Group Database}, tell you how to access
  699: the system user and group databases.
  700: 
  701: @item
  702: @ref{System Management}, describes functions for controlling and getting
  703: information about the hardware and software configuration your program
  704: is executing under.
  705: 
  706: @item
  707: @ref{System Configuration}, tells you how you can get information about
  708: various operating system limits.  Most of these parameters are provided for
  709: compatibility with POSIX.
  710: 
  711: @item
  712: @ref{Library Summary}, gives a summary of all the functions, variables, and
  713: macros in the library, with complete data types and function prototypes,
  714: and says what standard or system each is derived from.
  715: 
  716: @item
  717: @ref{Maintenance}, explains how to build and install the GNU C library on
  718: your system, how to report any bugs you might find, and how to add new
  719: functions or port the library to a new system.
  720: @end itemize
  721: 
  722: If you already know the name of the facility you are interested in, you
  723: can look it up in @ref{Library Summary}.  This gives you a summary of
  724: its syntax and a pointer to where you can find a more detailed
  725: description.  This appendix is particularly useful if you just want to
  726: verify the order and type of arguments to a function, for example.  It
  727: also tells you what standard or system each function, variable, or macro
  728: is derived from.