The GNU C Library

• 1 Introduction
  • 1.1 Getting Started
  • 1.2 Standards and Portability
    • 1.2.1 ISO C
    • 1.2.2 POSIX (The Portable Operating System Interface)
    • 1.2.3 Berkeley Unix
    • 1.2.4 SVID (The System V Interface Description)
  • 1.3 Using the Library
    • 1.3.1 Header Files
    • 1.3.2 Macro Definitions of Functions
    • 1.3.3 Reserved Names
    • 1.3.4 Feature Test Macros
  • 1.4 Roadmap to the Manual
• 2 Error Reporting
  • 2.1 Checking for Errors
  • 2.2 Error Codes
  • 2.3 Error Messages
• 3 Memory Allocation
  • 3.1 Dynamic Memory Allocation Concepts
  • 3.2 Dynamic Allocation and C
  • 3.3 Unconstrained Allocation
    • 3.3.1 Basic Storage Allocation
    • 3.3.2 Examples of malloc
    • 3.3.3 Freeing Memory Allocated with malloc
    • 3.3.4 Changing the Size of a Block
    • 3.3.5 Allocating Cleared Space
    • 3.3.6 Efficiency Considerations for malloc
    • 3.3.7 Allocating Aligned Memory Blocks
    • 3.3.8 Malloc Tunable Parameters
    • 3.3.9 Heap Consistency Checking
    • 3.3.10 Storage Allocation Hooks
    • 3.3.11 Statistics for Storage Allocation with malloc
    • 3.3.12 Summary of malloc-Related Functions
  • 3.4 Obstacks
    • 3.4.1 Creating Obstacks
    • 3.4.2 Preparing for Using Obstacks
    • 3.4.3 Allocation in an Obstack
    • 3.4.4 Freeing Objects in an Obstack
    • 3.4.5 Obstack Functions and Macros
    • 3.4.6 Growing Objects
    • 3.4.7 Extra Fast Growing Objects
    • 3.4.8 Status of an Obstack
    • 3.4.9 Alignment of Data in Obstacks
    • 3.4.10 Obstack Chunks
    • 3.4.11 Summary of Obstack Functions
  • 3.5 Automatic Storage with Variable Size
    • 3.5.1 alloca Example
    • 3.5.2 Advantages of alloca
    • 3.5.3 Disadvantages of alloca
    • 3.5.4 GNU C Variable-Size Arrays
  • 3.6 Relocating Allocator
    • 3.6.1 Concepts of Relocating Allocation
    • 3.6.2 Allocating and Freeing Relocatable Blocks
• 4 Character Handling
  • 4.1 Classification of Characters
  • 4.2 Case Conversion
• 5 String and Array Utilities
  • 5.1 Representation of Strings
  • 5.2 String and Array Conventions
  • 5.3 String Length
  • 5.4 Copying and Concatenation
  • 5.5 String/Array Comparison
  • 5.6 Collation Functions
  • 5.7 Search Functions
  • 5.8 Finding Tokens in a String
• 6 Input/Output Overview
  • 6.1 Input/Output Concepts
    • 6.1.1 Streams and File Descriptors
    • 6.1.2 File Position
  • 6.2 File Names
    • 6.2.1 Directories
    • 6.2.2 File Name Resolution
    • 6.2.3 File Name Errors
    • 6.2.4 Portability of File Names
