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