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.21

This file documents the GNU C Library.

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

Copyright c 19932015 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.

iShort Contents

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

3 Virtual Memory Allocation And Paging . . . . . . . . . . . . . . . . . . 394 Character Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775 String and Array Utilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876 Character Set Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1277 Locales and Internationalization . . . . . . . . . . . . . . . . . . . . . . . 169

8 Message Translation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1889 Searching and Sorting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

10 Pattern Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22211 Input/Output Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

12 Input/Output on Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24713 Low-Level Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32214 File System Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

15 Pipes and FIFOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42216 Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42717 Low-Level Terminal Interface . . . . . . . . . . . . . . . . . . . . . . . . . . 47518 Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502

19 Mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 509

20 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55721 Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593

22 Resource Usage And Limitation . . . . . . . . . . . . . . . . . . . . . . . . 62823 Non-Local Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650

24 Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65925 The Basic Program/System Interface . . . . . . . . . . . . . . . . . . . 70326 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74727 Inter-Process Communication . . . . . . . . . . . . . . . . . . . . . . . . . 75928 Job Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76129 System Databases and Name Service Switch . . . . . . . . . . . . . . 78030 Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789

31 System Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81932 System Configuration Parameters . . . . . . . . . . . . . . . . . . . . . . 83633 DES Encryption and Password Handling . . . . . . . . . . . . . . . . 857

ii

34 Debugging support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86435 POSIX Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86736 Internal probes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 869A C Language Facilities in the Library . . . . . . . . . . . . . . . . . . . . 875B Summary of Library Facilities . . . . . . . . . . . . . . . . . . . . . . . . . 890C Installing the GNU C Library . . . . . . . . . . . . . . . . . . . . . . . . . 993

D Library Maintenance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001E Platform-specific facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008F Contributors to the GNU C Library . . . . . . . . . . . . . . . . . . . 1010G Free Software Needs Free Documentation . . . . . . . . . . . . . . . 1015H GNU Lesser General Public License . . . . . . . . . . . . . . . . . . . 1017

I GNU Free Documentation License . . . . . . . . . . . . . . . . . . . . . 1026Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034Type Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044Function and Macro Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1047

Variable and Constant Macro Index . . . . . . . . . . . . . . . . . . . . . . . 1059Program and File Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1069

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

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

3 Virtual Memory Allocation And Paging . . . . . 393.1 Process Memory Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393.2 Allocating Storage For Program Data . . . . . . . . . . . . . . . . . . . . . . . . . 40

3.2.1 Memory Allocation in C Programs . . . . . . . . . . . . . . . . . . . . . . . . 413.2.1.1 Dynamic Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . 41

3.2.2 Unconstrained Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.2.2.1 Basic Memory Allocation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.2.2.2 Examples of malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.2.2.3 Freeing Memory Allocated with malloc . . . . . . . . . . . . . . 433.2.2.4 Changing the Size of a Block . . . . . . . . . . . . . . . . . . . . . . . . 443.2.2.5 Allocating Cleared Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453.2.2.6 Efficiency Considerations for malloc . . . . . . . . . . . . . . . . . 453.2.2.7 Allocating Aligned Memory Blocks . . . . . . . . . . . . . . . . . . 463.2.2.8 Malloc Tunable Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 473.2.2.9 Heap Consistency Checking . . . . . . . . . . . . . . . . . . . . . . . . . . 483.2.2.10 Memory Allocation Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . 503.2.2.11 Statistics for Memory Allocation with malloc . . . . . . . 523.2.2.12 Summary of malloc-Related Functions . . . . . . . . . . . . . 53

iv

3.2.3 Allocation Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543.2.3.1 How to install the tracing functionality . . . . . . . . . . . . . . 543.2.3.2 Example program excerpts . . . . . . . . . . . . . . . . . . . . . . . . . . 553.2.3.3 Some more or less clever ideas . . . . . . . . . . . . . . . . . . . . . . . 563.2.3.4 Interpreting the traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

3.2.4 Obstacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583.2.4.1 Creating Obstacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583.2.4.2 Preparing for Using Obstacks . . . . . . . . . . . . . . . . . . . . . . . . 593.2.4.3 Allocation in an Obstack . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603.2.4.4 Freeing Objects in an Obstack . . . . . . . . . . . . . . . . . . . . . . . 613.2.4.5 Obstack Functions and Macros . . . . . . . . . . . . . . . . . . . . . . 613.2.4.6 Growing Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623.2.4.7 Extra Fast Growing Objects . . . . . . . . . . . . . . . . . . . . . . . . . 643.2.4.8 Status of an Obstack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 663.2.4.9 Alignment of Data in Obstacks . . . . . . . . . . . . . . . . . . . . . . 673.2.4.10 Obstack Chunks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 673.2.4.11 Summary of Obstack Functions . . . . . . . . . . . . . . . . . . . . . 68

3.2.5 Automatic Storage with Variable Size . . . . . . . . . . . . . . . . . . . . . 693.2.5.1 alloca Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703.2.5.2 Advantages of alloca . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703.2.5.3 Disadvantages of alloca . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713.2.5.4 GNU C Variable-Size Arrays . . . . . . . . . . . . . . . . . . . . . . . . . 71

3.3 Resizing the Data Segment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723.4 Locking Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72

3.4.1 Why Lock Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733.4.2 Locked Memory Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733.4.3 Functions To Lock And Unlock Pages . . . . . . . . . . . . . . . . . . . . 74

4 Character Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 774.1 Classification of Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774.2 Case Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 794.3 Character class determination for wide characters . . . . . . . . . . . . . . 804.4 Notes on using the wide character classes . . . . . . . . . . . . . . . . . . . . . . 844.5 Mapping of wide characters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

5 String and Array Utilities . . . . . . . . . . . . . . . . . . . . 875.1 Representation of Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875.2 String and Array Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 885.3 String Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 895.4 Copying and Concatenation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 915.5 String/Array Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1025.6 Collation Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1065.7 Search Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110

5.7.1 Compatibility String Search Functions . . . . . . . . . . . . . . . . . . . 1155.8 Finding Tokens in a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1155.9 strfry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1205.10 Trivial Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

v5.11 Encode Binary Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1215.12 Argz and Envz Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

5.12.1 Argz Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1235.12.2 Envz Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

6 Character Set Handling . . . . . . . . . . . . . . . . . . . . . 1276.1 Introduction to Extended Characters . . . . . . . . . . . . . . . . . . . . . . . . . 1276.2 Overview about Character Handling Functions . . . . . . . . . . . . . . . 1316.3 Restartable Multibyte Conversion Functions . . . . . . . . . . . . . . . . . . 131

