The GNU C Library

Main Menu

This is Edition 0.11, last updated 2007-09-09, of The GNU C Library Reference Manual, for Version 2.7 of the GNU C Library.

• 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.
• 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: DES encryption and password handling.
• Debugging Support: Functions to help debugging applications.

Appendices

• Language Features: C language features provided by the library.
• Library Summary: A summary showing the syntax, header file, and derivation of each library feature.
• Installation: How to install the GNU C library.
• Maintenance: How to enhance and port the GNU C Library.
• Contributors: Who wrote what parts of the GNU C library.
• 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.

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
• Locking Pages: Preventing page faults
• Resizing the Data Segment: brk, sbrk

Memory Allocation

• Memory Allocation and C: How to get different kinds of allocation in C.
• Unconstrained Allocation: The malloc facility allows fully general dynamic allocation.
• Allocation Debugging: Finding memory leaks and not freed memory.
• Obstacks: Obstacks are less general than malloc but more efficient and convenient.
• Variable Size Automatic: Allocation of variable-sized blocks of automatic storage that are freed when the calling function returns.

Unconstrained Allocation

• Basic Allocation: Simple use of 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.
• Efficiency and Malloc: Efficiency considerations in use of these functions.
• 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 and Concatenation: Functions to copy the contents of strings and arrays.
• String/Array Comparison: Functions for byte-wise and character-wise comparison.
• Collation Functions: Functions for collating strings.
• Search Functions: Searching for a specific element or substring.
• Finding Tokens in a String: Splitting a string into tokens by looking for delimiters.
• strfry: Function for flash-cooking a string.
• Trivial Encryption: Obscuring data.
• 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 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 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.
• Obstack Streams: Streams that store data in an obstack.
• Custom Streams: Defining your own streams with an arbitrary input data source and/or output data sink.

Custom Streams

• Streams and Cookies: The 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.
• Memory-mapped I/O: Using files like memory.
• Waiting for I/O: How to check for input or output on multiple file descriptors.
• Synchronizing I/O: Making sure all I/O actions completed.
• Asynchronous I/O: Perform I/O in parallel.
• Control Operations: Various other operations on file descriptors.
• Duplicating Descriptors: Fcntl commands for duplicating file descriptors.
• Descriptor Flags: Fcntl commands for manipulating flags associated with file descriptors.
• File Status Flags: Fcntl commands for manipulating flags associated with open files.
• File Locks: Fcntl commands for implementing file locking.
• Interrupt Input: Getting an asynchronous signal when input arrives.
• IOCTLs: Generic I/O Control operations.

Stream/Descriptor Precautions

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

Asynchronous I/O

• Asynchronous Reads/Writes: Asynchronous Read and Write Operations.
• Status of AIO Operations: Getting the Status of AIO Operations.
• Synchronizing AIO Operations: Getting into a consistent state.
• Cancel AIO Operations: 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.

File Attributes

• Attribute Meanings: The names of the file attributes, and what their values mean.
• Reading Attributes: How to read the attributes of a file.
• Testing File Type: Distinguishing ordinary files, directories, links...
• File Owner: How ownership for new files is determined, and how to change it.
• Permission Bits: How information about a file's access mode is stored.
• Access Permission: How the system decides who can access a file.
• Setting Permissions: How permissions for new files are assigned, and how to change them.
• Testing File Access: How to find out if your process can access a file.
• File Times: About the time attributes of a file.
• File Size: Manually changing the size of a file.

Pipes and FIFOs

• Creating a Pipe: Making a pipe with the 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 Forma