The GNU C Library

This is Edition 0.07 DRAFT, last updated 03 Apr 1998, of The GNU C Library Reference Manual, for Version 2.00 Beta of the GNU C Library.

• Introduction
  • Getting Started
  • Standards and Portability
    • ISO C
    • POSIX (The Portable Operating System Interface)
    • Berkeley Unix
    • SVID (The System V Interface Description)
    • XPG (The X/Open Portability Guide)
  • Using the Library
    • Header Files
    • Macro Definitions of Functions
    • Reserved Names
    • Feature Test Macros
  • Roadmap to the Manual
• Error Reporting
  • Checking for Errors
  • Error Codes
  • Error Messages
• Memory Allocation
  • Dynamic Memory Allocation Concepts
  • Dynamic Allocation and C
  • Unconstrained Allocation
    • Basic Storage Allocation
    • Examples of malloc
    • Freeing Memory Allocated with malloc
    • Changing the Size of a Block
    • Allocating Cleared Space
    • Efficiency Considerations for malloc
    • Allocating Aligned Memory Blocks
    • Malloc Tunable Parameters
    • Heap Consistency Checking
    • Storage Allocation Hooks
    • Statistics for Storage Allocation with malloc
    • Summary of malloc-Related Functions
  • Allocation Debugging
    • How to install the tracing functionality
    • Example programs excerpts
    • Some more or less clever ideas
    • Interpreting the traces
  • Obstacks
    • Creating Obstacks
    • Preparing for Using Obstacks
    • Allocation in an Obstack
    • Freeing Objects in an Obstack
    • Obstack Functions and Macros
    • Growing Objects
    • Extra Fast Growing Objects
    • Status of an Obstack
    • Alignment of Data in Obstacks
    • Obstack Chunks
    • Summary of Obstack Functions
  • Automatic Storage with Variable Size
    • alloca Example
    • Advantages of alloca
    • Disadvantages of alloca
    • GNU C Variable-Size Arrays
• Character Handling
  • Classification of Characters
  • Case Conversion
• String and Array Utilities
  • Representation of Strings
  • String and Array Conventions
  • String Length
  • Copying and Concatenation
  • String/Array Comparison
  • Collation Functions
  • Search Functions
  • Finding Tokens in a String
  • Encode Binary Data
  • Argz and Envz Vectors
    • Argz Functions
    • Envz Functions
• Extended Characters
  • Introduction to Extended Characters
  • Locales and Extended Characters
  • Multibyte Characters
  • Wide Character Introduction
  • Conversion of Extended Strings
  • Multibyte Character Length
  • Conversion of Extended Characters One by One
  • Character-by-Character Conversion Example
  • Multibyte Codes Using Shift Sequences
• Locales and Internationalization
  • What Effects a Locale Has
  • Choosing a Locale
  • Categories of Activities that Locales Affect
  • How Programs Set the Locale
  • Standard Locales
  • Accessing the Locale Information
    • localeconv: It is portable but ...
      • Generic Numeric Formatting Parameters
      • Printing the Currency Symbol
      • Printing the Sign of an Amount of Money
    • Pinpoint Access to Locale Data
  • A dedicated function to format numbers
• Message Translation
  • X/Open Message Catalog Handling
    • The catgets function family
    • Format of the message catalog files
    • Generate Message Catalogs files
    • How to use the catgets interface
      • Not using symbolic names
      • Using symbolic names
      • How does to this allow to develop
  • The Uniforum approach to Message Translation
    • The gettext family of functions
      • What has to be done to translate a message?
      • How to determine which catalog to be used
      • User influence on gettext
    • Programs to handle message catalogs for gettext
• Searching and Sorting
  • Defining the Comparison Function
  • Array Search Function
  • Array Sort Function
  • Searching and Sorting Example
  • The hsearch function.
  • The tsearch function.
