The GNU C Library Reference Manual

The GNU C Library Reference ManualSandra Loosemore with Richard M. Stallman, Roland McGrath, Andrew Oram, and Ulrich Drepper

Edition 0.10 last updated 2001-07-06 for version 2.2.x

Copyright c 1993, 1994, 1995, 1996, 1997, 1998, 2001, 2002 Free Software Foundation, Inc.

Published by the Free Software Foundation 59 Temple Place Suite 330, Boston, MA 02111-1307 USA ISBN 1-882114-55-8 Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later 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) (see below), and with the Back-Cover Texts being (b) (see below). A copy of the license is included in the section entitled "GNU Free Documentation License". (a) The FSFs Front-Cover Text is: A GNU Manual (b) The FSFs Back-Cover Text is: You have freedom to copy and modify this GNU Manual, like GNU software. Copies published by the Free Software Foundation raise funds for GNU development. Cover art for the Free Software Foundations printed edition by Etienne Suvasa.

i

Short Contents1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 A B Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Virtual Memory Allocation And Paging . . . . . . . . . . . . . . . 33 Character Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 String and Array Utilities . . . . . . . . . . . . . . . . . . . . . . . . . 79 Character Set Handling . . . . . . . . . . . . . . . . . . . . . . . . . 119 Locales and Internationalization . . . . . . . . . . . . . . . . . . . . 163 Message Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183 Searching and Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 Pattern Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 Input/Output Overview . . . . . . . . . . . . . . . . . . . . . . . . . 239 Input/Output on Streams . . . . . . . . . . . . . . . . . . . . . . . . 245 Low-Level Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . 319 File System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 Pipes and FIFOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417 Low-Level Terminal Interface . . . . . . . . . . . . . . . . . . . . . . 465 Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493 Mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 501 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 539 Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 Resource Usage And Limitation . . . . . . . . . . . . . . . . . . . . 605 Non-Local Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635 The Basic Program/System Interface . . . . . . . . . . . . . . . . 683 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729 Job Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741 System Databases and Name Service Switch . . . . . . . . . . . 761 Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 771 System Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 799 System Conguration Parameters . . . . . . . . . . . . . . . . . . . 815 DES Encryption and Password Handling . . . . . . . . . . . . . . 837 Debugging support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845 C Language Facilities in the Library . . . . . . . . . . . . . . . . . 849 Summary of Library Facilities . . . . . . . . . . . . . . . . . . . . . 867

ii

The GNU C Library

C Installing the GNU C Library . . . . . . . . . . . . . . . . . . . . . 969 D Library Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . 979 E Contributors to the GNU C Library . . . . . . . . . . . . . . . . . 987 F Free Software Needs Free Documentation . . . . . . . . . . . . . 993 G GNU Lesser General Public License . . . . . . . . . . . . . . . . . 995 H GNU Free Documentation License . . . . . . . . . . . . . . . . . 1005 Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013 Type Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023 Function and Macro Index . . . . . . . . . . . . . . . . . . . . . . . . . . 1025 Variable and Constant Macro Index . . . . . . . . . . . . . . . . . . . 1037 Program and File Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047

iii

Table of Contents1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1 1.2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 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) . . . . . . . . . . . 3 Using the Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.3.1 Header Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.3.2 Macro Denitions of Functions. . . . . . . . . . . . . . . . . . . 5 1.3.3 Reserved Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 1.3.4 Feature Test Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 Roadmap to the Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

1.3

1.4

2

Error Reporting . . . . . . . . . . . . . . . . . . . . . . . . . . 152.1 Checking for Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 2.2 Error Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 2.3 Error Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

3

Virtual Memory Allocation And Paging . . . . 333.1 Process Memory Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2 Allocating Storage For Program Data . . . . . . . . . . . . . . . . . . . . 3.2.1 Memory Allocation in C Programs . . . . . . . . . . . . . . 3.2.1.1 Dynamic Memory Allocation . . . . . . . . . . . 3.2.2 Unconstrained Allocation. . . . . . . . . . . . . . . . . . . . . . . 3.2.2.1 Basic Memory Allocation . . . . . . . . . . . . . . 3.2.2.2 Examples of malloc . . . . . . . . . . . . . . . . . . . 3.2.2.3 Freeing Memory Allocated with malloc ......................................... 3.2.2.4 Changing the Size of a Block . . . . . . . . . . . 3.2.2.5 Allocating Cleared Space . . . . . . . . . . . . . . 3.2.2.6 Eciency Considerations for malloc . . . . 3.2.2.7 Allocating Aligned Memory Blocks . . . . . 3.2.2.8 Malloc Tunable Parameters . . . . . . . . . . . . 3.2.2.9 Heap Consistency Checking . . . . . . . . . . . . 3.2.2.10 Memory Allocation Hooks . . . . . . . . . . . . 3.2.2.11 Statistics for Memory Allocation with malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.2.12 Summary of malloc-Related Functions ......................................... 33 35 35 35 36 36 37 37 38 39 40 40 41 41 43 46 47

iv 3.2.3

The GNU C Library Allocation Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.3.1 How to install the tracing functionality . . 3.2.3.2 Example program excerpts . . . . . . . . . . . . . 3.2.3.3 Some more or less clever ideas . . . . . . . . . 3.2.3.4 Interpreting the traces . . . . . . . . . . . . . . . . . 3.2.4 Obstacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.2.4.1 Creating Obstacks . . . . . . . . . . . . . . . . . . . . 3.2.4.2 Preparing for Using Obstacks . . . . . . . . . . 3.2.4.3 Allocation in an Obstack . . . . . . . . . . . . . . 3.2.4.4 Freeing Objects in an Obstack . . . . . . . . . 3.2.4.5 Obstack Functions and Macros . . . . . . . . . 3.2.4.6 Growing Objects . . . . . . . . . . . . . . . . . . . . . . 3.2.4.7 Extra Fast Growing Objects . . . . . . . . . . . 3.2.4.8 Status of an Obstack . . . . . . . . . . . . . . . . . . 3.2.4.9 Alignment of Data in Obstacks . . . . . . . . . 3.2.4.10 Obstack Chunks . . . . . . . . . . . . . . . . . . . . . 3.2.4.11 Summary of Obstack Functions . . . . . . . 3.2.5 Automatic Storage with Variable Size . . . . . . . . . . . 3.2.5.1 alloca Example . . . . . . . . . . . . . . . . . . . . . . 3.2.5.2 Advantages of alloca . . . . . . . . . . . . . . . . . 3.2.5.3 Disadvantages of alloca. . . . . . . . . . . . . . . 3.2.5.4 GNU C Variable-Size Arrays . . . . . . . . . . . 3.3 Resizing the Data Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4 Locking Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.1 Why Lock Pages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3.4.2 Locked Memory Details . . . . . . . . . . . . . . . . . . . . . . . . 3.4.3 Functions To Lock And Unlock Pages . . . . . . . . . . . 48 48 48 49 50 51 52 52 53 54 55 55 57 59 59 60 60 62 62 63 63 64 64 65 65 65 66

4

Character Handling . . . . . . . . . . . . . . . . . . . . . . . 694.1 4.2 4.3 4.4 4.5 Classication of Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Case Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Character class determination for wide characters . . . . . . . . . Notes on using the wide character classes . . . . . . . . . . . . . . . . Mapping of wide characters.. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 71 72 75 76

5

String and Array Utilities . . . . . . . . . . . . . . . . . 79Representation of Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 String and Array Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 String Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Copying and Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 String/Array Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94 Collation Functions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Search Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101 5.7.1 Compatibility String Search Functions . . . . . . . . . 106 5.8 Finding Tokens in a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106 5.9 strfry. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 5.10 Trivial Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 5.11 Encode Binary Data. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111 5.1 5.2 5.3 5.4 5.5 5.6 5.7

v 5.12 Argz and Envz Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113 5.12.1 Argz Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114 5.12.2 Envz Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116

6

