GNU C Library Application Fundamentals docx

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: press@gnu.org Free Software Foundation Orders: sales@gnu.org 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 6.5.4 The iconv Implementation in the GNU C Library . . . 165 6.5.4.1 Format of ‘gconv-modules’ Files . . . . . . 166 6.5.4.2 Finding the Conversion Path in iconv . . . . 167 6.5.4.3 iconv Module Data Structures . . . . . . . . . . . 168 6.5.4.4 iconv Module Interfaces. . . . . . . . . . . . . . . . . 171 vi The GNU C Library: Application Fundamentals 7 Locales and Internationalization. . . . . . . . . . . . . . . . . . . 181 7.1 What Effects a Locale Has . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181 7.2 Choosing a Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182 7.3 Categories of Activities That Locales Affect . . . . . . . . . . . . . . . . . . . 182 7.4 How Programs Set the Locale. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 7.5 Standard Locales. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185 7.6 Accessing Locale Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186 7.6.1 localeconv: “It is portable, but . . . ” . . . . . . . . . . . . . 186 7.6.1.1 Generic Numeric Formatting Parameters . . . 187 7.6.1.2 Printing the Currency Symbol . . . . . . . . . . . . . 188 7.6.1.3 Printing the Sign of a Monetary Amount . . . 190 7.6.2 Pinpoint Access to Locale Data . . . . . . . . . . . . . . . . . . . . . 191 7.7 A Dedicated Function to Format Numbers. . . . . . . . . . . . . . . . . . . . . 197 7.8 Yes-or-No Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200 8 Mathematics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 8.1 Predefined Mathematical Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . 203 8.2 Trigonometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204 8.3 Inverse Trigonometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 8.4 Exponentiation and Logarithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207 8.5 Hyperbolic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212 8.6 Special Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214 8.7 Known Maximum Errors in Math Functions . . . . . . . . . . . . . . . . . . . 216 8.8 Pseudorandom Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234 8.8.1 ISO C Random-Number Functions . . . . . . . . . . . . . . . . . . 235 8.8.2 BSD Random-Number Functions . . . . . . . . . . . . . . . . . . . 235 8.8.3 SVID Random-Number Functions . . . . . . . . . . . . . . . . . . 237 8.9 Is Fast Code or Small Code Preferred? . . . . . . . . . . . . . . . . . . . . . . . . 242 9 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 9.1 Integers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243 9.2 Integer Division . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 244 9.3 Floating-Point Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246 9.4 Floating-Point Number Classification Functions . . . . . . . . . . . . . . . 247 9.5 Errors in Floating-Point Calculations . . . . . . . . . . . . . . . . . . . . . . . . . . 249 9.5.1 FP Exceptions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 249 9.5.2 Infinity and NaN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 250 9.5.3 Examining the FPU Status Word . . . . . . . . . . . . . . . . . . . . 252 9.5.4 Error Reporting by Mathematical Functions . . . . . . . . . 253 9.6 Rounding Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254 9.7 Floating-Point Control Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256 9.8 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 9.8.1 Absolute Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258 9.8.2 Normalization Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . 259 9.8.3 Rounding Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260 vii 9.8.4 Remainder Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262 9.8.5 Setting and Modifying Single Bits of FP Values . . . . . . 263 9.8.6 Floating-Point Comparison Functions . . . . . . . . . . . . . . . 264 9.8.7 Miscellaneous FP Arithmetic Functions . . . . . . . . . . . . . 265 9.9 Complex Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 9.10 Projections, Conjugates and Decomposing of Complex Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 267 9.11 Parsing of Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 9.11.1 Parsing of Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268 9.11.2 Parsing of Floats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273 9.12 Old-fashioned System V Number-to-String Functions. . . . . . . . . 275 10 Date and Time. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 10.1 Time Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 10.2 Elapsed Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277 10.3 Processor and CPU Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279 10.3.1 CPU Time Inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280 10.3.2 Processor Time Inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281 10.4 Calendar Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 10.4.1 Simple Calendar Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282 10.4.2 High-Resolution Calendar . . . . . . . . . . . . . . . . . . . . . . . . . 283 10.4.3 Broken-Down Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 10.4.4 High-Accuracy Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288 10.4.5 Formatting Calendar Time . . . . . . . . . . . . . . . . . . . . . . . . . 291 10.4.6 Convert Textual Time and Date Information Back . . . 297 10.4.6.1 Interpret String According to Given Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297 10.4.6.2 A More User-Friendly Way to Parse Times and Dates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303 10.4.7 Specifying the Time Zone with TZ . . . . . . . . . . . . . . . . . 306 10.4.8 Functions and Variables for Time Zones . . . . . . . . . . . . 308 10.4.9 Time Functions Example . . . . . . . . . . . . . . . . . . . . . . . . . . 309 10.5 Setting an Alarm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310 10.6 Sleeping. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312 viii The GNU C Library: Application Fundamentals 11 Message Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 11.1 X/Open Message Catalog Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 315 11.1.1 The catgets Function Family . . . . . . . . . . . . . . . . . . . 316 11.1.2 Format of the Message Catalog Files . . . . . . . . . . . . . . . 319 11.1.3 Generate Message Catalogs Files . . . . . . . . . . . . . . . . . . 321 11.1.4 How to Use the catgets Interface. . . . . . . . . . . . . . . . 322 11.1.4.1 Not Using Symbolic Names. . . . . . . . . . . . . . 322 11.1.4.2 Using Symbolic Names . . . . . . . . . . . . . . . . . . 323 11.1.4.3 Using Symbolic Version Numbers . . . . . . . . 324 11.2 The Uniforum Approach to Message Translation . . . . . . . . . . . . . 325 11.2.1 The gettext Family of Functions . . . . . . . . . . . . . . . . 326 11.2.1.1 What Has to Be Done to Translate a Message? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326 11.2.1.2 How to Determine Which Catalog to Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328 11.2.1.3 Additional Functions for More Complicated Situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330 11.2.1.4 How to Specify the Output Character Set That gettext Uses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335 11.2.1.5 How to Use gettext in GUI Programs . . 336 11.2.1.6 User Influence on gettext . . . . . . . . . . . . . 338 11.2.2 Programs to Handle Message Catalogs for gettext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341 12 Searching and Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 12.1 Defining the Comparison Function. . . . . . . . . . . . . . . . . . . . . . . . . . . 343 12.2 Array Search Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343 12.3 Array Sort Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344 12.4 Searching and Sorting Example. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345 12.5 The hsearch Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348 12.6 The tsearch Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 351 13 Pattern Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 13.1 Wildcard Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355 13.2 Globbing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 13.2.1 Calling glob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357 13.2.2 Flags for Globbing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361 13.2.3 More Flags for Globbing . . . . . . . . . . . . . . . . . . . . . . . . . . 362 13.3 Regular Expression Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364 13.3.1 POSIX Regular Expression Compilation . . . . . . . . . . . . 365 13.3.2 Flags for POSIX Regular Expressions. . . . . . . . . . . . . . . 367 13.3.3 Matching a Compiled POSIX Regular Expression . . . 367 13.3.4 Match Results with Subexpressions . . . . . . . . . . . . . . . . 368 13.3.5 Complications in Subexpression Matching. . . . . . . . . . 369 13.3.6 POSIX Regexp Matching Clean-Up . . . . . . . . . . . . . . . . . 369 [...]... to do with this library s getline They would not be compilable if all features were enabled indiscriminately 14 See Richard M Stallman and the GCC Developer Community, “Invoking GCC” in Using GCC: The GNU Compiler Collection Reference Manual (Boston, MA: GNU Press, October 2003), http:// gcc .gnu. org/ onlinedocs/ gcc-3.3.2/ gcc/, for more information about GCC options Chapter 1: Introduction 9 This should... header files and ‘#include’ directives, see Richard M Stallman and the GCC Developer Community, “Header Files” in The GNU C Preprocessor Manual (2003), http:// gcc .gnu. org/ onlinedocs/ gcc-3.3.2/ cpp/ 6 The GNU C Library: Application Fundamentals Taking the address of a library function works even if it is also defined as a macro This is because, in this context, the name of the function isn’t followed... implements all of the functions specified in ISO/IEC 99451:1996, the POSIX System Application Program Interface, commonly referred to as POSIX 1 The primary extensions to the ISO C facilities specified by this standard Chapter 1: Introduction 3 include file-system interface primitives1 , device-speci c terminal control functions2 and process control functions.3 Some facilities from ISO/IEC 9945-2:1993, the... been specified to compile as thread safe 12 The GNU C Library: Application Fundamentals We recommend you use _GNU_ SOURCE in new programs If you don’t specify the ‘-ansi’ option to GCC and do not define any of these macros explicitly, the effect is the same as defining _POSIX _C_ SOURCE to 2 and _POSIX_SOURCE, _SVID_SOURCE and _BSD_SOURCE to 1 When you define a feature-test macro to request a larger class... arrays, including operations such as copying and comparison • “Character-Set Handling” contains information about manipulating characters and strings using character sets larger than will fit in the usual char data type • “Locales and Internationalization” describes how selecting a particular country or language affects the behavior of the library For example, the locale affects collation sequences for... same machine • “Sockets” describes a more complicated interprocess-communication mechanism that allows processes running on different machines to communicate 14 • • • • • • • • • • • • • • The GNU C Library: Application Fundamentals over a network This chapter also contains information about Internet hostaddressing and how to use the system network databases “Low-Level Terminal Interface” describes... not know in advance how much memory your program needs, you can allocate it dynamically instead, and manipulate it via pointers • “Character Handling” contains information about character-classification functions (such as isspace) and functions for performing case conversion • “String and Array Utilities” has descriptions of functions for manipulating strings (null-terminated character arrays) and general... The GNU C Library: Application Fundamentals SVID SOURCE Macro If you define this macro, functionality derived from SVID is included as well as the ISO C, POSIX.1, POSIX.2 and X/Open material XOPEN SOURCE XOPEN SOURCE EXTENDED Macro Macro If you define this macro, functionality described in the X/Open Portability Guide15 is included This is a superset of the POSIX.1 and POSIX.2 functionality and in fact... new directories This chapter also contains information about how you can access the attributes of a file, such as its owner and file-protection modes • “Pipes and FIFOs” contains information about simple interprocesscommunication mechanisms Pipes allow communication between two related processes (such as between a parent and child), while FIFOs allow communication between processes sharing a common file-system... that is syntactically necessary to recognize a macro call You might occasionally want to avoid using the macro definition of a function— perhaps to make your program easier to debug There are two ways you can do this: 1 You can avoid a macro definition in a speci c use by enclosing the name of the function in parentheses This works because the name of the function does not appear in a syntactic context where . the ISO C facilities specified by this standard Chapter 1: Introduction 3 include file-system interface primitives 1 , device-speci c terminal control func- tions 2 and process control functions. 3 Some. . . . . . . . 635 The GNU C Library: Application Fundamentals Chapter 1: Introduction 1 1 Introduction The C language provides no built-in facilities for performing such common op- erations as. 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