• Pattern Matching
  • Wildcard Matching
  • Globbing
    • Calling glob
    • Flags for Globbing
    • More Flags for Globbing
  • Regular Expression Matching
    • POSIX Regular Expression Compilation
    • Flags for POSIX Regular Expressions
    • Matching a Compiled POSIX Regular Expression
    • Match Results with Subexpressions
    • Complications in Subexpression Matching
    • POSIX Regexp Matching Cleanup
  • Shell-Style Word Expansion
    • The Stages of Word Expansion
    • Calling wordexp
    • Flags for Word Expansion
    • wordexp Example
    • Details of Tilde Expansion
    • Details of Variable Substitution
• Input/Output Overview
  • Input/Output Concepts
    • Streams and File Descriptors
    • File Position
  • File Names
    • Directories
    • File Name Resolution
    • File Name Errors
    • Portability of File Names
• Input/Output on Streams
  • Streams
  • Standard Streams
  • Opening Streams
  • Closing Streams
  • Simple Output by Characters or Lines
  • Character Input
  • Line-Oriented Input
  • Unreading
    • What Unreading Means
    • Using ungetc To Do Unreading
  • Block Input/Output
  • Formatted Output
    • Formatted Output Basics
    • Output Conversion Syntax
    • Table of Output Conversions
    • Integer Conversions
    • Floating-Point Conversions
    • Other Output Conversions
    • Formatted Output Functions
    • Dynamically Allocating Formatted Output
    • Variable Arguments Output Functions
    • Parsing a Template String
    • Example of Parsing a Template String
  • Customizing printf
    • Registering New Conversions
    • Conversion Specifier Options
    • Defining the Output Handler
    • printf Extension Example
    • Predefined printf Handlers
  • Formatted Input
    • Formatted Input Basics
    • Input Conversion Syntax
    • Table of Input Conversions
    • Numeric Input Conversions
    • String Input Conversions
    • Dynamically Allocating String Conversions
    • Other Input Conversions
    • Formatted Input Functions
    • Variable Arguments Input Functions
  • End-Of-File and Errors
  • Text and Binary Streams
  • File Positioning
  • Portable File-Position Functions
  • Stream Buffering
    • Buffering Concepts
    • Flushing Buffers
    • Controlling Which Kind of Buffering
  • Other Kinds of Streams
    • String Streams
    • Obstack Streams
    • Programming Your Own Custom Streams
      • Custom Streams and Cookies
      • Custom Stream Hook Functions
  • Formatted Messages
    • Printing Formatted Messages
    • Adding Severity Classes
    • How to use fmtmsg and addseverity
• Low-Level Input/Output
  • Opening and Closing Files
  • Change the size of a file
  • Input and Output Primitives
  • Setting the File Position of a Descriptor
  • Descriptors and Streams
  • Dangers of Mixing Streams and Descriptors
    • Linked Channels
    • Independent Channels
    • Cleaning Streams
  • Fast Scatter-Gather I/O
  • Memory-mapped I/O
  • Waiting for Input or Output
  • Synchronizing I/O operations
  • Perform I/O Operations in Parallel
    • Asynchronous Read and Write Operations
    • Getting the Status of AIO Operations
    • Getting into a Consistent State
    • Cancelation of AIO Operations
    • How to optimize the AIO implementation
  • Control Operations on Files
  • Duplicating Descriptors
  • File Descriptor Flags
  • File Status Flags
    • File Access Modes
    • Open-time Flags
    • I/O Operating Modes
    • Getting and Setting File Status Flags
  • File Locks
  • Interrupt-Driven Input
  • Generic I/O Control operations
• File System Interface
  • Working Directory
  • Accessing Directories
    • Format of a Directory Entry
    • Opening a Directory Stream
    • Reading and Closing a Directory Stream
    • Simple Program to List a Directory
    • Random Access in a Directory Stream
    • Scanning the Content of a Directory
    • Simple Program to List a Directory, Mark II
  • Working on Directory Trees
  • Hard Links
  • Symbolic Links
  • Deleting Files
  • Renaming Files
  • Creating Directories
  • File Attributes
    • What the File Attribute Values Mean
    • Reading the Attributes of a File
    • Testing the Type of a File
    • File Owner
    • The Mode Bits for Access Permission
    • How Your Access to a File is Decided
    • Assigning File Permissions
    • Testing Permission to Access a File
    • File Times
    • File Size
  • Making Special Files
  • Temporary Files