• 7 Input/Output on Streams
  • 7.1 Streams
  • 7.2 Standard Streams
  • 7.3 Opening Streams
  • 7.4 Closing Streams
  • 7.5 Simple Output by Characters or Lines
  • 7.6 Character Input
  • 7.7 Line-Oriented Input
  • 7.8 Unreading
    • 7.8.1 What Unreading Means
    • 7.8.2 Using ungetc To Do Unreading
  • 7.9 Block Input/Output
  • 7.10 Formatted Output
    • 7.10.1 Formatted Output Basics
    • 7.10.2 Output Conversion Syntax
    • 7.10.3 Table of Output Conversions
    • 7.10.4 Integer Conversions
    • 7.10.5 Floating-Point Conversions
    • 7.10.6 Other Output Conversions
    • 7.10.7 Formatted Output Functions
    • 7.10.8 Dynamically Allocating Formatted Output
    • 7.10.9 Variable Arguments Output Functions
    • 7.10.10 Parsing a Template String
    • 7.10.11 Example of Parsing a Template String
  • 7.11 Customizing printf
    • 7.11.1 Registering New Conversions
    • 7.11.2 Conversion Specifier Options
    • 7.11.3 Defining the Output Handler
    • 7.11.4 printf Extension Example
  • 7.12 Formatted Input
    • 7.12.1 Formatted Input Basics
    • 7.12.2 Input Conversion Syntax
    • 7.12.3 Table of Input Conversions
    • 7.12.4 Numeric Input Conversions
    • 7.12.5 String Input Conversions
    • 7.12.6 Dynamically Allocating String Conversions
    • 7.12.7 Other Input Conversions
    • 7.12.8 Formatted Input Functions
    • 7.12.9 Variable Arguments Input Functions
  • 7.13 End-Of-File and Errors
  • 7.14 Text and Binary Streams
  • 7.15 File Positioning
  • 7.16 Portable File-Position Functions
  • 7.17 Stream Buffering
    • 7.17.1 Buffering Concepts
    • 7.17.2 Flushing Buffers
    • 7.17.3 Controlling Which Kind of Buffering
  • 7.18 Other Kinds of Streams
    • 7.18.1 String Streams
    • 7.18.2 Obstack Streams
    • 7.18.3 Programming Your Own Custom Streams
      • 7.18.3.1 Custom Streams and Cookies
      • 7.18.3.2 Custom Stream Hook Functions
• 8 Low-Level Input/Output
  • 8.1 Opening and Closing Files
  • 8.2 Input and Output Primitives
  • 8.3 Setting the File Position of a Descriptor
  • 8.4 Descriptors and Streams
  • 8.5 Dangers of Mixing Streams and Descriptors
    • 8.5.1 Linked Channels
    • 8.5.2 Independent Channels
    • 8.5.3 Cleaning Streams
  • 8.6 Waiting for Input or Output
  • 8.7 Control Operations on Files
  • 8.8 Duplicating Descriptors
  • 8.9 File Descriptor Flags
  • 8.10 File Status Flags
    • 8.10.1 File Access Modes
    • 8.10.2 Open-time Flags
    • 8.10.3 I/O Operating Modes
    • 8.10.4 Getting and Setting File Status Flags
  • 8.11 File Locks
  • 8.12 Interrupt-Driven Input
• 9 File System Interface
  • 9.1 Working Directory
  • 9.2 Accessing Directories
    • 9.2.1 Format of a Directory Entry
    • 9.2.2 Opening a Directory Stream
    • 9.2.3 Reading and Closing a Directory Stream
    • 9.2.4 Simple Program to List a Directory
    • 9.2.5 Random Access in a Directory Stream
    • 9.2.6 Scanning the Content of a Directory
    • 9.2.7 Simple Program to List a Directory, Mark II
  • 9.3 Hard Links
  • 9.4 Symbolic Links
  • 9.5 Deleting Files
  • 9.6 Renaming Files
  • 9.7 Creating Directories
  • 9.8 File Attributes
    • 9.8.1 What the File Attribute Values Mean
    • 9.8.2 Reading the Attributes of a File
    • 9.8.3 Testing the Type of a File
    • 9.8.4 File Owner
    • 9.8.5 The Mode Bits for Access Permission
    • 9.8.6 How Your Access to a File is Decided
    • 9.8.7 Assigning File Permissions
    • 9.8.8 Testing Permission to Access a File
    • 9.8.9 File Times
  • 9.9 Making Special Files
  • 9.10 Temporary Files
• 10 Pipes and FIFOs
  • 10.1 Creating a Pipe
  • 10.2 Pipe to a Subprocess
  • 10.3 FIFO Special Files
  • 10.4 Atomicity of Pipe I/O
