The GNU C Library: Application Fundamentals for GNU C Libraries Version 2.3.X
Total Page:16
File Type:pdf, Size:1020Kb
The GNU C Library: Application Fundamentals For GNU C Libraries version 2.3.x by Sandra Loosemore with Richard M. Stallman, Roland McGrath, Andrew Oram, and Ulrich Drepper This manual documents the GNU C Libraries version 2.3.x. ISBN 1-882114-22-1, First Printing, March 2004. Published by: GNU Press Website: www.gnupress.org a division of the General: [email protected] Free Software Foundation Orders: [email protected] 51 Franklin St, Fifth Floor Tel: 617-542-5942 Boston, MA 02110-1301 USA Fax: 617-542-2652 Copyright © 1999, 2000, 2001, 2002, 2003, 2004 Free Software Foundation Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2, or any later version published by the Free Software Foundation; with the Invariant Sections being “Free Software and Free Manuals”, the “GNU Free Documentation License”," and the “GNU Lesser General Public License”, with 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 Back Cover Text is: You are free to copy and modify this GNU Manual. Buying copies from GNU Press supports the FSF in developing GNU and promoting software freedom. Cover art by Etienne Suvasa. Cover design by Jonathan Richard. Printed in USA. i Short Contents 1 Introduction ............................................ 1 2 Error Reporting......................................... 17 3 Virtual Memory Allocation and Paging ...................... 39 4 Character Handling...................................... 79 5 String and Array Utilities ................................. 89 6 Character-Set Handling ................................. 133 7 Locales and Internationalization .......................... 181 8 Mathematics .......................................... 203 9 Arithmetic Functions ................................... 243 10 Date and Time ........................................ 277 11 Message Translation .................................... 315 12 Searching and Sorting .................................. 343 13 Pattern Matching ...................................... 355 14 The Basic Program/System Interface ....................... 379 15 Input/Output Overview.................................. 429 16 Debugging Support..................................... 435 17 Input/Output on Streams ................................ 439 A Summary of Library Facilities ............................ 521 B Contributors to the GNU C Library ........................ 587 C Free Software Needs Free Documentation................... 591 D GNU Lesser General Public License ....................... 593 E GNU Free Documentation License ........................ 603 Concept Index............................................. 611 Type Index ............................................... 617 Function and Macro Index ................................... 619 Variable and Constant Macro Index ............................ 629 Program and File Index ..................................... 635 ii The GNU C Library: Application Fundamentals iii Table of Contents 1 Introduction ......................................... 1 1.1 Getting Started ................................................. 1 1.2 Standards and Portability ....................................... 1 1.2.1 ISO C ................................................ 2 1.2.2 POSIX (The Portable Operating System Interface) ...... 2 1.2.3 Berkeley Unix ........................................ 3 1.2.4 SVID (The System V Interface Description) ............ 3 1.2.5 XPG (The X/Open Portability Guide) .................. 4 1.3 Using the Library............................................... 4 1.3.1 Header Files .......................................... 4 1.3.2 Macro Definitions of Functions ........................ 5 1.3.3 Reserved Names ...................................... 6 1.3.4 Feature-Test Macros .................................. 8 1.4 Road Map to the Manual ...................................... 12 2 Error Reporting .................................... 17 2.1 Checking for Errors ........................................... 17 2.2 Error Codes ................................................... 18 2.3 Error Messages ............................................... 32 3 Virtual Memory Allocation and Paging ............. 39 3.1 Process Memory Concepts..................................... 39 3.2 Allocating Storage for Program Data ........................... 41 3.2.1 Memory Allocation in C Programs ................... 41 3.2.1.1 Dynamic Memory Allocation............... 41 3.2.2 Unconstrained Allocation ............................ 42 3.2.2.1 Basic Memory Allocation .................. 42 3.2.2.2 Examples of malloc ...................... 43 3.2.2.3 Freeing Memory Allocated with malloc ... 44 3.2.2.4 Changing the Size of a Block ............... 45 3.2.2.5 Allocating Cleared Space................... 46 3.2.2.6 Efficiency Considerations for malloc...... 46 3.2.2.7 Allocating Aligned Memory Blocks ........ 47 3.2.2.8 malloc Tunable Parameters ............... 47 3.2.2.9 Heap Consistency Checking ................ 48 3.2.2.10 Memory Allocation Hooks ................ 50 3.2.2.11 Statistics for Memory Allocation with malloc....................................... 53 3.2.2.12 Summary of malloc-Related Functions .. 54 3.2.3 Allocation Debugging ............................... 55 3.2.3.1 How to Install the Tracing Functionality .... 56 iv The GNU C Library: Application Fundamentals 3.2.3.2 Example Program Excerpts................. 56 3.2.3.3 Some More or Less Clever Ideas............ 57 3.2.3.4 Interpreting the Traces ..................... 58 3.2.4 Obstacks ............................................ 59 3.2.4.1 Creating Obstacks ......................... 60 3.2.4.2 Preparing for Using Obstacks............... 60 3.2.4.3 Allocation in an Obstack ................... 61 3.2.4.4 Freeing Objects in an Obstack .............. 63 3.2.4.5 Obstack Functions and Macros ............. 63 3.2.4.6 Growing Objects........................... 64 3.2.4.7 Extra-Fast Growing Objects ................ 66 3.2.4.8 Status of an Obstack ....................... 67 3.2.4.9 Alignment of Data in Obstacks ............. 68 3.2.4.10 Obstack Chunks .......................... 69 3.2.4.11 Summary of Obstack Functions ........... 69 3.2.5 Automatic Storage with Variable Size ................ 71 3.2.5.1 alloca Example ......................... 72 3.2.5.2 Advantages of alloca .................... 72 3.2.5.3 Disadvantages of alloca ................. 73 3.2.5.4 GNU C Variable-Size Arrays................ 73 3.3 Resizing the Data Segment .................................... 74 3.4 Locking Pages ................................................ 74 3.4.1 Why Lock Pages? ................................... 75 3.4.2 Locked-Memory Details ............................. 75 3.4.3 Functions to Lock and Unlock Pages ................. 76 4 Character Handling ................................ 79 4.1 Classification of Characters .................................... 79 4.2 Case Conversion .............................................. 81 4.3 Character Class Determination for Wide Characters ............. 82 4.4 Notes on Using the Wide-Character Classes .................... 86 4.5 Mapping of Wide Characters................................... 87 v 5 String and Array Utilities ........................... 89 5.1 Representation of Strings ...................................... 89 5.2 String and Array Conventions.................................. 91 5.3 String Length ................................................. 91 5.4 Copying and Concatenation.................................... 93 5.5 String/Array Comparison ..................................... 105 5.6 Collation Functions .......................................... 109 5.7 Search Functions............................................. 114 5.7.1 Compatibility String Search Functions............... 119 5.8 Finding Tokens in a String.................................... 119 5.9 strfry..................................................... 124 5.10 Trivial Encryption .......................................... 124 5.11 Encode Binary Data......................................... 125 5.12 Argz and Envz Vectors ...................................... 127 5.12.1 Argz Functions.................................... 127 5.12.2 Envz Functions ................................... 130 6 Character-Set Handling ........................... 133 6.1 Introduction to Extended Characters .......................... 133 6.2 Overview About Character-Handling Functions................ 137 6.3 Restartable Multibyte Conversion Functions ................... 137 6.3.1 Selecting the Conversion and Its Properties .......... 138 6.3.2 Representing the State of the Conversion ............ 139 6.3.3 Converting Single Characters ....................... 140 6.3.4 Converting Multibyte- and Wide-Character Strings... 147 6.3.5 A Complete Multibyte Conversion Example ......... 150 6.4 Nonreentrant Conversion Function ............................ 152 6.4.1 Nonreentrant Conversion of Single Characters ....... 153 6.4.2 Nonreentrant Conversion of Strings ................. 154 6.4.3 States in Nonreentrant Functions .................... 155 6.5 Generic Charset Conversion .................................. 157 6.5.1 Generic Character-Set Conversion Interface.......... 157 6.5.2 A Complete iconv Example ....................... 161 6.5.3 Some Details About Other iconv Implementations .....................................................