Character Set Handling . . . . . . . . . . . . . . . . . . 1196.1 Introduction to Extended Characters . . . . . . . . . . . . . . . . . . . 119 6.2 Overview about Character Handling Functions . . . . . . . . . . 123 6.3 Restartable Multibyte Conversion Functions . . . . . . . . . . . . . 123 6.3.1 Selecting the conversion and its properties . . . . . . 123 6.3.2 Representing the state of the conversion . . . . . . . . 124 6.3.3 Converting Single Characters . . . . . . . . . . . . . . . . . . 126 6.3.4 Converting Multibyte and Wide Character Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131 6.3.5 A Complete Multibyte Conversion Example . . . . 135 6.4 Non-reentrant Conversion Function . . . . . . . . . . . . . . . . . . . . . 136 6.4.1 Non-reentrant Conversion of Single Characters . . 137 6.4.2 Non-reentrant Conversion of Strings. . . . . . . . . . . . 138 6.4.3 States in Non-reentrant Functions. . . . . . . . . . . . . . 139 6.5 Generic Charset Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140 6.5.1 Generic Character Set Conversion Interface . . . . . 141 6.5.2 A complete iconv example . . . . . . . . . . . . . . . . . . . . 144 6.5.3 Some Details about other iconv Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146 6.5.4 The iconv Implementation in the GNU C library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148 6.5.4.1 Format of gconv-modules les . . . . . . . 149 6.5.4.2 Finding the conversion path in iconv . . 150 6.5.4.3 iconv module data structures . . . . . . . . . 151 6.5.4.4 iconv module interfaces . . . . . . . . . . . . . . 154

7

Locales and Internationalization . . . . . . . . . . 163What Eects a Locale Has . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163 Choosing a Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164 Categories of Activities that Locales Aect . . . . . . . . . . . . . . 164 How Programs Set the Locale . . . . . . . . . . . . . . . . . . . . . . . . . . 165 Standard Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167 Accessing Locale Information . . . . . . . . . . . . . . . . . . . . . . . . . . 167 7.6.1 localeconv: It is portable but . . . . . . . . . . . . . . . . 168 7.6.1.1 Generic Numeric Formatting Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168 7.6.1.2 Printing the Currency Symbol . . . . . . . . 169 7.6.1.3 Printing the Sign of a Monetary Amount . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171 7.6.2 Pinpoint Access to Locale Data . . . . . . . . . . . . . . . . 171 7.7 A dedicated function to format numbers . . . . . . . . . . . . . . . . 177 7.8 Yes-or-No Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180 7.1 7.2 7.3 7.4 7.5 7.6

vi

The GNU C Library

8

Message Translation . . . . . . . . . . . . . . . . . . . . . 1838.1 Message Catalog Handling . . . . . . . . . . . . . . . . . . . . . 183 The catgets function family . . . . . . . . . . . . . . . . . . 183 Format of the message catalog les . . . . . . . . . . . . . 186 Generate Message Catalogs les . . . . . . . . . . . . . . . 188 How to use the catgets interface . . . . . . . . . . . . . . 189 8.1.4.1 Not using symbolic names . . . . . . . . . . . . 190 8.1.4.2 Using symbolic names . . . . . . . . . . . . . . . . 190 8.1.4.3 How does to this allow to develop . . . . . 191 The Uniforum approach to Message Translation . . . . . . . . . 192 8.2.1 The gettext family of functions . . . . . . . . . . . . . . . 193 8.2.1.1 What has to be done to translate a message? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193 8.2.1.2 How to determine which catalog to be used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 8.2.1.3 Additional functions for more complicated situations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 8.2.1.4 How to specify the output character set gettext uses . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201 8.2.1.5 How to use gettext in GUI programs . . 201 8.2.1.6 User inuence on gettext . . . . . . . . . . . . 203 8.2.2 Programs to handle message catalogs for gettext . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 X/Open 8.1.1 8.1.2 8.1.3 8.1.4

8.2

9

Searching and Sorting. . . . . . . . . . . . . . . . . . . . 2099.1 9.2 9.3 9.4 9.5 9.6 Dening the Comparison Function . . . . . . . . . . . . . . . . . . . . . . Array Search Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Array Sort Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Searching and Sorting Example . . . . . . . . . . . . . . . . . . . . . . . . The hsearch function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The tsearch function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209 209 210 211 214 216

10

Pattern Matching . . . . . . . . . . . . . . . . . . . . . . 21910.1 Wildcard Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219 10.2 Globbing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 10.2.1 Calling glob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220 10.2.2 Flags for Globbing . . . . . . . . . . . . . . . . . . . . . . . . . . . 224 10.2.3 More Flags for Globbing . . . . . . . . . . . . . . . . . . . . . 225 10.3 Regular Expression Matching . . . . . . . . . . . . . . . . . . . . . . . . . 227 10.3.1 POSIX Regular Expression Compilation . . . . . . . 227 10.3.2 Flags for POSIX Regular Expressions . . . . . . . . . 229 10.3.3 Matching a Compiled POSIX Regular Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 230 10.3.4 Match Results with Subexpressions . . . . . . . . . . . 230 10.3.5 Complications in Subexpression Matching . . . . . 231 10.3.6 POSIX Regexp Matching Cleanup . . . . . . . . . . . . 232 10.4 Shell-Style Word Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

vii 10.4.1 10.4.2 10.4.3 10.4.4 10.4.5 10.4.6 The Stages of Word Expansion . . . . . . . . . . . . . . . Calling wordexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Flags for Word Expansion . . . . . . . . . . . . . . . . . . . . wordexp Example . . . . . . . . . . . . . . . . . . . . . . . . . . . Details of Tilde Expansion . . . . . . . . . . . . . . . . . . . Details of Variable Substitution . . . . . . . . . . . . . . . 233 233 235 236 237 237

11

Input/Output Overview. . . . . . . . . . . . . . . . . 23911.1 Input/Output Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1.1 Streams and File Descriptors . . . . . . . . . . . . . . . . . 11.1.2 File Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2.1 Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2.2 File Name Resolution . . . . . . . . . . . . . . . . . . . . . . . . 11.2.3 File Name Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.2.4 Portability of File Names. . . . . . . . . . . . . . . . . . . . . 239 239 240 241 241 242 242 243

11.2

12

Input/Output on Streams . . . . . . . . . . . . . . . 245Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Standard Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Opening Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Closing Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Streams and Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Streams in Internationalized Applications . . . . . . . . . . . . . . Simple Output by Characters or Lines . . . . . . . . . . . . . . . . . Character Input. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Line-Oriented Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Unreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.10.1 What Unreading Means . . . . . . . . . . . . . . . . . . . . . 12.10.2 Using ungetc To Do Unreading. . . . . . . . . . . . . . 12.11 Block Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.12 Formatted Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.12.1 Formatted Output Basics . . . . . . . . . . . . . . . . . . . 12.12.2 Output Conversion Syntax . . . . . . . . . . . . . . . . . . 12.12.3 Table of Output Conversions . . . . . . . . . . . . . . . . 12.12.4 Integer Conversions . . . . . . . . . . . . . . . . . . . . . . . . . 12.12.5 Floating-Point Conversions . . . . . . . . . . . . . . . . . . 12.12.6 Other Output Conversions . . . . . . . . . . . . . . . . . . 12.12.7 Formatted Output Functions . . . . . . . . . . . . . . . . 12.12.8 Dynamically Allocating Formatted Output . . . 12.12.9 Variable Arguments Output Functions . . . . . . . 12.12.10 Parsing a Template String . . . . . . . . . . . . . . . . . 12.12.11 Example of Parsing a Template String . . . . . . 12.13 Customizing printf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.13.1 Registering New Conversions . . . . . . . . . . . . . . . . 12.13.2 Conversion Specier Options . . . . . . . . . . . . . . . . 12.13.3 Dening the Output Handler . . . . . . . . . . . . . . . . 12.13.4 printf Extension Example . . . . . . . . . . . . . . . . . . 12.1 12.2 12.3 12.4 12.5 12.6 12.7 12.8 12.9 12.10 245 245 246 249 250 253 255 257 260 262 262 262 263 264 265 265 267 268 270 272 273 275 276 278 280 281 282 282 284 285

viii

The GNU C Library 12.13.5 Predened printf Handlers . . . . . . . . . . . . . . . . . Formatted Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.14.1 Formatted Input Basics . . . . . . . . . . . . . . . . . . . . . 12.14.2 Input Conversion Syntax . . . . . . . . . . . . . . . . . . . . 12.14.3 Table of Input Conversions . . . . . . . . . . . . . . . . . . 12.14.4 Numeric Input Conversions. . . . . . . . . . . . . . . . . . 12.14.5 String Input Conversions . . . . . . . . . . . . . . . . . . . . 12.14.6 Dynamically Allocating String Conversions . . . 12.14.7 Other Input Conversions . . . . . . . . . . . . . . . . . . . . 12.14.8 Formatted Input Functions . . . . . . . . . . . . . . . . . . 12.14.9 Variable Arguments Input Functions . . . . . . . . . End-Of-File and Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Recovering from errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Text and Binary Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Portable File-Position Functions . . . . . . . . . . . . . . . . . . . . . . Stream Buering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.20.1 Buering Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 12.20.2 Flushing Buers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.20.3 Controlling Which Kind of Buering . . . . . . . . . Other Kinds of Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.21.1 String Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.21.2 Obstack Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.21.3 Programming Your Own Custom Streams . . . . 12.21.3.1 Custom Streams and Cookies . . . . . . . 12.21.3.2 Custom Stream Hook Functions . . . . . Formatted Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12.22.1 Printing Formatted Messages . . . . . . . . . . . . . . . . 12.22.2 Adding Severity Classes . . . . . . . . . . . . . . . . . . . . . 12.22.3 How to use fmtmsg and addseverity . . . . . . . . 286 287 287 288 289 291 292 294 294 295 296 297 298 298 299 302 303 304 304 305 308 308 310 311 311 312 313 313 316 316