6.3.1 Selecting the conversion and its properties . . . . . . . . . . . . . . . 1316.3.2 Representing the state of the conversion . . . . . . . . . . . . . . . . . 1326.3.3 Converting Single Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1336.3.4 Converting Multibyte and Wide Character Strings . . . . . . . 1396.3.5 A Complete Multibyte Conversion Example . . . . . . . . . . . . . 143

6.4 Non-reentrant Conversion Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 1446.4.1 Non-reentrant Conversion of Single Characters . . . . . . . . . . . 1446.4.2 Non-reentrant Conversion of Strings . . . . . . . . . . . . . . . . . . . . . 1466.4.3 States in Non-reentrant Functions . . . . . . . . . . . . . . . . . . . . . . . 147

6.5 Generic Charset Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1486.5.1 Generic Character Set Conversion Interface . . . . . . . . . . . . . . 1496.5.2 A complete iconv example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1526.5.3 Some Details about other iconv Implementations . . . . . . . . 1546.5.4 The iconv Implementation in the GNU C Library . . . . . . . 155

6.5.4.1 Format of gconv-modules files . . . . . . . . . . . . . . . . . . . . . 1566.5.4.2 Finding the conversion path in iconv . . . . . . . . . . . . . . . 1576.5.4.3 iconv module data structures . . . . . . . . . . . . . . . . . . . . . . 1586.5.4.4 iconv module interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

7 Locales and Internationalization . . . . . . . . . . . . 1697.1 What Effects a Locale Has . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1697.2 Choosing a Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1707.3 Locale Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1707.4 How Programs Set the Locale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1717.5 Standard Locales . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1737.6 Locale Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1737.7 Accessing Locale Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

7.7.1 localeconv: It is portable but . . . . . . . . . . . . . . . . . . . . . . . . . 1757.7.1.1 Generic Numeric Formatting Parameters . . . . . . . . . . . . 1757.7.1.2 Printing the Currency Symbol . . . . . . . . . . . . . . . . . . . . . . 1767.7.1.3 Printing the Sign of a Monetary Amount . . . . . . . . . . . 178

7.7.2 Pinpoint Access to Locale Data . . . . . . . . . . . . . . . . . . . . . . . . . 1787.8 A dedicated function to format numbers . . . . . . . . . . . . . . . . . . . . . . 1847.9 Yes-or-No Questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187

vi

8 Message Translation . . . . . . . . . . . . . . . . . . . . . . . . . 1888.1 X/Open Message Catalog Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 188

8.1.1 The catgets function family . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1888.1.2 Format of the message catalog files . . . . . . . . . . . . . . . . . . . . . . 1918.1.3 Generate Message Catalogs files . . . . . . . . . . . . . . . . . . . . . . . . . 1938.1.4 How to use the catgets interface . . . . . . . . . . . . . . . . . . . . . . . . 194

8.1.4.1 Not using symbolic names . . . . . . . . . . . . . . . . . . . . . . . . . . 1958.1.4.2 Using symbolic names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1958.1.4.3 How does to this allow to develop . . . . . . . . . . . . . . . . . . 196

8.2 The Uniforum approach to Message Translation . . . . . . . . . . . . . . 1978.2.1 The gettext family of functions . . . . . . . . . . . . . . . . . . . . . . . . . 197

8.2.1.1 What has to be done to translate a message? . . . . . . . 1988.2.1.2 How to determine which catalog to be used . . . . . . . . . 2008.2.1.3 Additional functions for more complicated situations

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2028.2.1.4 How to specify the output character set gettext uses

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2068.2.1.5 How to use gettext in GUI programs . . . . . . . . . . . . . . 2078.2.1.6 User influence on gettext . . . . . . . . . . . . . . . . . . . . . . . . . . 208

8.2.2 Programs to handle message catalogs for gettext . . . . . . . 211

9 Searching and Sorting . . . . . . . . . . . . . . . . . . . . . . . 2129.1 Defining the Comparison Function . . . . . . . . . . . . . . . . . . . . . . . . . . . 2129.2 Array Search Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2129.3 Array Sort Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2139.4 Searching and Sorting Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2149.5 The hsearch function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2169.6 The tsearch function. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

10 Pattern Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . 22210.1 Wildcard Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22210.2 Globbing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

10.2.1 Calling glob . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22310.2.2 Flags for Globbing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22710.2.3 More Flags for Globbing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 228

10.3 Regular Expression Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23010.3.1 POSIX Regular Expression Compilation . . . . . . . . . . . . . . . . 23110.3.2 Flags for POSIX Regular Expressions . . . . . . . . . . . . . . . . . . 23210.3.3 Matching a Compiled POSIX Regular Expression . . . . . . . 23310.3.4 Match Results with Subexpressions . . . . . . . . . . . . . . . . . . . . . 23410.3.5 Complications in Subexpression Matching . . . . . . . . . . . . . . 23410.3.6 POSIX Regexp Matching Cleanup . . . . . . . . . . . . . . . . . . . . . . 235

10.4 Shell-Style Word Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23610.4.1 The Stages of Word Expansion . . . . . . . . . . . . . . . . . . . . . . . . . 23610.4.2 Calling wordexp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23710.4.3 Flags for Word Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23810.4.4 wordexp Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

vii

10.4.5 Details of Tilde Expansion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24010.4.6 Details of Variable Substitution . . . . . . . . . . . . . . . . . . . . . . . . 240

11 Input/Output Overview . . . . . . . . . . . . . . . . . . . . 24211.1 Input/Output Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242

11.1.1 Streams and File Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . 24211.1.2 File Position . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 243

11.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24411.2.1 Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24411.2.2 File Name Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24511.2.3 File Name Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24511.2.4 Portability of File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 246

12 Input/Output on Streams . . . . . . . . . . . . . . . . . . 24712.1 Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24712.2 Standard Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24712.3 Opening Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24812.4 Closing Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25212.5 Streams and Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25312.6 Streams in Internationalized Applications . . . . . . . . . . . . . . . . . . . 25612.7 Simple Output by Characters or Lines . . . . . . . . . . . . . . . . . . . . . . 25812.8 Character Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26112.9 Line-Oriented Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26312.10 Unreading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266

12.10.1 What Unreading Means . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26612.10.2 Using ungetc To Do Unreading . . . . . . . . . . . . . . . . . . . . . . . 266

12.11 Block Input/Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26712.12 Formatted Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