• 11 Sockets
  • 11.1 Socket Concepts
  • 11.2 Communication Styles
  • 11.3 Socket Addresses
    • 11.3.1 Address Formats
    • 11.3.2 Setting the Address of a Socket
    • 11.3.3 Reading the Address of a Socket
  • 11.4 The File Namespace
    • 11.4.1 File Namespace Concepts
    • 11.4.2 Details of File Namespace
    • 11.4.3 Example of File-Namespace Sockets
  • 11.5 The Internet Namespace
    • 11.5.1 Internet Socket Address Format
    • 11.5.2 Host Addresses
      • 11.5.2.1 Internet Host Addresses
      • 11.5.2.2 Host Address Data Type
      • 11.5.2.3 Host Address Functions
      • 11.5.2.4 Host Names
    • 11.5.3 Internet Ports
    • 11.5.4 The Services Database
    • 11.5.5 Byte Order Conversion
    • 11.5.6 Protocols Database
    • 11.5.7 Internet Socket Example
  • 11.6 Other Namespaces
  • 11.7 Opening and Closing Sockets
    • 11.7.1 Creating a Socket
    • 11.7.2 Closing a Socket
    • 11.7.3 Socket Pairs
  • 11.8 Using Sockets with Connections
    • 11.8.1 Making a Connection
    • 11.8.2 Listening for Connections
    • 11.8.3 Accepting Connections
    • 11.8.4 Who is Connected to Me?
    • 11.8.5 Transferring Data
      • 11.8.5.1 Sending Data
      • 11.8.5.2 Receiving Data
      • 11.8.5.3 Socket Data Options
    • 11.8.6 Byte Stream Socket Example
    • 11.8.7 Byte Stream Connection Server Example
    • 11.8.8 Out-of-Band Data
  • 11.9 Datagram Socket Operations
    • 11.9.1 Sending Datagrams
    • 11.9.2 Receiving Datagrams
    • 11.9.3 Datagram Socket Example
    • 11.9.4 Example of Reading Datagrams
  • 11.10 The inetd Daemon
    • 11.10.1 inetd Servers
    • 11.10.2 Configuring inetd
  • 11.11 Socket Options
    • 11.11.1 Socket Option Functions
    • 11.11.2 Socket-Level Options
  • 11.12 Networks Database
• 12 Low-Level Terminal Interface
  • 12.1 Identifying Terminals
  • 12.2 I/O Queues
  • 12.3 Two Styles of Input: Canonical or Not
  • 12.4 Terminal Modes
    • 12.4.1 Terminal Mode Data Types
    • 12.4.2 Terminal Mode Functions
    • 12.4.3 Setting Terminal Modes Properly
    • 12.4.4 Input Modes
    • 12.4.5 Output Modes
    • 12.4.6 Control Modes
    • 12.4.7 Local Modes
    • 12.4.8 Line Speed
    • 12.4.9 Special Characters
      • 12.4.9.1 Characters for Input Editing
      • 12.4.9.2 Characters that Cause Signals
      • 12.4.9.3 Special Characters for Flow Control
      • 12.4.9.4 Other Special Characters
    • 12.4.10 Noncanonical Input
  • 12.5 Line Control Functions
  • 12.6 Noncanonical Mode Example
• 13 Mathematics
  • 13.1 Domain and Range Errors
  • 13.2 Trigonometric Functions
  • 13.3 Inverse Trigonometric Functions
  • 13.4 Exponentiation and Logarithms
  • 13.5 Hyperbolic Functions
  • 13.6 Pseudo-Random Numbers
    • 13.6.1 ISO C Random Number Functions
    • 13.6.2 BSD Random Number Functions
• 14 Low-Level Arithmetic Functions
  • 14.1 "Not a Number" Values
  • 14.2 Predicates on Floats
  • 14.3 Absolute Value
  • 14.4 Normalization Functions
  • 14.5 Rounding and Remainder Functions
  • 14.6 Integer Division
  • 14.7 Parsing of Numbers
    • 14.7.1 Parsing of Integers
    • 14.7.2 Parsing of Floats