12.14

12.15 12.16 12.17 12.18 12.19 12.20

12.21

12.22

13

Low-Level Input/Output . . . . . . . . . . . . . . . . 31913.1 13.2 13.3 13.4 13.5 Opening and Closing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . Input and Output Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the File Position of a Descriptor . . . . . . . . . . . . . . . Descriptors and Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Dangers of Mixing Streams and Descriptors . . . . . . . . . . . . 13.5.1 Linked Channels. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.5.2 Independent Channels . . . . . . . . . . . . . . . . . . . . . . . 13.5.3 Cleaning Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . Fast Scatter-Gather I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Memory-mapped I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Waiting for Input or Output . . . . . . . . . . . . . . . . . . . . . . . . . . Synchronizing I/O operations . . . . . . . . . . . . . . . . . . . . . . . . . Perform I/O Operations in Parallel . . . . . . . . . . . . . . . . . . . 13.10.1 Asynchronous Read and Write Operations . . . . 13.10.2 Getting the Status of AIO Operations . . . . . . . . 13.10.3 Getting into a Consistent State . . . . . . . . . . . . . . 319 322 326 329 330 330 330 331 331 332 337 340 341 344 348 349

13.6 13.7 13.8 13.9 13.10

ix 13.10.4 Cancellation of AIO Operations . . . . . . . . . . . . . 13.10.5 How to optimize the AIO implementation . . . . Control Operations on Files . . . . . . . . . . . . . . . . . . . . . . . . . . Duplicating Descriptors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Descriptor Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . File Status Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.14.1 File Access Modes . . . . . . . . . . . . . . . . . . . . . . . . . . 13.14.2 Open-time Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . 13.14.3 I/O Operating Modes . . . . . . . . . . . . . . . . . . . . . . . 13.14.4 Getting and Setting File Status Flags . . . . . . . . File Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Interrupt-Driven Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Generic I/O Control operations . . . . . . . . . . . . . . . . . . . . . . 351 352 353 354 355 357 357 358 360 361 362 365 366

13.11 13.12 13.13 13.14

13.15 13.16 13.17

14

File System Interface . . . . . . . . . . . . . . . . . . . 36914.1 Working Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.2 Accessing Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.2.1 Format of a Directory Entry . . . . . . . . . . . . . . . . . . 14.2.2 Opening a Directory Stream . . . . . . . . . . . . . . . . . . 14.2.3 Reading and Closing a Directory Stream . . . . . . 14.2.4 Simple Program to List a Directory . . . . . . . . . . . 14.2.5 Random Access in a Directory Stream . . . . . . . . 14.2.6 Scanning the Content of a Directory . . . . . . . . . . 14.2.7 Simple Program to List a Directory, Mark II . . . 14.3 Working with Directory Trees . . . . . . . . . . . . . . . . . . . . . . . . . 14.4 Hard Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.5 Symbolic Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.6 Deleting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.7 Renaming Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.8 Creating Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.9 File Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.9.1 The meaning of the File Attributes . . . . . . . . . . . 14.9.2 Reading the Attributes of a File . . . . . . . . . . . . . . 14.9.3 Testing the Type of a File . . . . . . . . . . . . . . . . . . . . 14.9.4 File Owner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.9.5 The Mode Bits for Access Permission . . . . . . . . . 14.9.6 How Your Access to a File is Decided . . . . . . . . . 14.9.7 Assigning File Permissions . . . . . . . . . . . . . . . . . . . 14.9.8 Testing Permission to Access a File . . . . . . . . . . . 14.9.9 File Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.9.10 File Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.10 Making Special Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14.11 Temporary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 369 371 371 372 373 375 375 376 377 378 382 383 385 386 388 388 388 392 394 396 397 399 399 401 402 404 406 407

x

The GNU C Library

15

Pipes and FIFOs . . . . . . . . . . . . . . . . . . . . . . . 41115.1 Creating a Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.2 Pipe to a Subprocess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.3 FIFO Special Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15.4 Atomicity of Pipe I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 411 413 414 415

16

Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41716.1 Socket Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.2 Communication Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.3 Socket Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.3.1 Address Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.3.2 Setting the Address of a Socket . . . . . . . . . . . . . . . 16.3.3 Reading the Address of a Socket . . . . . . . . . . . . . . 16.4 Interface Naming. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.5 The Local Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.5.1 Local Namespace Concepts . . . . . . . . . . . . . . . . . . . 16.5.2 Details of Local Namespace . . . . . . . . . . . . . . . . . . 16.5.3 Example of Local-Namespace Sockets . . . . . . . . . 16.6 The Internet Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.6.1 Internet Socket Address Formats. . . . . . . . . . . . . . 16.6.2 Host Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.6.2.1 Internet Host Addresses . . . . . . . . . . . . . 16.6.2.2 Host Address Data Type . . . . . . . . . . . . 16.6.2.3 Host Address Functions . . . . . . . . . . . . . 16.6.2.4 Host Names . . . . . . . . . . . . . . . . . . . . . . . . 16.6.3 Internet Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.6.4 The Services Database . . . . . . . . . . . . . . . . . . . . . . . 16.6.5 Byte Order Conversion . . . . . . . . . . . . . . . . . . . . . . . 16.6.6 Protocols Database . . . . . . . . . . . . . . . . . . . . . . . . . . 16.6.7 Internet Socket Example . . . . . . . . . . . . . . . . . . . . . 16.7 Other Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.8 Opening and Closing Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . 16.8.1 Creating a Socket. . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.8.2 Closing a Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.8.3 Socket Pairs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.9 Using Sockets with Connections . . . . . . . . . . . . . . . . . . . . . . . 16.9.1 Making a Connection . . . . . . . . . . . . . . . . . . . . . . . . 16.9.2 Listening for Connections . . . . . . . . . . . . . . . . . . . . 16.9.3 Accepting Connections . . . . . . . . . . . . . . . . . . . . . . . 16.9.4 Who is Connected to Me? . . . . . . . . . . . . . . . . . . . . 16.9.5 Transferring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.9.5.1 Sending Data . . . . . . . . . . . . . . . . . . . . . . . 16.9.5.2 Receiving Data . . . . . . . . . . . . . . . . . . . . . 16.9.5.3 Socket Data Options . . . . . . . . . . . . . . . . 16.9.6 Byte Stream Socket Example . . . . . . . . . . . . . . . . . 16.9.7 Byte Stream Connection Server Example . . . . . . 16.9.8 Out-of-Band Data . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.10 Datagram Socket Operations . . . . . . . . . . . . . . . . . . . . . . . . . 417 418 419 419 421 421 422 423 423 423 424 425 426 427 427 428 429 431 434 435 436 437 439 440 440 440 441 441 442 442 444 444 445 446 446 447 448 448 449 452 455

xi 16.10.1 Sending Datagrams . . . . . . . . . . . . . . . . . . . . . . . . . 16.10.2 Receiving Datagrams . . . . . . . . . . . . . . . . . . . . . . . 16.10.3 Datagram Socket Example . . . . . . . . . . . . . . . . . . 16.10.4 Example of Reading Datagrams . . . . . . . . . . . . . 16.11 The inetd Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.11.1 inetd Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.11.2 Conguring inetd . . . . . . . . . . . . . . . . . . . . . . . . . . 16.12 Socket Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16.12.1 Socket Option Functions . . . . . . . . . . . . . . . . . . . . 16.12.2 Socket-Level Options . . . . . . . . . . . . . . . . . . . . . . . 16.13 Networks Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455 455 456 457 459 459 459 460 460 461 462

17