12.12.1 Formatted Output Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26912.12.2 Output Conversion Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27012.12.3 Table of Output Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . 27112.12.4 Integer Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27212.12.5 Floating-Point Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27412.12.6 Other Output Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27612.12.7 Formatted Output Functions . . . . . . . . . . . . . . . . . . . . . . . . . . 27712.12.8 Dynamically Allocating Formatted Output . . . . . . . . . . . . 28012.12.9 Variable Arguments Output Functions . . . . . . . . . . . . . . . . 28012.12.10 Parsing a Template String . . . . . . . . . . . . . . . . . . . . . . . . . . . 28312.12.11 Example of Parsing a Template String . . . . . . . . . . . . . . . 284

12.13 Customizing printf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28512.13.1 Registering New Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . 28612.13.2 Conversion Specifier Options . . . . . . . . . . . . . . . . . . . . . . . . . . 28612.13.3 Defining the Output Handler . . . . . . . . . . . . . . . . . . . . . . . . . . 28812.13.4 printf Extension Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 28912.13.5 Predefined printf Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . 290

12.14 Formatted Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29112.14.1 Formatted Input Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291

viii

12.14.2 Input Conversion Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29212.14.3 Table of Input Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29312.14.4 Numeric Input Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . 29512.14.5 String Input Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29612.14.6 Dynamically Allocating String Conversions . . . . . . . . . . . . 29812.14.7 Other Input Conversions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29812.14.8 Formatted Input Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29912.14.9 Variable Arguments Input Functions . . . . . . . . . . . . . . . . . . 300

12.15 End-Of-File and Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30112.16 Recovering from errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30212.17 Text and Binary Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30312.18 File Positioning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30412.19 Portable File-Position Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 30612.20 Stream Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

12.20.1 Buffering Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30912.20.2 Flushing Buffers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30912.20.3 Controlling Which Kind of Buffering . . . . . . . . . . . . . . . . . . 310

12.21 Other Kinds of Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31312.21.1 String Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31312.21.2 Programming Your Own Custom Streams . . . . . . . . . . . . . 315

12.21.2.1 Custom Streams and Cookies . . . . . . . . . . . . . . . . . . . . 31512.21.2.2 Custom Stream Hook Functions . . . . . . . . . . . . . . . . . . 316

12.22 Formatted Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31712.22.1 Printing Formatted Messages . . . . . . . . . . . . . . . . . . . . . . . . . 31712.22.2 Adding Severity Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31912.22.3 How to use fmtmsg and addseverity . . . . . . . . . . . . . . . . . 320

13 Low-Level Input/Output . . . . . . . . . . . . . . . . . . . 32213.1 Opening and Closing Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32213.2 Input and Output Primitives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32513.3 Setting the File Position of a Descriptor . . . . . . . . . . . . . . . . . . . . . 33013.4 Descriptors and Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33213.5 Dangers of Mixing Streams and Descriptors . . . . . . . . . . . . . . . . . 333

13.5.1 Linked Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33313.5.2 Independent Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33413.5.3 Cleaning Streams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

13.6 Fast Scatter-Gather I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33513.7 Memory-mapped I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33613.8 Waiting for Input or Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34113.9 Synchronizing I/O operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34413.10 Perform I/O Operations in Parallel . . . . . . . . . . . . . . . . . . . . . . . . 345

13.10.1 Asynchronous Read and Write Operations . . . . . . . . . . . . . 34813.10.2 Getting the Status of AIO Operations . . . . . . . . . . . . . . . . . 35213.10.3 Getting into a Consistent State . . . . . . . . . . . . . . . . . . . . . . . 35313.10.4 Cancellation of AIO Operations . . . . . . . . . . . . . . . . . . . . . . . 35513.10.5 How to optimize the AIO implementation . . . . . . . . . . . . . 357

13.11 Control Operations on Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35813.12 Duplicating Descriptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359

ix

13.13 File Descriptor Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36013.14 File Status Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

13.14.1 File Access Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36213.14.2 Open-time Flags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36313.14.3 I/O Operating Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36513.14.4 Getting and Setting File Status Flags . . . . . . . . . . . . . . . . . 366

13.15 File Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36713.16 Open File Description Locks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37013.17 Open File Description Locks Example . . . . . . . . . . . . . . . . . . . . . . 37213.18 Interrupt-Driven Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37413.19 Generic I/O Control operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374

14 File System Interface . . . . . . . . . . . . . . . . . . . . . . . 37614.1 Working Directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37614.2 Accessing Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

14.2.1 Format of a Directory Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . 37814.2.2 Opening a Directory Stream . . . . . . . . . . . . . . . . . . . . . . . . . . . 38014.2.3 Reading and Closing a Directory Stream . . . . . . . . . . . . . . . 38114.2.4 Simple Program to List a Directory . . . . . . . . . . . . . . . . . . . . 38314.2.5 Random Access in a Directory Stream . . . . . . . . . . . . . . . . . . 38414.2.6 Scanning the Content of a Directory . . . . . . . . . . . . . . . . . . . . 38414.2.7 Simple Program to List a Directory, Mark II . . . . . . . . . . . 386

14.3 Working with Directory Trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38714.4 Hard Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39114.5 Symbolic Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39214.6 Deleting Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39514.7 Renaming Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39614.8 Creating Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39714.9 File Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398

14.9.1 The meaning of the File Attributes . . . . . . . . . . . . . . . . . . . . . 39814.9.2 Reading the Attributes of a File . . . . . . . . . . . . . . . . . . . . . . . . 40214.9.3 Testing the Type of a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40314.9.4 File Owner . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40514.9.5 The Mode Bits for Access Permission . . . . . . . . . . . . . . . . . . . 40714.9.6 How Your Access to a File is Decided . . . . . . . . . . . . . . . . . . 40814.9.7 Assigning File Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40914.9.8 Testing Permission to Access a File . . . . . . . . . . . . . . . . . . . . . 41114.9.9 File Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41214.9.10 File Size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

14.10 Making Special Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41714.11 Temporary Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 417

15 Pipes and FIFOs . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42215.1 Creating a Pipe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42215.2 Pipe to a Subprocess . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42415.3 FIFO Special Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42515.4 Atomicity of Pipe I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 426

x16 Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42716.1 Socket Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42716.2 Communication Styles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42816.3 Socket Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

16.3.1 Address Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42916.3.2 Setting the Address of a Socket . . . . . . . . . . . . . . . . . . . . . . . . 43116.3.3 Reading the Address of a Socket . . . . . . . . . . . . . . . . . . . . . . . 431

16.4 Interface Naming . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43216.5 The Local Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

