The GNU C Library Reference Manual

The GNU C Library

Reference Manual

Sandra Loosemorewith

Richard M. Stallman, Roland McGrath, Andrew Oram, and Ulrich Drepper

for version 2.27

This file documents the GNU C Library.

This is The GNU C Library Reference Manual, for version 2.27.

Copyright c 19932018 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 beingA 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 FSFs 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.

i

Short Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

3 Virtual Memory Allocation And Paging . . . . . . . . . . . . . . . . . . 414 Character Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 865 String and Array Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 966 Character Set Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1397 Locales and Internationalization . . . . . . . . . . . . . . . . . . . . . . . . 181

8 Message Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2019 Searching and Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226

10 Pattern Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23611 Input/Output Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

12 Input/Output on Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26313 Low-Level Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33914 File System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

15 Pipes and FIFOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44716 Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45217 Low-Level Terminal Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 50018 Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528

19 Mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536

20 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59021 Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634

22 Resource Usage And Limitation . . . . . . . . . . . . . . . . . . . . . . . . 67023 Non-Local Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692

24 Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70125 The Basic Program/System Interface . . . . . . . . . . . . . . . . . . . . 74526 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78927 Inter-Process Communication . . . . . . . . . . . . . . . . . . . . . . . . . . 80028 Job Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80229 System Databases and Name Service Switch . . . . . . . . . . . . . . 82130 Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 831

31 System Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86132 System Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . . 87833 DES Encryption and Password Handling . . . . . . . . . . . . . . . . . 900

ii

34 Debugging support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90935 POSIX Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91236 Internal probes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91437 Tunables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 921A C Language Facilities in the Library . . . . . . . . . . . . . . . . . . . . 927B Summary of Library Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . 943

C Installing the GNU C Library . . . . . . . . . . . . . . . . . . . . . . . . . 1062D Library Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1072E Platform-specific facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1079F Contributors to the GNU C Library . . . . . . . . . . . . . . . . . . . . 1082G Free Software Needs Free Documentation . . . . . . . . . . . . . . . 1088

H GNU Lesser General Public License . . . . . . . . . . . . . . . . . . . . 1090I GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . 1099Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1107Type Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1119

Function and Macro Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1122Variable and Constant Macro Index . . . . . . . . . . . . . . . . . . . . . . . 1137Program and File Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1149

iii

Table of Contents

1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2 Standards and Portability . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.2.1 ISO C . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.2.2 POSIX (The Portable Operating System Interface) . . . . . . . . . 2

1.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

1.2.3 Berkeley Unix . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111.2.4 SVID (The System V Interface Description) . . . . . . . . . . . . . . . 111.2.5 XPG (The X/Open Portability Guide) . . . . . . . . . . . . . . . . . . . . 12

1.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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.4 Roadmap to the Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

2 Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.1 Checking for Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222.2 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232.3 Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

3 Virtual Memory Allocation And Paging . . . . . 413.1 Process Memory Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.2 Allocating Storage For Program Data . . . . . . . . . . . . . . . . . . . . . . . . . . 42

3.2.1 Memory Allocation in C Programs . . . . . . . . . . . . . . . . . . . . . . . . 433.2.1.1 Dynamic Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . 43

3.2.2 The GNU Allocator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443.2.3 Unconstrained Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

3.2.3.1 Basic Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443.2.3.2 Examples of malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.2.3.3 Freeing Memory Allocated with malloc . . . . . . . . . . . . . . 463.2.3.4 Changing the Size of a Block . . . . . . . . . . . . . . . . . . . . . . . . . 473.2.3.5 Allocating Cleared Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 483.2.3.6 Allocating Aligned Memory Blocks . . . . . . . . . . . . . . . . . . . 483.2.3.7 Malloc Tunable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 503.2.3.8 Heap Consistency Checking . . . . . . . . . . . . . . . . . . . . . . . . . . 513.2.3.9 Memory Allocation Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . 533.2.3.10 Statistics for Memory Allocation with malloc . . . . . . . 553.2.3.11 Summary of malloc-Related Functions . . . . . . . . . . . . . . 56

iv

3.2.4 Allocation Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573.2.4.1 How to install the tracing functionality . . . . . . . . . . . . . . . 583.2.4.2 Example program excerpts . . . .