]>
Commit | Line | Data |
---|---|---|
28f540f4 RM |
1 | @node Introduction, Error Reporting, Top, Top |
2 | @chapter Introduction | |
3 | ||
4 | The C language provides no built-in facilities for performing such | |
5 | common operations as input/output, memory management, string | |
6 | manipulation, and the like. Instead, these facilities are defined | |
7 | in a standard @dfn{library}, which you compile and link with your | |
8 | programs. | |
9 | @cindex library | |
10 | ||
11 | The GNU C library, described in this document, defines all of the | |
f65fd747 | 12 | library functions that are specified by the @w{ISO C} standard, as well as |
28f540f4 RM |
13 | additional features specific to POSIX and other derivatives of the Unix |
14 | operating system, and extensions specific to the GNU system. | |
15 | ||
16 | The purpose of this manual is to tell you how to use the facilities | |
17 | of the GNU library. We have mentioned which features belong to which | |
f2ea0f5b | 18 | standards to help you identify things that are potentially non-portable |
28f540f4 RM |
19 | to other systems. But the emphasis in this manual is not on strict |
20 | portability. | |
21 | ||
22 | @menu | |
23 | * Getting Started:: What this manual is for and how to use it. | |
24 | * Standards and Portability:: Standards and sources upon which the GNU | |
25 | C library is based. | |
26 | * Using the Library:: Some practical uses for the library. | |
27 | * Roadmap to the Manual:: Overview of the remaining chapters in | |
28 | this manual. | |
29 | @end menu | |
30 | ||
31 | @node Getting Started, Standards and Portability, , Introduction | |
32 | @section Getting Started | |
33 | ||
34 | This manual is written with the assumption that you are at least | |
35 | somewhat familiar with the C programming language and basic programming | |
f65fd747 UD |
36 | concepts. Specifically, familiarity with ISO standard C |
37 | (@pxref{ISO C}), rather than ``traditional'' pre-ISO C dialects, is | |
28f540f4 RM |
38 | assumed. |
39 | ||
40 | The GNU C library includes several @dfn{header files}, each of which | |
41 | provides definitions and declarations for a group of related facilities; | |
42 | this information is used by the C compiler when processing your program. | |
43 | For example, the header file @file{stdio.h} declares facilities for | |
44 | performing input and output, and the header file @file{string.h} | |
45 | declares string processing utilities. The organization of this manual | |
46 | generally follows the same division as the header files. | |
47 | ||
48 | If you are reading this manual for the first time, you should read all | |
49 | of the introductory material and skim the remaining chapters. There are | |
50 | a @emph{lot} of functions in the GNU C library and it's not realistic to | |
51 | expect that you will be able to remember exactly @emph{how} to use each | |
52 | and every one of them. It's more important to become generally familiar | |
53 | with the kinds of facilities that the library provides, so that when you | |
54 | are writing your programs you can recognize @emph{when} to make use of | |
55 | library functions, and @emph{where} in this manual you can find more | |
56 | specific information about them. | |
57 | ||
58 | ||
59 | @node Standards and Portability, Using the Library, Getting Started, Introduction | |
60 | @section Standards and Portability | |
61 | @cindex standards | |
62 | ||
63 | This section discusses the various standards and other sources that the | |
f65fd747 | 64 | GNU C library is based upon. These sources include the @w{ISO C} and |
28f540f4 RM |
65 | POSIX standards, and the System V and Berkeley Unix implementations. |
66 | ||
67 | The primary focus of this manual is to tell you how to make effective | |
68 | use of the GNU library facilities. But if you are concerned about | |
69 | making your programs compatible with these standards, or portable to | |
70 | operating systems other than GNU, this can affect how you use the | |
71 | library. This section gives you an overview of these standards, so that | |
72 | you will know what they are when they are mentioned in other parts of | |
73 | the manual. | |
74 | ||
75 | @xref{Library Summary}, for an alphabetical list of the functions and | |
76 | other symbols provided by the library. This list also states which | |
77 | standards each function or symbol comes from. | |
78 | ||
79 | @menu | |
b13927da | 80 | * ISO C:: The international standard for the C |
f65fd747 UD |
81 | programming language. |
82 | * POSIX:: The ISO/IEC 9945 (aka IEEE 1003) standards | |
83 | for operating systems. | |
28f540f4 | 84 | * Berkeley Unix:: BSD and SunOS. |
2c6fe0bd | 85 | * SVID:: The System V Interface Description. |
b13927da | 86 | * XPG:: The X/Open Portability Guide. |
28f540f4 RM |
87 | @end menu |
88 | ||
f65fd747 UD |
89 | @node ISO C, POSIX, , Standards and Portability |
90 | @subsection ISO C | |
91 | @cindex ISO C | |
28f540f4 RM |
92 | |
93 | The GNU C library is compatible with the C standard adopted by the | |
94 | American National Standards Institute (ANSI): | |
f65fd747 | 95 | @cite{American National Standard X3.159-1989---``ANSI C''} and later |
6d52618b | 96 | by the International Standardization Organization (ISO): |
f65fd747 UD |
97 | @cite{ISO/IEC 9899:1990, ``Programming languages---C''}. |
98 | We here refer to the standard as @w{ISO C} since this is the more | |
99 | general standard in respect of ratification. | |
28f540f4 | 100 | The header files and library facilities that make up the GNU library are |
f65fd747 | 101 | a superset of those specified by the @w{ISO C} standard.@refill |
28f540f4 RM |
102 | |
103 | @pindex gcc | |
f65fd747 | 104 | If you are concerned about strict adherence to the @w{ISO C} standard, you |
28f540f4 | 105 | should use the @samp{-ansi} option when you compile your programs with |
f65fd747 | 106 | the GNU C compiler. This tells the compiler to define @emph{only} ISO |
28f540f4 RM |
107 | standard features from the library header files, unless you explicitly |
108 | ask for additional features. @xref{Feature Test Macros}, for | |
109 | information on how to do this. | |
110 | ||
f65fd747 UD |
111 | Being able to restrict the library to include only @w{ISO C} features is |
112 | important because @w{ISO C} puts limitations on what names can be defined | |
28f540f4 RM |
113 | by the library implementation, and the GNU extensions don't fit these |
114 | limitations. @xref{Reserved Names}, for more information about these | |
115 | restrictions. | |
116 | ||
117 | This manual does not attempt to give you complete details on the | |
f65fd747 | 118 | differences between @w{ISO C} and older dialects. It gives advice on how |
28f540f4 RM |
119 | to write programs to work portably under multiple C dialects, but does |
120 | not aim for completeness. | |
121 | ||
b13927da | 122 | |
f65fd747 | 123 | @node POSIX, Berkeley Unix, ISO C, Standards and Portability |
28f540f4 RM |
124 | @subsection POSIX (The Portable Operating System Interface) |
125 | @cindex POSIX | |
126 | @cindex POSIX.1 | |
127 | @cindex IEEE Std 1003.1 | |
b13927da | 128 | @cindex ISO/IEC 9945-1 |
28f540f4 RM |
129 | @cindex POSIX.2 |
130 | @cindex IEEE Std 1003.2 | |
b13927da | 131 | @cindex ISO/IEC 9945-2 |
28f540f4 | 132 | |
b13927da | 133 | The GNU library is also compatible with the ISO @dfn{POSIX} family of |
28f540f4 | 134 | standards, known more formally as the @dfn{Portable Operating System |
b13927da UD |
135 | Interface for Computer Environments} (ISO/IEC 9945). They were also |
136 | published as ANSI/IEEE Std 1003. POSIX is derived mostly from various | |
137 | versions of the Unix operating system. | |
28f540f4 RM |
138 | |
139 | The library facilities specified by the POSIX standards are a superset | |
f65fd747 UD |
140 | of those required by @w{ISO C}; POSIX specifies additional features for |
141 | @w{ISO C} functions, as well as specifying new additional functions. In | |
28f540f4 RM |
142 | general, the additional requirements and functionality defined by the |
143 | POSIX standards are aimed at providing lower-level support for a | |
144 | particular kind of operating system environment, rather than general | |
145 | programming language support which can run in many diverse operating | |
146 | system environments.@refill | |
147 | ||
148 | The GNU C library implements all of the functions specified in | |
b13927da | 149 | @cite{ISO/IEC 9945-1:1996, the POSIX System Application Program |
28f540f4 | 150 | Interface}, commonly referred to as POSIX.1. The primary extensions to |
f65fd747 | 151 | the @w{ISO C} facilities specified by this standard include file system |
28f540f4 RM |
152 | interface primitives (@pxref{File System Interface}), device-specific |
153 | terminal control functions (@pxref{Low-Level Terminal Interface}), and | |
154 | process control functions (@pxref{Processes}). | |
155 | ||
b13927da | 156 | Some facilities from @cite{ISO/IEC 9945-2:1993, the POSIX Shell and |
28f540f4 RM |
157 | Utilities standard} (POSIX.2) are also implemented in the GNU library. |
158 | These include utilities for dealing with regular expressions and other | |
159 | pattern matching facilities (@pxref{Pattern Matching}). | |
160 | ||
161 | @comment Roland sez: | |
162 | @comment The GNU C library as it stands conforms to 1003.2 draft 11, which | |
163 | @comment specifies: | |
2c6fe0bd | 164 | @comment |
28f540f4 RM |
165 | @comment Several new macros in <limits.h>. |
166 | @comment popen, pclose | |
167 | @comment <regex.h> (which is not yet fully implemented--wait on this) | |
168 | @comment fnmatch | |
169 | @comment getopt | |
170 | @comment <glob.h> | |
171 | @comment <wordexp.h> (not yet implemented) | |
172 | @comment confstr | |
173 | ||
174 | ||
175 | @node Berkeley Unix, SVID, POSIX, Standards and Portability | |
176 | @subsection Berkeley Unix | |
177 | @cindex BSD Unix | |
178 | @cindex 4.@var{n} BSD Unix | |
179 | @cindex Berkeley Unix | |
180 | @cindex SunOS | |
181 | @cindex Unix, Berkeley | |
182 | ||
183 | The GNU C library defines facilities from some versions of Unix which | |
184 | are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD, | |
185 | and 4.4 BSD Unix systems (also known as @dfn{Berkeley Unix}) and from | |
186 | @dfn{SunOS} (a popular 4.2 BSD derivative that includes some Unix System | |
f65fd747 | 187 | V functionality). These systems support most of the @w{ISO C} and POSIX |
28f540f4 RM |
188 | facilities, and 4.4 BSD and newer releases of SunOS in fact support them all. |
189 | ||
190 | The BSD facilities include symbolic links (@pxref{Symbolic Links}), the | |
191 | @code{select} function (@pxref{Waiting for I/O}), the BSD signal | |
192 | functions (@pxref{BSD Signal Handling}), and sockets (@pxref{Sockets}). | |
193 | ||
b13927da | 194 | @node SVID, XPG, Berkeley Unix, Standards and Portability |
28f540f4 RM |
195 | @subsection SVID (The System V Interface Description) |
196 | @cindex SVID | |
197 | @cindex System V Unix | |
198 | @cindex Unix, System V | |
199 | ||
200 | The @dfn{System V Interface Description} (SVID) is a document describing | |
201 | the AT&T Unix System V operating system. It is to some extent a | |
202 | superset of the POSIX standard (@pxref{POSIX}). | |
203 | ||
b13927da | 204 | The GNU C library defines most of the facilities required by the SVID |
f65fd747 | 205 | that are not also required by the @w{ISO C} or POSIX standards, for |
28f540f4 RM |
206 | compatibility with System V Unix and other Unix systems (such as |
207 | SunOS) which include these facilities. However, many of the more | |
208 | obscure and less generally useful facilities required by the SVID are | |
209 | not included. (In fact, Unix System V itself does not provide them all.) | |
210 | ||
b13927da UD |
211 | The supported facilities from System V include the methods for |
212 | inter-process communication and shared memory, the @code{hsearch} and | |
213 | @code{drand48} families of functions, @code{fmtmsg} and several of the | |
214 | mathematical functions. | |
215 | ||
216 | @node XPG, , SVID, Standards and Portability | |
217 | @subsection XPG (The X/Open Portability Guide) | |
218 | ||
219 | The X/Open Portability Guide, published by the X/Open Company, Ltd., is | |
220 | a more general standard than POSIX. X/Open owns the Unix copyright and | |
221 | the XPG specifies the requirements for systems which are intended to be | |
222 | a Unix system. | |
223 | ||
224 | The GNU C library complies to the X/Open Portability Guide, Issue 4.2, | |
714a562f | 225 | with all extensions common to XSI (X/Open System Interface) |
b13927da UD |
226 | compliant systems and also all X/Open UNIX extensions. |
227 | ||
228 | The additions on top of POSIX are mainly derived from functionality | |
229 | available in @w{System V} and BSD systems. Some of the really bad | |
230 | mistakes in @w{System V} systems were corrected, though. Since | |
231 | fulfilling the XPG standard with the Unix extensions is a | |
232 | precondition for getting the Unix brand chances are good that the | |
233 | functionality is available on commercial systems. | |
28f540f4 RM |
234 | |
235 | ||
236 | @node Using the Library, Roadmap to the Manual, Standards and Portability, Introduction | |
237 | @section Using the Library | |
238 | ||
239 | This section describes some of the practical issues involved in using | |
240 | the GNU C library. | |
241 | ||
242 | @menu | |
243 | * Header Files:: How to include the header files in your | |
2c6fe0bd | 244 | programs. |
28f540f4 RM |
245 | * Macro Definitions:: Some functions in the library may really |
246 | be implemented as macros. | |
247 | * Reserved Names:: The C standard reserves some names for | |
248 | the library, and some for users. | |
249 | * Feature Test Macros:: How to control what names are defined. | |
250 | @end menu | |
251 | ||
252 | @node Header Files, Macro Definitions, , Using the Library | |
253 | @subsection Header Files | |
254 | @cindex header files | |
255 | ||
256 | Libraries for use by C programs really consist of two parts: @dfn{header | |
257 | files} that define types and macros and declare variables and | |
258 | functions; and the actual library or @dfn{archive} that contains the | |
259 | definitions of the variables and functions. | |
260 | ||
261 | (Recall that in C, a @dfn{declaration} merely provides information that | |
262 | a function or variable exists and gives its type. For a function | |
263 | declaration, information about the types of its arguments might be | |
264 | provided as well. The purpose of declarations is to allow the compiler | |
265 | to correctly process references to the declared variables and functions. | |
266 | A @dfn{definition}, on the other hand, actually allocates storage for a | |
267 | variable or says what a function does.) | |
268 | @cindex definition (compared to declaration) | |
269 | @cindex declaration (compared to definition) | |
270 | ||
271 | In order to use the facilities in the GNU C library, you should be sure | |
272 | that your program source files include the appropriate header files. | |
273 | This is so that the compiler has declarations of these facilities | |
274 | available and can correctly process references to them. Once your | |
275 | program has been compiled, the linker resolves these references to | |
276 | the actual definitions provided in the archive file. | |
277 | ||
278 | Header files are included into a program source file by the | |
279 | @samp{#include} preprocessor directive. The C language supports two | |
280 | forms of this directive; the first, | |
281 | ||
282 | @smallexample | |
283 | #include "@var{header}" | |
284 | @end smallexample | |
285 | ||
286 | @noindent | |
287 | is typically used to include a header file @var{header} that you write | |
288 | yourself; this would contain definitions and declarations describing the | |
289 | interfaces between the different parts of your particular application. | |
290 | By contrast, | |
291 | ||
292 | @smallexample | |
293 | #include <file.h> | |
294 | @end smallexample | |
295 | ||
296 | @noindent | |
297 | is typically used to include a header file @file{file.h} that contains | |
298 | definitions and declarations for a standard library. This file would | |
299 | normally be installed in a standard place by your system administrator. | |
300 | You should use this second form for the C library header files. | |
301 | ||
302 | Typically, @samp{#include} directives are placed at the top of the C | |
303 | source file, before any other code. If you begin your source files with | |
304 | some comments explaining what the code in the file does (a good idea), | |
305 | put the @samp{#include} directives immediately afterwards, following the | |
306 | feature test macro definition (@pxref{Feature Test Macros}). | |
307 | ||
308 | For more information about the use of header files and @samp{#include} | |
309 | directives, @pxref{Header Files,,, cpp.info, The GNU C Preprocessor | |
310 | Manual}.@refill | |
311 | ||
312 | The GNU C library provides several header files, each of which contains | |
313 | the type and macro definitions and variable and function declarations | |
314 | for a group of related facilities. This means that your programs may | |
315 | need to include several header files, depending on exactly which | |
316 | facilities you are using. | |
317 | ||
318 | Some library header files include other library header files | |
319 | automatically. However, as a matter of programming style, you should | |
320 | not rely on this; it is better to explicitly include all the header | |
321 | files required for the library facilities you are using. The GNU C | |
322 | library header files have been written in such a way that it doesn't | |
323 | matter if a header file is accidentally included more than once; | |
324 | including a header file a second time has no effect. Likewise, if your | |
325 | program needs to include multiple header files, the order in which they | |
326 | are included doesn't matter. | |
327 | ||
328 | @strong{Compatibility Note:} Inclusion of standard header files in any | |
f65fd747 | 329 | order and any number of times works in any @w{ISO C} implementation. |
28f540f4 RM |
330 | However, this has traditionally not been the case in many older C |
331 | implementations. | |
332 | ||
333 | Strictly speaking, you don't @emph{have to} include a header file to use | |
334 | a function it declares; you could declare the function explicitly | |
335 | yourself, according to the specifications in this manual. But it is | |
336 | usually better to include the header file because it may define types | |
337 | and macros that are not otherwise available and because it may define | |
338 | more efficient macro replacements for some functions. It is also a sure | |
339 | way to have the correct declaration. | |
340 | ||
341 | @node Macro Definitions, Reserved Names, Header Files, Using the Library | |
342 | @subsection Macro Definitions of Functions | |
343 | @cindex shadowing functions with macros | |
344 | @cindex removing macros that shadow functions | |
345 | @cindex undefining macros that shadow functions | |
346 | ||
347 | If we describe something as a function in this manual, it may have a | |
348 | macro definition as well. This normally has no effect on how your | |
349 | program runs---the macro definition does the same thing as the function | |
350 | would. In particular, macro equivalents for library functions evaluate | |
351 | arguments exactly once, in the same way that a function call would. The | |
352 | main reason for these macro definitions is that sometimes they can | |
353 | produce an inline expansion that is considerably faster than an actual | |
354 | function call. | |
355 | ||
356 | Taking the address of a library function works even if it is also | |
357 | defined as a macro. This is because, in this context, the name of the | |
358 | function isn't followed by the left parenthesis that is syntactically | |
359 | necessary to recognize a macro call. | |
360 | ||
361 | You might occasionally want to avoid using the macro definition of a | |
362 | function---perhaps to make your program easier to debug. There are | |
363 | two ways you can do this: | |
364 | ||
365 | @itemize @bullet | |
2c6fe0bd | 366 | @item |
28f540f4 RM |
367 | You can avoid a macro definition in a specific use by enclosing the name |
368 | of the function in parentheses. This works because the name of the | |
369 | function doesn't appear in a syntactic context where it is recognizable | |
370 | as a macro call. | |
371 | ||
372 | @item | |
373 | You can suppress any macro definition for a whole source file by using | |
374 | the @samp{#undef} preprocessor directive, unless otherwise stated | |
375 | explicitly in the description of that facility. | |
376 | @end itemize | |
377 | ||
378 | For example, suppose the header file @file{stdlib.h} declares a function | |
379 | named @code{abs} with | |
380 | ||
381 | @smallexample | |
382 | extern int abs (int); | |
383 | @end smallexample | |
384 | ||
385 | @noindent | |
386 | and also provides a macro definition for @code{abs}. Then, in: | |
387 | ||
388 | @smallexample | |
389 | #include <stdlib.h> | |
b13927da | 390 | int f (int *i) @{ return abs (++*i); @} |
28f540f4 RM |
391 | @end smallexample |
392 | ||
393 | @noindent | |
394 | the reference to @code{abs} might refer to either a macro or a function. | |
395 | On the other hand, in each of the following examples the reference is | |
396 | to a function and not a macro. | |
397 | ||
398 | @smallexample | |
399 | #include <stdlib.h> | |
b13927da | 400 | int g (int *i) @{ return (abs) (++*i); @} |
28f540f4 RM |
401 | |
402 | #undef abs | |
b13927da | 403 | int h (int *i) @{ return abs (++*i); @} |
28f540f4 RM |
404 | @end smallexample |
405 | ||
406 | Since macro definitions that double for a function behave in | |
407 | exactly the same way as the actual function version, there is usually no | |
408 | need for any of these methods. In fact, removing macro definitions usually | |
409 | just makes your program slower. | |
410 | ||
411 | ||
412 | @node Reserved Names, Feature Test Macros, Macro Definitions, Using the Library | |
413 | @subsection Reserved Names | |
414 | @cindex reserved names | |
415 | @cindex name space | |
416 | ||
417 | The names of all library types, macros, variables and functions that | |
f65fd747 | 418 | come from the @w{ISO C} standard are reserved unconditionally; your program |
28f540f4 RM |
419 | @strong{may not} redefine these names. All other library names are |
420 | reserved if your program explicitly includes the header file that | |
421 | defines or declares them. There are several reasons for these | |
422 | restrictions: | |
423 | ||
424 | @itemize @bullet | |
425 | @item | |
426 | Other people reading your code could get very confused if you were using | |
427 | a function named @code{exit} to do something completely different from | |
428 | what the standard @code{exit} function does, for example. Preventing | |
429 | this situation helps to make your programs easier to understand and | |
430 | contributes to modularity and maintainability. | |
431 | ||
432 | @item | |
433 | It avoids the possibility of a user accidentally redefining a library | |
434 | function that is called by other library functions. If redefinition | |
435 | were allowed, those other functions would not work properly. | |
436 | ||
437 | @item | |
438 | It allows the compiler to do whatever special optimizations it pleases | |
439 | on calls to these functions, without the possibility that they may have | |
440 | been redefined by the user. Some library facilities, such as those for | |
441 | dealing with variadic arguments (@pxref{Variadic Functions}) | |
442 | and non-local exits (@pxref{Non-Local Exits}), actually require a | |
443 | considerable amount of cooperation on the part of the C compiler, and | |
444 | implementationally it might be easier for the compiler to treat these as | |
445 | built-in parts of the language. | |
446 | @end itemize | |
447 | ||
448 | In addition to the names documented in this manual, reserved names | |
449 | include all external identifiers (global functions and variables) that | |
450 | begin with an underscore (@samp{_}) and all identifiers regardless of | |
451 | use that begin with either two underscores or an underscore followed by | |
452 | a capital letter are reserved names. This is so that the library and | |
453 | header files can define functions, variables, and macros for internal | |
454 | purposes without risk of conflict with names in user programs. | |
455 | ||
456 | Some additional classes of identifier names are reserved for future | |
457 | extensions to the C language or the POSIX.1 environment. While using these | |
458 | names for your own purposes right now might not cause a problem, they do | |
459 | raise the possibility of conflict with future versions of the C | |
460 | or POSIX standards, so you should avoid these names. | |
461 | ||
462 | @itemize @bullet | |
2c6fe0bd | 463 | @item |
28f540f4 RM |
464 | Names beginning with a capital @samp{E} followed a digit or uppercase |
465 | letter may be used for additional error code names. @xref{Error | |
466 | Reporting}. | |
467 | ||
468 | @item | |
469 | Names that begin with either @samp{is} or @samp{to} followed by a | |
470 | lowercase letter may be used for additional character testing and | |
471 | conversion functions. @xref{Character Handling}. | |
472 | ||
473 | @item | |
474 | Names that begin with @samp{LC_} followed by an uppercase letter may be | |
475 | used for additional macros specifying locale attributes. | |
476 | @xref{Locales}. | |
477 | ||
478 | @item | |
479 | Names of all existing mathematics functions (@pxref{Mathematics}) | |
480 | suffixed with @samp{f} or @samp{l} are reserved for corresponding | |
481 | functions that operate on @code{float} and @code{long double} arguments, | |
482 | respectively. | |
483 | ||
484 | @item | |
485 | Names that begin with @samp{SIG} followed by an uppercase letter are | |
486 | reserved for additional signal names. @xref{Standard Signals}. | |
487 | ||
488 | @item | |
489 | Names that begin with @samp{SIG_} followed by an uppercase letter are | |
490 | reserved for additional signal actions. @xref{Basic Signal Handling}. | |
491 | ||
492 | @item | |
493 | Names beginning with @samp{str}, @samp{mem}, or @samp{wcs} followed by a | |
494 | lowercase letter are reserved for additional string and array functions. | |
495 | @xref{String and Array Utilities}. | |
496 | ||
497 | @item | |
498 | Names that end with @samp{_t} are reserved for additional type names. | |
499 | @end itemize | |
500 | ||
501 | In addition, some individual header files reserve names beyond | |
502 | those that they actually define. You only need to worry about these | |
503 | restrictions if your program includes that particular header file. | |
504 | ||
505 | @itemize @bullet | |
506 | @item | |
507 | The header file @file{dirent.h} reserves names prefixed with | |
508 | @samp{d_}. | |
509 | @pindex dirent.h | |
510 | ||
511 | @item | |
512 | The header file @file{fcntl.h} reserves names prefixed with | |
513 | @samp{l_}, @samp{F_}, @samp{O_}, and @samp{S_}. | |
514 | @pindex fcntl.h | |
515 | ||
516 | @item | |
517 | The header file @file{grp.h} reserves names prefixed with @samp{gr_}. | |
518 | @pindex grp.h | |
519 | ||
520 | @item | |
521 | The header file @file{limits.h} reserves names suffixed with @samp{_MAX}. | |
522 | @pindex limits.h | |
523 | ||
524 | @item | |
525 | The header file @file{pwd.h} reserves names prefixed with @samp{pw_}. | |
526 | @pindex pwd.h | |
527 | ||
528 | @item | |
529 | The header file @file{signal.h} reserves names prefixed with @samp{sa_} | |
530 | and @samp{SA_}. | |
531 | @pindex signal.h | |
532 | ||
533 | @item | |
534 | The header file @file{sys/stat.h} reserves names prefixed with @samp{st_} | |
535 | and @samp{S_}. | |
536 | @pindex sys/stat.h | |
537 | ||
538 | @item | |
539 | The header file @file{sys/times.h} reserves names prefixed with @samp{tms_}. | |
540 | @pindex sys/times.h | |
541 | ||
542 | @item | |
543 | The header file @file{termios.h} reserves names prefixed with @samp{c_}, | |
544 | @samp{V}, @samp{I}, @samp{O}, and @samp{TC}; and names prefixed with | |
545 | @samp{B} followed by a digit. | |
546 | @pindex termios.h | |
547 | @end itemize | |
548 | ||
549 | @comment Include the section on Creature Nest Macros. | |
550 | @comment It is in a separate file so it can be formatted into ../NOTES. | |
551 | @include creature.texi | |
552 | ||
553 | @node Roadmap to the Manual, , Using the Library, Introduction | |
554 | @section Roadmap to the Manual | |
555 | ||
556 | Here is an overview of the contents of the remaining chapters of | |
557 | this manual. | |
558 | ||
559 | @itemize @bullet | |
2c6fe0bd | 560 | @item |
28f540f4 RM |
561 | @ref{Error Reporting}, describes how errors detected by the library |
562 | are reported. | |
563 | ||
2c6fe0bd | 564 | @item |
28f540f4 RM |
565 | @ref{Language Features}, contains information about library support for |
566 | standard parts of the C language, including things like the @code{sizeof} | |
567 | operator and the symbolic constant @code{NULL}, how to write functions | |
568 | accepting variable numbers of arguments, and constants describing the | |
569 | ranges and other properties of the numerical types. There is also a simple | |
570 | debugging mechanism which allows you to put assertions in your code, and | |
571 | have diagnostic messages printed if the tests fail. | |
572 | ||
2c6fe0bd | 573 | @item |
28f540f4 RM |
574 | @ref{Memory Allocation}, describes the GNU library's facilities for |
575 | dynamic allocation of storage. If you do not know in advance how much | |
576 | storage your program needs, you can allocate it dynamically instead, | |
577 | and manipulate it via pointers. | |
578 | ||
2c6fe0bd | 579 | @item |
28f540f4 RM |
580 | @ref{Character Handling}, contains information about character |
581 | classification functions (such as @code{isspace}) and functions for | |
582 | performing case conversion. | |
583 | ||
2c6fe0bd | 584 | @item |
28f540f4 RM |
585 | @ref{String and Array Utilities}, has descriptions of functions for |
586 | manipulating strings (null-terminated character arrays) and general | |
587 | byte arrays, including operations such as copying and comparison. | |
588 | ||
589 | @item | |
590 | @ref{I/O Overview}, gives an overall look at the input and output | |
591 | facilities in the library, and contains information about basic concepts | |
592 | such as file names. | |
593 | ||
594 | @item | |
595 | @ref{I/O on Streams}, describes I/O operations involving streams (or | |
596 | @w{@code{FILE *}} objects). These are the normal C library functions | |
597 | from @file{stdio.h}. | |
598 | ||
599 | @item | |
600 | @ref{Low-Level I/O}, contains information about I/O operations | |
601 | on file descriptors. File descriptors are a lower-level mechanism | |
602 | specific to the Unix family of operating systems. | |
603 | ||
604 | @item | |
605 | @ref{File System Interface}, has descriptions of operations on entire | |
606 | files, such as functions for deleting and renaming them and for creating | |
607 | new directories. This chapter also contains information about how you | |
608 | can access the attributes of a file, such as its owner and file protection | |
609 | modes. | |
610 | ||
611 | @item | |
612 | @ref{Pipes and FIFOs}, contains information about simple interprocess | |
613 | communication mechanisms. Pipes allow communication between two related | |
614 | processes (such as between a parent and child), while FIFOs allow | |
615 | communication between processes sharing a common file system on the same | |
616 | machine. | |
617 | ||
618 | @item | |
619 | @ref{Sockets}, describes a more complicated interprocess communication | |
620 | mechanism that allows processes running on different machines to | |
621 | communicate over a network. This chapter also contains information about | |
622 | Internet host addressing and how to use the system network databases. | |
623 | ||
624 | @item | |
625 | @ref{Low-Level Terminal Interface}, describes how you can change the | |
626 | attributes of a terminal device. If you want to disable echo of | |
627 | characters typed by the user, for example, read this chapter. | |
628 | ||
2c6fe0bd | 629 | @item |
28f540f4 RM |
630 | @ref{Mathematics}, contains information about the math library |
631 | functions. These include things like random-number generators and | |
632 | remainder functions on integers as well as the usual trigonometric and | |
633 | exponential functions on floating-point numbers. | |
634 | ||
635 | @item | |
636 | @ref{Arithmetic,, Low-Level Arithmetic Functions}, describes functions | |
637 | for simple arithmetic, analysis of floating-point values, and reading | |
638 | numbers from strings. | |
639 | ||
2c6fe0bd | 640 | @item |
28f540f4 RM |
641 | @ref{Searching and Sorting}, contains information about functions |
642 | for searching and sorting arrays. You can use these functions on any | |
643 | kind of array by providing an appropriate comparison function. | |
644 | ||
645 | @item | |
646 | @ref{Pattern Matching}, presents functions for matching regular expressions | |
647 | and shell file name patterns, and for expanding words as the shell does. | |
648 | ||
649 | @item | |
650 | @ref{Date and Time}, describes functions for measuring both calendar time | |
651 | and CPU time, as well as functions for setting alarms and timers. | |
652 | ||
2c6fe0bd | 653 | @item |
28f540f4 RM |
654 | @ref{Extended Characters}, contains information about manipulating |
655 | characters and strings using character sets larger than will fit in | |
2c6fe0bd | 656 | the usual @code{char} data type. |
28f540f4 | 657 | |
2c6fe0bd UD |
658 | @item |
659 | @ref{Locales}, describes how selecting a particular country | |
28f540f4 RM |
660 | or language affects the behavior of the library. For example, the locale |
661 | affects collation sequences for strings and how monetary values are | |
662 | formatted. | |
663 | ||
664 | @item | |
665 | @ref{Non-Local Exits}, contains descriptions of the @code{setjmp} and | |
666 | @code{longjmp} functions. These functions provide a facility for | |
667 | @code{goto}-like jumps which can jump from one function to another. | |
668 | ||
669 | @item | |
670 | @ref{Signal Handling}, tells you all about signals---what they are, | |
671 | how to establish a handler that is called when a particular kind of | |
672 | signal is delivered, and how to prevent signals from arriving during | |
673 | critical sections of your program. | |
674 | ||
675 | @item | |
676 | @ref{Process Startup}, tells how your programs can access their | |
677 | command-line arguments and environment variables. | |
678 | ||
2c6fe0bd | 679 | @item |
28f540f4 RM |
680 | @ref{Processes}, contains information about how to start new processes |
681 | and run programs. | |
682 | ||
683 | @item | |
684 | @ref{Job Control}, describes functions for manipulating process groups | |
685 | and the controlling terminal. This material is probably only of | |
686 | interest if you are writing a shell or other program which handles job | |
687 | control specially. | |
688 | ||
2c6fe0bd UD |
689 | @item |
690 | @ref{Name Service Switch}, describes the services which are available | |
691 | for looking up names in the system databases, how to determine which | |
692 | service is used for which database, and how these services are | |
693 | implemented so that contributors can design their own services. | |
694 | ||
28f540f4 RM |
695 | @item |
696 | @ref{User Database}, and @ref{Group Database}, tell you how to access | |
697 | the system user and group databases. | |
698 | ||
699 | @item | |
700 | @ref{System Information}, describes functions for getting information | |
701 | about the hardware and software configuration your program is executing | |
702 | under. | |
703 | ||
2c6fe0bd | 704 | @item |
28f540f4 RM |
705 | @ref{System Configuration}, tells you how you can get information about |
706 | various operating system limits. Most of these parameters are provided for | |
707 | compatibility with POSIX. | |
708 | ||
709 | @item | |
710 | @ref{Library Summary}, gives a summary of all the functions, variables, and | |
711 | macros in the library, with complete data types and function prototypes, | |
712 | and says what standard or system each is derived from. | |
713 | ||
714 | @item | |
715 | @ref{Maintenance}, explains how to build and install the GNU C library on | |
716 | your system, how to report any bugs you might find, and how to add new | |
717 | functions or port the library to a new system. | |
718 | @end itemize | |
719 | ||
720 | If you already know the name of the facility you are interested in, you | |
721 | can look it up in @ref{Library Summary}. This gives you a summary of | |
722 | its syntax and a pointer to where you can find a more detailed | |
723 | description. This appendix is particularly useful if you just want to | |
724 | verify the order and type of arguments to a function, for example. It | |
725 | also tells you what standard or system each function, variable, or macro | |
726 | is derived from. |