16.5.1 Local Namespace Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43316.5.2 Details of Local Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43316.5.3 Example of Local-Namespace Sockets . . . . . . . . . . . . . . . . . . 434

16.6 The Internet Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43516.6.1 Internet Socket Address Formats . . . . . . . . . . . . . . . . . . . . . . . 43616.6.2 Host Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437

16.6.2.1 Internet Host Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . 43716.6.2.2 Host Address Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . 43816.6.2.3 Host Address Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . 43916.6.2.4 Host Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

16.6.3 Internet Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44516.6.4 The Services Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44616.6.5 Byte Order Conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44716.6.6 Protocols Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44816.6.7 Internet Socket Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

16.7 Other Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45116.8 Opening and Closing Sockets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

16.8.1 Creating a Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45116.8.2 Closing a Socket . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45216.8.3 Socket Pairs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 453

16.9 Using Sockets with Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45316.9.1 Making a Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45416.9.2 Listening for Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45516.9.3 Accepting Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45516.9.4 Who is Connected to Me? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45716.9.5 Transferring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 457

16.9.5.1 Sending Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45716.9.5.2 Receiving Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45816.9.5.3 Socket Data Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 459

16.9.6 Byte Stream Socket Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 45916.9.7 Byte Stream Connection Server Example . . . . . . . . . . . . . . . 46016.9.8 Out-of-Band Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 462

16.10 Datagram Socket Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46516.10.1 Sending Datagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46516.10.2 Receiving Datagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46616.10.3 Datagram Socket Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46716.10.4 Example of Reading Datagrams . . . . . . . . . . . . . . . . . . . . . . . 468

16.11 The inetd Daemon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46916.11.1 inetd Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469

xi

16.11.2 Configuring inetd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46916.12 Socket Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470

16.12.1 Socket Option Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47016.12.2 Socket-Level Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 471

16.13 Networks Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 473

17 Low-Level Terminal Interface . . . . . . . . . . . . . . 47517.1 Identifying Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47517.2 I/O Queues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47617.3 Two Styles of Input: Canonical or Not . . . . . . . . . . . . . . . . . . . . . . 47617.4 Terminal Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 477

17.4.1 Terminal Mode Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47717.4.2 Terminal Mode Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47817.4.3 Setting Terminal Modes Properly . . . . . . . . . . . . . . . . . . . . . . 47917.4.4 Input Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48017.4.5 Output Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48217.4.6 Control Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48317.4.7 Local Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48417.4.8 Line Speed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48717.4.9 Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 488

17.4.9.1 Characters for Input Editing . . . . . . . . . . . . . . . . . . . . . . 48817.4.9.2 Characters that Cause Signals . . . . . . . . . . . . . . . . . . . . . 49017.4.9.3 Special Characters for Flow Control . . . . . . . . . . . . . . . 49117.4.9.4 Other Special Characters . . . . . . . . . . . . . . . . . . . . . . . . . . 492

17.4.10 Noncanonical Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49217.5 BSD Terminal Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49417.6 Line Control Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49517.7 Noncanonical Mode Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49717.8 Pseudo-Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 498

17.8.1 Allocating Pseudo-Terminals . . . . . . . . . . . . . . . . . . . . . . . . . . . 49817.8.2 Opening a Pseudo-Terminal Pair . . . . . . . . . . . . . . . . . . . . . . . 500

18 Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50218.1 Overview of Syslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50218.2 Submitting Syslog Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 503

18.2.1 openlog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50318.2.2 syslog, vsyslog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50518.2.3 closelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50718.2.4 setlogmask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50818.2.5 Syslog Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508

xii

19 Mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50919.1 Predefined Mathematical Constants . . . . . . . . . . . . . . . . . . . . . . . . . 50919.2 Trigonometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51019.3 Inverse Trigonometric Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51219.4 Exponentiation and Logarithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51319.5 Hyperbolic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51819.6 Special Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52019.7 Known Maximum Errors in Math Functions . . . . . . . . . . . . . . . . . 52319.8 Pseudo-Random Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547

19.8.1 ISO C Random Number Functions . . . . . . . . . . . . . . . . . . . . . 54819.8.2 BSD Random Number Functions . . . . . . . . . . . . . . . . . . . . . . . 54919.8.3 SVID Random Number Function . . . . . . . . . . . . . . . . . . . . . . . 551

19.9 Is Fast Code or Small Code preferred? . . . . . . . . . . . . . . . . . . . . . . 556

20 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . 55720.1 Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55720.2 Integer Division . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55820.3 Floating Point Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56020.4 Floating-Point Number Classification Functions . . . . . . . . . . . . . 56120.5 Errors in Floating-Point Calculations . . . . . . . . . . . . . . . . . . . . . . . . 563

20.5.1 FP Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56320.5.2 Infinity and NaN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56420.5.3 Examining the FPU status word . . . . . . . . . . . . . . . . . . . . . . . 56520.5.4 Error Reporting by Mathematical Functions . . . . . . . . . . . . 567

20.6 Rounding Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56820.7 Floating-Point Control Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56920.8 Arithmetic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

20.8.1 Absolute Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57220.8.2 Normalization Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57220.8.3 Rounding Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57420.8.4 Remainder Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57620.8.5 Setting and modifying single bits of FP values . . . . . . . . . . 57720.8.6 Floating-Point Comparison Functions . . . . . . . . . . . . . . . . . . 57820.8.7 Miscellaneous FP arithmetic functions . . . . . . . . . . . . . . . . . . 580

20.9 Complex Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58120.10 Projections, Conjugates, and Decomposing of Complex Numbers

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58120.11 Parsing of Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 582

20.11.1 Parsing of Integers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58320.11.2 Parsing of Floats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

20.12 Old-fashioned System V number-to-string functions . . . . . . . . 589

xiii

21 Date and Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59321.1 Time Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59321.2 Elapsed Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59321.3 Processor And CPU Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595

21.3.1 CPU Time Inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59521.3.2 Processor Time Inquiry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596

21.4 Calendar Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59721.4.1 Simple Calendar Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59721.4.2 High-Resolution Calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59821.4.3 Broken-down Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60021.4.4 High Accuracy Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60321.4.5 Formatting Calendar Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60621.4.6 Convert textual time and date information back . . . . . . . . 612

21.4.6.1 Interpret string according to given format . . . . . . . . . 61221.4.6.2 A More User-friendly Way to Parse Times and Dates

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61721.4.7 Specifying the Time Zone with TZ . . . . . . . . . . . . . . . . . . . . . . 62021.4.8 Functions and Variables for Time Zones . . . . . . . . . . . . . . . . 62221.4.9 Time Functions Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 623