Low-Level Terminal Interface . . . . . . . . . . . . 46517.1 Identifying Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.2 I/O Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.3 Two Styles of Input: Canonical or Not . . . . . . . . . . . . . . . . . 17.4 Terminal Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.4.1 Terminal Mode Data Types . . . . . . . . . . . . . . . . . . 17.4.2 Terminal Mode Functions . . . . . . . . . . . . . . . . . . . . 17.4.3 Setting Terminal Modes Properly . . . . . . . . . . . . . 17.4.4 Input Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.4.5 Output Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.4.6 Control Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.4.7 Local Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.4.8 Line Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.4.9 Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.4.9.1 Characters for Input Editing . . . . . . . . . 17.4.9.2 Characters that Cause Signals . . . . . . . 17.4.9.3 Special Characters for Flow Control . . 17.4.9.4 Other Special Characters . . . . . . . . . . . . 17.4.10 Noncanonical Input . . . . . . . . . . . . . . . . . . . . . . . . . 17.5 BSD Terminal Modes. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.6 Line Control Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.7 Noncanonical Mode Example. . . . . . . . . . . . . . . . . . . . . . . . . . 17.8 Pseudo-Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17.8.1 Allocating Pseudo-Terminals . . . . . . . . . . . . . . . . . 17.8.2 Opening a Pseudo-Terminal Pair. . . . . . . . . . . . . . 465 466 466 467 467 468 469 470 472 473 475 477 479 479 481 482 482 483 484 485 487 488 489 491

18

Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49318.1 Overview of Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.2 Submitting Syslog Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . 18.2.1 openlog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.2.2 syslog, vsyslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.2.3 closelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.2.4 setlogmask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18.2.5 Syslog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 493 494 494 495 498 498 499

xii

The GNU C Library

19

Mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . 50119.1 19.2 19.3 19.4 19.5 19.6 19.7 19.8 Predened Mathematical Constants . . . . . . . . . . . . . . . . . . . Trigonometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Inverse Trigonometric Functions . . . . . . . . . . . . . . . . . . . . . . . Exponentiation and Logarithms . . . . . . . . . . . . . . . . . . . . . . . Hyperbolic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Special Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Known Maximum Errors in Math Functions . . . . . . . . . . . . Pseudo-Random Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19.8.1 ISO C Random Number Functions . . . . . . . . . . . . 19.8.2 BSD Random Number Functions . . . . . . . . . . . . . 19.8.3 SVID Random Number Function . . . . . . . . . . . . . Is Fast Code or Small Code preferred? . . . . . . . . . . . . . . . . . 501 502 504 505 509 511 513 531 531 532 534 538

19.9

20

Arithmetic Functions . . . . . . . . . . . . . . . . . . . 539Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Integer Division . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Floating Point Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Floating-Point Number Classication Functions . . . . . . . . Errors in Floating-Point Calculations . . . . . . . . . . . . . . . . . . 20.5.1 FP Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.5.2 Innity and NaN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.5.3 Examining the FPU status word . . . . . . . . . . . . . . 20.5.4 Error Reporting by Mathematical Functions . . . 20.6 Rounding Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.7 Floating-Point Control Functions . . . . . . . . . . . . . . . . . . . . . . 20.8 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.8.1 Absolute Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.8.2 Normalization Functions . . . . . . . . . . . . . . . . . . . . . 20.8.3 Rounding Functions . . . . . . . . . . . . . . . . . . . . . . . . . 20.8.4 Remainder Functions . . . . . . . . . . . . . . . . . . . . . . . . 20.8.5 Setting and modifying single bits of FP values . . 20.8.6 Floating-Point Comparison Functions . . . . . . . . . 20.8.7 Miscellaneous FP arithmetic functions . . . . . . . . 20.9 Complex Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.10 Projections, Conjugates, and Decomposing of Complex Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.11 Parsing of Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.11.1 Parsing of Integers . . . . . . . . . . . . . . . . . . . . . . . . . . 20.11.2 Parsing of Floats . . . . . . . . . . . . . . . . . . . . . . . . . . . 20.12 Old-fashioned System V number-to-string functions . . . . 20.1 20.2 20.3 20.4 20.5 539 540 542 542 544 544 546 547 548 549 551 552 553 553 555 556 557 558 559 560 561 562 562 566 568

xiii

21

Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . 57121.1 Time Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 21.2 Elapsed Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571 21.3 Processor And CPU Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . 573 21.3.1 CPU Time Inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . 573 21.3.2 Processor Time Inquiry . . . . . . . . . . . . . . . . . . . . . . 574 21.4 Calendar Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575 21.4.1 Simple Calendar Time . . . . . . . . . . . . . . . . . . . . . . . 576 21.4.2 High-Resolution Calendar . . . . . . . . . . . . . . . . . . . . 576 21.4.3 Broken-down Time . . . . . . . . . . . . . . . . . . . . . . . . . . 578 21.4.4 High Accuracy Clock . . . . . . . . . . . . . . . . . . . . . . . . 581 21.4.5 Formatting Calendar Time . . . . . . . . . . . . . . . . . . . 584 21.4.6 Convert textual time and date information back . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589 21.4.6.1 Interpret string according to given format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590 21.4.6.2 A More User-friendly Way to Parse Times and Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595 21.4.7 Specifying the Time Zone with TZ . . . . . . . . . . . . 597 21.4.8 Functions and Variables for Time Zones . . . . . . . 599 21.4.9 Time Functions Example . . . . . . . . . . . . . . . . . . . . . 600 21.5 Setting an Alarm. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600 21.6 Sleeping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603

22

Resource Usage And Limitation . . . . . . . . . 60522.1 Resource Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605 22.2 Limiting Resource Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 607 22.3 Process CPU Priority And Scheduling . . . . . . . . . . . . . . . . . 611 22.3.1 Absolute Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612 22.3.1.1 Using Absolute Priority . . . . . . . . . . . . . 612 22.3.2 Realtime Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . 613 22.3.3 Basic Scheduling Functions . . . . . . . . . . . . . . . . . . . 614 22.3.4 Traditional Scheduling . . . . . . . . . . . . . . . . . . . . . . . 617 22.3.4.1 Introduction To Traditional Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617 22.3.4.2 Functions For Traditional Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618 22.4 Querying memory available resources . . . . . . . . . . . . . . . . . . 620 22.4.1 Overview about traditional Unix memory handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 22.4.2 How to get information about the memory subsystem? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 22.5 Learn about the processors available . . . . . . . . . . . . . . . . . . . 622

xiv

The GNU C Library

23

Non-Local Exits . . . . . . . . . . . . . . . . . . . . . . . . 62523.1 Introduction to Non-Local Exits . . . . . . . . . . . . . . . . . . . . . . . 23.2 Details of Non-Local Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23.3 Non-Local Exits and Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 23.4 Complete Context Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 626 627 628

24

Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . 63524.1 Basic Concepts of Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.1.1 Some Kinds of Signals . . . . . . . . . . . . . . . . . . . . . . . 24.1.2 Concepts of Signal Generation . . . . . . . . . . . . . . . . 24.1.3 How Signals Are Delivered . . . . . . . . . . . . . . . . . . . Standard Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.2.1 Program Error Signals . . . . . . . . . . . . . . . . . . . . . . . 24.2.2 Termination Signals . . . . . . . . . . . . . . . . . . . . . . . . . 24.2.3 Alarm Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.2.4 Asynchronous I/O Signals . . . . . . . . . . . . . . . . . . . . 24.2.5 Job Control Signals . . . . . . . . . . . . . . . . . . . . . . . . . . 24.2.6 Operation Error Signals . . . . . . . . . . . . . . . . . . . . . . 24.2.7 Miscellaneous Signals . . . . . . . . . . . . . . . . . . . . . . . . 24.2.8 Signal Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Signal Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.3.1 Basic Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . 24.3.2 Advanced Signal Handling . . . . . . . . . . . . . . . . . . . 24.3.3 Interaction of signal and sigaction . . . . . . . . . 24.3.4 sigaction Function Example . . . . . . . . . . . . . . . . 24.3.5 Flags for sigaction . . . . . . . . . . . . . . . . . . . . . . . . . 24.3.6 Initial Signal Actions . . . . . . . . . . . . . . . . . . . . . . . . Dening Signal Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.4.1 Signal Handlers that Return . . . . . . . . . . . . . . . . . . 24.4.2 Handlers That Terminate the Process . . . . . . . . . 24.4.3 Nonlocal Control Transfer in Handlers . . . . . . . . 24.4.4 Signals Arriving While a Handler Runs . . . . . . . . 24.4.5 Signals Close Together Merge into One . . . . . . . . 24.4.6 Signal Handling and Nonreentrant Functions . . 24.4.7 Atomic Data Access and Signal Handling . . . . . . 24.4.7.1 Problems with Non-Atomic Access . . . 24.4.7.2 Atomic Types . . . . . . . . . . . . . . . . . . . . . . 24.4.7.3 Atomic Usage Patterns . . . . . . . . . . . . . . Primitives Interrupted by Signals . . . . . . . . . . . . . . . . . . . . . . Generating Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.6.1 Signaling Yourself . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.6.2 Signaling Another Process . . . . . . . . . . . . . . . . . . . . 24.6.3 Permission for using kill . . . . . . . . . . . . . . . . . . . . 24.6.4 Using kill for Communication . . . . . . . . . . . . . . . Blocking Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.7.1 Why Blocking Signals is Useful . . . . . . . . . . . . . . . 24.7.2 Signal Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.7.3 Process Signal Mask . . . . . . . . . . . . . . . . . . . . . . . . . 635 635 636 636 637 637 640 641 642 642 644 645 645 646 646 648 649 650 651 652 652 653 654 655 656 657 659 661 661 662 662 663 664 664 665 666 667 668 669 669 670

