The GNU C Library

Next: Introduction, Previous: (dir), Up: (dir)

Main Menu

This is Edition 0.10, last updated 2001-07-06, of The GNU C Library Reference Manual, for Version 2.2.x 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

--- The Detailed Node Listing ---

Introduction

Standards and Portability

Using the Library

Error Reporting

Memory

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

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

Locking Pages

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

Character Set Handling

Restartable multibyte conversion

Non-reentrant Conversion

Generic Charset Conversion

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

Message Translation

Message catalogs a la X/Open

The Uniforum approach

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

Pattern Matching

Globbing

Regular Expressions

Word Expansion

I/O Overview

I/O Concepts

File Names

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

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

Other Kinds of Streams

Custom Streams

Formatted Messages

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

Asynchronous I/O

File Status 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

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

Local Namespace

Internet Namespace

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

Host Addresses

Open/Close Sockets

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

Datagrams

Inetd

Socket Options

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

Syslog

Submitting Syslog Messages

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

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.
System V Number Conversion: An archaic way to convert numbers to strings.

Floating Point Errors

Arithmetic Functions

Parsing of Numbers

Date and Time

Processor And CPU Time

Calendar Time

Simple Calendar Time: Facilities for manipulating calendar time.
High-Resolution Calendar: A time representation with greater precision.
Broken-down Time: Facilities for manipulating local time.
High Accuracy Clock: Maintaining a high accuracy system clock.
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

Resource Usage And Limitation

Priority

Traditional Scheduling

Memory Resources

Non-Local Exits

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

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

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

Generating Signals

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

BSD Signal Handling

Program Basics

Program Arguments

Parsing Program Arguments

Environment Variables

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.

Job Control

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

Implementing a Shell

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

Functions for Job Control

Name Service Switch

NSS Configuration File

NSS Module Internals

Extending NSS

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

User Database

Group Database

Netgroup Database

System Management

Filesystem Handling

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

Cryptographic Functions

Debugging Support

Language Features

Variadic Functions

How Variadic

Variadic Prototypes: How to make a prototype for a function with variable arguments.
Receiving Arguments: Steps you must follow to access the optional argument values.
How Many Arguments: How to decide whether there are more arguments.
Calling Variadics: Things you need to know about calling variable arguments functions.
Argument Macros: Detailed specification of the macros for accessing variable arguments.
Old Varargs: The pre-ISO way of defining variadic functions.

Data Type Measurements

Floating Type Macros

Installation

Maintenance

Porting