diff options
Diffstat (limited to 'manual/libc.texinfo')
| -rw-r--r-- | manual/libc.texinfo | 1007 |
1 files changed, 1007 insertions, 0 deletions
diff --git a/manual/libc.texinfo b/manual/libc.texinfo new file mode 100644 index 0000000000..0b455b32d2 --- /dev/null +++ b/manual/libc.texinfo @@ -0,0 +1,1007 @@ +\input texinfo @c -*- Texinfo -*- +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename libc.info +@settitle The GNU C Library +@setchapternewpage odd +@comment %**end of header (This is for running Texinfo on a region.) + +@c This tells texinfo.tex to use the real section titles in xrefs in +@c place of the node name, when no section title is explicitly given. +@set xref-automatic-section-title +@smallbook + +@c I've already told people the printed edition will be 0.06 +@set EDITION 0.06 +@set VERSION 1.09 Beta +@set UPDATED 23 December 1994 +@set ISBN 1-882114-53-1 + +@ifinfo +This file documents the GNU C library. + +This is Edition @value{EDITION}, last updated @value{UPDATED}, +of @cite{The GNU C Library Reference Manual}, for Version @value{VERSION}. + +Copyright (C) 1993, 1994 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU Library General Public License'' is included +exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + +Permission is granted to copy and distribute translations of this manual +Library General Public License'' must be approved for accuracy by the +Foundation. +@end ifinfo + +@iftex +@shorttitlepage The GNU C Library Reference Manual +@end iftex +@titlepage +@center @titlefont{The GNU C Library} +@sp 1 +@center @titlefont{Reference Manual} +@sp 2 +@center Sandra Loosemore +@center with +@center Richard M. Stallman, Roland McGrath, and Andrew Oram +@sp 3 +@center Edition @value{EDITION} +@sp 1 +@center last updated @value{UPDATED} +@sp 1 +@center for version @value{VERSION} +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1993, 1994 Free Software Foundation, Inc. +@sp 2 +Published by the Free Software Foundation @* +675 Massachusetts Avenue, @* +Cambridge, MA 02139 USA @* +Printed copies are available for $50 each. @* +ISBN @value{ISBN} @* + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +section entitled ``GNU Library General Public License'' is included +exactly as in the original, and provided that the entire resulting +derived work is distributed under the terms of a permission notice +identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that the text of the translation of the section entitled ``GNU +Library General Public License'' must be approved for accuracy by the +Foundation. +@end titlepage +@page + +@ifinfo +@node Top, Introduction, (dir), (dir) +@top Main Menu +This is Edition @value{EDITION}, last updated @value{UPDATED}, of +@cite{The GNU C Library Reference Manual}, for Version @value{VERSION} +of the GNU C Library. +@end ifinfo + + +@menu +* Introduction:: Purpose of the GNU C Library. +* Error Reporting:: How the GNU Library functions report + error conditions. +* Memory Allocation:: Your program can allocate memory dynamically + and manipulate it via pointers. +* Character Handling:: Character testing and conversion functions. +* String and Array Utilities:: Utilities for copying and comparing + strings and arrays. +* Extended Characters:: Support for extended character sets. +* Locales:: The country and language can affect + the behavior of library functions. +* Searching and Sorting:: General searching and sorting functions. +* Pattern Matching:: Matching wildcards and regular expressions, + and shell-style ``word expansion''. +* I/O Overview:: Introduction to the I/O facilities. +* Streams: I/O on Streams. High-level, portable I/O facilities. +* Low-Level I/O:: Low-level, less portable I/O. +* File System Interface:: Functions for manipulating files. +* Pipes and FIFOs:: A simple interprocess communication mechanism. +* Sockets:: A more complicated interprocess communication + mechanism, with support for networking. +* Low-Level Terminal Interface::How to change the characteristics + of a terminal device. +* Mathematics:: Math functions (transcendental functions, + random numbers, absolute value, etc.). +* Arithmetic:: Low-level arithmetic functions. +* Date and Time:: Functions for getting the date and time, + and for conversion between formats. +* Non-Local Exits:: The @code{setjmp} and @code{longjmp} facilities. +* Signal Handling:: All about signals; how to send them, + block them, and handle them. +* Process Startup:: Writing the beginning and end of your program. +* Processes:: How to create processes and run other programs. +* Job Control:: All about process groups and sessions. +* Users and Groups:: How users are identified and classified. +* System Information:: Getting information about the + hardware and software configuration + of the machine a program runs on. +* System Configuration:: Parameters describing operating system limits. + +Appendices + +* Language Features:: C language features provided by the library. + +* Library Summary:: A summary showing the syntax, header file, + and derivation of each library feature. +* Maintenance:: How to install and maintain the GNU C Library. +* Copying:: The GNU Library General Public License says + how you can copy and share the GNU C Library. + +Indices + +* Concept Index:: Index of concepts and names. +* Type Index:: Index of types and type qualifiers. +* Function Index:: Index of functions and function-like macros. +* Variable Index:: Index of variables and variable-like macros. +* File Index:: Index of programs and files. + + --- The Detailed Node Listing --- + +Introduction + +* Getting Started:: Getting Started +* Standards and Portability:: Standards and Portability +* Using the Library:: Using the Library +* Roadmap to the Manual:: Roadmap to the Manual + +Standards and Portability + +* ANSI C:: The American National Standard for the + C programming language. +* POSIX:: The IEEE 1003 standards for operating systems. +* Berkeley Unix:: BSD and SunOS. +* SVID:: The System V Interface Description. + +Using the Library + +* Header Files:: How to use the header files in your programs. +* Macro Definitions:: Some functions in the library may really + be implemented as macros. +* Reserved Names:: The C standard reserves some names for + the library, and some for users. +* Feature Test Macros:: How to control what names are defined. + +Error Reporting + +* Checking for Errors:: How errors are reported by library functions. +* Error Codes:: What all the error codes are. +* Error Messages:: Mapping error codes onto error messages. + +Memory Allocation + +* Memory Concepts:: An introduction to concepts and terminology. +* Dynamic Allocation and C:: How to get different kinds of allocation in C. +* Unconstrained Allocation:: The @code{malloc} facility allows fully general + dynamic allocation. +* Obstacks:: Obstacks are less general than malloc + but more efficient and convenient. +* Variable Size Automatic:: Allocation of variable-sized blocks + of automatic storage that are freed when the + calling function returns. +* Relocating Allocator:: Waste less memory, if you can tolerate + automatic relocation of the blocks you get. +* Memory Warnings:: Getting warnings when memory is nearly full. + +Unconstrained Allocation + +* Basic Allocation:: Simple use of @code{malloc}. +* Malloc Examples:: Examples of @code{malloc}. @code{xmalloc}. +* Freeing after Malloc:: Use @code{free} to free a block you + got with @code{malloc}. +* Changing Block Size:: Use @code{realloc} to make a block + bigger or smaller. +* Allocating Cleared Space:: Use @code{calloc} to allocate a + block and clear it. +* Efficiency and Malloc:: Efficiency considerations in use of + these functions. +* Aligned Memory Blocks:: Allocating specially aligned memory: + @code{memalign} and @code{valloc}. +* Heap Consistency Checking:: Automatic checking for errors. +* Hooks for Malloc:: You can use these hooks for debugging + programs that use @code{malloc}. +* Statistics of Malloc:: Getting information about how much + memory your program is using. +* Summary of Malloc:: Summary of @code{malloc} and related functions. + +Obstacks + +* Creating Obstacks:: How to declare an obstack in your program. +* Preparing for Obstacks:: Preparations needed before you can + use obstacks. +* Allocation in an Obstack:: Allocating objects in an obstack. +* Freeing Obstack Objects:: Freeing objects in an obstack. +* Obstack Functions:: The obstack functions are both + functions and macros. +* Growing Objects:: Making an object bigger by stages. +* Extra Fast Growing:: Extra-high-efficiency (though more + complicated) growing objects. +* Status of an Obstack:: Inquiries about the status of an obstack. +* Obstacks Data Alignment:: Controlling alignment of objects in obstacks. +* Obstack Chunks:: How obstacks obtain and release chunks. + Efficiency considerations. +* Summary of Obstacks:: + +Automatic Storage with Variable Size + +* Alloca Example:: Example of using @code{alloca}. +* Advantages of Alloca:: Reasons to use @code{alloca}. +* Disadvantages of Alloca:: Reasons to avoid @code{alloca}. +* GNU C Variable-Size Arrays:: Only in GNU C, here is an alternative + method of allocating dynamically and + freeing automatically. +Relocating Allocator + +* Relocator Concepts:: How to understand relocating allocation. +* Using Relocator:: Functions for relocating allocation. + +Character Handling + +* Classification of Characters::Testing whether characters are + letters, digits, punctuation, etc. +* Case Conversion:: Case mapping, and the like. + +String and Array Utilities + +* Representation of Strings:: Introduction to basic concepts. +* String/Array Conventions:: Whether to use a string function or an + arbitrary array function. +* String Length:: Determining the length of a string. +* Copying and Concatenation:: Functions to copy the contents of strings + and arrays. +* String/Array Comparison:: Functions for byte-wise and character-wise + comparison. +* Collation Functions:: Functions for collating strings. +* Search Functions:: Searching for a specific element or substring. +* Finding Tokens in a String:: Splitting a string into tokens by looking + for delimiters. + +Extended Characters + +* Extended Char Intro:: Multibyte codes versus wide characters. +* Locales and Extended Chars:: The locale selects the character codes. +* Multibyte Char Intro:: How multibyte codes are represented. +* Wide Char Intro:: How wide characters are represented. +* Wide String Conversion:: Converting wide strings to multibyte code + and vice versa. +* Length of Char:: how many bytes make up one multibyte char. +* Converting One Char:: Converting a string character by character. +* Example of Conversion:: Example showing why converting + one character at a time may be useful. +* Shift State:: Multibyte codes with "shift characters". + +Locales and Internationalization + +* Effects of Locale:: Actions affected by the choice of locale. +* Choosing Locale:: How the user specifies a locale. +* Locale Categories:: Different purposes for which + you can select a locale. +* Setting the Locale:: How a program specifies the locale. +* Standard Locales:: Locale names available on all systems. +* Numeric Formatting:: How to format numbers for the chosen locale. + +Searching and Sorting + +* Comparison Functions:: Defining how to compare two objects. + Since the sort and search facilities are + general, you have to specify the ordering. +* Array Search Function:: The @code{bsearch} function. +* Array Sort Function:: The @code{qsort} function. +* Search/Sort Example:: An example program. + +Pattern Matching + +* Wildcard Matching:: Matching a wildcard pattern against a single string. +* Globbing:: Finding the files that match a wildcard pattern. +* Regular Expressions:: Matching regular expressions against strings. +* Word Expansion:: Expanding shell variables, nested commands, + arithmetic, and wildcards. + This is what the shell does with shell commands. + +I/O Overview + +* I/O Concepts:: Some basic information and terminology. +* File Names:: How to refer to a file. + +I/O Concepts + +* Streams and File Descriptors:: The GNU Library provides two ways + to access the contents of files. +* File Position:: The number of bytes from the + beginning of the file. + +File Names + +* Directories:: Directories contain entries for files. +* File Name Resolution:: A file name specifies how to look up a file. +* File Name Errors:: Error conditions relating to file names. +* File Name Portability:: File name portability and syntax issues. + +I/O on Streams + +* Streams:: About the data type representing a stream. +* Standard Streams:: Streams to the standard input and output + devices are created for you. +* Opening Streams:: How to create a stream to talk to a file. +* Closing Streams:: Close a stream when you are finished with it. +* Simple Output:: Unformatted output by characters and lines. +* Character Input:: Unformatted input by characters and words. +* Line Input:: Reading a line or a record from a stream. +* Unreading:: Peeking ahead/pushing back input just read. +* Formatted Output:: @code{printf} and related functions. +* Customizing Printf:: You can define new conversion specifiers for + @code{printf} and friends. +* Formatted Input:: @code{scanf} and related functions. +* Block Input/Output:: Input and output operations on blocks of data. +* EOF and Errors:: How you can tell if an I/O error happens. +* Binary Streams:: Some systems distinguish between text files + and binary files. +* File Positioning:: About random-access streams. +* Portable Positioning:: Random access on peculiar ANSI C systems. +* Stream Buffering:: How to control buffering of streams. +* Temporary Files:: How to open a temporary file. +* Other Kinds of Streams:: Other Kinds of Streams + +Unreading + +* Unreading Idea:: An explanation of unreading with pictures. +* How Unread:: How to call @code{ungetc} to do unreading. + +Formatted Output + +* Formatted Output Basics:: Some examples to get you started. +* Output Conversion Syntax:: General syntax of conversion specifications. +* Table of Output Conversions:: Summary of output conversions, what they do. +* Integer Conversions:: Details of formatting integers. +* Floating-Point Conversions:: Details of formatting floating-point numbers. +* Other Output Conversions:: Details about formatting of strings, + characters, pointers, and the like. +* Formatted Output Functions:: Descriptions of the actual functions. +* Variable Arguments Output:: @code{vprintf} and friends. +* Parsing a Template String:: What kinds of arguments does + a given template call for? + +Customizing Printf + +* Registering New Conversions:: +* Conversion Specifier Options:: +* Defining the Output Handler:: +* Printf Extension Example:: + +Formatted Input + +* Formatted Input Basics:: Some basics to get you started. +* Input Conversion Syntax:: Syntax of conversion specifications. +* Table of Input Conversions:: Summary of input conversions and what they do. +* Numeric Input Conversions:: Details of conversions for reading numbers. +* String Input Conversions:: Details of conversions for reading strings. +* Other Input Conversions:: Details of miscellaneous other conversions. +* Formatted Input Functions:: Descriptions of the actual functions. +* Variable Arguments Input:: @code{vscanf} and friends. + +Stream Buffering + +* Buffering Concepts:: Terminology is defined here. +* Flushing Buffers:: How to ensure that output buffers are flushed. +* Controlling Buffering:: How to specify what kind of buffering to use. + +Other Kinds of Streams + +* String Streams:: +* Custom Streams:: + +Programming Your Own Custom Streams + +* Streams and Cookies:: +* Hook Functions:: + +Low-Level I/O + +* Opening and Closing Files:: How to open and close file descriptors. +* I/O Primitives:: Reading and writing data. +* File Position Primitive:: Setting a descriptor's file position. +* Descriptors and Streams:: Converting descriptor to stream or vice-versa. +* Stream/Descriptor Precautions:: Precautions needed if you use both + descriptors and streams. +* Waiting for I/O:: How to check for input or output + on multiple file descriptors. +* Control Operations:: Various other operations on file descriptors. +* Duplicating Descriptors:: Fcntl commands for duplicating descriptors. +* Descriptor Flags:: Fcntl commands for manipulating flags + associated with file descriptors. +* File Status Flags:: Fcntl commands for manipulating flags + associated with open files. +* File Locks:: Fcntl commands for implementing file locking. +* Interrupt Input:: Getting a signal when input arrives. + +File System Interface + +* Working Directory:: This is used to resolve relative file names. +* Accessing Directories:: Finding out what files a directory contains. +* Hard Links:: Adding alternate names to a file. +* Symbolic Links:: A file that ``points to'' a file name. +* Deleting Files:: How to delete a file, and what that means. +* Renaming Files:: Changing a file's name. +* Creating Directories:: A system call just for creating a directory. +* File Attributes:: Attributes of individual files. +* Making Special Files:: How to create special files. + +Accessing Directories + +* Directory Entries:: Format of one directory entry. +* Opening a Directory:: How to open a directory stream. +* Reading/Closing Directory:: How to read directory entries from the stream. +* Simple Directory Lister:: A very simple directory listing program. +* Random Access Directory:: Rereading part of the directory + already read with the same stream. + +File Attributes + +* Attribute Meanings:: The names of the file attributes, + and what their values mean. +* Reading Attributes:: How to read the attributes of a file. +* Testing File Type:: Distinguishing ordinary files, + directories, links... +* File Owner:: How ownership for new files is determined, + and how to change it. +* Permission Bits:: How information about a file's access mode + is stored. +* Access Permission:: How the system decides who can access a file. +* Setting Permissions:: How permissions for new files are assigned, + and how to change them. +* Testing File Access:: How to find out if your process can + access a file. +* File Times:: About the time attributes of a file. + +Pipes and FIFOs + +* Creating a Pipe:: Making a pipe with the @code{pipe} function. +* Pipe to a Subprocess:: Using a pipe to communicate with a child. +* FIFO Special Files:: Making a FIFO special file. + +Sockets + +* Socket Concepts:: Basic concepts you need to know about. +* Communication Styles:: Stream communication, datagrams, and others. +* Socket Addresses:: How socket names (``addresses'') work. +* File Namespace:: Details about the file namespace. +* Internet Namespace:: Details about the Internet namespace. +* Open/Close Sockets:: Creating sockets and destroying them. +* Connections:: Operations on sockets with connection state. +* Datagrams:: Operations on datagram sockets. +* Socket Options:: Miscellaneous low-level socket options. +* Networks Database:: Accessing the database of network names. + +Socket Addresses + +* Address Formats:: About @code{struct sockaddr}. +* Setting Address:: Binding an address to a socket. +* Reading Address:: Reading the address of a socket. + +Internet Domain + +* Internet Address Format:: How socket addresses are specified in the + Internet namespace. +* Host Addresses:: All about host addresses of Internet hosts. +* Protocols Database:: Referring to protocols by name. +* Services Database:: Ports may have symbolic names. +* Byte Order:: Different hosts may use different byte + ordering conventions; you need to + canonicalize host address and port number. +* Inet Example:: Putting it all together. + +Host Addresses + +* Abstract Host Addresses:: What a host number consists of. +* Data type: Host Address Data Type. Data type for a host number. +* Functions: Host Address Functions. Functions to operate on them. +* Names: Host Names. Translating host names to host numbers. + +Open/Close Sockets + +* Creating a Socket:: How to open a socket. +* Closing a Socket:: How to close a socket. +* Socket Pairs:: These are created like pipes. + +Connections + +* Connecting:: What the client program must do. +* Listening:: How a server program waits for requests. +* Accepting Connections:: What the server does when it gets a request. +* Who is Connected:: Getting the address of the + other side of a connection. +* Transferring Data:: How to send and receive data. +* Byte Stream Example:: An example client for communicating over a + byte stream socket in the Internet namespace. +* Server Example:: A corresponding server program. +* Out-of-Band Data:: This is an advanced feature. + +Transferring Data + +* Sending Data:: Sending data with @code{write}. +* Receiving Data:: Reading data with @code{read}. +* Socket Data Options:: Using @code{send} and @code{recv}. + +Datagrams + +* Sending Datagrams:: Sending packets on a datagram socket. +* Receiving Datagrams:: Receiving packets on a datagram socket. +* Datagram Example:: An example program: packets sent over a + datagram stream in the file namespace. +* Example Receiver:: Another program, that receives those packets. + +Socket Options + +* Socket Option Functions:: The basic functions for setting and getting + socket options. +* Socket-Level Options:: Details of the options at the socket level. + +Low-Level Terminal Interface + +* Is It a Terminal:: How to determine if a file is a terminal + device, and what its name is. +* I/O Queues:: About flow control and typeahead. +* Canonical or Not:: Two basic styles of input processing. +* Terminal Modes:: How to examine and modify flags controlling + terminal I/O: echoing, signals, editing. +* Line Control:: Sending break sequences, clearing buffers... +* Noncanon Example:: How to read single characters without echo. + +Terminal Modes + +* Mode Data Types:: The data type @code{struct termios} and related types. +* Mode Functions:: Functions to read and set terminal attributes. +* Setting Modes:: The right way to set attributes reliably. +* Input Modes:: Flags controlling low-level input handling. +* Output Modes:: Flags controlling low-level output handling. +* Control Modes:: Flags controlling serial port behavior. +* Local Modes:: Flags controlling high-level input handling. +* Line Speed:: How to read and set the terminal line speed. +* Special Characters:: Characters that have special effects, + and how to change them. +* Noncanonical Input:: Controlling how long to wait for input. + +Special Characters + +* Editing Characters:: +* Signal Characters:: +* Start/Stop Characters:: + +Mathematics + +* Domain and Range Errors:: How overflow conditions and the + like are reported. +* Not a Number:: Making NANs and testing for NANs. +* Trig Functions:: Sine, cosine, and tangent. +* Inverse Trig Functions:: Arc sine, arc cosine, and arc tangent. +* Exponents and Logarithms:: Also includes square root. +* Hyperbolic Functions:: Hyperbolic sine and friends. +* Pseudo-Random Numbers:: Functions for generating pseudo-random numbers. +* Absolute Value:: Absolute value functions. + +Pseudo-Random Numbers + +* ANSI Random:: @code{rand} and friends. +* BSD Random:: @code{random} and friends. + +Low-Level Arithmetic Functions + +* Normalization Functions:: Hacks for radix-2 representations. +* Rounding and Remainders:: Determinining the integer and + fractional parts of a float. +* Integer Division:: Functions for performing integer division. +* Parsing of Numbers:: Functions for ``reading'' numbers from strings. +* Predicates on Floats:: Some miscellaneous test functions. + +Parsing of Numbers + +* Parsing of Integers:: Functions for conversion of integer values. +* Parsing of Floats:: Functions for conversion of floating-point. + +Date and Time + +* Processor Time:: Measures processor time used by a program. +* Calendar Time:: Manipulation of ``real'' dates and times. +* Setting an Alarm:: Sending a signal after a specified time. +* Sleeping:: Waiting for a period of time. + +Processor Time + +* Basic CPU Time:: The @code{clock} function. +* Detailed CPU Time:: The @code{times} function. + +Calendar Time + +* Simple Calendar Time:: Facilities for manipulating calendar time. +* High-Resolution Calendar:: A time representation with greater precision. +* Broken-down Time:: Facilities for manipulating local time. +* Formatting Date and Time:: Converting times to strings. +* TZ Variable:: How users specify the time zone. +* Time Zone Functions:: Functions to examine or specify the time zone. +* Time Functions Example:: An example program showing use of some of + the time functions. + +Signal Handling + +* Concepts of Signals:: Introduction to the signal facilities. +* Standard Signals:: Particular kinds of signals with standard + names and meanings. +* Signal Actions:: Specifying what happens when a particular + signal is delivered. +* Defining Handlers:: How to write a signal handler function. +* Generating Signals:: How to send a signal to a process. +* Blocking Signals:: Making the system hold signals temporarily. +* Waiting for a Signal:: Suspending your program until a signal arrives. +* Signal Stack:: Using a Separate Signal Stack +* BSD Signal Handling:: Additional functions for backward + compatibility with BSD. + +Basic Concepts of Signals + +* Kinds of Signals:: Some examples of what can cause a signal. +* Signal Generation:: Concepts of why and how signals occur. +* Delivery of Signal:: Concepts of what a signal does to the process. + +Standard Signals + +* Program Error Signals:: Used to report serious program errors. +* Termination Signals:: Used to interrupt and/or terminate the program. +* Alarm Signals:: Used to indicate expiration of timers. +* Asynchronous I/O Signals:: Used to indicate input is available. +* Job Control Signals:: Signals used to support job control. +* Operation Error Signals:: Used to report operational system errors. +* Miscellaneous Signals:: Miscellaneous Signals. +* Signal Messages:: Printing a message describing a signal. + +Specifying Signal Actions + +* Basic Signal Handling:: The simple @code{signal} function. +* Advanced Signal Handling:: The more powerful @code{sigaction} function. +* Signal and Sigaction:: How those two functions interact. +* Sigaction Function Example:: An example of using the sigaction function. +* Flags for Sigaction:: Specifying options for signal handling. +* Initial Signal Actions:: How programs inherit signal actions. + +Defining Signal Handlers + +* Handler Returns:: +* Termination in Handler:: +* Longjmp in Handler:: +* Signals in Handler:: +* Nonreentrancy:: +* Atomic Data Access:: + +Generating Signals + +* Signaling Yourself:: Signaling Yourself +* Signaling Another Process:: Send a signal to another process. +* Permission for kill:: Permission for using @code{kill} +* Kill Example:: Using @code{kill} for Communication + +Blocking Signals + +* Why Block:: The purpose of blocking signals. +* Signal Sets:: How to specify which signals to block. +* Process Signal Mask:: Blocking delivery of signals to your + process during normal execution. +* Testing for Delivery:: Blocking to Test for Delivery of a Signal +* Blocking for Handler:: Blocking additional signals while a + handler is being run. +* Checking for Pending Signals::Checking for Pending Signals +* Remembering a Signal:: How you can get almost the same effect + as blocking a signal, by handling it + and setting a flag to be tested later. + +Waiting for a Signal + +* Using Pause:: The simple way, using @code{pause}. +* Pause Problems:: Why the simple way is often not very good. +* Sigsuspend:: Reliably waiting for a specific signal. + +BSD Signal Handling + +* BSD Handler:: BSD Function to Establish a Handler. +* Blocking in BSD:: BSD Functions for Blocking Signals + +Process Startup and Termination + +* Program Arguments:: Parsing your program's command-line arguments. +* Environment Variables:: How to access parameters inherited from + a parent process. +* Program Termination:: How to cause a process to terminate and + return status information to its parent. + +Program Arguments + +* Argument Syntax:: By convention, options start with a hyphen. +* Parsing Options:: The @code{getopt} function. +* Example of Getopt:: An example of parsing options with @code{getopt}. +* Long Options:: GNU utilities should accept long-named options. + Here is how to do that. +* Long Option Example:: An example of using @code{getopt_long}. + +Environment Variables + +* Environment Access:: How to get and set the values of + environment variables. +* Standard Environment:: These environment variables have + standard interpretations. + +Program Termination + +* Normal Termination:: If a program calls @code{exit}, a + process terminates normally. +* Exit Status:: The @code{exit status} provides information + about why the process terminated. +* Cleanups on Exit:: A process can run its own cleanup + functions upon normal termination. +* Aborting a Program:: The @code{abort} function causes + abnormal program termination. +* Termination Internals:: What happens when a process terminates. + + +Child Processes + +* Running a Command:: The easy way to run another program. +* Process Creation Concepts:: An overview of the hard way to do it. +* Process Identification:: How to get the process ID of a process. +* Creating a Process:: How to fork a child process. +* Executing a File:: How to make a child execute another program. +* Process Completion:: How to tell when a child process has completed. +* Process Completion Status:: How to interpret the status value + returned from a child process. +* BSD Wait Functions:: More functions, for backward compatibility. +* Process Creation Example:: A complete example program. + +Job Control + +* Concepts of Job Control :: Concepts of Job Control +* Job Control is Optional:: Not all POSIX systems support job control. +* Controlling Terminal:: How a process gets its controlling terminal. +* Access to the Terminal:: How processes share the controlling terminal. +* Orphaned Process Groups:: Jobs left after the user logs out. +* Implementing a Shell:: What a shell must do to implement job control. +* Functions for Job Control:: Functions to control process groups. + +Implementing a Job Control Shell + +* Data Structures:: Introduction to the sample shell. +* Initializing the Shell:: What the shell must do to take + responsibility for job control. +* Launching Jobs:: Creating jobs to execute commands. +* Foreground and Background:: Putting a job in foreground of background. +* Stopped and Terminated Jobs:: Reporting job status. +* Continuing Stopped Jobs:: How to continue a stopped job in + the foreground or background. +* Missing Pieces:: Other parts of the shell. + +Functions for Job Control + +* Identifying the Terminal:: Determining the controlling terminal's name. +* Process Group Functions:: Functions for manipulating process groups. +* Terminal Access Functions:: Functions for controlling terminal access. + +Users and Groups + +* User and Group IDs:: Each user and group has a unique numeric ID. +* Process Persona:: The user IDs and group IDs of a process. +* Why Change Persona:: Why a program might need to change + its user and/or group IDs. +* How Change Persona:: Restrictions on changing user and group IDs. +* Reading Persona:: Examining the process's user and group IDs. +* Setting User ID:: +* Setting Groups:: +* Enable/Disable Setuid:: +* Setuid Program Example:: Setuid Program Example +* Tips for Setuid:: +* Who Logged In:: Getting the name of the user who logged in, + or of the real user ID of the current process. + +* User Database:: Functions and data structures for + accessing the user database. +* Group Database:: Functions and data structures for + accessing the group database. +* Database Example:: Example program showing use of database + inquiry functions. + +User Database + +* User Data Structure:: +* Lookup User:: +* Scanning All Users:: Scanning the List of All Users +* Writing a User Entry:: + +Group Database + +* Group Data Structure:: +* Lookup Group:: +* Scanning All Groups:: Scanning the List of All Groups + +System Information + +* Host Identification:: Determining the name of the machine. +* Hardware/Software Type ID:: Determining the hardware type and + operating system type. + +System Configuration Limits + +* General Limits:: Constants and functions that describe + various process-related limits that have + one uniform value for any given machine. +* System Options:: Optional POSIX features. +* Version Supported:: Version numbers of POSIX.1 and POSIX.2. +* Sysconf:: Getting specific configuration values + of general limits and system options. +* Minimums:: Minimum values for general limits. + +* Limits for Files:: Size limitations on individual files. + These can vary between file systems + or even from file to file. +* Options for Files:: Optional features that some files may support. +* File Minimums:: Minimum values for file limits. +* Pathconf:: Getting the limit values for a particular file. + +* Utility Limits:: Capacity limits of POSIX.2 utility programs. +* Utility Minimums:: Minimum allowable values of those limits. + +* String Parameters:: Getting the default search path. + +Library Facilities that are Part of the C Language + +* Consistency Checking:: Using @code{assert} to abort + if something ``impossible'' happens. +* Variadic Functions:: Defining functions with varying + numbers of arguments. +* Null Pointer Constant:: The macro @code{NULL}. +* Important Data Types:: Data types for object sizes. +* Data Type Measurements:: Parameters of data type representations. + +Variadic Functions + +* Why Variadic:: Reasons for making functions take + variable arguments. +* How Variadic:: How to define and call variadic functions. +* Argument Macros:: Detailed specification of the macros + for accessing variable arguments. +* Variadic Example:: A complete example. + +How Variadic Functions are Defined and Used + +* Variadic Prototypes:: How to make a prototype for a function + with variable arguments. +* Receiving Arguments:: Steps you must follow to access the + optional argument values. +* How Many Arguments:: How to decide whether there are more arguments. +* Calling Variadics:: Things you need to know about calling + variable arguments functions. + +Data Type Measurements + +* Width of Type:: How many bits does an integer type hold? +* Range of Type:: What are the largest and smallest values + that an integer type can hold? +* Floating Type Macros:: Parameters that measure floating-point types. +* Structure Measurement:: Getting measurements on structure types. + +Floating Type Macros + +* Floating Point Concepts:: Definitions of terminology. +* Floating Point Parameters:: Dimensions, limits of floating point types. +* IEEE Floating Point:: How one common representation is described. + +Library Maintenance + +* Installation:: How to configure, compile and install + the GNU C library. +* Reporting Bugs:: How to report bugs (if you want to + get them fixed) and other troubles + you may have with the GNU C library. +* Porting:: How to port the GNU C library to + a new machine or operating system. +@c * Traditional C Compatibility:: Using the GNU C library with non-ANSI +@c C compilers. +* Contributors:: Who wrote what parts of the GNU C Library. + +Porting the GNU C Library + +* Hierarchy Conventions:: How the @file{sysdeps} hierarchy is + layed out. +* Porting to Unix:: Porting the library to an average + Unix-like system. +@end menu + + +@comment Includes of all the individual chapters. +@include intro.texi +@include errno.texi +@include memory.texi +@include ctype.texi +@include string.texi +@include io.texi +@include stdio.texi +@include llio.texi +@include filesys.texi +@include pipe.texi +@include socket.texi +@include terminal.texi +@include math.texi +@include arith.texi +@include search.texi +@include pattern.texi +@include time.texi +@include mbyte.texi +@include locale.texi +@include setjmp.texi +@include signal.texi +@include startup.texi +@include process.texi +@include job.texi +@include users.texi +@include sysinfo.texi +@include conf.texi + +@comment Includes of the appendices. +@include lang.texi +@include header.texi +@include maint.texi + + +@set lgpl-appendix +@node Copying, Concept Index, Maintenance, Top +@include lgpl.texinfo + + +@node Concept Index, Type Index, Copying, Top +@unnumbered Concept Index + +@printindex cp + +@node Type Index, Function Index, Concept Index, Top +@unnumbered Type Index + +@printindex tp + +@node Function Index, Variable Index, Type Index, Top +@unnumbered Function and Macro Index + +@printindex fn + +@node Variable Index, File Index, Function Index, Top +@unnumbered Variable and Constant Macro Index + +@printindex vr + +@node File Index, , Variable Index, Top +@unnumbered Program and File Index + +@printindex pg + + +@shortcontents +@contents +@bye |