• Pipes and FIFOs
  • Creating a Pipe
  • Pipe to a Subprocess
  • FIFO Special Files
  • Atomicity of Pipe I/O
• Sockets
  • Socket Concepts
  • Communication Styles
  • Socket Addresses
    • Address Formats
    • Setting the Address of a Socket
    • Reading the Address of a Socket
  • Interface Naming
  • The Local Namespace
    • Local Namespace Concepts
    • Details of Local Namespace
    • Example of Local-Namespace Sockets
  • The Internet Namespace
    • Internet Socket Address Formats
    • Host Addresses
      • Internet Host Addresses
      • Host Address Data Type
      • Host Address Functions
      • Host Names
    • Internet Ports
    • The Services Database
    • Byte Order Conversion
    • Protocols Database
    • Internet Socket Example
  • Other Namespaces
  • Opening and Closing Sockets
    • Creating a Socket
    • Closing a Socket
    • Socket Pairs
  • Using Sockets with Connections
    • Making a Connection
    • Listening for Connections
    • Accepting Connections
    • Who is Connected to Me?
    • Transferring Data
      • Sending Data
      • Receiving Data
      • Socket Data Options
    • Byte Stream Socket Example
    • Byte Stream Connection Server Example
    • Out-of-Band Data
  • Datagram Socket Operations
    • Sending Datagrams
    • Receiving Datagrams
    • Datagram Socket Example
    • Example of Reading Datagrams
  • The inetd Daemon
    • inetd Servers
    • Configuring inetd
  • Socket Options
    • Socket Option Functions
    • Socket-Level Options
  • Networks Database
• Low-Level Terminal Interface
  • Identifying Terminals
  • I/O Queues
  • Two Styles of Input: Canonical or Not
  • Terminal Modes
    • Terminal Mode Data Types
    • Terminal Mode Functions
    • Setting Terminal Modes Properly
    • Input Modes
    • Output Modes
    • Control Modes
    • Local Modes
    • Line Speed
    • Special Characters
      • Characters for Input Editing
      • Characters that Cause Signals
      • Special Characters for Flow Control
      • Other Special Characters
    • Noncanonical Input
  • Line Control Functions
  • Noncanonical Mode Example
  • Pseudo-Terminals
    • Allocating Pseudo-Terminals
    • Opening a Pseudo-Terminal Pair
• Mathematics
  • Predefined Mathematical Constants
  • Trigonometric Functions
  • Inverse Trigonometric Functions
  • Exponentiation and Logarithms
  • Hyperbolic Functions
  • Special Functions
  • Pseudo-Random Numbers
    • ISO C Random Number Functions
    • BSD Random Number Functions
    • SVID Random Number Function
  • Is Fast Code or Small Code preferred?
• Arithmetic Functions
  • Floating Point Numbers
  • Floating-Point Number Classification Functions
  • Errors in Floating-Point Calculations
    • FP Exceptions
    • Infinity and NaN
    • Examining the FPU status word
    • Error Reporting by Mathematical Functions
  • Rounding Modes
  • Floating-Point Control Functions
  • Arithmetic Functions
    • Absolute Value
    • Normalization Functions
    • Rounding Functions
    • Remainder Functions
    • Setting and modifying single bits of FP values
    • Floating-Point Comparison Functions
    • Miscellaneous FP arithmetic functions
  • Complex Numbers
  • Projections, Conjugates, and Decomposing of Complex Numbers
  • Integer Division
  • Parsing of Numbers
    • Parsing of Integers
    • Parsing of Floats
  • Old-fashioned System V number-to-string functions
• Date and Time
  • Processor Time
    • Basic CPU Time Inquiry
    • Detailed Elapsed CPU Time Inquiry
  • Calendar Time
    • Simple Calendar Time
    • High-Resolution Calendar
    • Broken-down Time
    • Formatting Date and Time
    • Specifying the Time Zone with TZ
    • Functions and Variables for Time Zones
    • Time Functions Example
  • Setting an Alarm
  • Sleeping
  • Resource Usage
  • Limiting Resource Usage
  • Process Priority
