Generated top-level menu.
[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 Error Reporting
81
82 * Checking for Errors::         How errors are reported by library functions.
83 * Error Codes::                 Error code macros; all of these expand
84                                  into integer constant values.
85 * Error Messages::              Mapping error codes onto error messages.
86
87 Memory Allocation
88
89 * Memory Concepts::             An introduction to concepts and terminology.
90 * Dynamic Allocation and C::    How to get different kinds of allocation in C.
91 * Unconstrained Allocation::    The @code{malloc} facility allows fully general
92                                  dynamic allocation.
93 * Allocation Debugging::        Finding memory leaks and not freed memory.
94 * Obstacks::                    Obstacks are less general than malloc
95                                  but more efficient and convenient.
96 * Variable Size Automatic::     Allocation of variable-sized blocks
97                                  of automatic storage that are freed when the
98                                  calling function returns.
99 * Relocating Allocator::        Waste less memory, if you can tolerate
100                                  automatic relocation of the blocks you get.
101
102 Character Handling
103
104 * Classification of Characters::   Testing whether characters are
105                                     letters, digits, punctuation, etc.
106
107 * Case Conversion::                Case mapping, and the like.
108
109 String and Array Utilities
110
111 * Representation of Strings::   Introduction to basic concepts.
112 * String/Array Conventions::    Whether to use a string function or an
113                                  arbitrary array function.
114 * String Length::               Determining the length of a string.
115 * Copying and Concatenation::   Functions to copy the contents of strings
116                                  and arrays.
117 * String/Array Comparison::     Functions for byte-wise and character-wise
118                                  comparison.
119 * Collation Functions::         Functions for collating strings.
120 * Search Functions::            Searching for a specific element or substring.
121 * Finding Tokens in a String::  Splitting a string into tokens by looking
122                                  for delimiters.
123 * Encode Binary Data::          Encoding and Decoding of Binary Data.
124 * Argz and Envz Vectors::       Null-separated string vectors.
125
126 Extended Characters
127
128 * Extended Char Intro::         Multibyte codes versus wide characters.
129 * Locales and Extended Chars::  The locale selects the character codes.
130 * Multibyte Char Intro::        How multibyte codes are represented.
131 * Wide Char Intro::             How wide characters are represented.
132 * Wide String Conversion::      Converting wide strings to multibyte code
133                                  and vice versa.
134 * Length of Char::              how many bytes make up one multibyte char.
135 * Converting One Char::         Converting a string character by character.
136 * Example of Conversion::       Example showing why converting
137                                  one character at a time may be useful.
138 * Shift State::                 Multibyte codes with "shift characters".
139
140 Locales
141
142 * Effects of Locale::           Actions affected by the choice of
143                                  locale.
144 * Choosing Locale::             How the user specifies a locale.
145 * Locale Categories::           Different purposes for which you can
146                                  select a locale.
147 * Setting the Locale::          How a program specifies the locale
148                                  with library functions.
149 * Standard Locales::            Locale names available on all systems.
150 * Numeric Formatting::          How to format numbers according to the
151                                  chosen locale.
152
153 Message Translation
154
155 * Message catalogs a la X/Open::  The @code{catgets} family of functions.
156 * The Uniforum approach::         The @code{gettext} family of functions.
157
158 Searching and Sorting
159
160 * Comparison Functions::        Defining how to compare two objects.
161                                  Since the sort and search facilities
162                                  are general, you have to specify the
163                                  ordering.
164 * Array Search Function::       The @code{bsearch} function.
165 * Array Sort Function::         The @code{qsort} function.
166 * Search/Sort Example::         An example program.
167 * Hash Search Function::        The @code{hsearch} function.
168 * Tree Search Function::        The @code{tsearch} function.
169
170 Pattern Matching
171
172 * Wildcard Matching::    Matching a wildcard pattern against a single string.
173 * Globbing::             Finding the files that match a wildcard pattern.
174 * Regular Expressions::  Matching regular expressions against strings.
175 * Word Expansion::       Expanding shell variables, nested commands,
176                             arithmetic, and wildcards.
177                             This is what the shell does with shell commands.
178
179 I/O Overview
180
181 * I/O Concepts::       Some basic information and terminology.
182 * File Names::         How to refer to a file.
183
184 I/O on Streams
185
186 * Streams::                     About the data type representing a stream.
187 * Standard Streams::            Streams to the standard input and output
188                                  devices are created for you.
189 * Opening Streams::             How to create a stream to talk to a file.
190 * Closing Streams::             Close a stream when you are finished with it.
191 * Simple Output::               Unformatted output by characters and lines.
192 * Character Input::             Unformatted input by characters and words.
193 * Line Input::                  Reading a line or a record from a stream.
194 * Unreading::                   Peeking ahead/pushing back input just read.
195 * Block Input/Output::          Input and output operations on blocks of data.
196 * Formatted Output::            @code{printf} and related functions.
197 * Customizing Printf::          You can define new conversion specifiers for
198                                  @code{printf} and friends.
199 * Formatted Input::             @code{scanf} and related functions.
200 * EOF and Errors::              How you can tell if an I/O error happens.
201 * Binary Streams::              Some systems distinguish between text files
202                                  and binary files.
203 * File Positioning::            About random-access streams.
204 * Portable Positioning::        Random access on peculiar ISO C systems.
205 * Stream Buffering::            How to control buffering of streams.
206 * Other Kinds of Streams::      Streams that do not necessarily correspond
207                                  to an open file.
208 * Formatted Messages::          Print strictly formatted messages.
209
210 Low-Level I/O
211
212 * Opening and Closing Files::           How to open and close file
213                                          descriptors.
214 * Truncating Files::                    Change the size of a file.
215 * I/O Primitives::                      Reading and writing data.
216 * File Position Primitive::             Setting a descriptor's file
217                                          position.
218 * Descriptors and Streams::             Converting descriptor to stream
219                                          or vice-versa.
220 * Stream/Descriptor Precautions::       Precautions needed if you use both
221                                          descriptors and streams.
222 * Waiting for I/O::                     How to check for input or output
223                                          on multiple file descriptors.
224 * Synchronizing I/O::                   Making sure all I/O actions completed.
225 * Asynchronous I/O::                    Perform I/O in parallel.
226 * Control Operations::                  Various other operations on file
227                                          descriptors.
228 * Duplicating Descriptors::             Fcntl commands for duplicating
229                                          file descriptors.
230 * Descriptor Flags::                    Fcntl commands for manipulating
231                                          flags associated with file
232                                          descriptors.
233 * File Status Flags::                   Fcntl commands for manipulating
234                                          flags associated with open files.
235 * File Locks::                          Fcntl commands for implementing
236                                          file locking.
237 * Interrupt Input::                     Getting an asynchronous signal when
238                                          input arrives.
239
240 File System Interface
241
242 * Working Directory::           This is used to resolve relative
243                                  file names.
244 * Accessing Directories::       Finding out what files a directory
245                                  contains.
246 * Working on Directory Trees::  Apply actions to all files or a selectable
247                                  subset of a directory hierarchy.
248 * Hard Links::                  Adding alternate names to a file.
249 * Symbolic Links::              A file that ``points to'' a file name.
250 * Deleting Files::              How to delete a file, and what that means.
251 * Renaming Files::              Changing a file's name.
252 * Creating Directories::        A system call just for creating a directory.
253 * File Attributes::             Attributes of individual files.
254 * Making Special Files::        How to create special files.
255 * Temporary Files::             Naming and creating temporary files.
256
257 Pipes and FIFOs
258
259 * Creating a Pipe::             Making a pipe with the @code{pipe} function.
260 * Pipe to a Subprocess::        Using a pipe to communicate with a
261                                  child process.
262 * FIFO Special Files::          Making a FIFO special file.
263 * Pipe Atomicity::              When pipe (or FIFO) I/O is atomic.
264
265 Sockets
266
267 * Socket Concepts::     Basic concepts you need to know about.
268 * Communication Styles::Stream communication, datagrams, and other styles.
269 * Socket Addresses::    How socket names (``addresses'') work.
270 * Interface Naming::    Identifying specific network interfaces.
271 * Local Namespace::     Details about the local namespace.
272 * Internet Namespace::  Details about the Internet namespace.
273 * Misc Namespaces::     Other namespaces not documented fully here.
274 * Open/Close Sockets::  Creating sockets and destroying them.
275 * Connections::         Operations on sockets with connection state.
276 * Datagrams::           Operations on datagram sockets.
277 * Inetd::               Inetd is a daemon that starts servers on request.
278                            The most convenient way to write a server
279                            is to make it work with Inetd.
280 * Socket Options::      Miscellaneous low-level socket options.
281 * Networks Database::   Accessing the database of network names.
282
283 Low-Level Terminal Interface
284
285 * Is It a Terminal::            How to determine if a file is a terminal
286                                  device, and what its name is.
287 * I/O Queues::                  About flow control and typeahead.
288 * Canonical or Not::            Two basic styles of input processing.
289 * Terminal Modes::              How to examine and modify flags controlling
290                                  details of terminal I/O: echoing,
291                                  signals, editing.
292 * Line Control::                Sending break sequences, clearing
293                                  terminal buffers @dots{}
294 * Noncanon Example::            How to read single characters without echo.
295 * Pseudo-Terminals::            How to open a pseudo-terminal.
296
297 Mathematics
298
299 * Mathematical Constants::      Precise numeric values for often-used
300                                  constants.
301 * Trig Functions::              Sine, cosine, tangent, and friends.
302 * Inverse Trig Functions::      Arcsine, arccosine, etc.
303 * Exponents and Logarithms::    Also pow and sqrt.
304 * Hyperbolic Functions::        sinh, cosh, tanh, etc.
305 * Special Functions::           Bessel, gamma, erf.
306 * Pseudo-Random Numbers::       Functions for generating pseudo-random
307                                  numbers.
308 * FP Function Optimizations::   Fast code or small code.
309
310 Arithmetic
311
312 * Floating Point Numbers::      Basic concepts.  IEEE 754.
313 * Floating Point Classes::      The five kinds of floating-point number.
314 * Floating Point Errors::       When something goes wrong in a calculation.
315 * Rounding::                    Controlling how results are rounded.
316 * Control Functions::           Saving and restoring the FPU's state.
317 * Arithmetic Functions::        Fundamental operations provided by the library.
318 * Complex Numbers::             The types.  Writing complex constants.
319 * Operations on Complex::       Projection, conjugation, decomposition.
320 * Integer Division::            Integer division with guaranteed rounding.
321 * Parsing of Numbers::          Converting strings to numbers.
322 * System V Number Conversion::  An archaic way to convert numbers to strings.
323
324 Date and Time
325
326 * Processor Time::              Measures processor time used by a program.
327 * Calendar Time::               Manipulation of ``real'' dates and times.
328 * Setting an Alarm::            Sending a signal after a specified time.
329 * Sleeping::                    Waiting for a period of time.
330 * Resource Usage::              Measuring various resources used.
331 * Limits on Resources::         Specifying limits on resource usage.
332 * Priority::                    Reading or setting process run priority.
333
334 Non-Local Exits
335
336 * Intro: Non-Local Intro.        When and how to use these facilities.
337 * Details: Non-Local Details.   Functions for nonlocal exits.
338 * Non-Local Exits and Signals::  Portability issues.
339
340 Signal Handling
341
342 * Concepts of Signals::         Introduction to the signal facilities.
343 * Standard Signals::            Particular kinds of signals with
344                                  standard names and meanings.
345 * Signal Actions::              Specifying what happens when a
346                                  particular signal is delivered.
347 * Defining Handlers::           How to write a signal handler function.
348 * Interrupted Primitives::      Signal handlers affect use of @code{open},
349                                  @code{read}, @code{write} and other functions.
350 * Generating Signals::          How to send a signal to a process.
351 * Blocking Signals::            Making the system hold signals temporarily.
352 * Waiting for a Signal::        Suspending your program until a signal
353                                  arrives.
354 * Signal Stack::                Using a Separate Signal Stack.
355 * BSD Signal Handling::         Additional functions for backward
356                                  compatibility with BSD.
357
358 Process Startup
359
360 * Program Arguments::           Parsing your program's command-line arguments.
361 * Environment Variables::       How to access parameters inherited from
362                                  a parent process.
363 * Program Termination::         How to cause a process to terminate and
364                                  return status information to its parent.
365
366 Processes
367
368 * Running a Command::           The easy way to run another program.
369 * Process Creation Concepts::   An overview of the hard way to do it.
370 * Process Identification::      How to get the process ID of a process.
371 * Creating a Process::          How to fork a child process.
372 * Executing a File::            How to make a process execute another program.
373 * Process Completion::          How to tell when a child process has completed.
374 * Process Completion Status::   How to interpret the status value
375                                  returned from a child process.
376 * BSD Wait Functions::          More functions, for backward compatibility.
377 * Process Creation Example::    A complete example program.
378
379 Job Control
380
381 * Concepts of Job Control::     Jobs can be controlled by a shell.
382 * Job Control is Optional::     Not all POSIX systems support job control.
383 * Controlling Terminal::        How a process gets its controlling terminal.
384 * Access to the Terminal::      How processes share the controlling terminal.
385 * Orphaned Process Groups::     Jobs left after the user logs out.
386 * Implementing a Shell::        What a shell must do to implement job control.
387 * Functions for Job Control::   Functions to control process groups.
388
389 Name Service Switch
390
391 * NSS Basics::                  What is this NSS good for.
392 * NSS Configuration File::      Configuring NSS.
393 * NSS Module Internals::        How does it work internally.
394 * Extending NSS::               What to do to add services or databases.
395
396 Users and Groups
397
398 * User and Group IDs::          Each user has a unique numeric ID;
399                                  likewise for groups.
400 * Process Persona::             The user IDs and group IDs of a process.
401 * Why Change Persona::          Why a program might need to change
402                                  its user and/or group IDs.
403 * How Change Persona::          Changing the user and group IDs.
404 * Reading Persona::             How to examine the user and group IDs.
405
406 * Setting User ID::             Functions for setting the user ID.
407 * Setting Groups::              Functions for setting the group IDs.
408
409 * Enable/Disable Setuid::       Turning setuid access on and off.
410 * Setuid Program Example::      The pertinent parts of one sample program.
411 * Tips for Setuid::             How to avoid granting unlimited access.
412
413 * Who Logged In::               Getting the name of the user who logged in,
414                                  or of the real user ID of the current process.
415
416 * User Accounting Database::    Keeping information about users and various
417                                  actions in databases.
418
419 * User Database::               Functions and data structures for
420                                  accessing the user database.
421 * Group Database::              Functions and data structures for
422                                  accessing the group database.
423 * Database Example::            Example program showing the use of database
424                                  inquiry functions.
425 * Netgroup Database::           Functions for accessing the netgroup database.
426
427 System Information
428
429 * Host Identification::         Determining the name of the machine.
430 * Hardware/Software Type ID::   Determining the hardware type of the
431                                  machine and what operating system it is
432                                  running.
433 * Filesystem handling::         Which is mounted and/or available?
434
435 System Configuration
436
437 * General Limits::           Constants and functions that describe
438                                 various process-related limits that have
439                                 one uniform value for any given machine.
440 * System Options::           Optional POSIX features.
441 * Version Supported::        Version numbers of POSIX.1 and POSIX.2.
442 * Sysconf::                  Getting specific configuration values
443                                 of general limits and system options.
444 * Minimums::                 Minimum values for general limits.
445
446 * Limits for Files::         Size limitations that pertain to individual files.
447                                 These can vary between file systems
448                                 or even from file to file.
449 * Options for Files::        Optional features that some files may support.
450 * File Minimums::            Minimum values for file limits.
451 * Pathconf::                 Getting the limit values for a particular file.
452
453 * Utility Limits::           Capacity limits of some POSIX.2 utility programs.
454 * Utility Minimums::         Minimum allowable values of those limits.
455
456 * String Parameters::        Getting the default search path.
457
458 POSIX Threads
459
460 * Basic Thread Operations::     Creating, terminating, and waiting for threads.
461 * Thread Attributes::           Tuning thread scheduling.
462 * Cancellation::                Stopping a thread before it's done.
463 * Cleanup Handlers::            Deallocating resources when a thread is
464                                   cancelled.
465 * Mutexes::                     One way to synchronize threads.
466 * Condition Variables::         Another way.
467 * POSIX Semaphores::            And a third way.
468 * Thread-Specific Data::        Variables with different values in
469                                   different threads.
470 * Threads and Signal Handling:: Why you should avoid mixing the two, and
471                                   how to do it if you must.
472 * Miscellaneous Thread Functions:: A grab bag of utility routines.
473
474 Language Features
475
476 * Consistency Checking::        Using @code{assert} to abort if
477                                  something ``impossible'' happens.
478 * Variadic Functions::          Defining functions with varying numbers
479                                  of args.
480 * Null Pointer Constant::       The macro @code{NULL}.
481 * Important Data Types::        Data types for object sizes.
482 * Data Type Measurements::      Parameters of data type representations.
483
484 Installation
485
486 * Tools for Installation::      We recommend using these tools to build.
487 * Supported Configurations::    What systems the GNU C library runs on.
488 * Tips for Installation::       Useful hints for the installation.
489 * Reporting Bugs::              How to report bugs (if you want to
490                                 get them fixed) and other troubles
491                                 you may have with the GNU C library.
492
493 Maintenance
494
495 * Source Layout::         How to add new functions or header files
496                              to the GNU C library.
497 * Porting::               How to port the GNU C library to
498                              a new machine or operating system.
499 @end menu