• 15 Searching and Sorting
  • 15.1 Defining the Comparison Function
  • 15.2 Array Search Function
  • 15.3 Array Sort Function
  • 15.4 Searching and Sorting Example
• 16 Pattern Matching
  • 16.1 Wildcard Matching
  • 16.2 Globbing
    • 16.2.1 Calling glob
    • 16.2.2 Flags for Globbing
  • 16.3 Regular Expression Matching
    • 16.3.1 POSIX Regular Expression Compilation
    • 16.3.2 Flags for POSIX Regular Expressions
    • 16.3.3 Matching a Compiled POSIX Regular Expression
    • 16.3.4 Match Results with Subexpressions
    • 16.3.5 Complications in Subexpression Matching
    • 16.3.6 POSIX Regexp Matching Cleanup
  • 16.4 Shell-Style Word Expansion
    • 16.4.1 The Stages of Word Expansion
    • 16.4.2 Calling wordexp
    • 16.4.3 Flags for Word Expansion
    • 16.4.4 wordexp Example
• 17 Date and Time
  • 17.1 Processor Time
    • 17.1.1 Basic CPU Time Inquiry
    • 17.1.2 Detailed Elapsed CPU Time Inquiry
  • 17.2 Calendar Time
    • 17.2.1 Simple Calendar Time
    • 17.2.2 High-Resolution Calendar
    • 17.2.3 Broken-down Time
    • 17.2.4 Formatting Date and Time
    • 17.2.5 Specifying the Time Zone with TZ
    • 17.2.6 Functions and Variables for Time Zones
    • 17.2.7 Time Functions Example
  • 17.3 Setting an Alarm
  • 17.4 Sleeping
  • 17.5 Resource Usage
  • 17.6 Limiting Resource Usage
  • 17.7 Process Priority
• 18 Extended Characters
  • 18.1 Introduction to Extended Characters
  • 18.2 Locales and Extended Characters
  • 18.3 Multibyte Characters
  • 18.4 Wide Character Introduction
  • 18.5 Conversion of Extended Strings
  • 18.6 Multibyte Character Length
  • 18.7 Conversion of Extended Characters One by One
  • 18.8 Character-by-Character Conversion Example
  • 18.9 Multibyte Codes Using Shift Sequences
• 19 Locales and Internationalization
  • 19.1 What Effects a Locale Has
  • 19.2 Choosing a Locale
  • 19.3 Categories of Activities that Locales Affect
  • 19.4 How Programs Set the Locale
  • 19.5 Standard Locales
  • 19.6 Numeric Formatting
    • 19.6.1 Generic Numeric Formatting Parameters
    • 19.6.2 Printing the Currency Symbol
    • 19.6.3 Printing the Sign of an Amount of Money
• 20 Non-Local Exits
  • 20.1 Introduction to Non-Local Exits
  • 20.2 Details of Non-Local Exits
  • 20.3 Non-Local Exits and Signals