24.2

24.3

24.4

24.5 24.6

24.7

xv 24.7.4 Blocking to Test for Delivery of a Signal . . . . . . . 24.7.5 Blocking Signals for a Handler . . . . . . . . . . . . . . . . 24.7.6 Checking for Pending Signals . . . . . . . . . . . . . . . . . 24.7.7 Remembering a Signal to Act On Later . . . . . . . 24.8 Waiting for a Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.8.1 Using pause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.8.2 Problems with pause . . . . . . . . . . . . . . . . . . . . . . . . 24.8.3 Using sigsuspend . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.9 Using a Separate Signal Stack . . . . . . . . . . . . . . . . . . . . . . . . . 24.10 BSD Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24.10.1 BSD Function to Establish a Handler . . . . . . . . 24.10.2 BSD Functions for Blocking Signals . . . . . . . . . . 671 672 673 674 675 675 676 677 678 680 680 681

25

The Basic Program/System Interface . . . . 683Program Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 683 25.1.1 Program Argument Syntax Conventions . . . . . . . 684 25.1.2 Parsing Program Arguments . . . . . . . . . . . . . . . . . 685 25.2 Parsing program options using getopt . . . . . . . . . . . . . . . . . 685 25.2.1 Using the getopt function . . . . . . . . . . . . . . . . . . . 685 25.2.2 Example of Parsing Arguments with getopt . . . 686 25.2.3 Parsing Long Options with getopt_long . . . . . . 688 25.2.4 Example of Parsing Long Options with getopt_long . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690 25.3 Parsing Program Options with Argp . . . . . . . . . . . . . . . . . . . 692 25.3.1 The argp_parse Function . . . . . . . . . . . . . . . . . . . . 692 25.3.2 Argp Global Variables . . . . . . . . . . . . . . . . . . . . . . . 693 25.3.3 Specifying Argp Parsers . . . . . . . . . . . . . . . . . . . . . . 694 25.3.4 Specifying Options in an Argp Parser . . . . . . . . . 695 25.3.4.1 Flags for Argp Options . . . . . . . . . . . . . . 696 25.3.5 Argp Parser Functions . . . . . . . . . . . . . . . . . . . . . . . 696 25.3.5.1 Special Keys for Argp Parser Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698 25.3.5.2 Functions For Use in Argp Parsers . . . 700 25.3.5.3 Argp Parsing State . . . . . . . . . . . . . . . . . . 701 25.3.6 Combining Multiple Argp Parsers . . . . . . . . . . . . . 702 25.3.7 Flags for argp_parse . . . . . . . . . . . . . . . . . . . . . . . . 703 25.3.8 Customizing Argp Help Output . . . . . . . . . . . . . . . 704 25.3.8.1 Special Keys for Argp Help Filter Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704 25.3.9 The argp_help Function . . . . . . . . . . . . . . . . . . . . . 705 25.3.10 Flags for the argp_help Function . . . . . . . . . . . . 705 25.3.11 Argp Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706 25.3.11.1 A Minimal Program Using Argp . . . . 706 25.3.11.2 A Program Using Argp with Only Default Options . . . . . . . . . . . . . . . . . . . . . . . . . 707 25.3.11.3 A Program Using Argp with User Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708 25.1

xvi

The GNU C Library 25.3.11.4 A Program Using Multiple Combined Argp Parsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25.3.12 Argp User Customization . . . . . . . . . . . . . . . . . . . 25.3.12.5 Parsing of Suboptions . . . . . . . . . . . . . . 25.3.13 Parsing of Suboptions Example . . . . . . . . . . . . . . 25.4 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25.4.1 Environment Access . . . . . . . . . . . . . . . . . . . . . . . . . 25.4.2 Standard Environment Variables . . . . . . . . . . . . . . 25.5 System Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25.6 Program Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25.6.1 Normal Termination . . . . . . . . . . . . . . . . . . . . . . . . . 25.6.2 Exit Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25.6.3 Cleanups on Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25.6.4 Aborting a Program . . . . . . . . . . . . . . . . . . . . . . . . . 25.6.5 Termination Internals . . . . . . . . . . . . . . . . . . . . . . . .

711 715 716 716 718 719 720 722 724 724 724 725 726 727

26

Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72926.1 26.2 26.3 26.4 26.5 26.6 26.7 26.8 26.9 Running a Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process Creation Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process Identication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Executing a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Process Completion Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . BSD Process Wait Functions . . . . . . . . . . . . . . . . . . . . . . . . . . Process Creation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729 730 730 731 732 734 737 738 739

27

Job Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74127.1 27.2 27.3 27.4 27.5 27.6 Concepts of Job Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Job Control is Optional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Controlling Terminal of a Process . . . . . . . . . . . . . . . . . . . . . Access to the Controlling Terminal . . . . . . . . . . . . . . . . . . . . Orphaned Process Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementing a Job Control Shell . . . . . . . . . . . . . . . . . . . . . 27.6.1 Data Structures for the Shell . . . . . . . . . . . . . . . . . 27.6.2 Initializing the Shell . . . . . . . . . . . . . . . . . . . . . . . . . 27.6.3 Launching Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27.6.4 Foreground and Background . . . . . . . . . . . . . . . . . . 27.6.5 Stopped and Terminated Jobs . . . . . . . . . . . . . . . . 27.6.6 Continuing Stopped Jobs . . . . . . . . . . . . . . . . . . . . . 27.6.7 The Missing Pieces . . . . . . . . . . . . . . . . . . . . . . . . . . Functions for Job Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27.7.1 Identifying the Controlling Terminal . . . . . . . . . . 27.7.2 Process Group Functions . . . . . . . . . . . . . . . . . . . . . 27.7.3 Functions for Controlling Terminal Access . . . . . 741 742 742 742 743 743 744 745 747 750 751 754 755 756 756 756 758

27.7

xvii

28

System Databases and Name Service Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76128.1 NSS Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28.2 The NSS Conguration File . . . . . . . . . . . . . . . . . . . . . . . . . . . 28.2.1 Services in the NSS conguration File . . . . . . . . . 28.2.2 Actions in the NSS conguration . . . . . . . . . . . . . 28.2.3 Notes on the NSS Conguration File . . . . . . . . . . 28.3 NSS Module Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28.3.1 The Naming Scheme of the NSS Modules . . . . . . 28.3.2 The Interface of the Function in NSS Modules . . 28.4 Extending NSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28.4.1 Adding another Service to NSS . . . . . . . . . . . . . . . 28.4.2 Internals of the NSS Module Functions . . . . . . . . 761 762 762 763 764 764 764 765 767 767 768

29