• Non-Local Exits
  • Introduction to Non-Local Exits
  • Details of Non-Local Exits
  • Non-Local Exits and Signals
• Signal Handling
  • Basic Concepts of Signals
    • Some Kinds of Signals
    • Concepts of Signal Generation
    • How Signals Are Delivered
  • Standard Signals
    • Program Error Signals
    • Termination Signals
    • Alarm Signals
    • Asynchronous I/O Signals
    • Job Control Signals
    • Operation Error Signals
    • Miscellaneous Signals
    • Signal Messages
  • Specifying Signal Actions
    • Basic Signal Handling
    • Advanced Signal Handling
    • Interaction of signal and sigaction
    • sigaction Function Example
    • Flags for sigaction
    • Initial Signal Actions
  • Defining Signal Handlers
    • Signal Handlers that Return
    • Handlers That Terminate the Process
    • Nonlocal Control Transfer in Handlers
    • Signals Arriving While a Handler Runs
    • Signals Close Together Merge into One
    • Signal Handling and Nonreentrant Functions
    • Atomic Data Access and Signal Handling
      • Problems with Non-Atomic Access
      • Atomic Types
      • Atomic Usage Patterns
  • Primitives Interrupted by Signals
  • Generating Signals
    • Signaling Yourself
    • Signaling Another Process
    • Permission for using kill
    • Using kill for Communication
  • Blocking Signals
    • Why Blocking Signals is Useful
    • Signal Sets
    • Process Signal Mask
    • Blocking to Test for Delivery of a Signal
    • Blocking Signals for a Handler
    • Checking for Pending Signals
    • Remembering a Signal to Act On Later
  • Waiting for a Signal
    • Using pause
    • Problems with pause
    • Using sigsuspend
  • Using a Separate Signal Stack
  • BSD Signal Handling
    • BSD Function to Establish a Handler
    • BSD Functions for Blocking Signals
• Process Startup and Termination
  • Program Arguments
    • Program Argument Syntax Conventions
    • Parsing Program Arguments
  • Parsing program options using getopt
    • Using the getopt function
    • Example of Parsing Arguments with getopt
    • Parsing Long Options with getopt_long
    • Example of Parsing Long Options with getopt_long
  • Parsing Program Options with Argp
    • The argp_parse Function
    • Argp Global Variables
    • Specifying Argp Parsers
    • Specifying Options in an Argp Parser
      • Flags for Argp Options
    • Argp Parser Functions
      • Special Keys for Argp Parser Functions
      • Functions For Use in Argp Parsers
      • Argp Parsing State
    • Combining Multiple Argp Parsers
    • Flags for argp_parse
    • Customizing Argp Help Output
      • Special Keys for Argp Help Filter Functions
    • The argp_help Function
    • Flags for the argp_help Function
    • Argp Examples
      • A Minimal Program Using Argp
      • A Program Using Argp with Only Default Options
      • A Program Using Argp with User Options
      • A Program Using Multiple Combined Argp Parsers
    • Argp User Customization
      • Parsing of Suboptions
    • Parsing of Suboptions Example
  • Environment Variables
    • Environment Access
    • Standard Environment Variables
  • Program Termination
    • Normal Termination
    • Exit Status
    • Cleanups on Exit
    • Aborting a Program
    • Termination Internals
• Processes
  • Running a Command
  • Process Creation Concepts
  • Process Identification
  • Creating a Process
  • Executing a File
  • Process Completion
  • Process Completion Status
  • BSD Process Wait Functions
  • Process Creation Example
• Job Control
  • Concepts of Job Control
  • Job Control is Optional
  • Controlling Terminal of a Process
  • Access to the Controlling Terminal
  • Orphaned Process Groups
  • Implementing a Job Control Shell
    • Data Structures for the Shell
    • Initializing the Shell
    • Launching Jobs
    • Foreground and Background
    • Stopped and Terminated Jobs
    • Continuing Stopped Jobs
    • The Missing Pieces
  • Functions for Job Control
    • Identifying the Controlling Terminal
    • Process Group Functions
    • Functions for Controlling Terminal Access
