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
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
14 * Searching and Sorting:: General searching and sorting functions.
15 * Pattern Matching:: Matching shell ``globs'' and regular
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
23 * Sockets:: A more complicated IPC mechanism, with
25 * Low-Level Terminal Interface:: How to change the characteristics of a
27 * Mathematics:: Math functions, useful constants, random
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
36 * Processes:: How to create processes and run other
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
43 * System Configuration:: Parameters describing operating system
48 * POSIX Threads:: The standard threads library.
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.
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.
69 --- The Detailed Node Listing ---
73 * Getting Started:: What this manual is for and how to use it.
74 * Standards and Portability:: Standards and sources upon which the GNU
76 * Using the Library:: Some practical uses for the library.
77 * Roadmap to the Manual:: Overview of the remaining chapters in
80 Standards and Portability
82 * ISO C:: The international standard for the C
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.
92 * Header Files:: How to include the header files in your
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.
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.
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
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.
120 Unconstrained Allocation
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
128 * Allocating Cleared Space:: Use @code{calloc} to allocate a
130 * Efficiency and Malloc:: Efficiency considerations in use of
132 * Aligned Memory Blocks:: Allocating specially aligned memory:
133 @code{memalign} and @code{valloc}.
134 * Malloc Tunable Parameters:: Use @code{mallopt} to adjust allocation
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.
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?
152 * Creating Obstacks:: How to declare an obstack in your program.
153 * Preparing for Obstacks:: Preparations needed before you can
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::
168 Variable Size Automatic
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.
179 * Classification of Characters:: Testing whether characters are
180 letters, digits, punctuation, etc.
182 * Case Conversion:: Case mapping, and the like.
184 String and Array Utilities
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
192 * String/Array Comparison:: Functions for byte-wise and character-wise
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
198 * Encode Binary Data:: Encoding and Decoding of Binary Data.
199 * Argz and Envz Vectors:: Null-separated string vectors.
201 Argz and Envz Vectors
203 * Argz Functions:: Operations on argz vectors.
204 * Envz Functions:: Additional operations on environment vectors.
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
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".
222 * Effects of Locale:: Actions affected by the choice of
224 * Choosing Locale:: How the user specifies a locale.
225 * Locale Categories:: Different purposes for which you can
227 * Setting the Locale:: How a program specifies the locale
228 with library functions.
229 * Standard Locales:: Locale names available on all systems.
230 * Numeric Formatting:: How to format numbers according to the
235 * General Numeric:: Parameters for formatting numbers and
237 * Currency Symbol:: How to print the symbol that identifies an
238 amount of money (e.g. @samp{$}).
239 * Sign of Money Amount:: How to print the (positive or negative) sign
240 for a monetary amount, if one exists.
244 * Message catalogs a la X/Open:: The @code{catgets} family of functions.
245 * The Uniforum approach:: The @code{gettext} family of functions.
247 Message catalogs a la X/Open
249 * The catgets Functions:: The @code{catgets} function family.
250 * The message catalog files:: Format of the message catalog files.
251 * The gencat program:: How to generate message catalogs files which
252 can be used by the functions.
253 * Common Usage:: How to use the @code{catgets} interface.
255 The Uniforum approach
257 * Message catalogs with gettext:: The @code{gettext} family of functions.
258 * Helper programs for gettext:: Programs to handle message catalogs
261 Message catalogs with gettext
263 * Translation with gettext:: What has to be done to translate a message.
264 * Locating gettext catalog:: How to determine which catalog to be used.
265 * Using gettextized software:: The possibilities of the user to influence
266 the way @code{gettext} works.
268 Searching and Sorting
270 * Comparison Functions:: Defining how to compare two objects.
271 Since the sort and search facilities
272 are general, you have to specify the
274 * Array Search Function:: The @code{bsearch} function.
275 * Array Sort Function:: The @code{qsort} function.
276 * Search/Sort Example:: An example program.
277 * Hash Search Function:: The @code{hsearch} function.
278 * Tree Search Function:: The @code{tsearch} function.
282 * Wildcard Matching:: Matching a wildcard pattern against a single string.
283 * Globbing:: Finding the files that match a wildcard pattern.
284 * Regular Expressions:: Matching regular expressions against strings.
285 * Word Expansion:: Expanding shell variables, nested commands,
286 arithmetic, and wildcards.
287 This is what the shell does with shell commands.
291 * Calling Glob:: Basic use of @code{glob}.
292 * Flags for Globbing:: Flags that enable various options in @code{glob}.
293 * More Flags for Globbing:: GNU specific extensions to @code{glob}.
297 * POSIX Regexp Compilation:: Using @code{regcomp} to prepare to match.
298 * Flags for POSIX Regexps:: Syntax variations for @code{regcomp}.
299 * Matching POSIX Regexps:: Using @code{regexec} to match the compiled
300 pattern that you get from @code{regcomp}.
301 * Regexp Subexpressions:: Finding which parts of the string were matched.
302 * Subexpression Complications:: Find points of which parts were matched.
303 * Regexp Cleanup:: Freeing storage; reporting errors.
307 * Expansion Stages:: What word expansion does to a string.
308 * Calling Wordexp:: How to call @code{wordexp}.
309 * Flags for Wordexp:: Options you can enable in @code{wordexp}.
310 * Wordexp Example:: A sample program that does word expansion.
314 * I/O Concepts:: Some basic information and terminology.
315 * File Names:: How to refer to a file.
319 * Streams and File Descriptors:: The GNU Library provides two ways
320 to access the contents of files.
321 * File Position:: The number of bytes from the
322 beginning of the file.
326 * Directories:: Directories contain entries for files.
327 * File Name Resolution:: A file name specifies how to look up a file.
328 * File Name Errors:: Error conditions relating to file names.
329 * File Name Portability:: File name portability and syntax issues.
333 * Streams:: About the data type representing a stream.
334 * Standard Streams:: Streams to the standard input and output
335 devices are created for you.
336 * Opening Streams:: How to create a stream to talk to a file.
337 * Closing Streams:: Close a stream when you are finished with it.
338 * Simple Output:: Unformatted output by characters and lines.
339 * Character Input:: Unformatted input by characters and words.
340 * Line Input:: Reading a line or a record from a stream.
341 * Unreading:: Peeking ahead/pushing back input just read.
342 * Block Input/Output:: Input and output operations on blocks of data.
343 * Formatted Output:: @code{printf} and related functions.
344 * Customizing Printf:: You can define new conversion specifiers for
345 @code{printf} and friends.
346 * Formatted Input:: @code{scanf} and related functions.
347 * EOF and Errors:: How you can tell if an I/O error happens.
348 * Binary Streams:: Some systems distinguish between text files
350 * File Positioning:: About random-access streams.
351 * Portable Positioning:: Random access on peculiar ISO C systems.
352 * Stream Buffering:: How to control buffering of streams.
353 * Other Kinds of Streams:: Streams that do not necessarily correspond
355 * Formatted Messages:: Print strictly formatted messages.
359 * Unreading Idea:: An explanation of unreading with pictures.
360 * How Unread:: How to call @code{ungetc} to do unreading.
364 * Formatted Output Basics:: Some examples to get you started.
365 * Output Conversion Syntax:: General syntax of conversion
367 * Table of Output Conversions:: Summary of output conversions and
369 * Integer Conversions:: Details about formatting of integers.
370 * Floating-Point Conversions:: Details about formatting of
371 floating-point numbers.
372 * Other Output Conversions:: Details about formatting of strings,
373 characters, pointers, and the like.
374 * Formatted Output Functions:: Descriptions of the actual functions.
375 * Dynamic Output:: Functions that allocate memory for the output.
376 * Variable Arguments Output:: @code{vprintf} and friends.
377 * Parsing a Template String:: What kinds of args does a given template
379 * Example of Parsing:: Sample program using @code{parse_printf_format}.
383 * Registering New Conversions:: Using @code{register_printf_function}
384 to register a new output conversion.
385 * Conversion Specifier Options:: The handler must be able to get
386 the options specified in the
387 template when it is called.
388 * Defining the Output Handler:: Defining the handler and arginfo
389 functions that are passed as arguments
390 to @code{register_printf_function}.
391 * Printf Extension Example:: How to define a @code{printf}
393 * Predefined Printf Handlers:: Predefined @code{printf} handlers.
397 * Formatted Input Basics:: Some basics to get you started.
398 * Input Conversion Syntax:: Syntax of conversion specifications.
399 * Table of Input Conversions:: Summary of input conversions and what they do.
400 * Numeric Input Conversions:: Details of conversions for reading numbers.
401 * String Input Conversions:: Details of conversions for reading strings.
402 * Dynamic String Input:: String conversions that @code{malloc} the buffer.
403 * Other Input Conversions:: Details of miscellaneous other conversions.
404 * Formatted Input Functions:: Descriptions of the actual functions.
405 * Variable Arguments Input:: @code{vscanf} and friends.
409 * Buffering Concepts:: Terminology is defined here.
410 * Flushing Buffers:: How to ensure that output buffers are flushed.
411 * Controlling Buffering:: How to specify what kind of buffering to use.
413 Other Kinds of Streams
415 * String Streams:: Streams that get data from or put data in
416 a string or memory buffer.
417 * Obstack Streams:: Streams that store data in an obstack.
418 * Custom Streams:: Defining your own streams with an arbitrary
419 input data source and/or output data sink.
423 * Streams and Cookies:: The @dfn{cookie} records where to fetch or
424 store data that is read or written.
425 * Hook Functions:: How you should define the four @dfn{hook
426 functions} that a custom stream needs.
430 * Printing Formatted Messages:: The @code{fmtmsg} function.
431 * Adding Severity Classes:: Add more severity classes.
432 * Example:: How to use @code{fmtmsg} and @code{addseverity}.
436 * Opening and Closing Files:: How to open and close file
438 * Truncating Files:: Change the size of a file.
439 * I/O Primitives:: Reading and writing data.
440 * File Position Primitive:: Setting a descriptor's file
442 * Descriptors and Streams:: Converting descriptor to stream
444 * Stream/Descriptor Precautions:: Precautions needed if you use both
445 descriptors and streams.
446 * Scatter-Gather:: Fast I/O to discontinous buffers.
447 * Memory-mapped I/O:: Using files like memory.
448 * Waiting for I/O:: How to check for input or output
449 on multiple file descriptors.
450 * Synchronizing I/O:: Making sure all I/O actions completed.
451 * Asynchronous I/O:: Perform I/O in parallel.
452 * Control Operations:: Various other operations on file
454 * Duplicating Descriptors:: Fcntl commands for duplicating
456 * Descriptor Flags:: Fcntl commands for manipulating
457 flags associated with file
459 * File Status Flags:: Fcntl commands for manipulating
460 flags associated with open files.
461 * File Locks:: Fcntl commands for implementing
463 * Interrupt Input:: Getting an asynchronous signal when
465 * IOCTLs:: Generic I/O Control operations.
467 Stream/Descriptor Precautions
469 * Linked Channels:: Dealing with channels sharing a file position.
470 * Independent Channels:: Dealing with separately opened, unlinked channels.
471 * Cleaning Streams:: Cleaning a stream makes it safe to use
476 * Asynchronous Reads/Writes:: Asynchronous Read and Write Operations.
477 * Status of AIO Operations:: Getting the Status of AIO Operations.
478 * Synchronizing AIO Operations:: Getting into a consistent state.
479 * Cancel AIO Operations:: Cancelation of AIO Operations.
480 * Configuration of AIO:: How to optimize the AIO implementation.
484 * Access Modes:: Whether the descriptor can read or write.
485 * Open-time Flags:: Details of @code{open}.
486 * Operating Modes:: Special modes to control I/O operations.
487 * Getting File Status Flags:: Fetching and changing these flags.
489 File System Interface
491 * Working Directory:: This is used to resolve relative
493 * Accessing Directories:: Finding out what files a directory
495 * Working on Directory Trees:: Apply actions to all files or a selectable
496 subset of a directory hierarchy.
497 * Hard Links:: Adding alternate names to a file.
498 * Symbolic Links:: A file that ``points to'' a file name.
499 * Deleting Files:: How to delete a file, and what that means.
500 * Renaming Files:: Changing a file's name.
501 * Creating Directories:: A system call just for creating a directory.
502 * File Attributes:: Attributes of individual files.
503 * Making Special Files:: How to create special files.
504 * Temporary Files:: Naming and creating temporary files.
506 Accessing Directories
508 * Directory Entries:: Format of one directory entry.
509 * Opening a Directory:: How to open a directory stream.
510 * Reading/Closing Directory:: How to read directory entries from the stream.
511 * Simple Directory Lister:: A very simple directory listing program.
512 * Random Access Directory:: Rereading part of the directory
513 already read with the same stream.
514 * Scanning Directory Content:: Get entries for user selected subset of
515 contents in given directory.
516 * Simple Directory Lister Mark II:: Revised version of the program.
520 * Attribute Meanings:: The names of the file attributes,
521 and what their values mean.
522 * Reading Attributes:: How to read the attributes of a file.
523 * Testing File Type:: Distinguishing ordinary files,
524 directories, links...
525 * File Owner:: How ownership for new files is determined,
526 and how to change it.
527 * Permission Bits:: How information about a file's access
529 * Access Permission:: How the system decides who can access a file.
530 * Setting Permissions:: How permissions for new files are assigned,
531 and how to change them.
532 * Testing File Access:: How to find out if your process can
534 * File Times:: About the time attributes of a file.
538 * Creating a Pipe:: Making a pipe with the @code{pipe} function.
539 * Pipe to a Subprocess:: Using a pipe to communicate with a
541 * FIFO Special Files:: Making a FIFO special file.
542 * Pipe Atomicity:: When pipe (or FIFO) I/O is atomic.
546 * Socket Concepts:: Basic concepts you need to know about.
547 * Communication Styles::Stream communication, datagrams, and other styles.
548 * Socket Addresses:: How socket names (``addresses'') work.
549 * Interface Naming:: Identifying specific network interfaces.
550 * Local Namespace:: Details about the local namespace.
551 * Internet Namespace:: Details about the Internet namespace.
552 * Misc Namespaces:: Other namespaces not documented fully here.
553 * Open/Close Sockets:: Creating sockets and destroying them.
554 * Connections:: Operations on sockets with connection state.
555 * Datagrams:: Operations on datagram sockets.
556 * Inetd:: Inetd is a daemon that starts servers on request.
557 The most convenient way to write a server
558 is to make it work with Inetd.
559 * Socket Options:: Miscellaneous low-level socket options.
560 * Networks Database:: Accessing the database of network names.
564 * Address Formats:: About @code{struct sockaddr}.
565 * Setting Address:: Binding an address to a socket.
566 * Reading Address:: Reading the address of a socket.
570 * Concepts: Local Namespace Concepts. What you need to understand.
571 * Details: Local Namespace Details. Address format, symbolic names, etc.
572 * Example: Local Socket Example. Example of creating a socket.
576 * Internet Address Formats:: How socket addresses are specified in the
578 * Host Addresses:: All about host addresses of internet host.
579 * Protocols Database:: Referring to protocols by name.
580 * Ports:: Internet port numbers.
581 * Services Database:: Ports may have symbolic names.
582 * Byte Order:: Different hosts may use different byte
583 ordering conventions; you need to
584 canonicalize host address and port number.
585 * Inet Example:: Putting it all together.
589 * Abstract Host Addresses:: What a host number consists of.
590 * Data type: Host Address Data Type. Data type for a host number.
591 * Functions: Host Address Functions. Functions to operate on them.
592 * Names: Host Names. Translating host names to host numbers.
596 * Creating a Socket:: How to open a socket.
597 * Closing a Socket:: How to close a socket.
598 * Socket Pairs:: These are created like pipes.
602 * Connecting:: What the client program must do.
603 * Listening:: How a server program waits for requests.
604 * Accepting Connections:: What the server does when it gets a request.
605 * Who is Connected:: Getting the address of the
606 other side of a connection.
607 * Transferring Data:: How to send and receive data.
608 * Byte Stream Example:: An example program: a client for communicating
609 over a byte stream socket in the Internet namespace.
610 * Server Example:: A corresponding server program.
611 * Out-of-Band Data:: This is an advanced feature.
615 * Sending Data:: Sending data with @code{send}.
616 * Receiving Data:: Reading data with @code{recv}.
617 * Socket Data Options:: Using @code{send} and @code{recv}.
621 * Sending Datagrams:: Sending packets on a datagram socket.
622 * Receiving Datagrams:: Receiving packets on a datagram socket.
623 * Datagram Example:: An example program: packets sent over a
624 datagram socket in the local namespace.
625 * Example Receiver:: Another program, that receives those packets.
630 * Configuring Inetd::
634 * Socket Option Functions:: The basic functions for setting and getting
636 * Socket-Level Options:: Details of the options at the socket level.
638 Low-Level Terminal Interface
640 * Is It a Terminal:: How to determine if a file is a terminal
641 device, and what its name is.
642 * I/O Queues:: About flow control and typeahead.
643 * Canonical or Not:: Two basic styles of input processing.
644 * Terminal Modes:: How to examine and modify flags controlling
645 details of terminal I/O: echoing,
647 * Line Control:: Sending break sequences, clearing
648 terminal buffers @dots{}
649 * Noncanon Example:: How to read single characters without echo.
650 * Pseudo-Terminals:: How to open a pseudo-terminal.
654 * Mode Data Types:: The data type @code{struct termios} and
656 * Mode Functions:: Functions to read and set the terminal
658 * Setting Modes:: The right way to set terminal attributes
660 * Input Modes:: Flags controlling low-level input handling.
661 * Output Modes:: Flags controlling low-level output handling.
662 * Control Modes:: Flags controlling serial port behavior.
663 * Local Modes:: Flags controlling high-level input handling.
664 * Line Speed:: How to read and set the terminal line speed.
665 * Special Characters:: Characters that have special effects,
666 and how to change them.
667 * Noncanonical Input:: Controlling how long to wait for input.
671 * Editing Characters:: Special characters that terminate lines and
672 delete text, and other editing functions.
673 * Signal Characters:: Special characters that send or raise signals
674 to or for certain classes of processes.
675 * Start/Stop Characters:: Special characters that suspend or resume
677 * Other Special:: Other special characters for BSD systems:
678 they can discard output, and print status.
682 * Allocation:: Allocating a pseudo terminal.
683 * Pseudo-Terminal Pairs:: How to open both sides of a
684 pseudo-terminal in a single operation.
688 * Mathematical Constants:: Precise numeric values for often-used
690 * Trig Functions:: Sine, cosine, tangent, and friends.
691 * Inverse Trig Functions:: Arcsine, arccosine, etc.
692 * Exponents and Logarithms:: Also pow and sqrt.
693 * Hyperbolic Functions:: sinh, cosh, tanh, etc.
694 * Special Functions:: Bessel, gamma, erf.
695 * Pseudo-Random Numbers:: Functions for generating pseudo-random
697 * FP Function Optimizations:: Fast code or small code.
699 Pseudo-Random Numbers
701 * ISO Random:: @code{rand} and friends.
702 * BSD Random:: @code{random} and friends.
703 * SVID Random:: @code{drand48} and friends.
707 * Floating Point Numbers:: Basic concepts. IEEE 754.
708 * Floating Point Classes:: The five kinds of floating-point number.
709 * Floating Point Errors:: When something goes wrong in a calculation.
710 * Rounding:: Controlling how results are rounded.
711 * Control Functions:: Saving and restoring the FPU's state.
712 * Arithmetic Functions:: Fundamental operations provided by the library.
713 * Complex Numbers:: The types. Writing complex constants.
714 * Operations on Complex:: Projection, conjugation, decomposition.
715 * Integer Division:: Integer division with guaranteed rounding.
716 * Parsing of Numbers:: Converting strings to numbers.
717 * System V Number Conversion:: An archaic way to convert numbers to strings.
719 Floating Point Errors
721 * FP Exceptions:: IEEE 754 math exceptions and how to detect them.
722 * Infinity and NaN:: Special values returned by calculations.
723 * Status bit operations:: Checking for exceptions after the fact.
724 * Math Error Reporting:: How the math functions report errors.
728 * Absolute Value:: Absolute values of integers and floats.
729 * Normalization Functions:: Extracting exponents and putting them back.
730 * Rounding Functions:: Rounding floats to integers.
731 * Remainder Functions:: Remainders on division, precisely defined.
732 * FP Bit Twiddling:: Sign bit adjustment. Adding epsilon.
733 * FP Comparison Functions:: Comparisons without risk of exceptions.
734 * Misc FP Arithmetic:: Max, min, positive difference, multiply-add.
738 * Parsing of Integers:: Functions for conversion of integer values.
739 * Parsing of Floats:: Functions for conversion of floating-point
744 * Processor Time:: Measures processor time used by a program.
745 * Calendar Time:: Manipulation of ``real'' dates and times.
746 * Setting an Alarm:: Sending a signal after a specified time.
747 * Sleeping:: Waiting for a period of time.
748 * Resource Usage:: Measuring various resources used.
749 * Limits on Resources:: Specifying limits on resource usage.
750 * Priority:: Reading or setting process run priority.
754 * Basic CPU Time:: The @code{clock} function.
755 * Detailed CPU Time:: The @code{times} function.
759 * Simple Calendar Time:: Facilities for manipulating calendar time.
760 * High-Resolution Calendar:: A time representation with greater precision.
761 * Broken-down Time:: Facilities for manipulating local time.
762 * Formatting Date and Time:: Converting times to strings.
763 * TZ Variable:: How users specify the time zone.
764 * Time Zone Functions:: Functions to examine or specify the time zone.
765 * Time Functions Example:: An example program showing use of some of
770 * Intro: Non-Local Intro. When and how to use these facilities.
771 * Details: Non-Local Details. Functions for nonlocal exits.
772 * Non-Local Exits and Signals:: Portability issues.
776 * Concepts of Signals:: Introduction to the signal facilities.
777 * Standard Signals:: Particular kinds of signals with
778 standard names and meanings.
779 * Signal Actions:: Specifying what happens when a
780 particular signal is delivered.
781 * Defining Handlers:: How to write a signal handler function.
782 * Interrupted Primitives:: Signal handlers affect use of @code{open},
783 @code{read}, @code{write} and other functions.
784 * Generating Signals:: How to send a signal to a process.
785 * Blocking Signals:: Making the system hold signals temporarily.
786 * Waiting for a Signal:: Suspending your program until a signal
788 * Signal Stack:: Using a Separate Signal Stack.
789 * BSD Signal Handling:: Additional functions for backward
790 compatibility with BSD.
794 * Kinds of Signals:: Some examples of what can cause a signal.
795 * Signal Generation:: Concepts of why and how signals occur.
796 * Delivery of Signal:: Concepts of what a signal does to the
801 * Program Error Signals:: Used to report serious program errors.
802 * Termination Signals:: Used to interrupt and/or terminate the
804 * Alarm Signals:: Used to indicate expiration of timers.
805 * Asynchronous I/O Signals:: Used to indicate input is available.
806 * Job Control Signals:: Signals used to support job control.
807 * Operation Error Signals:: Used to report operational system errors.
808 * Miscellaneous Signals:: Miscellaneous Signals.
809 * Signal Messages:: Printing a message describing a signal.
813 * Basic Signal Handling:: The simple @code{signal} function.
814 * Advanced Signal Handling:: The more powerful @code{sigaction} function.
815 * Signal and Sigaction:: How those two functions interact.
816 * Sigaction Function Example:: An example of using the sigaction function.
817 * Flags for Sigaction:: Specifying options for signal handling.
818 * Initial Signal Actions:: How programs inherit signal actions.
822 * Handler Returns:: Handlers that return normally, and what
824 * Termination in Handler:: How handler functions terminate a program.
825 * Longjmp in Handler:: Nonlocal transfer of control out of a
827 * Signals in Handler:: What happens when signals arrive while
828 the handler is already occupied.
829 * Merged Signals:: When a second signal arrives before the
831 * Nonreentrancy:: Do not call any functions unless you know they
832 are reentrant with respect to signals.
833 * Atomic Data Access:: A single handler can run in the middle of
834 reading or writing a single object.
838 * Non-atomic Example:: A program illustrating interrupted access.
839 * Types: Atomic Types. Data types that guarantee no interruption.
840 * Usage: Atomic Usage. Proving that interruption is harmless.
844 * Signaling Yourself:: A process can send a signal to itself.
845 * Signaling Another Process:: Send a signal to another process.
846 * Permission for kill:: Permission for using @code{kill}.
847 * Kill Example:: Using @code{kill} for Communication.
851 * Why Block:: The purpose of blocking signals.
852 * Signal Sets:: How to specify which signals to
854 * Process Signal Mask:: Blocking delivery of signals to your
855 process during normal execution.
856 * Testing for Delivery:: Blocking to Test for Delivery of
858 * Blocking for Handler:: Blocking additional signals while a
859 handler is being run.
860 * Checking for Pending Signals:: Checking for Pending Signals
861 * Remembering a Signal:: How you can get almost the same
862 effect as blocking a signal, by
863 handling it and setting a flag
868 * Using Pause:: The simple way, using @code{pause}.
869 * Pause Problems:: Why the simple way is often not very good.
870 * Sigsuspend:: Reliably waiting for a specific signal.
874 * BSD Handler:: BSD Function to Establish a Handler.
875 * Blocking in BSD:: BSD Functions for Blocking Signals.
879 * Program Arguments:: Parsing your program's command-line arguments.
880 * Environment Variables:: How to access parameters inherited from
882 * Program Termination:: How to cause a process to terminate and
883 return status information to its parent.
887 * Argument Syntax:: By convention, options start with a hyphen.
888 * Parsing Program Arguments:: Ways to parse program options and arguments.
890 Parsing Program Arguments
892 * Getopt:: Parsing program options using @code{getopt}.
893 * Argp:: Parsing program options using @code{argp_parse}.
894 * Suboptions:: Some programs need more detailed options.
895 * Suboptions Example:: This shows how it could be done for @code{mount}.
897 Environment Variables
899 * Environment Access:: How to get and set the values of
900 environment variables.
901 * Standard Environment:: These environment variables have
902 standard interpretations.
906 * Normal Termination:: If a program calls @code{exit}, a
907 process terminates normally.
908 * Exit Status:: The @code{exit status} provides information
909 about why the process terminated.
910 * Cleanups on Exit:: A process can run its own cleanup
911 functions upon normal termination.
912 * Aborting a Program:: The @code{abort} function causes
913 abnormal program termination.
914 * Termination Internals:: What happens when a process terminates.
918 * Running a Command:: The easy way to run another program.
919 * Process Creation Concepts:: An overview of the hard way to do it.
920 * Process Identification:: How to get the process ID of a process.
921 * Creating a Process:: How to fork a child process.
922 * Executing a File:: How to make a process execute another program.
923 * Process Completion:: How to tell when a child process has completed.
924 * Process Completion Status:: How to interpret the status value
925 returned from a child process.
926 * BSD Wait Functions:: More functions, for backward compatibility.
927 * Process Creation Example:: A complete example program.
931 * Concepts of Job Control:: Jobs can be controlled by a shell.
932 * Job Control is Optional:: Not all POSIX systems support job control.
933 * Controlling Terminal:: How a process gets its controlling terminal.
934 * Access to the Terminal:: How processes share the controlling terminal.
935 * Orphaned Process Groups:: Jobs left after the user logs out.
936 * Implementing a Shell:: What a shell must do to implement job control.
937 * Functions for Job Control:: Functions to control process groups.
941 * Data Structures:: Introduction to the sample shell.
942 * Initializing the Shell:: What the shell must do to take
943 responsibility for job control.
944 * Launching Jobs:: Creating jobs to execute commands.
945 * Foreground and Background:: Putting a job in foreground of background.
946 * Stopped and Terminated Jobs:: Reporting job status.
947 * Continuing Stopped Jobs:: How to continue a stopped job in
948 the foreground or background.
949 * Missing Pieces:: Other parts of the shell.
951 Functions for Job Control
953 * Identifying the Terminal:: Determining the controlling terminal's name.
954 * Process Group Functions:: Functions for manipulating process groups.
955 * Terminal Access Functions:: Functions for controlling terminal access.
959 * NSS Basics:: What is this NSS good for.
960 * NSS Configuration File:: Configuring NSS.
961 * NSS Module Internals:: How does it work internally.
962 * Extending NSS:: What to do to add services or databases.
964 NSS Configuration File
966 * Services in the NSS configuration:: Service names in the NSS configuration.
967 * Actions in the NSS configuration:: React appropriately to the lookup result.
968 * Notes on NSS Configuration File:: Things to take care about while
973 * NSS Module Names:: Construction of the interface function of
975 * NSS Modules Interface:: Programming interface in the NSS module
980 * Adding another Service to NSS:: What is to do to add a new service.
981 * NSS Module Function Internals:: Guidelines for writing new NSS
986 * User and Group IDs:: Each user has a unique numeric ID;
988 * Process Persona:: The user IDs and group IDs of a process.
989 * Why Change Persona:: Why a program might need to change
990 its user and/or group IDs.
991 * How Change Persona:: Changing the user and group IDs.
992 * Reading Persona:: How to examine the user and group IDs.
994 * Setting User ID:: Functions for setting the user ID.
995 * Setting Groups:: Functions for setting the group IDs.
997 * Enable/Disable Setuid:: Turning setuid access on and off.
998 * Setuid Program Example:: The pertinent parts of one sample program.
999 * Tips for Setuid:: How to avoid granting unlimited access.
1001 * Who Logged In:: Getting the name of the user who logged in,
1002 or of the real user ID of the current process.
1004 * User Accounting Database:: Keeping information about users and various
1005 actions in databases.
1007 * User Database:: Functions and data structures for
1008 accessing the user database.
1009 * Group Database:: Functions and data structures for
1010 accessing the group database.
1011 * Database Example:: Example program showing the use of database
1013 * Netgroup Database:: Functions for accessing the netgroup database.
1015 User Accounting Database
1017 * Manipulating the Database:: Scanning and modifying the user
1018 accounting database.
1019 * XPG Functions:: A standardized way for doing the same thing.
1020 * Logging In and Out:: Functions from BSD that modify the user
1021 accounting database.
1025 * User Data Structure:: What each user record contains.
1026 * Lookup User:: How to look for a particular user.
1027 * Scanning All Users:: Scanning the list of all users, one by one.
1028 * Writing a User Entry:: How a program can rewrite a user's record.
1032 * Group Data Structure:: What each group record contains.
1033 * Lookup Group:: How to look for a particular group.
1034 * Scanning All Groups:: Scanning the list of all groups.
1038 * Netgroup Data:: Data in the Netgroup database and where
1040 * Lookup Netgroup:: How to look for a particular netgroup.
1041 * Netgroup Membership:: How to test for netgroup membership.
1045 * Host Identification:: Determining the name of the machine.
1046 * Hardware/Software Type ID:: Determining the hardware type of the
1047 machine and what operating system it is
1049 * Filesystem handling:: Which is mounted and/or available?
1051 System Configuration
1053 * General Limits:: Constants and functions that describe
1054 various process-related limits that have
1055 one uniform value for any given machine.
1056 * System Options:: Optional POSIX features.
1057 * Version Supported:: Version numbers of POSIX.1 and POSIX.2.
1058 * Sysconf:: Getting specific configuration values
1059 of general limits and system options.
1060 * Minimums:: Minimum values for general limits.
1062 * Limits for Files:: Size limitations that pertain to individual files.
1063 These can vary between file systems
1064 or even from file to file.
1065 * Options for Files:: Optional features that some files may support.
1066 * File Minimums:: Minimum values for file limits.
1067 * Pathconf:: Getting the limit values for a particular file.
1069 * Utility Limits:: Capacity limits of some POSIX.2 utility programs.
1070 * Utility Minimums:: Minimum allowable values of those limits.
1072 * String Parameters:: Getting the default search path.
1076 * Sysconf Definition:: Detailed specifications of @code{sysconf}.
1077 * Constants for Sysconf:: The list of parameters @code{sysconf} can read.
1078 * Examples of Sysconf:: How to use @code{sysconf} and the parameter
1079 macros properly together.
1083 * Basic Thread Operations:: Creating, terminating, and waiting for threads.
1084 * Thread Attributes:: Tuning thread scheduling.
1085 * Cancellation:: Stopping a thread before it's done.
1086 * Cleanup Handlers:: Deallocating resources when a thread is
1088 * Mutexes:: One way to synchronize threads.
1089 * Condition Variables:: Another way.
1090 * POSIX Semaphores:: And a third way.
1091 * Thread-Specific Data:: Variables with different values in
1093 * Threads and Signal Handling:: Why you should avoid mixing the two, and
1094 how to do it if you must.
1095 * Miscellaneous Thread Functions:: A grab bag of utility routines.
1099 * Consistency Checking:: Using @code{assert} to abort if
1100 something ``impossible'' happens.
1101 * Variadic Functions:: Defining functions with varying numbers
1103 * Null Pointer Constant:: The macro @code{NULL}.
1104 * Important Data Types:: Data types for object sizes.
1105 * Data Type Measurements:: Parameters of data type representations.
1109 * Why Variadic:: Reasons for making functions take
1111 * How Variadic:: How to define and call variadic functions.
1112 * Variadic Example:: A complete example.
1116 * Variadic Prototypes:: How to make a prototype for a function
1117 with variable arguments.
1118 * Receiving Arguments:: Steps you must follow to access the
1119 optional argument values.
1120 * How Many Arguments:: How to decide whether there are more arguments.
1121 * Calling Variadics:: Things you need to know about calling
1122 variable arguments functions.
1123 * Argument Macros:: Detailed specification of the macros
1124 for accessing variable arguments.
1125 * Old Varargs:: The pre-ISO way of defining variadic functions.
1127 Data Type Measurements
1129 * Width of Type:: How many bits does an integer type hold?
1130 * Range of Type:: What are the largest and smallest values
1131 that an integer type can hold?
1132 * Floating Type Macros:: Parameters that measure the floating point types.
1133 * Structure Measurement:: Getting measurements on structure types.
1135 Floating Type Macros
1137 * Floating Point Concepts:: Definitions of terminology.
1138 * Floating Point Parameters:: Details of specific macros.
1139 * IEEE Floating Point:: The measurements for one common
1144 * Tools for Installation:: We recommend using these tools to build.
1145 * Supported Configurations:: What systems the GNU C library runs on.
1146 * Tips for Installation:: Useful hints for the installation.
1147 * Reporting Bugs:: How to report bugs (if you want to
1148 get them fixed) and other troubles
1149 you may have with the GNU C library.
1153 * Source Layout:: How to add new functions or header files
1154 to the GNU C library.
1155 * Porting:: How to port the GNU C library to
1156 a new machine or operating system.
1160 * Hierarchy Conventions:: The layout of the @file{sysdeps} hierarchy.
1161 * Porting to Unix:: Porting the library to an average