Users and Groups . . . . . . . . . . . . . . . . . . . . . . 77129.1 29.2 29.3 29.4 29.5 29.6 29.7 29.8 29.9 29.10 29.11 29.12 User and Group IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Persona of a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Why Change the Persona of a Process? . . . . . . . . . . . . . . . . How an Application Can Change Persona . . . . . . . . . . . . . . Reading the Persona of a Process . . . . . . . . . . . . . . . . . . . . . . Setting the User ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting the Group IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling and Disabling Setuid Access . . . . . . . . . . . . . . . . . Setuid Program Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Tips for Writing Setuid Programs . . . . . . . . . . . . . . . . . . . . Identifying Who Logged In . . . . . . . . . . . . . . . . . . . . . . . . . . The User Accounting Database. . . . . . . . . . . . . . . . . . . . . . . 29.12.1 Manipulating the User Accounting Database . . 29.12.2 XPG User Accounting Database Functions . . . 29.12.3 Logging In and Out . . . . . . . . . . . . . . . . . . . . . . . . User Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29.13.1 The Data Structure that Describes a User . . . . 29.13.2 Looking Up One User . . . . . . . . . . . . . . . . . . . . . . . 29.13.3 Scanning the List of All Users . . . . . . . . . . . . . . . 29.13.4 Writing a User Entry . . . . . . . . . . . . . . . . . . . . . . . Group Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29.14.1 The Data Structure for a Group . . . . . . . . . . . . . 29.14.2 Looking Up One Group . . . . . . . . . . . . . . . . . . . . . 29.14.3 Scanning the List of All Groups . . . . . . . . . . . . . User and Group Database Example. . . . . . . . . . . . . . . . . . . Netgroup Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29.16.1 Netgroup Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29.16.2 Looking up one Netgroup . . . . . . . . . . . . . . . . . . . 29.16.3 Testing for Netgroup Membership. . . . . . . . . . . . 771 771 772 772 773 774 775 777 778 780 781 782 782 786 789 789 790 790 791 792 792 793 793 794 795 796 796 797 798

29.13

29.14

29.15 29.16

xviii

The GNU C Library

30

System Management . . . . . . . . . . . . . . . . . . . . 79930.1 Host Identication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30.2 Platform Type Identication . . . . . . . . . . . . . . . . . . . . . . . . . . 30.3 Controlling and Querying Mounts . . . . . . . . . . . . . . . . . . . . . 30.3.1 Mount Information . . . . . . . . . . . . . . . . . . . . . . . . . . 30.3.1.1 The fstab le . . . . . . . . . . . . . . . . . . . . . 30.3.1.2 The mtab le . . . . . . . . . . . . . . . . . . . . . . 30.3.1.3 Other (Non-libc) Sources of Mount Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30.3.2 Mount, Unmount, Remount . . . . . . . . . . . . . . . . . . 30.4 System Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799 801 802 803 803 805 809 809 812

31

System Conguration Parameters . . . . . . . 81531.1 General Capacity Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 Overall System Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.3 Which Version of POSIX is Supported . . . . . . . . . . . . . . . . . 31.4 Using sysconf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.4.1 Denition of sysconf . . . . . . . . . . . . . . . . . . . . . . . . 31.4.2 Constants for sysconf Parameters . . . . . . . . . . . . 31.4.3 Examples of sysconf . . . . . . . . . . . . . . . . . . . . . . . . 31.5 Minimum Values for General Capacity Limits . . . . . . . . . . 31.6 Limits on File System Capacity . . . . . . . . . . . . . . . . . . . . . . . 31.7 Optional Features in File Support . . . . . . . . . . . . . . . . . . . . . 31.8 Minimum Values for File System Limits. . . . . . . . . . . . . . . . 31.9 Using pathconf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.10 Utility Program Capacity Limits . . . . . . . . . . . . . . . . . . . . . 31.11 Minimum Values for Utility Limits . . . . . . . . . . . . . . . . . . . 31.12 String-Valued Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 815 816 817 818 818 818 826 827 828 829 830 831 833 834 834

32

DES Encryption and Password Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83732.1 Legal Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.2 Reading Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.3 Encrypting Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32.4 DES Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 837 838 839 841

33

Debugging support . . . . . . . . . . . . . . . . . . . . . 84533.1 Backtraces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 845

xix

Appendix A C Language Facilities in the Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 849A.1 Explicitly Checking Internal Consistency . . . . . . . . . . . . . . . 849 A.2 Variadic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 850 A.2.1 Why Variadic Functions are Used . . . . . . . . . . . . . 850 A.2.2 How Variadic Functions are Dened and Used . . 851 A.2.2.1 Syntax for Variable Arguments . . . . . . . 851 A.2.2.2 Receiving the Argument Values . . . . . . . 852 A.2.2.3 How Many Arguments Were Supplied . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 852 A.2.2.4 Calling Variadic Functions . . . . . . . . . . . 853 A.2.2.5 Argument Access Macros . . . . . . . . . . . . 854 A.2.3 Example of a Variadic Function . . . . . . . . . . . . . . . 855 A.2.3.1 Old-Style Variadic Functions . . . . . . . . . 856 A.3 Null Pointer Constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 856 A.4 Important Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857 A.5 Data Type Measurements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858 A.5.1 Computing the Width of an Integer Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 858 A.5.2 Range of an Integer Type . . . . . . . . . . . . . . . . . . . . . 858 A.5.3 Floating Type Macros . . . . . . . . . . . . . . . . . . . . . . . . 860 A.5.3.1 Floating Point Representation Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 860 A.5.3.2 Floating Point Parameters . . . . . . . . . . . 861 A.5.3.3 IEEE Floating Point . . . . . . . . . . . . . . . . . 864 A.5.4 Structure Field Oset Measurement . . . . . . . . . . . 865

Appendix B Appendix CC.1 C.2 C.3 C.4 C.5 C.6

Summary of Library Facilities . . 867 Installing the GNU C Library . . 969969 972 973 974 976 976

Conguring and compiling GNU Libc . . . . . . . . . . . . . . . . . . Installing the C Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Recommended Tools for Compilation . . . . . . . . . . . . . . . . . . . Supported Congurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specic advice for Linux systems. . . . . . . . . . . . . . . . . . . . . . . Reporting Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

Appendix D

Library Maintenance . . . . . . . . . . 979979 980 983 985

D.1 Adding New Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . D.2 Porting the GNU C Library . . . . . . . . . . . . . . . . . . . . . . . . . . . D.2.1 Layout of the sysdeps Directory Hierarchy . . . D.2.2 Porting the GNU C Library to Unix Systems . . .

Appendix E Contributors to the GNU C Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 987

xx

The GNU C Library

Appendix F Free Software Needs Free Documentation . . . . . . . . . . . . . . . . . . . . . . . . . 993 Appendix G GNU Lesser General Public License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995G.0.1 Preamble . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 995 G.0.2 TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION . . . . . . . . 996 G.0.3 How to Apply These Terms to Your New Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003

Appendix H GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1005H.0.1 ADDENDUM: How to use this License for your documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1011

Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1013 Type Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1023 Function and Macro Index . . . . . . . . . . . . . . . . . 1025 Variable and Constant Macro Index. . . . . . . . . 1037 Program and File Index . . . . . . . . . . . . . . . . . . . . 1047

Chapter 1: Introduction

1

1 IntroductionThe C language provides no built-in facilities for performing such common operations as input/output, memory management, string manipulation, and the like. Instead, these facilities are dened in a standard library, which you compile and link with your programs. The GNU C library, described in this document, denes all of the library functions that are specied by the ISO C standard, as well as additional features specic to POSIX and other derivatives of the Unix operating system, and extensions specic to the GNU system. The purpose of this manual is to tell you how to use the facilities of the GNU library. We have mentioned which features belong to which standards to help you identify things that are potentially non-portable to other systems. But the emphasis in this manual is not on strict portability.

1.1 Getting StartedThis manual is written with the assumption that you are at least somewhat familiar with the C programming language and basic programming concepts. Specically, familiarity with ISO standard C (see Section 1.2.1 [ISO C], page 2), rather than traditional pre-ISO C dialects, is assumed. The GNU C library includes several header les, each of which provides denitions and declarations for a group of related facilities; this information is used by the C compiler when processing your program. For example, the header le stdio.h declares facilities for performing input and output, and the header le string.h declares string processing utilities. The organization of this manual generally follows the same division as the header les. If you are reading this manual for the rst time, you should read all of the introductory material and skim the remaining chapters. There are a lot of functions in the GNU C library and its not realistic to expect that you will be able to remember exactly how to use each and every one of them. Its more important to become generally familiar with the kinds of facilities that the library provides, so that when you are writing your programs you can recognize when to make use of library functions, and where in this manual you can nd more specic information about them.

1.2 Standards and PortabilityThis section discusses the various standards and other sources that the GNU C library is based upon. These sources include the ISO C and POSIX standards, and the System V and Berkeley Unix implementations. The primary focus of this manual is to tell you how to make eective use of the GNU library facilities. But if you are concerned about making your programs compatible with these standards, or portable to operating systems other than GNU, this can aect how you use the library. This section gives you an overview of these standards, so that you will know what they are when they are mentioned in other parts of the manual.

2

The GNU C Library

See Appendix B [Summary of Library Facilities], page 867, for an alphabetical list of the functions and other symbols provided by the library. This list also states which standards each function or symbol comes from.