• System Databases and Name Service Switch
  • NSS Basics
  • The NSS Configuration File
    • Services in the NSS configuration File
    • Actions in the NSS configuration
    • Notes on the NSS Configuration File
  • NSS Module Internals
    • The Naming Scheme of the NSS Modules
    • The Interface of the Function in NSS Modules
  • Extending NSS
    • Adding another Service to NSS
    • Internals of the NSS Module Functions
• Users and Groups
  • User and Group IDs
  • The Persona of a Process
  • Why Change the Persona of a Process?
  • How an Application Can Change Persona
  • Reading the Persona of a Process
  • Setting the User ID
  • Setting the Group IDs
  • Enabling and Disabling Setuid Access
  • Setuid Program Example
  • Tips for Writing Setuid Programs
  • Identifying Who Logged In
  • The User Accounting Database
    • Manipulating the User Accounting Database
    • XPG User Accounting Database Functions
    • Logging In and Out
  • User Database
    • The Data Structure that Describes a User
    • Looking Up One User
    • Scanning the List of All Users
    • Writing a User Entry
  • Group Database
    • The Data Structure for a Group
    • Looking Up One Group
    • Scanning the List of All Groups
  • User and Group Database Example
  • Netgroup Database
    • Netgroup Data
    • Looking up one Netgroup
    • Testing for Netgroup Membership
• System Information
  • Host Identification
  • Hardware/Software Type Identification
  • Which filesystems are mounted and/or available?
• System Configuration Parameters
  • General Capacity Limits
  • Overall System Options
  • Which Version of POSIX is Supported
  • Using sysconf
    • Definition of sysconf
    • Constants for sysconf Parameters
    • Examples of sysconf
  • Minimum Values for General Capacity Limits
  • Limits on File System Capacity
  • Optional Features in File Support
  • Minimum Values for File System Limits
  • Using pathconf
  • Utility Program Capacity Limits
  • Minimum Values for Utility Limits
  • String-Valued Parameters
• POSIX Threads
  • Basic Thread Operations
  • Thread Attributes
  • Cancellation
  • Cleanup Handlers
  • Mutexes
  • Condition Variables
  • POSIX Semaphores
  • Thread-Specific Data
  • Threads and Signal Handling
  • Miscellaneous Thread Functions
• C Language Facilities in the Library
  • Explicitly Checking Internal Consistency
  • Variadic Functions
    • Why Variadic Functions are Used
    • How Variadic Functions are Defined and Used
      • Syntax for Variable Arguments
      • Receiving the Argument Values
      • How Many Arguments Were Supplied
      • Calling Variadic Functions
      • Argument Access Macros
    • Example of a Variadic Function
      • Old-Style Variadic Functions
  • Null Pointer Constant
  • Important Data Types
  • Data Type Measurements
    • Computing the Width of an Integer Data Type
    • Range of an Integer Type
    • Floating Type Macros
      • Floating Point Representation Concepts
      • Floating Point Parameters
      • IEEE Floating Point
    • Structure Field Offset Measurement
• Summary of Library Facilities
• Installing the GNU C Library
  • Configuring and compiling GNU Libc
  • Installing the C Library
  • Recommended Tools for Compilation
  • Supported Configurations
  • Specific advice for Linux systems
  • Reporting Bugs
• Library Maintenance
  • Adding New Functions
  • Porting the GNU C Library
    • Layout of the `sysdeps' Directory Hierarchy
    • Porting the GNU C Library to Unix Systems
• Contributors to the GNU C Library
• GNU LIBRARY GENERAL PUBLIC LICENSE
  • Preamble
  • TERMS AND CONDITIONS FOR COPYING,
    DISTRIBUTION AND MODIFICATION
  • How to Apply These Terms to Your New Libraries
• Concept Index
• Type Index
• Function and Macro Index
• Variable and Constant Macro Index
• Program and File Index

This document was generated on 11 Febuary 1999 using the texi2html translator version 1.54.