Top (The GNU C Library)

The GNU C Library

This is The GNU C Library Reference Manual, for version 2.33.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being “Free Software Needs Free Documentation” and “GNU Lesser General Public License”, the Front-Cover texts being “A GNU Manual”, and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled "GNU Free Documentation License".

(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing GNU and promoting software freedom.”

Short Table of Contents

Main Menu

• Introduction		Purpose of the GNU C Library.
• Error Reporting		How library functions report errors.
• Memory		Allocating virtual memory and controlling paging.
• Character Handling		Character testing and conversion functions.
• String and Array Utilities		Utilities for copying and comparing strings and arrays.
• Character Set Handling		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		High-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.
• Syslog		System logging and messaging.
• 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.
• Resource Usage And Limitation		Functions for examining resource usage and getting and setting limits.
• Non-Local Exits		Jumping out of nested function calls.
• Signal Handling		How to send, block, and handle signals.
• Program Basics		Writing the beginning and end of your program.
• Processes		How to create processes and run other programs.
• Inter-Process Communication		All about inter-process communication.
• Job Control		All about process groups and sessions.
• Name Service Switch		Accessing system databases.
• Users and Groups		How users are identified and classified.
• System Management		Controlling the system and getting information about it.
• System Configuration		Parameters describing operating system limits.
• Cryptographic Functions		Passphrase storage and strongly unpredictable bytes..
• Debugging Support		Functions to help debugging applications.
• Threads		Functions, constants, and data types for working with threads.
• Internal Probes		Probes to monitor libc internal behavior.
• Tunables		Tunable switches to alter libc internal behavior.
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.
• Platform		Describe all platform-specific facilities provided.
• Contributors		Who wrote what parts of the GNU C Library.
• Free Manuals		Free Software Needs Free Documentation.
• Copying		The GNU Lesser General Public License says how you can copy and share the GNU C Library.
• Documentation License		This manual is under the GNU Free Documentation License.
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.
POSIX
• POSIX Safety Concepts		Safety concepts from POSIX.
• Unsafe Features		Features that make functions unsafe.
• Conditionally Safe Features		Features that make functions unsafe in the absence of workarounds.
• Other Safety Remarks		Additional safety features and remarks.
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
• Memory Concepts		An introduction to concepts and terminology.
• Memory Allocation		Allocating storage for your program data
• Resizing the Data Segment		`brk`, `sbrk`
• Memory Protection		Controlling access to memory regions.
• Locking Pages		Preventing page faults
Memory Allocation
• Memory Allocation and C		How to get different kinds of allocation in C.
• The GNU Allocator		An overview of the GNU `malloc` implementation.
• Unconstrained Allocation		The `malloc` facility allows fully general dynamic allocation.
• Allocation Debugging		Finding memory leaks and not freed memory.
• Replacing malloc		Using your own `malloc`-style allocator.
• 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 `malloc`.
• Malloc Examples		Examples of `malloc`. `xmalloc`.
• Freeing after Malloc		Use `free` to free a block you got with `malloc`.
• Changing Block Size		Use `realloc` to make a block bigger or smaller.
• Allocating Cleared Space		Use `calloc` to allocate a block and clear it.
• Aligned Memory Blocks		Allocating specially aligned memory.
• Malloc Tunable Parameters		Use `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 `malloc`.
• Statistics of Malloc		Getting information about how much memory your program is using.
• Summary of Malloc		Summary of `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 `alloca`.
• Advantages of Alloca		Reasons to use `alloca`.
• Disadvantages of Alloca		Reasons to avoid `alloca`.
• GNU C Variable-Size Arrays		Only in GNU C, here is an alternative method of allocating dynamically and freeing automatically.
Locking Pages
• Why Lock Pages		Reasons to read this section.
• Locked Memory Details		Everything you need to know locked memory
• Page Lock Functions		Here’s how to do it.
Character Handling
• Classification of Characters		Testing whether characters are letters, digits, punctuation, etc.

• Case Conversion		Case mapping, and the like.
• Classification of Wide Characters		Character class determination for wide characters.
• Using Wide Char Classes		Notes on using the wide character classes.
• Wide Character Case Conversion		Mapping of wide characters.
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 Strings and Arrays		Functions to copy strings and arrays.
• Concatenating Strings		Functions to concatenate strings while copying.
• Truncating Strings		Functions to truncate strings while copying.
• 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.
• Erasing Sensitive Data		Clearing memory which contains sensitive data, after it’s no longer needed.
• Shuffling Bytes		Or how to flash-cook a string.
• Obfuscating Data		Reversibly obscuring data from casual view.
• 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.
Character Set Handling
• Extended Char Intro		Introduction to Extended Characters.
• Charset Function Overview		Overview about Character Handling Functions.
• Restartable multibyte conversion		Restartable multibyte conversion Functions.
• Non-reentrant Conversion		Non-reentrant Conversion Function.
• Generic Charset Conversion		Generic Charset Conversion.
Restartable multibyte conversion
• Selecting the Conversion		Selecting the conversion and its properties.
• Keeping the state		Representing the state of the conversion.
• Converting a Character		Converting Single Characters.
• Converting Strings		Converting Multibyte and Wide Character Strings.
• Multibyte Conversion Example		A Complete Multibyte Conversion Example.
Non-reentrant Conversion
• Non-reentrant Character Conversion		Non-reentrant Conversion of Single Characters.
• Non-reentrant String Conversion		Non-reentrant Conversion of Strings.
• Shift State		States in Non-reentrant Functions.
Generic Charset Conversion
• Generic Conversion Interface		Generic Character Set Conversion Interface.
• iconv Examples		A complete `iconv` example.
• Other iconv Implementations		Some Details about other `iconv` Implementations.
• glibc iconv Implementation		The `iconv` Implementation in the GNU C library.
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 Names		Format of system-specific locale names.
• Locale Information		How to access the information for the locale.
• Formatting Numbers		A dedicated function to format numbers.
• Yes-or-No Questions		Check a Response against the locale.
Locale Information
• The Lame Way to Locale Data		ISO C’s `localeconv`.
• The Elegant and Fast Way		X/Open’s `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. ‘`$`’).
• 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 `catgets` family of functions.
• The Uniforum approach		The `gettext` family of functions.
Message catalogs a la X/Open
• The catgets Functions		The `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 `catgets` interface.
The Uniforum approach
• Message catalogs with gettext		The `gettext` family of functions.
• Helper programs for gettext		Programs to handle message catalogs for `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.
• Advanced gettext functions		Additional functions for more complicated situations.
• Charset conversion in gettext		How to specify the output character set `gettext` uses.
• GUI program problems		How to use `gettext` in GUI programs.
• Using gettextized software		The possibilities of the user to influence the way `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 `bsearch` function.
• Array Sort Function		The `qsort` function.
• Search/Sort Example		An example program.
• Hash Search Function		The `hsearch` function.
• Tree Search Function		The `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 `glob`.
• Flags for Globbing		Flags that enable various options in `glob`.
• More Flags for Globbing		GNU specific extensions to `glob`.
Regular Expressions
• POSIX Regexp Compilation		Using `regcomp` to prepare to match.
• Flags for POSIX Regexps		Syntax variations for `regcomp`.
• Matching POSIX Regexps		Using `regexec` to match the compiled pattern that you get from `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 `wordexp`.
• Flags for Wordexp		Options you can enable in `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 C 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.
• Streams and Threads		Issues with streams in threaded programs.
• Streams and I18N		Streams in internationalized applications.
• 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		`printf` and related functions.
• Customizing Printf		You can define new conversion specifiers for `printf` and friends.
• Formatted Input		`scanf` and related functions.
• EOF and Errors		How you can tell if an I/O error happens.
• Error Recovery		What you can do about errors.
• 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 `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		`vprintf` and friends.
• Parsing a Template String		What kinds of args does a given template call for?
• Example of Parsing		Sample program using `parse_printf_format`.
Customizing Printf
• Registering New Conversions		Using `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 `register_printf_function`.
• Printf Extension Example		How to define a `printf` handler function.
• Predefined Printf Handlers		Predefined `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 `malloc` the buffer.
• Other Input Conversions		Details of miscellaneous other conversions.
• Formatted Input Functions		Descriptions of the actual functions.
• Variable Arguments Input		`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.
• Custom Streams		Defining your own streams with an arbitrary input data source and/or output data sink.
Custom Streams
• Streams and Cookies		The cookie records where to fetch or store data that is read or written.
• Hook Functions		How you should define the four hook functions that a custom stream needs.
Formatted Messages
• Printing Formatted Messages		The `fmtmsg` function.
• Adding Severity Classes		Add more severity classes.
• Example		How to use `fmtmsg` and `addseverity`.
Low-Level I/O
• Opening and Closing Files		How to open and close file descriptors.
• 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 discontinuous buffers.
• Copying File Data		Copying data between files.
• 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.
• Open File Description Locks		Fcntl commands for implementing open file description locking.
• Open File Description Locks Example		An example of open file description lock usage
• 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		Cancellation 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 `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 with 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.
• Low-level Directory Access		AS-Safe functions for directory access.
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.
• Storage Allocation		Allocate backing storage for files.
Pipes and FIFOs
• Creating a Pipe		Making a pipe with the `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 `struct sockaddr`.
• Setting Address		Binding an address to a socket.
• Reading Address		Reading the address of a socket.
Local Namespace
• Concepts		What you need to understand.
• Details		Address format, symbolic names, etc.
• 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.
• 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.
• Protocols Database		Referring to protocols by name.
• Inet Example		Putting it all together.
Host Addresses
• Abstract Host Addresses		What a host number consists of.
• Data type		Data type for a host number.
• Functions		Functions to operate on them.
• 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 `send`.
• Receiving Data		Reading data with `recv`.
• Socket Data Options		Using `send` and `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. Posix.
• BSD Terminal Modes		BSD compatible terminal mode setting
• Line Control		Sending break sequences, clearing terminal buffers …
• Noncanon Example		How to read single characters without echo.
• getpass		Prompting the user for a passphrase.
• Pseudo-Terminals		How to open a pseudo-terminal.
Terminal Modes
• Mode Data Types		The data type `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.
Syslog
• Overview of Syslog		Overview of a system’s Syslog facility
• Submitting Syslog Messages		Functions to submit messages to Syslog
Submitting Syslog Messages
• openlog		Open connection to Syslog
• syslog; vsyslog		Submit message to Syslog
• closelog		Close connection to Syslog
• setlogmask		Cause certain messages to be ignored
• Syslog Example		Example of all of the above
Mathematics
• Mathematical Constants		Precise numeric values for often-used constants.
• Trig Functions		Sine, cosine, tangent, and friends.

• Introduction

Purpose of the GNU C Library.

• Error Reporting

How library functions report errors.

• Memory

Allocating virtual memory and controlling paging.

• Character Handling

Character testing and conversion functions.

• String and Array Utilities

Utilities for copying and comparing strings and arrays.

• Character Set Handling

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

High-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.

• Syslog

System logging and messaging.

• 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.

• Resource Usage And Limitation

Functions for examining resource usage and getting and setting limits.

• Non-Local Exits

Jumping out of nested function calls.

• Signal Handling

How to send, block, and handle signals.

• Program Basics

Writing the beginning and end of your program.

• Processes

How to create processes and run other programs.

• Inter-Process Communication

All about inter-process communication.

• Job Control

All about process groups and sessions.

• Name Service Switch

Accessing system databases.

• Users and Groups

How users are identified and classified.

• System Management

Controlling the system and getting information about it.

• System Configuration

Parameters describing operating system limits.

• Cryptographic Functions

Passphrase storage and strongly unpredictable bytes..

• Debugging Support

Functions to help debugging applications.

• Threads

Functions, constants, and data types for working with threads.

• Internal Probes

Probes to monitor libc internal behavior.

• Tunables

Tunable switches to alter libc internal behavior.


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.

• Platform

Describe all platform-specific facilities provided.

• Contributors

Who wrote what parts of the GNU C Library.

• Free Manuals

Free Software Needs Free Documentation.

• Copying

The GNU Lesser General Public License says how you can copy and share the GNU C Library.

• Documentation License

This manual is under the GNU Free Documentation License.


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.


POSIX

• POSIX Safety Concepts

Safety concepts from POSIX.

• Unsafe Features

Features that make functions unsafe.

• Conditionally Safe Features

Features that make functions unsafe in the absence of workarounds.

• Other Safety Remarks

Additional safety features and remarks.


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

• Memory Concepts

An introduction to concepts and terminology.

• Memory Allocation

Allocating storage for your program data

• Resizing the Data Segment

brk, sbrk

• Memory Protection

Controlling access to memory regions.

• Locking Pages

Preventing page faults


Memory Allocation

• Memory Allocation and C

How to get different kinds of allocation in C.

• The GNU Allocator

An overview of the GNU malloc implementation.

• Unconstrained Allocation

The malloc facility allows fully general dynamic allocation.

• Allocation Debugging

Finding memory leaks and not freed memory.

• Replacing malloc

Using your own malloc-style allocator.

• 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 malloc.

• Malloc Examples

Examples of malloc. xmalloc.

• Freeing after Malloc

Use free to free a block you got with malloc.

• Changing Block Size

Use realloc to make a block bigger or smaller.

• Allocating Cleared Space

Use calloc to allocate a block and clear it.

• Aligned Memory Blocks

Allocating specially aligned memory.

• Malloc Tunable Parameters

Use 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 malloc.

• Statistics of Malloc

Getting information about how much memory your program is using.

• Summary of Malloc

Summary of 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 alloca.

• Advantages of Alloca

Reasons to use alloca.

• Disadvantages of Alloca

Reasons to avoid alloca.

• GNU C Variable-Size Arrays

Only in GNU C, here is an alternative method of allocating dynamically and freeing automatically.


Locking Pages

• Why Lock Pages

Reasons to read this section.

• Locked Memory Details

Everything you need to know locked memory

• Page Lock Functions

Here’s how to do it.


Character Handling

• Classification of Characters

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

• Case Conversion

Case mapping, and the like.

• Classification of Wide Characters

Character class determination for wide characters.

• Using Wide Char Classes

Notes on using the wide character classes.

• Wide Character Case Conversion

Mapping of wide characters.


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 Strings and Arrays

Functions to copy strings and arrays.

• Concatenating Strings

Functions to concatenate strings while copying.

• Truncating Strings

Functions to truncate strings while copying.

• 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.

• Erasing Sensitive Data

Clearing memory which contains sensitive data, after it’s no longer needed.

• Shuffling Bytes

Or how to flash-cook a string.

• Obfuscating Data

Reversibly obscuring data from casual view.

• 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.


Character Set Handling

• Extended Char Intro

Introduction to Extended Characters.

• Charset Function Overview

Overview about Character Handling Functions.

• Restartable multibyte conversion

Restartable multibyte conversion Functions.

• Non-reentrant Conversion

Non-reentrant Conversion Function.

• Generic Charset Conversion

Generic Charset Conversion.


Restartable multibyte conversion

• Selecting the Conversion

Selecting the conversion and its properties.

• Keeping the state

Representing the state of the conversion.

• Converting a Character

Converting Single Characters.

• Converting Strings

Converting Multibyte and Wide Character Strings.

• Multibyte Conversion Example

A Complete Multibyte Conversion Example.


Non-reentrant Conversion

• Non-reentrant Character Conversion

Non-reentrant Conversion of Single Characters.

• Non-reentrant String Conversion

Non-reentrant Conversion of Strings.

• Shift State

States in Non-reentrant Functions.


Generic Charset Conversion

• Generic Conversion Interface

Generic Character Set Conversion Interface.

• iconv Examples

A complete iconv example.

• Other iconv Implementations

Some Details about other iconv Implementations.

• glibc iconv Implementation

The iconv Implementation in the GNU C library.


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 Names

Format of system-specific locale names.

• Locale Information

How to access the information for the locale.

• Formatting Numbers

A dedicated function to format numbers.

• Yes-or-No Questions

Check a Response against the locale.


Locale Information

• The Lame Way to Locale Data

ISO C’s localeconv.

• The Elegant and Fast Way

X/Open’s 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. ‘$’).

• 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 catgets family of functions.

• The Uniforum approach

The gettext family of functions.


Message catalogs a la X/Open

• The catgets Functions

The 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 catgets interface.


The Uniforum approach

• Message catalogs with gettext

The gettext family of functions.

• Helper programs for gettext

Programs to handle message catalogs for 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.

• Advanced gettext functions

Additional functions for more complicated situations.

• Charset conversion in gettext

How to specify the output character set gettext uses.

• GUI program problems

How to use gettext in GUI programs.

• Using gettextized software

The possibilities of the user to influence the way 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 bsearch function.

• Array Sort Function

The qsort function.

• Search/Sort Example

An example program.

• Hash Search Function

The hsearch function.

• Tree Search Function

The 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 glob.

• Flags for Globbing

Flags that enable various options in glob.

• More Flags for Globbing

GNU specific extensions to glob.


Regular Expressions

• POSIX Regexp Compilation

Using regcomp to prepare to match.

• Flags for POSIX Regexps

Syntax variations for regcomp.

• Matching POSIX Regexps

Using regexec to match the compiled pattern that you get from 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 wordexp.

• Flags for Wordexp

Options you can enable in 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 C 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.

• Streams and Threads

Issues with streams in threaded programs.

• Streams and I18N

Streams in internationalized applications.

• 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

printf and related functions.

• Customizing Printf

You can define new conversion specifiers for printf and friends.

• Formatted Input

scanf and related functions.

• EOF and Errors

How you can tell if an I/O error happens.

• Error Recovery

What you can do about errors.

• 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 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

vprintf and friends.

• Parsing a Template String

What kinds of args does a given template call for?

• Example of Parsing

Sample program using parse_printf_format.


Customizing Printf

• Registering New Conversions

Using 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 register_printf_function.

• Printf Extension Example

How to define a printf handler function.

• Predefined Printf Handlers

Predefined 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 malloc the buffer.

• Other Input Conversions

Details of miscellaneous other conversions.

• Formatted Input Functions

Descriptions of the actual functions.

• Variable Arguments Input

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.

• Custom Streams

Defining your own streams with an arbitrary input data source and/or output data sink.


Custom Streams

• Streams and Cookies

The cookie records where to fetch or store data that is read or written.

• Hook Functions

How you should define the four hook functions that a custom stream needs.


Formatted Messages

• Printing Formatted Messages

The fmtmsg function.

• Adding Severity Classes

Add more severity classes.

• Example

How to use fmtmsg and addseverity.


Low-Level I/O

• Opening and Closing Files

How to open and close file descriptors.

• 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 discontinuous buffers.

• Copying File Data

Copying data between files.

• 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.

• Open File Description Locks

Fcntl commands for implementing open file description locking.

• Open File Description Locks Example

An example of open file description lock usage

• 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

Cancellation 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 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 with 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.

• Low-level Directory Access

AS-Safe functions for directory access.


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.

• Storage Allocation

Allocate backing storage for files.


Pipes and FIFOs

• Creating a Pipe

Making a pipe with the 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 struct sockaddr.

• Setting Address

Binding an address to a socket.

• Reading Address

Reading the address of a socket.


Local Namespace

• Concepts

What you need to understand.

• Details

Address format, symbolic names, etc.

• 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.

• 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.

• Protocols Database

Referring to protocols by name.

• Inet Example

Putting it all together.


Host Addresses

• Abstract Host Addresses

What a host number consists of.

• Data type

Data type for a host number.

• Functions

Functions to operate on them.

• 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 send.

• Receiving Data

Reading data with recv.

• Socket Data Options

Using send and 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. Posix.

• BSD Terminal Modes

BSD compatible terminal mode setting

• Line Control

Sending break sequences, clearing terminal buffers …

• Noncanon Example

How to read single characters without echo.

• getpass

Prompting the user for a passphrase.

• Pseudo-Terminals

How to open a pseudo-terminal.


Terminal Modes

• Mode Data Types

The data type 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.


Syslog

• Overview of Syslog

Overview of a system’s Syslog facility

• Submitting Syslog Messages

Functions to submit messages to Syslog


Submitting Syslog Messages

• openlog

Open connection to Syslog

• syslog; vsyslog

Submit message to Syslog

• closelog

Close connection to Syslog

• setlogmask

Cause certain messages to be ignored

• Syslog Example

Example of all of the above


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.

• Errors in Math Functions

Known Maximum Errors in Math Functions.

• Pseudo-Random Numbers

Functions for generating pseudo-random numbers.

• FP Function Optimizations

Fast code or small code.


Pseudo-Random Numbers

• ISO Random

rand and friends.

• BSD Random

random and friends.

• SVID Random

drand48 and friends.


Arithmetic

• Integers

Basic integer types and concepts

• Integer Division

Integer division with guaranteed rounding.

• 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.

• Parsing of Numbers

Converting strings to numbers.

• Printing of Floats

Converting floating-point numbers to strings.

• 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

• Time Basics

Concepts and definitions.

• Time Types

Data types to represent time.

• Calculating Elapsed Time

How to calculate the length of an interval.

• Processor And CPU Time

Time a program has spent executing.

• 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.


Processor And CPU Time

• CPU Time

The clock function.

• Processor Time

The times function.


Calendar Time

• Getting the Time

Functions for finding out what time it is.

• Setting and Adjusting the Time

Functions for setting and adjusting the system clock.

• Broken-down Time

Facilities for manipulating local time.

• Formatting Calendar Time

Converting times to strings.

• Parsing Date and Time

Convert textual time and date information back into broken-down time values.

• 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.


Parsing Date and Time

• Low-Level Time String Parsing

Interpret string according to given format.

• General Time String Parsing

User-friendly function to parse data and time strings.


Resource Usage And Limitation

• Resource Usage

Measuring various resources used.

• Limits on Resources

Specifying limits on resource usage.

• Priority

Reading or setting process run priority.

• Memory Resources

Querying memory available resources.

• Processor Resources

Learn about the processors available.


Priority

• Absolute Priority

The first tier of priority. Posix

• Realtime Scheduling

Scheduling among the process nobility

• Basic Scheduling Functions

Get/set scheduling policy, priority

• Traditional Scheduling

Scheduling among the vulgar masses

• CPU Affinity

Limiting execution to certain CPUs


Traditional Scheduling

• Traditional Scheduling Intro

• Traditional Scheduling Functions


Memory Resources

• Memory Subsystem

Overview about traditional Unix memory handling.

• Query Memory Parameters

How to get information about the memory subsystem?


Non-Local Exits

• Intro

When and how to use these facilities.

• Details

Functions for non-local exits.

• Non-Local Exits and Signals

Portability issues.

• System V contexts

Complete context control a la System V.


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 open, read, 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 signal function.

• Advanced Signal Handling

The more powerful 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

Data types that guarantee no interruption.

• 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 kill.

• Kill Example

Using 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 pause.

• Pause Problems

Why the simple way is often not very good.

• Sigsuspend

Reliably waiting for a specific signal.


Program Basics

• Program Arguments

Parsing your program’s command-line arguments

• Environment Variables

Less direct parameters affecting your program

• Auxiliary Vector

Least direct parameters affecting your program

• System Calls

Requesting service from the system

• Program Termination

Telling the system you’re done; return status


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 getopt.

• Argp

Parsing program options using argp_parse.

• Suboptions

Some programs need more detailed options.

• Suboptions Example

This shows how it could be done for 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 exit, a process terminates normally.

• Exit Status

The 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 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.


Inter-Process Communication

• Semaphores

Support for creating and managing semaphores


Job Control

• Concepts of Job Control

Jobs can be controlled by a shell.

• 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 Management

• Host Identification

Determining the name of the machine.

• Platform Type

Determining operating system and basic machine type

• Filesystem Handling

Controlling/querying mounts


Filesystem Handling

• Mount Information

What is or could be mounted?

• Mount-Unmount-Remount

Controlling what is mounted and how


Mount Information

• fstab

The fstab file

• mtab

The mtab file

• Other Mount Information

Other (non-libc) sources of mount information


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 sysconf.

• Constants for Sysconf

The list of parameters sysconf can read.

• Examples of Sysconf

How to use sysconf and the parameter macros properly together.


Cryptographic Functions

• Passphrase Storage

One-way hashing for passphrases.

• Unpredictable Bytes

Randomness for cryptographic purposes.


Debugging Support

• Backtraces

Obtaining and printing a back trace of the current stack.


Threads

• ISO C Threads

Threads based on the ISO C specification.

• POSIX Threads

Threads based on the POSIX specification.


ISO C Threads

• ISO C Threads Return Values

Symbolic constants that represent a function’s return value.

• ISO C Thread Management

Support for basic threading.

• Call Once

Single-call functions and macros.

• ISO C Mutexes

A low-level mechanism for mutual exclusion.

• ISO C Condition Variables

High-level objects for thread synchronization.

• ISO C Thread-local Storage

Functions to support thread-local storage.


POSIX Threads

• Thread-specific Data

Support for creating and managing thread-specific data

• Non-POSIX Extensions

Additional functions to extend POSIX Thread functionality


Non-POSIX Extensions

• Default Thread Attributes

Setting default attributes for threads in a process.

• Initial Thread Signal Mask

Setting the initial mask of threads.

• Waiting with Explicit Clocks

Functions for waiting with an explicit clock specification.

• Single-Threaded

Detecting single-threaded execution.


Internal Probes

• Memory Allocation Probes

Probes in the memory allocation subsystem

• Mathematical Function Probes

Probes in mathematical functions

• Non-local Goto Probes

Probes in setjmp and longjmp


Tunables

• Tunable names

The structure of a tunable name

• Memory Allocation Tunables

Tunables in the memory allocation subsystem

• Dynamic Linking Tunables

Tunables in the dynamic linking subsystem

• Elision Tunables

Tunables in elision subsystem

• POSIX Thread Tunables

Tunables in the POSIX thread subsystem

• Hardware Capability Tunables

Tunables that modify the hardware capabilities seen by the GNU C Library

• Memory Related Tunables

Tunables that control the use of memory by the GNU C Library.


Language Features

• Consistency Checking

Using assert to abort if something “impossible” happens.

• Variadic Functions

Defining functions with varying numbers of args.

• Null Pointer Constant

The macro 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.


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

• Configuring and compiling

How to compile and test GNU libc.

• Running make install

How to install it once you’ve got it compiled.

• Tools for Compilation

You’ll need these first.

• Linux

Specific advice for GNU/Linux systems.

• Reporting Bugs

So they’ll get fixed.


Maintenance

• Source Layout

How to add new functions or header files to the GNU C Library.

• Symbol handling

How to handle symbols in the GNU C Library.

• Porting

How to port the GNU C Library to a new machine or operating system.


Source Layout

• Platform

Adding platform-specific features.


Symbol handling

• 64-bit time symbol handling

How to handle 64-bit time related symbols in the GNU C Library.


Porting

• Hierarchy Conventions

The layout of the sysdeps hierarchy.

• Porting to Unix

Porting the library to an average Unix-like system.


Platform

• PowerPC

Facilities Specific to the PowerPC Architecture

• RISC-V

Facilities Specific to the RISC-V Architecture

• X86

Facilities Specific to the X86 Architecture