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