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