Transcription
The GNU C Library Reference Manual
The GNU C LibraryReference ManualSandra LoosemorewithRichard M. Stallman, Roland McGrath, Andrew Oram, and Ulrich Drepperfor version 2.32
This is The GNU C Library Reference Manual, for version 2.32.Copyright c 1993–2020 Free Software Foundation, Inc.Permission is granted to copy, distribute and/or modify this document under the terms ofthe GNU Free Documentation License, Version 1.3 or any later version published by theFree Software Foundation; with the Invariant Sections being “Free Software Needs FreeDocumentation” 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 isincluded in the section entitled "GNU Free Documentation License".(a) The FSF’s Back-Cover Text is: “You have the freedom to copy and modify this GNUmanual. Buying copies from the FSF supports it in developing GNU and promoting softwarefreedom.”
iShort Contents1Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233Virtual Memory Allocation And Paging . . . . . . . . . . . . . . . . . . 4245Character Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87String and Array Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 976Character Set Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1407Locales and Internationalization . . . . . . . . . . . . . . . . . . . . . . . . 18389Message Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203Searching and Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22810 Pattern Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23911 Input/Output Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26112 Input/Output on Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26613 Low-Level Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34214 File System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40215 Pipes and FIFOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45016 Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45517 Low-Level Terminal Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 50318 Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53119 Mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53920 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60121 Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64622 Resource Usage And Limitation . . . . . . . . . . . . . . . . . . . . . . . . 68423 Non-Local Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70624 Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71525 The Basic Program/System Interface . . . . . . . . . . . . . . . . . . . . 76026 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80427 Inter-Process Communication . . . . . . . . . . . . . . . . . . . . . . . . . . 81628 Job Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81829 System Databases and Name Service Switch . . . . . . . . . . . . . . 83630 Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84631 System Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87632 System Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . 89133 Cryptographic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 913
ii34 Debugging support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91935 Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92236 Internal probes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93537 Tunables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 941ABC Language Facilities in the Library . . . . . . . . . . . . . . . . . . . . 948Summary of Library Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . 964CInstalling the GNU C Library . . . . . . . . . . . . . . . . . . . . . . . . . 1087DLibrary Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1098EFPlatform-specific facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107Contributors to the GNU C Library . . . . . . . . . . . . . . . . . . . . 1110GFree Software Needs Free Documentation . . . . . . . . . . . . . . . 1116HGNU Lesser General Public License . . . . . . . . . . . . . . . . . . . . 1118IGNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . 1127Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1135Type Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1148Function and Macro Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1151Variable and Constant Macro Index . . . . . . . . . . . . . . . . . . . . . . . 1167Program and File Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1180
iiiTable of Contents1Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.11.2Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1Standards and Portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2.1 ISO C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2.2 POSIX (The Portable Operating System Interface) . . . . . . . . . 21.2.2.1 POSIX Safety Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2.2.2 Unsafe Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2.2.3 Conditionally Safe Features . . . . . . . . . . . . . . . . . . . . . . . . . . . 51.2.2.4 Other Safety Remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.2.3 Berkeley Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.2.4 SVID (The System V Interface Description) . . . . . . . . . . . . . . . 111.2.5 XPG (The X/Open Portability Guide) . . . . . . . . . . . . . . . . . . . . 121.3 Using the Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.3.1 Header Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121.3.2 Macro Definitions of Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131.3.3 Reserved Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141.3.4 Feature Test Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151.4 Roadmap to the Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 192Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.12.22.33Checking for Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36Virtual Memory Allocation And Paging . . . . . 423.13.2Process Memory Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42Allocating Storage For Program Data . . . . . . . . . . . . . . . . . . . . . . . . . . 433.2.1 Memory Allocation in C Programs . . . . . . . . . . . . . . . . . . . . . . . . 443.2.1.1 Dynamic Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . 443.2.2 The GNU Allocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.2.3 Unconstrained Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.2.3.1 Basic Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.2.3.2 Examples of malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 463.2.3.3 Freeing Memory Allocated with malloc . . . . . . . . . . . . . . 473.2.3.4 Changing the Size of a Block . . . . . . . . . . . . . . . . . . . . . . . . . 483.2.3.5 Allocating Cleared Space. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493.2.3.6 Allocating Aligned Memory Blocks . . . . . . . . . . . . . . . . . . . 493.2.3.7 Malloc Tunable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 513.2.3.8 Heap Consistency Checking . . . . . . . . . . . . . . . . . . . . . . . . . . 523.2.3.9 Memory Allocation Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . 543.2.3.10 Statistics for Memory Allocation with malloc . . . . . . . 563.2.3.11 Summary of malloc-Related Functions . . . . . . . . . . . . . . 57
iv3.2.4 Allocation Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583.2.4.1 How to install the tracing functionality . . . . . . . . . . . . . . . 593.2.4.2 Example program excerpts . . . . . . . . . . . . . . . . . . . . . . . . . . . 593.2.4.3 Some more or less clever ideas . . . . . . . . . . . . . . . . . . . . . . . 603.2.4.4 Interpreting the traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 613.2.5 Replacing malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623.2.6 Obstacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633.2.6.1 Creating Obstacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633.2.6.2 Preparing for Using Obstacks . . . . . . . . . . . . . . . . . . . . . . . . 643.2.6.3 Allocation in an Obstack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653.2.6.4 Freeing Objects in an Obstack . . . . . . . . . . . . . . . . . . . . . . . 663.2.6.5 Obstack Functions and Macros . . . . . . . . . . . . . . . . . . . . . . . 663.2.6.6 Growing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673.2.6.7 Extra Fast Growing Objects . . . . . . . . . . . . . . . . . . . . . . . . . 693.2.6.8 Status of an Obstack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713.2.6.9 Alignment of Data in Obstacks . . . . . . . . . . . . . . . . . . . . . . . 723.2.6.10 Obstack Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723.2.6.11 Summary of Obstack Functions . . . . . . . . . . . . . . . . . . . . . 733.2.7 Automatic Storage with Variable Size . . . . . . . . . . . . . . . . . . . . . 743.2.7.1 alloca Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753.2.7.2 Advantages of alloca. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753.2.7.3 Disadvantages of alloca . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763.2.7.4 GNU C Variable-Size Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 763.3 Resizing the Data Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773.4 Memory Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773.4.1 Memory Protection Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793.5 Locking Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823.5.1 Why Lock Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 823.5.2 Locked Memory Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833.5.3 Functions To Lock And Unlock Pages . . . . . . . . . . . . . . . . . . . . . 834Character Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874.14.24.34.44.55Classification of Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87Case Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89Character class determination for wide characters . . . . . . . . . . . . . . 90Notes on using the wide character classes . . . . . . . . . . . . . . . . . . . . . . 94Mapping of wide characters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95String and Array Utilities . . . . . . . . . . . . . . . . . . . . . 975.15.25.35.45.55.65.75.8Representation of Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97String and Array Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98String Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99Copying Strings and Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101Concatenating Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106Truncating Strings while Copying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109String/Array Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113Collation Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
v5.9Search Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215.9.1 Compatibility String Search Functions . . . . . . . . . . . . . . . . . . . 1265.10 Finding Tokens in a String
The GNU C Library Reference Manual Sandra Loosemore with Richard M. Stallman, Roland McGrath, Andrew Oram, and Ulrich Drepper for version 2.32
