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