]>
Commit | Line | Data |
---|---|---|
28f540f4 RM |
1 | \input texinfo @c -*- Texinfo -*- |
2 | @comment %**start of header (This is for running Texinfo on a region.) | |
3 | @setfilename libc.info | |
4 | @settitle The GNU C Library | |
5 | @setchapternewpage odd | |
6 | @comment %**end of header (This is for running Texinfo on a region.) | |
7 | ||
8 | @c This tells texinfo.tex to use the real section titles in xrefs in | |
9 | @c place of the node name, when no section title is explicitly given. | |
10 | @set xref-automatic-section-title | |
11 | @smallbook | |
12 | ||
b8fe19fa RM |
13 | @c sold 0.06/1.09, print run out 21may96 |
14 | @set EDITION 0.07 DRAFT | |
28f540f4 | 15 | @set VERSION 1.09 Beta |
b8fe19fa | 16 | @set UPDATED 21 May 1996 |
28f540f4 RM |
17 | @set ISBN 1-882114-53-1 |
18 | ||
19 | @ifinfo | |
20 | This file documents the GNU C library. | |
21 | ||
22 | This is Edition @value{EDITION}, last updated @value{UPDATED}, | |
23 | of @cite{The GNU C Library Reference Manual}, for Version @value{VERSION}. | |
24 | ||
b8fe19fa | 25 | Copyright (C) 1993, '94, '95, '96 Free Software Foundation, Inc. |
28f540f4 RM |
26 | |
27 | Permission is granted to make and distribute verbatim copies of | |
28 | this manual provided the copyright notice and this permission notice | |
29 | are preserved on all copies. | |
30 | ||
31 | @ignore | |
32 | Permission is granted to process this file through TeX and print the | |
33 | results, provided the printed document carries copying permission | |
34 | notice identical to this one except for the removal of this paragraph | |
35 | (this paragraph not being relevant to the printed manual). | |
36 | ||
37 | @end ignore | |
38 | Permission is granted to copy and distribute modified versions of this | |
39 | manual under the conditions for verbatim copying, provided also that the | |
40 | section entitled ``GNU Library General Public License'' is included | |
41 | exactly as in the original, and provided that the entire resulting | |
42 | derived work is distributed under the terms of a permission notice | |
43 | identical to this one. | |
44 | ||
45 | Permission is granted to copy and distribute translations of this manual | |
46 | Library General Public License'' must be approved for accuracy by the | |
47 | Foundation. | |
48 | @end ifinfo | |
49 | ||
50 | @iftex | |
51 | @shorttitlepage The GNU C Library Reference Manual | |
52 | @end iftex | |
53 | @titlepage | |
54 | @center @titlefont{The GNU C Library} | |
55 | @sp 1 | |
56 | @center @titlefont{Reference Manual} | |
57 | @sp 2 | |
58 | @center Sandra Loosemore | |
59 | @center with | |
60 | @center Richard M. Stallman, Roland McGrath, and Andrew Oram | |
61 | @sp 3 | |
62 | @center Edition @value{EDITION} | |
63 | @sp 1 | |
64 | @center last updated @value{UPDATED} | |
65 | @sp 1 | |
66 | @center for version @value{VERSION} | |
67 | @page | |
68 | @vskip 0pt plus 1filll | |
b8fe19fa | 69 | Copyright @copyright{} 1993, '94, '95, '96 Free Software Foundation, Inc. |
28f540f4 RM |
70 | @sp 2 |
71 | Published by the Free Software Foundation @* | |
b8fe19fa RM |
72 | 59 Temple Place -- Suite 330, @* |
73 | Boston, MA 02111-1307 USA @* | |
28f540f4 RM |
74 | Printed copies are available for $50 each. @* |
75 | ISBN @value{ISBN} @* | |
76 | ||
77 | Permission is granted to make and distribute verbatim copies of | |
78 | this manual provided the copyright notice and this permission notice | |
79 | are preserved on all copies. | |
80 | ||
81 | Permission is granted to copy and distribute modified versions of this | |
82 | manual under the conditions for verbatim copying, provided also that the | |
83 | section entitled ``GNU Library General Public License'' is included | |
84 | exactly as in the original, and provided that the entire resulting | |
85 | derived work is distributed under the terms of a permission notice | |
86 | identical to this one. | |
87 | ||
88 | Permission is granted to copy and distribute translations of this manual | |
89 | into another language, under the above conditions for modified versions, | |
90 | except that the text of the translation of the section entitled ``GNU | |
91 | Library General Public License'' must be approved for accuracy by the | |
92 | Foundation. | |
93 | @end titlepage | |
94 | @page | |
95 | ||
96 | @ifinfo | |
97 | @node Top, Introduction, (dir), (dir) | |
98 | @top Main Menu | |
99 | This is Edition @value{EDITION}, last updated @value{UPDATED}, of | |
100 | @cite{The GNU C Library Reference Manual}, for Version @value{VERSION} | |
101 | of the GNU C Library. | |
102 | @end ifinfo | |
103 | ||
104 | ||
105 | @menu | |
106 | * Introduction:: Purpose of the GNU C Library. | |
107 | * Error Reporting:: How the GNU Library functions report | |
108 | error conditions. | |
109 | * Memory Allocation:: Your program can allocate memory dynamically | |
110 | and manipulate it via pointers. | |
111 | * Character Handling:: Character testing and conversion functions. | |
112 | * String and Array Utilities:: Utilities for copying and comparing | |
113 | strings and arrays. | |
114 | * Extended Characters:: Support for extended character sets. | |
115 | * Locales:: The country and language can affect | |
116 | the behavior of library functions. | |
117 | * Searching and Sorting:: General searching and sorting functions. | |
118 | * Pattern Matching:: Matching wildcards and regular expressions, | |
119 | and shell-style ``word expansion''. | |
120 | * I/O Overview:: Introduction to the I/O facilities. | |
121 | * Streams: I/O on Streams. High-level, portable I/O facilities. | |
122 | * Low-Level I/O:: Low-level, less portable I/O. | |
123 | * File System Interface:: Functions for manipulating files. | |
124 | * Pipes and FIFOs:: A simple interprocess communication mechanism. | |
125 | * Sockets:: A more complicated interprocess communication | |
126 | mechanism, with support for networking. | |
127 | * Low-Level Terminal Interface::How to change the characteristics | |
128 | of a terminal device. | |
129 | * Mathematics:: Math functions (transcendental functions, | |
130 | random numbers, absolute value, etc.). | |
131 | * Arithmetic:: Low-level arithmetic functions. | |
132 | * Date and Time:: Functions for getting the date and time, | |
133 | and for conversion between formats. | |
134 | * Non-Local Exits:: The @code{setjmp} and @code{longjmp} facilities. | |
135 | * Signal Handling:: All about signals; how to send them, | |
136 | block them, and handle them. | |
137 | * Process Startup:: Writing the beginning and end of your program. | |
138 | * Processes:: How to create processes and run other programs. | |
139 | * Job Control:: All about process groups and sessions. | |
140 | * Users and Groups:: How users are identified and classified. | |
141 | * System Information:: Getting information about the | |
142 | hardware and software configuration | |
143 | of the machine a program runs on. | |
144 | * System Configuration:: Parameters describing operating system limits. | |
145 | ||
146 | Appendices | |
147 | ||
b8fe19fa | 148 | * Language Features:: C language features provided by the library. |
28f540f4 RM |
149 | |
150 | * Library Summary:: A summary showing the syntax, header file, | |
151 | and derivation of each library feature. | |
152 | * Maintenance:: How to install and maintain the GNU C Library. | |
153 | * Copying:: The GNU Library General Public License says | |
154 | how you can copy and share the GNU C Library. | |
155 | ||
156 | Indices | |
157 | ||
158 | * Concept Index:: Index of concepts and names. | |
159 | * Type Index:: Index of types and type qualifiers. | |
160 | * Function Index:: Index of functions and function-like macros. | |
161 | * Variable Index:: Index of variables and variable-like macros. | |
162 | * File Index:: Index of programs and files. | |
163 | ||
164 | --- The Detailed Node Listing --- | |
165 | ||
166 | Introduction | |
167 | ||
168 | * Getting Started:: Getting Started | |
169 | * Standards and Portability:: Standards and Portability | |
170 | * Using the Library:: Using the Library | |
171 | * Roadmap to the Manual:: Roadmap to the Manual | |
172 | ||
173 | Standards and Portability | |
174 | ||
175 | * ANSI C:: The American National Standard for the | |
b8fe19fa | 176 | C programming language. |
28f540f4 RM |
177 | * POSIX:: The IEEE 1003 standards for operating systems. |
178 | * Berkeley Unix:: BSD and SunOS. | |
b8fe19fa | 179 | * SVID:: The System V Interface Description. |
28f540f4 RM |
180 | |
181 | Using the Library | |
182 | ||
183 | * Header Files:: How to use the header files in your programs. | |
184 | * Macro Definitions:: Some functions in the library may really | |
185 | be implemented as macros. | |
186 | * Reserved Names:: The C standard reserves some names for | |
187 | the library, and some for users. | |
188 | * Feature Test Macros:: How to control what names are defined. | |
189 | ||
190 | Error Reporting | |
191 | ||
192 | * Checking for Errors:: How errors are reported by library functions. | |
193 | * Error Codes:: What all the error codes are. | |
194 | * Error Messages:: Mapping error codes onto error messages. | |
195 | ||
196 | Memory Allocation | |
197 | ||
198 | * Memory Concepts:: An introduction to concepts and terminology. | |
199 | * Dynamic Allocation and C:: How to get different kinds of allocation in C. | |
200 | * Unconstrained Allocation:: The @code{malloc} facility allows fully general | |
201 | dynamic allocation. | |
202 | * Obstacks:: Obstacks are less general than malloc | |
203 | but more efficient and convenient. | |
204 | * Variable Size Automatic:: Allocation of variable-sized blocks | |
205 | of automatic storage that are freed when the | |
206 | calling function returns. | |
207 | * Relocating Allocator:: Waste less memory, if you can tolerate | |
208 | automatic relocation of the blocks you get. | |
209 | * Memory Warnings:: Getting warnings when memory is nearly full. | |
210 | ||
211 | Unconstrained Allocation | |
212 | ||
213 | * Basic Allocation:: Simple use of @code{malloc}. | |
214 | * Malloc Examples:: Examples of @code{malloc}. @code{xmalloc}. | |
215 | * Freeing after Malloc:: Use @code{free} to free a block you | |
216 | got with @code{malloc}. | |
217 | * Changing Block Size:: Use @code{realloc} to make a block | |
218 | bigger or smaller. | |
219 | * Allocating Cleared Space:: Use @code{calloc} to allocate a | |
220 | block and clear it. | |
221 | * Efficiency and Malloc:: Efficiency considerations in use of | |
222 | these functions. | |
223 | * Aligned Memory Blocks:: Allocating specially aligned memory: | |
224 | @code{memalign} and @code{valloc}. | |
225 | * Heap Consistency Checking:: Automatic checking for errors. | |
226 | * Hooks for Malloc:: You can use these hooks for debugging | |
227 | programs that use @code{malloc}. | |
228 | * Statistics of Malloc:: Getting information about how much | |
229 | memory your program is using. | |
230 | * Summary of Malloc:: Summary of @code{malloc} and related functions. | |
231 | ||
232 | Obstacks | |
233 | ||
234 | * Creating Obstacks:: How to declare an obstack in your program. | |
235 | * Preparing for Obstacks:: Preparations needed before you can | |
236 | use obstacks. | |
237 | * Allocation in an Obstack:: Allocating objects in an obstack. | |
238 | * Freeing Obstack Objects:: Freeing objects in an obstack. | |
239 | * Obstack Functions:: The obstack functions are both | |
240 | functions and macros. | |
241 | * Growing Objects:: Making an object bigger by stages. | |
242 | * Extra Fast Growing:: Extra-high-efficiency (though more | |
243 | complicated) growing objects. | |
244 | * Status of an Obstack:: Inquiries about the status of an obstack. | |
245 | * Obstacks Data Alignment:: Controlling alignment of objects in obstacks. | |
b8fe19fa | 246 | * Obstack Chunks:: How obstacks obtain and release chunks. |
28f540f4 | 247 | Efficiency considerations. |
b8fe19fa | 248 | * Summary of Obstacks:: |
28f540f4 RM |
249 | |
250 | Automatic Storage with Variable Size | |
251 | ||
252 | * Alloca Example:: Example of using @code{alloca}. | |
253 | * Advantages of Alloca:: Reasons to use @code{alloca}. | |
254 | * Disadvantages of Alloca:: Reasons to avoid @code{alloca}. | |
255 | * GNU C Variable-Size Arrays:: Only in GNU C, here is an alternative | |
256 | method of allocating dynamically and | |
257 | freeing automatically. | |
258 | Relocating Allocator | |
259 | ||
260 | * Relocator Concepts:: How to understand relocating allocation. | |
261 | * Using Relocator:: Functions for relocating allocation. | |
262 | ||
263 | Character Handling | |
264 | ||
265 | * Classification of Characters::Testing whether characters are | |
266 | letters, digits, punctuation, etc. | |
267 | * Case Conversion:: Case mapping, and the like. | |
268 | ||
269 | String and Array Utilities | |
270 | ||
271 | * Representation of Strings:: Introduction to basic concepts. | |
272 | * String/Array Conventions:: Whether to use a string function or an | |
273 | arbitrary array function. | |
274 | * String Length:: Determining the length of a string. | |
275 | * Copying and Concatenation:: Functions to copy the contents of strings | |
276 | and arrays. | |
277 | * String/Array Comparison:: Functions for byte-wise and character-wise | |
278 | comparison. | |
279 | * Collation Functions:: Functions for collating strings. | |
280 | * Search Functions:: Searching for a specific element or substring. | |
281 | * Finding Tokens in a String:: Splitting a string into tokens by looking | |
282 | for delimiters. | |
283 | ||
284 | Extended Characters | |
285 | ||
286 | * Extended Char Intro:: Multibyte codes versus wide characters. | |
287 | * Locales and Extended Chars:: The locale selects the character codes. | |
288 | * Multibyte Char Intro:: How multibyte codes are represented. | |
289 | * Wide Char Intro:: How wide characters are represented. | |
290 | * Wide String Conversion:: Converting wide strings to multibyte code | |
291 | and vice versa. | |
292 | * Length of Char:: how many bytes make up one multibyte char. | |
293 | * Converting One Char:: Converting a string character by character. | |
b8fe19fa | 294 | * Example of Conversion:: Example showing why converting |
28f540f4 RM |
295 | one character at a time may be useful. |
296 | * Shift State:: Multibyte codes with "shift characters". | |
297 | ||
298 | Locales and Internationalization | |
299 | ||
300 | * Effects of Locale:: Actions affected by the choice of locale. | |
301 | * Choosing Locale:: How the user specifies a locale. | |
302 | * Locale Categories:: Different purposes for which | |
303 | you can select a locale. | |
304 | * Setting the Locale:: How a program specifies the locale. | |
305 | * Standard Locales:: Locale names available on all systems. | |
306 | * Numeric Formatting:: How to format numbers for the chosen locale. | |
307 | ||
b8fe19fa | 308 | Searching and Sorting |
28f540f4 RM |
309 | |
310 | * Comparison Functions:: Defining how to compare two objects. | |
311 | Since the sort and search facilities are | |
312 | general, you have to specify the ordering. | |
313 | * Array Search Function:: The @code{bsearch} function. | |
314 | * Array Sort Function:: The @code{qsort} function. | |
315 | * Search/Sort Example:: An example program. | |
316 | ||
317 | Pattern Matching | |
318 | ||
319 | * Wildcard Matching:: Matching a wildcard pattern against a single string. | |
320 | * Globbing:: Finding the files that match a wildcard pattern. | |
321 | * Regular Expressions:: Matching regular expressions against strings. | |
322 | * Word Expansion:: Expanding shell variables, nested commands, | |
323 | arithmetic, and wildcards. | |
324 | This is what the shell does with shell commands. | |
325 | ||
326 | I/O Overview | |
327 | ||
328 | * I/O Concepts:: Some basic information and terminology. | |
329 | * File Names:: How to refer to a file. | |
330 | ||
331 | I/O Concepts | |
332 | ||
333 | * Streams and File Descriptors:: The GNU Library provides two ways | |
334 | to access the contents of files. | |
335 | * File Position:: The number of bytes from the | |
336 | beginning of the file. | |
337 | ||
338 | File Names | |
339 | ||
340 | * Directories:: Directories contain entries for files. | |
341 | * File Name Resolution:: A file name specifies how to look up a file. | |
342 | * File Name Errors:: Error conditions relating to file names. | |
343 | * File Name Portability:: File name portability and syntax issues. | |
344 | ||
345 | I/O on Streams | |
346 | ||
347 | * Streams:: About the data type representing a stream. | |
b8fe19fa | 348 | * Standard Streams:: Streams to the standard input and output |
28f540f4 RM |
349 | devices are created for you. |
350 | * Opening Streams:: How to create a stream to talk to a file. | |
351 | * Closing Streams:: Close a stream when you are finished with it. | |
352 | * Simple Output:: Unformatted output by characters and lines. | |
353 | * Character Input:: Unformatted input by characters and words. | |
354 | * Line Input:: Reading a line or a record from a stream. | |
355 | * Unreading:: Peeking ahead/pushing back input just read. | |
356 | * Formatted Output:: @code{printf} and related functions. | |
357 | * Customizing Printf:: You can define new conversion specifiers for | |
358 | @code{printf} and friends. | |
359 | * Formatted Input:: @code{scanf} and related functions. | |
360 | * Block Input/Output:: Input and output operations on blocks of data. | |
361 | * EOF and Errors:: How you can tell if an I/O error happens. | |
362 | * Binary Streams:: Some systems distinguish between text files | |
363 | and binary files. | |
364 | * File Positioning:: About random-access streams. | |
365 | * Portable Positioning:: Random access on peculiar ANSI C systems. | |
366 | * Stream Buffering:: How to control buffering of streams. | |
367 | * Temporary Files:: How to open a temporary file. | |
368 | * Other Kinds of Streams:: Other Kinds of Streams | |
369 | ||
370 | Unreading | |
371 | ||
372 | * Unreading Idea:: An explanation of unreading with pictures. | |
373 | * How Unread:: How to call @code{ungetc} to do unreading. | |
374 | ||
375 | Formatted Output | |
376 | ||
377 | * Formatted Output Basics:: Some examples to get you started. | |
378 | * Output Conversion Syntax:: General syntax of conversion specifications. | |
379 | * Table of Output Conversions:: Summary of output conversions, what they do. | |
380 | * Integer Conversions:: Details of formatting integers. | |
381 | * Floating-Point Conversions:: Details of formatting floating-point numbers. | |
382 | * Other Output Conversions:: Details about formatting of strings, | |
383 | characters, pointers, and the like. | |
384 | * Formatted Output Functions:: Descriptions of the actual functions. | |
385 | * Variable Arguments Output:: @code{vprintf} and friends. | |
386 | * Parsing a Template String:: What kinds of arguments does | |
387 | a given template call for? | |
388 | ||
389 | Customizing Printf | |
390 | ||
b8fe19fa RM |
391 | * Registering New Conversions:: |
392 | * Conversion Specifier Options:: | |
393 | * Defining the Output Handler:: | |
394 | * Printf Extension Example:: | |
28f540f4 RM |
395 | |
396 | Formatted Input | |
397 | ||
398 | * Formatted Input Basics:: Some basics to get you started. | |
399 | * Input Conversion Syntax:: Syntax of conversion specifications. | |
400 | * Table of Input Conversions:: Summary of input conversions and what they do. | |
401 | * Numeric Input Conversions:: Details of conversions for reading numbers. | |
402 | * String Input Conversions:: Details of conversions for reading strings. | |
403 | * Other Input Conversions:: Details of miscellaneous other conversions. | |
404 | * Formatted Input Functions:: Descriptions of the actual functions. | |
405 | * Variable Arguments Input:: @code{vscanf} and friends. | |
406 | ||
407 | Stream Buffering | |
408 | ||
409 | * Buffering Concepts:: Terminology is defined here. | |
410 | * Flushing Buffers:: How to ensure that output buffers are flushed. | |
411 | * Controlling Buffering:: How to specify what kind of buffering to use. | |
412 | ||
413 | Other Kinds of Streams | |
414 | ||
b8fe19fa RM |
415 | * String Streams:: |
416 | * Custom Streams:: | |
28f540f4 RM |
417 | |
418 | Programming Your Own Custom Streams | |
419 | ||
b8fe19fa RM |
420 | * Streams and Cookies:: |
421 | * Hook Functions:: | |
28f540f4 RM |
422 | |
423 | Low-Level I/O | |
424 | ||
425 | * Opening and Closing Files:: How to open and close file descriptors. | |
426 | * I/O Primitives:: Reading and writing data. | |
427 | * File Position Primitive:: Setting a descriptor's file position. | |
428 | * Descriptors and Streams:: Converting descriptor to stream or vice-versa. | |
429 | * Stream/Descriptor Precautions:: Precautions needed if you use both | |
430 | descriptors and streams. | |
431 | * Waiting for I/O:: How to check for input or output | |
432 | on multiple file descriptors. | |
433 | * Control Operations:: Various other operations on file descriptors. | |
434 | * Duplicating Descriptors:: Fcntl commands for duplicating descriptors. | |
435 | * Descriptor Flags:: Fcntl commands for manipulating flags | |
436 | associated with file descriptors. | |
437 | * File Status Flags:: Fcntl commands for manipulating flags | |
438 | associated with open files. | |
439 | * File Locks:: Fcntl commands for implementing file locking. | |
440 | * Interrupt Input:: Getting a signal when input arrives. | |
441 | ||
442 | File System Interface | |
443 | ||
444 | * Working Directory:: This is used to resolve relative file names. | |
445 | * Accessing Directories:: Finding out what files a directory contains. | |
446 | * Hard Links:: Adding alternate names to a file. | |
447 | * Symbolic Links:: A file that ``points to'' a file name. | |
448 | * Deleting Files:: How to delete a file, and what that means. | |
449 | * Renaming Files:: Changing a file's name. | |
450 | * Creating Directories:: A system call just for creating a directory. | |
451 | * File Attributes:: Attributes of individual files. | |
452 | * Making Special Files:: How to create special files. | |
453 | ||
454 | Accessing Directories | |
455 | ||
456 | * Directory Entries:: Format of one directory entry. | |
457 | * Opening a Directory:: How to open a directory stream. | |
458 | * Reading/Closing Directory:: How to read directory entries from the stream. | |
459 | * Simple Directory Lister:: A very simple directory listing program. | |
460 | * Random Access Directory:: Rereading part of the directory | |
461 | already read with the same stream. | |
462 | ||
463 | File Attributes | |
464 | ||
465 | * Attribute Meanings:: The names of the file attributes, | |
466 | and what their values mean. | |
467 | * Reading Attributes:: How to read the attributes of a file. | |
468 | * Testing File Type:: Distinguishing ordinary files, | |
469 | directories, links... | |
470 | * File Owner:: How ownership for new files is determined, | |
471 | and how to change it. | |
472 | * Permission Bits:: How information about a file's access mode | |
473 | is stored. | |
474 | * Access Permission:: How the system decides who can access a file. | |
475 | * Setting Permissions:: How permissions for new files are assigned, | |
476 | and how to change them. | |
477 | * Testing File Access:: How to find out if your process can | |
478 | access a file. | |
479 | * File Times:: About the time attributes of a file. | |
480 | ||
481 | Pipes and FIFOs | |
482 | ||
483 | * Creating a Pipe:: Making a pipe with the @code{pipe} function. | |
484 | * Pipe to a Subprocess:: Using a pipe to communicate with a child. | |
485 | * FIFO Special Files:: Making a FIFO special file. | |
486 | ||
487 | Sockets | |
488 | ||
489 | * Socket Concepts:: Basic concepts you need to know about. | |
490 | * Communication Styles:: Stream communication, datagrams, and others. | |
491 | * Socket Addresses:: How socket names (``addresses'') work. | |
492 | * File Namespace:: Details about the file namespace. | |
493 | * Internet Namespace:: Details about the Internet namespace. | |
494 | * Open/Close Sockets:: Creating sockets and destroying them. | |
495 | * Connections:: Operations on sockets with connection state. | |
496 | * Datagrams:: Operations on datagram sockets. | |
497 | * Socket Options:: Miscellaneous low-level socket options. | |
498 | * Networks Database:: Accessing the database of network names. | |
499 | ||
500 | Socket Addresses | |
501 | ||
502 | * Address Formats:: About @code{struct sockaddr}. | |
503 | * Setting Address:: Binding an address to a socket. | |
504 | * Reading Address:: Reading the address of a socket. | |
505 | ||
506 | Internet Domain | |
507 | ||
508 | * Internet Address Format:: How socket addresses are specified in the | |
509 | Internet namespace. | |
510 | * Host Addresses:: All about host addresses of Internet hosts. | |
511 | * Protocols Database:: Referring to protocols by name. | |
512 | * Services Database:: Ports may have symbolic names. | |
513 | * Byte Order:: Different hosts may use different byte | |
514 | ordering conventions; you need to | |
b8fe19fa | 515 | canonicalize host address and port number. |
28f540f4 RM |
516 | * Inet Example:: Putting it all together. |
517 | ||
518 | Host Addresses | |
519 | ||
520 | * Abstract Host Addresses:: What a host number consists of. | |
521 | * Data type: Host Address Data Type. Data type for a host number. | |
522 | * Functions: Host Address Functions. Functions to operate on them. | |
523 | * Names: Host Names. Translating host names to host numbers. | |
524 | ||
525 | Open/Close Sockets | |
526 | ||
527 | * Creating a Socket:: How to open a socket. | |
528 | * Closing a Socket:: How to close a socket. | |
529 | * Socket Pairs:: These are created like pipes. | |
530 | ||
531 | Connections | |
532 | ||
533 | * Connecting:: What the client program must do. | |
534 | * Listening:: How a server program waits for requests. | |
535 | * Accepting Connections:: What the server does when it gets a request. | |
536 | * Who is Connected:: Getting the address of the | |
537 | other side of a connection. | |
538 | * Transferring Data:: How to send and receive data. | |
539 | * Byte Stream Example:: An example client for communicating over a | |
540 | byte stream socket in the Internet namespace. | |
541 | * Server Example:: A corresponding server program. | |
542 | * Out-of-Band Data:: This is an advanced feature. | |
543 | ||
544 | Transferring Data | |
545 | ||
546 | * Sending Data:: Sending data with @code{write}. | |
547 | * Receiving Data:: Reading data with @code{read}. | |
548 | * Socket Data Options:: Using @code{send} and @code{recv}. | |
549 | ||
550 | Datagrams | |
551 | ||
552 | * Sending Datagrams:: Sending packets on a datagram socket. | |
553 | * Receiving Datagrams:: Receiving packets on a datagram socket. | |
554 | * Datagram Example:: An example program: packets sent over a | |
555 | datagram stream in the file namespace. | |
556 | * Example Receiver:: Another program, that receives those packets. | |
557 | ||
558 | Socket Options | |
559 | ||
560 | * Socket Option Functions:: The basic functions for setting and getting | |
561 | socket options. | |
562 | * Socket-Level Options:: Details of the options at the socket level. | |
563 | ||
564 | Low-Level Terminal Interface | |
565 | ||
566 | * Is It a Terminal:: How to determine if a file is a terminal | |
567 | device, and what its name is. | |
568 | * I/O Queues:: About flow control and typeahead. | |
569 | * Canonical or Not:: Two basic styles of input processing. | |
570 | * Terminal Modes:: How to examine and modify flags controlling | |
571 | terminal I/O: echoing, signals, editing. | |
572 | * Line Control:: Sending break sequences, clearing buffers... | |
573 | * Noncanon Example:: How to read single characters without echo. | |
574 | ||
575 | Terminal Modes | |
576 | ||
577 | * Mode Data Types:: The data type @code{struct termios} and related types. | |
578 | * Mode Functions:: Functions to read and set terminal attributes. | |
579 | * Setting Modes:: The right way to set attributes reliably. | |
580 | * Input Modes:: Flags controlling low-level input handling. | |
581 | * Output Modes:: Flags controlling low-level output handling. | |
582 | * Control Modes:: Flags controlling serial port behavior. | |
583 | * Local Modes:: Flags controlling high-level input handling. | |
584 | * Line Speed:: How to read and set the terminal line speed. | |
585 | * Special Characters:: Characters that have special effects, | |
586 | and how to change them. | |
587 | * Noncanonical Input:: Controlling how long to wait for input. | |
588 | ||
589 | Special Characters | |
590 | ||
b8fe19fa RM |
591 | * Editing Characters:: |
592 | * Signal Characters:: | |
593 | * Start/Stop Characters:: | |
28f540f4 RM |
594 | |
595 | Mathematics | |
596 | ||
597 | * Domain and Range Errors:: How overflow conditions and the | |
598 | like are reported. | |
599 | * Not a Number:: Making NANs and testing for NANs. | |
600 | * Trig Functions:: Sine, cosine, and tangent. | |
601 | * Inverse Trig Functions:: Arc sine, arc cosine, and arc tangent. | |
602 | * Exponents and Logarithms:: Also includes square root. | |
603 | * Hyperbolic Functions:: Hyperbolic sine and friends. | |
604 | * Pseudo-Random Numbers:: Functions for generating pseudo-random numbers. | |
605 | * Absolute Value:: Absolute value functions. | |
606 | ||
607 | Pseudo-Random Numbers | |
608 | ||
609 | * ANSI Random:: @code{rand} and friends. | |
610 | * BSD Random:: @code{random} and friends. | |
611 | ||
612 | Low-Level Arithmetic Functions | |
613 | ||
614 | * Normalization Functions:: Hacks for radix-2 representations. | |
615 | * Rounding and Remainders:: Determinining the integer and | |
616 | fractional parts of a float. | |
617 | * Integer Division:: Functions for performing integer division. | |
618 | * Parsing of Numbers:: Functions for ``reading'' numbers from strings. | |
619 | * Predicates on Floats:: Some miscellaneous test functions. | |
620 | ||
621 | Parsing of Numbers | |
622 | ||
623 | * Parsing of Integers:: Functions for conversion of integer values. | |
624 | * Parsing of Floats:: Functions for conversion of floating-point. | |
625 | ||
626 | Date and Time | |
627 | ||
628 | * Processor Time:: Measures processor time used by a program. | |
629 | * Calendar Time:: Manipulation of ``real'' dates and times. | |
630 | * Setting an Alarm:: Sending a signal after a specified time. | |
631 | * Sleeping:: Waiting for a period of time. | |
632 | ||
633 | Processor Time | |
634 | ||
635 | * Basic CPU Time:: The @code{clock} function. | |
636 | * Detailed CPU Time:: The @code{times} function. | |
637 | ||
638 | Calendar Time | |
639 | ||
640 | * Simple Calendar Time:: Facilities for manipulating calendar time. | |
641 | * High-Resolution Calendar:: A time representation with greater precision. | |
642 | * Broken-down Time:: Facilities for manipulating local time. | |
643 | * Formatting Date and Time:: Converting times to strings. | |
644 | * TZ Variable:: How users specify the time zone. | |
645 | * Time Zone Functions:: Functions to examine or specify the time zone. | |
646 | * Time Functions Example:: An example program showing use of some of | |
647 | the time functions. | |
648 | ||
649 | Signal Handling | |
650 | ||
651 | * Concepts of Signals:: Introduction to the signal facilities. | |
652 | * Standard Signals:: Particular kinds of signals with standard | |
653 | names and meanings. | |
654 | * Signal Actions:: Specifying what happens when a particular | |
655 | signal is delivered. | |
656 | * Defining Handlers:: How to write a signal handler function. | |
657 | * Generating Signals:: How to send a signal to a process. | |
658 | * Blocking Signals:: Making the system hold signals temporarily. | |
659 | * Waiting for a Signal:: Suspending your program until a signal arrives. | |
660 | * Signal Stack:: Using a Separate Signal Stack | |
661 | * BSD Signal Handling:: Additional functions for backward | |
662 | compatibility with BSD. | |
663 | ||
664 | Basic Concepts of Signals | |
665 | ||
666 | * Kinds of Signals:: Some examples of what can cause a signal. | |
667 | * Signal Generation:: Concepts of why and how signals occur. | |
668 | * Delivery of Signal:: Concepts of what a signal does to the process. | |
669 | ||
670 | Standard Signals | |
671 | ||
672 | * Program Error Signals:: Used to report serious program errors. | |
673 | * Termination Signals:: Used to interrupt and/or terminate the program. | |
674 | * Alarm Signals:: Used to indicate expiration of timers. | |
675 | * Asynchronous I/O Signals:: Used to indicate input is available. | |
676 | * Job Control Signals:: Signals used to support job control. | |
677 | * Operation Error Signals:: Used to report operational system errors. | |
678 | * Miscellaneous Signals:: Miscellaneous Signals. | |
679 | * Signal Messages:: Printing a message describing a signal. | |
680 | ||
681 | Specifying Signal Actions | |
682 | ||
683 | * Basic Signal Handling:: The simple @code{signal} function. | |
684 | * Advanced Signal Handling:: The more powerful @code{sigaction} function. | |
685 | * Signal and Sigaction:: How those two functions interact. | |
686 | * Sigaction Function Example:: An example of using the sigaction function. | |
687 | * Flags for Sigaction:: Specifying options for signal handling. | |
688 | * Initial Signal Actions:: How programs inherit signal actions. | |
689 | ||
690 | Defining Signal Handlers | |
691 | ||
b8fe19fa RM |
692 | * Handler Returns:: |
693 | * Termination in Handler:: | |
694 | * Longjmp in Handler:: | |
695 | * Signals in Handler:: | |
696 | * Nonreentrancy:: | |
697 | * Atomic Data Access:: | |
28f540f4 RM |
698 | |
699 | Generating Signals | |
700 | ||
701 | * Signaling Yourself:: Signaling Yourself | |
702 | * Signaling Another Process:: Send a signal to another process. | |
703 | * Permission for kill:: Permission for using @code{kill} | |
704 | * Kill Example:: Using @code{kill} for Communication | |
705 | ||
706 | Blocking Signals | |
707 | ||
708 | * Why Block:: The purpose of blocking signals. | |
709 | * Signal Sets:: How to specify which signals to block. | |
710 | * Process Signal Mask:: Blocking delivery of signals to your | |
711 | process during normal execution. | |
712 | * Testing for Delivery:: Blocking to Test for Delivery of a Signal | |
713 | * Blocking for Handler:: Blocking additional signals while a | |
714 | handler is being run. | |
715 | * Checking for Pending Signals::Checking for Pending Signals | |
716 | * Remembering a Signal:: How you can get almost the same effect | |
717 | as blocking a signal, by handling it | |
718 | and setting a flag to be tested later. | |
719 | ||
720 | Waiting for a Signal | |
721 | ||
722 | * Using Pause:: The simple way, using @code{pause}. | |
723 | * Pause Problems:: Why the simple way is often not very good. | |
724 | * Sigsuspend:: Reliably waiting for a specific signal. | |
725 | ||
726 | BSD Signal Handling | |
727 | ||
728 | * BSD Handler:: BSD Function to Establish a Handler. | |
b8fe19fa | 729 | * Blocking in BSD:: BSD Functions for Blocking Signals |
28f540f4 RM |
730 | |
731 | Process Startup and Termination | |
732 | ||
733 | * Program Arguments:: Parsing your program's command-line arguments. | |
734 | * Environment Variables:: How to access parameters inherited from | |
735 | a parent process. | |
736 | * Program Termination:: How to cause a process to terminate and | |
737 | return status information to its parent. | |
738 | ||
739 | Program Arguments | |
740 | ||
741 | * Argument Syntax:: By convention, options start with a hyphen. | |
742 | * Parsing Options:: The @code{getopt} function. | |
743 | * Example of Getopt:: An example of parsing options with @code{getopt}. | |
744 | * Long Options:: GNU utilities should accept long-named options. | |
745 | Here is how to do that. | |
746 | * Long Option Example:: An example of using @code{getopt_long}. | |
747 | ||
748 | Environment Variables | |
749 | ||
750 | * Environment Access:: How to get and set the values of | |
751 | environment variables. | |
752 | * Standard Environment:: These environment variables have | |
753 | standard interpretations. | |
754 | ||
755 | Program Termination | |
756 | ||
757 | * Normal Termination:: If a program calls @code{exit}, a | |
758 | process terminates normally. | |
b8fe19fa RM |
759 | * Exit Status:: The @code{exit status} provides information |
760 | about why the process terminated. | |
28f540f4 | 761 | * Cleanups on Exit:: A process can run its own cleanup |
b8fe19fa | 762 | functions upon normal termination. |
28f540f4 | 763 | * Aborting a Program:: The @code{abort} function causes |
b8fe19fa | 764 | abnormal program termination. |
28f540f4 RM |
765 | * Termination Internals:: What happens when a process terminates. |
766 | ||
767 | ||
768 | Child Processes | |
769 | ||
770 | * Running a Command:: The easy way to run another program. | |
771 | * Process Creation Concepts:: An overview of the hard way to do it. | |
772 | * Process Identification:: How to get the process ID of a process. | |
773 | * Creating a Process:: How to fork a child process. | |
774 | * Executing a File:: How to make a child execute another program. | |
775 | * Process Completion:: How to tell when a child process has completed. | |
b8fe19fa | 776 | * Process Completion Status:: How to interpret the status value |
28f540f4 RM |
777 | returned from a child process. |
778 | * BSD Wait Functions:: More functions, for backward compatibility. | |
779 | * Process Creation Example:: A complete example program. | |
780 | ||
781 | Job Control | |
782 | ||
783 | * Concepts of Job Control :: Concepts of Job Control | |
784 | * Job Control is Optional:: Not all POSIX systems support job control. | |
785 | * Controlling Terminal:: How a process gets its controlling terminal. | |
786 | * Access to the Terminal:: How processes share the controlling terminal. | |
787 | * Orphaned Process Groups:: Jobs left after the user logs out. | |
788 | * Implementing a Shell:: What a shell must do to implement job control. | |
789 | * Functions for Job Control:: Functions to control process groups. | |
790 | ||
791 | Implementing a Job Control Shell | |
792 | ||
793 | * Data Structures:: Introduction to the sample shell. | |
794 | * Initializing the Shell:: What the shell must do to take | |
795 | responsibility for job control. | |
796 | * Launching Jobs:: Creating jobs to execute commands. | |
797 | * Foreground and Background:: Putting a job in foreground of background. | |
798 | * Stopped and Terminated Jobs:: Reporting job status. | |
799 | * Continuing Stopped Jobs:: How to continue a stopped job in | |
800 | the foreground or background. | |
801 | * Missing Pieces:: Other parts of the shell. | |
802 | ||
803 | Functions for Job Control | |
804 | ||
805 | * Identifying the Terminal:: Determining the controlling terminal's name. | |
806 | * Process Group Functions:: Functions for manipulating process groups. | |
807 | * Terminal Access Functions:: Functions for controlling terminal access. | |
808 | ||
809 | Users and Groups | |
810 | ||
811 | * User and Group IDs:: Each user and group has a unique numeric ID. | |
812 | * Process Persona:: The user IDs and group IDs of a process. | |
813 | * Why Change Persona:: Why a program might need to change | |
814 | its user and/or group IDs. | |
815 | * How Change Persona:: Restrictions on changing user and group IDs. | |
816 | * Reading Persona:: Examining the process's user and group IDs. | |
b8fe19fa RM |
817 | * Setting User ID:: |
818 | * Setting Groups:: | |
819 | * Enable/Disable Setuid:: | |
28f540f4 | 820 | * Setuid Program Example:: Setuid Program Example |
b8fe19fa | 821 | * Tips for Setuid:: |
28f540f4 RM |
822 | * Who Logged In:: Getting the name of the user who logged in, |
823 | or of the real user ID of the current process. | |
824 | ||
825 | * User Database:: Functions and data structures for | |
826 | accessing the user database. | |
827 | * Group Database:: Functions and data structures for | |
828 | accessing the group database. | |
829 | * Database Example:: Example program showing use of database | |
830 | inquiry functions. | |
831 | ||
832 | User Database | |
833 | ||
b8fe19fa RM |
834 | * User Data Structure:: |
835 | * Lookup User:: | |
28f540f4 | 836 | * Scanning All Users:: Scanning the List of All Users |
b8fe19fa | 837 | * Writing a User Entry:: |
28f540f4 RM |
838 | |
839 | Group Database | |
840 | ||
b8fe19fa RM |
841 | * Group Data Structure:: |
842 | * Lookup Group:: | |
28f540f4 RM |
843 | * Scanning All Groups:: Scanning the List of All Groups |
844 | ||
845 | System Information | |
846 | ||
847 | * Host Identification:: Determining the name of the machine. | |
848 | * Hardware/Software Type ID:: Determining the hardware type and | |
849 | operating system type. | |
850 | ||
851 | System Configuration Limits | |
852 | ||
853 | * General Limits:: Constants and functions that describe | |
854 | various process-related limits that have | |
855 | one uniform value for any given machine. | |
856 | * System Options:: Optional POSIX features. | |
857 | * Version Supported:: Version numbers of POSIX.1 and POSIX.2. | |
858 | * Sysconf:: Getting specific configuration values | |
859 | of general limits and system options. | |
860 | * Minimums:: Minimum values for general limits. | |
b8fe19fa | 861 | |
28f540f4 RM |
862 | * Limits for Files:: Size limitations on individual files. |
863 | These can vary between file systems | |
864 | or even from file to file. | |
865 | * Options for Files:: Optional features that some files may support. | |
866 | * File Minimums:: Minimum values for file limits. | |
867 | * Pathconf:: Getting the limit values for a particular file. | |
b8fe19fa | 868 | |
28f540f4 RM |
869 | * Utility Limits:: Capacity limits of POSIX.2 utility programs. |
870 | * Utility Minimums:: Minimum allowable values of those limits. | |
b8fe19fa | 871 | |
28f540f4 RM |
872 | * String Parameters:: Getting the default search path. |
873 | ||
874 | Library Facilities that are Part of the C Language | |
875 | ||
876 | * Consistency Checking:: Using @code{assert} to abort | |
877 | if something ``impossible'' happens. | |
878 | * Variadic Functions:: Defining functions with varying | |
879 | numbers of arguments. | |
880 | * Null Pointer Constant:: The macro @code{NULL}. | |
881 | * Important Data Types:: Data types for object sizes. | |
882 | * Data Type Measurements:: Parameters of data type representations. | |
883 | ||
884 | Variadic Functions | |
885 | ||
886 | * Why Variadic:: Reasons for making functions take | |
887 | variable arguments. | |
888 | * How Variadic:: How to define and call variadic functions. | |
889 | * Argument Macros:: Detailed specification of the macros | |
890 | for accessing variable arguments. | |
891 | * Variadic Example:: A complete example. | |
892 | ||
893 | How Variadic Functions are Defined and Used | |
894 | ||
895 | * Variadic Prototypes:: How to make a prototype for a function | |
896 | with variable arguments. | |
897 | * Receiving Arguments:: Steps you must follow to access the | |
898 | optional argument values. | |
899 | * How Many Arguments:: How to decide whether there are more arguments. | |
900 | * Calling Variadics:: Things you need to know about calling | |
901 | variable arguments functions. | |
902 | ||
903 | Data Type Measurements | |
904 | ||
905 | * Width of Type:: How many bits does an integer type hold? | |
906 | * Range of Type:: What are the largest and smallest values | |
907 | that an integer type can hold? | |
908 | * Floating Type Macros:: Parameters that measure floating-point types. | |
909 | * Structure Measurement:: Getting measurements on structure types. | |
910 | ||
911 | Floating Type Macros | |
912 | ||
913 | * Floating Point Concepts:: Definitions of terminology. | |
914 | * Floating Point Parameters:: Dimensions, limits of floating point types. | |
915 | * IEEE Floating Point:: How one common representation is described. | |
916 | ||
917 | Library Maintenance | |
918 | ||
919 | * Installation:: How to configure, compile and install | |
920 | the GNU C library. | |
921 | * Reporting Bugs:: How to report bugs (if you want to | |
922 | get them fixed) and other troubles | |
923 | you may have with the GNU C library. | |
924 | * Porting:: How to port the GNU C library to | |
925 | a new machine or operating system. | |
926 | @c * Traditional C Compatibility:: Using the GNU C library with non-ANSI | |
927 | @c C compilers. | |
928 | * Contributors:: Who wrote what parts of the GNU C Library. | |
929 | ||
930 | Porting the GNU C Library | |
931 | ||
932 | * Hierarchy Conventions:: How the @file{sysdeps} hierarchy is | |
933 | layed out. | |
934 | * Porting to Unix:: Porting the library to an average | |
935 | Unix-like system. | |
936 | @end menu | |
937 | ||
938 | ||
939 | @comment Includes of all the individual chapters. | |
940 | @include intro.texi | |
941 | @include errno.texi | |
942 | @include memory.texi | |
943 | @include ctype.texi | |
944 | @include string.texi | |
945 | @include io.texi | |
946 | @include stdio.texi | |
947 | @include llio.texi | |
948 | @include filesys.texi | |
949 | @include pipe.texi | |
950 | @include socket.texi | |
951 | @include terminal.texi | |
952 | @include math.texi | |
953 | @include arith.texi | |
954 | @include search.texi | |
955 | @include pattern.texi | |
956 | @include time.texi | |
957 | @include mbyte.texi | |
958 | @include locale.texi | |
959 | @include setjmp.texi | |
960 | @include signal.texi | |
961 | @include startup.texi | |
962 | @include process.texi | |
963 | @include job.texi | |
964 | @include users.texi | |
965 | @include sysinfo.texi | |
966 | @include conf.texi | |
967 | ||
968 | @comment Includes of the appendices. | |
969 | @include lang.texi | |
970 | @include header.texi | |
971 | @include maint.texi | |
972 | ||
973 | ||
974 | @set lgpl-appendix | |
975 | @node Copying, Concept Index, Maintenance, Top | |
976 | @include lgpl.texinfo | |
977 | ||
978 | ||
979 | @node Concept Index, Type Index, Copying, Top | |
980 | @unnumbered Concept Index | |
981 | ||
982 | @printindex cp | |
983 | ||
984 | @node Type Index, Function Index, Concept Index, Top | |
985 | @unnumbered Type Index | |
986 | ||
987 | @printindex tp | |
988 | ||
989 | @node Function Index, Variable Index, Type Index, Top | |
990 | @unnumbered Function and Macro Index | |
991 | ||
992 | @printindex fn | |
993 | ||
994 | @node Variable Index, File Index, Function Index, Top | |
995 | @unnumbered Variable and Constant Macro Index | |
996 | ||
997 | @printindex vr | |
998 | ||
999 | @node File Index, , Variable Index, Top | |
1000 | @unnumbered Program and File Index | |
1001 | ||
1002 | @printindex pg | |
1003 | ||
1004 | ||
1005 | @shortcontents | |
1006 | @contents | |
1007 | @bye |