The GNU C library reference manual

Standards and Portability......Page 5 POSIX (The Portable Operating System Interface)......Page 6 Using the Library......Page 7 Header Files......Page 8 Reserved Names......Page 9 Feature Test Macros......Page 11 Roadmap to the Manual......Page 15 Checking for Errors......Page 19 Error Codes......Page 20 Error Messages......Page 31 Process Memory Concepts......Page 35 Dynamic Memory Allocation......Page 37 Basic Memory Allocation......Page 38 Freeing Memory Allocated with malloc......Page 39 Changing the Size of a Block......Page 40 Allocating Cleared Space......Page 41 Allocating Aligned Memory Blocks......Page 42 Heap Consistency Checking......Page 43 Memory Allocation Hooks......Page 45 Statistics for Memory Allocation with malloc......Page 48 Summary of malloc-Related Functions......Page 49 Example program excerpts......Page 50 Some more or less clever ideas......Page 51 Interpreting the traces......Page 52 Obstacks......Page 53 Preparing for Using Obstacks......Page 54 Allocation in an Obstack......Page 55 Freeing Objects in an Obstack......Page 56 Growing Objects......Page 57 Extra Fast Growing Objects......Page 59 Alignment of Data in Obstacks......Page 61 Summary of Obstack Functions......Page 62 alloca Example......Page 64 Disadvantages of alloca......Page 65 Resizing the Data Segment......Page 66 Locked Memory Details......Page 67 Functions To Lock And Unlock Pages......Page 68 Classification of Characters......Page 71 Case Conversion......Page 73 Character class determination for wide characters......Page 74 Notes on using the wide character classes......Page 77 Mapping of wide characters.......Page 78 Representation of Strings......Page 81 String and Array Conventions......Page 82 String Length......Page 83 Copying and Concatenation......Page 85 String/Array Comparison......Page 96 Collation Functions......Page 99 Search Functions......Page 103 Finding Tokens in a String......Page 108 Encode Binary Data......Page 113 Argz and Envz Vectors......Page 115 Argz Functions......Page 116 Envz Functions......Page 118 Introduction to Extended Characters......Page 121 Selecting the conversion and its properties......Page 125 Representing the state of the conversion......Page 126 Converting Single Characters......Page 128 Converting Multibyte and Wide Character Strings......Page 134 A Complete Multibyte Conversion Example......Page 137 Non-reentrant Conversion of Single Characters......Page 139 Non-reentrant Conversion of Strings......Page 140 States in Non-reentrant Functions......Page 141 Generic Character Set Conversion Interface......Page 143 A complete iconv example......Page 146 Some Details about other iconv Implementations......Page 149 The iconv Implementation in the GNU C library......Page 150 Format of gconv-modules files......Page 151 Finding the conversion path in iconv......Page 152 iconv module data structures......Page 153 iconv module interfaces......Page 156 What Effects a Locale Has......Page 165 Categories of Activities that Locales Affect......Page 166 How Programs Set the Locale......Page 167 Accessing Locale Information......Page 169 Generic Numeric Formatting Parameters......Page 170 Printing the Currency Symbol......Page 171 Pinpoint Access to Locale Data......Page 173 A dedicated function to format numbers......Page 179 The catgets function family......Page 183 Format of the message catalog files......Page 186 Generate Message Catalogs files......Page 188 How to use the catgets interface......Page 189 Using symbolic names......Page 190 How does to this allow to develop......Page 191 The Uniforum approach to Message Translation......Page 192 What has to be done to translate a message?......Page 193 How to determine which catalog to be used......Page 195 Additional functions for more complicated situations......Page 197 How to specify the output character set gettext uses......Page 200 How to use gettext in GUI programs......Page 201 User influence on gettext......Page 203 Programs to handle message catalogs for gettext......Page 206 Array Search Function......Page 207 Array Sort Function......Page 208 Searching and Sorting Example......Page 209 The hsearch function.......Page 212 The tsearch function.......Page 214 Wildcard Matching......Page 217 Calling glob......Page 218 Flags for Globbing......Page 222 More Flags for Globbing......Page 223 POSIX Regular Expression Compilation......Page 225 Flags for POSIX Regular Expressions......Page 227 Match Results with Subexpressions......Page 228 Complications in Subexpression Matching......Page 229 POSIX Regexp Matching Cleanup......Page 230 Calling wordexp......Page 231 Flags for Word Expansion......Page 233 wordexp Example......Page 234 Details of Variable Substitution......Page 235 Streams and File Descriptors......Page 237 File Position......Page 238 Directories......Page 239 File Name Errors......Page 240 Portability of File Names......Page 241 Standard Streams......Page 243 Opening Streams......Page 244 Closing Streams......Page 247 Streams and Threads......Page 248 Streams in Internationalized Applications......Page 251 Simple Output by Characters or Lines......Page 253 Character Input......Page 255 Line-Oriented Input......Page 258 Using ungetc To Do Unreading......Page 260 Block Input/Output......Page 261 Formatted Output......Page 262 Output Conversion Syntax......Page 263 Table of Output Conversions......Page 265 Integer Conversions......Page 266 Floating-Point Conversions......Page 268 Other Output Conversions......Page 270 Formatted Output Functions......Page 271 Dynamically Allocating Formatted Output......Page 273 Variable Arguments Output Functions......Page 274 Parsing a Template String......Page 276 Example of Parsing a Template String......Page 278 Customizing printf......Page 279 Conversion Specifier Options......Page 280 Defining the Output Handler......Page 282 printf Extension Example......Page 283 Predefined printf Handlers......Page 284 Formatted Input Basics......Page 285 Input Conversion Syntax......Page 286 Table of Input Conversions......Page 287 Numeric Input Conversions......Page 289 String Input Conversions......Page 290 Other Input Conversions......Page 292 Formatted Input Functions......Page 293 Variable Arguments Input Functions......Page 294 End-Of-File and Errors......Page 295 Text and Binary Streams......Page 296 File Positioning......Page 297 Portable File-Position Functions......Page 300 Stream Buffering......Page 301 Flushing Buffers......Page 302 Controlling Which Kind of Buffering......Page 303 String Streams......Page 306 Obstack Streams......Page 308 Custom Streams and Cookies......Page 309 Custom Stream Hook Functions......Page 310 Printing Formatted Messages......Page 311 How to use fmtmsg and addseverity......Page 314 Opening and Closing Files......Page 317 Input and Output Primitives......Page 320 Setting the File Position of a Descriptor......Page 324 Descriptors and Streams......Page 327 Independent Channels......Page 328 Fast Scatter-Gather I/O......Page 329 Memory-mapped I/O......Page 330 Waiting for Input or Output......Page 334 Synchronizing I/O operations......Page 337 Perform I/O Operations in Parallel......Page 338 Asynchronous Read and Write Operations......Page 340 Getting the Status of AIO Operations......Page 344 Getting into a Consistent State......Page 345 Cancellation of AIO Operations......Page 348 Control Operations on Files......Page 349 Duplicating Descriptors......Page 350 File Descriptor Flags......Page 352 File Status Flags......Page 353 File Access Modes......Page 354 Open-time Flags......Page 355 I/O Operating Modes......Page 356 Getting and Setting File Status Flags......Page 357 File Locks......Page 359 Generic I/O Control operations......Page 362 Working Directory......Page 365 Format of a Directory Entry......Page 367 Opening a Directory Stream......Page 368 Reading and Closing a Directory Stream......Page 369 Random Access in a Directory Stream......Page 371 Scanning the Content of a Directory......Page 372 Simple Program to List a Directory, Mark II......Page 373 Working with Directory Trees......Page 374 Hard Links......Page 378 Symbolic Links......Page 379 Deleting Files......Page 381 Renaming Files......Page 382 The meaning of the File Attributes......Page 384 Reading the Attributes of a File......Page 388 Testing the Type of a File......Page 390 File Owner......Page 392 The Mode Bits for Access Permission......Page 393 Assigning File Permissions......Page 395 Testing Permission to Access a File......Page 397 File Times......Page 398 File Size......Page 400 Making Special Files......Page 402 Temporary Files......Page 403 Creating a Pipe......Page 407 Pipe to a Subprocess......Page 409 FIFO Special Files......Page 410 Atomicity of Pipe I/O......Page 411 Socket Concepts......Page 413 Communication Styles......Page 414 Address Formats......Page 415 Reading the Address of a Socket......Page 417 Interface Naming......Page 418 Details of Local Namespace......Page 419 Example of Local-Namespace Sockets......Page 420 The Internet Namespace......Page 421 Internet Socket Address Formats......Page 422 Internet Host Addresses......Page 423 Host Address Data Type......Page 424 Host Address Functions......Page 425 Host Names......Page 427 Internet Ports......Page 430 The Services Database......Page 431 Byte Order Conversion......Page 432 Protocols Database......Page 433 Internet Socket Example......Page 435 Creating a Socket......Page 436 Socket Pairs......Page 437 Making a Connection......Page 438 Accepting Connections......Page 440 Who is Connected to Me?......Page 441 Sending Data......Page 442 Receiving Data......Page 443 Byte Stream Socket Example......Page 444 Byte Stream Connection Server Example......Page 445 Out-of-Band Data......Page 448 Receiving Datagrams......Page 451 Datagram Socket Example......Page 452 Example of Reading Datagrams......Page 453 Configuring inetd......Page 455 Socket Option Functions......Page 456 Socket-Level Options......Page 457 Networks Database......Page 458 Identifying Terminals......Page 461 Two Styles of Input: Canonical or Not......Page 462 Terminal Mode Data Types......Page 463 Terminal Mode Functions......Page 464 Setting Terminal Modes Properly......Page 465 Input Modes......Page 466 Output Modes......Page 468 Control Modes......Page 469 Local Modes......Page 471 Line Speed......Page 473 Characters for Input Editing......Page 475 Characters that Cause Signals......Page 477 Other Special Characters......Page 478 Noncanonical Input......Page 479 BSD Terminal Modes......Page 480 Line Control Functions......Page 481 Noncanonical Mode Example......Page 483 Pseudo-Terminals......Page 484 Allocating Pseudo-Terminals......Page 485 Opening a Pseudo-Terminal Pair......Page 487 Overview of Syslog......Page 489 openlog......Page 490 syslog, vsyslog......Page 491 setlogmask......Page 494 Syslog Example......Page 495 Predefined Mathematical Constants......Page 497 Trigonometric Functions......Page 498 Inverse Trigonometric Functions......Page 500 Exponentiation and Logarithms......Page 501 Hyperbolic Functions......Page 505 Special Functions......Page 507 Known Maximum Errors in Math Functions......Page 509 Pseudo-Random Numbers......Page 515 BSD Random Number Functions......Page 516 SVID Random Number Function......Page 518 Is Fast Code or Small Code preferred?......Page 522 Integers......Page 525 Integer Division......Page 526 Floating-Point Number Classification Functions......Page 528 FP Exceptions......Page 530 Infinity and NaN......Page 532 Examining the FPU status word......Page 533 Rounding Modes......Page 535 Floating-Point Control Functions......Page 537 Absolute Value......Page 539 Normalization Functions......Page 540 Rounding Functions......Page 541 Remainder Functions......Page 543 Setting and modifying single bits of FP values......Page 544 Floating-Point Comparison Functions......Page 545 Miscellaneous FP arithmetic functions......Page 546 Projections, Conjugates, and Decomposing of Complex Numbers......Page 547 Parsing of Integers......Page 548 Parsing of Floats......Page 553 Old-fashioned System V number-to-string functions......Page 554 Elapsed Time......Page 557 CPU Time Inquiry......Page 559 Processor Time Inquiry......Page 560 Calendar Time......Page 561 High-Resolution Calendar......Page 562 Broken-down Time......Page 564 High Accuracy Clock......Page 567 Formatting Calendar Time......Page 570 Convert textual time and date information back......Page 575 Interpret string according to given format......Page 576 A More User-friendly Way to Parse Times and Dates......Page 580 Specifying the Time Zone with TZ......Page 583 Functions and Variables for Time Zones......Page 585 Setting an Alarm......Page 586 Sleeping......Page 588 Resource Usage......Page 591 Limiting Resource Usage......Page 593 Process CPU Priority And Scheduling......Page 597 Using Absolute Priority......Page 598 Realtime Scheduling......Page 599 Basic Scheduling Functions......Page 600 Introduction To Traditional Scheduling......Page 603 Functions For Traditional Scheduling......Page 604 Overview about traditional Unix memory handling......Page 606 How to get information about the memory subsystem?......Page 607 Learn about the processors available......Page 608 Introduction to Non-Local Exits......Page 611 Details of Non-Local Exits......Page 612 Non-Local Exits and Signals......Page 613 Complete Context Control......Page 614 Some Kinds of Signals......Page 621 How Signals Are Delivered......Page 622 Program Error Signals......Page 623 Termination Signals......Page 626 Alarm Signals......Page 627 Job Control Signals......Page 628 Operation Error Signals......Page 630 Signal Messages......Page 631 Basic Signal Handling......Page 632 Advanced Signal Handling......Page 634 Interaction of signal and sigaction......Page 635 sigaction Function Example......Page 636 Flags for sigaction......Page 637 Defining Signal Handlers......Page 638 Signal Handlers that Return......Page 639 Handlers That Terminate the Process......Page 640 Nonlocal Control Transfer in Handlers......Page 641 Signals Arriving While a Handler Runs......Page 642 Signals Close Together Merge into One......Page 643 Signal Handling and Nonreentrant Functions......Page 645 Problems with Non-Atomic Access......Page 647 Atomic Usage Patterns......Page 648 Primitives Interrupted by Signals......Page 649 Signaling Yourself......Page 650 Signaling Another Process......Page 651 Permission for using kill......Page 652 Using kill for Communication......Page 653 Blocking Signals......Page 654 Signal Sets......Page 655 Process Signal Mask......Page 656 Blocking to Test for Delivery of a Signal......Page 657 Blocking Signals for a Handler......Page 658 Checking for Pending Signals......Page 659 Remembering a Signal to Act On Later......Page 660 Using pause......Page 661 Problems with pause......Page 662 Using sigsuspend......Page 663 Using a Separate Signal Stack......Page 664 BSD Function to Establish a Handler......Page 666 BSD Functions for Blocking Signals......Page 667 Program Arguments......Page 669 Program Argument Syntax Conventions......Page 670 Using the getopt function......Page 671 Example of Parsing Arguments with getopt......Page 672 Parsing Long Options with getopt_long......Page 674 Example of Parsing Long Options with getopt_long......Page 676 The argp_parse Function......Page 678 Argp Global Variables......Page 679 Specifying Argp Parsers......Page 680 Specifying Options in an Argp Parser......Page 681 Argp Parser Functions......Page 682 Special Keys for Argp Parser Functions......Page 684 Functions For Use in Argp Parsers......Page 686 Argp Parsing State......Page 687 Combining Multiple Argp Parsers......Page 688 Flags for argp_parse......Page 689 Special Keys for Argp Help Filter Functions......Page 690 Flags for the argp_help Function......Page 691 Argp Examples......Page 692 A Program Using Argp with Only Default Options......Page 693 A Program Using Argp with User Options......Page 694 A Program Using Multiple Combined Argp Parsers......Page 698 Argp User Customization......Page 701 Parsing of Suboptions......Page 702 Parsing of Suboptions Example......Page 703 Environment Variables......Page 704 Environment Access......Page 705 Standard Environment Variables......Page 707 System Calls......Page 708 Normal Termination......Page 710 Exit Status......Page 711 Cleanups on Exit......Page 712 Termination Internals......Page 713 Running a Command......Page 715 Process Identification......Page 716 Creating a Process......Page 717 Executing a File......Page 718 Process Completion......Page 720 Process Completion Status......Page 723 BSD Process Wait Functions......Page 724 Process Creation Example......Page 725 Concepts of Job Control......Page 727 Access to the Controlling Terminal......Page 728 Implementing a Job Control Shell......Page 729 Data Structures for the Shell......Page 730 Initializing the Shell......Page 731 Launching Jobs......Page 733 Foreground and Background......Page 736 Stopped and Terminated Jobs......Page 737 Continuing Stopped Jobs......Page 740 The Missing Pieces......Page 741 Process Group Functions......Page 742 Functions for Controlling Terminal Access......Page 744 NSS Basics......Page 747 Services in the NSS configuration File......Page 748 Actions in the NSS configuration......Page 749 The Naming Scheme of the NSS Modules......Page 750 The Interface of the Function in NSS Modules......Page 751 Adding another Service to NSS......Page 753 Internals of the NSS Module Functions......Page 754 The Persona of a Process......Page 757 How an Application Can Change Persona......Page 758 Reading the Persona of a Process......Page 759 Setting the User ID......Page 760 Setting the Group IDs......Page 761 Enabling and Disabling Setuid Access......Page 762 Setuid Program Example......Page 763 Tips for Writing Setuid Programs......Page 765 Identifying Who Logged In......Page 766 Manipulating the User Accounting Database......Page 767 XPG User Accounting Database Functions......Page 772 Logging In and Out......Page 774 Looking Up One User......Page 775 Scanning the List of All Users......Page 776 Writing a User Entry......Page 777 Looking Up One Group......Page 778 Scanning the List of All Groups......Page 779 User and Group Database Example......Page 780 Netgroup Data......Page 781 Looking up one Netgroup......Page 782 Testing for Netgroup Membership......Page 783 Host Identification......Page 785 Platform Type Identification......Page 787 Controlling and Querying Mounts......Page 788 The fstab file......Page 789 The mtab file......Page 791 Mount, Unmount, Remount......Page 795 System Parameters......Page 798 General Capacity Limits......Page 801 Overall System Options......Page 802 Which Version of POSIX is Supported......Page 803 Constants for sysconf Parameters......Page 804 Examples of sysconf......Page 812 Minimum Values for General Capacity Limits......Page 813 Limits on File System Capacity......Page 814 Optional Features in File Support......Page 815 Minimum Values for File System Limits......Page 816 Using pathconf......Page 817 Utility Program Capacity Limits......Page 819 String-Valued Parameters......Page 820 Legal Problems......Page 823 Reading Passwords......Page 824 Encrypting Passwords......Page 825 DES Encryption......Page 827 Backtraces......Page 831 Explicitly Checking Internal Consistency......Page 835 Why Variadic Functions are Used......Page 836 Syntax for Variable Arguments......Page 837 How Many Arguments Were Supplied......Page 838 Calling Variadic Functions......Page 839 Argument Access Macros......Page 840 Example of a Variadic Function......Page 841 Null Pointer Constant......Page 842 Important Data Types......Page 843 Range of an Integer Type......Page 844 Floating Point Representation Concepts......Page 846 Floating Point Parameters......Page 847 IEEE Floating Point......Page 850 Structure Field Offset Measurement......Page 851 Summary of Library Facilities......Page 853 Configuring and compiling GNU Libc......Page 959 Installing the C Library......Page 962 Recommended Tools for Compilation......Page 963 Supported Configurations......Page 964 Reporting Bugs......Page 966 Adding New Functions......Page 969 Porting the GNU C Library......Page 970 Layout of the sysdeps Directory Hierarchy......Page 973 Porting the GNU C Library to Unix Systems......Page 975 Contributors to the GNU C Library......Page 977 Preamble......Page 983 TERMS AND CONDITIONS FOR COPYING,@hfil @penalty -@@M @hbox {}@ignorespaces DISTRIBUTION AND MODIFICATION......Page 984 How to Apply These Terms to Your New Libraries......Page 991 Concept Index......Page 993 Type Index......Page 1003 Function and Macro Index......Page 1005 Variable and Constant Macro Index......Page 1017 Program and File Index......Page 1029