Update subnode names in memory chapter.
[kopensolaris-gnu/glibc.git] / manual / libc.texinfo
1 \input texinfo                  @c -*- Texinfo -*-
2 @comment %**start of header (This is for running Texinfo on a region.)
3 @setfilename library.info
4 @settitle The GNU C Library
5 @setchapternewpage odd
6 @comment %**end of header (This is for running Texinfo on a region.)
7
8 @ifinfo
9 This file documents the GNU C library.
10
11 Copyright (C) 1992 Free Software Foundation, Inc.
12
13 This will be free information when it is finished, but isn't finished yet.
14 @end ifinfo
15
16 @setchapternewpage odd
17
18 @titlepage
19 @center @titlefont{The GNU C Library}
20 @sp 1
21 @center @titlefont{Reference Manual}
22 @sp 2
23 @center Sandra Loosemore
24 @center with
25 @center Roland McGrath, Andrew Oram, and Richard M. Stallman
26 @sp 3
27 @center last updated January 10, 1992
28 @sp 1
29 @center for version 0.00
30 @page
31 @vskip 0pt plus 1filll
32 Copyright @copyright{} 1992 Free Software Foundation, Inc.
33 @end titlepage
34 @page
35
36 @ifinfo
37 @node Top, Introduction, (dir), (dir)
38 @top Main Menu
39 This is the reference manual for version 0.00 of the GNU C Library.
40 @end ifinfo
41
42
43 @menu
44 * Introduction::                Purpose of the GNU C Library.
45 * Error Reporting::             How the GNU Library functions report
46                                          error conditions.
47 * Memory Allocation::           Your program can allocate memory
48                                          dynamically and manipulate it via
49                                          pointers.
50 * Character Handling::          Character testing and conversion
51                                          functions.
52 * String and Array Utilities::  Utilities for copying and comparing
53                                          strings and arrays.
54 * Extended Characters::         Support for extended character sets.
55 * Locales::                     The country and language can affect
56                                          the behavior of library functions.
57 * Searching and Sorting::       General searching and sorting
58                                          functions.
59 * Pattern Matching::   Matching wildcards and regular expressions.
60                           Shell-style ``word expansion''.
61 * I/O Overview::       Introduction to the I/O facilities.
62 * I/O on Streams::     High-level, portable I/O facilities.
63 * Low-Level I/O::      Low-level, less portable I/O.
64 * File System Interface::       Functions for manipulating files.
65 * Pipes and FIFOs::             A simple interprocess communication
66                                          mechanism.
67 * Sockets::                     A more complicated interprocess
68                                          communication mechanism, with support
69                                          for networking.
70 * Low-Level Terminal Interface::  How to change the characteristics
71                                          of a terminal device.
72 * Mathematics::                 Math functions (transcendental,
73                                           random numbers, abs value).
74 * Arithmetic::                  Low-level arithmetic functions.
75 * Date and Time::               Functions for getting the date and
76                                          time, and conversion between formats.
77 * Non-Local Exits::             The @code{setjmp} and @code{longjmp}
78                                          facilities.
79 * Signal Handling::             All about signals; how to send them,
80                                          block them, and handle them.
81 * Process Startup::             Writing the beginning and end of your program.
82 * Child Processes::             How to create processes and run other programs.
83 * Job Control::                 All about process groups and sessions.
84 * Users and Groups::            How users are identified and classified.
85                                   The database of users.
86 * System Information::          Getting information about the
87                                          hardware and software configuration
88                                          of the machine a program runs on.
89 * System Configuration::        Parameters describing operating
90                                          system limits.
91
92 Appendices
93 * Language Features::           C language features provided by the library. 
94
95 * Library Summary::             A summary showing the syntax, header
96                                          file, and derivation of each library
97                                          feature.
98 * Maintenance::                 How to install and maintain the
99                                          GNU C Library.
100 * Copying::                     The GNU Library General Public License
101                                          says how you can copy and share the
102                                          GNU C Library.
103
104 Indices
105 * Concept Index::               Index of concepts and names.
106 * Type Index::                  Index of types and type qualifiers.
107 * Function Index::              Index of functions and function-like macros.
108 * Variable Index::              Index of variables and variable-like macros.
109 * File Index::                  Index of programs and files.
110
111  --- The Detailed Node Listing ---
112
113 Introduction
114
115 * Getting Started::             Getting Started
116 * Standards and Portability::   Standards and Portability
117 * Using the Library::           Using the Library
118 * Roadmap to the Manual::       Roadmap to the Manual
119
120 Standards and Portability
121
122 * ANSI C::                      The American National Standard for the
123                                  C programming language.  
124 * POSIX::                       The IEEE 1003 standards for operating systems.
125 * Berkeley Unix::               BSD and SunOS.
126 * SVID::                        The System V Interface Description.  
127
128 Using the Library
129
130 * Header Files::                How to include the header files in your programs.
131 * Macro Definitions::           Some functions in the library may really be 
132                          implemented as macros.
133 * Reserved Names::              The C standard reserves some names for the library,
134                          and some for users.
135 * Feature Test Macros::         How to control what names are defined.
136
137 Error Reporting
138
139 * Checking for Errors::         How errors are reported by library functions.
140 * Error Codes::                 Error Codes
141 * Error Messages::              Mapping error codes onto error messages.
142
143 Memory Allocation
144
145 * Memory Concepts::             An introduction to concepts and terminology.
146 * Dynamic Allocation and C::    How to get different kinds of allocation in C.
147 * Unconstrained Allocation::    The @code{malloc} facility allows fully general
148                                  dynamic allocation.
149 * Obstacks::                    Obstacks are less general than malloc
150                                  but more efficient and convenient.
151 * Variable Size Automatic::     Allocation of variable-sized blocks
152                                  of automatic storage that are freed when the
153                                  calling function returns.
154 * Relocating Allocator::        Waste less memory, if you can tolerate
155                                  automatic relocation of the blocks you get.
156 * Memory Warnings::             Getting warnings when memory is nearly full.
157
158 Unconstrained Allocation
159
160 * Basic Allocation::            Simple use of @code{malloc}.
161 * Malloc Examples::             Examples of @code{malloc}.  @code{xmalloc}.
162 * Freeing after Malloc::        Use @code{free} to free a block you
163                                  got with @code{malloc}.
164 * Changing Block Size::         Use @code{realloc} to make a block
165                                  bigger or smaller.
166 * Allocating Cleared Space::    Use @code{calloc} to allocate a
167                                  block and clear it.
168 * Efficiency and Malloc::       Efficiency considerations in use of
169                                  these functions.
170 * Aligned Memory Blocks::       Allocating specially aligned memory:
171                                  @code{memalign} and @code{valloc}.
172 * Heap Consistency Checking::   Automatic checking for errors.
173 * Hooks for Malloc::            You can use these hooks for debugging
174                                  programs that use @code{malloc}.
175 * Statistics of Malloc::        Getting information about how much
176                                  memory your program is using.
177 * Summary of Malloc::           Summary of @code{malloc} and related functions.
178
179 Obstacks
180
181 * Creating Obstacks::           How to declare an obstack in your program.
182 * Preparing for Obstacks::      Preparations needed before you can
183                                  use obstacks.
184 * Allocation in an Obstack::    Allocating objects in an obstack.
185 * Freeing Obstack Objects::     Freeing objects in an obstack.
186 * Obstack Functions::           The obstack functions are both
187                                  functions and macros.
188 * Growing Objects::             Making an object bigger by stages.
189 * Extra Fast Growing::          Extra-high-efficiency (though more
190                                  complicated) growing objects.
191 * Status of an Obstack::        Inquiries about the status of an obstack.
192 * Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
193 * Obstack Chunks::              How obstacks obtain and release chunks. 
194                                 Efficiency considerations.
195 * Summary of Obstacks::         
196
197 Automatic Storage with Variable Size
198
199 * Alloca Example::              Example of using @code{alloca}.
200 * Advantages of Alloca::        Reasons to use @code{alloca}.
201 * Disadvantages of Alloca::     Reasons to avoid @code{alloca}.
202 * GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
203                                  method of allocating dynamically and
204                                  freeing automatically.
205 Relocating Allocator
206
207 * Relocator Concepts::          How to understand relocating allocation.
208 * Using Relocator::             Functions for relocating allocation.
209
210 Character Handling
211
212 * Classification of Characters::  Testing whether characters are
213                                          letters, digits, punctuation, etc.
214 * Case Conversion::             Case mapping, and the like.
215
216 String and Array Utilities
217
218 * Representation of Strings::   Introduction to basic concepts.
219 * String/Array Conventions::    Whether to use a string function or an
220                                  arbitrary array function.
221 * String Length::               Determining the length of a string.
222 * Copying and Concatenation::   Functions to copy the contents of strings
223                                  and arrays.
224 * String/Array Comparison::     Functions for byte-wise and character-wise
225                                  comparison.
226 * Collation Functions::         Functions for collating strings.
227 * Search Functions::            Searching for a specific element or substring.
228 * Finding Tokens in a String::  Splitting a string into tokens by looking
229                                  for delimiters.
230
231 Extended Characters
232
233 * Extended Char Intro::         Multibyte codes versus wide characters.
234 * Locales and Extended Chars::  The locale selects the character codes.
235 * Multibyte Char Intro::        How multibyte codes are represented.
236 * Wide Char Intro::             How wide characters are represented.
237 * Wide String Conversion::      Converting wide strings to multibyte code
238                                    and vice versa.
239 * Length of Char::              how many bytes make up one multibyte char.
240 * Converting One Char::         Converting a string character by character.
241 * Example of Conversion::       Example showing why converting 
242                                    one character at a time may be useful.
243 * Shift State::                 Multibyte codes with "shift characters".
244
245 Locales and Internationalization
246
247 * Effects of Locale::           Actions affected by the choice of locale.
248 * Choosing Locale::             How the user specifies a locale.
249 * Locale Categories::           Different purposes for which you can select a locale.
250 * Setting the Locale::          How a program specifies the locale library functions.
251 * Standard Locales::            Locale names available on all systems.
252 * Numeric Formatting::          How to format numbers according to the chosen locale.
253
254 Numeric Formatting
255
256 * General Numeric::             
257 * Currency Symbol::             
258 * Sign of Money Amount::        
259
260 Searching and Sorting 
261
262 * Comparison Functions::        Defining how to compare two objects.
263                                 Since the sort and search facilities are
264                                 general, you have to specify the ordering.
265 * Array Search Function::       The @code{bsearch} function.
266 * Array Sort Function::         The @code{qsort} function.
267 * Search/Sort Example::         An example program.
268
269 Pattern Matching
270
271 * Wildcard Matching::    Matching a wildcard pattern against a single string.
272 * Globbing::             Finding the files that match a wildcard pattern.
273 * Regular Expressions::  Matching regular expressions against strings.
274 * Word Expansion::       Expanding shell variables, nested commands,
275                             arithmetic, and wildcards.
276                             This is what the shell does with shell commands.
277
278 I/O Overview
279
280 * I/O Concepts::       Some basic information and terminology.
281 * File Names::                  How to refer to a file.
282
283 I/O Concepts
284
285 * Streams and File Descriptors::  The GNU Library provides two ways
286                                          to access the contents of files.
287 * File Position::               
288
289 File Names
290
291 * Directories::                 Directories contain entries for files.
292 * File Name Resolution::        A file name specifies how to look up a file.
293 * File Name Errors::            Error conditions relating to file names.
294 * File Name Portability::   
295
296 I/O on Streams
297
298 * Streams::                     About the data type representing a stream.
299 * Standard Streams::            Streams to the standard input and output 
300                          devices are created for you.
301 * Opening Streams::             How to create a stream to talk to a file.
302 * Closing Streams::             Close a stream when you are finished with it.
303 * Simple Output::               Unformatted output by characters and lines.
304 * Character Input::             Unformatted input by characters and words.
305 * Line Input::                  Reading a line or a record from a stream.
306 * Unreading::                   Peeking ahead/pushing back input just read.
307 * Formatted Output::            @code{printf} and related functions.
308 * Customizing Printf::          You can define new conversion specifiers for
309                          @code{printf} and friends.
310 * Formatted Input::             @code{scanf} and related functions.
311 * Block Input/Output::          Input and output operations on blocks of data.
312 * EOF and Errors::              How you can tell if an I/O error happens.
313 * Binary Streams::              Some systems distinguish between text files
314                          and binary files.
315 * File Positioning::            About random-access streams.
316 * Portable Positioning::        Random access on peculiar ANSI C systems.
317 * Stream Buffering::            How to control buffering of streams.
318 * Temporary Files::             How to open a temporary file.
319 * Other Kinds of Streams::      Other Kinds of Streams
320
321 Unreading
322
323 * Unreading Idea::              An explanation of unreading with pictures.
324 * How Unread::                  How to call @code{ungetc} to do unreading.
325
326 Formatted Output
327
328 * Formatted Output Basics::     Some examples to get you started.
329 * Output Conversion Syntax::    General syntax of conversion
330                                          specifications.
331 * Table of Output Conversions::  Summary of output conversions and
332                                          what they do.
333 * Integer Conversions::         Details about formatting of integers.
334 * Floating-Point Conversions::  Details about formatting of
335                                          floating-point numbers.
336 * Other Output Conversions::    Details about formatting of strings,
337                                          characters, pointers, and the like.
338 * Formatted Output Functions::  Descriptions of the actual functions.
339 * Variable Arguments Output::  @code{vprintf} and friends.
340 * Parsing a Template String::   What kinds of args
341                                          does a given template call for?
342
343 Customizing Printf
344
345 * Registering New Conversions::  
346 * Conversion Specifier Options::  
347 * Defining the Output Handler::  
348 * Printf Extension Example::    
349
350 Formatted Input
351
352 * Formatted Input Basics::      Some basics to get you started.
353 * Input Conversion Syntax::     Syntax of conversion specifications.
354 * Table of Input Conversions::  Summary of input conversions and what they do.
355 * Numeric Input Conversions::   Details of conversions for reading numbers.
356 * String Input Conversions::    Details of conversions for reading strings.
357 * Other Input Conversions::     Details of miscellaneous other conversions.
358 * Formatted Input Functions::   Descriptions of the actual functions.
359 * Variable Arguments Input::  @code{vscanf} and friends.
360
361 Stream Buffering
362
363 * Buffering Concepts::          Terminology is defined here.
364 * Flushing Buffers::            How to ensure that output buffers are flushed.
365 * Controlling Buffering::       How to specify what kind of buffering to use.
366
367 Other Kinds of Streams
368
369 * String Streams::              
370 * Custom Streams::              
371
372 Programming Your Own Custom Streams
373
374 * Streams and Cookies::         
375 * Hook Functions::              
376
377 Low-Level I/O
378
379 * Opening and Closing Files::   How to open and close file descriptors.
380 * I/O Primitives::              Reading and writing data.
381 * File Position Primitive::     Setting a descriptor's file position.
382 * Descriptors and Streams::     Converting descriptor to stream
383                                          or vice-versa.
384 * Stream/Descriptor Precautions::  Precautions needed if you use both
385                                          descriptors and streams.
386 * Waiting for I/O::             How to check for input or output
387                                          on multiple file descriptors.
388 * Control Operations::          Various other operations on file
389                                          descriptors.
390 * Duplicating Descriptors::     Fcntl commands for duplicating file
391                                          descriptors.
392 * Descriptor Flags::            Fcntl commands for manipulating flags
393                                          associated with file descriptors.
394 * File Status Flags::           Fcntl commands for manipulating flags
395                                          associated with open files.
396 * File Locks::                  Fcntl commands for implementing file
397                                          locking.
398 * Interrupt Input::             Getting an asynchronous signal when
399                                          input arrives.
400
401 File System Interface
402
403 * Working Directory::           This is used to resolve relative
404                                  file names.
405 * Accessing Directories::       Finding out what files a directory
406                                  contains.
407 * Hard Links::                  Adding alternate names to a file.
408 * Symbolic Links::              A file that ``points to'' a file name.
409 * Deleting Files::              How to delete a file, and what that means.
410 * Renaming Files::              Changing a file's name.
411 * Creating Directories::        A system call just for creating a directory.
412 * File Attributes::             Attributes of individual files.
413 * Making Special Files::        How to create special files.
414
415 Accessing Directories
416
417 * Directory Entries::           Format of one directory entry.
418 * Opening a Directory::         How to open a directory stream.
419 * Reading/Closing Directory::   How to read directory entries from the stream.
420 * Simple Directory Lister::     A very simple directory listing program.
421 * Random Access Directory::     Rereading part of the directory
422                                   already read with the same stream.
423
424 File Attributes
425
426 * Attribute Meanings::          The names of the file attributes, 
427                            and what their values mean.
428 * Reading Attributes::          How to read the attributes of a file.
429 * Testing File Type::           Distinguishing ordinary files, directories, links...
430 * File Owner::                  How ownership for new files is determined,
431                            and how to change it.
432 * Permission Bits::             How information about a file's access mode is stored.
433 * Access Permission::           How the system decides who can access a file.
434 * Setting Permissions::         How permissions for new files are assigned,
435                            and how to change them.
436 * Testing File Access::         How to find out if your process can access a file.
437 * File Times::                  About the time attributes of a file.
438
439 Pipes and FIFOs
440
441 * Creating a Pipe::             Making a pipe with the @code{pipe} function.
442 * Pipe to a Subprocess::        Using a pipe to communicate with a
443                                  child process.
444 * FIFO Special Files::          Making a FIFO special file.
445
446 Sockets
447
448 * Socket Concepts::             Basic concepts you need to know about.
449 * Communication Styles::        Stream communication, datagrams, and others.
450 * Socket Addresses::            How socket names (``addresses'') work.
451 * File Namespace::              Details about the file namespace.
452 * Internet Namespace::          Details about the Internet namespace.
453 * Open/Close Sockets::          Creating sockets and destroying them.
454 * Connections::                 Operations on sockets with connection state.
455 * Datagrams::                   Operations on datagram sockets.
456 * Socket Options::              Miscellaneous low-level socket options.
457 * Networks Database::           Accessing the database of network names.
458
459 Socket Addresses
460
461 * Address Formats::             About @code{struct sockaddr}.
462 * Setting Address::             Binding an address to a socket.
463 * Reading Address::             Reading the address of a socket.
464
465 Internet Domain
466
467 * Internet Address Format::     How socket addresses are specified in the
468                                    Internet namespace.
469 * Host Addresses::              All about host addresses of internet host.
470 * Protocols Database::          Referring to protocols by name.
471 * Services Database::           Ports may have symbolic names.
472 * Byte Order::                  Different hosts may use different byte
473                                    ordering conventions; you need to
474                                    canonicalize host address and port number. 
475 * Inet Example::                Putting it all together.
476
477 Host Addresses
478
479 * Abstract Host Addresses::     What a host number consists of.
480 * Data type: Host Address Data Type.    Data type for a host number.
481 * Functions: Host Address Functions.    Functions to operate on them.
482 * Names: Host Names.            Translating host names to host numbers.
483
484 Open/Close Sockets
485
486 * Creating a Socket::           How to open a socket.
487 * Closing a Socket::            How to close a socket.
488 * Socket Pairs::                These are created like pipes.
489
490 Connections
491
492 * Connecting::                  What the client program must do.
493 * Listening::                   How a server program waits for requests.
494 * Accepting Connections::       What the server does when it gets a request.
495 * Who is Connected::            Getting the address of the
496                                    other side of a connection.
497 * Transferring Data::           How to send and receive data.
498 * Byte Stream Example::         An example program: a client for communicating
499                                    over a byte stream socket
500                                    in the Internet namespace.
501 * Server Example::              A corresponding server program.
502 * Out-of-Band Data::            This is an advanced feature.
503
504 Transferring Data
505
506 * Sending Data::                Sending data with @code{write}.
507 * Receiving Data::              Reading data with @code{read}.
508 * Socket Data Options::         Using @code{send} and @code{recv}.
509
510 Datagrams
511
512 * Sending Datagrams::           Sending packets on a datagram socket.
513 * Receiving Datagrams::         Receiving packets on a datagram socket.
514 * Datagram Example::            An example program: packets sent over a
515                                    datagram stream in the file namespace.
516 * Example Receiver::            Another program, that receives those packets.
517
518 Socket Options
519
520 * Socket Option Functions::     The basic functions for setting and getting
521                                    socket options.
522 * Socket-Level Options::        Details of the options at the socket level.
523
524 Low-Level Terminal Interface
525
526 * Is It a Terminal::            How to determine if a file is a terminal
527                           device, and what its name is.
528 * I/O Queues::                  About flow control and typeahead.
529 * Canonical or Not::            Two basic styles of input processing.
530 * Terminal Modes::              How to examine and modify flags controlling
531                           details of terminal I/O: echoing, signals, editing.
532 * Line Control::                Sending break sequences, clearing terminal buffers...
533 * Noncanon Example::            How to read single characters without echo.
534
535 Terminal Modes
536
537 * Mode Data Types::             The data type @code{struct termios} and related types.
538 * Mode Functions::              Functions to read and set the terminal attributes.
539 * Setting Modes::               The right way to set terminal attributes reliably.
540 * Input Modes::                 Flags controlling low-level input handling.
541 * Output Modes::                Flags controlling low-level output handling.
542 * Control Modes::               Flags controlling serial port behavior.
543 * Local Modes::                 Flags controlling high-level input handling.
544 * Line Speed::                  How to read and set the terminal line speed.
545 * Special Characters::          Characters that have special effects,
546                           and how to change them.
547 * Noncanonical Input::          Controlling how long to wait for input.
548
549 Special Characters
550
551 * Editing Characters::          
552 * Signal Characters::           
553 * Start/Stop Characters::       
554
555 Mathematics
556
557 * Domain and Range Errors::     How overflow conditions and the like
558                                          are reported.
559 * Not a Number::                Making NANs and testing for NANs.
560 * Trig Functions::     Sine, cosine, and tangent.
561 * Inverse Trig Functions::  Arc sine, arc cosine, and arc tangent.
562 * Exponents and Logarithms::  Also includes square root.
563 * Hyperbolic Functions::        Hyperbolic sine and friends.
564 * Pseudo-Random Numbers::       Functions for generating pseudo-random
565                                          numbers.
566 * Absolute Value::              Absolute value functions.
567
568 Pseudo-Random Numbers
569
570 * ANSI C Random Number Functions::  @code{rand} and friends.
571 * BSD Random Number Functions::  @code{random} and friends.
572
573 Low-Level Arithmetic Functions
574
575 * Normalization Functions::     Hacks for radix-2 representations.
576 * Rounding and Remainders::  Determinining the integer and
577                                          fractional parts of a float.
578 * Integer Division::            Functions for performing integer
579                                          division.
580 * Parsing of Numbers::          Functions for ``reading'' numbers
581                                          from strings.
582 * Predicates on Floats::        Some miscellaneous test functions.
583
584 Parsing of Numbers
585
586 * Parsing of Integers::         Functions for conversion of integer values.
587 * Parsing of Floats::           Functions for conversion of floating-point
588                                  values.
589
590 Date and Time
591
592 * Processor Time::              Measures processor time used by a program.
593 * Calendar Time::               Manipulation of ``real'' dates and times.
594 * Setting an Alarm::            Sending a signal after a specified time.
595 * Sleeping::                    Waiting for a period of time.
596
597 Processor Time
598
599 * Basic CPU Time::              The @code{clock} function.
600 * Detailed CPU Time::           The @code{times} function.
601
602 Calendar Time
603
604 * Simple Calendar Time::        Facilities for manipulating calendar time.
605 * High-Resolution Calendar::    A time representation with greater precision.
606 * Broken-down Time::            Facilities for manipulating local time.
607 * Formatting Date and Time::    Converting times to strings.
608 * TZ Variable::                 How users specify the time zone.
609 * Time Zone Functions::         Functions to examine or specify the time zone.
610 * Time Functions Example::      An example program showing use of some of
611                                  the time functions.
612
613 Signal Handling
614
615 * Concepts of Signals::         Introduction to the signal facilities.
616 * Standard Signals::            Particular kinds of signals with standard
617                              names and meanings.
618 * Signal Actions::              Specifying what happens when a particular signal
619                              is delivered.
620 * Defining Handlers::           How to write a signal handler function.
621 * Generating Signals::          How to send a signal to a process.
622 * Blocking Signals::            Making the system hold signals temporarily.
623 * Waiting for a Signal::        Suspending your program until a signal arrives.
624 * BSD Signal Handling::         Additional functions for backward
625                              compatibility with BSD.
626 * BSD Handler::                 BSD Function to Establish a Handler
627
628 Basic Concepts of Signals
629
630 * Kinds of Signals::            Some examples of what can cause a signal.
631 * Signal Generation::           Concepts of why and how signals occur.
632 * Delivery of Signal::          Concepts of what a signal does to the process.
633
634 Standard Signals
635
636 * Program Error Signals::       Used to report serious program errors.
637 * Termination Signals::         Used to interrupt and/or terminate the program.
638 * Alarm Signals::               Used to indicate expiration of timers.
639 * Asynchronous I/O Signals::    Used to indicate input is available.
640 * Job Control Signals::         Signals used to support job control.
641 * Miscellaneous Signals::       Miscellaneous Signals
642 * Other Signals::               Implementations can support other signals.
643 * Signal Messages::             Printing a message describing a signal.
644
645 Specifying Signal Actions
646
647 * Basic Signal Handling::       The simple @code{signal} function.
648 * Advanced Signal Handling::    The more powerful @code{sigaction} function.
649 * Signal and Sigaction::        How those two functions interact.
650 * Sigaction Function Example::  An example of using the sigaction function.
651 * Flags for Sigaction::         Specifying options for signal handling.
652 * Initial Signal Actions::      How programs inherit signal actions.
653
654 Defining Signal Handlers
655
656 * Handler Returns::             
657 * Termination in Handler::      
658 * Longjmp in Handler::          
659 * Signals in Succession::       
660 * Nonreentrancy::               
661 * Atomic Data Access::          
662
663 Generating Signals
664
665 * Signaling Yourself::          Signaling Yourself
666 * Signaling Another Process::   Send a signal to another process.
667 * Permission for kill::         Permission for using @code{kill}
668 * Kill Example::                Using @code{kill} for Communication
669
670 Blocking Signals
671
672 * Why Block::                   The purpose of blocking signals.
673 * Signal Sets::                 How to specify which signals to block.
674 * Process Signal Mask::         Blocking delivery of signals to your
675                                          process during normal execution.
676 * Testing for Delivery::        Blocking to Test for Delivery of a Signal
677 * Blocking for Handler::        Blocking additional signals while a
678                                          handler is being run.
679 * Checking for Pending Signals::  Checking for Pending Signals
680 * Remembering a Signal::        How you can get almost the same effect
681                                  as blocking a signal, by handling it
682                                  and setting a flag to be tested later.
683
684 Waiting for a Signal
685
686 * Using Pause::                 The simple way, using @code{pause}.
687 * Pause Problems::              Why the simple way is often not very good.
688 * Sigsuspend::                  Reliably waiting for a specific signal.
689
690 BSD Signal Handling
691
692 * POSIX vs BSD::                Overview comparing BSD and POSIX signal functions.
693
694 BSD Function to Establish a Handler
695
696 * Blocking in BSD::             BSD Functions for Blocking Signals 
697 * Signal Stack::                Using a Separate Signal Stack
698
699 Process Startup and Termination
700
701 * Program Arguments::           Parsing your program's command-line arguments.
702 * Environment Variables::       How to access parameters inherited from
703                                  a parent process.
704 * Program Termination::         How to cause a process to terminate and
705                                  return status information to its parent.
706
707 Program Arguments
708
709 * Argument Syntax::             By convention, options start with a hyphen.
710 * Parsing Options::             The @code{getopt} function.
711 * Example of Getopt::           An example of parsing options with @code{getopt}.
712 * Long Options::                GNU utilities should accept long-named options.
713                                    Here is how to do that.
714 * Long Option Example::         An example of using @code{getopt_long}.
715
716 Environment Variables
717
718 * Environment Access::          How to get and set the values of
719                                    environment variables.
720 * Standard Environment::        These environment variables have
721                                    standard interpretations.
722
723 Program Termination
724
725 * Normal Termination::          If a program calls @code{exit}, a
726                                  process terminates normally.
727 * Exit Status::                 The @code{exit status} provides information 
728                                  about why the process terminated. 
729 * Cleanups on Exit::            A process can run its own cleanup
730                                  functions upon normal termination. 
731 * Aborting a Program::          The @code{abort} function causes
732                                  abnormal program termination. 
733 * Termination Internals::       What happens when a process terminates.
734
735
736 Child Processes
737
738 * Running a Command::           The easy way to run another program.
739 * Process Creation Concepts::   An overview of the hard way to do it.
740 * Process Identification::      How to get the process ID of a process.
741 * Creating a Process::          How to fork a child process.
742 * Executing a File::            How to make a child execute another program.
743 * Process Completion::          How to tell when a child process has completed.
744 * Process Completion Status::   How to interpret the status value 
745                                    returned from a child process.
746 * BSD wait Functions::          More functions, for backward compatibility.
747 * Process Creation Example::    A complete example program.
748
749 Job Control
750
751 * Concepts of Job Control ::    Concepts of Job Control
752 * Job Control is Optional::     Not all POSIX systems support job control.
753 * Controlling Terminal::        How a process gets its controlling terminal.
754 * Access to the Terminal::      How processes share the controlling terminal.
755 * Orphaned Process Groups::     Jobs left after the user logs out.
756 * Implementing a Shell::        What a shell must do to implement job control.
757 * Functions for Job Control::   Functions to control process groups.
758
759 Implementing a Job Control Shell
760
761 * Data Structures::             Introduction to the sample shell.
762 * Initializing the Shell::      What the shell must do to take
763                                  responsibility for job control.
764 * Launching Jobs::              Creating jobs to execute commands.
765 * Foreground and Background::   Putting a job in foreground of background.
766 * Stopped and Terminated Jobs::  Reporting job status.
767 * Continuing Stopped Jobs::     How to continue a stopped job in
768                                  the foreground or background.
769 * Missing Pieces::          Other parts of the shell.
770
771 Functions for Job Control
772
773 * Identifying the Terminal::    Determining the controlling terminal's name.
774 * Process Group Functions::     Functions for manipulating process groups.
775 * Terminal Access Functions::   Functions for controlling terminal access.
776
777 Users and Groups
778
779 * User and Group IDs::          Each user has a unique numeric ID; likewise for groups.
780 * Process Persona::             The user IDs and group IDs of a process.
781 * Why Change Persona::          Why a program might need to change
782                          its user and/or group IDs.
783 * How Change Persona::          Restrictions on changing the user and group IDs.
784 * Reading Persona::             How to examine the process's user and group IDs.
785 * Setting User ID::             
786 * Setting Groups::              
787 * Enable/Disable Setuid::       
788 * Setuid Program Example::      Setuid Program Example
789 * Tips for Setuid::             
790 * Who Logged In::               Getting the name of the user who logged in,
791                          or of the real user ID of the current process.
792
793 * User Database::               Functions and data structures for
794                          accessing the user database.
795 * Group Database::              Functions and data structures for
796                          accessing the group database.
797 * Database Example::            Example program showing use of database
798                          inquiry functions.
799
800 User Database
801
802 * User Data Structure::         
803 * Lookup User::                 
804 * Scanning All Users::          Scanning the List of All Users
805 * Writing a User Entry::        
806
807 Group Database
808
809 * Group Data Structure::        
810 * Lookup Group::                
811 * Scanning All Groups::         Scanning the List of All Groups
812
813 System Information
814
815 * Host Identification::         Determining the name of the machine.
816 * Hardware/Software Type ID::   Determining the hardware type and
817                                    operating system type.
818
819 System Configuration Limits
820
821 * General Limits::              Constants and functions that describe
822                                    various process-related limits that have
823                                    one uniform value for any given machine.
824 * System Options::              Optional POSIX features.
825 * Version Supported::           Version numbers of POSIX.1 and POSIX.2.
826 * Sysconf::                     Getting specific configuration values
827                                    of general limits and system options.
828 * Minimums::                    Minimum values for general limits.
829    
830 * Limits for Files::            Size limitations that pertain to individual files.
831                                    These can vary between file systems
832                                    or even from file to file.
833 * Options for Files::           Optional features that some files may support.
834 * File Minimums::               Minimum values for file limits.
835 * Pathconf::                    Getting the limit values for a particular file.
836    
837 * Utility Limits::              Capacity limits of some POSIX.2 utility programs.
838 * Utility Minimums::            Minimum allowable values of those limits.
839    
840 * String Parameters::           Getting the default search path.
841
842 Library Facilities that are Part of the C Language
843
844 * Consistency Checking::        Using @code{assert} to abort
845                                 if something ``impossible'' happens.
846 * Variadic Functions::          Defining functions with varying numbers of args.
847 * Null Pointer Constant::       The macro @code{NULL}.
848 * Important Data Types::        Data types for object sizes.
849 * Data Type Measurements::      Parameters of data type representations.
850
851 Variadic Functions
852
853 * Why Variadic::                Reasons for making functions take variable arguments.
854 * How Variadic::                How to define and call variadic functions.
855 * Argument Macros::             Detailed specification of the macros
856                                    for accessing variable arguments.
857 * Variadic Example::            A complete example.
858
859 How Variadic Functions are Defined and Used
860
861 * Variadic Prototypes::         How to make a prototype for a function
862                                    with variable arguments.
863 * Receiving Arguments::         Steps you must follow to access the
864                                    optional argument values.
865 * How Many Arguments::          How to decide whether there are more arguments.
866 * Calling Variadics::           Things you need to know about calling
867                                    variable arguments functions.
868
869 Data Type Measurements
870
871 * Width of Type::               How many bits does an integer type hold?
872 * Range of Type::               What are the largest and smallest values
873                                   that an integer type can hold?
874 * Floating Type Macros::        Parameters that measure the floating point types.
875 * Structure Measurement::       Getting measurements on structure types.
876
877 Floating Type Macros
878
879 * Floating Point Concepts::     Definitions of terminology.
880 * Floating Point Parameters::   Dimensions, limits of floating point types.
881 * IEEE Floating Point::         How one common representation is described.
882
883 Library Maintenance
884
885 * Installation::                How to configure, compile and install
886                                          the GNU C library.
887 * Reporting Bugs::              How to report bugs (if you want to
888                                          get them fixed) and other troubles
889                                          you may have with the GNU C library.
890 * Porting::                     How to port the GNU C library to
891                                          a new machine or operating system.
892 @c * Traditional C Compatibility::  Using the GNU C library with non-ANSI
893 @c                                          C compilers.
894 * Contributors::                Contributors to the GNU C Library.
895
896 Porting the GNU C Library
897
898 * Hierarchy Conventions::       How the @file{sysdeps} hierarchy is
899                                  layed out.
900 * Porting to Unix::             Porting the library to an average
901                                  Unix-like system.
902 @end menu
903
904
905
906 @include intro.texinfo
907 @include errno.texinfo
908 @include memory.texinfo
909 @include ctype.texinfo
910 @include string.texinfo
911 @include mbyte.texinfo
912 @include locale.texinfo
913 @include search.texinfo
914 @include pattern.texi
915 @include io.texinfo
916 @include stdio.texinfo
917 @include llio.texinfo
918 @include filesys.texinfo
919 @include pipe.texinfo
920 @include socket.texinfo
921 @include terminal.texinfo
922 @include math.texinfo
923 @include arith.texinfo
924 @include time.texinfo
925 @include setjmp.texinfo
926 @include signal.texinfo
927 @include startup.texinfo
928 @include child.texinfo
929 @include job.texinfo
930 @include users.texinfo
931 @include sysinfo.texinfo
932 @include conf.texinfo
933 @include lang.texinfo
934
935 @include header.texinfo
936 @include maint.texinfo
937
938 @c @set lgpl-appendix
939 @c node Copying, Concept Index, Maintenance, Top
940 @c @include lgpl.texinfo
941 @include copying.texinfo
942
943 @include index-cp.texi
944
945 @include index-tp.texi
946    
947 @include index-fn.texi
948
949 @include index-vr.texi
950
951 @include index-pg.texi
952
953 @shortcontents
954 @contents
955 @bye