1.2.1 ISO CThe GNU C library is compatible with the C standard adopted by the American National Standards Institute (ANSI): American National Standard X3.159-1989ANSI C and later by the International Standardization Organization (ISO): ISO/IEC 9899:1990, Programming languagesC. We here refer to the standard as ISO C since this is the more general standard in respect of ratication. The header les and library facilities that make up the GNU library are a superset of those specied by the ISO C standard. If you are concerned about strict adherence to the ISO C standard, you should use the -ansi option when you compile your programs with the GNU C compiler. This tells the compiler to dene only ISO standard features from the library header les, unless you explicitly ask for additional features. See Section 1.3.4 [Feature Test Macros], page 7, for information on how to do this. Being able to restrict the library to include only ISO C features is important because ISO C puts limitations on what names can be dened by the library implementation, and the GNU extensions dont t these limitations. See Section 1.3.3 [Reserved Names], page 5, for more information about these restrictions. This manual does not attempt to give you complete details on the dierences between ISO C and older dialects. It gives advice on how to write programs to work portably under multiple C dialects, but does not aim for completeness.

1.2.2 POSIX (The Portable Operating System Interface)The GNU library is also compatible with the ISO POSIX family of standards, known more formally as the Portable Operating System Interface for Computer Environments (ISO/IEC 9945). They were also published as ANSI/IEEE Std 1003. POSIX is derived mostly from various versions of the Unix operating system. The library facilities specied by the POSIX standards are a superset of those required by ISO C; POSIX species additional features for ISO C functions, as well as specifying new additional functions. In general, the additional requirements and functionality dened by the POSIX standards are aimed at providing lower-level support for a particular kind of operating system environment, rather than general programming language support which can run in many diverse operating system environments. The GNU C library implements all of the functions specied in ISO/IEC 9945-1:1996, the POSIX System Application Program Interface, commonly referred to as POSIX.1. The primary extensions to the ISO C facilities specied by this standard include le system interface primitives (see Chapter 14 [File System Interface], page 369), device-specic terminal control functions (see Chapter 17 [Low-Level Terminal Interface], page 465), and process control functions (see Chapter 26 [Processes], page 729). Some facilities from ISO/IEC 9945-2:1993, the POSIX Shell and Utilities standard (POSIX.2) are also implemented in the GNU library. These include utilities for dealing with regular expressions and other pattern matching facilities (see Chapter 10 [Pattern Matching], page 219).

Chapter 1: Introduction

3

1.2.3 Berkeley UnixThe GNU C library denes facilities from some versions of Unix which are not formally standardized, specically from the 4.2 BSD, 4.3 BSD, and 4.4 BSD Unix systems (also known as Berkeley Unix) and from SunOS (a popular 4.2 BSD derivative that includes some Unix System V functionality). These systems support most of the ISO C and POSIX facilities, and 4.4 BSD and newer releases of SunOS in fact support them all. The BSD facilities include symbolic links (see Section 14.5 [Symbolic Links], page 383), the select function (see Section 13.8 [Waiting for Input or Output], page 337), the BSD signal functions (see Section 24.10 [BSD Signal Handling], page 680), and sockets (see Chapter 16 [Sockets], page 417).

1.2.4 SVID (The System V Interface Description)The System V Interface Description (SVID) is a document describing the AT&T Unix System V operating system. It is to some extent a superset of the POSIX standard (see Section 1.2.2 [POSIX (The Portable Operating System Interface)], page 2). The GNU C library denes most of the facilities required by the SVID that are not also required by the ISO C or POSIX standards, for compatibility with System V Unix and other Unix systems (such as SunOS) which include these facilities. However, many of the more obscure and less generally useful facilities required by the SVID are not included. (In fact, Unix System V itself does not provide them all.) The supported facilities from System V include the methods for inter-process communication and shared memory, the hsearch and drand48 families of functions, fmtmsg and several of the mathematical functions.

1.2.5 XPG (The X/Open Portability Guide)The X/Open Portability Guide, published by the X/Open Company, Ltd., is a more general standard than POSIX. X/Open owns the Unix copyright and the XPG species the requirements for systems which are intended to be a Unix system. The GNU C library complies to the X/Open Portability Guide, Issue 4.2, with all extensions common to XSI (X/Open System Interface) compliant systems and also all X/Open UNIX extensions. The additions on top of POSIX are mainly derived from functionality available in System V and BSD systems. Some of the really bad mistakes in System V systems were corrected, though. Since fullling the XPG standard with the Unix extensions is a precondition for getting the Unix brand chances are good that the functionality is available on commercial systems.

1.3 Using the LibraryThis section describes some of the practical issues involved in using the GNU C library.

4

The GNU C Library

1.3.1 Header FilesLibraries for use by C programs really consist of two parts: header les that dene types and macros and declare variables and functions; and the actual library or archive that contains the denitions of the variables and functions. (Recall that in C, a declaration merely provides information that a function or variable exists and gives its type. For a function declaration, information about the types of its arguments might be provided as well. The purpose of declarations is to allow the compiler to correctly process references to the declared variables and functions. A denition, on the other hand, actually allocates storage for a variable or says what a function does.) In order to use the facilities in the GNU C library, you should be sure that your program source les include the appropriate header les. This is so that the compiler has declarations of these facilities available and can correctly process references to them. Once your program has been compiled, the linker resolves these references to the actual denitions provided in the archive le. Header les are included into a program source le by the #include preprocessor directive. The C language supports two forms of this directive; the rst, #include "header" is typically used to include a header le header that you write yourself; this would contain denitions and declarations describing the interfaces between the dierent parts of your particular application. By contrast, #include is typically used to include a header le file.h that contains denitions and declarations for a standard library. This le would normally be installed in a standard place by your system administrator. You should use this second form for the C library header les. Typically, #include directives are placed at the top of the C source le, before any other code. If you begin your source les with some comments explaining what the code in the le does (a good idea), put the #include directives immediately afterwards, following the feature test macro denition (see Section 1.3.4 [Feature Test Macros], page 7). For more information about the use of header les and #include directives, see section Header Files in The GNU C Preprocessor Manual. The GNU C library provides several header les, each of which contains the type and macro denitions and variable and function declarations for a group of related facilities. This means that your programs may need to include several header les, depending on exactly which facilities you are using. Some library header les include other library header les automatically. However, as a matter of programming style, you should not rely on this; it is better to explicitly include all the header les required for the library facilities you are using. The GNU C library header les have been written in such a way that it doesnt matter if a header le is accidentally included more than once; including a header le a second time has no eect. Likewise, if your program needs to include multiple header les, the order in which they are included doesnt matter. Compatibility Note: Inclusion of standard header les in any order and any number of times works in any ISO C implementation. However, this has traditionally not been the case in many older C implementations.

Chapter 1: Introduction

5

Strictly speaking, you dont have to include a header le to use a function it declares; you could declare the function explicitly yourself, according to the specications in this manual. But it is usually better to include the header le because it may dene types and macros that are not otherwise available and because it may dene more ecient macro replacements for some functions. It is also a sure way to have the correct declaration.

1.3.2 Macro Denitions of FunctionsIf we describe something as a function in this manual, it may have a macro denition as well. This normally has no eect on how your program runsthe macro denition does the same thing as the function would. In particular, macro equivalents for library functions evaluate arguments exactly once, in the same way that a function call would. The main reason for these macro denitions is that sometimes they can produce an inline expansion that is considerably faster than an actual function call. Taking the address of a library function works even if it is also dened as a macro. This is because, in this context, the name of the function isnt followed by the left parenthesis that is syntactically necessary to recognize a macro call. You might occasionally want to avoid using the macro denition of a functionperhaps to make your program easier to debug. There are two ways you can do this: You can avoid a macro denition in a specic use by enclosing the name of the function in parentheses. This works because the name of the function doesnt appear in a syntactic context where it is recognizable as a macro call. You can suppress any macro denition for a whole source le by using the #undef preprocessor directive, unless otherwise stated explicitly in the description of that facility. For example, suppose the header le stdlib.h declares a function named abs with extern int abs (int); and also provides a macro denition for abs. Then, in: #include int f (int *i) { return abs (++*i); } the reference to abs might refer to either a macro or a function. On the other hand, in each of the following examples the reference is to a function and not a macro. #include int g (int *i) { return (abs) (++*i); } #undef abs int h (int *i) { return abs (++*i); } Since macro denitions that double for a function behave in exactly the same way as the actual function version, there is usually no need for any of these methods. In fact, removing macro denitions usually just makes your program slower.