21.5 Setting an Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62321.6 Sleeping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626

22 Resource Usage And Limitation . . . . . . . . . . . 62822.1 Resource Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62822.2 Limiting Resource Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63022.3 Process CPU Priority And Scheduling . . . . . . . . . . . . . . . . . . . . . . . 634

22.3.1 Absolute Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63522.3.1.1 Using Absolute Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . 635

22.3.2 Realtime Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63622.3.3 Basic Scheduling Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63722.3.4 Traditional Scheduling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640

22.3.4.1 Introduction To Traditional Scheduling . . . . . . . . . . . . 64022.3.4.2 Functions For Traditional Scheduling . . . . . . . . . . . . . . 642

22.3.5 Limiting execution to certain CPUs . . . . . . . . . . . . . . . . . . . . 64322.4 Querying memory available resources . . . . . . . . . . . . . . . . . . . . . . . . 646

22.4.1 Overview about traditional Unix memory handling . . . . . 64622.4.2 How to get information about the memory subsystem? . . 646

22.5 Learn about the processors available . . . . . . . . . . . . . . . . . . . . . . . . 648

23 Non-Local Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65023.1 Introduction to Non-Local Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65023.2 Details of Non-Local Exits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65123.3 Non-Local Exits and Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65223.4 Complete Context Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653

xiv

24 Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65924.1 Basic Concepts of Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

24.1.1 Some Kinds of Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65924.1.2 Concepts of Signal Generation . . . . . . . . . . . . . . . . . . . . . . . . . 65924.1.3 How Signals Are Delivered . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660

24.2 Standard Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66124.2.1 Program Error Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66124.2.2 Termination Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66424.2.3 Alarm Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66524.2.4 Asynchronous I/O Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66524.2.5 Job Control Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66624.2.6 Operation Error Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66724.2.7 Miscellaneous Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66824.2.8 Signal Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 669

24.3 Specifying Signal Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66924.3.1 Basic Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67024.3.2 Advanced Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67224.3.3 Interaction of signal and sigaction . . . . . . . . . . . . . . . . . . . 67324.3.4 sigaction Function Example . . . . . . . . . . . . . . . . . . . . . . . . . . 67324.3.5 Flags for sigaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67424.3.6 Initial Signal Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 675

24.4 Defining Signal Handlers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67624.4.1 Signal Handlers that Return . . . . . . . . . . . . . . . . . . . . . . . . . . . 67624.4.2 Handlers That Terminate the Process . . . . . . . . . . . . . . . . . . 67724.4.3 Nonlocal Control Transfer in Handlers . . . . . . . . . . . . . . . . . . 67824.4.4 Signals Arriving While a Handler Runs . . . . . . . . . . . . . . . . . 67924.4.5 Signals Close Together Merge into One . . . . . . . . . . . . . . . . . 67924.4.6 Signal Handling and Nonreentrant Functions . . . . . . . . . . . 68224.4.7 Atomic Data Access and Signal Handling . . . . . . . . . . . . . . . 683

24.4.7.1 Problems with Non-Atomic Access . . . . . . . . . . . . . . . . 68424.4.7.2 Atomic Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68424.4.7.3 Atomic Usage Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . 685

24.5 Primitives Interrupted by Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . 68524.6 Generating Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 686

24.6.1 Signaling Yourself . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68624.6.2 Signaling Another Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68724.6.3 Permission for using kill . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68824.6.4 Using kill for Communication . . . . . . . . . . . . . . . . . . . . . . . . . 689

24.7 Blocking Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69024.7.1 Why Blocking Signals is Useful . . . . . . . . . . . . . . . . . . . . . . . . . 69024.7.2 Signal Sets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69124.7.3 Process Signal Mask . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69224.7.4 Blocking to Test for Delivery of a Signal . . . . . . . . . . . . . . . . 69324.7.5 Blocking Signals for a Handler . . . . . . . . . . . . . . . . . . . . . . . . . 69424.7.6 Checking for Pending Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . 69524.7.7 Remembering a Signal to Act On Later . . . . . . . . . . . . . . . . 696

24.8 Waiting for a Signal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69724.8.1 Using pause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697

xv

24.8.2 Problems with pause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69824.8.3 Using sigsuspend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698

24.9 Using a Separate Signal Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69924.10 BSD Signal Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 701

25 The Basic Program/System Interface . . . . . 70325.1 Program Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703

25.1.1 Program Argument Syntax Conventions . . . . . . . . . . . . . . . . 70425.1.2 Parsing Program Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . 704

25.2 Parsing program options using getopt . . . . . . . . . . . . . . . . . . . . . . 70525.2.1 Using the getopt function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70525.2.2 Example of Parsing Arguments with getopt . . . . . . . . . . . . 70625.2.3 Parsing Long Options with getopt_long . . . . . . . . . . . . . . . 70825.2.4 Example of Parsing Long Options with getopt_long . . . 710

25.3 Parsing Program Options with Argp . . . . . . . . . . . . . . . . . . . . . . . . 71225.3.1 The argp_parse Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71225.3.2 Argp Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71325.3.3 Specifying Argp Parsers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71325.3.4 Specifying Options in an Argp Parser . . . . . . . . . . . . . . . . . . 714

25.3.4.1 Flags for Argp Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71525.3.5 Argp Parser Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716

25.3.5.1 Special Keys for Argp Parser Functions . . . . . . . . . . . . 71725.3.5.2 Argp Parsing State . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71925.3.5.3 Functions For Use in Argp Parsers . . . . . . . . . . . . . . . . . 720

25.3.6 Combining Multiple Argp Parsers . . . . . . . . . . . . . . . . . . . . . . 72225.3.7 Flags for argp_parse . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72225.3.8 Customizing Argp Help Output . . . . . . . . . . . . . . . . . . . . . . . . 723

25.3.8.1 Special Keys for Argp Help Filter Functions . . . . . . . 72325.3.9 The argp_help Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72425.3.10 Flags for the argp_help Function . . . . . . . . . . . . . . . . . . . . . 72425.3.11 Argp Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 725

25.3.11.1 A Minimal Program Using Argp . . . . . . . . . . . . . . . . . . 72525.3.11.2 A Program Using Argp with Only Default Options

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72625.3.11.3 A Program Using Argp with User Options . . . . . . . . 72725.3.11.4 A Program Using Multiple Combined Argp Parsers

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73025.3.12 Argp User Customization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733

25.3.12.1 Parsing of Suboptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73425.3.13 Parsing of Suboptions Example . . . . . . . . . . . . . . . . . . . . . . . 734

