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