The GNU C Library

This is Edition 0.08 DRAFT, last updated 11 Jan 1999, of The GNU C Library Reference Manual, for Version 2.1 Beta of the GNU C Library.

1. Introduction		Purpose of the GNU C Library.
2. Error Reporting		How library functions report errors.
3. Memory Allocation		Allocating memory dynamically and manipulating it via pointers.
4. Character Handling		Character testing and conversion functions.
5. String and Array Utilities		Utilities for copying and comparing strings and arrays.
6. Character Set Handling		Support for extended character sets.
7. Locales and Internationalization		The country and language can affect the behavior of library functions.
8. Message Translation		How to make the program speak the user's language.
9. Searching and Sorting		General searching and sorting functions.
10. Pattern Matching		Matching shell "globs" and regular expressions.
11. Input/Output Overview		Introduction to the I/O facilities.
12. Input/Output on Streams		High-level, portable I/O facilities.
13. Low-Level Input/Output		Low-level, less portable I/O.
14. File System Interface		Functions for manipulating files.
15. Pipes and FIFOs		A simple interprocess communication mechanism.
16. Sockets		A more complicated IPC mechanism, with networking support.
17. Low-Level Terminal Interface		How to change the characteristics of a terminal device.
18. Mathematics		Math functions, useful constants, random numbers.
19. Arithmetic Functions		Low level arithmetic functions.
20. Date and Time		Functions for getting the date and time and formatting them nicely.
21. Non-Local Exits		Jumping out of nested function calls.
22. Signal Handling		How to send, block, and handle signals.
23. Process Startup and Termination		Writing the beginning and end of your program.
24. Processes		How to create processes and run other programs.
25. Job Control		All about process groups and sessions.
26. System Databases and Name Service Switch		Accessing system databases.
27. Users and Groups		How users are identified and classified.
28. System Information		Getting information about the hardware and operating system.
29. System Configuration Parameters		Parameters describing operating system limits.

Add-ons

30. DES Encryption and Password Handling		DES encryption and password handling.
31. POSIX Threads		The standard threads library.

Appendices

A. C Language Facilities in the Library		C language features provided by the library.
B. Summary of Library Facilities		A summary showing the syntax, header file, and derivation of each library feature.
C. Installing the GNU C Library		How to install the GNU C library.
D. Library Maintenance		How to enhance and port the GNU C Library.
E. Contributors to the GNU C Library		Who wrote what parts of the GNU C library.
F. GNU LIBRARY GENERAL PUBLIC LICENSE		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 and Macro Index		Index of functions and function-like macros.
Variable and Constant Macro Index		Index of variables and variable-like macros.
Program and File Index		Index of programs and files.

 -- The Detailed Node Listing ---

Introduction

1.1 Getting Started		What this manual is for and how to use it.
1.2 Standards and Portability		Standards and sources upon which the GNU C library is based.
1.3 Using the Library		Some practical uses for the library.
1.4 Roadmap to the Manual		Overview of the remaining chapters in this manual.

Standards and Portability

1.2.1 ISO C		The international standard for the C programming language.
1.2.2 POSIX (The Portable Operating System Interface)		The ISO/IEC 9945 (aka IEEE 1003) standards for operating systems.
1.2.3 Berkeley Unix		BSD and SunOS.
1.2.4 SVID (The System V Interface Description)		The System V Interface Description.
1.2.5 XPG (The X/Open Portability Guide)		The X/Open Portability Guide.

Using the Library

1.3.1 Header Files		How to include the header files in your programs.
1.3.2 Macro Definitions of Functions		Some functions in the library may really be implemented as macros.
1.3.3 Reserved Names		The C standard reserves some names for the library, and some for users.
1.3.4 Feature Test Macros		How to control what names are defined.

Error Reporting

2.1 Checking for Errors		How errors are reported by library functions.
2.2 Error Codes		Error code macros; all of these expand into integer constant values.
2.3 Error Messages		Mapping error codes onto error messages.

Memory Allocation

3.1 Dynamic Memory Allocation Concepts		An introduction to concepts and terminology.
3.2 Dynamic Allocation and C		How to get different kinds of allocation in C.
3.3 Unconstrained Allocation		The malloc facility allows fully general dynamic allocation.
3.4 Allocation Debugging		Finding memory leaks and not freed memory.
3.5 Obstacks		Obstacks are less general than malloc but more efficient and convenient.
3.6 Automatic Storage with Variable Size		Allocation of variable-sized blocks of automatic storage that are freed when the calling function returns.

Unconstrained Allocation

3.3.1 Basic Storage Allocation		Simple use of malloc.
3.3.2 Examples of malloc		Examples of malloc. xmalloc.
3.3.3 Freeing Memory Allocated with malloc		Use free to free a block you got with malloc.
3.3.4 Changing the Size of a Block		Use realloc to make a block bigger or smaller.
3.3.5 Allocating Cleared Space		Use calloc to allocate a block and clear it.
3.3.6 Efficiency Considerations for malloc		Efficiency considerations in use of these functions.
3.3.7 Allocating Aligned Memory Blocks		Allocating specially aligned memory:

 memalign and valloc.

3.3.8 Malloc Tunable Parameters		Use mallopt to adjust allocation parameters.
3.3.9 Heap Consistency Checking		Automatic checking for errors.
3.3.10 Storage Allocation Hooks		You can use these hooks for debugging programs that use malloc.
3.3.11 Statistics for Storage Allocation with malloc		Getting information about how much memory your program is using.
3.3.12 Summary of malloc-Related Functions		Summary of malloc and related functions.

Allocation Debugging

3.4.1 How to install the tracing functionality		How to install the tracing functionality.
3.4.2 Example programs excerpts		Example programs excerpts.
3.4.3 Some more or less clever ideas		Some more or less clever ideas.
3.4.4 Interpreting the traces		What do all these lines mean?

Obstacks