25.4 Environment Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73625.4.1 Environment Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73625.4.2 Standard Environment Variables . . . . . . . . . . . . . . . . . . . . . . . 739

25.5 Auxiliary Vector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74025.5.1 Definition of getauxval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741

25.6 System Calls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74125.7 Program Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 742

25.7.1 Normal Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 743

xvi

25.7.2 Exit Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74325.7.3 Cleanups on Exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74425.7.4 Aborting a Program . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74525.7.5 Termination Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 745

26 Processes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74726.1 Running a Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74726.2 Process Creation Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74826.3 Process Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74826.4 Creating a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74926.5 Executing a File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75026.6 Process Completion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75326.7 Process Completion Status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75526.8 BSD Process Wait Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75626.9 Process Creation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757

27 Inter-Process Communication . . . . . . . . . . . . . 75927.1 Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759

27.1.1 System V Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75927.1.2 POSIX Semaphores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 759

28 Job Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76128.1 Concepts of Job Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76128.2 Job Control is Optional . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76228.3 Controlling Terminal of a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . 76228.4 Access to the Controlling Terminal . . . . . . . . . . . . . . . . . . . . . . . . . . 76228.5 Orphaned Process Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76328.6 Implementing a Job Control Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . 763

28.6.1 Data Structures for the Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . 76428.6.2 Initializing the Shell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76528.6.3 Launching Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76628.6.4 Foreground and Background . . . . . . . . . . . . . . . . . . . . . . . . . . . 77028.6.5 Stopped and Terminated Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . 77128.6.6 Continuing Stopped Jobs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77428.6.7 The Missing Pieces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775

28.7 Functions for Job Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77628.7.1 Identifying the Controlling Terminal . . . . . . . . . . . . . . . . . . . . 77628.7.2 Process Group Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77628.7.3 Functions for Controlling Terminal Access . . . . . . . . . . . . . . 778

xvii

29 System Databases and Name Service Switch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780

29.1 NSS Basics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78029.2 The NSS Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 781

29.2.1 Services in the NSS configuration File . . . . . . . . . . . . . . . . . . 78129.2.2 Actions in the NSS configuration . . . . . . . . . . . . . . . . . . . . . . . 78229.2.3 Notes on the NSS Configuration File . . . . . . . . . . . . . . . . . . . 783

29.3 NSS Module Internals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78329.3.1 The Naming Scheme of the NSS Modules . . . . . . . . . . . . . . . 78329.3.2 The Interface of the Function in NSS Modules . . . . . . . . . . 784

29.4 Extending NSS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78629.4.1 Adding another Service to NSS . . . . . . . . . . . . . . . . . . . . . . . . . 78629.4.2 Internals of the NSS Module Functions . . . . . . . . . . . . . . . . . 787

30 Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . 78930.1 User and Group IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78930.2 The Persona of a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78930.3 Why Change the Persona of a Process? . . . . . . . . . . . . . . . . . . . . . 79030.4 How an Application Can Change Persona . . . . . . . . . . . . . . . . . . . 79030.5 Reading the Persona of a Process . . . . . . . . . . . . . . . . . . . . . . . . . . . 79130.6 Setting the User ID . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79230.7 Setting the Group IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79330.8 Enabling and Disabling Setuid Access . . . . . . . . . . . . . . . . . . . . . . . 79530.9 Setuid Program Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79630.10 Tips for Writing Setuid Programs . . . . . . . . . . . . . . . . . . . . . . . . . . 79830.11 Identifying Who Logged In . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79930.12 The User Accounting Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . 800

30.12.1 Manipulating the User Accounting Database . . . . . . . . . . 80030.12.2 XPG User Accounting Database Functions . . . . . . . . . . . . 80530.12.3 Logging In and Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 807

30.13 User Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80830.13.1 The Data Structure that Describes a User . . . . . . . . . . . . . 80830.13.2 Looking Up One User . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80930.13.3 Scanning the List of All Users . . . . . . . . . . . . . . . . . . . . . . . . . 81030.13.4 Writing a User Entry . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 811

30.14 Group Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81230.14.1 The Data Structure for a Group . . . . . . . . . . . . . . . . . . . . . . . 81230.14.2 Looking Up One Group . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81230.14.3 Scanning the List of All Groups . . . . . . . . . . . . . . . . . . . . . . . 813

30.15 User and Group Database Example . . . . . . . . . . . . . . . . . . . . . . . . 81530.16 Netgroup Database . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 816

30.16.1 Netgroup Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81630.16.2 Looking up one Netgroup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81630.16.3 Testing for Netgroup Membership . . . . . . . . . . . . . . . . . . . . . 818

xviii

31 System Management . . . . . . . . . . . . . . . . . . . . . . . 81931.1 Host Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81931.2 Platform Type Identification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82131.3 Controlling and Querying Mounts . . . . . . . . . . . . . . . . . . . . . . . . . . . 822

31.3.1 Mount Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82331.3.1.1 The fstab file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82331.3.1.2 The mtab file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82631.3.1.3 Other (Non-libc) Sources of Mount Information . . . . 829

31.3.2 Mount, Unmount, Remount . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82931.4 System Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 833

32 System Configuration Parameters . . . . . . . . . 83632.1 General Capacity Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83632.2 Overall System Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83732.3 Which Version of POSIX is Supported . . . . . . . . . . . . . . . . . . . . . . 83832.4 Using sysconf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 839

32.4.1 Definition of sysconf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83932.4.2 Constants for sysconf Parameters . . . . . . . . . . . . . . . . . . . . . 83932.4.3 Examples of sysconf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 846

32.5 Minimum Values for General Capacity Limits . . . . . . . . . . . . . . . 84732.6 Limits on File System Capacity . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84832.7 Optional Features in File Support . . . . . . . . . . . . . . . . . . . . . . . . . . . 84932.8 Minimum Values for File System Limits . . . . . . . . . . . . . . . . . . . . . 85032.9 Using pathconf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85132.10 Utility Program Capacity Limits . . . . . . . . . . . . . . . . . . . . . . . . . . . 85332.11 Minimum Values for Utility Limits . . . . . . . . . . . . . . . . . . . . . . . . . 85332.12 String-Valued Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 854

33 DES Encryption and Password Handling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 857

33.1 Legal Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85733.2 Reading Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85833.3 Encrypting Passwords . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85933.4 DES Encryption . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 861

34 Debugging support . . . . . . . . . . . . . . . . . . . . . . . . . 86434.1 Backtraces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 864