• 21 Signal Handling
  • 21.1 Basic Concepts of Signals
    • 21.1.1 Some Kinds of Signals
    • 21.1.2 Concepts of Signal Generation
    • 21.1.3 How Signals Are Delivered
  • 21.2 Standard Signals
    • 21.2.1 Program Error Signals
    • 21.2.2 Termination Signals
    • 21.2.3 Alarm Signals
    • 21.2.4 Asynchronous I/O Signals
    • 21.2.5 Job Control Signals
    • 21.2.6 Operation Error Signals
    • 21.2.7 Miscellaneous Signals
    • 21.2.8 Signal Messages
  • 21.3 Specifying Signal Actions
    • 21.3.1 Basic Signal Handling
    • 21.3.2 Advanced Signal Handling
    • 21.3.3 Interaction of signal and sigaction
    • 21.3.4 sigaction Function Example
    • 21.3.5 Flags for sigaction
    • 21.3.6 Initial Signal Actions
  • 21.4 Defining Signal Handlers
    • 21.4.1 Signal Handlers that Return
    • 21.4.2 Handlers That Terminate the Process
    • 21.4.3 Nonlocal Control Transfer in Handlers
    • 21.4.4 Signals Arriving While a Handler Runs
    • 21.4.5 Signals Close Together Merge into One
    • 21.4.6 Signal Handling and Nonreentrant Functions
    • 21.4.7 Atomic Data Access and Signal Handling
      • 21.4.7.1 Problems with Non-Atomic Access
      • 21.4.7.2 Atomic Types
      • 21.4.7.3 Atomic Usage Patterns
  • 21.5 Primitives Interrupted by Signals
  • 21.6 Generating Signals
    • 21.6.1 Signaling Yourself
    • 21.6.2 Signaling Another Process
    • 21.6.3 Permission for using kill
    • 21.6.4 Using kill for Communication
  • 21.7 Blocking Signals
    • 21.7.1 Why Blocking Signals is Useful
    • 21.7.2 Signal Sets
    • 21.7.3 Process Signal Mask
    • 21.7.4 Blocking to Test for Delivery of a Signal
    • 21.7.5 Blocking Signals for a Handler
    • 21.7.6 Checking for Pending Signals
    • 21.7.7 Remembering a Signal to Act On Later
  • 21.8 Waiting for a Signal
    • 21.8.1 Using pause
    • 21.8.2 Problems with pause
    • 21.8.3 Using sigsuspend
  • 21.9 Using a Separate Signal Stack
  • 21.10 BSD Signal Handling
    • 21.10.1 BSD Function to Establish a Handler
    • 21.10.2 BSD Functions for Blocking Signals
• 22 Process Startup and Termination
  • 22.1 Program Arguments
    • 22.1.1 Program Argument Syntax Conventions
    • 22.1.2 Parsing Program Options
    • 22.1.3 Example of Parsing Arguments with getopt
    • 22.1.4 Parsing Long Options
    • 22.1.5 Example of Parsing Long Options
    • 22.1.6 Parsing of Suboptions
    • 22.1.7 Parsing of Suboptions Example
  • 22.2 Environment Variables
    • 22.2.1 Environment Access
    • 22.2.2 Standard Environment Variables
  • 22.3 Program Termination
    • 22.3.1 Normal Termination
    • 22.3.2 Exit Status
    • 22.3.3 Cleanups on Exit
    • 22.3.4 Aborting a Program
    • 22.3.5 Termination Internals
• 23 Processes
  • 23.1 Running a Command
  • 23.2 Process Creation Concepts
  • 23.3 Process Identification
  • 23.4 Creating a Process
  • 23.5 Executing a File
  • 23.6 Process Completion
  • 23.7 Process Completion Status
  • 23.8 BSD Process Wait Functions
  • 23.9 Process Creation Example
• 24 Job Control
  • 24.1 Concepts of Job Control
  • 24.2 Job Control is Optional
  • 24.3 Controlling Terminal of a Process
  • 24.4 Access to the Controlling Terminal
  • 24.5 Orphaned Process Groups
  • 24.6 Implementing a Job Control Shell
    • 24.6.1 Data Structures for the Shell
    • 24.6.2 Initializing the Shell
    • 24.6.3 Launching Jobs
    • 24.6.4 Foreground and Background
    • 24.6.5 Stopped and Terminated Jobs
    • 24.6.6 Continuing Stopped Jobs
    • 24.6.7 The Missing Pieces
  • 24.7 Functions for Job Control
    • 24.7.1 Identifying the Controlling Terminal
    • 24.7.2 Process Group Functions
    • 24.7.3 Functions for Controlling Terminal Access
• 25 System Databases and Name Service Switch
  • 25.1 NSS Basics
  • 25.2 The NSS Configuration File
    • 25.2.1 Services in the NSS configuration File
    • 25.2.2 Actions in the NSS configuration
    • 25.2.3 Notes on the NSS Configuration File
  • 25.3 NSS Module Internals
    • 25.3.1 The Naming Scheme of the NSS Modules
    • 25.3.2 The Interface of the Function in NSS Modules
  • 25.4 Extending NSS
    • 25.4.1 Adding another Service to NSS
    • 25.4.2 Internals of the NSS Module Functions
