Regenerated.
[kopensolaris-gnu/glibc.git] / manual / top-menu.texi
1 @menu
2 * Introduction::                 Purpose of the GNU C Library.
3 * Error Reporting::              How library functions report errors.
4 * Memory Allocation::            Allocating memory dynamically and
5                                    manipulating it via pointers.
6 * Character Handling::           Character testing and conversion functions.
7 * String and Array Utilities::   Utilities for copying and comparing strings
8                                    and arrays.
9 * Extended Characters::          Support for extended character sets.
10 * Locales::                      The country and language can affect the
11                                    behavior of library functions.
12 * Message Translation::          How to make the program speak the user's
13                                    language.
14 * Searching and Sorting::        General searching and sorting functions.
15 * Pattern Matching::             Matching shell ``globs'' and regular
16                                    expressions.
17 * I/O Overview::                 Introduction to the I/O facilities.
18 * I/O on Streams::               Hign-level, portable I/O facilities.
19 * Low-Level I/O::                Low-level, less portable I/O.
20 * File System Interface::        Functions for manipulating files.
21 * Pipes and FIFOs::              A simple interprocess communication
22                                    mechanism.
23 * Sockets::                      A more complicated IPC mechanism, with
24                                    networking support.
25 * Low-Level Terminal Interface:: How to change the characteristics of a
26                                    terminal device.
27 * Mathematics::                  Math functions, useful constants, random
28                                    numbers.
29 * Arithmetic::                   Low level arithmetic functions.
30 * Date and Time::                Functions for getting the date and time and
31                                    formatting them nicely.
32 * Non-Local Exits::              Jumping out of nested function calls.
33 * Signal Handling::              How to send, block, and handle signals.
34 * Process Startup::              Writing the beginning and end of your
35                                    program.
36 * Processes::                    How to create processes and run other
37                                    programs.
38 * Job Control::                  All about process groups and sessions.
39 * Name Service Switch::          Accessing system databases.
40 * Users and Groups::             How users are identified and classified.
41 * System Information::           Getting information about the hardware and
42                                    operating system.
43 * System Configuration::         Parameters describing operating system
44                                    limits.
45
46 Add-ons
47
48 * POSIX Threads::                The standard threads library.
49
50 Appendices
51
52 * Language Features::            C language features provided by the library.
53 * Library Summary::              A summary showing the syntax, header file,
54                                    and derivation of each library feature.
55 * Installation::                 How to install the GNU C library.
56 * Maintenance::                  How to enhance and port the GNU C Library.
57 * Contributors::                 Who wrote what parts of the GNU C library.
58 * Copying::                      The GNU Library General Public License says
59                                   how you can copy and share the GNU C Library.
60
61 Indices
62
63 * Concept Index::                Index of concepts and names.
64 * Type Index::                   Index of types and type qualifiers.
65 * Function Index::               Index of functions and function-like macros.
66 * Variable Index::               Index of variables and variable-like macros.
67 * File Index::                   Index of programs and files.
68
69  --- The Detailed Node Listing ---
70
71 Introduction
72
73 * Getting Started::             What this manual is for and how to use it.
74 * Standards and Portability::   Standards and sources upon which the GNU
75                                  C library is based.
76 * Using the Library::           Some practical uses for the library.
77 * Roadmap to the Manual::       Overview of the remaining chapters in
78                                  this manual.
79
80 Standards and Portability
81
82 * ISO C::                       The international standard for the C
83                                  programming language.
84 * POSIX::                       The ISO/IEC 9945 (aka IEEE 1003) standards
85                                  for operating systems.
86 * Berkeley Unix::               BSD and SunOS.
87 * SVID::                        The System V Interface Description.
88 * XPG::                         The X/Open Portability Guide.
89
90 Using the Library
91
92 * Header Files::                How to include the header files in your
93                                  programs.
94 * Macro Definitions::           Some functions in the library may really
95                                  be implemented as macros.
96 * Reserved Names::              The C standard reserves some names for
97                                  the library, and some for users.
98 * Feature Test Macros::         How to control what names are defined.
99
100 Error Reporting
101
102 * Checking for Errors::         How errors are reported by library functions.
103 * Error Codes::                 Error code macros; all of these expand
104                                  into integer constant values.
105 * Error Messages::              Mapping error codes onto error messages.
106
107 Memory Allocation
108
109 * Memory Concepts::             An introduction to concepts and terminology.
110 * Dynamic Allocation and C::    How to get different kinds of allocation in C.
111 * Unconstrained Allocation::    The @code{malloc} facility allows fully general
112                                  dynamic allocation.
113 * Allocation Debugging::        Finding memory leaks and not freed memory.
114 * Obstacks::                    Obstacks are less general than malloc
115                                  but more efficient and convenient.
116 * Variable Size Automatic::     Allocation of variable-sized blocks
117                                  of automatic storage that are freed when the
118                                  calling function returns.
119 * Relocating Allocator::        Waste less memory, if you can tolerate
120                                  automatic relocation of the blocks you get.
121
122 Unconstrained Allocation
123
124 * Basic Allocation::            Simple use of @code{malloc}.
125 * Malloc Examples::             Examples of @code{malloc}.  @code{xmalloc}.
126 * Freeing after Malloc::        Use @code{free} to free a block you
127                                  got with @code{malloc}.
128 * Changing Block Size::         Use @code{realloc} to make a block
129                                  bigger or smaller.
130 * Allocating Cleared Space::    Use @code{calloc} to allocate a
131                                  block and clear it.
132 * Efficiency and Malloc::       Efficiency considerations in use of
133                                  these functions.
134 * Aligned Memory Blocks::       Allocating specially aligned memory:
135                                  @code{memalign} and @code{valloc}.
136 * Malloc Tunable Parameters::   Use @code{mallopt} to adjust allocation
137                                  parameters.
138 * Heap Consistency Checking::   Automatic checking for errors.
139 * Hooks for Malloc::            You can use these hooks for debugging
140                                  programs that use @code{malloc}.
141 * Statistics of Malloc::        Getting information about how much
142                                  memory your program is using.
143 * Summary of Malloc::           Summary of @code{malloc} and related functions.
144
145 Allocation Debugging
146
147 * Tracing malloc::               How to install the tracing functionality.
148 * Using the Memory Debugger::    Example programs excerpts.
149 * Tips for the Memory Debugger:: Some more or less clever ideas.
150 * Interpreting the traces::      What do all these lines mean?
151
152 Obstacks
153
154 * Creating Obstacks::           How to declare an obstack in your program.
155 * Preparing for Obstacks::      Preparations needed before you can
156                                  use obstacks.
157 * Allocation in an Obstack::    Allocating objects in an obstack.
158 * Freeing Obstack Objects::     Freeing objects in an obstack.
159 * Obstack Functions::           The obstack functions are both
160                                  functions and macros.
161 * Growing Objects::             Making an object bigger by stages.
162 * Extra Fast Growing::          Extra-high-efficiency (though more
163                                  complicated) growing objects.
164 * Status of an Obstack::        Inquiries about the status of an obstack.
165 * Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
166 * Obstack Chunks::              How obstacks obtain and release chunks;
167                                  efficiency considerations.
168 * Summary of Obstacks::
169
170 Variable Size Automatic
171
172 * Alloca Example::              Example of using @code{alloca}.
173 * Advantages of Alloca::        Reasons to use @code{alloca}.
174 * Disadvantages of Alloca::     Reasons to avoid @code{alloca}.
175 * GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
176                                  method of allocating dynamically and
177                                  freeing automatically.
178
179 Relocating Allocator
180
181 * Relocator Concepts::          How to understand relocating allocation.
182 * Using Relocator::             Functions for relocating allocation.
183
184 Character Handling
185
186 * Classification of Characters::   Testing whether characters are
187                                     letters, digits, punctuation, etc.
188
189 * Case Conversion::                Case mapping, and the like.
190
191 String and Array Utilities
192
193 * Representation of Strings::   Introduction to basic concepts.
194 * String/Array Conventions::    Whether to use a string function or an
195                                  arbitrary array function.
196 * String Length::               Determining the length of a string.
197 * Copying and Concatenation::   Functions to copy the contents of strings
198                                  and arrays.
199 * String/Array Comparison::     Functions for byte-wise and character-wise
200                                  comparison.
201 * Collation Functions::         Functions for collating strings.
202 * Search Functions::            Searching for a specific element or substring.
203 * Finding Tokens in a String::  Splitting a string into tokens by looking
204                                  for delimiters.
205 * Encode Binary Data::          Encoding and Decoding of Binary Data.
206 * Argz and Envz Vectors::       Null-separated string vectors.
207
208 Argz and Envz Vectors
209
210 * Argz Functions::              Operations on argz vectors.
211 * Envz Functions::              Additional operations on environment vectors.
212
213 Extended Characters
214
215 * Extended Char Intro::         Multibyte codes versus wide characters.
216 * Locales and Extended Chars::  The locale selects the character codes.
217 * Multibyte Char Intro::        How multibyte codes are represented.
218 * Wide Char Intro::             How wide characters are represented.
219 * Wide String Conversion::      Converting wide strings to multibyte code
220                                  and vice versa.
221 * Length of Char::              how many bytes make up one multibyte char.
222 * Converting One Char::         Converting a string character by character.
223 * Example of Conversion::       Example showing why converting
224                                  one character at a time may be useful.
225 * Shift State::                 Multibyte codes with "shift characters".
226
227 Locales
228
229 * Effects of Locale::           Actions affected by the choice of
230                                  locale.
231 * Choosing Locale::             How the user specifies a locale.
232 * Locale Categories::           Different purposes for which you can
233                                  select a locale.
234 * Setting the Locale::          How a program specifies the locale
235                                  with library functions.
236 * Standard Locales::            Locale names available on all systems.
237 * Numeric Formatting::          How to format numbers according to the
238                                  chosen locale.
239
240 Numeric Formatting
241
242 * General Numeric::             Parameters for formatting numbers and
243                                  currency amounts.
244 * Currency Symbol::             How to print the symbol that identifies an
245                                  amount of money (e.g. @samp{$}).
246 * Sign of Money Amount::        How to print the (positive or negative) sign
247                                  for a monetary amount, if one exists.
248
249 Message Translation
250
251 * Message catalogs a la X/Open::  The @code{catgets} family of functions.
252 * The Uniforum approach::         The @code{gettext} family of functions.
253
254 Message catalogs a la X/Open
255
256 * The catgets Functions::      The @code{catgets} function family.
257 * The message catalog files::  Format of the message catalog files.
258 * The gencat program::         How to generate message catalogs files which
259                                 can be used by the functions.
260 * Common Usage::               How to use the @code{catgets} interface.
261
262 The Uniforum approach
263
264 * Message catalogs with gettext::  The @code{gettext} family of functions.
265 * Helper programs for gettext::    Programs to handle message catalogs
266                                     for @code{gettext}.
267
268 Message catalogs with gettext
269
270 * Translation with gettext::    What has to be done to translate a message.
271 * Locating gettext catalog::    How to determine which catalog to be used.
272 * Using gettextized software::  The possibilities of the user to influence
273                                  the way @code{gettext} works.
274
275 Searching and Sorting
276
277 * Comparison Functions::        Defining how to compare two objects.
278                                  Since the sort and search facilities
279                                  are general, you have to specify the
280                                  ordering.
281 * Array Search Function::       The @code{bsearch} function.
282 * Array Sort Function::         The @code{qsort} function.
283 * Search/Sort Example::         An example program.
284 * Hash Search Function::        The @code{hsearch} function.
285 * Tree Search Function::        The @code{tsearch} function.
286
287 Pattern Matching
288
289 * Wildcard Matching::    Matching a wildcard pattern against a single string.
290 * Globbing::             Finding the files that match a wildcard pattern.
291 * Regular Expressions::  Matching regular expressions against strings.
292 * Word Expansion::       Expanding shell variables, nested commands,
293                             arithmetic, and wildcards.
294                             This is what the shell does with shell commands.
295
296 Globbing
297
298 * Calling Glob::             Basic use of @code{glob}.
299 * Flags for Globbing::       Flags that enable various options in @code{glob}.
300 * More Flags for Globbing::  GNU specific extensions to @code{glob}.
301
302 Regular Expressions
303
304 * POSIX Regexp Compilation::    Using @code{regcomp} to prepare to match.
305 * Flags for POSIX Regexps::     Syntax variations for @code{regcomp}.
306 * Matching POSIX Regexps::      Using @code{regexec} to match the compiled
307                                    pattern that you get from @code{regcomp}.
308 * Regexp Subexpressions::       Finding which parts of the string were matched.
309 * Subexpression Complications:: Find points of which parts were matched.
310 * Regexp Cleanup::              Freeing storage; reporting errors.
311
312 Word Expansion
313
314 * Expansion Stages::    What word expansion does to a string.
315 * Calling Wordexp::     How to call @code{wordexp}.
316 * Flags for Wordexp::   Options you can enable in @code{wordexp}.
317 * Wordexp Example::     A sample program that does word expansion.
318
319 I/O Overview
320
321 * I/O Concepts::       Some basic information and terminology.
322 * File Names::         How to refer to a file.
323
324 I/O Concepts
325
326 * Streams and File Descriptors::    The GNU Library provides two ways
327                                      to access the contents of files.
328 * File Position::                   The number of bytes from the
329                                      beginning of the file.
330
331 File Names
332
333 * Directories::                 Directories contain entries for files.
334 * File Name Resolution::        A file name specifies how to look up a file.
335 * File Name Errors::            Error conditions relating to file names.
336 * File Name Portability::       File name portability and syntax issues.
337
338 I/O on Streams
339
340 * Streams::                     About the data type representing a stream.
341 * Standard Streams::            Streams to the standard input and output
342                                  devices are created for you.
343 * Opening Streams::             How to create a stream to talk to a file.
344 * Closing Streams::             Close a stream when you are finished with it.
345 * Simple Output::               Unformatted output by characters and lines.
346 * Character Input::             Unformatted input by characters and words.
347 * Line Input::                  Reading a line or a record from a stream.
348 * Unreading::                   Peeking ahead/pushing back input just read.
349 * Block Input/Output::          Input and output operations on blocks of data.
350 * Formatted Output::            @code{printf} and related functions.
351 * Customizing Printf::          You can define new conversion specifiers for
352                                  @code{printf} and friends.
353 * Formatted Input::             @code{scanf} and related functions.
354 * EOF and Errors::              How you can tell if an I/O error happens.
355 * Binary Streams::              Some systems distinguish between text files
356                                  and binary files.
357 * File Positioning::            About random-access streams.
358 * Portable Positioning::        Random access on peculiar ISO C systems.
359 * Stream Buffering::            How to control buffering of streams.
360 * Other Kinds of Streams::      Streams that do not necessarily correspond
361                                  to an open file.
362 * Formatted Messages::          Print strictly formatted messages.
363
364 Unreading
365
366 * Unreading Idea::              An explanation of unreading with pictures.
367 * How Unread::                  How to call @code{ungetc} to do unreading.
368
369 Formatted Output
370
371 * Formatted Output Basics::     Some examples to get you started.
372 * Output Conversion Syntax::    General syntax of conversion
373                                  specifications.
374 * Table of Output Conversions:: Summary of output conversions and
375                                  what they do.
376 * Integer Conversions::         Details about formatting of integers.
377 * Floating-Point Conversions::  Details about formatting of
378                                  floating-point numbers.
379 * Other Output Conversions::    Details about formatting of strings,
380                                  characters, pointers, and the like.
381 * Formatted Output Functions::  Descriptions of the actual functions.
382 * Dynamic Output::              Functions that allocate memory for the output.
383 * Variable Arguments Output::   @code{vprintf} and friends.
384 * Parsing a Template String::   What kinds of args does a given template
385                                  call for?
386 * Example of Parsing::          Sample program using @code{parse_printf_format}.
387
388 Customizing Printf
389
390 * Registering New Conversions::         Using @code{register_printf_function}
391                                          to register a new output conversion.
392 * Conversion Specifier Options::        The handler must be able to get
393                                          the options specified in the
394                                          template when it is called.
395 * Defining the Output Handler::         Defining the handler and arginfo
396                                          functions that are passed as arguments
397                                          to @code{register_printf_function}.
398 * Printf Extension Example::            How to define a @code{printf}
399                                          handler function.
400 * Predefined Printf Handlers::          Predefined @code{printf} handlers.
401
402 Formatted Input
403
404 * Formatted Input Basics::      Some basics to get you started.
405 * Input Conversion Syntax::     Syntax of conversion specifications.
406 * Table of Input Conversions::  Summary of input conversions and what they do.
407 * Numeric Input Conversions::   Details of conversions for reading numbers.
408 * String Input Conversions::    Details of conversions for reading strings.
409 * Dynamic String Input::        String conversions that @code{malloc} the buffer.
410 * Other Input Conversions::     Details of miscellaneous other conversions.
411 * Formatted Input Functions::   Descriptions of the actual functions.
412 * Variable Arguments Input::    @code{vscanf} and friends.
413
414 Stream Buffering
415
416 * Buffering Concepts::          Terminology is defined here.
417 * Flushing Buffers::            How to ensure that output buffers are flushed.
418 * Controlling Buffering::       How to specify what kind of buffering to use.
419
420 Other Kinds of Streams
421
422 * String Streams::              Streams that get data from or put data in
423                                  a string or memory buffer.
424 * Obstack Streams::             Streams that store data in an obstack.
425 * Custom Streams::              Defining your own streams with an arbitrary
426                                  input data source and/or output data sink.
427
428 Custom Streams
429
430 * Streams and Cookies::         The @dfn{cookie} records where to fetch or
431                                  store data that is read or written.
432 * Hook Functions::              How you should define the four @dfn{hook
433                                  functions} that a custom stream needs.
434
435 Formatted Messages
436
437 * Printing Formatted Messages::   The @code{fmtmsg} function.
438 * Adding Severity Classes::       Add more severity classes.
439 * Example::                       How to use @code{fmtmsg} and @code{addseverity}.
440
441 Low-Level I/O
442
443 * Opening and Closing Files::           How to open and close file
444                                          descriptors.
445 * Truncating Files::                    Change the size of a file.
446 * I/O Primitives::                      Reading and writing data.
447 * File Position Primitive::             Setting a descriptor's file
448                                          position.
449 * Descriptors and Streams::             Converting descriptor to stream
450                                          or vice-versa.
451 * Stream/Descriptor Precautions::       Precautions needed if you use both
452                                          descriptors and streams.
453 * Scatter-Gather::                      Fast I/O to discontinous buffers.
454 * Memory-mapped I/O::                   Using files like memory.
455 * Waiting for I/O::                     How to check for input or output
456                                          on multiple file descriptors.
457 * Synchronizing I/O::                   Making sure all I/O actions completed.
458 * Asynchronous I/O::                    Perform I/O in parallel.
459 * Control Operations::                  Various other operations on file
460                                          descriptors.
461 * Duplicating Descriptors::             Fcntl commands for duplicating
462                                          file descriptors.
463 * Descriptor Flags::                    Fcntl commands for manipulating
464                                          flags associated with file
465                                          descriptors.
466 * File Status Flags::                   Fcntl commands for manipulating
467                                          flags associated with open files.
468 * File Locks::                          Fcntl commands for implementing
469                                          file locking.
470 * Interrupt Input::                     Getting an asynchronous signal when
471                                          input arrives.
472 * IOCTLs::                              Generic I/O Control operations.
473
474 Stream/Descriptor Precautions
475
476 * Linked Channels::        Dealing with channels sharing a file position.
477 * Independent Channels::   Dealing with separately opened, unlinked channels.
478 * Cleaning Streams::       Cleaning a stream makes it safe to use
479                             another channel.
480
481 Asynchronous I/O
482
483 * Asynchronous Reads/Writes::    Asynchronous Read and Write Operations.
484 * Status of AIO Operations::     Getting the Status of AIO Operations.
485 * Synchronizing AIO Operations:: Getting into a consistent state.
486 * Cancel AIO Operations::        Cancelation of AIO Operations.
487 * Configuration of AIO::         How to optimize the AIO implementation.
488
489 File Status Flags
490
491 * Access Modes::                Whether the descriptor can read or write.
492 * Open-time Flags::             Details of @code{open}.
493 * Operating Modes::             Special modes to control I/O operations.
494 * Getting File Status Flags::   Fetching and changing these flags.
495
496 File System Interface
497
498 * Working Directory::           This is used to resolve relative
499                                  file names.
500 * Accessing Directories::       Finding out what files a directory
501                                  contains.
502 * Working on Directory Trees::  Apply actions to all files or a selectable
503                                  subset of a directory hierarchy.
504 * Hard Links::                  Adding alternate names to a file.
505 * Symbolic Links::              A file that ``points to'' a file name.
506 * Deleting Files::              How to delete a file, and what that means.
507 * Renaming Files::              Changing a file's name.
508 * Creating Directories::        A system call just for creating a directory.
509 * File Attributes::             Attributes of individual files.
510 * Making Special Files::        How to create special files.
511 * Temporary Files::             Naming and creating temporary files.
512
513 Accessing Directories
514
515 * Directory Entries::           Format of one directory entry.
516 * Opening a Directory::         How to open a directory stream.
517 * Reading/Closing Directory::   How to read directory entries from the stream.
518 * Simple Directory Lister::     A very simple directory listing program.
519 * Random Access Directory::     Rereading part of the directory
520                                  already read with the same stream.
521 * Scanning Directory Content::  Get entries for user selected subset of
522                                  contents in given directory.
523 * Simple Directory Lister Mark II::  Revised version of the program.
524
525 File Attributes
526
527 * Attribute Meanings::          The names of the file attributes,
528                                  and what their values mean.
529 * Reading Attributes::          How to read the attributes of a file.
530 * Testing File Type::           Distinguishing ordinary files,
531                                  directories, links...
532 * File Owner::                  How ownership for new files is determined,
533                                  and how to change it.
534 * Permission Bits::             How information about a file's access
535                                  mode is stored.
536 * Access Permission::           How the system decides who can access a file.
537 * Setting Permissions::         How permissions for new files are assigned,
538                                  and how to change them.
539 * Testing File Access::         How to find out if your process can
540                                  access a file.
541 * File Times::                  About the time attributes of a file.
542
543 Pipes and FIFOs
544
545 * Creating a Pipe::             Making a pipe with the @code{pipe} function.
546 * Pipe to a Subprocess::        Using a pipe to communicate with a
547                                  child process.
548 * FIFO Special Files::          Making a FIFO special file.
549 * Pipe Atomicity::              When pipe (or FIFO) I/O is atomic.
550
551 Sockets
552
553 * Socket Concepts::     Basic concepts you need to know about.
554 * Communication Styles::Stream communication, datagrams, and other styles.
555 * Socket Addresses::    How socket names (``addresses'') work.
556 * Interface Naming::    Identifying specific network interfaces.
557 * Local Namespace::     Details about the local namespace.
558 * Internet Namespace::  Details about the Internet namespace.
559 * Misc Namespaces::     Other namespaces not documented fully here.
560 * Open/Close Sockets::  Creating sockets and destroying them.
561 * Connections::         Operations on sockets with connection state.
562 * Datagrams::           Operations on datagram sockets.
563 * Inetd::               Inetd is a daemon that starts servers on request.
564                            The most convenient way to write a server
565                            is to make it work with Inetd.
566 * Socket Options::      Miscellaneous low-level socket options.
567 * Networks Database::   Accessing the database of network names.
568
569 Socket Addresses
570
571 * Address Formats::             About @code{struct sockaddr}.
572 * Setting Address::             Binding an address to a socket.
573 * Reading Address::             Reading the address of a socket.
574
575 Local Namespace
576
577 * Concepts: Local Namespace Concepts. What you need to understand.
578 * Details: Local Namespace Details.   Address format, symbolic names, etc.
579 * Example: Local Socket Example.      Example of creating a socket.
580
581 Internet Namespace
582
583 * Internet Address Formats::    How socket addresses are specified in the
584                                  Internet namespace.
585 * Host Addresses::              All about host addresses of internet host.
586 * Protocols Database::          Referring to protocols by name.
587 * Ports::                       Internet port numbers.
588 * Services Database::           Ports may have symbolic names.
589 * Byte Order::                  Different hosts may use different byte
590                                  ordering conventions; you need to
591                                  canonicalize host address and port number.
592 * Inet Example::                Putting it all together.
593
594 Host Addresses
595
596 * Abstract Host Addresses::     What a host number consists of.
597 * Data type: Host Address Data Type.    Data type for a host number.
598 * Functions: Host Address Functions.    Functions to operate on them.
599 * Names: Host Names.            Translating host names to host numbers.
600
601 Open/Close Sockets
602
603 * Creating a Socket::           How to open a socket.
604 * Closing a Socket::            How to close a socket.
605 * Socket Pairs::                These are created like pipes.
606
607 Connections
608
609 * Connecting::               What the client program must do.
610 * Listening::                How a server program waits for requests.
611 * Accepting Connections::    What the server does when it gets a request.
612 * Who is Connected::         Getting the address of the
613                                 other side of a connection.
614 * Transferring Data::        How to send and receive data.
615 * Byte Stream Example::      An example program: a client for communicating
616                               over a byte stream socket in the Internet namespace.
617 * Server Example::           A corresponding server program.
618 * Out-of-Band Data::         This is an advanced feature.
619
620 Transferring Data
621
622 * Sending Data::                Sending data with @code{send}.
623 * Receiving Data::              Reading data with @code{recv}.
624 * Socket Data Options::         Using @code{send} and @code{recv}.
625
626 Datagrams
627
628 * Sending Datagrams::    Sending packets on a datagram socket.
629 * Receiving Datagrams::  Receiving packets on a datagram socket.
630 * Datagram Example::     An example program: packets sent over a
631                            datagram socket in the local namespace.
632 * Example Receiver::     Another program, that receives those packets.
633
634 Inetd
635
636 * Inetd Servers::
637 * Configuring Inetd::
638
639 Socket Options
640
641 * Socket Option Functions::     The basic functions for setting and getting
642                                  socket options.
643 * Socket-Level Options::        Details of the options at the socket level.
644
645 Low-Level Terminal Interface
646
647 * Is It a Terminal::            How to determine if a file is a terminal
648                                  device, and what its name is.
649 * I/O Queues::                  About flow control and typeahead.
650 * Canonical or Not::            Two basic styles of input processing.
651 * Terminal Modes::              How to examine and modify flags controlling
652                                  details of terminal I/O: echoing,
653                                  signals, editing.
654 * Line Control::                Sending break sequences, clearing
655                                  terminal buffers @dots{}
656 * Noncanon Example::            How to read single characters without echo.
657 * Pseudo-Terminals::            How to open a pseudo-terminal.
658
659 Terminal Modes
660
661 * Mode Data Types::             The data type @code{struct termios} and
662                                  related types.
663 * Mode Functions::              Functions to read and set the terminal
664                                  attributes.
665 * Setting Modes::               The right way to set terminal attributes
666                                  reliably.
667 * Input Modes::                 Flags controlling low-level input handling.
668 * Output Modes::                Flags controlling low-level output handling.
669 * Control Modes::               Flags controlling serial port behavior.
670 * Local Modes::                 Flags controlling high-level input handling.
671 * Line Speed::                  How to read and set the terminal line speed.
672 * Special Characters::          Characters that have special effects,
673                                  and how to change them.
674 * Noncanonical Input::          Controlling how long to wait for input.
675
676 Special Characters
677
678 * Editing Characters::          Special characters that terminate lines and
679                                   delete text, and other editing functions.
680 * Signal Characters::           Special characters that send or raise signals
681                                   to or for certain classes of processes.
682 * Start/Stop Characters::       Special characters that suspend or resume
683                                   suspended output.
684 * Other Special::               Other special characters for BSD systems:
685                                   they can discard output, and print status.
686
687 Pseudo-Terminals
688
689 * Allocation::             Allocating a pseudo terminal.
690 * Pseudo-Terminal Pairs::  How to open both sides of a
691                             pseudo-terminal in a single operation.
692
693 Mathematics
694
695 * Mathematical Constants::      Precise numeric values for often-used
696                                  constants.
697 * Trig Functions::              Sine, cosine, tangent, and friends.
698 * Inverse Trig Functions::      Arcsine, arccosine, etc.
699 * Exponents and Logarithms::    Also pow and sqrt.
700 * Hyperbolic Functions::        sinh, cosh, tanh, etc.
701 * Special Functions::           Bessel, gamma, erf.
702 * Pseudo-Random Numbers::       Functions for generating pseudo-random
703                                  numbers.
704 * FP Function Optimizations::   Fast code or small code.
705
706 Pseudo-Random Numbers
707
708 * ISO Random::                  @code{rand} and friends.
709 * BSD Random::                  @code{random} and friends.
710 * SVID Random::                 @code{drand48} and friends.
711
712 Arithmetic
713
714 * Floating Point Numbers::      Basic concepts.  IEEE 754.
715 * Floating Point Classes::      The five kinds of floating-point number.
716 * Floating Point Errors::       When something goes wrong in a calculation.
717 * Rounding::                    Controlling how results are rounded.
718 * Control Functions::           Saving and restoring the FPU's state.
719 * Arithmetic Functions::        Fundamental operations provided by the library.
720 * Complex Numbers::             The types.  Writing complex constants.
721 * Operations on Complex::       Projection, conjugation, decomposition.
722 * Integer Division::            Integer division with guaranteed rounding.
723 * Parsing of Numbers::          Converting strings to numbers.
724 * System V Number Conversion::  An archaic way to convert numbers to strings.
725
726 Floating Point Errors
727
728 * FP Exceptions::               IEEE 754 math exceptions and how to detect them.
729 * Infinity and NaN::            Special values returned by calculations.
730 * Status bit operations::       Checking for exceptions after the fact.
731 * Math Error Reporting::        How the math functions report errors.
732
733 Arithmetic Functions
734
735 * Absolute Value::              Absolute values of integers and floats.
736 * Normalization Functions::     Extracting exponents and putting them back.
737 * Rounding Functions::          Rounding floats to integers.
738 * Remainder Functions::         Remainders on division, precisely defined.
739 * FP Bit Twiddling::            Sign bit adjustment.  Adding epsilon.
740 * FP Comparison Functions::     Comparisons without risk of exceptions.
741 * Misc FP Arithmetic::          Max, min, positive difference, multiply-add.
742
743 Parsing of Numbers
744
745 * Parsing of Integers::         Functions for conversion of integer values.
746 * Parsing of Floats::           Functions for conversion of floating-point
747                                  values.
748
749 Date and Time
750
751 * Processor Time::              Measures processor time used by a program.
752 * Calendar Time::               Manipulation of ``real'' dates and times.
753 * Setting an Alarm::            Sending a signal after a specified time.
754 * Sleeping::                    Waiting for a period of time.
755 * Resource Usage::              Measuring various resources used.
756 * Limits on Resources::         Specifying limits on resource usage.
757 * Priority::                    Reading or setting process run priority.
758
759 Processor Time
760
761 * Basic CPU Time::              The @code{clock} function.
762 * Detailed CPU Time::           The @code{times} function.
763
764 Calendar Time
765
766 * Simple Calendar Time::        Facilities for manipulating calendar time.
767 * High-Resolution Calendar::    A time representation with greater precision.
768 * Broken-down Time::            Facilities for manipulating local time.
769 * Formatting Date and Time::    Converting times to strings.
770 * TZ Variable::                 How users specify the time zone.
771 * Time Zone Functions::         Functions to examine or specify the time zone.
772 * Time Functions Example::      An example program showing use of some of
773                                  the time functions.
774
775 Non-Local Exits
776
777 * Intro: Non-Local Intro.        When and how to use these facilities.
778 * Details: Non-Local Details.   Functions for nonlocal exits.
779 * Non-Local Exits and Signals::  Portability issues.
780
781 Signal Handling
782
783 * Concepts of Signals::         Introduction to the signal facilities.
784 * Standard Signals::            Particular kinds of signals with
785                                  standard names and meanings.
786 * Signal Actions::              Specifying what happens when a
787                                  particular signal is delivered.
788 * Defining Handlers::           How to write a signal handler function.
789 * Interrupted Primitives::      Signal handlers affect use of @code{open},
790                                  @code{read}, @code{write} and other functions.
791 * Generating Signals::          How to send a signal to a process.
792 * Blocking Signals::            Making the system hold signals temporarily.
793 * Waiting for a Signal::        Suspending your program until a signal
794                                  arrives.
795 * Signal Stack::                Using a Separate Signal Stack.
796 * BSD Signal Handling::         Additional functions for backward
797                                  compatibility with BSD.
798
799 Concepts of Signals
800
801 * Kinds of Signals::            Some examples of what can cause a signal.
802 * Signal Generation::           Concepts of why and how signals occur.
803 * Delivery of Signal::          Concepts of what a signal does to the
804                                  process.
805
806 Standard Signals
807
808 * Program Error Signals::       Used to report serious program errors.
809 * Termination Signals::         Used to interrupt and/or terminate the
810                                  program.
811 * Alarm Signals::               Used to indicate expiration of timers.
812 * Asynchronous I/O Signals::    Used to indicate input is available.
813 * Job Control Signals::         Signals used to support job control.
814 * Operation Error Signals::     Used to report operational system errors.
815 * Miscellaneous Signals::       Miscellaneous Signals.
816 * Signal Messages::             Printing a message describing a signal.
817
818 Signal Actions
819
820 * Basic Signal Handling::       The simple @code{signal} function.
821 * Advanced Signal Handling::    The more powerful @code{sigaction} function.
822 * Signal and Sigaction::        How those two functions interact.
823 * Sigaction Function Example::  An example of using the sigaction function.
824 * Flags for Sigaction::         Specifying options for signal handling.
825 * Initial Signal Actions::      How programs inherit signal actions.
826
827 Defining Handlers
828
829 * Handler Returns::             Handlers that return normally, and what
830                                  this means.
831 * Termination in Handler::      How handler functions terminate a program.
832 * Longjmp in Handler::          Nonlocal transfer of control out of a
833                                  signal handler.
834 * Signals in Handler::          What happens when signals arrive while
835                                  the handler is already occupied.
836 * Merged Signals::              When a second signal arrives before the
837                                  first is handled.
838 * Nonreentrancy::               Do not call any functions unless you know they
839                                  are reentrant with respect to signals.
840 * Atomic Data Access::          A single handler can run in the middle of
841                                  reading or writing a single object.
842
843 Atomic Data Access
844
845 * Non-atomic Example::          A program illustrating interrupted access.
846 * Types: Atomic Types.          Data types that guarantee no interruption.
847 * Usage: Atomic Usage.          Proving that interruption is harmless.
848
849 Generating Signals
850
851 * Signaling Yourself::          A process can send a signal to itself.
852 * Signaling Another Process::   Send a signal to another process.
853 * Permission for kill::         Permission for using @code{kill}.
854 * Kill Example::                Using @code{kill} for Communication.
855
856 Blocking Signals
857
858 * Why Block::                           The purpose of blocking signals.
859 * Signal Sets::                         How to specify which signals to
860                                          block.
861 * Process Signal Mask::                 Blocking delivery of signals to your
862                                          process during normal execution.
863 * Testing for Delivery::                Blocking to Test for Delivery of
864                                          a Signal.
865 * Blocking for Handler::                Blocking additional signals while a
866                                          handler is being run.
867 * Checking for Pending Signals::        Checking for Pending Signals
868 * Remembering a Signal::                How you can get almost the same
869                                          effect as blocking a signal, by
870                                          handling it and setting a flag
871                                          to be tested later.
872
873 Waiting for a Signal
874
875 * Using Pause::                 The simple way, using @code{pause}.
876 * Pause Problems::              Why the simple way is often not very good.
877 * Sigsuspend::                  Reliably waiting for a specific signal.
878
879 BSD Signal Handling
880
881 * BSD Handler::                 BSD Function to Establish a Handler.
882 * Blocking in BSD::             BSD Functions for Blocking Signals.
883
884 Process Startup
885
886 * Program Arguments::           Parsing your program's command-line arguments.
887 * Environment Variables::       How to access parameters inherited from
888                                  a parent process.
889 * Program Termination::         How to cause a process to terminate and
890                                  return status information to its parent.
891
892 Program Arguments
893
894 * Argument Syntax::             By convention, options start with a hyphen.
895 * Parsing Program Arguments::   Ways to parse program options and arguments.
896
897 Parsing Program Arguments
898
899 * Getopt::                      Parsing program options using @code{getopt}.
900 * Argp::                        Parsing program options using @code{argp_parse}.
901 * Suboptions::                  Some programs need more detailed options.
902 * Suboptions Example::          This shows how it could be done for @code{mount}.
903
904 Environment Variables
905
906 * Environment Access::          How to get and set the values of
907                                  environment variables.
908 * Standard Environment::        These environment variables have
909                                  standard interpretations.
910
911 Program Termination
912
913 * Normal Termination::          If a program calls @code{exit}, a
914                                  process terminates normally.
915 * Exit Status::                 The @code{exit status} provides information
916                                  about why the process terminated.
917 * Cleanups on Exit::            A process can run its own cleanup
918                                  functions upon normal termination.
919 * Aborting a Program::          The @code{abort} function causes
920                                  abnormal program termination.
921 * Termination Internals::       What happens when a process terminates.
922
923 Processes
924
925 * Running a Command::           The easy way to run another program.
926 * Process Creation Concepts::   An overview of the hard way to do it.
927 * Process Identification::      How to get the process ID of a process.
928 * Creating a Process::          How to fork a child process.
929 * Executing a File::            How to make a process execute another program.
930 * Process Completion::          How to tell when a child process has completed.
931 * Process Completion Status::   How to interpret the status value
932                                  returned from a child process.
933 * BSD Wait Functions::          More functions, for backward compatibility.
934 * Process Creation Example::    A complete example program.
935
936 Job Control
937
938 * Concepts of Job Control::     Jobs can be controlled by a shell.
939 * Job Control is Optional::     Not all POSIX systems support job control.
940 * Controlling Terminal::        How a process gets its controlling terminal.
941 * Access to the Terminal::      How processes share the controlling terminal.
942 * Orphaned Process Groups::     Jobs left after the user logs out.
943 * Implementing a Shell::        What a shell must do to implement job control.
944 * Functions for Job Control::   Functions to control process groups.
945
946 Implementing a Shell
947
948 * Data Structures::             Introduction to the sample shell.
949 * Initializing the Shell::      What the shell must do to take
950                                  responsibility for job control.
951 * Launching Jobs::              Creating jobs to execute commands.
952 * Foreground and Background::   Putting a job in foreground of background.
953 * Stopped and Terminated Jobs::  Reporting job status.
954 * Continuing Stopped Jobs::     How to continue a stopped job in
955                                  the foreground or background.
956 * Missing Pieces::              Other parts of the shell.
957
958 Functions for Job Control
959
960 * Identifying the Terminal::    Determining the controlling terminal's name.
961 * Process Group Functions::     Functions for manipulating process groups.
962 * Terminal Access Functions::   Functions for controlling terminal access.
963
964 Name Service Switch
965
966 * NSS Basics::                  What is this NSS good for.
967 * NSS Configuration File::      Configuring NSS.
968 * NSS Module Internals::        How does it work internally.
969 * Extending NSS::               What to do to add services or databases.
970
971 NSS Configuration File
972
973 * Services in the NSS configuration::  Service names in the NSS configuration.
974 * Actions in the NSS configuration::  React appropriately to the lookup result.
975 * Notes on NSS Configuration File::  Things to take care about while
976                                      configuring NSS.
977
978 NSS Module Internals
979
980 * NSS Module Names::            Construction of the interface function of
981                                 the NSS modules.
982 * NSS Modules Interface::       Programming interface in the NSS module
983                                 functions.
984
985 Extending NSS
986
987 * Adding another Service to NSS::  What is to do to add a new service.
988 * NSS Module Function Internals::  Guidelines for writing new NSS
989                                         service functions.
990
991 Users and Groups
992
993 * User and Group IDs::          Each user has a unique numeric ID;
994                                  likewise for groups.
995 * Process Persona::             The user IDs and group IDs of a process.
996 * Why Change Persona::          Why a program might need to change
997                                  its user and/or group IDs.
998 * How Change Persona::          Changing the user and group IDs.
999 * Reading Persona::             How to examine the user and group IDs.
1000
1001 * Setting User ID::             Functions for setting the user ID.
1002 * Setting Groups::              Functions for setting the group IDs.
1003
1004 * Enable/Disable Setuid::       Turning setuid access on and off.
1005 * Setuid Program Example::      The pertinent parts of one sample program.
1006 * Tips for Setuid::             How to avoid granting unlimited access.
1007
1008 * Who Logged In::               Getting the name of the user who logged in,
1009                                  or of the real user ID of the current process.
1010
1011 * User Accounting Database::    Keeping information about users and various
1012                                  actions in databases.
1013
1014 * User Database::               Functions and data structures for
1015                                  accessing the user database.
1016 * Group Database::              Functions and data structures for
1017                                  accessing the group database.
1018 * Database Example::            Example program showing the use of database
1019                                  inquiry functions.
1020 * Netgroup Database::           Functions for accessing the netgroup database.
1021
1022 User Accounting Database
1023
1024 * Manipulating the Database::   Scanning and modifying the user
1025                                  accounting database.
1026 * XPG Functions::               A standardized way for doing the same thing.
1027 * Logging In and Out::          Functions from BSD that modify the user
1028                                  accounting database.
1029
1030 User Database
1031
1032 * User Data Structure::         What each user record contains.
1033 * Lookup User::                 How to look for a particular user.
1034 * Scanning All Users::          Scanning the list of all users, one by one.
1035 * Writing a User Entry::        How a program can rewrite a user's record.
1036
1037 Group Database
1038
1039 * Group Data Structure::        What each group record contains.
1040 * Lookup Group::                How to look for a particular group.
1041 * Scanning All Groups::         Scanning the list of all groups.
1042
1043 Netgroup Database
1044
1045 * Netgroup Data::                  Data in the Netgroup database and where
1046                                    it comes from.
1047 * Lookup Netgroup::                How to look for a particular netgroup.
1048 * Netgroup Membership::            How to test for netgroup membership.
1049
1050 System Information
1051
1052 * Host Identification::         Determining the name of the machine.
1053 * Hardware/Software Type ID::   Determining the hardware type of the
1054                                  machine and what operating system it is
1055                                  running.
1056 * Filesystem handling::         Which is mounted and/or available?
1057
1058 System Configuration
1059
1060 * General Limits::           Constants and functions that describe
1061                                 various process-related limits that have
1062                                 one uniform value for any given machine.
1063 * System Options::           Optional POSIX features.
1064 * Version Supported::        Version numbers of POSIX.1 and POSIX.2.
1065 * Sysconf::                  Getting specific configuration values
1066                                 of general limits and system options.
1067 * Minimums::                 Minimum values for general limits.
1068
1069 * Limits for Files::         Size limitations that pertain to individual files.
1070                                 These can vary between file systems
1071                                 or even from file to file.
1072 * Options for Files::        Optional features that some files may support.
1073 * File Minimums::            Minimum values for file limits.
1074 * Pathconf::                 Getting the limit values for a particular file.
1075
1076 * Utility Limits::           Capacity limits of some POSIX.2 utility programs.
1077 * Utility Minimums::         Minimum allowable values of those limits.
1078
1079 * String Parameters::        Getting the default search path.
1080
1081 Sysconf
1082
1083 * Sysconf Definition::        Detailed specifications of @code{sysconf}.
1084 * Constants for Sysconf::     The list of parameters @code{sysconf} can read.
1085 * Examples of Sysconf::       How to use @code{sysconf} and the parameter
1086                                  macros properly together.
1087
1088 POSIX Threads
1089
1090 * Basic Thread Operations::     Creating, terminating, and waiting for threads.
1091 * Thread Attributes::           Tuning thread scheduling.
1092 * Cancellation::                Stopping a thread before it's done.
1093 * Cleanup Handlers::            Deallocating resources when a thread is
1094                                   cancelled.
1095 * Mutexes::                     One way to synchronize threads.
1096 * Condition Variables::         Another way.
1097 * POSIX Semaphores::            And a third way.
1098 * Thread-Specific Data::        Variables with different values in
1099                                   different threads.
1100 * Threads and Signal Handling:: Why you should avoid mixing the two, and
1101                                   how to do it if you must.
1102 * Miscellaneous Thread Functions:: A grab bag of utility routines.
1103
1104 Language Features
1105
1106 * Consistency Checking::        Using @code{assert} to abort if
1107                                  something ``impossible'' happens.
1108 * Variadic Functions::          Defining functions with varying numbers
1109                                  of args.
1110 * Null Pointer Constant::       The macro @code{NULL}.
1111 * Important Data Types::        Data types for object sizes.
1112 * Data Type Measurements::      Parameters of data type representations.
1113
1114 Variadic Functions
1115
1116 * Why Variadic::                Reasons for making functions take
1117                                  variable arguments.
1118 * How Variadic::                How to define and call variadic functions.
1119 * Variadic Example::            A complete example.
1120
1121 How Variadic
1122
1123 * Variadic Prototypes::  How to make a prototype for a function
1124                           with variable arguments.
1125 * Receiving Arguments::  Steps you must follow to access the
1126                           optional argument values.
1127 * How Many Arguments::   How to decide whether there are more arguments.
1128 * Calling Variadics::    Things you need to know about calling
1129                           variable arguments functions.
1130 * Argument Macros::      Detailed specification of the macros
1131                           for accessing variable arguments.
1132 * Old Varargs::          The pre-ISO way of defining variadic functions.
1133
1134 Data Type Measurements
1135
1136 * Width of Type::           How many bits does an integer type hold?
1137 * Range of Type::           What are the largest and smallest values
1138                              that an integer type can hold?
1139 * Floating Type Macros::    Parameters that measure the floating point types.
1140 * Structure Measurement::   Getting measurements on structure types.
1141
1142 Floating Type Macros
1143
1144 * Floating Point Concepts::     Definitions of terminology.
1145 * Floating Point Parameters::   Details of specific macros.
1146 * IEEE Floating Point::         The measurements for one common
1147                                  representation.
1148
1149 Installation
1150
1151 * Tools for Installation::      We recommend using these tools to build.
1152 * Supported Configurations::    What systems the GNU C library runs on.
1153 * Tips for Installation::       Useful hints for the installation.
1154 * Reporting Bugs::              How to report bugs (if you want to
1155                                 get them fixed) and other troubles
1156                                 you may have with the GNU C library.
1157
1158 Maintenance
1159
1160 * Source Layout::         How to add new functions or header files
1161                              to the GNU C library.
1162 * Porting::               How to port the GNU C library to
1163                              a new machine or operating system.
1164
1165 Porting
1166
1167 * Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
1168 * Porting to Unix::             Porting the library to an average
1169                                    Unix-like system.
1170 @end menu