35 POSIX Threads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86735.1 Thread-specific Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86735.2 Non-POSIX Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 867

35.2.1 Setting Process-wide defaults for thread attributes . . . . . . 867

xix

36 Internal probes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86936.1 Memory Allocation Probes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86936.2 Mathematical Function Probes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87236.3 Non-local Goto Probes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 874

Appendix A C Language Facilities in theLibrary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 875

A.1 Explicitly Checking Internal Consistency . . . . . . . . . . . . . . . . . . . . . 875A.2 Variadic Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 876

A.2.1 Why Variadic Functions are Used . . . . . . . . . . . . . . . . . . . . . . . 876A.2.2 How Variadic Functions are Defined and Used . . . . . . . . . . . 877

A.2.2.1 Syntax for Variable Arguments . . . . . . . . . . . . . . . . . . . . . 877A.2.2.2 Receiving the Argument Values . . . . . . . . . . . . . . . . . . . . 878A.2.2.3 How Many Arguments Were Supplied . . . . . . . . . . . . . . 878A.2.2.4 Calling Variadic Functions . . . . . . . . . . . . . . . . . . . . . . . . . 879A.2.2.5 Argument Access Macros . . . . . . . . . . . . . . . . . . . . . . . . . . 879

A.2.3 Example of a Variadic Function . . . . . . . . . . . . . . . . . . . . . . . . . 881A.3 Null Pointer Constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 881A.4 Important Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882A.5 Data Type Measurements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 882

A.5.1 Computing the Width of an Integer Data Type . . . . . . . . . 882A.5.2 Range of an Integer Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 883A.5.3 Floating Type Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 884

A.5.3.1 Floating Point Representation Concepts . . . . . . . . . . . . 885A.5.3.2 Floating Point Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 886A.5.3.3 IEEE Floating Point . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 889

A.5.4 Structure Field Offset Measurement . . . . . . . . . . . . . . . . . . . . . 889

Appendix B Summary of Library Facilities. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 890

Appendix C Installing the GNU C Library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 993

C.1 Configuring and compiling the GNU C Library . . . . . . . . . . . . . . . 993C.2 Installing the C Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 997C.3 Recommended Tools for Compilation . . . . . . . . . . . . . . . . . . . . . . . . 998C.4 Specific advice for GNU/Linux systems . . . . . . . . . . . . . . . . . . . . . . 999C.5 Reporting Bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1000

Appendix D Library Maintenance . . . . . . . . . . 1001D.1 Adding New Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1001

D.1.1 Platform-specific types, macros and functions . . . . . . . . . . 1002D.2 Porting the GNU C Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1003

D.2.1 Layout of the sysdeps Directory Hierarchy . . . . . . . . . . . . 1005D.2.2 Porting the GNU C Library to Unix Systems . . . . . . . . . . 1007

xx

Appendix E Platform-specific facilities . . . . . 1008E.1 PowerPC-specific Facilities . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1008

Appendix F Contributors to the GNU CLibrary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1010

Appendix G Free Software Needs FreeDocumentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1015

Appendix H GNU Lesser General Public License. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1017

Appendix I GNU Free Documentation License. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1026

Concept Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1034

Type Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1044

Function and Macro Index . . . . . . . . . . . . . . . . . . . . . 1047

Variable and Constant Macro Index . . . . . . . . . . 1059

Program and File Index . . . . . . . . . . . . . . . . . . . . . . . . 1069

Chapter 1: Introduction 1

1 Introduction

The C language provides no built-in facilities for performing such common operations asinput/output, memory management, string manipulation, and the like. Instead, these fa-cilities are defined in a standard library, which you compile and link with your programs.

The GNU C Library, described in this document, defines all of the library functions thatare specified by the ISO C standard, as well as additional features specific to POSIX andother derivatives of the Unix operating system, and extensions specific to GNU systems.

The purpose of this manual is to tell you how to use the facilities of the GNU C Library.We have mentioned which features belong to which standards to help you identify thingsthat are potentially non-portable to other systems. But the emphasis in this manual is noton strict portability.

1.1 Getting Started

This manual is written with the assumption that you are at least somewhat familiar withthe C programming language and basic programming concepts. Specifically, familiaritywith ISO standard C (see Section 1.2.1 [ISO C], page 2), rather than traditional pre-ISOC dialects, is assumed.

The GNU C Library includes several header files, each of which provides definitions anddeclarations for a group of related facilities; this information is used by the C compilerwhen processing your program. For example, the header file stdio.h declares facilitiesfor performing input and output, and the header file string.h declares string processingutilities. The organization of this manual generally follows the same division as the headerfiles.

If you are reading this manual for the first time, you should read all of the introductorymaterial and skim the remaining chapters. There are a lot of functions in the GNU CLibrary and its not realistic to expect that you will be able to remember exactly how touse each and every one of them. Its more important to become generally familiar with thekinds of facilities that the library provides, so that when you are writing your programs youcan recognize when to make use of library functions, and where in this manual you can findmore specific information about them.

1.2 Standards and Portability

This section discusses the various standards and other sources that the GNU C Library isbased upon. These sources include the ISO C and POSIX standards, and the System Vand Berkeley Unix implementations.

The primary focus of this manual is to tell you how to make effective use of the GNU CLibrary facilities. But if you are concerned about making your programs compatible withthese standards, or portable to operating systems other than GNU, this can affect how youuse the library. This section gives you an overview of these standards, so that you will knowwhat they are when they are mentioned in other parts of the manual.

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

Chapter 1: Introduction 2

1.2.1 ISO C

The GNU C Library is compatible with the C standard adopted by the American Na-tional Standards Institute (ANSI): American National Standard X3.159-1989ANSI Cand 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 themore general standard in respect of ratification. The header files and library facilities thatmake up the GNU C Library are a superset of those specified 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 tellsthe compiler to define only ISO standard features from the library header files, unless youexplicitly ask for additional features. See Section 1.3.4 [Feature Test Macros], page 15, forinformation on how to do this.

Being able to restrict the library to include only ISO C features is important becauseISO C puts limitations on what names can be defined by the library implementation, andthe GNU extensions dont fit these limitations. See Section 1.3.3 [Reserved Names], page 14,for more information about these restrictions.

This manual does not attempt to give you complete details on the differences betweenISO C and older dialects. It gives advice on how to write programs to work portably undermultiple C dialects, but does not aim for completeness.

1.2.2 POSIX (The Portable Operating System Interface)