1.3.3 Reserved NamesThe names of all library types, macros, variables and functions that come from the ISO C standard are reserved unconditionally; your program may not redene these names.

6

The GNU C Library

All other library names are reserved if your program explicitly includes the header le that denes or declares them. There are several reasons for these restrictions: Other people reading your code could get very confused if you were using a function named exit to do something completely dierent from what the standard exit function does, for example. Preventing this situation helps to make your programs easier to understand and contributes to modularity and maintainability. It avoids the possibility of a user accidentally redening a library function that is called by other library functions. If redenition were allowed, those other functions would not work properly. It allows the compiler to do whatever special optimizations it pleases on calls to these functions, without the possibility that they may have been redened by the user. Some library facilities, such as those for dealing with variadic arguments (see Section A.2 [Variadic Functions], page 850) and non-local exits (see Chapter 23 [Non-Local Exits], page 625), actually require a considerable amount of cooperation on the part of the C compiler, and with respect to the implementation, it might be easier for the compiler to treat these as built-in parts of the language. In addition to the names documented in this manual, reserved names include all external identiers (global functions and variables) that begin with an underscore (_) and all identiers regardless of use that begin with either two underscores or an underscore followed by a capital letter are reserved names. This is so that the library and header les can dene functions, variables, and macros for internal purposes without risk of conict with names in user programs. Some additional classes of identier names are reserved for future extensions to the C language or the POSIX.1 environment. While using these names for your own purposes right now might not cause a problem, they do raise the possibility of conict with future versions of the C or POSIX standards, so you should avoid these names. Names beginning with a capital E followed a digit or uppercase letter may be used for additional error code names. See Chapter 2 [Error Reporting], page 15. Names that begin with either is or to followed by a lowercase letter may be used for additional character testing and conversion functions. See Chapter 4 [Character Handling], page 69. Names that begin with LC_ followed by an uppercase letter may be used for additional macros specifying locale attributes. See Chapter 7 [Locales and Internationalization], page 163. Names of all existing mathematics functions (see Chapter 19 [Mathematics], page 501) suxed with f or l are reserved for corresponding functions that operate on float and long double arguments, respectively. Names that begin with SIG followed by an uppercase letter are reserved for additional signal names. See Section 24.2 [Standard Signals], page 637. Names that begin with SIG_ followed by an uppercase letter are reserved for additional signal actions. See Section 24.3.1 [Basic Signal Handling], page 646. Names beginning with str, mem, or wcs followed by a lowercase letter are reserved for additional string and array functions. See Chapter 5 [String and Array Utilities], page 79.

Chapter 1: Introduction

7

Names that end with _t are reserved for additional type names. In addition, some individual header les reserve names beyond those that they actually dene. You only need to worry about these restrictions if your program includes that particular header le. The header le dirent.h reserves names prexed with d_. The header le fcntl.h reserves names prexed with l_, F_, O_, and S_. The header le grp.h reserves names prexed with gr_. The header le limits.h reserves names suxed with _MAX. The header le pwd.h reserves names prexed with pw_. The header le signal.h reserves names prexed with sa_ and SA_. The header le sys/stat.h reserves names prexed with st_ and S_. The header le sys/times.h reserves names prexed with tms_. The header le termios.h reserves names prexed with c_, V, I, O, and TC; and names prexed with B followed by a digit.

1.3.4 Feature Test MacrosThe exact set of features available when you compile a source le is controlled by which feature test macros you dene. If you compile your programs using gcc -ansi, you get only the ISO C library features, unless you explicitly request additional features by dening one or more of the feature macros. See section GNU CC Command Options in The GNU CC Manual, for more information about GCC options. You should dene these macros by using #define preprocessor directives at the top of your source code les. These directives must come before any #include of a system header le. It is best to make them the very rst thing in the le, preceded only by comments. You could also use the -D option to GCC, but its better if you make the source les indicate their own meaning in a self-contained way. This system exists to allow the library to conform to multiple standards. Although the dierent standards are often described as supersets of each other, they are usually incompatible because larger standards require functions with names that smaller ones reserve to the user program. This is not mere pedantry it has been a problem in practice. For instance, some non-GNU programs dene functions named getline that have nothing to do with this librarys getline. They would not be compilable if all features were enabled indiscriminately. This should not be used to verify that a program conforms to a limited standard. It is insucient for this purpose, as it will not protect you from including header les outside the standard, or relying on semantics undened within the standard.

POSIX SOURCE

Macro If you dene this macro, then the functionality from the POSIX.1 standard (IEEE Standard 1003.1) is available, as well as all of the ISO C facilities. The state of _POSIX_SOURCE is irrelevant if you dene the macro _POSIX_C_SOURCE to a positive integer.

8

The GNU C Library

POSIX C SOURCE

Macro Dene this macro to a positive integer to control which POSIX functionality is made available. The greater the value of this macro, the more functionality is made available. If you dene this macro to a value greater than or equal to 1, then the functionality from the 1990 edition of the POSIX.1 standard (IEEE Standard 1003.1-1990) is made available. If you dene this macro to a value greater than or equal to 2, then the functionality from the 1992 edition of the POSIX.2 standard (IEEE Standard 1003.2-1992) is made available. If you dene this macro to a value greater than or equal to 199309L, then the functionality from the 1993 edition of the POSIX.1b standard (IEEE Standard 1003.1b-1993) is made available. Greater values for _POSIX_C_SOURCE will enable future extensions. The POSIX standards process will dene these values as necessary, and the GNU C Library should support them some time after they become standardized. The 1996 edition of POSIX.1 (ISO/IEC 9945-1: 1996) states that if you dene _POSIX_C_SOURCE to a value greater than or equal to 199506L, then the functionality from the 1996 edition is made available. Macro If you dene this macro, functionality derived from 4.3 BSD Unix is included as well as the ISO C, POSIX.1, and POSIX.2 material. Some of the features derived from 4.3 BSD Unix conict with the corresponding features specied by the POSIX.1 standard. If this macro is dened, the 4.3 BSD denitions take precedence over the POSIX denitions. Due to the nature of some of the conicts between 4.3 BSD and POSIX.1, you need to use a special BSD compatibility library when linking programs compiled for BSD compatibility. This is because some functions must be dened in two dierent ways, one of them in the normal C library, and one of them in the compatibility library. If your program denes _BSD_SOURCE, you must give the option -lbsd-compat to the compiler or linker when linking the program, to tell it to nd functions in this special compatibility library before looking for them in the normal C library. Macro If you dene this macro, functionality derived from SVID is included as well as the ISO C, POSIX.1, POSIX.2, and X/Open material.

BSD SOURCE

SVID SOURCE

XOPEN SOURCE XOPEN SOURCE EXTENDED

Macro Macro If you dene this macro, functionality described in the X/Open Portability Guide is included. This is a superset of the POSIX.1 and POSIX.2 functionality and in fact _POSIX_SOURCE and _POSIX_C_SOURCE are automatically dened. As the unication of all Unices, functionality only available in BSD and SVID is also included.

Chapter 1: Introduction

9

If the macro _XOPEN_SOURCE_EXTENDED is also dened, even more functionality is available. The extra functions will make all functions available which are necessary for the X/Open Unix brand. If the macro _XOPEN_SOURCE has the value 500 this includes all functionality described so far plus some new denitions from the Single Unix Specication, version 2.

LARGEFILE SOURCE

Macro If this macro is dened some extra functions are available which rectify a few shortcomings in all previous standards. Specically, the functions fseeko and ftello are available. Without these functions the dierence between the ISO C interface (fseek, ftell) and the low-level POSIX interface (lseek) would lead to problems.

This macro was introduced as part of the Large File Support extension (LFS).

LARGEFILE64 SOURCE

Macro If you dene this macro an additional set of functions is made available which enables 32 bit systems to use les of sizes beyond the usual limit of 2GB. This interface is not available if the system does not support les that large. On systems where the natural le size limit is greater than 2GB (i.e., on 64 bit systems) the new functions are identical to the replaced functions.

The new functionality is made available by a new set of types and functions which replace the existing ones. The names of these new objects contain 64 to indicate the intention, e.g., off_t vs. off64_t and fseeko vs. fseeko64. This macro was introduced as part of the Large File Support extension (LFS). It is a transition interface for the period when 64 bit osets are not generally used (see _FILE_OFFSET_BITS).

FILE OFFSET BITS

Macro This macro determines which le system interface shall be used,