f14e172794383c8d7429f7f74042e6003f382d7d
[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
120 Unconstrained Allocation
121
122 * Basic Allocation::            Simple use of @code{malloc}.
123 * Malloc Examples::             Examples of @code{malloc}.  @code{xmalloc}.
124 * Freeing after Malloc::        Use @code{free} to free a block you
125                                  got with @code{malloc}.
126 * Changing Block Size::         Use @code{realloc} to make a block
127                                  bigger or smaller.
128 * Allocating Cleared Space::    Use @code{calloc} to allocate a
129                                  block and clear it.
130 * Efficiency and Malloc::       Efficiency considerations in use of
131                                  these functions.
132 * Aligned Memory Blocks::       Allocating specially aligned memory:
133                                  @code{memalign} and @code{valloc}.
134 * Malloc Tunable Parameters::   Use @code{mallopt} to adjust allocation
135                                  parameters.
136 * Heap Consistency Checking::   Automatic checking for errors.
137 * Hooks for Malloc::            You can use these hooks for debugging
138                                  programs that use @code{malloc}.
139 * Statistics of Malloc::        Getting information about how much
140                                  memory your program is using.
141 * Summary of Malloc::           Summary of @code{malloc} and related functions.
142
143 Allocation Debugging
144
145 * Tracing malloc::               How to install the tracing functionality.
146 * Using the Memory Debugger::    Example programs excerpts.
147 * Tips for the Memory Debugger:: Some more or less clever ideas.
148 * Interpreting the traces::      What do all these lines mean?
149
150 Obstacks
151
152 * Creating Obstacks::           How to declare an obstack in your program.
153 * Preparing for Obstacks::      Preparations needed before you can
154                                  use obstacks.
155 * Allocation in an Obstack::    Allocating objects in an obstack.
156 * Freeing Obstack Objects::     Freeing objects in an obstack.
157 * Obstack Functions::           The obstack functions are both
158                                  functions and macros.
159 * Growing Objects::             Making an object bigger by stages.
160 * Extra Fast Growing::          Extra-high-efficiency (though more
161                                  complicated) growing objects.
162 * Status of an Obstack::        Inquiries about the status of an obstack.
163 * Obstacks Data Alignment::     Controlling alignment of objects in obstacks.
164 * Obstack Chunks::              How obstacks obtain and release chunks;
165                                  efficiency considerations.
166 * Summary of Obstacks::
167
168 Variable Size Automatic
169
170 * Alloca Example::              Example of using @code{alloca}.
171 * Advantages of Alloca::        Reasons to use @code{alloca}.
172 * Disadvantages of Alloca::     Reasons to avoid @code{alloca}.
173 * GNU C Variable-Size Arrays::  Only in GNU C, here is an alternative
174                                  method of allocating dynamically and
175                                  freeing automatically.
176
177 Character Handling
178
179 * Classification of Characters::   Testing whether characters are
180                                     letters, digits, punctuation, etc.
181
182 * Case Conversion::                Case mapping, and the like.
183
184 String and Array Utilities
185
186 * Representation of Strings::   Introduction to basic concepts.
187 * String/Array Conventions::    Whether to use a string function or an
188                                  arbitrary array function.
189 * String Length::               Determining the length of a string.
190 * Copying and Concatenation::   Functions to copy the contents of strings
191                                  and arrays.
192 * String/Array Comparison::     Functions for byte-wise and character-wise
193                                  comparison.
194 * Collation Functions::         Functions for collating strings.
195 * Search Functions::            Searching for a specific element or substring.
196 * Finding Tokens in a String::  Splitting a string into tokens by looking
197                                  for delimiters.
198 * Encode Binary Data::          Encoding and Decoding of Binary Data.
199 * Argz and Envz Vectors::       Null-separated string vectors.
200
201 Argz and Envz Vectors
202
203 * Argz Functions::              Operations on argz vectors.
204 * Envz Functions::              Additional operations on environment vectors.
205
206 Extended Characters
207
208 * Extended Char Intro::         Multibyte codes versus wide characters.
209 * Locales and Extended Chars::  The locale selects the character codes.
210 * Multibyte Char Intro::        How multibyte codes are represented.
211 * Wide Char Intro::             How wide characters are represented.
212 * Wide String Conversion::      Converting wide strings to multibyte code
213                                  and vice versa.
214 * Length of Char::              how many bytes make up one multibyte char.
215 * Converting One Char::         Converting a string character by character.
216 * Example of Conversion::       Example showing why converting
217                                  one character at a time may be useful.
218 * Shift State::                 Multibyte codes with "shift characters".
219
220 Locales
221
222 * Effects of Locale::           Actions affected by the choice of
223                                  locale.
224 * Choosing Locale::             How the user specifies a locale.
225 * Locale Categories::           Different purposes for which you can
226                                  select a locale.
227 * Setting the Locale::          How a program specifies the locale
228                                  with library functions.
229 * Standard Locales::            Locale names available on all systems.
230 * Locale Information::          How to access the information for the locale.
231 * Formatting Numbers::          A dedicated function to format numbers.
232
233 Locale Information
234
235 * The Lame Way to Locale Data::   ISO C's @code{localeconv}.
236 * The Elegant and Fast Way::      X/Open's @code{nl_langinfo}.
237
238 The Lame Way to Locale Data
239
240 * General Numeric::             Parameters for formatting numbers and
241                                  currency amounts.
242 * Currency Symbol::             How to print the symbol that identifies an
243                                  amount of money (e.g. @samp{$}).
244 * Sign of Money Amount::        How to print the (positive or negative) sign
245                                  for a monetary amount, if one exists.
246
247 Message Translation
248
249 * Message catalogs a la X/Open::  The @code{catgets} family of functions.
250 * The Uniforum approach::         The @code{gettext} family of functions.
251
252 Message catalogs a la X/Open
253
254 * The catgets Functions::      The @code{catgets} function family.
255 * The message catalog files::  Format of the message catalog files.
256 * The gencat program::         How to generate message catalogs files which
257                                 can be used by the functions.
258 * Common Usage::               How to use the @code{catgets} interface.
259
260 The Uniforum approach
261
262 * Message catalogs with gettext::  The @code{gettext} family of functions.
263 * Helper programs for gettext::    Programs to handle message catalogs
264                                     for @code{gettext}.
265
266 Message catalogs with gettext
267
268 * Translation with gettext::    What has to be done to translate a message.
269 * Locating gettext catalog::    How to determine which catalog to be used.
270 * Using gettextized software::  The possibilities of the user to influence
271                                  the way @code{gettext} works.
272
273 Searching and Sorting
274
275 * Comparison Functions::        Defining how to compare two objects.
276                                  Since the sort and search facilities
277                                  are general, you have to specify the
278                                  ordering.
279 * Array Search Function::       The @code{bsearch} function.
280 * Array Sort Function::         The @code{qsort} function.
281 * Search/Sort Example::         An example program.
282 * Hash Search Function::        The @code{hsearch} function.
283 * Tree Search Function::        The @code{tsearch} function.
284
285 Pattern Matching
286
287 * Wildcard Matching::    Matching a wildcard pattern against a single string.
288 * Globbing::             Finding the files that match a wildcard pattern.
289 * Regular Expressions::  Matching regular expressions against strings.
290 * Word Expansion::       Expanding shell variables, nested commands,
291                             arithmetic, and wildcards.
292                             This is what the shell does with shell commands.
293
294 Globbing
295
296 * Calling Glob::             Basic use of @code{glob}.
297 * Flags for Globbing::       Flags that enable various options in @code{glob}.
298 * More Flags for Globbing::  GNU specific extensions to @code{glob}.
299
300 Regular Expressions
301
302 * POSIX Regexp Compilation::    Using @code{regcomp} to prepare to match.
303 * Flags for POSIX Regexps::     Syntax variations for @code{regcomp}.
304 * Matching POSIX Regexps::      Using @code{regexec} to match the compiled
305                                    pattern that you get from @code{regcomp}.
306 * Regexp Subexpressions::       Finding which parts of the string were matched.
307 * Subexpression Complications:: Find points of which parts were matched.
308 * Regexp Cleanup::              Freeing storage; reporting errors.
309
310 Word Expansion
311
312 * Expansion Stages::            What word expansion does to a string.
313 * Calling Wordexp::             How to call @code{wordexp}.
314 * Flags for Wordexp::           Options you can enable in @code{wordexp}.
315 * Wordexp Example::             A sample program that does word expansion.
316 * Tilde Expansion::             Details of how tilde expansion works.
317 * Variable Substitution::       Different types of variable substitution.
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 * File Size::                   Manually changing the size of a file.
543
544 Pipes and FIFOs
545
546 * Creating a Pipe::             Making a pipe with the @code{pipe} function.
547 * Pipe to a Subprocess::        Using a pipe to communicate with a
548                                  child process.
549 * FIFO Special Files::          Making a FIFO special file.
550 * Pipe Atomicity::              When pipe (or FIFO) I/O is atomic.
551
552 Sockets
553
554 * Socket Concepts::     Basic concepts you need to know about.
555 * Communication Styles::Stream communication, datagrams, and other styles.
556 * Socket Addresses::    How socket names (``addresses'') work.
557 * Interface Naming::    Identifying specific network interfaces.
558 * Local Namespace::     Details about the local namespace.
559 * Internet Namespace::  Details about the Internet namespace.
560 * Misc Namespaces::     Other namespaces not documented fully here.
561 * Open/Close Sockets::  Creating sockets and destroying them.
562 * Connections::         Operations on sockets with connection state.
563 * Datagrams::           Operations on datagram sockets.
564 * Inetd::               Inetd is a daemon that starts servers on request.
565                            The most convenient way to write a server
566                            is to make it work with Inetd.
567 * Socket Options::      Miscellaneous low-level socket options.
568 * Networks Database::   Accessing the database of network names.
569
570 Socket Addresses
571
572 * Address Formats::             About @code{struct sockaddr}.
573 * Setting Address::             Binding an address to a socket.
574 * Reading Address::             Reading the address of a socket.
575
576 Local Namespace
577
578 * Concepts: Local Namespace Concepts. What you need to understand.
579 * Details: Local Namespace Details.   Address format, symbolic names, etc.
580 * Example: Local Socket Example.      Example of creating a socket.
581
582 Internet Namespace
583
584 * Internet Address Formats::    How socket addresses are specified in the
585                                  Internet namespace.
586 * Host Addresses::              All about host addresses of internet host.
587 * Protocols Database::          Referring to protocols by name.
588 * Ports::                       Internet port numbers.
589 * Services Database::           Ports may have symbolic names.
590 * Byte Order::                  Different hosts may use different byte
591                                  ordering conventions; you need to
592                                  canonicalize host address and port number.
593 * Inet Example::                Putting it all together.
594
595 Host Addresses
596
597 * Abstract Host Addresses::     What a host number consists of.
598 * Data type: Host Address Data Type.    Data type for a host number.
599 * Functions: Host Address Functions.    Functions to operate on them.
600 * Names: Host Names.            Translating host names to host numbers.
601
602 Open/Close Sockets
603
604 * Creating a Socket::           How to open a socket.
605 * Closing a Socket::            How to close a socket.
606 * Socket Pairs::                These are created like pipes.
607
608 Connections
609
610 * Connecting::               What the client program must do.
611 * Listening::                How a server program waits for requests.
612 * Accepting Connections::    What the server does when it gets a request.
613 * Who is Connected::         Getting the address of the
614                                 other side of a connection.
615 * Transferring Data::        How to send and receive data.
616 * Byte Stream Example::      An example program: a client for communicating
617                               over a byte stream socket in the Internet namespace.
618 * Server Example::           A corresponding server program.
619 * Out-of-Band Data::         This is an advanced feature.
620
621 Transferring Data
622
623 * Sending Data::                Sending data with @code{send}.
624 * Receiving Data::              Reading data with @code{recv}.
625 * Socket Data Options::         Using @code{send} and @code{recv}.
626
627 Datagrams
628
629 * Sending Datagrams::    Sending packets on a datagram socket.
630 * Receiving Datagrams::  Receiving packets on a datagram socket.
631 * Datagram Example::     An example program: packets sent over a
632                            datagram socket in the local namespace.
633 * Example Receiver::     Another program, that receives those packets.
634
635 Inetd
636
637 * Inetd Servers::
638 * Configuring Inetd::
639
640 Socket Options
641
642 * Socket Option Functions::     The basic functions for setting and getting
643                                  socket options.
644 * Socket-Level Options::        Details of the options at the socket level.
645
646 Low-Level Terminal Interface
647
648 * Is It a Terminal::            How to determine if a file is a terminal
649                                  device, and what its name is.
650 * I/O Queues::                  About flow control and typeahead.
651 * Canonical or Not::            Two basic styles of input processing.
652 * Terminal Modes::              How to examine and modify flags controlling
653                                  details of terminal I/O: echoing,
654                                  signals, editing.
655 * Line Control::                Sending break sequences, clearing
656                                  terminal buffers @dots{}
657 * Noncanon Example::            How to read single characters without echo.
658 * Pseudo-Terminals::            How to open a pseudo-terminal.
659
660 Terminal Modes
661
662 * Mode Data Types::             The data type @code{struct termios} and
663                                  related types.
664 * Mode Functions::              Functions to read and set the terminal
665                                  attributes.
666 * Setting Modes::               The right way to set terminal attributes
667                                  reliably.
668 * Input Modes::                 Flags controlling low-level input handling.
669 * Output Modes::                Flags controlling low-level output handling.
670 * Control Modes::               Flags controlling serial port behavior.
671 * Local Modes::                 Flags controlling high-level input handling.
672 * Line Speed::                  How to read and set the terminal line speed.
673 * Special Characters::          Characters that have special effects,
674                                  and how to change them.
675 * Noncanonical Input::          Controlling how long to wait for input.
676
677 Special Characters
678
679 * Editing Characters::          Special characters that terminate lines and
680                                   delete text, and other editing functions.
681 * Signal Characters::           Special characters that send or raise signals
682                                   to or for certain classes of processes.
683 * Start/Stop Characters::       Special characters that suspend or resume
684                                   suspended output.
685 * Other Special::               Other special characters for BSD systems:
686                                   they can discard output, and print status.
687
688 Pseudo-Terminals
689
690 * Allocation::             Allocating a pseudo terminal.
691 * Pseudo-Terminal Pairs::  How to open both sides of a
692                             pseudo-terminal in a single operation.
693
694 Mathematics
695
696 * Mathematical Constants::      Precise numeric values for often-used
697                                  constants.
698 * Trig Functions::              Sine, cosine, tangent, and friends.
699 * Inverse Trig Functions::      Arcsine, arccosine, etc.
700 * Exponents and Logarithms::    Also pow and sqrt.
701 * Hyperbolic Functions::        sinh, cosh, tanh, etc.
702 * Special Functions::           Bessel, gamma, erf.
703 * Pseudo-Random Numbers::       Functions for generating pseudo-random
704                                  numbers.
705 * FP Function Optimizations::   Fast code or small code.
706
707 Pseudo-Random Numbers
708
709 * ISO Random::                  @code{rand} and friends.
710 * BSD Random::                  @code{random} and friends.
711 * SVID Random::                 @code{drand48} and friends.
712
713 Arithmetic
714
715 * Floating Point Numbers::      Basic concepts.  IEEE 754.
716 * Floating Point Classes::      The five kinds of floating-point number.
717 * Floating Point Errors::       When something goes wrong in a calculation.
718 * Rounding::                    Controlling how results are rounded.
719 * Control Functions::           Saving and restoring the FPU's state.
720 * Arithmetic Functions::        Fundamental operations provided by the library.
721 * Complex Numbers::             The types.  Writing complex constants.
722 * Operations on Complex::       Projection, conjugation, decomposition.
723 * Integer Division::            Integer division with guaranteed rounding.
724 * Parsing of Numbers::          Converting strings to numbers.
725 * System V Number Conversion::  An archaic way to convert numbers to strings.
726
727 Floating Point Errors
728
729 * FP Exceptions::               IEEE 754 math exceptions and how to detect them.
730 * Infinity and NaN::            Special values returned by calculations.
731 * Status bit operations::       Checking for exceptions after the fact.
732 * Math Error Reporting::        How the math functions report errors.
733
734 Arithmetic Functions
735
736 * Absolute Value::              Absolute values of integers and floats.
737 * Normalization Functions::     Extracting exponents and putting them back.
738 * Rounding Functions::          Rounding floats to integers.
739 * Remainder Functions::         Remainders on division, precisely defined.
740 * FP Bit Twiddling::            Sign bit adjustment.  Adding epsilon.
741 * FP Comparison Functions::     Comparisons without risk of exceptions.
742 * Misc FP Arithmetic::          Max, min, positive difference, multiply-add.
743
744 Parsing of Numbers
745
746 * Parsing of Integers::         Functions for conversion of integer values.
747 * Parsing of Floats::           Functions for conversion of floating-point
748                                  values.
749
750 Date and Time
751
752 * Processor Time::              Measures processor time used by a program.
753 * Calendar Time::               Manipulation of ``real'' dates and times.
754 * Setting an Alarm::            Sending a signal after a specified time.
755 * Sleeping::                    Waiting for a period of time.
756 * Resource Usage::              Measuring various resources used.
757 * Limits on Resources::         Specifying limits on resource usage.
758 * Priority::                    Reading or setting process run priority.
759
760 Processor Time
761
762 * Basic CPU Time::              The @code{clock} function.
763 * Detailed CPU Time::           The @code{times} function.
764
765 Calendar Time
766
767 * Simple Calendar Time::        Facilities for manipulating calendar time.
768 * High-Resolution Calendar::    A time representation with greater precision.
769 * Broken-down Time::            Facilities for manipulating local time.
770 * Formatting Date and Time::    Converting times to strings.
771 * TZ Variable::                 How users specify the time zone.
772 * Time Zone Functions::         Functions to examine or specify the time zone.
773 * Time Functions Example::      An example program showing use of some of
774                                  the time functions.
775
776 Non-Local Exits
777
778 * Intro: Non-Local Intro.        When and how to use these facilities.
779 * Details: Non-Local Details.   Functions for nonlocal exits.
780 * Non-Local Exits and Signals::  Portability issues.
781
782 Signal Handling
783
784 * Concepts of Signals::         Introduction to the signal facilities.
785 * Standard Signals::            Particular kinds of signals with
786                                  standard names and meanings.
787 * Signal Actions::              Specifying what happens when a
788                                  particular signal is delivered.
789 * Defining Handlers::           How to write a signal handler function.
790 * Interrupted Primitives::      Signal handlers affect use of @code{open},
791                                  @code{read}, @code{write} and other functions.
792 * Generating Signals::          How to send a signal to a process.
793 * Blocking Signals::            Making the system hold signals temporarily.
794 * Waiting for a Signal::        Suspending your program until a signal
795                                  arrives.
796 * Signal Stack::                Using a Separate Signal Stack.
797 * BSD Signal Handling::         Additional functions for backward
798                                  compatibility with BSD.
799
800 Concepts of Signals
801
802 * Kinds of Signals::            Some examples of what can cause a signal.
803 * Signal Generation::           Concepts of why and how signals occur.
804 * Delivery of Signal::          Concepts of what a signal does to the
805                                  process.
806
807 Standard Signals
808
809 * Program Error Signals::       Used to report serious program errors.
810 * Termination Signals::         Used to interrupt and/or terminate the
811                                  program.
812 * Alarm Signals::               Used to indicate expiration of timers.
813 * Asynchronous I/O Signals::    Used to indicate input is available.
814 * Job Control Signals::         Signals used to support job control.
815 * Operation Error Signals::     Used to report operational system errors.
816 * Miscellaneous Signals::       Miscellaneous Signals.
817 * Signal Messages::             Printing a message describing a signal.
818
819 Signal Actions
820
821 * Basic Signal Handling::       The simple @code{signal} function.
822 * Advanced Signal Handling::    The more powerful @code{sigaction} function.
823 * Signal and Sigaction::        How those two functions interact.
824 * Sigaction Function Example::  An example of using the sigaction function.
825 * Flags for Sigaction::         Specifying options for signal handling.
826 * Initial Signal Actions::      How programs inherit signal actions.
827
828 Defining Handlers
829
830 * Handler Returns::             Handlers that return normally, and what
831                                  this means.
832 * Termination in Handler::      How handler functions terminate a program.
833 * Longjmp in Handler::          Nonlocal transfer of control out of a
834                                  signal handler.
835 * Signals in Handler::          What happens when signals arrive while
836                                  the handler is already occupied.
837 * Merged Signals::              When a second signal arrives before the
838                                  first is handled.
839 * Nonreentrancy::               Do not call any functions unless you know they
840                                  are reentrant with respect to signals.
841 * Atomic Data Access::          A single handler can run in the middle of
842                                  reading or writing a single object.
843
844 Atomic Data Access
845
846 * Non-atomic Example::          A program illustrating interrupted access.
847 * Types: Atomic Types.          Data types that guarantee no interruption.
848 * Usage: Atomic Usage.          Proving that interruption is harmless.
849
850 Generating Signals
851
852 * Signaling Yourself::          A process can send a signal to itself.
853 * Signaling Another Process::   Send a signal to another process.
854 * Permission for kill::         Permission for using @code{kill}.
855 * Kill Example::                Using @code{kill} for Communication.
856
857 Blocking Signals
858
859 * Why Block::                           The purpose of blocking signals.
860 * Signal Sets::                         How to specify which signals to
861                                          block.
862 * Process Signal Mask::                 Blocking delivery of signals to your
863                                          process during normal execution.
864 * Testing for Delivery::                Blocking to Test for Delivery of
865                                          a Signal.
866 * Blocking for Handler::                Blocking additional signals while a
867                                          handler is being run.
868 * Checking for Pending Signals::        Checking for Pending Signals
869 * Remembering a Signal::                How you can get almost the same
870                                          effect as blocking a signal, by
871                                          handling it and setting a flag
872                                          to be tested later.
873
874 Waiting for a Signal
875
876 * Using Pause::                 The simple way, using @code{pause}.
877 * Pause Problems::              Why the simple way is often not very good.
878 * Sigsuspend::                  Reliably waiting for a specific signal.
879
880 BSD Signal Handling
881
882 * BSD Handler::                 BSD Function to Establish a Handler.
883 * Blocking in BSD::             BSD Functions for Blocking Signals.
884
885 Process Startup
886
887 * Program Arguments::           Parsing your program's command-line arguments.
888 * Environment Variables::       How to access parameters inherited from
889                                  a parent process.
890 * Program Termination::         How to cause a process to terminate and
891                                  return status information to its parent.
892
893 Program Arguments
894
895 * Argument Syntax::             By convention, options start with a hyphen.
896 * Parsing Program Arguments::   Ways to parse program options and arguments.
897
898 Parsing Program Arguments
899
900 * Getopt::                      Parsing program options using @code{getopt}.
901 * Argp::                        Parsing program options using @code{argp_parse}.
902 * Suboptions::                  Some programs need more detailed options.
903 * Suboptions Example::          This shows how it could be done for @code{mount}.
904
905 Environment Variables
906
907 * Environment Access::          How to get and set the values of
908                                  environment variables.
909 * Standard Environment::        These environment variables have
910                                  standard interpretations.
911
912 Program Termination
913
914 * Normal Termination::          If a program calls @code{exit}, a
915                                  process terminates normally.
916 * Exit Status::                 The @code{exit status} provides information
917                                  about why the process terminated.
918 * Cleanups on Exit::            A process can run its own cleanup
919                                  functions upon normal termination.
920 * Aborting a Program::          The @code{abort} function causes
921                                  abnormal program termination.
922 * Termination Internals::       What happens when a process terminates.
923
924 Processes
925
926 * Running a Command::           The easy way to run another program.
927 * Process Creation Concepts::   An overview of the hard way to do it.
928 * Process Identification::      How to get the process ID of a process.
929 * Creating a Process::          How to fork a child process.
930 * Executing a File::            How to make a process execute another program.
931 * Process Completion::          How to tell when a child process has completed.
932 * Process Completion Status::   How to interpret the status value
933                                  returned from a child process.
934 * BSD Wait Functions::          More functions, for backward compatibility.
935 * Process Creation Example::    A complete example program.
936
937 Job Control
938
939 * Concepts of Job Control::     Jobs can be controlled by a shell.
940 * Job Control is Optional::     Not all POSIX systems support job control.
941 * Controlling Terminal::        How a process gets its controlling terminal.
942 * Access to the Terminal::      How processes share the controlling terminal.
943 * Orphaned Process Groups::     Jobs left after the user logs out.
944 * Implementing a Shell::        What a shell must do to implement job control.
945 * Functions for Job Control::   Functions to control process groups.
946
947 Implementing a Shell
948
949 * Data Structures::             Introduction to the sample shell.
950 * Initializing the Shell::      What the shell must do to take
951                                  responsibility for job control.
952 * Launching Jobs::              Creating jobs to execute commands.
953 * Foreground and Background::   Putting a job in foreground of background.
954 * Stopped and Terminated Jobs::  Reporting job status.
955 * Continuing Stopped Jobs::     How to continue a stopped job in
956                                  the foreground or background.
957 * Missing Pieces::              Other parts of the shell.
958
959 Functions for Job Control
960
961 * Identifying the Terminal::    Determining the controlling terminal's name.
962 * Process Group Functions::     Functions for manipulating process groups.
963 * Terminal Access Functions::   Functions for controlling terminal access.
964
965 Name Service Switch
966
967 * NSS Basics::                  What is this NSS good for.
968 * NSS Configuration File::      Configuring NSS.
969 * NSS Module Internals::        How does it work internally.
970 * Extending NSS::               What to do to add services or databases.
971
972 NSS Configuration File
973
974 * Services in the NSS configuration::  Service names in the NSS configuration.
975 * Actions in the NSS configuration::  React appropriately to the lookup result.
976 * Notes on NSS Configuration File::  Things to take care about while
977                                      configuring NSS.
978
979 NSS Module Internals
980
981 * NSS Module Names::            Construction of the interface function of
982                                 the NSS modules.
983 * NSS Modules Interface::       Programming interface in the NSS module
984                                 functions.
985
986 Extending NSS
987
988 * Adding another Service to NSS::  What is to do to add a new service.
989 * NSS Module Function Internals::  Guidelines for writing new NSS
990                                         service functions.
991
992 Users and Groups
993
994 * User and Group IDs::          Each user has a unique numeric ID;
995                                  likewise for groups.
996 * Process Persona::             The user IDs and group IDs of a process.
997 * Why Change Persona::          Why a program might need to change
998                                  its user and/or group IDs.
999 * How Change Persona::          Changing the user and group IDs.
1000 * Reading Persona::             How to examine the user and group IDs.
1001
1002 * Setting User ID::             Functions for setting the user ID.
1003 * Setting Groups::              Functions for setting the group IDs.
1004
1005 * Enable/Disable Setuid::       Turning setuid access on and off.
1006 * Setuid Program Example::      The pertinent parts of one sample program.
1007 * Tips for Setuid::             How to avoid granting unlimited access.
1008
1009 * Who Logged In::               Getting the name of the user who logged in,
1010                                  or of the real user ID of the current process.
1011
1012 * User Accounting Database::    Keeping information about users and various
1013                                  actions in databases.
1014
1015 * User Database::               Functions and data structures for
1016                                  accessing the user database.
1017 * Group Database::              Functions and data structures for
1018                                  accessing the group database.
1019 * Database Example::            Example program showing the use of database
1020                                  inquiry functions.
1021 * Netgroup Database::           Functions for accessing the netgroup database.
1022
1023 User Accounting Database
1024
1025 * Manipulating the Database::   Scanning and modifying the user
1026                                  accounting database.
1027 * XPG Functions::               A standardized way for doing the same thing.
1028 * Logging In and Out::          Functions from BSD that modify the user
1029                                  accounting database.
1030
1031 User Database
1032
1033 * User Data Structure::         What each user record contains.
1034 * Lookup User::                 How to look for a particular user.
1035 * Scanning All Users::          Scanning the list of all users, one by one.
1036 * Writing a User Entry::        How a program can rewrite a user's record.
1037
1038 Group Database
1039
1040 * Group Data Structure::        What each group record contains.
1041 * Lookup Group::                How to look for a particular group.
1042 * Scanning All Groups::         Scanning the list of all groups.
1043
1044 Netgroup Database
1045
1046 * Netgroup Data::                  Data in the Netgroup database and where
1047                                    it comes from.
1048 * Lookup Netgroup::                How to look for a particular netgroup.
1049 * Netgroup Membership::            How to test for netgroup membership.
1050
1051 System Information
1052
1053 * Host Identification::         Determining the name of the machine.
1054 * Hardware/Software Type ID::   Determining the hardware type of the
1055                                  machine and what operating system it is
1056                                  running.
1057 * Filesystem handling::         Which is mounted and/or available?
1058
1059 System Configuration
1060
1061 * General Limits::           Constants and functions that describe
1062                                 various process-related limits that have
1063                                 one uniform value for any given machine.
1064 * System Options::           Optional POSIX features.
1065 * Version Supported::        Version numbers of POSIX.1 and POSIX.2.
1066 * Sysconf::                  Getting specific configuration values
1067                                 of general limits and system options.
1068 * Minimums::                 Minimum values for general limits.
1069
1070 * Limits for Files::         Size limitations that pertain to individual files.
1071                                 These can vary between file systems
1072                                 or even from file to file.
1073 * Options for Files::        Optional features that some files may support.
1074 * File Minimums::            Minimum values for file limits.
1075 * Pathconf::                 Getting the limit values for a particular file.
1076
1077 * Utility Limits::           Capacity limits of some POSIX.2 utility programs.
1078 * Utility Minimums::         Minimum allowable values of those limits.
1079
1080 * String Parameters::        Getting the default search path.
1081
1082 Sysconf
1083
1084 * Sysconf Definition::        Detailed specifications of @code{sysconf}.
1085 * Constants for Sysconf::     The list of parameters @code{sysconf} can read.
1086 * Examples of Sysconf::       How to use @code{sysconf} and the parameter
1087                                  macros properly together.
1088
1089 POSIX Threads
1090
1091 * Basic Thread Operations::     Creating, terminating, and waiting for threads.
1092 * Thread Attributes::           Tuning thread scheduling.
1093 * Cancellation::                Stopping a thread before it's done.
1094 * Cleanup Handlers::            Deallocating resources when a thread is
1095                                   cancelled.
1096 * Mutexes::                     One way to synchronize threads.
1097 * Condition Variables::         Another way.
1098 * POSIX Semaphores::            And a third way.
1099 * Thread-Specific Data::        Variables with different values in
1100                                   different threads.
1101 * Threads and Signal Handling:: Why you should avoid mixing the two, and
1102                                   how to do it if you must.
1103 * Miscellaneous Thread Functions:: A grab bag of utility routines.
1104
1105 Language Features
1106
1107 * Consistency Checking::        Using @code{assert} to abort if
1108                                  something ``impossible'' happens.
1109 * Variadic Functions::          Defining functions with varying numbers
1110                                  of args.
1111 * Null Pointer Constant::       The macro @code{NULL}.
1112 * Important Data Types::        Data types for object sizes.
1113 * Data Type Measurements::      Parameters of data type representations.
1114
1115 Variadic Functions
1116
1117 * Why Variadic::                Reasons for making functions take
1118                                  variable arguments.
1119 * How Variadic::                How to define and call variadic functions.
1120 * Variadic Example::            A complete example.
1121
1122 How Variadic
1123
1124 * Variadic Prototypes::  How to make a prototype for a function
1125                           with variable arguments.
1126 * Receiving Arguments::  Steps you must follow to access the
1127                           optional argument values.
1128 * How Many Arguments::   How to decide whether there are more arguments.
1129 * Calling Variadics::    Things you need to know about calling
1130                           variable arguments functions.
1131 * Argument Macros::      Detailed specification of the macros
1132                           for accessing variable arguments.
1133 * Old Varargs::          The pre-ISO way of defining variadic functions.
1134
1135 Data Type Measurements
1136
1137 * Width of Type::           How many bits does an integer type hold?
1138 * Range of Type::           What are the largest and smallest values
1139                              that an integer type can hold?
1140 * Floating Type Macros::    Parameters that measure the floating point types.
1141 * Structure Measurement::   Getting measurements on structure types.
1142
1143 Floating Type Macros
1144
1145 * Floating Point Concepts::     Definitions of terminology.
1146 * Floating Point Parameters::   Details of specific macros.
1147 * IEEE Floating Point::         The measurements for one common
1148                                  representation.
1149
1150 Installation
1151
1152 * Configuring and compiling::   How to compile and test GNU libc.
1153 * Running make install::        How to install it once you've got it compiled.
1154 * Tools for Compilation::       You'll need these first.
1155 * Supported Configurations::    What it runs on, what it doesn't.
1156 * Linux::                       Specific advice for Linux systems.
1157 * Reporting Bugs::              So they'll get fixed.
1158
1159 Maintenance
1160
1161 * Source Layout::         How to add new functions or header files
1162                              to the GNU C library.
1163 * Porting::               How to port the GNU C library to
1164                              a new machine or operating system.
1165
1166 Porting
1167
1168 * Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
1169 * Porting to Unix::             Porting the library to an average
1170                                    Unix-like system.
1171 @end menu