The GNU C Library is also compatible with the ISO POSIX family of standards, knownmore formally as the Portable Operating System Interface for Computer Environments(ISO/IEC 9945). They were also published as ANSI/IEEE Std 1003. POSIX is derivedmostly from various versions of the Unix operating system.

The library facilities specified by the POSIX standards are a superset of those requiredby ISO C; POSIX specifies additional features for ISO C functions, as well as specifyingnew additional functions. In general, the additional requirements and functionality definedby the POSIX standards are aimed at providing lower-level support for a particular kind ofoperating system environment, rather than general programming language support whichcan run in many diverse operating system environments.

The GNU C Library implements all of the functions specified in ISO/IEC 9945-1:1996,the POSIX System Application Program Interface, commonly referred to as POSIX.1. Theprimary extensions to the ISO C facilities specified by this standard include file systeminterface primitives (see Chapter 14 [File System Interface], page 376), device-specific ter-minal control functions (see Chapter 17 [Low-Level Terminal Interface], page 475), andprocess control functions (see Chapter 26 [Processes], page 747).

Some facilities from ISO/IEC 9945-2:1993, the POSIX Shell and Utilities standard(POSIX.2) are also implemented in the GNU C Library. These include utilities for deal-ing with regular expressions and other pattern matching facilities (see Chapter 10 [PatternMatching], page 222).

1.2.2.1 POSIX Safety Concepts

This manual documents various safety properties of GNU C Library functions, in lines thatfollow their prototypes and look like:

Chapter 1: Introduction 3

Preliminary: | MT-Safe | AS-Safe | AC-Safe |

The properties are assessed according to the criteria set forth in the POSIX standard forsuch safety contexts as Thread-, Async-Signal- and Async-Cancel- -Safety. Intuitive defi-nitions of these properties, attempting to capture the meaning of the standard definitions,follow.

MT-Safe or Thread-Safe functions are safe to call in the presence of other threads. MT,in MT-Safe, stands for Multi Thread.

Being MT-Safe does not imply a function is atomic, nor that it uses any of the memorysynchronization mechanisms POSIX exposes to users. It is even possible that callingMT-Safe functions in sequence does not yield an MT-Safe combination. For example,having a thread call two MT-Safe functions one right after the other does not guaran-tee behavior equivalent to atomic execution of a combination of both functions, sinceconcurrent calls in other threads may interfere in a destructive way.

Whole-program optimizations that could inline functions across library interfaces mayexpose unsafe reordering, and so performing inlining across the GNU C Library inter-face is not recommended. The documented MT-Safety status is not guaranteed underwhole-program optimization. However, functions defined in user-visible headers aredesigned to be safe for inlining.

AS-Safe or Async-Signal-Safe functions are safe to call from asynchronous signal han-dlers. AS, in AS-Safe, stands for Asynchronous Signal.

Many functions that are AS-Safe may set errno, or modify the floating-point environ-ment, because their doing so does not make them unsuitable for use in signal handlers.However, programs could misbehave should asynchronous signal handlers modify thisthread-local state, and the signal handling machinery cannot be counted on to pre-serve it. Therefore, signal handlers that call functions that may set errno or modifythe floating-point environment must save their original values, and restore them beforereturning.

AC-Safe or Async-Cancel-Safe functions are safe to call when asynchronous cancellationis enabled. AC in AC-Safe stands for Asynchronous Cancellation.

The POSIX standard defines only three functions to be AC-Safe, namely pthread_cancel, pthread_setcancelstate, and pthread_setcanceltype. At present theGNU C Library provides no guarantees beyond these three functions, but does docu-ment which functions are presently AC-Safe. This documentation is provided for useby the GNU C Library developers.

Just like signal handlers, cancellation cleanup routines must configure the floating pointenvironment they require. The routines cannot assume a floating point environment,particularly when asynchronous cancellation is enabled. If the configuration of thefloating point environment cannot be performed atomically then it is also possible thatthe environment encountered is internally inconsistent.

MT-Unsafe, AS-Unsafe, AC-Unsafe functions are not safe to call within the safety con-texts described above. Calling them within such contexts invokes undefined behavior.

Functions not explicitly documented as safe in a safety context should be regarded asUnsafe.

Preliminary safety properties are documented, indicating these properties may not becounted on in future releases of the GNU C Library.

Chapter 1: Introduction 4

Such preliminary properties are the result of an assessment of the properties of ourcurrent implementation, rather than of what is mandated and permitted by currentand future standards.

Although we strive to abide by the standards, in some cases our implementation is safeeven when the standard does not demand safety, and in other cases our implementationdoes not meet the standard safety requirements. The latter are most likely bugs; theformer, when marked as Preliminary, should not be counted on: future standards mayrequire changes that are not compatible with the additional safety properties affordedby the current implementation.

Furthermore, the POSIX standard does not offer a detailed definition of safety. Weassume that, by safe to call, POSIX means that, as long as the program does notinvoke undefined behavior, the safe to call function behaves as specified, and doesnot cause other functions to deviate from their specified behavior. We have chosen touse its loose definitions of safety, not because they are the best definitions to use, butbecause choosing them harmonizes this manual with POSIX.

Please keep in mind that these are preliminary definitions and annotations, and certainaspects of the definitions are still under discussion and might be subject to clarificationor change.

Over time, we envision evolving the preliminary safety notes into stable commitments,as stable as those of our interfaces. As we do, we will remove the Preliminary keywordfrom safety notes. As long as the keyword remains, however, they are not to be regardedas a promise of future behavior.

Other keywords that appear in safety notes are defined in subsequent sections.

1.2.2.2 Unsafe Features

Functions that are unsafe to call in certain contexts are annotated with keywords thatdocument their features that make them unsafe to call. AS-Unsafe features in this sec-tion indicate the functions are never safe to call when asynchronous signals are enabled.AC-Unsafe features indicate they are never safe to call when asynchronous cancellation isenabled. There are no MT-Unsafe marks in this section.

lockFunctions marked with lock as an AS-Unsafe feature may be interrupted by a signalwhile holding a non-recursive lock. If the signal handler calls another such functionthat takes the same lock, the result is a deadlock.

Functions annotated with lock as an AC-Unsafe feature may, if cancelledasynchronously, fail to release a lock that would have been released if their executionhad not been interrupted by asynchronous thread cancellation. Once a lock is lefttaken, attempts to take that lock will block indefinitely.

corruptFunctions marked with corrupt as an AS-Unsafe feature may corrupt data struct