• 26 Users and Groups
  • 26.1 User and Group IDs
  • 26.2 The Persona of a Process
  • 26.3 Why Change the Persona of a Process?
  • 26.4 How an Application Can Change Persona
  • 26.5 Reading the Persona of a Process
  • 26.6 Setting the User ID
  • 26.7 Setting the Group IDs
  • 26.8 Enabling and Disabling Setuid Access
  • 26.9 Setuid Program Example
  • 26.10 Tips for Writing Setuid Programs
  • 26.11 Identifying Who Logged In
  • 26.12 User Database
    • 26.12.1 The Data Structure that Describes a User
    • 26.12.2 Looking Up One User
    • 26.12.3 Scanning the List of All Users
    • 26.12.4 Writing a User Entry
  • 26.13 Group Database
    • 26.13.1 The Data Structure for a Group
    • 26.13.2 Looking Up One Group
    • 26.13.3 Scanning the List of All Groups
  • 26.14 Netgroup Database
    • 26.14.1 Netgroup Data
    • 26.14.2 Looking up one Netgroup
    • 26.14.3 Testing for Netgroup Membership
  • 26.15 User and Group Database Example
• 27 System Information
  • 27.1 Host Identification
  • 27.2 Hardware/Software Type Identification
• 28 System Configuration Parameters
  • 28.1 General Capacity Limits
  • 28.2 Overall System Options
  • 28.3 Which Version of POSIX is Supported
  • 28.4 Using sysconf
    • 28.4.1 Definition of sysconf
    • 28.4.2 Constants for sysconf Parameters
    • 28.4.3 Examples of sysconf
  • 28.5 Minimum Values for General Capacity Limits
  • 28.6 Limits on File System Capacity
  • 28.7 Optional Features in File Support
  • 28.8 Minimum Values for File System Limits
  • 28.9 Using pathconf
  • 28.10 Utility Program Capacity Limits
  • 28.11 Minimum Values for Utility Limits
  • 28.12 String-Valued Parameters
• A C Language Facilities in the Library
  • 28.13 Explicitly Checking Internal Consistency
  • 28.14 Variadic Functions
    • 28.14.1 Why Variadic Functions are Used
    • 28.14.2 How Variadic Functions are Defined and Used
      • 28.14.2.1 Syntax for Variable Arguments
      • 28.14.2.2 Receiving the Argument Values
      • 28.14.2.3 How Many Arguments Were Supplied
      • 28.14.2.4 Calling Variadic Functions
      • 28.14.2.5 Argument Access Macros
    • 28.14.3 Example of a Variadic Function
      • 28.14.3.1 Old-Style Variadic Functions
  • 28.15 Null Pointer Constant
  • 28.16 Important Data Types
  • 28.17 Data Type Measurements
    • 28.17.1 Computing the Width of an Integer Data Type
    • 28.17.2 Range of an Integer Type
    • 28.17.3 Floating Type Macros
      • 28.17.3.1 Floating Point Representation Concepts
      • 28.17.3.2 Floating Point Parameters
      • 28.17.3.3 IEEE Floating Point
    • 28.17.4 Structure Field Offset Measurement
• B Summary of Library Facilities
• C Library Maintenance
  • C.1 How to Install the GNU C Library
    • C.1.1 Recommended Tools to Install the GNU C Library
    • C.1.2 Supported Configurations
  • C.2 Reporting Bugs
  • C.3 Adding New Functions
  • C.4 Porting the GNU C Library
    • C.4.1 Layout of the `sysdeps' Directory Hierarchy
    • C.4.2 Porting the GNU C Library to Unix Systems
  • C.5 Contributors to the GNU C Library
• D 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 3 June 1997 using the texi2html translator version 1.51.