@menu * Introduction:: Purpose of the GNU C Library. * Error Reporting:: How library functions report errors. * Memory Allocation:: Allocating memory dynamically and manipulating it via pointers. * Character Handling:: Character testing and conversion functions. * String and Array Utilities:: Utilities for copying and comparing strings and arrays. * Extended Characters:: Support for extended character sets. * Locales:: The country and language can affect the behavior of library functions. * Message Translation:: How to make the program speak the user's language. * Searching and Sorting:: General searching and sorting functions. * Pattern Matching:: Matching shell ``globs'' and regular expressions. * I/O Overview:: Introduction to the I/O facilities. * I/O on Streams:: Hign-level, portable I/O facilities. * Low-Level I/O:: Low-level, less portable I/O. * File System Interface:: Functions for manipulating files. * Pipes and FIFOs:: A simple interprocess communication mechanism. * Sockets:: A more complicated IPC mechanism, with networking support. * Low-Level Terminal Interface:: How to change the characteristics of a terminal device. * Mathematics:: Math functions, useful constants, random numbers. * Arithmetic:: Low level arithmetic functions. * Date and Time:: Functions for getting the date and time and formatting them nicely. * Non-Local Exits:: Jumping out of nested function calls. * Signal Handling:: How to send, block, and handle signals. * Process Startup:: Writing the beginning and end of your program. * Processes:: How to create processes and run other programs. * Job Control:: All about process groups and sessions. * Name Service Switch:: Accessing system databases. * Users and Groups:: How users are identified and classified. * System Information:: Getting information about the hardware and operating system. * System Configuration:: Parameters describing operating system limits. Add-ons * POSIX Threads:: The standard threads library. Appendices * Language Features:: C language features provided by the library. * Library Summary:: A summary showing the syntax, header file, and derivation of each library feature. * Installation:: How to install the GNU C library. * Maintenance:: How to enhance and port the GNU C Library. * Contributors:: Who wrote what parts of the GNU C library. * Copying:: The GNU Library General Public License says how you can copy and share the GNU C Library. Indices * Concept Index:: Index of concepts and names. * Type Index:: Index of types and type qualifiers. * Function Index:: Index of functions and function-like macros. * Variable Index:: Index of variables and variable-like macros. * File Index:: Index of programs and files. --- The Detailed Node Listing --- Introduction * Getting Started:: What this manual is for and how to use it. * Standards and Portability:: Standards and sources upon which the GNU C library is based. * Using the Library:: Some practical uses for the library. * Roadmap to the Manual:: Overview of the remaining chapters in this manual. Standards and Portability * ISO C:: The international standard for the C programming language. * POSIX:: The ISO/IEC 9945 (aka IEEE 1003) standards for operating systems. * Berkeley Unix:: BSD and SunOS. * SVID:: The System V Interface Description. * XPG:: The X/Open Portability Guide. Using the Library * Header Files:: How to include the header files in your programs. * Macro Definitions:: Some functions in the library may really be implemented as macros. * Reserved Names:: The C standard reserves some names for the library, and some for users. * Feature Test Macros:: How to control what names are defined. Error Reporting * Checking for Errors:: How errors are reported by library functions. * Error Codes:: Error code macros; all of these expand into integer constant values. * Error Messages:: Mapping error codes onto error messages. Memory Allocation * Memory Concepts:: An introduction to concepts and terminology. * Dynamic Allocation and C:: How to get different kinds of allocation in C. * Unconstrained Allocation:: The @code{malloc} facility allows fully general dynamic allocation. * Allocation Debugging:: Finding memory leaks and not freed memory. * Obstacks:: Obstacks are less general than malloc but more efficient and convenient. * Variable Size Automatic:: Allocation of variable-sized blocks of automatic storage that are freed when the calling function returns. Unconstrained Allocation * Basic Allocation:: Simple use of @code{malloc}. * Malloc Examples:: Examples of @code{malloc}. @code{xmalloc}. * Freeing after Malloc:: Use @code{free} to free a block you got with @code{malloc}. * Changing Block Size:: Use @code{realloc} to make a block bigger or smaller. * Allocating Cleared Space:: Use @code{calloc} to allocate a block and clear it. * Efficiency and Malloc:: Efficiency considerations in use of these functions. * Aligned Memory Blocks:: Allocating specially aligned memory: @code{memalign} and @code{valloc}. * Malloc Tunable Parameters:: Use @code{mallopt} to adjust allocation parameters. * Heap Consistency Checking:: Automatic checking for errors. * Hooks for Malloc:: You can use these hooks for debugging programs that use @code{malloc}. * Statistics of Malloc:: Getting information about how much memory your program is using. * Summary of Malloc:: Summary of @code{malloc} and related functions. Allocation Debugging * Tracing malloc:: How to install the tracing functionality. * Using the Memory Debugger:: Example programs excerpts. * Tips for the Memory Debugger:: Some more or less clever ideas. * Interpreting the traces:: What do all these lines mean? Obstacks * Creating Obstacks:: How to declare an obstack in your program. * Preparing for Obstacks:: Preparations needed before you can use obstacks. * Allocation in an Obstack:: Allocating objects in an obstack. * Freeing Obstack Objects:: Freeing objects in an obstack. * Obstack Functions:: The obstack functions are both functions and macros. * Growing Objects:: Making an object bigger by stages. * Extra Fast Growing:: Extra-high-efficiency (though more complicated) growing objects. * Status of an Obstack:: Inquiries about the status of an obstack. * Obstacks Data Alignment:: Controlling alignment of objects in obstacks. * Obstack Chunks:: How obstacks obtain and release chunks; efficiency considerations. * Summary of Obstacks:: Variable Size Automatic * Alloca Example:: Example of using @code{alloca}. * Advantages of Alloca:: Reasons to use @code{alloca}. * Disadvantages of Alloca:: Reasons to avoid @code{alloca}. * GNU C Variable-Size Arrays:: Only in GNU C, here is an alternative method of allocating dynamically and freeing automatically. Character Handling * Classification of Characters:: Testing whether characters are letters, digits, punctuation, etc. * Case Conversion:: Case mapping, and the like. String and Array Utilities * Representation of Strings:: Introduction to basic concepts. * String/Array Conventions:: Whether to use a string function or an arbitrary array function. * String Length:: Determining the length of a string. * Copying and Concatenation:: Functions to copy the contents of strings and arrays. * String/Array Comparison:: Functions for byte-wise and character-wise comparison. * Collation Functions:: Functions for collating strings. * Search Functions:: Searching for a specific element or substring. * Finding Tokens in a String:: Splitting a string into tokens by looking for delimiters. * Encode Binary Data:: Encoding and Decoding of Binary Data. * Argz and Envz Vectors:: Null-separated string vectors. Argz and Envz Vectors * Argz Functions:: Operations on argz vectors. * Envz Functions:: Additional operations on environment vectors. Extended Characters * Extended Char Intro:: Multibyte codes versus wide characters. * Locales and Extended Chars:: The locale selects the character codes. * Multibyte Char Intro:: How multibyte codes are represented. * Wide Char Intro:: How wide characters are represented. * Wide String Conversion:: Converting wide strings to multibyte code and vice versa. * Length of Char:: how many bytes make up one multibyte char. * Converting One Char:: Converting a string character by character. * Example of Conversion:: Example showing why converting one character at a time may be useful. * Shift State:: Multibyte codes with "shift characters". Locales * Effects of Locale:: Actions affected by the choice of locale. * Choosing Locale:: How the user specifies a locale. * Locale Categories:: Different purposes for which you can select a locale. * Setting the Locale:: How a program specifies the locale with library functions. * Standard Locales:: Locale names available on all systems. * Locale Information:: How to access the information for the locale. * Formatting Numbers:: A dedicated function to format numbers. Locale Information * The Lame Way to Locale Data:: ISO C's @code{localeconv}. * The Elegant and Fast Way:: X/Open's @code{nl_langinfo}. The Lame Way to Locale Data * General Numeric:: Parameters for formatting numbers and currency amounts. * Currency Symbol:: How to print the symbol that identifies an amount of money (e.g. @samp{$}). * Sign of Money Amount:: How to print the (positive or negative) sign for a monetary amount, if one exists. Message Translation * Message catalogs a la X/Open:: The @code{catgets} family of functions. * The Uniforum approach:: The @code{gettext} family of functions. Message catalogs a la X/Open * The catgets Functions:: The @code{catgets} function family. * The message catalog files:: Format of the message catalog files. * The gencat program:: How to generate message catalogs files which can be used by the functions. * Common Usage:: How to use the @code{catgets} interface. The Uniforum approach * Message catalogs with gettext:: The @code{gettext} family of functions. * Helper programs for gettext:: Programs to handle message catalogs for @code{gettext}. Message catalogs with gettext * Translation with gettext:: What has to be done to translate a message. * Locating gettext catalog:: How to determine which catalog to be used. * Using gettextized software:: The possibilities of the user to influence the way @code{gettext} works. Searching and Sorting * Comparison Functions:: Defining how to compare two objects. Since the sort and search facilities are general, you have to specify the ordering. * Array Search Function:: The @code{bsearch} function. * Array Sort Function:: The @code{qsort} function. * Search/Sort Example:: An example program. * Hash Search Function:: The @code{hsearch} function. * Tree Search Function:: The @code{tsearch} function. Pattern Matching * Wildcard Matching:: Matching a wildcard pattern against a single string. * Globbing:: Finding the files that match a wildcard pattern. * Regular Expressions:: Matching regular expressions against strings. * Word Expansion:: Expanding shell variables, nested commands, arithmetic, and wildcards. This is what the shell does with shell commands. Globbing * Calling Glob:: Basic use of @code{glob}. * Flags for Globbing:: Flags that enable various options in @code{glob}. * More Flags for Globbing:: GNU specific extensions to @code{glob}. Regular Expressions * POSIX Regexp Compilation:: Using @code{regcomp} to prepare to match. * Flags for POSIX Regexps:: Syntax variations for @code{regcomp}. * Matching POSIX Regexps:: Using @code{regexec} to match the compiled pattern that you get from @code{regcomp}. * Regexp Subexpressions:: Finding which parts of the string were matched. * Subexpression Complications:: Find points of which parts were matched. * Regexp Cleanup:: Freeing storage; reporting errors. Word Expansion * Expansion Stages:: What word expansion does to a string. * Calling Wordexp:: How to call @code{wordexp}. * Flags for Wordexp:: Options you can enable in @code{wordexp}. * Wordexp Example:: A sample program that does word expansion. * Tilde Expansion:: Details of how tilde expansion works. * Variable Substitution:: Different types of variable substitution. I/O Overview * I/O Concepts:: Some basic information and terminology. * File Names:: How to refer to a file. I/O Concepts * Streams and File Descriptors:: The GNU Library provides two ways to access the contents of files. * File Position:: The number of bytes from the beginning of the file. File Names * Directories:: Directories contain entries for files. * File Name Resolution:: A file name specifies how to look up a file. * File Name Errors:: Error conditions relating to file names. * File Name Portability:: File name portability and syntax issues. I/O on Streams * Streams:: About the data type representing a stream. * Standard Streams:: Streams to the standard input and output devices are created for you. * Opening Streams:: How to create a stream to talk to a file. * Closing Streams:: Close a stream when you are finished with it. * Simple Output:: Unformatted output by characters and lines. * Character Input:: Unformatted input by characters and words. * Line Input:: Reading a line or a record from a stream. * Unreading:: Peeking ahead/pushing back input just read. * Block Input/Output:: Input and output operations on blocks of data. * Formatted Output:: @code{printf} and related functions. * Customizing Printf:: You can define new conversion specifiers for @code{printf} and friends. * Formatted Input:: @code{scanf} and related functions. * EOF and Errors:: How you can tell if an I/O error happens. * Binary Streams:: Some systems distinguish between text files and binary files. * File Positioning:: About random-access streams. * Portable Positioning:: Random access on peculiar ISO C systems. * Stream Buffering:: How to control buffering of streams. * Other Kinds of Streams:: Streams that do not necessarily correspond to an open file. * Formatted Messages:: Print strictly formatted messages. Unreading * Unreading Idea:: An explanation of unreading with pictures. * How Unread:: How to call @code{ungetc} to do unreading. Formatted Output * Formatted Output Basics:: Some examples to get you started. * Output Conversion Syntax:: General syntax of conversion specifications. * Table of Output Conversions:: Summary of output conversions and what they do. * Integer Conversions:: Details about formatting of integers. * Floating-Point Conversions:: Details about formatting of floating-point numbers. * Other Output Conversions:: Details about formatting of strings, characters, pointers, and the like. * Formatted Output Functions:: Descriptions of the actual functions. * Dynamic Output:: Functions that allocate memory for the output. * Variable Arguments Output:: @code{vprintf} and friends. * Parsing a Template String:: What kinds of args does a given template call for? * Example of Parsing:: Sample program using @code{parse_printf_format}. Customizing Printf * Registering New Conversions:: Using @code{register_printf_function} to register a new output conversion. * Conversion Specifier Options:: The handler must be able to get the options specified in the template when it is called. * Defining the Output Handler:: Defining the handler and arginfo functions that are passed as arguments to @code{register_printf_function}. * Printf Extension Example:: How to define a @code{printf} handler function. * Predefined Printf Handlers:: Predefined @code{printf} handlers. Formatted Input * Formatted Input Basics:: Some basics to get you started. * Input Conversion Syntax:: Syntax of conversion specifications. * Table of Input Conversions:: Summary of input conversions and what they do. * Numeric Input Conversions:: Details of conversions for reading numbers. * String Input Conversions:: Details of conversions for reading strings. * Dynamic String Input:: String conversions that @code{malloc} the buffer. * Other Input Conversions:: Details of miscellaneous other conversions. * Formatted Input Functions:: Descriptions of the actual functions. * Variable Arguments Input:: @code{vscanf} and friends. Stream Buffering * Buffering Concepts:: Terminology is defined here. * Flushing Buffers:: How to ensure that output buffers are flushed. * Controlling Buffering:: How to specify what kind of buffering to use. Other Kinds of Streams * String Streams:: Streams that get data from or put data in a string or memory buffer. * Obstack Streams:: Streams that store data in an obstack. * Custom Streams:: Defining your own streams with an arbitrary input data source and/or output data sink. Custom Streams * Streams and Cookies:: The @dfn{cookie} records where to fetch or store data that is read or written. * Hook Functions:: How you should define the four @dfn{hook functions} that a custom stream needs. Formatted Messages * Printing Formatted Messages:: The @code{fmtmsg} function. * Adding Severity Classes:: Add more severity classes. * Example:: How to use @code{fmtmsg} and @code{addseverity}. Low-Level I/O * Opening and Closing Files:: How to open and close file descriptors. * Truncating Files:: Change the size of a file. * I/O Primitives:: Reading and writing data. * File Position Primitive:: Setting a descriptor's file position. * Descriptors and Streams:: Converting descriptor to stream or vice-versa. * Stream/Descriptor Precautions:: Precautions needed if you use both descriptors and streams. * Scatter-Gather:: Fast I/O to discontinous buffers. * Memory-mapped I/O:: Using files like memory. * Waiting for I/O:: How to check for input or output on multiple file descriptors. * Synchronizing I/O:: Making sure all I/O actions completed. * Asynchronous I/O:: Perform I/O in parallel. * Control Operations:: Various other operations on file descriptors. * Duplicating Descriptors:: Fcntl commands for duplicating file descriptors. * Descriptor Flags:: Fcntl commands for manipulating flags associated with file descriptors. * File Status Flags:: Fcntl commands for manipulating flags associated with open files. * File Locks:: Fcntl commands for implementing file locking. * Interrupt Input:: Getting an asynchronous signal when input arrives. * IOCTLs:: Generic I/O Control operations. Stream/Descriptor Precautions * Linked Channels:: Dealing with channels sharing a file position. * Independent Channels:: Dealing with separately opened, unlinked channels. * Cleaning Streams:: Cleaning a stream makes it safe to use another channel. Asynchronous I/O * Asynchronous Reads/Writes:: Asynchronous Read and Write Operations. * Status of AIO Operations:: Getting the Status of AIO Operations. * Synchronizing AIO Operations:: Getting into a consistent state. * Cancel AIO Operations:: Cancelation of AIO Operations. * Configuration of AIO:: How to optimize the AIO implementation. File Status Flags * Access Modes:: Whether the descriptor can read or write. * Open-time Flags:: Details of @code{open}. * Operating Modes:: Special modes to control I/O operations. * Getting File Status Flags:: Fetching and changing these flags. File System Interface * Working Directory:: This is used to resolve relative file names. * Accessing Directories:: Finding out what files a directory contains. * Working on Directory Trees:: Apply actions to all files or a selectable subset of a directory hierarchy. * Hard Links:: Adding alternate names to a file. * Symbolic Links:: A file that ``points to'' a file name. * Deleting Files:: How to delete a file, and what that means. * Renaming Files:: Changing a file's name. * Creating Directories:: A system call just for creating a directory. * File Attributes:: Attributes of individual files. * Making Special Files:: How to create special files. * Temporary Files:: Naming and creating temporary files. Accessing Directories * Directory Entries:: Format of one directory entry. * Opening a Directory:: How to open a directory stream. * Reading/Closing Directory:: How to read directory entries from the stream. * Simple Directory Lister:: A very simple directory listing program. * Random Access Directory:: Rereading part of the directory already read with the same stream. * Scanning Directory Content:: Get entries for user selected subset of contents in given directory. * Simple Directory Lister Mark II:: Revised version of the program. File Attributes * Attribute Meanings:: The names of the file attributes, and what their values mean. * Reading Attributes:: How to read the attributes of a file. * Testing File Type:: Distinguishing ordinary files, directories, links... * File Owner:: How ownership for new files is determined, and how to change it. * Permission Bits:: How information about a file's access mode is stored. * Access Permission:: How the system decides who can access a file. * Setting Permissions:: How permissions for new files are assigned, and how to change them. * Testing File Access:: How to find out if your process can access a file. * File Times:: About the time attributes of a file. * File Size:: Manually changing the size of a file. Pipes and FIFOs * Creating a Pipe:: Making a pipe with the @code{pipe} function. * Pipe to a Subprocess:: Using a pipe to communicate with a child process. * FIFO Special Files:: Making a FIFO special file. * Pipe Atomicity:: When pipe (or FIFO) I/O is atomic. Sockets * Socket Concepts:: Basic concepts you need to know about. * Communication Styles::Stream communication, datagrams, and other styles. * Socket Addresses:: How socket names (``addresses'') work. * Interface Naming:: Identifying specific network interfaces. * Local Namespace:: Details about the local namespace. * Internet Namespace:: Details about the Internet namespace. * Misc Namespaces:: Other namespaces not documented fully here. * Open/Close Sockets:: Creating sockets and destroying them. * Connections:: Operations on sockets with connection state. * Datagrams:: Operations on datagram sockets. * Inetd:: Inetd is a daemon that starts servers on request. The most convenient way to write a server is to make it work with Inetd. * Socket Options:: Miscellaneous low-level socket options. * Networks Database:: Accessing the database of network names. Socket Addresses * Address Formats:: About @code{struct sockaddr}. * Setting Address:: Binding an address to a socket. * Reading Address:: Reading the address of a socket. Local Namespace * Concepts: Local Namespace Concepts. What you need to understand. * Details: Local Namespace Details. Address format, symbolic names, etc. * Example: Local Socket Example. Example of creating a socket. Internet Namespace * Internet Address Formats:: How socket addresses are specified in the Internet namespace. * Host Addresses:: All about host addresses of internet host. * Protocols Database:: Referring to protocols by name. * Ports:: Internet port numbers. * Services Database:: Ports may have symbolic names. * Byte Order:: Different hosts may use different byte ordering conventions; you need to canonicalize host address and port number. * Inet Example:: Putting it all together. Host Addresses * Abstract Host Addresses:: What a host number consists of. * Data type: Host Address Data Type. Data type for a host number. * Functions: Host Address Functions. Functions to operate on them. * Names: Host Names. Translating host names to host numbers. Open/Close Sockets * Creating a Socket:: How to open a socket. * Closing a Socket:: How to close a socket. * Socket Pairs:: These are created like pipes. Connections * Connecting:: What the client program must do. * Listening:: How a server program waits for requests. * Accepting Connections:: What the server does when it gets a request. * Who is Connected:: Getting the address of the other side of a connection. * Transferring Data:: How to send and receive data. * Byte Stream Example:: An example program: a client for communicating over a byte stream socket in the Internet namespace. * Server Example:: A corresponding server program. * Out-of-Band Data:: This is an advanced feature. Transferring Data * Sending Data:: Sending data with @code{send}. * Receiving Data:: Reading data with @code{recv}. * Socket Data Options:: Using @code{send} and @code{recv}. Datagrams * Sending Datagrams:: Sending packets on a datagram socket. * Receiving Datagrams:: Receiving packets on a datagram socket. * Datagram Example:: An example program: packets sent over a datagram socket in the local namespace. * Example Receiver:: Another program, that receives those packets. Inetd * Inetd Servers:: * Configuring Inetd:: Socket Options * Socket Option Functions:: The basic functions for setting and getting socket options. * Socket-Level Options:: Details of the options at the socket level. Low-Level Terminal Interface * Is It a Terminal:: How to determine if a file is a terminal device, and what its name is. * I/O Queues:: About flow control and typeahead. * Canonical or Not:: Two basic styles of input processing. * Terminal Modes:: How to examine and modify flags controlling details of terminal I/O: echoing, signals, editing. * Line Control:: Sending break sequences, clearing terminal buffers @dots{} * Noncanon Example:: How to read single characters without echo. * Pseudo-Terminals:: How to open a pseudo-terminal. Terminal Modes * Mode Data Types:: The data type @code{struct termios} and related types. * Mode Functions:: Functions to read and set the terminal attributes. * Setting Modes:: The right way to set terminal attributes reliably. * Input Modes:: Flags controlling low-level input handling. * Output Modes:: Flags controlling low-level output handling. * Control Modes:: Flags controlling serial port behavior. * Local Modes:: Flags controlling high-level input handling. * Line Speed:: How to read and set the terminal line speed. * Special Characters:: Characters that have special effects, and how to change them. * Noncanonical Input:: Controlling how long to wait for input. Special Characters * Editing Characters:: Special characters that terminate lines and delete text, and other editing functions. * Signal Characters:: Special characters that send or raise signals to or for certain classes of processes. * Start/Stop Characters:: Special characters that suspend or resume suspended output. * Other Special:: Other special characters for BSD systems: they can discard output, and print status. Pseudo-Terminals * Allocation:: Allocating a pseudo terminal. * Pseudo-Terminal Pairs:: How to open both sides of a pseudo-terminal in a single operation. Mathematics * Mathematical Constants:: Precise numeric values for often-used constants. * Trig Functions:: Sine, cosine, tangent, and friends. * Inverse Trig Functions:: Arcsine, arccosine, etc. * Exponents and Logarithms:: Also pow and sqrt. * Hyperbolic Functions:: sinh, cosh, tanh, etc. * Special Functions:: Bessel, gamma, erf. * Pseudo-Random Numbers:: Functions for generating pseudo-random numbers. * FP Function Optimizations:: Fast code or small code. Pseudo-Random Numbers * ISO Random:: @code{rand} and friends. * BSD Random:: @code{random} and friends. * SVID Random:: @code{drand48} and friends. Arithmetic * Floating Point Numbers:: Basic concepts. IEEE 754. * Floating Point Classes:: The five kinds of floating-point number. * Floating Point Errors:: When something goes wrong in a calculation. * Rounding:: Controlling how results are rounded. * Control Functions:: Saving and restoring the FPU's state. * Arithmetic Functions:: Fundamental operations provided by the library. * Complex Numbers:: The types. Writing complex constants. * Operations on Complex:: Projection, conjugation, decomposition. * Integer Division:: Integer division with guaranteed rounding. * Parsing of Numbers:: Converting strings to numbers. * System V Number Conversion:: An archaic way to convert numbers to strings. Floating Point Errors * FP Exceptions:: IEEE 754 math exceptions and how to detect them. * Infinity and NaN:: Special values returned by calculations. * Status bit operations:: Checking for exceptions after the fact. * Math Error Reporting:: How the math functions report errors. Arithmetic Functions * Absolute Value:: Absolute values of integers and floats. * Normalization Functions:: Extracting exponents and putting them back. * Rounding Functions:: Rounding floats to integers. * Remainder Functions:: Remainders on division, precisely defined. * FP Bit Twiddling:: Sign bit adjustment. Adding epsilon. * FP Comparison Functions:: Comparisons without risk of exceptions. * Misc FP Arithmetic:: Max, min, positive difference, multiply-add. Parsing of Numbers * Parsing of Integers:: Functions for conversion of integer values. * Parsing of Floats:: Functions for conversion of floating-point values. Date and Time * Processor Time:: Measures processor time used by a program. * Calendar Time:: Manipulation of ``real'' dates and times. * Setting an Alarm:: Sending a signal after a specified time. * Sleeping:: Waiting for a period of time. * Resource Usage:: Measuring various resources used. * Limits on Resources:: Specifying limits on resource usage. * Priority:: Reading or setting process run priority. Processor Time * Basic CPU Time:: The @code{clock} function. * Detailed CPU Time:: The @code{times} function. Calendar Time * Simple Calendar Time:: Facilities for manipulating calendar time. * High-Resolution Calendar:: A time representation with greater precision. * Broken-down Time:: Facilities for manipulating local time. * Formatting Date and Time:: Converting times to strings. * TZ Variable:: How users specify the time zone. * Time Zone Functions:: Functions to examine or specify the time zone. * Time Functions Example:: An example program showing use of some of the time functions. Non-Local Exits * Intro: Non-Local Intro. When and how to use these facilities. * Details: Non-Local Details. Functions for nonlocal exits. * Non-Local Exits and Signals:: Portability issues. Signal Handling * Concepts of Signals:: Introduction to the signal facilities. * Standard Signals:: Particular kinds of signals with standard names and meanings. * Signal Actions:: Specifying what happens when a particular signal is delivered. * Defining Handlers:: How to write a signal handler function. * Interrupted Primitives:: Signal handlers affect use of @code{open}, @code{read}, @code{write} and other functions. * Generating Signals:: How to send a signal to a process. * Blocking Signals:: Making the system hold signals temporarily. * Waiting for a Signal:: Suspending your program until a signal arrives. * Signal Stack:: Using a Separate Signal Stack. * BSD Signal Handling:: Additional functions for backward compatibility with BSD. Concepts of Signals * Kinds of Signals:: Some examples of what can cause a signal. * Signal Generation:: Concepts of why and how signals occur. * Delivery of Signal:: Concepts of what a signal does to the process. Standard Signals * Program Error Signals:: Used to report serious program errors. * Termination Signals:: Used to interrupt and/or terminate the program. * Alarm Signals:: Used to indicate expiration of timers. * Asynchronous I/O Signals:: Used to indicate input is available. * Job Control Signals:: Signals used to support job control. * Operation Error Signals:: Used to report operational system errors. * Miscellaneous Signals:: Miscellaneous Signals. * Signal Messages:: Printing a message describing a signal. Signal Actions * Basic Signal Handling:: The simple @code{signal} function. * Advanced Signal Handling:: The more powerful @code{sigaction} function. * Signal and Sigaction:: How those two functions interact. * Sigaction Function Example:: An example of using the sigaction function. * Flags for Sigaction:: Specifying options for signal handling. * Initial Signal Actions:: How programs inherit signal actions. Defining Handlers * Handler Returns:: Handlers that return normally, and what this means. * Termination in Handler:: How handler functions terminate a program. * Longjmp in Handler:: Nonlocal transfer of control out of a signal handler. * Signals in Handler:: What happens when signals arrive while the handler is already occupied. * Merged Signals:: When a second signal arrives before the first is handled. * Nonreentrancy:: Do not call any functions unless you know they are reentrant with respect to signals. * Atomic Data Access:: A single handler can run in the middle of reading or writing a single object. Atomic Data Access * Non-atomic Example:: A program illustrating interrupted access. * Types: Atomic Types. Data types that guarantee no interruption. * Usage: Atomic Usage. Proving that interruption is harmless. Generating Signals * Signaling Yourself:: A process can send a signal to itself. * Signaling Another Process:: Send a signal to another process. * Permission for kill:: Permission for using @code{kill}. * Kill Example:: Using @code{kill} for Communication. Blocking Signals * Why Block:: The purpose of blocking signals. * Signal Sets:: How to specify which signals to block. * Process Signal Mask:: Blocking delivery of signals to your process during normal execution. * Testing for Delivery:: Blocking to Test for Delivery of a Signal. * Blocking for Handler:: Blocking additional signals while a handler is being run. * Checking for Pending Signals:: Checking for Pending Signals * Remembering a Signal:: How you can get almost the same effect as blocking a signal, by handling it and setting a flag to be tested later. Waiting for a Signal * Using Pause:: The simple way, using @code{pause}. * Pause Problems:: Why the simple way is often not very good. * Sigsuspend:: Reliably waiting for a specific signal. BSD Signal Handling * BSD Handler:: BSD Function to Establish a Handler. * Blocking in BSD:: BSD Functions for Blocking Signals. Process Startup * Program Arguments:: Parsing your program's command-line arguments. * Environment Variables:: How to access parameters inherited from a parent process. * Program Termination:: How to cause a process to terminate and return status information to its parent. Program Arguments * Argument Syntax:: By convention, options start with a hyphen. * Parsing Program Arguments:: Ways to parse program options and arguments. Parsing Program Arguments * Getopt:: Parsing program options using @code{getopt}. * Argp:: Parsing program options using @code{argp_parse}. * Suboptions:: Some programs need more detailed options. * Suboptions Example:: This shows how it could be done for @code{mount}. Environment Variables * Environment Access:: How to get and set the values of environment variables. * Standard Environment:: These environment variables have standard interpretations. Program Termination * Normal Termination:: If a program calls @code{exit}, a process terminates normally. * Exit Status:: The @code{exit status} provides information about why the process terminated. * Cleanups on Exit:: A process can run its own cleanup functions upon normal termination. * Aborting a Program:: The @code{abort} function causes abnormal program termination. * Termination Internals:: What happens when a process terminates. Processes * Running a Command:: The easy way to run another program. * Process Creation Concepts:: An overview of the hard way to do it. * Process Identification:: How to get the process ID of a process. * Creating a Process:: How to fork a child process. * Executing a File:: How to make a process execute another program. * Process Completion:: How to tell when a child process has completed. * Process Completion Status:: How to interpret the status value returned from a child process. * BSD Wait Functions:: More functions, for backward compatibility. * Process Creation Example:: A complete example program. Job Control * Concepts of Job Control:: Jobs can be controlled by a shell. * Job Control is Optional:: Not all POSIX systems support job control. * Controlling Terminal:: How a process gets its controlling terminal. * Access to the Terminal:: How processes share the controlling terminal. * Orphaned Process Groups:: Jobs left after the user logs out. * Implementing a Shell:: What a shell must do to implement job control. * Functions for Job Control:: Functions to control process groups. Implementing a Shell * Data Structures:: Introduction to the sample shell. * Initializing the Shell:: What the shell must do to take responsibility for job control. * Launching Jobs:: Creating jobs to execute commands. * Foreground and Background:: Putting a job in foreground of background. * Stopped and Terminated Jobs:: Reporting job status. * Continuing Stopped Jobs:: How to continue a stopped job in the foreground or background. * Missing Pieces:: Other parts of the shell. Functions for Job Control * Identifying the Terminal:: Determining the controlling terminal's name. * Process Group Functions:: Functions for manipulating process groups. * Terminal Access Functions:: Functions for controlling terminal access. Name Service Switch * NSS Basics:: What is this NSS good for. * NSS Configuration File:: Configuring NSS. * NSS Module Internals:: How does it work internally. * Extending NSS:: What to do to add services or databases. NSS Configuration File * Services in the NSS configuration:: Service names in the NSS configuration. * Actions in the NSS configuration:: React appropriately to the lookup result. * Notes on NSS Configuration File:: Things to take care about while configuring NSS. NSS Module Internals * NSS Module Names:: Construction of the interface function of the NSS modules. * NSS Modules Interface:: Programming interface in the NSS module functions. Extending NSS * Adding another Service to NSS:: What is to do to add a new service. * NSS Module Function Internals:: Guidelines for writing new NSS service functions. Users and Groups * User and Group IDs:: Each user has a unique numeric ID; likewise for groups. * Process Persona:: The user IDs and group IDs of a process. * Why Change Persona:: Why a program might need to change its user and/or group IDs. * How Change Persona:: Changing the user and group IDs. * Reading Persona:: How to examine the user and group IDs. * Setting User ID:: Functions for setting the user ID. * Setting Groups:: Functions for setting the group IDs. * Enable/Disable Setuid:: Turning setuid access on and off. * Setuid Program Example:: The pertinent parts of one sample program. * Tips for Setuid:: How to avoid granting unlimited access. * Who Logged In:: Getting the name of the user who logged in, or of the real user ID of the current process. * User Accounting Database:: Keeping information about users and various actions in databases. * User Database:: Functions and data structures for accessing the user database. * Group Database:: Functions and data structures for accessing the group database. * Database Example:: Example program showing the use of database inquiry functions. * Netgroup Database:: Functions for accessing the netgroup database. User Accounting Database * Manipulating the Database:: Scanning and modifying the user accounting database. * XPG Functions:: A standardized way for doing the same thing. * Logging In and Out:: Functions from BSD that modify the user accounting database. User Database * User Data Structure:: What each user record contains. * Lookup User:: How to look for a particular user. * Scanning All Users:: Scanning the list of all users, one by one. * Writing a User Entry:: How a program can rewrite a user's record. Group Database * Group Data Structure:: What each group record contains. * Lookup Group:: How to look for a particular group. * Scanning All Groups:: Scanning the list of all groups. Netgroup Database * Netgroup Data:: Data in the Netgroup database and where it comes from. * Lookup Netgroup:: How to look for a particular netgroup. * Netgroup Membership:: How to test for netgroup membership. System Information * Host Identification:: Determining the name of the machine. * Hardware/Software Type ID:: Determining the hardware type of the machine and what operating system it is running. * Filesystem handling:: Which is mounted and/or available? System Configuration * General Limits:: Constants and functions that describe various process-related limits that have one uniform value for any given machine. * System Options:: Optional POSIX features. * Version Supported:: Version numbers of POSIX.1 and POSIX.2. * Sysconf:: Getting specific configuration values of general limits and system options. * Minimums:: Minimum values for general limits. * Limits for Files:: Size limitations that pertain to individual files. These can vary between file systems or even from file to file. * Options for Files:: Optional features that some files may support. * File Minimums:: Minimum values for file limits. * Pathconf:: Getting the limit values for a particular file. * Utility Limits:: Capacity limits of some POSIX.2 utility programs. * Utility Minimums:: Minimum allowable values of those limits. * String Parameters:: Getting the default search path. Sysconf * Sysconf Definition:: Detailed specifications of @code{sysconf}. * Constants for Sysconf:: The list of parameters @code{sysconf} can read. * Examples of Sysconf:: How to use @code{sysconf} and the parameter macros properly together. POSIX Threads * Basic Thread Operations:: Creating, terminating, and waiting for threads. * Thread Attributes:: Tuning thread scheduling. * Cancellation:: Stopping a thread before it's done. * Cleanup Handlers:: Deallocating resources when a thread is cancelled. * Mutexes:: One way to synchronize threads. * Condition Variables:: Another way. * POSIX Semaphores:: And a third way. * Thread-Specific Data:: Variables with different values in different threads. * Threads and Signal Handling:: Why you should avoid mixing the two, and how to do it if you must. * Miscellaneous Thread Functions:: A grab bag of utility routines. Language Features * Consistency Checking:: Using @code{assert} to abort if something ``impossible'' happens. * Variadic Functions:: Defining functions with varying numbers of args. * Null Pointer Constant:: The macro @code{NULL}. * Important Data Types:: Data types for object sizes. * Data Type Measurements:: Parameters of data type representations. Variadic Functions * Why Variadic:: Reasons for making functions take variable arguments. * How Variadic:: How to define and call variadic functions. * Variadic Example:: A complete example. How Variadic * Variadic Prototypes:: How to make a prototype for a function with variable arguments. * Receiving Arguments:: Steps you must follow to access the optional argument values. * How Many Arguments:: How to decide whether there are more arguments. * Calling Variadics:: Things you need to know about calling variable arguments functions. * Argument Macros:: Detailed specification of the macros for accessing variable arguments. * Old Varargs:: The pre-ISO way of defining variadic functions. Data Type Measurements * Width of Type:: How many bits does an integer type hold? * Range of Type:: What are the largest and smallest values that an integer type can hold? * Floating Type Macros:: Parameters that measure the floating point types. * Structure Measurement:: Getting measurements on structure types. Floating Type Macros * Floating Point Concepts:: Definitions of terminology. * Floating Point Parameters:: Details of specific macros. * IEEE Floating Point:: The measurements for one common representation. Installation * Tools for Installation:: We recommend using these tools to build. * Supported Configurations:: What systems the GNU C library runs on. * Tips for Installation:: Useful hints for the installation. * Reporting Bugs:: How to report bugs (if you want to get them fixed) and other troubles you may have with the GNU C library. Maintenance * Source Layout:: How to add new functions or header files to the GNU C library. * Porting:: How to port the GNU C library to a new machine or operating system. Porting * Hierarchy Conventions:: The layout of the @file{sysdeps} hierarchy. * Porting to Unix:: Porting the library to an average Unix-like system. @end menu