The GNU C Library Reference Manual
The GNU C Library Reference manual Sandra loosemore with Richard m. stallman, Roland McGrath, Andrew Oram, and Ulrich Drepper for version 2.17 This file documents the Gnu C Library This is The GN C Library Reference Manual, for version 2.17 Copyright 1993-2012 Free Software Foundation, Inc Permission is granted to copy, distribute and /or modify this document under the terms of the gnu Frcc Documentation License, Version 1. 3 or any latcr version published by the Free Software Foundation; with the Invariant Sections being " Free Software Needs free Documentation"and"GNU Lesser General Public License, 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 ll (a) The FSF's Back-Cover Text is: You have the freedom to copy and modify this GNU manual. Buying copies from the FSF supports it in developing gnU and promoting software freedon.” Short contents 1 Introduction 2 Error Reporting 3 Virtual Memory Allocation And Paging......... 30 4 Character handling 65 5 String and array utilities 73 6 Character Set Handling 7 Locales and internationalization 看·· 150 8 Message translation ,,,168 9 Searching and Sortin 192 10 Pattern Matching 202 11 Input/Output Ove 222 12 Input/Output on Streams 227 13 LOw-Level Input/Output 296 14 File System Interfac 343 15 Pipes and FIFOs 384 16 Sockets 89 17 Low-Level Terminal interface 434 slog ..,,,.,,,,,460 1 9 Mathematics .467 20 Arithmetic functions 510 21 Date and time 541 22 Resource Usage And Limitation.............574 23 Non-Local exits 594 24 Signal Handling 603 25 The Basic Program/ System Interface 647 26 Processes ...690 27 Job Control ...701 28 Systerm Databases and Name service switch 720 29 Users and groups 729 30 System management ....756 31 System Configuration parameters ..772 32 DES Encryption and Password handling e··申非 792 33 Debugging support 799 a C Language Facilities in the Library b Summary of Library facilities 816 C Installing the GNU C Library 919 d Library maintenance 926 E Platform-specific facilities 933 F Contributors to the gnu C library 934 G Free Software Needs free documentation .938 h GnU Lesser general public license 940 I GNU Free Documentation license 949 Concept Index 957 Type Index ....967 Function and macro index 969 Variable and constant macro Index ..981 Program and File Index 991 Table of Contents 1 Introduction 1.1 Getting St 1.2St ds and portability 1.2.11SOC..... 1.2.2 POSiX( The Portable Operating System Interface 1.2.3 Berkeley Unix 1.2.4 SVID(The System V Interface Description) 1.2.5 XPG(The X/Open Portability Guide 1.3 Using the Library · 3333 1.3. 1 Header Files 1.3.2 Macro definitions of functions 1.3.3 Reserved names ··, 0 1.3.4 Fcaturc Test macros 7 1.4 Roadmap to the manual 2 Error Reporting ········ 13 2.1 Checking for Errors 2.2 Error Codes 1 4 2.3 Error messa 24 3 Virtual Memory Allocation And Paging 30 3.1 Proccss Memory Concepts ..30 3.2 Allocating Storage For Program Data 31 3.2.1 Memory Allocation in C Programs 鲁鲁 32 3.2.1.1 Dynamic Memory Allocation 32 3.2.2 Unconstrained Allocation ,,33 3.2.2.1 Basic Memory Allocation .33 3.2.2.2 Examples of malloc ∴..33 3.2.2.3 Freeing memory Allocated with malloc 34 3.2. 2. Changing the Size of a Block ∴,35 3.2.2.5 Allocating Cleared space 36 3.2.2.6 Efficiency Considerations for malloc .36 3.2.2.7 Allocating Aligned Memory blocks 36 3.2.2. 8 Malloc Tunable paraneters ∴.37 3.2.2.9 Heap Consistency Checking 38 3.2.2.10 Memory Allocation Hooks 40 3.2. 2.11 Statistics for Memory Allocation with malloc.... 12 3.2.2. 12 Summary of malloc-Related Functions .43 3.2.3 Allocation Debugging 14 3.2.3.1 How to install the tracing functionality 44 3.2.3.2 Example program excerpts 45 3.2.3.3 Some more or less clever ideas 45 3.2.3.4 Interpreting the traces 46 3.2.4 Obstack 48 3.2.4.1 Creating Obstacks 48 3.2.4.2 Preparing for Using Obstacks 48 3.2.4.3 Allocation in an Obstack 49 3.2.4.4上 reeing Objects in an Obstack.……,,…,50 3.2.4.5 Obstack Functions and macros...........51 3.2.4.6 Growing Objects.……,,…,,…,51 3.2.4.7 Extra Fast growing Objects 3.2.4.8 Status of an Obstack 54 3.2.4.9 Alignment of Data in Obstacks 影,:;·,;, 55 3.2.4.10 Obstack Chunks 3. 4.11 Summary of obstack Functions 56 3.2.5 Automatic Storagc with Variable Sizc........... 58 3.2.5.1 alloca fxample 58 3.2.5.2 Advantagcs of alloca 58 3.2.5.3 Disadvantages of alloca ...59 3.2.5.4 GNU C Variable-Size arrays ∴...59 3.3 Resizing the Data Segment 60 4 Locking pages 60 3.4.1 Why Lock Pa 61 3.4.2 Locked Memory details 61 3.4.3 Functions To Lock And Unlock Pages 62 4 Character Handling 65 4.1 Classification of characters 4.2 Casc Convcrsion 67 4.3 Character class determination for wide characters ..67 4. Notes on using the widc charactor classes 4.5 Mapping of wide characters. 71 5 String and array utilities 73 5. 1 Representation of Strings 73 5.2 String and Array Conventions 5.3 String Lengthl 75 5.4 Copying and Concatenation 77 5 String / Array Comparison ..86 5.6 Collation functions 90 5.7 Search functions 94 5.7.1 Compatibility String Scarch Functions 鲁鲁垂 98 5.8 Finding Tokens in a string 98 5.9 sorry.....102 5.10 Trivial Encryption 102 5.11 Encode Binary Data ∴,103 5.12 Argz and Envz Vectors 105 5.12.1 Argz Functions 105 5.12.2 Envz Functions 107 6 Character Set handling 109 6.1 Introduction to extended characters ............ 109 6.2 Overview about Character Handling Functions 113 6. 3 Restartable Multibyte Conversion Functions.........113 6.3.1 Selecting the conversion and its properties ..113 6.3.2 Representing the state of the conversion 114 6.3.3 Converting Single Characters ..115 6.3.4 Converting Multibyte and Wide character strings 121 6.3.5 A Complctc Multibyte Conversion Examplc 124 6.4 Non-reentrant Conversion Function .125 6.4.1 Non-reentrant Conversion of Single Characters...... 126 6.4.2 Non-reentrant Conversion of strings 127 6.4.3 States in Non-reentrant Functions ∴..128 6.5 Generic Charset Conversion 129 6.5.1 Generic Character Set Conversion Interface....... 130 6.5.2 A complete iconv example 133 6.5.4 The iconv Implementation in the GNU C Library..'.. 135 6.5. 3 Some Details about other iconv Implementations .136 6.5.4.1 Format of gconv-modules files........... 137 6.5.4. 2 Finding the conversion path in iconv ...138 6.5.4.3 iconv module data structures 139 6.5. 4.4 iconv module interfaces 142 7 Locales and internationalization 150 7. 1 What Effects a Locale has 150 7.2 Choosing a Locale............ 着·· ∴.,151 7. 3 Categories of Activities that Locales Affect 151 7.4 How Programs Set the Locale ∴.152 7.5 Standard locales 154 7.6 Accessing Locale Information 154 7.6.1 localeconv: It is portable but 155 7.6.1.1 Generic Numeric Formatting Parameters...... 155 7.6.1.2 Printing the Currency Symbol 156 7.6.1.3 Printing the Sign of a Monetary Amount...... 157 7.6.2 Pinpoint Access to Locale Data 158 7.7 A dedicated funciion to fornal numbers ∴.,164 7.8 Yes-or-No Questions 167 8 Message Translation 168 8.1 X/Open Message Catalog Handling 168 8.1.1 The catgets function family ∴..168 8.1.2 Format of the message catalog files 171 8.1.3 Generate Message Catalogs files 173 8.1.4 How to use the catgets interface 174 8.1.4.1 Not using symbolic names 174 8.1.4.2 USing symbolic names 175 8. 1.4.3 Ilow does to this allow to develop 176 8.2 The Uniforum approach to Message Translation ....... 177 8.2. 1 The gettext family of functions ,,,177 8.2.1.1 What has to be done to translate a message 177 8.2.1. 2 How to determine which catalog to be used..... 179 8.2.1.3 Additional functions for more complicated situations 181 8.2.1. How to specify the output character set gettext uses 186 8.2. 1.5 How lo use gettext in Gui programs 186 8.216 User influence on gettext∴………188 8.2.2 Programs to handle message catalogs for gettext 191 9 Searching and Sorting 192 9.1 Defining the Comparison Function..............192 9.2 Array Search Function 192 9.3 Array Sort Function 193 9. 4 Searching and Sorting Example .....194 9.5 The hsearch func 196 9. 6 The tsearch function 199 10 Pattern Matching 202 0.1 Wildcard Matching 202 10.2 Globbing ····· 203 10.2.1 Calling glob 203 10.2.2 Flags for Gobbi 207 10.2.3 More Flags for Globbing ..208 10.3 Regular Expression Matching 10.3.1 POSiX Regular Expression Compilation ..210 10.3.2 Flags for POSiX Regular Expressions 212 10.3.3 Matching a Compiled POSIX Regular Expression 2 10.3.4 Match Results with Subexpressions 213 10.3.5 Complications in Subexpression Matching....... 214 10.3.6 POSIX Regexp Matching Cleanup ..214 10.4 Shell-Style Word Expansion 10.4.1 The Stages of Word Expansion ..215 10.4.2 Calling wordexp 16 10.4.3 Flags for Word Expansion 217 10.4.4 wordexp Example 218 10.4.5 Details of Tilde Expansion 219 10.4.6 Details of Variable Substitution 219