3.5.1 Creating Obstacks		How to declare an obstack in your program.
3.5.2 Preparing for Using Obstacks		Preparations needed before you can use obstacks.
3.5.3 Allocation in an Obstack		Allocating objects in an obstack.
3.5.4 Freeing Objects in an Obstack		Freeing objects in an obstack.
3.5.5 Obstack Functions and Macros		The obstack functions are both functions and macros.
3.5.6 Growing Objects		Making an object bigger by stages.
3.5.7 Extra Fast Growing Objects		Extra-high-efficiency (though more complicated) growing objects.
3.5.8 Status of an Obstack		Inquiries about the status of an obstack.
3.5.9 Alignment of Data in Obstacks		Controlling alignment of objects in obstacks.
3.5.10 Obstack Chunks		How obstacks obtain and release chunks; efficiency considerations.
3.5.11 Summary of Obstack Functions

Variable Size Automatic

3.6.1 alloca Example		Example of using alloca.
3.6.2 Advantages of alloca		Reasons to use alloca.
3.6.3 Disadvantages of alloca		Reasons to avoid alloca.
3.6.4 GNU C Variable-Size Arrays		Only in GNU C, here is an alternative method of allocating dynamically and freeing automatically.

Character Handling

4.1 Classification of Characters

Testing whether characters are letters, digits, punctuation, etc.

4.2 Case Conversion		Case mapping, and the like.
4.3 Character class determination for wide characters		Character class determination for wide characters.
4.4 Notes on using the wide character classes		Notes on using the wide character classes.
4.5 Mapping of wide characters.

String and Array Utilities

5.1 Representation of Strings		Introduction to basic concepts.
5.2 String and Array Conventions		Whether to use a string function or an arbitrary array function.
5.3 String Length		Determining the length of a string.
5.4 Copying and Concatenation		Functions to copy the contents of strings and arrays.
5.5 String/Array Comparison		Functions for byte-wise and character-wise comparison.
5.6 Collation Functions		Functions for collating strings.
5.7 Search Functions		Searching for a specific element or substring.
5.8 Finding Tokens in a String		Splitting a string into tokens by looking for delimiters.
5.9 Encode Binary Data		Encoding and Decoding of Binary Data.
5.10 Argz and Envz Vectors		Null-separated string vectors.

Argz and Envz Vectors

5.10.1 Argz Functions		Operations on argz vectors.
5.10.2 Envz Functions		Additional operations on environment vectors.

Character Set Handling

6.1 Introduction to Extended Characters		Introduction to Extended Characters.
6.2 Overview about Character Handling Functions		Overview about Character Handling Functions.
6.3 Restartable Multibyte Conversion Functions		Restartable multibyte conversion Functions.
6.4 Non-reentrant Conversion Function		Non-reentrant Conversion Function.
6.5 Generic Charset Conversion		Generic Charset Conversion.

Restartable multibyte conversion

6.3.1 Selecting the conversion and its properties		Selecting the conversion and its properties.
6.3.2 Representing the state of the conversion		Representing the state of the conversion.
6.3.3 Converting Single Characters		Converting Single Characters.
6.3.4 Converting Multibyte and Wide Character Strings		Converting Multibyte and Wide Character Strings.
6.3.5 A Complete Multibyte Conversion Example		A Complete Multibyte Conversion Example.

Non-reentrant Conversion

6.4.1 Non-reentrant Conversion of Single Characters		Non-reentrant Conversion of Single Characters.
6.4.2 Non-reentrant Conversion of Strings		Non-reentrant Conversion of Strings.
6.4.3 States in Non-reentrant Functions		States in Non-reentrant Functions.

Generic Charset Conversion

6.5.1 Generic Character Set Conversion Interface		Generic Character Set Conversion Interface.
6.5.2 A complete iconv example		A complete iconv example.
6.5.3 Some Details about other iconv Implementations		Some Details about other iconv Implementations.
6.5.4 The iconv Implementation in the GNU C library		The iconv Implementation in the GNU C library.

Locales

7.1 What Effects a Locale Has		Actions affected by the choice of locale.
7.2 Choosing a Locale		How the user specifies a locale.
7.3 Categories of Activities that Locales Affect		Different purposes for which you can select a locale.
7.4 How Programs Set the Locale		How a program specifies the locale with library functions.
7.5 Standard Locales		Locale names available on all systems.
7.6 Accessing the Locale Information		How to access the information for the locale.
7.7 A dedicated function to format numbers		A dedicated function to format numbers.

Locale Information

7.6.1 localeconv: It is portable but ...		ISO C's localeconv.
7.6.2 Pinpoint Access to Locale Data		X/Open's nl_langinfo.

The Lame Way to Locale Data

