]>
Commit | Line | Data |
---|---|---|
28f540f4 RM |
1 | @node Introduction, Error Reporting, Top, Top |
2 | @chapter Introduction | |
7a68c94a | 3 | @c %MENU% Purpose of the GNU C Library |
28f540f4 RM |
4 | |
5 | The C language provides no built-in facilities for performing such | |
6 | common operations as input/output, memory management, string | |
7 | manipulation, and the like. Instead, these facilities are defined | |
8 | in a standard @dfn{library}, which you compile and link with your | |
9 | programs. | |
10 | @cindex library | |
11 | ||
1f77f049 | 12 | @Theglibc{}, described in this document, defines all of the |
f65fd747 | 13 | library functions that are specified by the @w{ISO C} standard, as well as |
28f540f4 | 14 | additional features specific to POSIX and other derivatives of the Unix |
a7a93d50 | 15 | operating system, and extensions specific to @gnusystems{}. |
28f540f4 RM |
16 | |
17 | The purpose of this manual is to tell you how to use the facilities | |
1f77f049 | 18 | of @theglibc{}. We have mentioned which features belong to which |
f2ea0f5b | 19 | standards to help you identify things that are potentially non-portable |
28f540f4 RM |
20 | to other systems. But the emphasis in this manual is not on strict |
21 | portability. | |
22 | ||
23 | @menu | |
24 | * Getting Started:: What this manual is for and how to use it. | |
25 | * Standards and Portability:: Standards and sources upon which the GNU | |
26 | C library is based. | |
27 | * Using the Library:: Some practical uses for the library. | |
28 | * Roadmap to the Manual:: Overview of the remaining chapters in | |
29 | this manual. | |
30 | @end menu | |
31 | ||
32 | @node Getting Started, Standards and Portability, , Introduction | |
33 | @section Getting Started | |
34 | ||
35 | This manual is written with the assumption that you are at least | |
36 | somewhat familiar with the C programming language and basic programming | |
f65fd747 UD |
37 | concepts. Specifically, familiarity with ISO standard C |
38 | (@pxref{ISO C}), rather than ``traditional'' pre-ISO C dialects, is | |
28f540f4 RM |
39 | assumed. |
40 | ||
1f77f049 | 41 | @Theglibc{} includes several @dfn{header files}, each of which |
28f540f4 RM |
42 | provides definitions and declarations for a group of related facilities; |
43 | this information is used by the C compiler when processing your program. | |
44 | For example, the header file @file{stdio.h} declares facilities for | |
45 | performing input and output, and the header file @file{string.h} | |
46 | declares string processing utilities. The organization of this manual | |
47 | generally follows the same division as the header files. | |
48 | ||
49 | If you are reading this manual for the first time, you should read all | |
50 | of the introductory material and skim the remaining chapters. There are | |
1f77f049 | 51 | a @emph{lot} of functions in @theglibc{} and it's not realistic to |
28f540f4 RM |
52 | expect that you will be able to remember exactly @emph{how} to use each |
53 | and every one of them. It's more important to become generally familiar | |
54 | with the kinds of facilities that the library provides, so that when you | |
55 | are writing your programs you can recognize @emph{when} to make use of | |
56 | library functions, and @emph{where} in this manual you can find more | |
57 | specific information about them. | |
58 | ||
59 | ||
60 | @node Standards and Portability, Using the Library, Getting Started, Introduction | |
61 | @section Standards and Portability | |
62 | @cindex standards | |
63 | ||
1f77f049 JM |
64 | This section discusses the various standards and other sources that @theglibc{} |
65 | is based upon. These sources include the @w{ISO C} and | |
28f540f4 RM |
66 | POSIX standards, and the System V and Berkeley Unix implementations. |
67 | ||
68 | The primary focus of this manual is to tell you how to make effective | |
1f77f049 | 69 | use of the @glibcadj{} facilities. But if you are concerned about |
28f540f4 RM |
70 | making your programs compatible with these standards, or portable to |
71 | operating systems other than GNU, this can affect how you use the | |
72 | library. This section gives you an overview of these standards, so that | |
73 | you will know what they are when they are mentioned in other parts of | |
74 | the manual. | |
75 | ||
76 | @xref{Library Summary}, for an alphabetical list of the functions and | |
77 | other symbols provided by the library. This list also states which | |
78 | standards each function or symbol comes from. | |
79 | ||
80 | @menu | |
b13927da | 81 | * ISO C:: The international standard for the C |
f65fd747 UD |
82 | programming language. |
83 | * POSIX:: The ISO/IEC 9945 (aka IEEE 1003) standards | |
84 | for operating systems. | |
28f540f4 | 85 | * Berkeley Unix:: BSD and SunOS. |
2c6fe0bd | 86 | * SVID:: The System V Interface Description. |
b13927da | 87 | * XPG:: The X/Open Portability Guide. |
28f540f4 RM |
88 | @end menu |
89 | ||
f65fd747 UD |
90 | @node ISO C, POSIX, , Standards and Portability |
91 | @subsection ISO C | |
92 | @cindex ISO C | |
28f540f4 | 93 | |
1f77f049 | 94 | @Theglibc{} is compatible with the C standard adopted by the |
28f540f4 | 95 | American National Standards Institute (ANSI): |
f65fd747 | 96 | @cite{American National Standard X3.159-1989---``ANSI C''} and later |
6d52618b | 97 | by the International Standardization Organization (ISO): |
f65fd747 UD |
98 | @cite{ISO/IEC 9899:1990, ``Programming languages---C''}. |
99 | We here refer to the standard as @w{ISO C} since this is the more | |
100 | general standard in respect of ratification. | |
1f77f049 | 101 | The header files and library facilities that make up @theglibc{} are |
0005e54f | 102 | a superset of those specified by the @w{ISO C} standard. |
28f540f4 RM |
103 | |
104 | @pindex gcc | |
f65fd747 | 105 | If you are concerned about strict adherence to the @w{ISO C} standard, you |
28f540f4 | 106 | should use the @samp{-ansi} option when you compile your programs with |
f65fd747 | 107 | the GNU C compiler. This tells the compiler to define @emph{only} ISO |
28f540f4 RM |
108 | standard features from the library header files, unless you explicitly |
109 | ask for additional features. @xref{Feature Test Macros}, for | |
110 | information on how to do this. | |
111 | ||
f65fd747 UD |
112 | Being able to restrict the library to include only @w{ISO C} features is |
113 | important because @w{ISO C} puts limitations on what names can be defined | |
28f540f4 RM |
114 | by the library implementation, and the GNU extensions don't fit these |
115 | limitations. @xref{Reserved Names}, for more information about these | |
116 | restrictions. | |
117 | ||
118 | This manual does not attempt to give you complete details on the | |
f65fd747 | 119 | differences between @w{ISO C} and older dialects. It gives advice on how |
28f540f4 RM |
120 | to write programs to work portably under multiple C dialects, but does |
121 | not aim for completeness. | |
122 | ||
b13927da | 123 | |
f65fd747 | 124 | @node POSIX, Berkeley Unix, ISO C, Standards and Portability |
28f540f4 RM |
125 | @subsection POSIX (The Portable Operating System Interface) |
126 | @cindex POSIX | |
127 | @cindex POSIX.1 | |
128 | @cindex IEEE Std 1003.1 | |
b13927da | 129 | @cindex ISO/IEC 9945-1 |
28f540f4 RM |
130 | @cindex POSIX.2 |
131 | @cindex IEEE Std 1003.2 | |
b13927da | 132 | @cindex ISO/IEC 9945-2 |
28f540f4 | 133 | |
1f77f049 | 134 | @Theglibc{} is also compatible with the ISO @dfn{POSIX} family of |
28f540f4 | 135 | standards, known more formally as the @dfn{Portable Operating System |
b13927da UD |
136 | Interface for Computer Environments} (ISO/IEC 9945). They were also |
137 | published as ANSI/IEEE Std 1003. POSIX is derived mostly from various | |
138 | versions of the Unix operating system. | |
28f540f4 RM |
139 | |
140 | The library facilities specified by the POSIX standards are a superset | |
f65fd747 UD |
141 | of those required by @w{ISO C}; POSIX specifies additional features for |
142 | @w{ISO C} functions, as well as specifying new additional functions. In | |
28f540f4 RM |
143 | general, the additional requirements and functionality defined by the |
144 | POSIX standards are aimed at providing lower-level support for a | |
145 | particular kind of operating system environment, rather than general | |
146 | programming language support which can run in many diverse operating | |
0005e54f | 147 | system environments. |
28f540f4 | 148 | |
1f77f049 | 149 | @Theglibc{} implements all of the functions specified in |
b13927da | 150 | @cite{ISO/IEC 9945-1:1996, the POSIX System Application Program |
28f540f4 | 151 | Interface}, commonly referred to as POSIX.1. The primary extensions to |
f65fd747 | 152 | the @w{ISO C} facilities specified by this standard include file system |
28f540f4 RM |
153 | interface primitives (@pxref{File System Interface}), device-specific |
154 | terminal control functions (@pxref{Low-Level Terminal Interface}), and | |
155 | process control functions (@pxref{Processes}). | |
156 | ||
b13927da | 157 | Some facilities from @cite{ISO/IEC 9945-2:1993, the POSIX Shell and |
1f77f049 | 158 | Utilities standard} (POSIX.2) are also implemented in @theglibc{}. |
28f540f4 RM |
159 | These include utilities for dealing with regular expressions and other |
160 | pattern matching facilities (@pxref{Pattern Matching}). | |
161 | ||
0a57b83e AO |
162 | @menu |
163 | * POSIX Safety Concepts:: Safety concepts from POSIX. | |
164 | * Unsafe Features:: Features that make functions unsafe. | |
165 | * Conditionally Safe Features:: Features that make functions unsafe | |
166 | in the absence of workarounds. | |
167 | * Other Safety Remarks:: Additional safety features and remarks. | |
168 | @end menu | |
169 | ||
28f540f4 RM |
170 | @comment Roland sez: |
171 | @comment The GNU C library as it stands conforms to 1003.2 draft 11, which | |
172 | @comment specifies: | |
2c6fe0bd | 173 | @comment |
28f540f4 RM |
174 | @comment Several new macros in <limits.h>. |
175 | @comment popen, pclose | |
176 | @comment <regex.h> (which is not yet fully implemented--wait on this) | |
177 | @comment fnmatch | |
178 | @comment getopt | |
179 | @comment <glob.h> | |
180 | @comment <wordexp.h> (not yet implemented) | |
181 | @comment confstr | |
182 | ||
0a57b83e AO |
183 | @node POSIX Safety Concepts, Unsafe Features, , POSIX |
184 | @subsubsection POSIX Safety Concepts | |
185 | @cindex POSIX Safety Concepts | |
186 | ||
187 | This manual documents various safety properties of @glibcadj{} | |
188 | functions, in lines that follow their prototypes and look like: | |
189 | ||
190 | @sampsafety{@prelim{}@mtsafe{}@assafe{}@acsafe{}} | |
191 | ||
192 | The properties are assessed according to the criteria set forth in the | |
193 | POSIX standard for such safety contexts as Thread-, Async-Signal- and | |
194 | Async-Cancel- -Safety. Intuitive definitions of these properties, | |
195 | attempting to capture the meaning of the standard definitions, follow. | |
196 | ||
197 | @itemize @bullet | |
198 | ||
199 | @item | |
200 | @cindex MT-Safe | |
201 | @cindex Thread-Safe | |
202 | @code{MT-Safe} or Thread-Safe functions are safe to call in the presence | |
203 | of other threads. MT, in MT-Safe, stands for Multi Thread. | |
204 | ||
205 | Being MT-Safe does not imply a function is atomic, nor that it uses any | |
206 | of the memory synchronization mechanisms POSIX exposes to users. It is | |
207 | even possible that calling MT-Safe functions in sequence does not yield | |
208 | an MT-Safe combination. For example, having a thread call two MT-Safe | |
209 | functions one right after the other does not guarantee behavior | |
210 | equivalent to atomic execution of a combination of both functions, since | |
211 | concurrent calls in other threads may interfere in a destructive way. | |
212 | ||
213 | Whole-program optimizations that could inline functions across library | |
214 | interfaces may expose unsafe reordering, and so performing inlining | |
215 | across the @glibcadj{} interface is not recommended. The documented | |
216 | MT-Safety status is not guaranteed under whole-program optimization. | |
217 | However, functions defined in user-visible headers are designed to be | |
218 | safe for inlining. | |
219 | ||
220 | ||
221 | @item | |
222 | @cindex AS-Safe | |
223 | @cindex Async-Signal-Safe | |
224 | @code{AS-Safe} or Async-Signal-Safe functions are safe to call from | |
225 | asynchronous signal handlers. AS, in AS-Safe, stands for Asynchronous | |
226 | Signal. | |
227 | ||
228 | Many functions that are AS-Safe may set @code{errno}, or modify the | |
229 | floating-point environment, because their doing so does not make them | |
230 | unsuitable for use in signal handlers. However, programs could | |
231 | misbehave should asynchronous signal handlers modify this thread-local | |
232 | state, and the signal handling machinery cannot be counted on to | |
233 | preserve it. Therefore, signal handlers that call functions that may | |
234 | set @code{errno} or modify the floating-point environment @emph{must} | |
235 | save their original values, and restore them before returning. | |
236 | ||
237 | ||
238 | @item | |
239 | @cindex AC-Safe | |
240 | @cindex Async-Cancel-Safe | |
241 | @code{AC-Safe} or Async-Cancel-Safe functions are safe to call when | |
242 | asynchronous cancellation is enabled. AC in AC-Safe stands for | |
243 | Asynchronous Cancellation. | |
244 | ||
245 | The POSIX standard defines only three functions to be AC-Safe, namely | |
246 | @code{pthread_cancel}, @code{pthread_setcancelstate}, and | |
247 | @code{pthread_setcanceltype}. At present @theglibc{} provides no | |
248 | guarantees beyond these three functions, but does document which | |
249 | functions are presently AC-Safe. This documentation is provided for use | |
250 | by @theglibc{} developers. | |
251 | ||
252 | Just like signal handlers, cancellation cleanup routines must configure | |
253 | the floating point environment they require. The routines cannot assume | |
254 | a floating point environment, particularly when asynchronous | |
255 | cancellation is enabled. If the configuration of the floating point | |
256 | environment cannot be performed atomically then it is also possible that | |
257 | the environment encountered is internally inconsistent. | |
258 | ||
259 | ||
260 | @item | |
261 | @cindex MT-Unsafe | |
262 | @cindex Thread-Unsafe | |
263 | @cindex AS-Unsafe | |
264 | @cindex Async-Signal-Unsafe | |
265 | @cindex AC-Unsafe | |
266 | @cindex Async-Cancel-Unsafe | |
267 | @code{MT-Unsafe}, @code{AS-Unsafe}, @code{AC-Unsafe} functions are not | |
268 | safe to call within the safety contexts described above. Calling them | |
269 | within such contexts invokes undefined behavior. | |
270 | ||
271 | Functions not explicitly documented as safe in a safety context should | |
272 | be regarded as Unsafe. | |
273 | ||
274 | ||
275 | @item | |
276 | @cindex Preliminary | |
277 | @code{Preliminary} safety properties are documented, indicating these | |
278 | properties may @emph{not} be counted on in future releases of | |
279 | @theglibc{}. | |
280 | ||
281 | Such preliminary properties are the result of an assessment of the | |
282 | properties of our current implementation, rather than of what is | |
283 | mandated and permitted by current and future standards. | |
284 | ||
285 | Although we strive to abide by the standards, in some cases our | |
286 | implementation is safe even when the standard does not demand safety, | |
287 | and in other cases our implementation does not meet the standard safety | |
288 | requirements. The latter are most likely bugs; the former, when marked | |
289 | as @code{Preliminary}, should not be counted on: future standards may | |
290 | require changes that are not compatible with the additional safety | |
291 | properties afforded by the current implementation. | |
292 | ||
293 | Furthermore, the POSIX standard does not offer a detailed definition of | |
294 | safety. We assume that, by ``safe to call'', POSIX means that, as long | |
295 | as the program does not invoke undefined behavior, the ``safe to call'' | |
296 | function behaves as specified, and does not cause other functions to | |
297 | deviate from their specified behavior. We have chosen to use its loose | |
298 | definitions of safety, not because they are the best definitions to use, | |
299 | but because choosing them harmonizes this manual with POSIX. | |
300 | ||
301 | Please keep in mind that these are preliminary definitions and | |
302 | annotations, and certain aspects of the definitions are still under | |
303 | discussion and might be subject to clarification or change. | |
304 | ||
305 | Over time, we envision evolving the preliminary safety notes into stable | |
306 | commitments, as stable as those of our interfaces. As we do, we will | |
307 | remove the @code{Preliminary} keyword from safety notes. As long as the | |
308 | keyword remains, however, they are not to be regarded as a promise of | |
309 | future behavior. | |
310 | ||
311 | ||
312 | @end itemize | |
313 | ||
314 | Other keywords that appear in safety notes are defined in subsequent | |
315 | sections. | |
316 | ||
317 | ||
318 | @node Unsafe Features, Conditionally Safe Features, POSIX Safety Concepts, POSIX | |
319 | @subsubsection Unsafe Features | |
320 | @cindex Unsafe Features | |
321 | ||
322 | Functions that are unsafe to call in certain contexts are annotated with | |
323 | keywords that document their features that make them unsafe to call. | |
324 | AS-Unsafe features in this section indicate the functions are never safe | |
325 | to call when asynchronous signals are enabled. AC-Unsafe features | |
326 | indicate they are never safe to call when asynchronous cancellation is | |
327 | enabled. There are no MT-Unsafe marks in this section. | |
328 | ||
329 | @itemize @bullet | |
330 | ||
331 | @item @code{lock} | |
332 | @cindex lock | |
333 | ||
334 | Functions marked with @code{lock} as an AS-Unsafe feature may be | |
335 | interrupted by a signal while holding a non-recursive lock. If the | |
336 | signal handler calls another such function that takes the same lock, the | |
337 | result is a deadlock. | |
338 | ||
339 | Functions annotated with @code{lock} as an AC-Unsafe feature may, if | |
340 | cancelled asynchronously, fail to release a lock that would have been | |
341 | released if their execution had not been interrupted by asynchronous | |
342 | thread cancellation. Once a lock is left taken, attempts to take that | |
343 | lock will block indefinitely. | |
344 | ||
345 | ||
346 | @item @code{corrupt} | |
347 | @cindex corrupt | |
348 | ||
349 | Functions marked with @code{corrupt} as an AS-Unsafe feature may corrupt | |
350 | data structures and misbehave when they interrupt, or are interrupted | |
351 | by, another such function. Unlike functions marked with @code{lock}, | |
352 | these take recursive locks to avoid MT-Safety problems, but this is not | |
353 | enough to stop a signal handler from observing a partially-updated data | |
354 | structure. Further corruption may arise from the interrupted function's | |
355 | failure to notice updates made by signal handlers. | |
356 | ||
357 | Functions marked with @code{corrupt} as an AC-Unsafe feature may leave | |
358 | data structures in a corrupt, partially updated state. Subsequent uses | |
359 | of the data structure may misbehave. | |
360 | ||
361 | @c A special case, probably not worth documenting separately, involves | |
362 | @c reallocing, or even freeing pointers. Any case involving free could | |
363 | @c be easily turned into an ac-safe leak by resetting the pointer before | |
364 | @c releasing it; I don't think we have any case that calls for this sort | |
365 | @c of fixing. Fixing the realloc cases would require a new interface: | |
366 | @c instead of @code{ptr=realloc(ptr,size)} we'd have to introduce | |
367 | @c @code{acsafe_realloc(&ptr,size)} that would modify ptr before | |
368 | @c releasing the old memory. The ac-unsafe realloc could be implemented | |
369 | @c in terms of an internal interface with this semantics (say | |
370 | @c __acsafe_realloc), but since realloc can be overridden, the function | |
371 | @c we call to implement realloc should not be this internal interface, | |
372 | @c but another internal interface that calls __acsafe_realloc if realloc | |
373 | @c was not overridden, and calls the overridden realloc with async | |
374 | @c cancel disabled. --lxoliva | |
375 | ||
376 | ||
377 | @item @code{heap} | |
378 | @cindex heap | |
379 | ||
380 | Functions marked with @code{heap} may call heap memory management | |
381 | functions from the @code{malloc}/@code{free} family of functions and are | |
382 | only as safe as those functions. This note is thus equivalent to: | |
383 | ||
384 | @sampsafety{@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}} | |
385 | ||
386 | ||
387 | @c Check for cases that should have used plugin instead of or in | |
388 | @c addition to this. Then, after rechecking gettext, adjust i18n if | |
389 | @c needed. | |
390 | @item @code{dlopen} | |
391 | @cindex dlopen | |
392 | ||
393 | Functions marked with @code{dlopen} use the dynamic loader to load | |
394 | shared libraries into the current execution image. This involves | |
395 | opening files, mapping them into memory, allocating additional memory, | |
396 | resolving symbols, applying relocations and more, all of this while | |
397 | holding internal dynamic loader locks. | |
398 | ||
399 | The locks are enough for these functions to be AS- and AC-Unsafe, but | |
400 | other issues may arise. At present this is a placeholder for all | |
401 | potential safety issues raised by @code{dlopen}. | |
402 | ||
403 | @c dlopen runs init and fini sections of the module; does this mean | |
404 | @c dlopen always implies plugin? | |
405 | ||
406 | ||
407 | @item @code{plugin} | |
408 | @cindex plugin | |
409 | ||
410 | Functions annotated with @code{plugin} may run code from plugins that | |
411 | may be external to @theglibc{}. Such plugin functions are assumed to be | |
412 | MT-Safe, AS-Unsafe and AC-Unsafe. Examples of such plugins are stack | |
413 | @cindex NSS | |
414 | unwinding libraries, name service switch (NSS) and character set | |
415 | @cindex iconv | |
416 | conversion (iconv) back-ends. | |
417 | ||
418 | Although the plugins mentioned as examples are all brought in by means | |
419 | of dlopen, the @code{plugin} keyword does not imply any direct | |
420 | involvement of the dynamic loader or the @code{libdl} interfaces, those | |
421 | are covered by @code{dlopen}. For example, if one function loads a | |
422 | module and finds the addresses of some of its functions, while another | |
423 | just calls those already-resolved functions, the former will be marked | |
424 | with @code{dlopen}, whereas the latter will get the @code{plugin}. When | |
425 | a single function takes all of these actions, then it gets both marks. | |
426 | ||
427 | ||
428 | @item @code{i18n} | |
429 | @cindex i18n | |
430 | ||
431 | Functions marked with @code{i18n} may call internationalization | |
432 | functions of the @code{gettext} family and will be only as safe as those | |
433 | functions. This note is thus equivalent to: | |
434 | ||
435 | @sampsafety{@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascudlopen{}}@acunsafe{@acucorrupt{}}} | |
436 | ||
437 | ||
438 | @item @code{timer} | |
439 | @cindex timer | |
440 | ||
441 | Functions marked with @code{timer} use the @code{alarm} function or | |
442 | similar to set a time-out for a system call or a long-running operation. | |
443 | In a multi-threaded program, there is a risk that the time-out signal | |
444 | will be delivered to a different thread, thus failing to interrupt the | |
445 | intended thread. Besides being MT-Unsafe, such functions are always | |
446 | AS-Unsafe, because calling them in signal handlers may interfere with | |
447 | timers set in the interrupted code, and AC-Unsafe, because there is no | |
448 | safe way to guarantee an earlier timer will be reset in case of | |
449 | asynchronous cancellation. | |
450 | ||
451 | @end itemize | |
452 | ||
453 | ||
454 | @node Conditionally Safe Features, Other Safety Remarks, Unsafe Features, POSIX | |
455 | @subsubsection Conditionally Safe Features | |
456 | @cindex Conditionally Safe Features | |
457 | ||
458 | For some features that make functions unsafe to call in certain | |
459 | contexts, there are known ways to avoid the safety problem other than | |
460 | refraining from calling the function altogether. The keywords that | |
461 | follow refer to such features, and each of their definitions indicate | |
462 | how the whole program needs to be constrained in order to remove the | |
463 | safety problem indicated by the keyword. Only when all the reasons that | |
464 | make a function unsafe are observed and addressed, by applying the | |
465 | documented constraints, does the function become safe to call in a | |
466 | context. | |
467 | ||
468 | @itemize @bullet | |
469 | ||
470 | @item @code{init} | |
471 | @cindex init | |
472 | ||
473 | Functions marked with @code{init} as an MT-Unsafe feature perform | |
474 | MT-Unsafe initialization when they are first called. | |
475 | ||
476 | Calling such a function at least once in single-threaded mode removes | |
477 | this specific cause for the function to be regarded as MT-Unsafe. If no | |
478 | other cause for that remains, the function can then be safely called | |
479 | after other threads are started. | |
480 | ||
481 | Functions marked with @code{init} as an AS- or AC-Unsafe feature use the | |
482 | internal @code{libc_once} machinery or similar to initialize internal | |
483 | data structures. | |
484 | ||
485 | If a signal handler interrupts such an initializer, and calls any | |
486 | function that also performs @code{libc_once} initialization, it will | |
487 | deadlock if the thread library has been loaded. | |
488 | ||
489 | Furthermore, if an initializer is partially complete before it is | |
490 | canceled or interrupted by a signal whose handler requires the same | |
491 | initialization, some or all of the initialization may be performed more | |
492 | than once, leaking resources or even resulting in corrupt internal data. | |
493 | ||
494 | Applications that need to call functions marked with @code{init} as an | |
495 | AS- or AC-Unsafe feature should ensure the initialization is performed | |
496 | before configuring signal handlers or enabling cancellation, so that the | |
497 | AS- and AC-Safety issues related with @code{libc_once} do not arise. | |
498 | ||
499 | @c We may have to extend the annotations to cover conditions in which | |
500 | @c initialization may or may not occur, since an initial call in a safe | |
501 | @c context is no use if the initialization doesn't take place at that | |
502 | @c time: it doesn't remove the risk for later calls. | |
503 | ||
504 | ||
505 | @item @code{race} | |
506 | @cindex race | |
507 | ||
508 | Functions annotated with @code{race} as an MT-Safety issue operate on | |
509 | objects in ways that may cause data races or similar forms of | |
510 | destructive interference out of concurrent execution. In some cases, | |
511 | the objects are passed to the functions by users; in others, they are | |
512 | used by the functions to return values to users; in others, they are not | |
513 | even exposed to users. | |
514 | ||
515 | We consider access to objects passed as (indirect) arguments to | |
516 | functions to be data race free. The assurance of data race free objects | |
517 | is the caller's responsibility. We will not mark a function as | |
518 | MT-Unsafe or AS-Unsafe if it misbehaves when users fail to take the | |
519 | measures required by POSIX to avoid data races when dealing with such | |
520 | objects. As a general rule, if a function is documented as reading from | |
521 | an object passed (by reference) to it, or modifying it, users ought to | |
522 | use memory synchronization primitives to avoid data races just as they | |
523 | would should they perform the accesses themselves rather than by calling | |
524 | the library function. @code{FILE} streams are the exception to the | |
525 | general rule, in that POSIX mandates the library to guard against data | |
526 | races in many functions that manipulate objects of this specific opaque | |
527 | type. We regard this as a convenience provided to users, rather than as | |
528 | a general requirement whose expectations should extend to other types. | |
529 | ||
530 | In order to remind users that guarding certain arguments is their | |
531 | responsibility, we will annotate functions that take objects of certain | |
532 | types as arguments. We draw the line for objects passed by users as | |
533 | follows: objects whose types are exposed to users, and that users are | |
534 | expected to access directly, such as memory buffers, strings, and | |
535 | various user-visible @code{struct} types, do @emph{not} give reason for | |
536 | functions to be annotated with @code{race}. It would be noisy and | |
537 | redundant with the general requirement, and not many would be surprised | |
538 | by the library's lack of internal guards when accessing objects that can | |
539 | be accessed directly by users. | |
540 | ||
541 | As for objects that are opaque or opaque-like, in that they are to be | |
542 | manipulated only by passing them to library functions (e.g., | |
543 | @code{FILE}, @code{DIR}, @code{obstack}, @code{iconv_t}), there might be | |
544 | additional expectations as to internal coordination of access by the | |
545 | library. We will annotate, with @code{race} followed by a colon and the | |
546 | argument name, functions that take such objects but that do not take | |
547 | care of synchronizing access to them by default. For example, | |
548 | @code{FILE} stream @code{unlocked} functions will be annotated, but | |
549 | those that perform implicit locking on @code{FILE} streams by default | |
550 | will not, even though the implicit locking may be disabled on a | |
551 | per-stream basis. | |
552 | ||
553 | In either case, we will not regard as MT-Unsafe functions that may | |
554 | access user-supplied objects in unsafe ways should users fail to ensure | |
555 | the accesses are well defined. The notion prevails that users are | |
556 | expected to safeguard against data races any user-supplied objects that | |
557 | the library accesses on their behalf. | |
558 | ||
559 | @c The above describes @mtsrace; @mtasurace is described below. | |
560 | ||
561 | This user responsibility does not apply, however, to objects controlled | |
562 | by the library itself, such as internal objects and static buffers used | |
563 | to return values from certain calls. When the library doesn't guard | |
564 | them against concurrent uses, these cases are regarded as MT-Unsafe and | |
565 | AS-Unsafe (although the @code{race} mark under AS-Unsafe will be omitted | |
566 | as redundant with the one under MT-Unsafe). As in the case of | |
567 | user-exposed objects, the mark may be followed by a colon and an | |
568 | identifier. The identifier groups all functions that operate on a | |
569 | certain unguarded object; users may avoid the MT-Safety issues related | |
570 | with unguarded concurrent access to such internal objects by creating a | |
571 | non-recursive mutex related with the identifier, and always holding the | |
572 | mutex when calling any function marked as racy on that identifier, as | |
573 | they would have to should the identifier be an object under user | |
574 | control. The non-recursive mutex avoids the MT-Safety issue, but it | |
575 | trades one AS-Safety issue for another, so use in asynchronous signals | |
576 | remains undefined. | |
577 | ||
578 | When the identifier relates to a static buffer used to hold return | |
579 | values, the mutex must be held for as long as the buffer remains in use | |
580 | by the caller. Many functions that return pointers to static buffers | |
581 | offer reentrant variants that store return values in caller-supplied | |
582 | buffers instead. In some cases, such as @code{tmpname}, the variant is | |
583 | chosen not by calling an alternate entry point, but by passing a | |
584 | non-@code{NULL} pointer to the buffer in which the returned values are | |
585 | to be stored. These variants are generally preferable in multi-threaded | |
586 | programs, although some of them are not MT-Safe because of other | |
587 | internal buffers, also documented with @code{race} notes. | |
588 | ||
589 | ||
590 | @item @code{const} | |
591 | @cindex const | |
592 | ||
593 | Functions marked with @code{const} as an MT-Safety issue non-atomically | |
594 | modify internal objects that are better regarded as constant, because a | |
595 | substantial portion of @theglibc{} accesses them without | |
596 | synchronization. Unlike @code{race}, that causes both readers and | |
597 | writers of internal objects to be regarded as MT-Unsafe and AS-Unsafe, | |
598 | this mark is applied to writers only. Writers remain equally MT- and | |
599 | AS-Unsafe to call, but the then-mandatory constness of objects they | |
600 | modify enables readers to be regarded as MT-Safe and AS-Safe (as long as | |
601 | no other reasons for them to be unsafe remain), since the lack of | |
602 | synchronization is not a problem when the objects are effectively | |
603 | constant. | |
604 | ||
605 | The identifier that follows the @code{const} mark will appear by itself | |
606 | as a safety note in readers. Programs that wish to work around this | |
607 | safety issue, so as to call writers, may use a non-recursve | |
608 | @code{rwlock} associated with the identifier, and guard @emph{all} calls | |
609 | to functions marked with @code{const} followed by the identifier with a | |
610 | write lock, and @emph{all} calls to functions marked with the identifier | |
611 | by itself with a read lock. The non-recursive locking removes the | |
612 | MT-Safety problem, but it trades one AS-Safety problem for another, so | |
613 | use in asynchronous signals remains undefined. | |
614 | ||
615 | @c But what if, instead of marking modifiers with const:id and readers | |
616 | @c with just id, we marked writers with race:id and readers with ro:id? | |
617 | @c Instead of having to define each instance of “id”, we'd have a | |
618 | @c general pattern governing all such “id”s, wherein race:id would | |
619 | @c suggest the need for an exclusive/write lock to make the function | |
620 | @c safe, whereas ro:id would indicate “id” is expected to be read-only, | |
621 | @c but if any modifiers are called (while holding an exclusive lock), | |
622 | @c then ro:id-marked functions ought to be guarded with a read lock for | |
623 | @c safe operation. ro:env or ro:locale, for example, seems to convey | |
624 | @c more clearly the expectations and the meaning, than just env or | |
625 | @c locale. | |
626 | ||
627 | ||
628 | @item @code{sig} | |
629 | @cindex sig | |
630 | ||
631 | Functions marked with @code{sig} as a MT-Safety issue (that implies an | |
632 | identical AS-Safety issue, omitted for brevity) may temporarily install | |
633 | a signal handler for internal purposes, which may interfere with other | |
634 | uses of the signal, identified after a colon. | |
635 | ||
636 | This safety problem can be worked around by ensuring that no other uses | |
637 | of the signal will take place for the duration of the call. Holding a | |
638 | non-recursive mutex while calling all functions that use the same | |
639 | temporary signal; blocking that signal before the call and resetting its | |
640 | handler afterwards is recommended. | |
641 | ||
642 | There is no safe way to guarantee the original signal handler is | |
643 | restored in case of asynchronous cancellation, therefore so-marked | |
644 | functions are also AC-Unsafe. | |
645 | ||
646 | @c fixme: at least deferred cancellation should get it right, and would | |
647 | @c obviate the restoring bit below, and the qualifier above. | |
648 | ||
649 | Besides the measures recommended to work around the MT- and AS-Safety | |
650 | problem, in order to avert the cancellation problem, disabling | |
651 | asynchronous cancellation @emph{and} installing a cleanup handler to | |
652 | restore the signal to the desired state and to release the mutex are | |
653 | recommended. | |
654 | ||
655 | ||
656 | @item @code{term} | |
657 | @cindex term | |
658 | ||
659 | Functions marked with @code{term} as an MT-Safety issue may change the | |
660 | terminal settings in the recommended way, namely: call @code{tcgetattr}, | |
661 | modify some flags, and then call @code{tcsetattr}; this creates a window | |
662 | in which changes made by other threads are lost. Thus, functions marked | |
663 | with @code{term} are MT-Unsafe. The same window enables changes made by | |
664 | asynchronous signals to be lost. These functions are also AS-Unsafe, | |
665 | but the corresponding mark is omitted as redundant. | |
666 | ||
667 | It is thus advisable for applications using the terminal to avoid | |
668 | concurrent and reentrant interactions with it, by not using it in signal | |
669 | handlers or blocking signals that might use it, and holding a lock while | |
670 | calling these functions and interacting with the terminal. This lock | |
671 | should also be used for mutual exclusion with functions marked with | |
06e90b14 AO |
672 | @code{@mtasurace{:tcattr(fd)}}, where @var{fd} is a file descriptor for |
673 | the controlling terminal. The caller may use a single mutex for | |
674 | simplicity, or use one mutex per terminal, even if referenced by | |
675 | different file descriptors. | |
0a57b83e AO |
676 | |
677 | Functions marked with @code{term} as an AC-Safety issue are supposed to | |
678 | restore terminal settings to their original state, after temporarily | |
679 | changing them, but they may fail to do so if cancelled. | |
680 | ||
681 | @c fixme: at least deferred cancellation should get it right, and would | |
682 | @c obviate the restoring bit below, and the qualifier above. | |
683 | ||
684 | Besides the measures recommended to work around the MT- and AS-Safety | |
685 | problem, in order to avert the cancellation problem, disabling | |
686 | asynchronous cancellation @emph{and} installing a cleanup handler to | |
687 | restore the terminal settings to the original state and to release the | |
688 | mutex are recommended. | |
689 | ||
690 | ||
691 | @end itemize | |
692 | ||
693 | ||
694 | @node Other Safety Remarks, , Conditionally Safe Features, POSIX | |
695 | @subsubsection Other Safety Remarks | |
696 | @cindex Other Safety Remarks | |
697 | ||
698 | Additional keywords may be attached to functions, indicating features | |
699 | that do not make a function unsafe to call, but that may need to be | |
700 | taken into account in certain classes of programs: | |
701 | ||
702 | @itemize @bullet | |
703 | ||
0a57b83e AO |
704 | @item @code{locale} |
705 | @cindex locale | |
706 | ||
707 | Functions annotated with @code{locale} as an MT-Safety issue read from | |
708 | the locale object without any form of synchronization. Functions | |
709 | annotated with @code{locale} called concurrently with locale changes may | |
710 | behave in ways that do not correspond to any of the locales active | |
711 | during their execution, but an unpredictable mix thereof. | |
712 | ||
713 | We do not mark these functions as MT- or AS-Unsafe, however, because | |
714 | functions that modify the locale object are marked with | |
715 | @code{const:locale} and regarded as unsafe. Being unsafe, the latter | |
716 | are not to be called when multiple threads are running or asynchronous | |
717 | signals are enabled, and so the locale can be considered effectively | |
718 | constant in these contexts, which makes the former safe. | |
719 | ||
720 | @c Should the locking strategy suggested under @code{const} be used, | |
721 | @c failure to guard locale uses is not as fatal as data races in | |
722 | @c general: unguarded uses will @emph{not} follow dangling pointers or | |
723 | @c access uninitialized, unmapped or recycled memory. Each access will | |
724 | @c read from a consistent locale object that is or was active at some | |
725 | @c point during its execution. Without synchronization, however, it | |
726 | @c cannot even be assumed that, after a change in locale, earlier | |
727 | @c locales will no longer be used, even after the newly-chosen one is | |
728 | @c used in the thread. Nevertheless, even though unguarded reads from | |
729 | @c the locale will not violate type safety, functions that access the | |
730 | @c locale multiple times may invoke all sorts of undefined behavior | |
731 | @c because of the unexpected locale changes. | |
732 | ||
733 | ||
0a57b83e AO |
734 | @item @code{env} |
735 | @cindex env | |
736 | ||
737 | Functions marked with @code{env} as an MT-Safety issue access the | |
738 | environment with @code{getenv} or similar, without any guards to ensure | |
739 | safety in the presence of concurrent modifications. | |
740 | ||
741 | We do not mark these functions as MT- or AS-Unsafe, however, because | |
742 | functions that modify the environment are all marked with | |
743 | @code{const:env} and regarded as unsafe. Being unsafe, the latter are | |
744 | not to be called when multiple threads are running or asynchronous | |
745 | signals are enabled, and so the environment can be considered | |
746 | effectively constant in these contexts, which makes the former safe. | |
747 | ||
748 | ||
749 | @item @code{hostid} | |
750 | @cindex hostid | |
751 | ||
752 | The function marked with @code{hostid} as an MT-Safety issue reads from | |
753 | the system-wide data structures that hold the ``host ID'' of the | |
754 | machine. These data structures cannot generally be modified atomically. | |
755 | Since it is expected that the ``host ID'' will not normally change, the | |
756 | function that reads from it (@code{gethostid}) is regarded as safe, | |
757 | whereas the function that modifies it (@code{sethostid}) is marked with | |
758 | @code{@mtasuconst{:@mtshostid{}}}, indicating it may require special | |
759 | care if it is to be called. In this specific case, the special care | |
760 | amounts to system-wide (not merely intra-process) coordination. | |
761 | ||
762 | ||
763 | @item @code{sigintr} | |
764 | @cindex sigintr | |
765 | ||
766 | Functions marked with @code{sigintr} as an MT-Safety issue access the | |
767 | @code{_sigintr} internal data structure without any guards to ensure | |
768 | safety in the presence of concurrent modifications. | |
769 | ||
770 | We do not mark these functions as MT- or AS-Unsafe, however, because | |
771 | functions that modify the this data structure are all marked with | |
772 | @code{const:sigintr} and regarded as unsafe. Being unsafe, the latter | |
773 | are not to be called when multiple threads are running or asynchronous | |
774 | signals are enabled, and so the data structure can be considered | |
775 | effectively constant in these contexts, which makes the former safe. | |
776 | ||
777 | ||
778 | @item @code{fd} | |
779 | @cindex fd | |
780 | ||
781 | Functions annotated with @code{fd} as an AC-Safety issue may leak file | |
782 | descriptors if asynchronous thread cancellation interrupts their | |
783 | execution. | |
784 | ||
785 | Functions that allocate or deallocate file descriptors will generally be | |
786 | marked as such. Even if they attempted to protect the file descriptor | |
787 | allocation and deallocation with cleanup regions, allocating a new | |
788 | descriptor and storing its number where the cleanup region could release | |
789 | it cannot be performed as a single atomic operation. Similarly, | |
790 | releasing the descriptor and taking it out of the data structure | |
791 | normally responsible for releasing it cannot be performed atomically. | |
792 | There will always be a window in which the descriptor cannot be released | |
793 | because it was not stored in the cleanup handler argument yet, or it was | |
794 | already taken out before releasing it. It cannot be taken out after | |
795 | release: an open descriptor could mean either that the descriptor still | |
796 | has to be closed, or that it already did so but the descriptor was | |
797 | reallocated by another thread or signal handler. | |
798 | ||
799 | Such leaks could be internally avoided, with some performance penalty, | |
800 | by temporarily disabling asynchronous thread cancellation. However, | |
801 | since callers of allocation or deallocation functions would have to do | |
802 | this themselves, to avoid the same sort of leak in their own layer, it | |
803 | makes more sense for the library to assume they are taking care of it | |
804 | than to impose a performance penalty that is redundant when the problem | |
805 | is solved in upper layers, and insufficient when it is not. | |
806 | ||
807 | This remark by itself does not cause a function to be regarded as | |
808 | AC-Unsafe. However, cumulative effects of such leaks may pose a | |
809 | problem for some programs. If this is the case, suspending asynchronous | |
810 | cancellation for the duration of calls to such functions is recommended. | |
811 | ||
812 | ||
813 | @item @code{mem} | |
814 | @cindex mem | |
815 | ||
816 | Functions annotated with @code{mem} as an AC-Safety issue may leak | |
817 | memory if asynchronous thread cancellation interrupts their execution. | |
818 | ||
819 | The problem is similar to that of file descriptors: there is no atomic | |
820 | interface to allocate memory and store its address in the argument to a | |
821 | cleanup handler, or to release it and remove its address from that | |
822 | argument, without at least temporarily disabling asynchronous | |
823 | cancellation, which these functions do not do. | |
824 | ||
825 | This remark does not by itself cause a function to be regarded as | |
826 | generally AC-Unsafe. However, cumulative effects of such leaks may be | |
827 | severe enough for some programs that disabling asynchronous cancellation | |
828 | for the duration of calls to such functions may be required. | |
829 | ||
830 | ||
831 | @item @code{cwd} | |
832 | @cindex cwd | |
833 | ||
834 | Functions marked with @code{cwd} as an MT-Safety issue may temporarily | |
835 | change the current working directory during their execution, which may | |
836 | cause relative pathnames to be resolved in unexpected ways in other | |
837 | threads or within asynchronous signal or cancellation handlers. | |
838 | ||
839 | This is not enough of a reason to mark so-marked functions as MT- or | |
840 | AS-Unsafe, but when this behavior is optional (e.g., @code{nftw} with | |
841 | @code{FTW_CHDIR}), avoiding the option may be a good alternative to | |
842 | using full pathnames or file descriptor-relative (e.g. @code{openat}) | |
843 | system calls. | |
844 | ||
845 | ||
846 | @item @code{!posix} | |
847 | @cindex !posix | |
848 | ||
849 | This remark, as an MT-, AS- or AC-Safety note to a function, indicates | |
850 | the safety status of the function is known to differ from the specified | |
851 | status in the POSIX standard. For example, POSIX does not require a | |
852 | function to be Safe, but our implementation is, or vice-versa. | |
853 | ||
854 | For the time being, the absence of this remark does not imply the safety | |
855 | properties we documented are identical to those mandated by POSIX for | |
856 | the corresponding functions. | |
857 | ||
858 | ||
06e90b14 AO |
859 | @item @code{:identifier} |
860 | @cindex :identifier | |
861 | ||
862 | Annotations may sometimes be followed by identifiers, intended to group | |
863 | several functions that e.g. access the data structures in an unsafe way, | |
864 | as in @code{race} and @code{const}, or to provide more specific | |
865 | information, such as naming a signal in a function marked with | |
866 | @code{sig}. It is envisioned that it may be applied to @code{lock} and | |
867 | @code{corrupt} as well in the future. | |
868 | ||
869 | In most cases, the identifier will name a set of functions, but it may | |
870 | name global objects or function arguments, or identifiable properties or | |
871 | logical components associated with them, with a notation such as | |
872 | e.g. @code{:buf(arg)} to denote a buffer associated with the argument | |
873 | @var{arg}, or @code{:tcattr(fd)} to denote the terminal attributes of a | |
874 | file descriptor @var{fd}. | |
875 | ||
876 | The most common use for identifiers is to provide logical groups of | |
877 | functions and arguments that need to be protected by the same | |
878 | synchronization primitive in order to ensure safe operation in a given | |
879 | context. | |
880 | ||
881 | ||
882 | @item @code{/condition} | |
883 | @cindex /condition | |
884 | ||
885 | Some safety annotations may be conditional, in that they only apply if a | |
886 | boolean expression involving arguments, global variables or even the | |
5a1021e8 | 887 | underlying kernel evaluates to true. Such conditions as |
06e90b14 AO |
888 | @code{/hurd} or @code{/!linux!bsd} indicate the preceding marker only |
889 | applies when the underlying kernel is the HURD, or when it is neither | |
890 | Linux nor a BSD kernel, respectively. @code{/!ps} and | |
891 | @code{/one_per_line} indicate the preceding marker only applies when | |
892 | argument @var{ps} is NULL, or global variable @var{one_per_line} is | |
893 | nonzero. | |
894 | ||
895 | When all marks that render a function unsafe are adorned with such | |
896 | conditions, and none of the named conditions hold, then the function can | |
897 | be regarded as safe. | |
898 | ||
899 | ||
0a57b83e AO |
900 | @end itemize |
901 | ||
28f540f4 RM |
902 | |
903 | @node Berkeley Unix, SVID, POSIX, Standards and Portability | |
904 | @subsection Berkeley Unix | |
905 | @cindex BSD Unix | |
906 | @cindex 4.@var{n} BSD Unix | |
907 | @cindex Berkeley Unix | |
908 | @cindex SunOS | |
909 | @cindex Unix, Berkeley | |
910 | ||
1f77f049 | 911 | @Theglibc{} defines facilities from some versions of Unix which |
28f540f4 RM |
912 | are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD, |
913 | and 4.4 BSD Unix systems (also known as @dfn{Berkeley Unix}) and from | |
914 | @dfn{SunOS} (a popular 4.2 BSD derivative that includes some Unix System | |
f65fd747 | 915 | V functionality). These systems support most of the @w{ISO C} and POSIX |
28f540f4 RM |
916 | facilities, and 4.4 BSD and newer releases of SunOS in fact support them all. |
917 | ||
918 | The BSD facilities include symbolic links (@pxref{Symbolic Links}), the | |
919 | @code{select} function (@pxref{Waiting for I/O}), the BSD signal | |
920 | functions (@pxref{BSD Signal Handling}), and sockets (@pxref{Sockets}). | |
921 | ||
b13927da | 922 | @node SVID, XPG, Berkeley Unix, Standards and Portability |
28f540f4 RM |
923 | @subsection SVID (The System V Interface Description) |
924 | @cindex SVID | |
925 | @cindex System V Unix | |
926 | @cindex Unix, System V | |
927 | ||
928 | The @dfn{System V Interface Description} (SVID) is a document describing | |
929 | the AT&T Unix System V operating system. It is to some extent a | |
930 | superset of the POSIX standard (@pxref{POSIX}). | |
931 | ||
1f77f049 | 932 | @Theglibc{} defines most of the facilities required by the SVID |
f65fd747 | 933 | that are not also required by the @w{ISO C} or POSIX standards, for |
28f540f4 RM |
934 | compatibility with System V Unix and other Unix systems (such as |
935 | SunOS) which include these facilities. However, many of the more | |
936 | obscure and less generally useful facilities required by the SVID are | |
937 | not included. (In fact, Unix System V itself does not provide them all.) | |
938 | ||
b13927da UD |
939 | The supported facilities from System V include the methods for |
940 | inter-process communication and shared memory, the @code{hsearch} and | |
941 | @code{drand48} families of functions, @code{fmtmsg} and several of the | |
942 | mathematical functions. | |
943 | ||
944 | @node XPG, , SVID, Standards and Portability | |
945 | @subsection XPG (The X/Open Portability Guide) | |
946 | ||
947 | The X/Open Portability Guide, published by the X/Open Company, Ltd., is | |
948 | a more general standard than POSIX. X/Open owns the Unix copyright and | |
949 | the XPG specifies the requirements for systems which are intended to be | |
950 | a Unix system. | |
951 | ||
1f77f049 | 952 | @Theglibc{} complies to the X/Open Portability Guide, Issue 4.2, |
714a562f | 953 | with all extensions common to XSI (X/Open System Interface) |
b13927da UD |
954 | compliant systems and also all X/Open UNIX extensions. |
955 | ||
956 | The additions on top of POSIX are mainly derived from functionality | |
957 | available in @w{System V} and BSD systems. Some of the really bad | |
958 | mistakes in @w{System V} systems were corrected, though. Since | |
959 | fulfilling the XPG standard with the Unix extensions is a | |
960 | precondition for getting the Unix brand chances are good that the | |
961 | functionality is available on commercial systems. | |
28f540f4 RM |
962 | |
963 | ||
964 | @node Using the Library, Roadmap to the Manual, Standards and Portability, Introduction | |
965 | @section Using the Library | |
966 | ||
967 | This section describes some of the practical issues involved in using | |
1f77f049 | 968 | @theglibc{}. |
28f540f4 RM |
969 | |
970 | @menu | |
971 | * Header Files:: How to include the header files in your | |
2c6fe0bd | 972 | programs. |
28f540f4 RM |
973 | * Macro Definitions:: Some functions in the library may really |
974 | be implemented as macros. | |
975 | * Reserved Names:: The C standard reserves some names for | |
976 | the library, and some for users. | |
977 | * Feature Test Macros:: How to control what names are defined. | |
978 | @end menu | |
979 | ||
980 | @node Header Files, Macro Definitions, , Using the Library | |
981 | @subsection Header Files | |
982 | @cindex header files | |
983 | ||
984 | Libraries for use by C programs really consist of two parts: @dfn{header | |
985 | files} that define types and macros and declare variables and | |
986 | functions; and the actual library or @dfn{archive} that contains the | |
987 | definitions of the variables and functions. | |
988 | ||
989 | (Recall that in C, a @dfn{declaration} merely provides information that | |
990 | a function or variable exists and gives its type. For a function | |
991 | declaration, information about the types of its arguments might be | |
992 | provided as well. The purpose of declarations is to allow the compiler | |
993 | to correctly process references to the declared variables and functions. | |
994 | A @dfn{definition}, on the other hand, actually allocates storage for a | |
995 | variable or says what a function does.) | |
996 | @cindex definition (compared to declaration) | |
997 | @cindex declaration (compared to definition) | |
998 | ||
1f77f049 | 999 | In order to use the facilities in @theglibc{}, you should be sure |
28f540f4 RM |
1000 | that your program source files include the appropriate header files. |
1001 | This is so that the compiler has declarations of these facilities | |
1002 | available and can correctly process references to them. Once your | |
1003 | program has been compiled, the linker resolves these references to | |
1004 | the actual definitions provided in the archive file. | |
1005 | ||
1006 | Header files are included into a program source file by the | |
1007 | @samp{#include} preprocessor directive. The C language supports two | |
1008 | forms of this directive; the first, | |
1009 | ||
1010 | @smallexample | |
1011 | #include "@var{header}" | |
1012 | @end smallexample | |
1013 | ||
1014 | @noindent | |
1015 | is typically used to include a header file @var{header} that you write | |
1016 | yourself; this would contain definitions and declarations describing the | |
1017 | interfaces between the different parts of your particular application. | |
1018 | By contrast, | |
1019 | ||
1020 | @smallexample | |
1021 | #include <file.h> | |
1022 | @end smallexample | |
1023 | ||
1024 | @noindent | |
1025 | is typically used to include a header file @file{file.h} that contains | |
1026 | definitions and declarations for a standard library. This file would | |
1027 | normally be installed in a standard place by your system administrator. | |
1028 | You should use this second form for the C library header files. | |
1029 | ||
1030 | Typically, @samp{#include} directives are placed at the top of the C | |
1031 | source file, before any other code. If you begin your source files with | |
1032 | some comments explaining what the code in the file does (a good idea), | |
1033 | put the @samp{#include} directives immediately afterwards, following the | |
1034 | feature test macro definition (@pxref{Feature Test Macros}). | |
1035 | ||
1036 | For more information about the use of header files and @samp{#include} | |
1037 | directives, @pxref{Header Files,,, cpp.info, The GNU C Preprocessor | |
0005e54f | 1038 | Manual}. |
28f540f4 | 1039 | |
1f77f049 | 1040 | @Theglibc{} provides several header files, each of which contains |
28f540f4 RM |
1041 | the type and macro definitions and variable and function declarations |
1042 | for a group of related facilities. This means that your programs may | |
1043 | need to include several header files, depending on exactly which | |
1044 | facilities you are using. | |
1045 | ||
1046 | Some library header files include other library header files | |
1047 | automatically. However, as a matter of programming style, you should | |
1048 | not rely on this; it is better to explicitly include all the header | |
1f77f049 JM |
1049 | files required for the library facilities you are using. The @glibcadj{} |
1050 | header files have been written in such a way that it doesn't | |
28f540f4 RM |
1051 | matter if a header file is accidentally included more than once; |
1052 | including a header file a second time has no effect. Likewise, if your | |
1053 | program needs to include multiple header files, the order in which they | |
1054 | are included doesn't matter. | |
1055 | ||
1056 | @strong{Compatibility Note:} Inclusion of standard header files in any | |
f65fd747 | 1057 | order and any number of times works in any @w{ISO C} implementation. |
28f540f4 RM |
1058 | However, this has traditionally not been the case in many older C |
1059 | implementations. | |
1060 | ||
1061 | Strictly speaking, you don't @emph{have to} include a header file to use | |
1062 | a function it declares; you could declare the function explicitly | |
1063 | yourself, according to the specifications in this manual. But it is | |
1064 | usually better to include the header file because it may define types | |
1065 | and macros that are not otherwise available and because it may define | |
1066 | more efficient macro replacements for some functions. It is also a sure | |
1067 | way to have the correct declaration. | |
1068 | ||
1069 | @node Macro Definitions, Reserved Names, Header Files, Using the Library | |
1070 | @subsection Macro Definitions of Functions | |
1071 | @cindex shadowing functions with macros | |
1072 | @cindex removing macros that shadow functions | |
1073 | @cindex undefining macros that shadow functions | |
1074 | ||
1075 | If we describe something as a function in this manual, it may have a | |
1076 | macro definition as well. This normally has no effect on how your | |
1077 | program runs---the macro definition does the same thing as the function | |
1078 | would. In particular, macro equivalents for library functions evaluate | |
1079 | arguments exactly once, in the same way that a function call would. The | |
1080 | main reason for these macro definitions is that sometimes they can | |
1081 | produce an inline expansion that is considerably faster than an actual | |
1082 | function call. | |
1083 | ||
1084 | Taking the address of a library function works even if it is also | |
1085 | defined as a macro. This is because, in this context, the name of the | |
1086 | function isn't followed by the left parenthesis that is syntactically | |
1087 | necessary to recognize a macro call. | |
1088 | ||
1089 | You might occasionally want to avoid using the macro definition of a | |
1090 | function---perhaps to make your program easier to debug. There are | |
1091 | two ways you can do this: | |
1092 | ||
1093 | @itemize @bullet | |
2c6fe0bd | 1094 | @item |
28f540f4 RM |
1095 | You can avoid a macro definition in a specific use by enclosing the name |
1096 | of the function in parentheses. This works because the name of the | |
1097 | function doesn't appear in a syntactic context where it is recognizable | |
1098 | as a macro call. | |
1099 | ||
1100 | @item | |
1101 | You can suppress any macro definition for a whole source file by using | |
1102 | the @samp{#undef} preprocessor directive, unless otherwise stated | |
1103 | explicitly in the description of that facility. | |
1104 | @end itemize | |
1105 | ||
1106 | For example, suppose the header file @file{stdlib.h} declares a function | |
1107 | named @code{abs} with | |
1108 | ||
1109 | @smallexample | |
1110 | extern int abs (int); | |
1111 | @end smallexample | |
1112 | ||
1113 | @noindent | |
1114 | and also provides a macro definition for @code{abs}. Then, in: | |
1115 | ||
1116 | @smallexample | |
1117 | #include <stdlib.h> | |
b13927da | 1118 | int f (int *i) @{ return abs (++*i); @} |
28f540f4 RM |
1119 | @end smallexample |
1120 | ||
1121 | @noindent | |
1122 | the reference to @code{abs} might refer to either a macro or a function. | |
1123 | On the other hand, in each of the following examples the reference is | |
1124 | to a function and not a macro. | |
1125 | ||
1126 | @smallexample | |
1127 | #include <stdlib.h> | |
b13927da | 1128 | int g (int *i) @{ return (abs) (++*i); @} |
28f540f4 RM |
1129 | |
1130 | #undef abs | |
b13927da | 1131 | int h (int *i) @{ return abs (++*i); @} |
28f540f4 RM |
1132 | @end smallexample |
1133 | ||
1134 | Since macro definitions that double for a function behave in | |
1135 | exactly the same way as the actual function version, there is usually no | |
1136 | need for any of these methods. In fact, removing macro definitions usually | |
1137 | just makes your program slower. | |
1138 | ||
1139 | ||
1140 | @node Reserved Names, Feature Test Macros, Macro Definitions, Using the Library | |
1141 | @subsection Reserved Names | |
1142 | @cindex reserved names | |
1143 | @cindex name space | |
1144 | ||
1145 | The names of all library types, macros, variables and functions that | |
f65fd747 | 1146 | come from the @w{ISO C} standard are reserved unconditionally; your program |
28f540f4 RM |
1147 | @strong{may not} redefine these names. All other library names are |
1148 | reserved if your program explicitly includes the header file that | |
1149 | defines or declares them. There are several reasons for these | |
1150 | restrictions: | |
1151 | ||
1152 | @itemize @bullet | |
1153 | @item | |
1154 | Other people reading your code could get very confused if you were using | |
1155 | a function named @code{exit} to do something completely different from | |
1156 | what the standard @code{exit} function does, for example. Preventing | |
1157 | this situation helps to make your programs easier to understand and | |
1158 | contributes to modularity and maintainability. | |
1159 | ||
1160 | @item | |
1161 | It avoids the possibility of a user accidentally redefining a library | |
1162 | function that is called by other library functions. If redefinition | |
1163 | were allowed, those other functions would not work properly. | |
1164 | ||
1165 | @item | |
1166 | It allows the compiler to do whatever special optimizations it pleases | |
1167 | on calls to these functions, without the possibility that they may have | |
1168 | been redefined by the user. Some library facilities, such as those for | |
1169 | dealing with variadic arguments (@pxref{Variadic Functions}) | |
1170 | and non-local exits (@pxref{Non-Local Exits}), actually require a | |
1171 | considerable amount of cooperation on the part of the C compiler, and | |
0bc93a2f AJ |
1172 | with respect to the implementation, it might be easier for the compiler |
1173 | to treat these as built-in parts of the language. | |
28f540f4 RM |
1174 | @end itemize |
1175 | ||
1176 | In addition to the names documented in this manual, reserved names | |
1177 | include all external identifiers (global functions and variables) that | |
1178 | begin with an underscore (@samp{_}) and all identifiers regardless of | |
1179 | use that begin with either two underscores or an underscore followed by | |
1180 | a capital letter are reserved names. This is so that the library and | |
1181 | header files can define functions, variables, and macros for internal | |
1182 | purposes without risk of conflict with names in user programs. | |
1183 | ||
1184 | Some additional classes of identifier names are reserved for future | |
1185 | extensions to the C language or the POSIX.1 environment. While using these | |
1186 | names for your own purposes right now might not cause a problem, they do | |
1187 | raise the possibility of conflict with future versions of the C | |
1188 | or POSIX standards, so you should avoid these names. | |
1189 | ||
1190 | @itemize @bullet | |
2c6fe0bd | 1191 | @item |
28f540f4 RM |
1192 | Names beginning with a capital @samp{E} followed a digit or uppercase |
1193 | letter may be used for additional error code names. @xref{Error | |
1194 | Reporting}. | |
1195 | ||
1196 | @item | |
1197 | Names that begin with either @samp{is} or @samp{to} followed by a | |
1198 | lowercase letter may be used for additional character testing and | |
1199 | conversion functions. @xref{Character Handling}. | |
1200 | ||
1201 | @item | |
1202 | Names that begin with @samp{LC_} followed by an uppercase letter may be | |
1203 | used for additional macros specifying locale attributes. | |
1204 | @xref{Locales}. | |
1205 | ||
1206 | @item | |
1207 | Names of all existing mathematics functions (@pxref{Mathematics}) | |
1208 | suffixed with @samp{f} or @samp{l} are reserved for corresponding | |
1209 | functions that operate on @code{float} and @code{long double} arguments, | |
1210 | respectively. | |
1211 | ||
1212 | @item | |
1213 | Names that begin with @samp{SIG} followed by an uppercase letter are | |
1214 | reserved for additional signal names. @xref{Standard Signals}. | |
1215 | ||
1216 | @item | |
1217 | Names that begin with @samp{SIG_} followed by an uppercase letter are | |
1218 | reserved for additional signal actions. @xref{Basic Signal Handling}. | |
1219 | ||
1220 | @item | |
1221 | Names beginning with @samp{str}, @samp{mem}, or @samp{wcs} followed by a | |
1222 | lowercase letter are reserved for additional string and array functions. | |
1223 | @xref{String and Array Utilities}. | |
1224 | ||
1225 | @item | |
1226 | Names that end with @samp{_t} are reserved for additional type names. | |
1227 | @end itemize | |
1228 | ||
1229 | In addition, some individual header files reserve names beyond | |
1230 | those that they actually define. You only need to worry about these | |
1231 | restrictions if your program includes that particular header file. | |
1232 | ||
1233 | @itemize @bullet | |
1234 | @item | |
1235 | The header file @file{dirent.h} reserves names prefixed with | |
1236 | @samp{d_}. | |
1237 | @pindex dirent.h | |
1238 | ||
1239 | @item | |
1240 | The header file @file{fcntl.h} reserves names prefixed with | |
1241 | @samp{l_}, @samp{F_}, @samp{O_}, and @samp{S_}. | |
1242 | @pindex fcntl.h | |
1243 | ||
1244 | @item | |
1245 | The header file @file{grp.h} reserves names prefixed with @samp{gr_}. | |
1246 | @pindex grp.h | |
1247 | ||
1248 | @item | |
1249 | The header file @file{limits.h} reserves names suffixed with @samp{_MAX}. | |
1250 | @pindex limits.h | |
1251 | ||
1252 | @item | |
1253 | The header file @file{pwd.h} reserves names prefixed with @samp{pw_}. | |
1254 | @pindex pwd.h | |
1255 | ||
1256 | @item | |
1257 | The header file @file{signal.h} reserves names prefixed with @samp{sa_} | |
1258 | and @samp{SA_}. | |
1259 | @pindex signal.h | |
1260 | ||
1261 | @item | |
1262 | The header file @file{sys/stat.h} reserves names prefixed with @samp{st_} | |
1263 | and @samp{S_}. | |
1264 | @pindex sys/stat.h | |
1265 | ||
1266 | @item | |
1267 | The header file @file{sys/times.h} reserves names prefixed with @samp{tms_}. | |
1268 | @pindex sys/times.h | |
1269 | ||
1270 | @item | |
1271 | The header file @file{termios.h} reserves names prefixed with @samp{c_}, | |
1272 | @samp{V}, @samp{I}, @samp{O}, and @samp{TC}; and names prefixed with | |
1273 | @samp{B} followed by a digit. | |
1274 | @pindex termios.h | |
1275 | @end itemize | |
1276 | ||
1277 | @comment Include the section on Creature Nest Macros. | |
28f540f4 RM |
1278 | @include creature.texi |
1279 | ||
1280 | @node Roadmap to the Manual, , Using the Library, Introduction | |
1281 | @section Roadmap to the Manual | |
1282 | ||
1283 | Here is an overview of the contents of the remaining chapters of | |
1284 | this manual. | |
1285 | ||
c54e5cf7 CD |
1286 | @c The chapter overview ordering is: |
1287 | @c Error Reporting (2) | |
1288 | @c Virtual Memory Allocation and Paging (3) | |
1289 | @c Character Handling (4) | |
1290 | @c Strings and Array Utilities (5) | |
1291 | @c Character Set Handling (6) | |
1292 | @c Locales and Internationalization (7) | |
1293 | @c Searching and Sorting (9) | |
1294 | @c Pattern Matching (10) | |
1295 | @c Input/Output Overview (11) | |
1296 | @c Input/Output on Streams (12) | |
1297 | @c Low-level Input/Ooutput (13) | |
1298 | @c File System Interface (14) | |
1299 | @c Pipes and FIFOs (15) | |
1300 | @c Sockets (16) | |
1301 | @c Low-Level Terminal Interface (17) | |
1302 | @c Syslog (18) | |
1303 | @c Mathematics (19) | |
1304 | @c Aritmetic Functions (20) | |
1305 | @c Date and Time (21) | |
1306 | @c Non-Local Exist (23) | |
1307 | @c Signal Handling (24) | |
1308 | @c The Basic Program/System Interface (25) | |
1309 | @c Processes (26) | |
1310 | @c Job Control (28) | |
1311 | @c System Databases and Name Service Switch (29) | |
1312 | @c Users and Groups (30) -- References `User Database' and `Group Database' | |
1313 | @c System Management (31) | |
1314 | @c System Configuration Parameters (32) | |
1315 | @c C Language Facilities in the Library (AA) | |
1316 | @c Summary of Library Facilities (AB) | |
1317 | @c Installing (AC) | |
1318 | @c Library Maintenance (AD) | |
1319 | ||
1320 | @c The following chapters need overview text to be added: | |
1321 | @c Message Translation (8) | |
1322 | @c Resource Usage And Limitations (22) | |
1323 | @c Inter-Process Communication (27) | |
c54e5cf7 CD |
1324 | @c Debugging support (34) |
1325 | @c POSIX Threads (35) | |
1326 | @c Internal Probes (36) | |
1327 | @c Platform-specific facilities (AE) | |
1328 | @c Contributors to (AF) | |
1329 | @c Free Software Needs Free Documentation (AG) | |
1330 | @c GNU Lesser General Public License (AH) | |
1331 | @c GNU Free Documentation License (AI) | |
1332 | ||
28f540f4 | 1333 | @itemize @bullet |
2c6fe0bd | 1334 | @item |
28f540f4 RM |
1335 | @ref{Error Reporting}, describes how errors detected by the library |
1336 | are reported. | |
1337 | ||
28f540f4 | 1338 | |
2c6fe0bd | 1339 | @item |
1f77f049 | 1340 | @ref{Memory}, describes @theglibc{}'s facilities for managing and |
99a20616 UD |
1341 | using virtual and real memory, including dynamic allocation of virtual |
1342 | memory. If you do not know in advance how much memory your program | |
1343 | needs, you can allocate it dynamically instead, and manipulate it via | |
1344 | pointers. | |
28f540f4 | 1345 | |
2c6fe0bd | 1346 | @item |
28f540f4 RM |
1347 | @ref{Character Handling}, contains information about character |
1348 | classification functions (such as @code{isspace}) and functions for | |
1349 | performing case conversion. | |
1350 | ||
2c6fe0bd | 1351 | @item |
28f540f4 RM |
1352 | @ref{String and Array Utilities}, has descriptions of functions for |
1353 | manipulating strings (null-terminated character arrays) and general | |
1354 | byte arrays, including operations such as copying and comparison. | |
1355 | ||
c54e5cf7 CD |
1356 | @item |
1357 | @ref{Character Set Handling}, contains information about manipulating | |
1358 | characters and strings using character sets larger than will fit in | |
1359 | the usual @code{char} data type. | |
1360 | ||
1361 | @item | |
1362 | @ref{Locales}, describes how selecting a particular country | |
1363 | or language affects the behavior of the library. For example, the locale | |
1364 | affects collation sequences for strings and how monetary values are | |
1365 | formatted. | |
1366 | ||
1367 | @item | |
1368 | @ref{Searching and Sorting}, contains information about functions | |
1369 | for searching and sorting arrays. You can use these functions on any | |
1370 | kind of array by providing an appropriate comparison function. | |
1371 | ||
1372 | @item | |
1373 | @ref{Pattern Matching}, presents functions for matching regular expressions | |
1374 | and shell file name patterns, and for expanding words as the shell does. | |
1375 | ||
28f540f4 RM |
1376 | @item |
1377 | @ref{I/O Overview}, gives an overall look at the input and output | |
1378 | facilities in the library, and contains information about basic concepts | |
1379 | such as file names. | |
1380 | ||
1381 | @item | |
1382 | @ref{I/O on Streams}, describes I/O operations involving streams (or | |
1383 | @w{@code{FILE *}} objects). These are the normal C library functions | |
1384 | from @file{stdio.h}. | |
1385 | ||
1386 | @item | |
1387 | @ref{Low-Level I/O}, contains information about I/O operations | |
1388 | on file descriptors. File descriptors are a lower-level mechanism | |
1389 | specific to the Unix family of operating systems. | |
1390 | ||
1391 | @item | |
1392 | @ref{File System Interface}, has descriptions of operations on entire | |
1393 | files, such as functions for deleting and renaming them and for creating | |
1394 | new directories. This chapter also contains information about how you | |
1395 | can access the attributes of a file, such as its owner and file protection | |
1396 | modes. | |
1397 | ||
1398 | @item | |
1399 | @ref{Pipes and FIFOs}, contains information about simple interprocess | |
1400 | communication mechanisms. Pipes allow communication between two related | |
1401 | processes (such as between a parent and child), while FIFOs allow | |
1402 | communication between processes sharing a common file system on the same | |
1403 | machine. | |
1404 | ||
1405 | @item | |
1406 | @ref{Sockets}, describes a more complicated interprocess communication | |
1407 | mechanism that allows processes running on different machines to | |
1408 | communicate over a network. This chapter also contains information about | |
1409 | Internet host addressing and how to use the system network databases. | |
1410 | ||
1411 | @item | |
1412 | @ref{Low-Level Terminal Interface}, describes how you can change the | |
1413 | attributes of a terminal device. If you want to disable echo of | |
1414 | characters typed by the user, for example, read this chapter. | |
1415 | ||
2c6fe0bd | 1416 | @item |
28f540f4 RM |
1417 | @ref{Mathematics}, contains information about the math library |
1418 | functions. These include things like random-number generators and | |
1419 | remainder functions on integers as well as the usual trigonometric and | |
1420 | exponential functions on floating-point numbers. | |
1421 | ||
1422 | @item | |
1423 | @ref{Arithmetic,, Low-Level Arithmetic Functions}, describes functions | |
1424 | for simple arithmetic, analysis of floating-point values, and reading | |
1425 | numbers from strings. | |
1426 | ||
28f540f4 RM |
1427 | @item |
1428 | @ref{Date and Time}, describes functions for measuring both calendar time | |
1429 | and CPU time, as well as functions for setting alarms and timers. | |
1430 | ||
28f540f4 RM |
1431 | @item |
1432 | @ref{Non-Local Exits}, contains descriptions of the @code{setjmp} and | |
1433 | @code{longjmp} functions. These functions provide a facility for | |
1434 | @code{goto}-like jumps which can jump from one function to another. | |
1435 | ||
1436 | @item | |
1437 | @ref{Signal Handling}, tells you all about signals---what they are, | |
1438 | how to establish a handler that is called when a particular kind of | |
1439 | signal is delivered, and how to prevent signals from arriving during | |
1440 | critical sections of your program. | |
1441 | ||
1442 | @item | |
17c389fc | 1443 | @ref{Program Basics}, tells how your programs can access their |
28f540f4 RM |
1444 | command-line arguments and environment variables. |
1445 | ||
2c6fe0bd | 1446 | @item |
28f540f4 RM |
1447 | @ref{Processes}, contains information about how to start new processes |
1448 | and run programs. | |
1449 | ||
1450 | @item | |
1451 | @ref{Job Control}, describes functions for manipulating process groups | |
1452 | and the controlling terminal. This material is probably only of | |
1453 | interest if you are writing a shell or other program which handles job | |
1454 | control specially. | |
1455 | ||
2c6fe0bd UD |
1456 | @item |
1457 | @ref{Name Service Switch}, describes the services which are available | |
1458 | for looking up names in the system databases, how to determine which | |
1459 | service is used for which database, and how these services are | |
1460 | implemented so that contributors can design their own services. | |
1461 | ||
28f540f4 RM |
1462 | @item |
1463 | @ref{User Database}, and @ref{Group Database}, tell you how to access | |
1464 | the system user and group databases. | |
1465 | ||
1466 | @item | |
faf2289f UD |
1467 | @ref{System Management}, describes functions for controlling and getting |
1468 | information about the hardware and software configuration your program | |
1469 | is executing under. | |
28f540f4 | 1470 | |
2c6fe0bd | 1471 | @item |
28f540f4 RM |
1472 | @ref{System Configuration}, tells you how you can get information about |
1473 | various operating system limits. Most of these parameters are provided for | |
1474 | compatibility with POSIX. | |
1475 | ||
c54e5cf7 CD |
1476 | @item |
1477 | @ref{Language Features}, contains information about library support for | |
1478 | standard parts of the C language, including things like the @code{sizeof} | |
1479 | operator and the symbolic constant @code{NULL}, how to write functions | |
1480 | accepting variable numbers of arguments, and constants describing the | |
1481 | ranges and other properties of the numerical types. There is also a simple | |
1482 | debugging mechanism which allows you to put assertions in your code, and | |
1483 | have diagnostic messages printed if the tests fail. | |
1484 | ||
28f540f4 RM |
1485 | @item |
1486 | @ref{Library Summary}, gives a summary of all the functions, variables, and | |
1487 | macros in the library, with complete data types and function prototypes, | |
1488 | and says what standard or system each is derived from. | |
1489 | ||
1490 | @item | |
1f77f049 | 1491 | @ref{Installation}, explains how to build and install @theglibc{} on |
5551a7b6 AJ |
1492 | your system, and how to report any bugs you might find. |
1493 | ||
1494 | @item | |
1495 | @ref{Maintenance}, explains how to add new functions or port the | |
1496 | library to a new system. | |
28f540f4 RM |
1497 | @end itemize |
1498 | ||
1499 | If you already know the name of the facility you are interested in, you | |
1500 | can look it up in @ref{Library Summary}. This gives you a summary of | |
1501 | its syntax and a pointer to where you can find a more detailed | |
1502 | description. This appendix is particularly useful if you just want to | |
1503 | verify the order and type of arguments to a function, for example. It | |
1504 | also tells you what standard or system each function, variable, or macro | |
1505 | is derived from. |