7.6.1.1 Generic Numeric Formatting Parameters		Parameters for formatting numbers and currency amounts.
7.6.1.2 Printing the Currency Symbol		How to print the symbol that identifies an amount of money (e.g. `$').
7.6.1.3 Printing the Sign of an Amount of Money		How to print the (positive or negative) sign for a monetary amount, if one exists.

Message Translation

8.1 X/Open Message Catalog Handling		The catgets family of functions.
8.2 The Uniforum approach to Message Translation		The gettext family of functions.

Message catalogs a la X/Open

8.1.1 The catgets function family		The catgets function family.
8.1.2 Format of the message catalog files		Format of the message catalog files.
8.1.3 Generate Message Catalogs files		How to generate message catalogs files which can be used by the functions.
8.1.4 How to use the catgets interface		How to use the catgets interface.

The Uniforum approach

8.2.1 The gettext family of functions		The gettext family of functions.
8.2.2 Programs to handle message catalogs for gettext		Programs to handle message catalogs for gettext.

Message catalogs with gettext

8.2.1.1 What has to be done to translate a message?		What has to be done to translate a message.
8.2.1.2 How to determine which catalog to be used		How to determine which catalog to be used.
8.2.1.3 User influence on gettext		The possibilities of the user to influence the way gettext works.

Searching and Sorting

9.1 Defining the Comparison Function		Defining how to compare two objects. Since the sort and search facilities are general, you have to specify the ordering.
9.2 Array Search Function		The bsearch function.
9.3 Array Sort Function		The qsort function.
9.4 Searching and Sorting Example		An example program.
9.5 The hsearch function.
9.6 The tsearch function.

Pattern Matching

10.1 Wildcard Matching		Matching a wildcard pattern against a single string.
10.2 Globbing		Finding the files that match a wildcard pattern.
10.3 Regular Expression Matching		Matching regular expressions against strings.
10.4 Shell-Style Word Expansion		Expanding shell variables, nested commands, arithmetic, and wildcards. This is what the shell does with shell commands.

Globbing

10.2.1 Calling glob		Basic use of glob.
10.2.2 Flags for Globbing		Flags that enable various options in glob.
10.2.3 More Flags for Globbing		GNU specific extensions to glob.

Regular Expressions

10.3.1 POSIX Regular Expression Compilation		Using regcomp to prepare to match.
10.3.2 Flags for POSIX Regular Expressions		Syntax variations for regcomp.
10.3.3 Matching a Compiled POSIX Regular Expression		Using regexec to match the compiled pattern that you get from regcomp.
10.3.4 Match Results with Subexpressions		Finding which parts of the string were matched.
10.3.5 Complications in Subexpression Matching		Find points of which parts were matched.
10.3.6 POSIX Regexp Matching Cleanup		Freeing storage; reporting errors.

Word Expansion

10.4.1 The Stages of Word Expansion		What word expansion does to a string.
10.4.2 Calling wordexp		How to call wordexp.
10.4.3 Flags for Word Expansion		Options you can enable in wordexp.
10.4.4 wordexp Example		A sample program that does word expansion.
10.4.5 Details of Tilde Expansion		Details of how tilde expansion works.
10.4.6 Details of Variable Substitution		Different types of variable substitution.

I/O Overview

11.1 Input/Output Concepts		Some basic information and terminology.
11.2 File Names		How to refer to a file.

I/O Concepts

11.1.1 Streams and File Descriptors		The GNU Library provides two ways to access the contents of files.
11.1.2 File Position		The number of bytes from the beginning of the file.

File Names

11.2.1 Directories		Directories contain entries for files.
11.2.2 File Name Resolution		A file name specifies how to look up a file.
11.2.3 File Name Errors		Error conditions relating to file names.
11.2.4 Portability of File Names		File name portability and syntax issues.

I/O on Streams

12.1 Streams		About the data type representing a stream.
12.2 Standard Streams		Streams to the standard input and output devices are created for you.
12.3 Opening Streams		How to create a stream to talk to a file.
12.4 Closing Streams		Close a stream when you are finished with it.
12.5 Simple Output by Characters or Lines		Unformatted output by characters and lines.
12.6 Character Input		Unformatted input by characters and words.
12.7 Line-Oriented Input		Reading a line or a record from a stream.
12.8 Unreading		Peeking ahead/pushing back input just read.
12.9 Block Input/Output		Input and output operations on blocks of data.
12.10 Formatted Output		printf and related functions.
12.11 Customizing printf		You can define new conversion specifiers for

                                  printf and friends.

12.12 Formatted Input		scanf and related functions.
12.13 End-Of-File and Errors		How you can tell if an I/O error happens.
12.14 Text and Binary Streams		Some systems distinguish between text files and binary files.
12.15 File Positioning		About random-access streams.
12.16 Portable File-Position Functions		Random access on peculiar ISO C systems.
12.17 Stream Buffering		How to control buffering of streams.
12.18 Other Kinds of Streams		Streams that do not necessarily correspond to an open file.
12.19 Formatted Messages		Print strictly formatted messages.

Unreading

12.8.1 What Unreading Means		An explanation of unreading with pictures.
12.8.2 Using ungetc To Do Unreading		How to call ungetc to do unreading.

Formatted Output

12.10.1 Formatted Output Basics		Some examples to get you started.
12.10.2 Output Conversion Syntax		General syntax of conversion specifications.
12.10.3 Table of Output Conversions		Summary of output conversions and what they do.
12.10.4 Integer Conversions		Details about formatting of integers.
12.10.5 Floating-Point Conversions		Details about formatting of floating-point numbers.
12.10.6 Other Output Conversions		Details about formatting of strings, characters, pointers, and the like.
12.10.7 Formatted Output Functions		Descriptions of the actual functions.
12.10.8 Dynamically Allocating Formatted Output		Functions that allocate memory for the output.
12.10.9 Variable Arguments Output Functions		vprintf and friends.
12.10.10 Parsing a Template String		What kinds of args does a given template call for?
12.10.11 Example of Parsing a Template String		Sample program using parse_printf_format.

Customizing Printf

12.11.1 Registering New Conversions		Using register_printf_function to register a new output conversion.
12.11.2 Conversion Specifier Options		The handler must be able to get the options specified in the template when it is called.
12.11.3 Defining the Output Handler		Defining the handler and arginfo functions that are passed as arguments to register_printf_function.
12.11.4 printf Extension Example		How to define a printf handler function.
12.11.5 Predefined printf Handlers		Predefined printf handlers.

Formatted Input

12.12.1 Formatted Input Basics		Some basics to get you started.
12.12.2 Input Conversion Syntax		Syntax of conversion specifications.
12.12.3 Table of Input Conversions		Summary of input conversions and what they do.
12.12.4 Numeric Input Conversions		Details of conversions for reading numbers.
12.12.5 String Input Conversions		Details of conversions for reading strings.
12.12.6 Dynamically Allocating String Conversions		String conversions that malloc the buffer.
12.12.7 Other Input Conversions		Details of miscellaneous other conversions.
12.12.8 Formatted Input Functions		Descriptions of the actual functions.
12.12.9 Variable Arguments Input Functions		vscanf and friends.

Stream Buffering

12.17.1 Buffering Concepts		Terminology is defined here.
12.17.2 Flushing Buffers		How to ensure that output buffers are flushed.
12.17.3 Controlling Which Kind of Buffering		How to specify what kind of buffering to use.

Other Kinds of Streams

12.18.1 String Streams		Streams that get data from or put data in a string or memory buffer.
12.18.2 Obstack Streams		Streams that store data in an obstack.
12.18.3 Programming Your Own Custom Streams		Defining your own streams with an arbitrary input data source and/or output data sink.

Custom Streams

12.18.3.1 Custom Streams and Cookies		The cookie records where to fetch or store data that is read or written.
12.18.3.2 Custom Stream Hook Functions		How you should define the four hook functions that a custom stream needs.

Formatted Messages

12.19.1 Printing Formatted Messages		The fmtmsg function.
12.19.2 Adding Severity Classes		Add more severity classes.
12.19.3 How to use fmtmsg and addseverity		How to use fmtmsg and addseverity.

Low-Level I/O

13.1 Opening and Closing Files		How to open and close file descriptors.
13.2 Change the size of a file		Change the size of a file.
13.3 Input and Output Primitives		Reading and writing data.
13.4 Setting the File Position of a Descriptor		Setting a descriptor's file position.
13.5 Descriptors and Streams		Converting descriptor to stream or vice-versa.
13.6 Dangers of Mixing Streams and Descriptors		Precautions needed if you use both descriptors and streams.
13.7 Fast Scatter-Gather I/O		Fast I/O to discontinuous buffers.
13.8 Memory-mapped I/O		Using files like memory.
13.9 Waiting for Input or Output		How to check for input or output on multiple file descriptors.
13.10 Synchronizing I/O operations		Making sure all I/O actions completed.
13.11 Perform I/O Operations in Parallel		Perform I/O in parallel.
13.12 Control Operations on Files		Various other operations on file descriptors.
13.13 Duplicating Descriptors		Fcntl commands for duplicating file descriptors.
13.14 File Descriptor Flags		Fcntl commands for manipulating flags associated with file descriptors.
13.15 File Status Flags		Fcntl commands for manipulating flags associated with open files.
13.16 File Locks		Fcntl commands for implementing file locking.
13.17 Interrupt-Driven Input		Getting an asynchronous signal when input arrives.
13.18 Generic I/O Control operations		Generic I/O Control operations.

Stream/Descriptor Precautions

13.6.1 Linked Channels		Dealing with channels sharing a file position.
13.6.2 Independent Channels		Dealing with separately opened, unlinked channels.
13.6.3 Cleaning Streams		Cleaning a stream makes it safe to use another channel.

Asynchronous I/O

13.11.1 Asynchronous Read and Write Operations		Asynchronous Read and Write Operations.
13.11.2 Getting the Status of AIO Operations		Getting the Status of AIO Operations.
13.11.3 Getting into a Consistent State		Getting into a consistent state.
13.11.4 Cancelation of AIO Operations		Cancelation of AIO Operations.
13.11.5 How to optimize the AIO implementation		How to optimize the AIO implementation.

File Status Flags

13.15.1 File Access Modes		Whether the descriptor can read or write.
13.15.2 Open-time Flags		Details of open.
13.15.3 I/O Operating Modes		Special modes to control I/O operations.
13.15.4 Getting and Setting File Status Flags		Fetching and changing these flags.

File System Interface

14.1 Working Directory		This is used to resolve relative file names.
14.2 Accessing Directories		Finding out what files a directory contains.
14.3 Working on Directory Trees		Apply actions to all files or a selectable subset of a directory hierarchy.
14.4 Hard Links		Adding alternate names to a file.
14.5 Symbolic Links		A file that "points to" a file name.
14.6 Deleting Files		How to delete a file, and what that means.
14.7 Renaming Files		Changing a file's name.
14.8 Creating Directories		A system call just for creating a directory.
14.9 File Attributes		Attributes of individual files.
14.10 Making Special Files		How to create special files.
14.11 Temporary Files		Naming and creating temporary files.

Accessing Directories

14.2.1 Format of a Directory Entry		Format of one directory entry.
14.2.2 Opening a Directory Stream		How to open a directory stream.
14.2.3 Reading and Closing a Directory Stream		How to read directory entries from the stream.
14.2.4 Simple Program to List a Directory		A very simple directory listing program.
14.2.5 Random Access in a Directory Stream		Rereading part of the directory already read with the same stream.
14.2.6 Scanning the Content of a Directory		Get entries for user selected subset of contents in given directory.
14.2.7 Simple Program to List a Directory, Mark II		Revised version of the program.

File Attributes

14.9.1 What the File Attribute Values Mean		The names of the file attributes, and what their values mean.
14.9.2 Reading the Attributes of a File		How to read the attributes of a file.
14.9.3 Testing the Type of a File		Distinguishing ordinary files, directories, links...
14.9.4 File Owner		How ownership for new files is determined, and how to change it.
14.9.5 The Mode Bits for Access Permission		How information about a file's access mode is stored.
14.9.6 How Your Access to a File is Decided		How the system decides who can access a file.
14.9.7 Assigning File Permissions		How permissions for new files are assigned, and how to change them.
14.9.8 Testing Permission to Access a File		How to find out if your process can access a file.
14.9.9 File Times		About the time attributes of a file.
14.9.10 File Size		Manually changing the size of a file.

Pipes and FIFOs

15.1 Creating a Pipe		Making a pipe with the pipe function.
15.2 Pipe to a Subprocess		Using a pipe to communicate with a child process.
15.3 FIFO Special Files		Making a FIFO special file.
15.4 Atomicity of Pipe I/O		When pipe (or FIFO) I/O is atomic.

Sockets

16.1 Socket Concepts		Basic concepts you need to know about.
16.2 Communication Styles		Stream communication, datagrams, and other styles.
16.3 Socket Addresses		How socket names ("addresses") work.
16.4 Interface Naming		Identifying specific network interfaces.
16.5 The Local Namespace		Details about the local namespace.
16.6 The Internet Namespace		Details about the Internet namespace.
16.7 Other Namespaces		Other namespaces not documented fully here.
16.8 Opening and Closing Sockets		Creating sockets and destroying them.
16.9 Using Sockets with Connections		Operations on sockets with connection state.
16.10 Datagram Socket Operations		Operations on datagram sockets.
16.11 The inetd Daemon		Inetd is a daemon that starts servers on request. The most convenient way to write a server is to make it work with Inetd.
16.12 Socket Options		Miscellaneous low-level socket options.
16.13 Networks Database		Accessing the database of network names.

Socket Addresses

16.3.1 Address Formats		About struct sockaddr.
16.3.2 Setting the Address of a Socket		Binding an address to a socket.
16.3.3 Reading the Address of a Socket		Reading the address of a socket.

Local Namespace

16.5.1 Local Namespace Concepts		What you need to understand.
16.5.2 Details of Local Namespace		Address format, symbolic names, etc.
16.5.3 Example of Local-Namespace Sockets		Example of creating a socket.

Internet Namespace

16.6.1 Internet Socket Address Formats		How socket addresses are specified in the Internet namespace.
16.6.2 Host Addresses		All about host addresses of internet host.
16.6.6 Protocols Database		Referring to protocols by name.
16.6.3 Internet Ports		Internet port numbers.
16.6.4 The Services Database		Ports may have symbolic names.
16.6.5 Byte Order Conversion		Different hosts may use different byte ordering conventions; you need to canonicalize host address and port number.
16.6.7 Internet Socket Example		Putting it all together.

Host Addresses

16.6.2.1 Internet Host Addresses		What a host number consists of.
16.6.2.2 Host Address Data Type		Data type for a host number.
16.6.2.3 Host Address Functions		Functions to operate on them.
16.6.2.4 Host Names		Translating host names to host numbers.

Open/Close Sockets

16.8.1 Creating a Socket		How to open a socket.
16.8.2 Closing a Socket		How to close a socket.
16.8.3 Socket Pairs		These are created like pipes.

Connections

16.9.1 Making a Connection		What the client program must do.
16.9.2 Listening for Connections		How a server program waits for requests.
16.9.3 Accepting Connections		What the server does when it gets a request.
16.9.4 Who is Connected to Me?		Getting the address of the other side of a connection.
16.9.5 Transferring Data		How to send and receive data.
16.9.6 Byte Stream Socket Example		An example program: a client for communicating over a byte stream socket in the Internet namespace.
16.9.7 Byte Stream Connection Server Example		A corresponding server program.
16.9.8 Out-of-Band Data		This is an advanced feature.

Transferring Data

16.9.5.1 Sending Data		Sending data with send.
16.9.5.2 Receiving Data		Reading data with recv.
16.9.5.3 Socket Data Options		Using send and recv.

Datagrams

16.10.1 Sending Datagrams		Sending packets on a datagram socket.
16.10.2 Receiving Datagrams		Receiving packets on a datagram socket.
16.10.3 Datagram Socket Example		An example program: packets sent over a datagram socket in the local namespace.
16.10.4 Example of Reading Datagrams		Another program, that receives those packets.

Inetd

16.11.1 inetd Servers
16.11.2 Configuring inetd

Socket Options

16.12.1 Socket Option Functions		The basic functions for setting and getting socket options.
16.12.2 Socket-Level Options		Details of the options at the socket level.

Low-Level Terminal Interface

17.1 Identifying Terminals		How to determine if a file is a terminal device, and what its name is.
17.2 I/O Queues		About flow control and typeahead.
17.3 Two Styles of Input: Canonical or Not		Two basic styles of input processing.
17.4 Terminal Modes		How to examine and modify flags controlling details of terminal I/O: echoing, signals, editing.
17.5 Line Control Functions		Sending break sequences, clearing terminal buffers ...
17.6 Noncanonical Mode Example		How to read single characters without echo.
17.7 Pseudo-Terminals		How to open a pseudo-terminal.

Terminal Modes

17.4.1 Terminal Mode Data Types		The data type struct termios and related types.
17.4.2 Terminal Mode Functions		Functions to read and set the terminal attributes.
17.4.3 Setting Terminal Modes Properly		The right way to set terminal attributes reliably.
17.4.4 Input Modes		Flags controlling low-level input handling.
17.4.5 Output Modes		Flags controlling low-level output handling.
17.4.6 Control Modes		Flags controlling serial port behavior.
17.4.7 Local Modes		Flags controlling high-level input handling.
17.4.8 Line Speed		How to read and set the terminal line speed.
17.4.9 Special Characters		Characters that have special effects, and how to change them.
17.4.10 Noncanonical Input		Controlling how long to wait for input.

Special Characters

17.4.9.1 Characters for Input Editing		Special characters that terminate lines and delete text, and other editing functions.
17.4.9.2 Characters that Cause Signals		Special characters that send or raise signals to or for certain classes of processes.
17.4.9.3 Special Characters for Flow Control		Special characters that suspend or resume suspended output.
17.4.9.4 Other Special Characters		Other special characters for BSD systems: they can discard output, and print status.

Pseudo-Terminals

17.7.1 Allocating Pseudo-Terminals		Allocating a pseudo terminal.
17.7.2 Opening a Pseudo-Terminal Pair		How to open both sides of a pseudo-terminal in a single operation.

Mathematics

18.1 Predefined Mathematical Constants		Precise numeric values for often-used constants.
18.2 Trigonometric Functions		Sine, cosine, tangent, and friends.
18.3 Inverse Trigonometric Functions		Arcsine, arccosine, etc.
18.4 Exponentiation and Logarithms		Also pow and sqrt.
18.5 Hyperbolic Functions		sinh, cosh, tanh, etc.
18.6 Special Functions		Bessel, gamma, erf.
18.7 Pseudo-Random Numbers		Functions for generating pseudo-random numbers.
18.8 Is Fast Code or Small Code preferred?		Fast code or small code.

Pseudo-Random Numbers

18.7.1 ISO C Random Number Functions		rand and friends.
18.7.2 BSD Random Number Functions		random and friends.
18.7.3 SVID Random Number Function		drand48 and friends.

Arithmetic

19.1 Floating Point Numbers		Basic concepts. IEEE 754.
19.2 Floating-Point Number Classification Functions		The five kinds of floating-point number.
19.3 Errors in Floating-Point Calculations		When something goes wrong in a calculation.
19.4 Rounding Modes		Controlling how results are rounded.
19.5 Floating-Point Control Functions		Saving and restoring the FPU's state.
19.6 Arithmetic Functions		Fundamental operations provided by the library.
19.7 Complex Numbers		The types. Writing complex constants.
19.8 Projections, Conjugates, and Decomposing of Complex Numbers		Projection, conjugation, decomposition.
19.9 Integer Division		Integer division with guaranteed rounding.
19.10 Parsing of Numbers		Converting strings to numbers.
19.11 Old-fashioned System V number-to-string functions		An archaic way to convert numbers to strings.

Floating Point Errors

19.3.1 FP Exceptions		IEEE 754 math exceptions and how to detect them.
19.3.2 Infinity and NaN		Special values returned by calculations.
19.3.3 Examining the FPU status word		Checking for exceptions after the fact.
19.3.4 Error Reporting by Mathematical Functions		How the math functions report errors.

Arithmetic Functions

19.6.1 Absolute Value		Absolute values of integers and floats.
19.6.2 Normalization Functions		Extracting exponents and putting them back.
19.6.3 Rounding Functions		Rounding floats to integers.
19.6.4 Remainder Functions		Remainders on division, precisely defined.
19.6.5 Setting and modifying single bits of FP values		Sign bit adjustment. Adding epsilon.
19.6.6 Floating-Point Comparison Functions		Comparisons without risk of exceptions.
19.6.7 Miscellaneous FP arithmetic functions		Max, min, positive difference, multiply-add.

Parsing of Numbers

19.10.1 Parsing of Integers		Functions for conversion of integer values.
19.10.2 Parsing of Floats		Functions for conversion of floating-point values.

Date and Time

20.1 Processor Time		Measures processor time used by a program.
20.2 Calendar Time		Manipulation of "real" dates and times.
20.3 Precision Time		Manipulation and monitoring of high accuracy time.
20.4 Setting an Alarm		Sending a signal after a specified time.
20.5 Sleeping		Waiting for a period of time.
20.6 Resource Usage		Measuring various resources used.
20.7 Limiting Resource Usage		Specifying limits on resource usage.
20.8 Process Priority		Reading or setting process run priority.

Processor Time

20.1.1 Basic CPU Time Inquiry		The clock function.
20.1.2 Detailed Elapsed CPU Time Inquiry		The times function.

Calendar Time

20.2.1 Simple Calendar Time		Facilities for manipulating calendar time.
20.2.2 High-Resolution Calendar		A time representation with greater precision.
20.2.3 Broken-down Time		Facilities for manipulating local time.
20.2.4 Formatting Date and Time		Converting times to strings.
20.2.5 Convert textual time and date information back		Convert textual time and date information back into broken-down time values.
20.2.6 Specifying the Time Zone with TZ		How users specify the time zone.
20.2.7 Functions and Variables for Time Zones		Functions to examine or specify the time zone.
20.2.8 Time Functions Example		An example program showing use of some of the time functions.

Parsing Date and Time

20.2.5.1 Interpret string according to given format		Interpret string according to given format.
20.2.5.2 A user-friendlier way to parse times and dates		User-friendly function to parse data and time strings.

Non-Local Exits

21.1 Introduction to Non-Local Exits		When and how to use these facilities.
21.2 Details of Non-Local Exits		Functions for nonlocal exits.
21.3 Non-Local Exits and Signals		Portability issues.

Signal Handling

22.1 Basic Concepts of Signals		Introduction to the signal facilities.
22.2 Standard Signals		Particular kinds of signals with standard names and meanings.
22.3 Specifying Signal Actions		Specifying what happens when a particular signal is delivered.
22.4 Defining Signal Handlers		How to write a signal handler function.
22.5 Primitives Interrupted by Signals		Signal handlers affect use of open,

 read, write and other functions.

22.6 Generating Signals		How to send a signal to a process.
22.7 Blocking Signals		Making the system hold signals temporarily.
22.8 Waiting for a Signal		Suspending your program until a signal arrives.
22.9 Using a Separate Signal Stack		Using a Separate Signal Stack.
22.10 BSD Signal Handling		Additional functions for backward compatibility with BSD.

Concepts of Signals

22.1.1 Some Kinds of Signals		Some examples of what can cause a signal.
22.1.2 Concepts of Signal Generation		Concepts of why and how signals occur.
22.1.3 How Signals Are Delivered		Concepts of what a signal does to the process.

Standard Signals

22.2.1 Program Error Signals		Used to report serious program errors.
22.2.2 Termination Signals		Used to interrupt and/or terminate the program.
22.2.3 Alarm Signals		Used to indicate expiration of timers.
22.2.4 Asynchronous I/O Signals		Used to indicate input is available.
22.2.5 Job Control Signals		Signals used to support job control.
22.2.6 Operation Error Signals		Used to report operational system errors.
22.2.7 Miscellaneous Signals		Miscellaneous Signals.
22.2.8 Signal Messages		Printing a message describing a signal.

Signal Actions

22.3.1 Basic Signal Handling		The simple signal function.
22.3.2 Advanced Signal Handling		The more powerful sigaction function.
22.3.3 Interaction of signal and sigaction		How those two functions interact.
22.3.4 sigaction Function Example		An example of using the sigaction function.
22.3.5 Flags for sigaction		Specifying options for signal handling.
22.3.6 Initial Signal Actions		How programs inherit signal actions.

Defining Handlers

22.4.1 Signal Handlers that Return		Handlers that return normally, and what this means.
22.4.2 Handlers That Terminate the Process		How handler functions terminate a program.
22.4.3 Nonlocal Control Transfer in Handlers		Nonlocal transfer of control out of a signal handler.
22.4.4 Signals Arriving While a Handler Runs		What happens when signals arrive while the handler is already occupied.
22.4.5 Signals Close Together Merge into One		When a second signal arrives before the first is handled.
22.4.6 Signal Handling and Nonreentrant Functions		Do not call any functions unless you know they are reentrant with respect to signals.
22.4.7 Atomic Data Access and Signal Handling		A single handler can run in the middle of reading or writing a single object.

Atomic Data Access

22.4.7.1 Problems with Non-Atomic Access		A program illustrating interrupted access.
22.4.7.2 Atomic Types		Data types that guarantee no interruption.
22.4.7.3 Atomic Usage Patterns		Proving that interruption is harmless.

Generating Signals

22.6.1 Signaling Yourself		A process can send a signal to itself.
22.6.2 Signaling Another Process		Send a signal to another process.
22.6.3 Permission for using kill		Permission for using kill.
22.6.4 Using kill for Communication		Using kill for Communication.

Blocking Signals

22.7.1 Why Blocking Signals is Useful		The purpose of blocking signals.
22.7.2 Signal Sets		How to specify which signals to block.
22.7.3 Process Signal Mask		Blocking delivery of signals to your process during normal execution.
22.7.4 Blocking to Test for Delivery of a Signal		Blocking to Test for Delivery of a Signal.
22.7.5 Blocking Signals for a Handler		Blocking additional signals while a handler is being run.
22.7.6 Checking for Pending Signals
22.7.7 Remembering a Signal to Act On Later		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

22.8.1 Using pause		The simple way, using pause.
22.8.2 Problems with pause		Why the simple way is often not very good.
22.8.3 Using sigsuspend		Reliably waiting for a specific signal.

BSD Signal Handling

22.10.1 BSD Function to Establish a Handler		BSD Function to Establish a Handler.
22.10.2 BSD Functions for Blocking Signals		BSD Functions for Blocking Signals.

Process Startup

23.1 Program Arguments		Parsing your program's command-line arguments.
23.4 Environment Variables		How to access parameters inherited from a parent process.
23.5 Program Termination		How to cause a process to terminate and return status information to its parent.

Program Arguments

23.1.1 Program Argument Syntax Conventions		By convention, options start with a hyphen.
23.1.2 Parsing Program Arguments		Ways to parse program options and arguments.

Parsing Program Arguments

23.2 Parsing program options using getopt		Parsing program options using getopt.
23.3 Parsing Program Options with Argp		Parsing program options using argp_parse.
23.3.12.1 Parsing of Suboptions		Some programs need more detailed options.
23.3.13 Parsing of Suboptions Example		This shows how it could be done for mount.

Environment Variables

23.4.1 Environment Access		How to get and set the values of environment variables.
23.4.2 Standard Environment Variables		These environment variables have standard interpretations.

Program Termination

23.5.1 Normal Termination		If a program calls exit, a process terminates normally.
23.5.2 Exit Status		The exit status provides information about why the process terminated.
23.5.3 Cleanups on Exit		A process can run its own cleanup functions upon normal termination.
23.5.4 Aborting a Program		The abort function causes abnormal program termination.
23.5.5 Termination Internals		What happens when a process terminates.

Processes

24.1 Running a Command		The easy way to run another program.
24.2 Process Creation Concepts		An overview of the hard way to do it.
24.3 Process Identification		How to get the process ID of a process.
24.4 Creating a Process		How to fork a child process.
24.5 Executing a File		How to make a process execute another program.
24.6 Process Completion		How to tell when a child process has completed.
24.7 Process Completion Status		How to interpret the status value returned from a child process.
24.8 BSD Process Wait Functions		More functions, for backward compatibility.
24.9 Process Creation Example		A complete example program.

Job Control

25.1 Concepts of Job Control		Jobs can be controlled by a shell.
25.2 Job Control is Optional		Not all POSIX systems support job control.
25.3 Controlling Terminal of a Process		How a process gets its controlling terminal.
25.4 Access to the Controlling Terminal		How processes share the controlling terminal.
25.5 Orphaned Process Groups		Jobs left after the user logs out.
25.6 Implementing a Job Control Shell		What a shell must do to implement job control.
25.7 Functions for Job Control		Functions to control process groups.

Implementing a Shell

25.6.1 Data Structures for the Shell		Introduction to the sample shell.
25.6.2 Initializing the Shell		What the shell must do to take responsibility for job control.
25.6.3 Launching Jobs		Creating jobs to execute commands.
25.6.4 Foreground and Background		Putting a job in foreground of background.
25.6.5 Stopped and Terminated Jobs		Reporting job status.
25.6.6 Continuing Stopped Jobs		How to continue a stopped job in the foreground or background.
25.6.7 The Missing Pieces		Other parts of the shell.

Functions for Job Control

25.7.1 Identifying the Controlling Terminal		Determining the controlling terminal's name.
25.7.2 Process Group Functions		Functions for manipulating process groups.
25.7.3 Functions for Controlling Terminal Access		Functions for controlling terminal access.

Name Service Switch

26.1 NSS Basics		What is this NSS good for.
26.2 The NSS Configuration File		Configuring NSS.
26.3 NSS Module Internals		How does it work internally.
26.4 Extending NSS		What to do to add services or databases.

NSS Configuration File

26.2.1 Services in the NSS configuration File		Service names in the NSS configuration.
26.2.2 Actions in the NSS configuration		React appropriately to the lookup result.
26.2.3 Notes on the NSS Configuration File		Things to take care about while configuring NSS.

NSS Module Internals

26.3.1 The Naming Scheme of the NSS Modules		Construction of the interface function of the NSS modules.
26.3.2 The Interface of the Function in NSS Modules		Programming interface in the NSS module functions.

Extending NSS

26.4.1 Adding another Service to NSS		What is to do to add a new service.
26.4.2 Internals of the NSS Module Functions		Guidelines for writing new NSS service functions.

Users and Groups

27.1 User and Group IDs		Each user has a unique numeric ID; likewise for groups.
27.2 The Persona of a Process		The user IDs and group IDs of a process.
27.3 Why Change the Persona of a Process?		Why a program might need to change its user and/or group IDs.
27.4 How an Application Can Change Persona		Changing the user and group IDs.
27.5 Reading the Persona of a Process		How to examine the user and group IDs.

27.6 Setting the User ID		Functions for setting the user ID.
27.7 Setting the Group IDs		Functions for setting the group IDs.

27.8 Enabling and Disabling Setuid Access		Turning setuid access on and off.
27.9 Setuid Program Example		The pertinent parts of one sample program.
27.10 Tips for Writing Setuid Programs		How to avoid granting unlimited access.

27.11 Identifying Who Logged In

Getting the name of the user who logged in, or of the real user ID of the current process.

27.12 The User Accounting Database

Keeping information about users and various actions in databases.

27.13 User Database		Functions and data structures for accessing the user database.
27.14 Group Database		Functions and data structures for accessing the group database.
27.15 User and Group Database Example		Example program showing the use of database inquiry functions.
27.16 Netgroup Database		Functions for accessing the netgroup database.

User Accounting Database

27.12.1 Manipulating the User Accounting Database		Scanning and modifying the user accounting database.
27.12.2 XPG User Accounting Database Functions		A standardized way for doing the same thing.
27.12.3 Logging In and Out		Functions from BSD that modify the user accounting database.

User Database

27.13.1 The Data Structure that Describes a User		What each user record contains.
27.13.2 Looking Up One User		How to look for a particular user.
27.13.3 Scanning the List of All Users		Scanning the list of all users, one by one.
27.13.4 Writing a User Entry		How a program can rewrite a user's record.

Group Database

27.14.1 The Data Structure for a Group		What each group record contains.
27.14.2 Looking Up One Group		How to look for a particular group.
27.14.3 Scanning the List of All Groups		Scanning the list of all groups.

Netgroup Database

27.16.1 Netgroup Data		Data in the Netgroup database and where it comes from.
27.16.2 Looking up one Netgroup		How to look for a particular netgroup.
27.16.3 Testing for Netgroup Membership		How to test for netgroup membership.

System Information

28.1 Host Identification		Determining the name of the machine.
28.2 Hardware/Software Type Identification		Determining the hardware type of the machine and what operating system it is running.
28.3 Which filesystems are mounted and/or available?		Which is mounted and/or available?

System Configuration

29.1 General Capacity Limits		Constants and functions that describe various process-related limits that have one uniform value for any given machine.
29.2 Overall System Options		Optional POSIX features.
29.3 Which Version of POSIX is Supported		Version numbers of POSIX.1 and POSIX.2.
29.4 Using sysconf		Getting specific configuration values of general limits and system options.
29.5 Minimum Values for General Capacity Limits		Minimum values for general limits.

29.6 Limits on File System Capacity		Size limitations that pertain to individual files. These can vary between file systems or even from file to file.
29.7 Optional Features in File Support		Optional features that some files may support.
29.8 Minimum Values for File System Limits		Minimum values for file limits.
29.9 Using pathconf		Getting the limit values for a particular file.

29.10 Utility Program Capacity Limits		Capacity limits of some POSIX.2 utility programs.
29.11 Minimum Values for Utility Limits		Minimum allowable values of those limits.

29.12 String-Valued Parameters

Getting the default search path.

Sysconf

29.4.1 Definition of sysconf		Detailed specifications of sysconf.
29.4.2 Constants for sysconf Parameters		The list of parameters sysconf can read.
29.4.3 Examples of sysconf		How to use sysconf and the parameter macros properly together.

Cryptographic Functions

30.1 Legal Problems		This software can get you locked up, or worse.
30.2 Reading Passwords		Prompting the user for a password.
30.3 Encrypting Passwords		A one-way function for UNIX passwords.
30.4 DES Encryption		Routines for DES encryption.

POSIX Threads

31.1 Basic Thread Operations		Creating, terminating, and waiting for threads.
31.2 Thread Attributes		Tuning thread scheduling.
31.3 Cancellation		Stopping a thread before it's done.
31.4 Cleanup Handlers		Deallocating resources when a thread is cancelled.
31.5 Mutexes		One way to synchronize threads.
31.6 Condition Variables		Another way.
31.7 POSIX Semaphores		And a third way.
31.8 Thread-Specific Data		Variables with different values in different threads.
31.9 Threads and Signal Handling		Why you should avoid mixing the two, and how to do it if you must.
31.10 Miscellaneous Thread Functions		A grab bag of utility routines.

Language Features

A.1 Explicitly Checking Internal Consistency		Using assert to abort if something "impossible" happens.
A.2 Variadic Functions		Defining functions with varying numbers of args.
A.3 Null Pointer Constant		The macro NULL.
A.4 Important Data Types		Data types for object sizes.
A.5 Data Type Measurements		Parameters of data type representations.

Variadic Functions

A.2.1 Why Variadic Functions are Used		Reasons for making functions take variable arguments.
A.2.2 How Variadic Functions are Defined and Used		How to define and call variadic functions.
A.2.3 Example of a Variadic Function		A complete example.

How Variadic

A.2.2.1 Syntax for Variable Arguments		How to make a prototype for a function with variable arguments.
A.2.2.2 Receiving the Argument Values		Steps you must follow to access the optional argument values.
A.2.2.3 How Many Arguments Were Supplied		How to decide whether there are more arguments.
A.2.2.4 Calling Variadic Functions		Things you need to know about calling variable arguments functions.
A.2.2.5 Argument Access Macros		Detailed specification of the macros for accessing variable arguments.
A.2.3.1 Old-Style Variadic Functions		The pre-ISO way of defining variadic functions.

Data Type Measurements

A.5.1 Computing the Width of an Integer Data Type		How many bits does an integer type hold?
A.5.2 Range of an Integer Type		What are the largest and smallest values that an integer type can hold?
A.5.3 Floating Type Macros		Parameters that measure the floating point types.
A.5.4 Structure Field Offset Measurement		Getting measurements on structure types.

Floating Type Macros

A.5.3.1 Floating Point Representation Concepts		Definitions of terminology.
A.5.3.2 Floating Point Parameters		Details of specific macros.
A.5.3.3 IEEE Floating Point		The measurements for one common representation.

Installation

C.1 Configuring and compiling GNU Libc		How to compile and test GNU libc.
C.2 Installing the C Library		How to install it once you've got it compiled.
C.3 Recommended Tools for Compilation		You'll need these first.
C.4 Supported Configurations		What it runs on, what it doesn't.
C.5 Specific advice for Linux systems		Specific advice for Linux systems.
C.6 Reporting Bugs		So they'll get fixed.

Maintenance

D.1 Adding New Functions		How to add new functions or header files to the GNU C library.
D.2 Porting the GNU C Library		How to port the GNU C library to a new machine or operating system.

Porting

D.2.1 Layout of the `sysdeps' Directory Hierarchy		The layout of the `sysdeps' hierarchy.
D.2.2 Porting the GNU C Library to Unix Systems		Porting the library to an average Unix-like system.