|
Packit |
6c4009 |
@node Introduction, Error Reporting, Top, Top
|
|
Packit |
6c4009 |
@chapter Introduction
|
|
Packit |
6c4009 |
@c %MENU% Purpose of the GNU C Library
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The C language provides no built-in facilities for performing such
|
|
Packit |
6c4009 |
common operations as input/output, memory management, string
|
|
Packit |
6c4009 |
manipulation, and the like. Instead, these facilities are defined
|
|
Packit |
6c4009 |
in a standard @dfn{library}, which you compile and link with your
|
|
Packit |
6c4009 |
programs.
|
|
Packit |
6c4009 |
@cindex library
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@Theglibc{}, described in this document, defines all of the
|
|
Packit |
6c4009 |
library functions that are specified by the @w{ISO C} standard, as well as
|
|
Packit |
6c4009 |
additional features specific to POSIX and other derivatives of the Unix
|
|
Packit |
6c4009 |
operating system, and extensions specific to @gnusystems{}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The purpose of this manual is to tell you how to use the facilities
|
|
Packit |
6c4009 |
of @theglibc{}. We have mentioned which features belong to which
|
|
Packit |
6c4009 |
standards to help you identify things that are potentially non-portable
|
|
Packit |
6c4009 |
to other systems. But the emphasis in this manual is not on strict
|
|
Packit |
6c4009 |
portability.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* Getting Started:: What this manual is for and how to use it.
|
|
Packit |
6c4009 |
* Standards and Portability:: Standards and sources upon which the GNU
|
|
Packit |
6c4009 |
C library is based.
|
|
Packit |
6c4009 |
* Using the Library:: Some practical uses for the library.
|
|
Packit |
6c4009 |
* Roadmap to the Manual:: Overview of the remaining chapters in
|
|
Packit |
6c4009 |
this manual.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Getting Started, Standards and Portability, , Introduction
|
|
Packit |
6c4009 |
@section Getting Started
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This manual is written with the assumption that you are at least
|
|
Packit |
6c4009 |
somewhat familiar with the C programming language and basic programming
|
|
Packit |
6c4009 |
concepts. Specifically, familiarity with ISO standard C
|
|
Packit |
6c4009 |
(@pxref{ISO C}), rather than ``traditional'' pre-ISO C dialects, is
|
|
Packit |
6c4009 |
assumed.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@Theglibc{} includes several @dfn{header files}, each of which
|
|
Packit |
6c4009 |
provides definitions and declarations for a group of related facilities;
|
|
Packit |
6c4009 |
this information is used by the C compiler when processing your program.
|
|
Packit |
6c4009 |
For example, the header file @file{stdio.h} declares facilities for
|
|
Packit |
6c4009 |
performing input and output, and the header file @file{string.h}
|
|
Packit |
6c4009 |
declares string processing utilities. The organization of this manual
|
|
Packit |
6c4009 |
generally follows the same division as the header files.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If you are reading this manual for the first time, you should read all
|
|
Packit |
6c4009 |
of the introductory material and skim the remaining chapters. There are
|
|
Packit |
6c4009 |
a @emph{lot} of functions in @theglibc{} and it's not realistic to
|
|
Packit |
6c4009 |
expect that you will be able to remember exactly @emph{how} to use each
|
|
Packit |
6c4009 |
and every one of them. It's more important to become generally familiar
|
|
Packit |
6c4009 |
with the kinds of facilities that the library provides, so that when you
|
|
Packit |
6c4009 |
are writing your programs you can recognize @emph{when} to make use of
|
|
Packit |
6c4009 |
library functions, and @emph{where} in this manual you can find more
|
|
Packit |
6c4009 |
specific information about them.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Standards and Portability, Using the Library, Getting Started, Introduction
|
|
Packit |
6c4009 |
@section Standards and Portability
|
|
Packit |
6c4009 |
@cindex standards
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This section discusses the various standards and other sources that @theglibc{}
|
|
Packit |
6c4009 |
is based upon. These sources include the @w{ISO C} and
|
|
Packit |
6c4009 |
POSIX standards, and the System V and Berkeley Unix implementations.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The primary focus of this manual is to tell you how to make effective
|
|
Packit |
6c4009 |
use of the @glibcadj{} facilities. But if you are concerned about
|
|
Packit |
6c4009 |
making your programs compatible with these standards, or portable to
|
|
Packit |
6c4009 |
operating systems other than GNU, this can affect how you use the
|
|
Packit |
6c4009 |
library. This section gives you an overview of these standards, so that
|
|
Packit |
6c4009 |
you will know what they are when they are mentioned in other parts of
|
|
Packit |
6c4009 |
the manual.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@xref{Library Summary}, for an alphabetical list of the functions and
|
|
Packit |
6c4009 |
other symbols provided by the library. This list also states which
|
|
Packit |
6c4009 |
standards each function or symbol comes from.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* ISO C:: The international standard for the C
|
|
Packit |
6c4009 |
programming language.
|
|
Packit |
6c4009 |
* POSIX:: The ISO/IEC 9945 (aka IEEE 1003) standards
|
|
Packit |
6c4009 |
for operating systems.
|
|
Packit |
6c4009 |
* Berkeley Unix:: BSD and SunOS.
|
|
Packit |
6c4009 |
* SVID:: The System V Interface Description.
|
|
Packit |
6c4009 |
* XPG:: The X/Open Portability Guide.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node ISO C, POSIX, , Standards and Portability
|
|
Packit |
6c4009 |
@subsection ISO C
|
|
Packit |
6c4009 |
@cindex ISO C
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@Theglibc{} is compatible with the C standard adopted by the
|
|
Packit |
6c4009 |
American National Standards Institute (ANSI):
|
|
Packit |
6c4009 |
@cite{American National Standard X3.159-1989---``ANSI C''} and later
|
|
Packit |
6c4009 |
by the International Standardization Organization (ISO):
|
|
Packit |
6c4009 |
@cite{ISO/IEC 9899:1990, ``Programming languages---C''}.
|
|
Packit |
6c4009 |
We here refer to the standard as @w{ISO C} since this is the more
|
|
Packit |
6c4009 |
general standard in respect of ratification.
|
|
Packit |
6c4009 |
The header files and library facilities that make up @theglibc{} are
|
|
Packit |
6c4009 |
a superset of those specified by the @w{ISO C} standard.@refill
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@pindex gcc
|
|
Packit |
6c4009 |
If you are concerned about strict adherence to the @w{ISO C} standard, you
|
|
Packit |
6c4009 |
should use the @samp{-ansi} option when you compile your programs with
|
|
Packit |
6c4009 |
the GNU C compiler. This tells the compiler to define @emph{only} ISO
|
|
Packit |
6c4009 |
standard features from the library header files, unless you explicitly
|
|
Packit |
6c4009 |
ask for additional features. @xref{Feature Test Macros}, for
|
|
Packit |
6c4009 |
information on how to do this.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Being able to restrict the library to include only @w{ISO C} features is
|
|
Packit |
6c4009 |
important because @w{ISO C} puts limitations on what names can be defined
|
|
Packit |
6c4009 |
by the library implementation, and the GNU extensions don't fit these
|
|
Packit |
6c4009 |
limitations. @xref{Reserved Names}, for more information about these
|
|
Packit |
6c4009 |
restrictions.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This manual does not attempt to give you complete details on the
|
|
Packit |
6c4009 |
differences between @w{ISO C} and older dialects. It gives advice on how
|
|
Packit |
6c4009 |
to write programs to work portably under multiple C dialects, but does
|
|
Packit |
6c4009 |
not aim for completeness.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node POSIX, Berkeley Unix, ISO C, Standards and Portability
|
|
Packit |
6c4009 |
@subsection POSIX (The Portable Operating System Interface)
|
|
Packit |
6c4009 |
@cindex POSIX
|
|
Packit |
6c4009 |
@cindex POSIX.1
|
|
Packit |
6c4009 |
@cindex IEEE Std 1003.1
|
|
Packit |
6c4009 |
@cindex ISO/IEC 9945-1
|
|
Packit |
6c4009 |
@cindex POSIX.2
|
|
Packit |
6c4009 |
@cindex IEEE Std 1003.2
|
|
Packit |
6c4009 |
@cindex ISO/IEC 9945-2
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@Theglibc{} is also compatible with the ISO @dfn{POSIX} family of
|
|
Packit |
6c4009 |
standards, known more formally as the @dfn{Portable Operating System
|
|
Packit |
6c4009 |
Interface for Computer Environments} (ISO/IEC 9945). They were also
|
|
Packit |
6c4009 |
published as ANSI/IEEE Std 1003. POSIX is derived mostly from various
|
|
Packit |
6c4009 |
versions of the Unix operating system.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The library facilities specified by the POSIX standards are a superset
|
|
Packit |
6c4009 |
of those required by @w{ISO C}; POSIX specifies additional features for
|
|
Packit |
6c4009 |
@w{ISO C} functions, as well as specifying new additional functions. In
|
|
Packit |
6c4009 |
general, the additional requirements and functionality defined by the
|
|
Packit |
6c4009 |
POSIX standards are aimed at providing lower-level support for a
|
|
Packit |
6c4009 |
particular kind of operating system environment, rather than general
|
|
Packit |
6c4009 |
programming language support which can run in many diverse operating
|
|
Packit |
6c4009 |
system environments.@refill
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@Theglibc{} implements all of the functions specified in
|
|
Packit |
6c4009 |
@cite{ISO/IEC 9945-1:1996, the POSIX System Application Program
|
|
Packit |
6c4009 |
Interface}, commonly referred to as POSIX.1. The primary extensions to
|
|
Packit |
6c4009 |
the @w{ISO C} facilities specified by this standard include file system
|
|
Packit |
6c4009 |
interface primitives (@pxref{File System Interface}), device-specific
|
|
Packit |
6c4009 |
terminal control functions (@pxref{Low-Level Terminal Interface}), and
|
|
Packit |
6c4009 |
process control functions (@pxref{Processes}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Some facilities from @cite{ISO/IEC 9945-2:1993, the POSIX Shell and
|
|
Packit |
6c4009 |
Utilities standard} (POSIX.2) are also implemented in @theglibc{}.
|
|
Packit |
6c4009 |
These include utilities for dealing with regular expressions and other
|
|
Packit |
6c4009 |
pattern matching facilities (@pxref{Pattern Matching}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* POSIX Safety Concepts:: Safety concepts from POSIX.
|
|
Packit |
6c4009 |
* Unsafe Features:: Features that make functions unsafe.
|
|
Packit |
6c4009 |
* Conditionally Safe Features:: Features that make functions unsafe
|
|
Packit |
6c4009 |
in the absence of workarounds.
|
|
Packit |
6c4009 |
* Other Safety Remarks:: Additional safety features and remarks.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@comment Roland sez:
|
|
Packit |
6c4009 |
@comment The GNU C library as it stands conforms to 1003.2 draft 11, which
|
|
Packit |
6c4009 |
@comment specifies:
|
|
Packit |
6c4009 |
@comment
|
|
Packit |
6c4009 |
@comment Several new macros in <limits.h>.
|
|
Packit |
6c4009 |
@comment popen, pclose
|
|
Packit |
6c4009 |
@comment <regex.h> (which is not yet fully implemented--wait on this)
|
|
Packit |
6c4009 |
@comment fnmatch
|
|
Packit |
6c4009 |
@comment getopt
|
|
Packit |
6c4009 |
@comment <glob.h>
|
|
Packit |
6c4009 |
@comment <wordexp.h> (not yet implemented)
|
|
Packit |
6c4009 |
@comment confstr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node POSIX Safety Concepts, Unsafe Features, , POSIX
|
|
Packit |
6c4009 |
@subsubsection POSIX Safety Concepts
|
|
Packit |
6c4009 |
@cindex POSIX Safety Concepts
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This manual documents various safety properties of @glibcadj{}
|
|
Packit |
6c4009 |
functions, in lines that follow their prototypes and look like:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@sampsafety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The properties are assessed according to the criteria set forth in the
|
|
Packit |
6c4009 |
POSIX standard for such safety contexts as Thread-, Async-Signal- and
|
|
Packit |
6c4009 |
Async-Cancel- -Safety. Intuitive definitions of these properties,
|
|
Packit |
6c4009 |
attempting to capture the meaning of the standard definitions, follow.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@cindex MT-Safe
|
|
Packit |
6c4009 |
@cindex Thread-Safe
|
|
Packit |
6c4009 |
@code{MT-Safe} or Thread-Safe functions are safe to call in the presence
|
|
Packit |
6c4009 |
of other threads. MT, in MT-Safe, stands for Multi Thread.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Being MT-Safe does not imply a function is atomic, nor that it uses any
|
|
Packit |
6c4009 |
of the memory synchronization mechanisms POSIX exposes to users. It is
|
|
Packit |
6c4009 |
even possible that calling MT-Safe functions in sequence does not yield
|
|
Packit |
6c4009 |
an MT-Safe combination. For example, having a thread call two MT-Safe
|
|
Packit |
6c4009 |
functions one right after the other does not guarantee behavior
|
|
Packit |
6c4009 |
equivalent to atomic execution of a combination of both functions, since
|
|
Packit |
6c4009 |
concurrent calls in other threads may interfere in a destructive way.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Whole-program optimizations that could inline functions across library
|
|
Packit |
6c4009 |
interfaces may expose unsafe reordering, and so performing inlining
|
|
Packit |
6c4009 |
across the @glibcadj{} interface is not recommended. The documented
|
|
Packit |
6c4009 |
MT-Safety status is not guaranteed under whole-program optimization.
|
|
Packit |
6c4009 |
However, functions defined in user-visible headers are designed to be
|
|
Packit |
6c4009 |
safe for inlining.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@cindex AS-Safe
|
|
Packit |
6c4009 |
@cindex Async-Signal-Safe
|
|
Packit |
6c4009 |
@code{AS-Safe} or Async-Signal-Safe functions are safe to call from
|
|
Packit |
6c4009 |
asynchronous signal handlers. AS, in AS-Safe, stands for Asynchronous
|
|
Packit |
6c4009 |
Signal.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Many functions that are AS-Safe may set @code{errno}, or modify the
|
|
Packit |
6c4009 |
floating-point environment, because their doing so does not make them
|
|
Packit |
6c4009 |
unsuitable for use in signal handlers. However, programs could
|
|
Packit |
6c4009 |
misbehave should asynchronous signal handlers modify this thread-local
|
|
Packit |
6c4009 |
state, and the signal handling machinery cannot be counted on to
|
|
Packit |
6c4009 |
preserve it. Therefore, signal handlers that call functions that may
|
|
Packit |
6c4009 |
set @code{errno} or modify the floating-point environment @emph{must}
|
|
Packit |
6c4009 |
save their original values, and restore them before returning.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@cindex AC-Safe
|
|
Packit |
6c4009 |
@cindex Async-Cancel-Safe
|
|
Packit |
6c4009 |
@code{AC-Safe} or Async-Cancel-Safe functions are safe to call when
|
|
Packit |
6c4009 |
asynchronous cancellation is enabled. AC in AC-Safe stands for
|
|
Packit |
6c4009 |
Asynchronous Cancellation.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The POSIX standard defines only three functions to be AC-Safe, namely
|
|
Packit |
6c4009 |
@code{pthread_cancel}, @code{pthread_setcancelstate}, and
|
|
Packit |
6c4009 |
@code{pthread_setcanceltype}. At present @theglibc{} provides no
|
|
Packit |
6c4009 |
guarantees beyond these three functions, but does document which
|
|
Packit |
6c4009 |
functions are presently AC-Safe. This documentation is provided for use
|
|
Packit |
6c4009 |
by @theglibc{} developers.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Just like signal handlers, cancellation cleanup routines must configure
|
|
Packit |
6c4009 |
the floating point environment they require. The routines cannot assume
|
|
Packit |
6c4009 |
a floating point environment, particularly when asynchronous
|
|
Packit |
6c4009 |
cancellation is enabled. If the configuration of the floating point
|
|
Packit |
6c4009 |
environment cannot be performed atomically then it is also possible that
|
|
Packit |
6c4009 |
the environment encountered is internally inconsistent.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@cindex MT-Unsafe
|
|
Packit |
6c4009 |
@cindex Thread-Unsafe
|
|
Packit |
6c4009 |
@cindex AS-Unsafe
|
|
Packit |
6c4009 |
@cindex Async-Signal-Unsafe
|
|
Packit |
6c4009 |
@cindex AC-Unsafe
|
|
Packit |
6c4009 |
@cindex Async-Cancel-Unsafe
|
|
Packit |
6c4009 |
@code{MT-Unsafe}, @code{AS-Unsafe}, @code{AC-Unsafe} functions are not
|
|
Packit |
6c4009 |
safe to call within the safety contexts described above. Calling them
|
|
Packit |
6c4009 |
within such contexts invokes undefined behavior.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions not explicitly documented as safe in a safety context should
|
|
Packit |
6c4009 |
be regarded as Unsafe.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@cindex Preliminary
|
|
Packit |
6c4009 |
@code{Preliminary} safety properties are documented, indicating these
|
|
Packit |
6c4009 |
properties may @emph{not} be counted on in future releases of
|
|
Packit |
6c4009 |
@theglibc{}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Such preliminary properties are the result of an assessment of the
|
|
Packit |
6c4009 |
properties of our current implementation, rather than of what is
|
|
Packit |
6c4009 |
mandated and permitted by current and future standards.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Although we strive to abide by the standards, in some cases our
|
|
Packit |
6c4009 |
implementation is safe even when the standard does not demand safety,
|
|
Packit |
6c4009 |
and in other cases our implementation does not meet the standard safety
|
|
Packit |
6c4009 |
requirements. The latter are most likely bugs; the former, when marked
|
|
Packit |
6c4009 |
as @code{Preliminary}, should not be counted on: future standards may
|
|
Packit |
6c4009 |
require changes that are not compatible with the additional safety
|
|
Packit |
6c4009 |
properties afforded by the current implementation.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Furthermore, the POSIX standard does not offer a detailed definition of
|
|
Packit |
6c4009 |
safety. We assume that, by ``safe to call'', POSIX means that, as long
|
|
Packit |
6c4009 |
as the program does not invoke undefined behavior, the ``safe to call''
|
|
Packit |
6c4009 |
function behaves as specified, and does not cause other functions to
|
|
Packit |
6c4009 |
deviate from their specified behavior. We have chosen to use its loose
|
|
Packit |
6c4009 |
definitions of safety, not because they are the best definitions to use,
|
|
Packit |
6c4009 |
but because choosing them harmonizes this manual with POSIX.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Please keep in mind that these are preliminary definitions and
|
|
Packit |
6c4009 |
annotations, and certain aspects of the definitions are still under
|
|
Packit |
6c4009 |
discussion and might be subject to clarification or change.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Over time, we envision evolving the preliminary safety notes into stable
|
|
Packit |
6c4009 |
commitments, as stable as those of our interfaces. As we do, we will
|
|
Packit |
6c4009 |
remove the @code{Preliminary} keyword from safety notes. As long as the
|
|
Packit |
6c4009 |
keyword remains, however, they are not to be regarded as a promise of
|
|
Packit |
6c4009 |
future behavior.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Other keywords that appear in safety notes are defined in subsequent
|
|
Packit |
6c4009 |
sections.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Unsafe Features, Conditionally Safe Features, POSIX Safety Concepts, POSIX
|
|
Packit |
6c4009 |
@subsubsection Unsafe Features
|
|
Packit |
6c4009 |
@cindex Unsafe Features
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions that are unsafe to call in certain contexts are annotated with
|
|
Packit |
6c4009 |
keywords that document their features that make them unsafe to call.
|
|
Packit |
6c4009 |
AS-Unsafe features in this section indicate the functions are never safe
|
|
Packit |
6c4009 |
to call when asynchronous signals are enabled. AC-Unsafe features
|
|
Packit |
6c4009 |
indicate they are never safe to call when asynchronous cancellation is
|
|
Packit |
6c4009 |
enabled. There are no MT-Unsafe marks in this section.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{lock}
|
|
Packit |
6c4009 |
@cindex lock
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{lock} as an AS-Unsafe feature may be
|
|
Packit |
6c4009 |
interrupted by a signal while holding a non-recursive lock. If the
|
|
Packit |
6c4009 |
signal handler calls another such function that takes the same lock, the
|
|
Packit |
6c4009 |
result is a deadlock.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions annotated with @code{lock} as an AC-Unsafe feature may, if
|
|
Packit |
6c4009 |
cancelled asynchronously, fail to release a lock that would have been
|
|
Packit |
6c4009 |
released if their execution had not been interrupted by asynchronous
|
|
Packit |
6c4009 |
thread cancellation. Once a lock is left taken, attempts to take that
|
|
Packit |
6c4009 |
lock will block indefinitely.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{corrupt}
|
|
Packit |
6c4009 |
@cindex corrupt
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{corrupt} as an AS-Unsafe feature may corrupt
|
|
Packit |
6c4009 |
data structures and misbehave when they interrupt, or are interrupted
|
|
Packit |
6c4009 |
by, another such function. Unlike functions marked with @code{lock},
|
|
Packit |
6c4009 |
these take recursive locks to avoid MT-Safety problems, but this is not
|
|
Packit |
6c4009 |
enough to stop a signal handler from observing a partially-updated data
|
|
Packit |
6c4009 |
structure. Further corruption may arise from the interrupted function's
|
|
Packit |
6c4009 |
failure to notice updates made by signal handlers.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{corrupt} as an AC-Unsafe feature may leave
|
|
Packit |
6c4009 |
data structures in a corrupt, partially updated state. Subsequent uses
|
|
Packit |
6c4009 |
of the data structure may misbehave.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c A special case, probably not worth documenting separately, involves
|
|
Packit |
6c4009 |
@c reallocing, or even freeing pointers. Any case involving free could
|
|
Packit |
6c4009 |
@c be easily turned into an ac-safe leak by resetting the pointer before
|
|
Packit |
6c4009 |
@c releasing it; I don't think we have any case that calls for this sort
|
|
Packit |
6c4009 |
@c of fixing. Fixing the realloc cases would require a new interface:
|
|
Packit |
6c4009 |
@c instead of @code{ptr=realloc(ptr,size)} we'd have to introduce
|
|
Packit |
6c4009 |
@c @code{acsafe_realloc(&ptr,size)} that would modify ptr before
|
|
Packit |
6c4009 |
@c releasing the old memory. The ac-unsafe realloc could be implemented
|
|
Packit |
6c4009 |
@c in terms of an internal interface with this semantics (say
|
|
Packit |
6c4009 |
@c __acsafe_realloc), but since realloc can be overridden, the function
|
|
Packit |
6c4009 |
@c we call to implement realloc should not be this internal interface,
|
|
Packit |
6c4009 |
@c but another internal interface that calls __acsafe_realloc if realloc
|
|
Packit |
6c4009 |
@c was not overridden, and calls the overridden realloc with async
|
|
Packit |
6c4009 |
@c cancel disabled. --lxoliva
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{heap}
|
|
Packit |
6c4009 |
@cindex heap
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{heap} may call heap memory management
|
|
Packit |
6c4009 |
functions from the @code{malloc}/@code{free} family of functions and are
|
|
Packit |
6c4009 |
only as safe as those functions. This note is thus equivalent to:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@sampsafety{@asunsafe{@asulock{}}@acunsafe{@aculock{} @acsfd{} @acsmem{}}}
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c Check for cases that should have used plugin instead of or in
|
|
Packit |
6c4009 |
@c addition to this. Then, after rechecking gettext, adjust i18n if
|
|
Packit |
6c4009 |
@c needed.
|
|
Packit |
6c4009 |
@item @code{dlopen}
|
|
Packit |
6c4009 |
@cindex dlopen
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{dlopen} use the dynamic loader to load
|
|
Packit |
6c4009 |
shared libraries into the current execution image. This involves
|
|
Packit |
6c4009 |
opening files, mapping them into memory, allocating additional memory,
|
|
Packit |
6c4009 |
resolving symbols, applying relocations and more, all of this while
|
|
Packit |
6c4009 |
holding internal dynamic loader locks.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The locks are enough for these functions to be AS- and AC-Unsafe, but
|
|
Packit |
6c4009 |
other issues may arise. At present this is a placeholder for all
|
|
Packit |
6c4009 |
potential safety issues raised by @code{dlopen}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c dlopen runs init and fini sections of the module; does this mean
|
|
Packit |
6c4009 |
@c dlopen always implies plugin?
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{plugin}
|
|
Packit |
6c4009 |
@cindex plugin
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions annotated with @code{plugin} may run code from plugins that
|
|
Packit |
6c4009 |
may be external to @theglibc{}. Such plugin functions are assumed to be
|
|
Packit |
6c4009 |
MT-Safe, AS-Unsafe and AC-Unsafe. Examples of such plugins are stack
|
|
Packit |
6c4009 |
@cindex NSS
|
|
Packit |
6c4009 |
unwinding libraries, name service switch (NSS) and character set
|
|
Packit |
6c4009 |
@cindex iconv
|
|
Packit |
6c4009 |
conversion (iconv) back-ends.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Although the plugins mentioned as examples are all brought in by means
|
|
Packit |
6c4009 |
of dlopen, the @code{plugin} keyword does not imply any direct
|
|
Packit |
6c4009 |
involvement of the dynamic loader or the @code{libdl} interfaces, those
|
|
Packit |
6c4009 |
are covered by @code{dlopen}. For example, if one function loads a
|
|
Packit |
6c4009 |
module and finds the addresses of some of its functions, while another
|
|
Packit |
6c4009 |
just calls those already-resolved functions, the former will be marked
|
|
Packit |
6c4009 |
with @code{dlopen}, whereas the latter will get the @code{plugin}. When
|
|
Packit |
6c4009 |
a single function takes all of these actions, then it gets both marks.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{i18n}
|
|
Packit |
6c4009 |
@cindex i18n
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{i18n} may call internationalization
|
|
Packit |
6c4009 |
functions of the @code{gettext} family and will be only as safe as those
|
|
Packit |
6c4009 |
functions. This note is thus equivalent to:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@sampsafety{@mtsafe{@mtsenv{}}@asunsafe{@asucorrupt{} @ascuheap{} @ascudlopen{}}@acunsafe{@acucorrupt{}}}
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{timer}
|
|
Packit |
6c4009 |
@cindex timer
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{timer} use the @code{alarm} function or
|
|
Packit |
6c4009 |
similar to set a time-out for a system call or a long-running operation.
|
|
Packit |
6c4009 |
In a multi-threaded program, there is a risk that the time-out signal
|
|
Packit |
6c4009 |
will be delivered to a different thread, thus failing to interrupt the
|
|
Packit |
6c4009 |
intended thread. Besides being MT-Unsafe, such functions are always
|
|
Packit |
6c4009 |
AS-Unsafe, because calling them in signal handlers may interfere with
|
|
Packit |
6c4009 |
timers set in the interrupted code, and AC-Unsafe, because there is no
|
|
Packit |
6c4009 |
safe way to guarantee an earlier timer will be reset in case of
|
|
Packit |
6c4009 |
asynchronous cancellation.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Conditionally Safe Features, Other Safety Remarks, Unsafe Features, POSIX
|
|
Packit |
6c4009 |
@subsubsection Conditionally Safe Features
|
|
Packit |
6c4009 |
@cindex Conditionally Safe Features
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
For some features that make functions unsafe to call in certain
|
|
Packit |
6c4009 |
contexts, there are known ways to avoid the safety problem other than
|
|
Packit |
6c4009 |
refraining from calling the function altogether. The keywords that
|
|
Packit |
6c4009 |
follow refer to such features, and each of their definitions indicate
|
|
Packit |
6c4009 |
how the whole program needs to be constrained in order to remove the
|
|
Packit |
6c4009 |
safety problem indicated by the keyword. Only when all the reasons that
|
|
Packit |
6c4009 |
make a function unsafe are observed and addressed, by applying the
|
|
Packit |
6c4009 |
documented constraints, does the function become safe to call in a
|
|
Packit |
6c4009 |
context.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{init}
|
|
Packit |
6c4009 |
@cindex init
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{init} as an MT-Unsafe feature perform
|
|
Packit |
6c4009 |
MT-Unsafe initialization when they are first called.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Calling such a function at least once in single-threaded mode removes
|
|
Packit |
6c4009 |
this specific cause for the function to be regarded as MT-Unsafe. If no
|
|
Packit |
6c4009 |
other cause for that remains, the function can then be safely called
|
|
Packit |
6c4009 |
after other threads are started.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{init} as an AS- or AC-Unsafe feature use the
|
|
Packit |
6c4009 |
internal @code{libc_once} machinery or similar to initialize internal
|
|
Packit |
6c4009 |
data structures.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If a signal handler interrupts such an initializer, and calls any
|
|
Packit |
6c4009 |
function that also performs @code{libc_once} initialization, it will
|
|
Packit |
6c4009 |
deadlock if the thread library has been loaded.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Furthermore, if an initializer is partially complete before it is
|
|
Packit |
6c4009 |
canceled or interrupted by a signal whose handler requires the same
|
|
Packit |
6c4009 |
initialization, some or all of the initialization may be performed more
|
|
Packit |
6c4009 |
than once, leaking resources or even resulting in corrupt internal data.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Applications that need to call functions marked with @code{init} as an
|
|
Packit |
6c4009 |
AS- or AC-Unsafe feature should ensure the initialization is performed
|
|
Packit |
6c4009 |
before configuring signal handlers or enabling cancellation, so that the
|
|
Packit |
6c4009 |
AS- and AC-Safety issues related with @code{libc_once} do not arise.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c We may have to extend the annotations to cover conditions in which
|
|
Packit |
6c4009 |
@c initialization may or may not occur, since an initial call in a safe
|
|
Packit |
6c4009 |
@c context is no use if the initialization doesn't take place at that
|
|
Packit |
6c4009 |
@c time: it doesn't remove the risk for later calls.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{race}
|
|
Packit |
6c4009 |
@cindex race
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions annotated with @code{race} as an MT-Safety issue operate on
|
|
Packit |
6c4009 |
objects in ways that may cause data races or similar forms of
|
|
Packit |
6c4009 |
destructive interference out of concurrent execution. In some cases,
|
|
Packit |
6c4009 |
the objects are passed to the functions by users; in others, they are
|
|
Packit |
6c4009 |
used by the functions to return values to users; in others, they are not
|
|
Packit |
6c4009 |
even exposed to users.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
We consider access to objects passed as (indirect) arguments to
|
|
Packit |
6c4009 |
functions to be data race free. The assurance of data race free objects
|
|
Packit |
6c4009 |
is the caller's responsibility. We will not mark a function as
|
|
Packit |
6c4009 |
MT-Unsafe or AS-Unsafe if it misbehaves when users fail to take the
|
|
Packit |
6c4009 |
measures required by POSIX to avoid data races when dealing with such
|
|
Packit |
6c4009 |
objects. As a general rule, if a function is documented as reading from
|
|
Packit |
6c4009 |
an object passed (by reference) to it, or modifying it, users ought to
|
|
Packit |
6c4009 |
use memory synchronization primitives to avoid data races just as they
|
|
Packit |
6c4009 |
would should they perform the accesses themselves rather than by calling
|
|
Packit |
6c4009 |
the library function. @code{FILE} streams are the exception to the
|
|
Packit |
6c4009 |
general rule, in that POSIX mandates the library to guard against data
|
|
Packit |
6c4009 |
races in many functions that manipulate objects of this specific opaque
|
|
Packit |
6c4009 |
type. We regard this as a convenience provided to users, rather than as
|
|
Packit |
6c4009 |
a general requirement whose expectations should extend to other types.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In order to remind users that guarding certain arguments is their
|
|
Packit |
6c4009 |
responsibility, we will annotate functions that take objects of certain
|
|
Packit |
6c4009 |
types as arguments. We draw the line for objects passed by users as
|
|
Packit |
6c4009 |
follows: objects whose types are exposed to users, and that users are
|
|
Packit |
6c4009 |
expected to access directly, such as memory buffers, strings, and
|
|
Packit |
6c4009 |
various user-visible @code{struct} types, do @emph{not} give reason for
|
|
Packit |
6c4009 |
functions to be annotated with @code{race}. It would be noisy and
|
|
Packit |
6c4009 |
redundant with the general requirement, and not many would be surprised
|
|
Packit |
6c4009 |
by the library's lack of internal guards when accessing objects that can
|
|
Packit |
6c4009 |
be accessed directly by users.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
As for objects that are opaque or opaque-like, in that they are to be
|
|
Packit |
6c4009 |
manipulated only by passing them to library functions (e.g.,
|
|
Packit |
6c4009 |
@code{FILE}, @code{DIR}, @code{obstack}, @code{iconv_t}), there might be
|
|
Packit |
6c4009 |
additional expectations as to internal coordination of access by the
|
|
Packit |
6c4009 |
library. We will annotate, with @code{race} followed by a colon and the
|
|
Packit |
6c4009 |
argument name, functions that take such objects but that do not take
|
|
Packit |
6c4009 |
care of synchronizing access to them by default. For example,
|
|
Packit |
6c4009 |
@code{FILE} stream @code{unlocked} functions will be annotated, but
|
|
Packit |
6c4009 |
those that perform implicit locking on @code{FILE} streams by default
|
|
Packit |
6c4009 |
will not, even though the implicit locking may be disabled on a
|
|
Packit |
6c4009 |
per-stream basis.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In either case, we will not regard as MT-Unsafe functions that may
|
|
Packit |
6c4009 |
access user-supplied objects in unsafe ways should users fail to ensure
|
|
Packit |
6c4009 |
the accesses are well defined. The notion prevails that users are
|
|
Packit |
6c4009 |
expected to safeguard against data races any user-supplied objects that
|
|
Packit |
6c4009 |
the library accesses on their behalf.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c The above describes @mtsrace; @mtasurace is described below.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This user responsibility does not apply, however, to objects controlled
|
|
Packit |
6c4009 |
by the library itself, such as internal objects and static buffers used
|
|
Packit |
6c4009 |
to return values from certain calls. When the library doesn't guard
|
|
Packit |
6c4009 |
them against concurrent uses, these cases are regarded as MT-Unsafe and
|
|
Packit |
6c4009 |
AS-Unsafe (although the @code{race} mark under AS-Unsafe will be omitted
|
|
Packit |
6c4009 |
as redundant with the one under MT-Unsafe). As in the case of
|
|
Packit |
6c4009 |
user-exposed objects, the mark may be followed by a colon and an
|
|
Packit |
6c4009 |
identifier. The identifier groups all functions that operate on a
|
|
Packit |
6c4009 |
certain unguarded object; users may avoid the MT-Safety issues related
|
|
Packit |
6c4009 |
with unguarded concurrent access to such internal objects by creating a
|
|
Packit |
6c4009 |
non-recursive mutex related with the identifier, and always holding the
|
|
Packit |
6c4009 |
mutex when calling any function marked as racy on that identifier, as
|
|
Packit |
6c4009 |
they would have to should the identifier be an object under user
|
|
Packit |
6c4009 |
control. The non-recursive mutex avoids the MT-Safety issue, but it
|
|
Packit |
6c4009 |
trades one AS-Safety issue for another, so use in asynchronous signals
|
|
Packit |
6c4009 |
remains undefined.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
When the identifier relates to a static buffer used to hold return
|
|
Packit |
6c4009 |
values, the mutex must be held for as long as the buffer remains in use
|
|
Packit |
6c4009 |
by the caller. Many functions that return pointers to static buffers
|
|
Packit |
6c4009 |
offer reentrant variants that store return values in caller-supplied
|
|
Packit |
6c4009 |
buffers instead. In some cases, such as @code{tmpname}, the variant is
|
|
Packit |
6c4009 |
chosen not by calling an alternate entry point, but by passing a
|
|
Packit |
6c4009 |
non-@code{NULL} pointer to the buffer in which the returned values are
|
|
Packit |
6c4009 |
to be stored. These variants are generally preferable in multi-threaded
|
|
Packit |
6c4009 |
programs, although some of them are not MT-Safe because of other
|
|
Packit |
6c4009 |
internal buffers, also documented with @code{race} notes.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{const}
|
|
Packit |
6c4009 |
@cindex const
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{const} as an MT-Safety issue non-atomically
|
|
Packit |
6c4009 |
modify internal objects that are better regarded as constant, because a
|
|
Packit |
6c4009 |
substantial portion of @theglibc{} accesses them without
|
|
Packit |
6c4009 |
synchronization. Unlike @code{race}, that causes both readers and
|
|
Packit |
6c4009 |
writers of internal objects to be regarded as MT-Unsafe and AS-Unsafe,
|
|
Packit |
6c4009 |
this mark is applied to writers only. Writers remain equally MT- and
|
|
Packit |
6c4009 |
AS-Unsafe to call, but the then-mandatory constness of objects they
|
|
Packit |
6c4009 |
modify enables readers to be regarded as MT-Safe and AS-Safe (as long as
|
|
Packit |
6c4009 |
no other reasons for them to be unsafe remain), since the lack of
|
|
Packit |
6c4009 |
synchronization is not a problem when the objects are effectively
|
|
Packit |
6c4009 |
constant.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The identifier that follows the @code{const} mark will appear by itself
|
|
Packit |
6c4009 |
as a safety note in readers. Programs that wish to work around this
|
|
Packit |
6c4009 |
safety issue, so as to call writers, may use a non-recursve
|
|
Packit |
6c4009 |
@code{rwlock} associated with the identifier, and guard @emph{all} calls
|
|
Packit |
6c4009 |
to functions marked with @code{const} followed by the identifier with a
|
|
Packit |
6c4009 |
write lock, and @emph{all} calls to functions marked with the identifier
|
|
Packit |
6c4009 |
by itself with a read lock. The non-recursive locking removes the
|
|
Packit |
6c4009 |
MT-Safety problem, but it trades one AS-Safety problem for another, so
|
|
Packit |
6c4009 |
use in asynchronous signals remains undefined.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c But what if, instead of marking modifiers with const:id and readers
|
|
Packit |
6c4009 |
@c with just id, we marked writers with race:id and readers with ro:id?
|
|
Packit |
6c4009 |
@c Instead of having to define each instance of “id”, we'd have a
|
|
Packit |
6c4009 |
@c general pattern governing all such “id”s, wherein race:id would
|
|
Packit |
6c4009 |
@c suggest the need for an exclusive/write lock to make the function
|
|
Packit |
6c4009 |
@c safe, whereas ro:id would indicate “id” is expected to be read-only,
|
|
Packit |
6c4009 |
@c but if any modifiers are called (while holding an exclusive lock),
|
|
Packit |
6c4009 |
@c then ro:id-marked functions ought to be guarded with a read lock for
|
|
Packit |
6c4009 |
@c safe operation. ro:env or ro:locale, for example, seems to convey
|
|
Packit |
6c4009 |
@c more clearly the expectations and the meaning, than just env or
|
|
Packit |
6c4009 |
@c locale.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{sig}
|
|
Packit |
6c4009 |
@cindex sig
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{sig} as a MT-Safety issue (that implies an
|
|
Packit |
6c4009 |
identical AS-Safety issue, omitted for brevity) may temporarily install
|
|
Packit |
6c4009 |
a signal handler for internal purposes, which may interfere with other
|
|
Packit |
6c4009 |
uses of the signal, identified after a colon.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This safety problem can be worked around by ensuring that no other uses
|
|
Packit |
6c4009 |
of the signal will take place for the duration of the call. Holding a
|
|
Packit |
6c4009 |
non-recursive mutex while calling all functions that use the same
|
|
Packit |
6c4009 |
temporary signal; blocking that signal before the call and resetting its
|
|
Packit |
6c4009 |
handler afterwards is recommended.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
There is no safe way to guarantee the original signal handler is
|
|
Packit |
6c4009 |
restored in case of asynchronous cancellation, therefore so-marked
|
|
Packit |
6c4009 |
functions are also AC-Unsafe.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c fixme: at least deferred cancellation should get it right, and would
|
|
Packit |
6c4009 |
@c obviate the restoring bit below, and the qualifier above.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Besides the measures recommended to work around the MT- and AS-Safety
|
|
Packit |
6c4009 |
problem, in order to avert the cancellation problem, disabling
|
|
Packit |
6c4009 |
asynchronous cancellation @emph{and} installing a cleanup handler to
|
|
Packit |
6c4009 |
restore the signal to the desired state and to release the mutex are
|
|
Packit |
6c4009 |
recommended.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{term}
|
|
Packit |
6c4009 |
@cindex term
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{term} as an MT-Safety issue may change the
|
|
Packit |
6c4009 |
terminal settings in the recommended way, namely: call @code{tcgetattr},
|
|
Packit |
6c4009 |
modify some flags, and then call @code{tcsetattr}; this creates a window
|
|
Packit |
6c4009 |
in which changes made by other threads are lost. Thus, functions marked
|
|
Packit |
6c4009 |
with @code{term} are MT-Unsafe. The same window enables changes made by
|
|
Packit |
6c4009 |
asynchronous signals to be lost. These functions are also AS-Unsafe,
|
|
Packit |
6c4009 |
but the corresponding mark is omitted as redundant.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
It is thus advisable for applications using the terminal to avoid
|
|
Packit |
6c4009 |
concurrent and reentrant interactions with it, by not using it in signal
|
|
Packit |
6c4009 |
handlers or blocking signals that might use it, and holding a lock while
|
|
Packit |
6c4009 |
calling these functions and interacting with the terminal. This lock
|
|
Packit |
6c4009 |
should also be used for mutual exclusion with functions marked with
|
|
Packit |
6c4009 |
@code{@mtasurace{:tcattr(fd)}}, where @var{fd} is a file descriptor for
|
|
Packit |
6c4009 |
the controlling terminal. The caller may use a single mutex for
|
|
Packit |
6c4009 |
simplicity, or use one mutex per terminal, even if referenced by
|
|
Packit |
6c4009 |
different file descriptors.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{term} as an AC-Safety issue are supposed to
|
|
Packit |
6c4009 |
restore terminal settings to their original state, after temporarily
|
|
Packit |
6c4009 |
changing them, but they may fail to do so if cancelled.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c fixme: at least deferred cancellation should get it right, and would
|
|
Packit |
6c4009 |
@c obviate the restoring bit below, and the qualifier above.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Besides the measures recommended to work around the MT- and AS-Safety
|
|
Packit |
6c4009 |
problem, in order to avert the cancellation problem, disabling
|
|
Packit |
6c4009 |
asynchronous cancellation @emph{and} installing a cleanup handler to
|
|
Packit |
6c4009 |
restore the terminal settings to the original state and to release the
|
|
Packit |
6c4009 |
mutex are recommended.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Other Safety Remarks, , Conditionally Safe Features, POSIX
|
|
Packit |
6c4009 |
@subsubsection Other Safety Remarks
|
|
Packit |
6c4009 |
@cindex Other Safety Remarks
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Additional keywords may be attached to functions, indicating features
|
|
Packit |
6c4009 |
that do not make a function unsafe to call, but that may need to be
|
|
Packit |
6c4009 |
taken into account in certain classes of programs:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{locale}
|
|
Packit |
6c4009 |
@cindex locale
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions annotated with @code{locale} as an MT-Safety issue read from
|
|
Packit |
6c4009 |
the locale object without any form of synchronization. Functions
|
|
Packit |
6c4009 |
annotated with @code{locale} called concurrently with locale changes may
|
|
Packit |
6c4009 |
behave in ways that do not correspond to any of the locales active
|
|
Packit |
6c4009 |
during their execution, but an unpredictable mix thereof.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
We do not mark these functions as MT- or AS-Unsafe, however, because
|
|
Packit |
6c4009 |
functions that modify the locale object are marked with
|
|
Packit |
6c4009 |
@code{const:locale} and regarded as unsafe. Being unsafe, the latter
|
|
Packit |
6c4009 |
are not to be called when multiple threads are running or asynchronous
|
|
Packit |
6c4009 |
signals are enabled, and so the locale can be considered effectively
|
|
Packit |
6c4009 |
constant in these contexts, which makes the former safe.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c Should the locking strategy suggested under @code{const} be used,
|
|
Packit |
6c4009 |
@c failure to guard locale uses is not as fatal as data races in
|
|
Packit |
6c4009 |
@c general: unguarded uses will @emph{not} follow dangling pointers or
|
|
Packit |
6c4009 |
@c access uninitialized, unmapped or recycled memory. Each access will
|
|
Packit |
6c4009 |
@c read from a consistent locale object that is or was active at some
|
|
Packit |
6c4009 |
@c point during its execution. Without synchronization, however, it
|
|
Packit |
6c4009 |
@c cannot even be assumed that, after a change in locale, earlier
|
|
Packit |
6c4009 |
@c locales will no longer be used, even after the newly-chosen one is
|
|
Packit |
6c4009 |
@c used in the thread. Nevertheless, even though unguarded reads from
|
|
Packit |
6c4009 |
@c the locale will not violate type safety, functions that access the
|
|
Packit |
6c4009 |
@c locale multiple times may invoke all sorts of undefined behavior
|
|
Packit |
6c4009 |
@c because of the unexpected locale changes.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{env}
|
|
Packit |
6c4009 |
@cindex env
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{env} as an MT-Safety issue access the
|
|
Packit |
6c4009 |
environment with @code{getenv} or similar, without any guards to ensure
|
|
Packit |
6c4009 |
safety in the presence of concurrent modifications.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
We do not mark these functions as MT- or AS-Unsafe, however, because
|
|
Packit |
6c4009 |
functions that modify the environment are all marked with
|
|
Packit |
6c4009 |
@code{const:env} and regarded as unsafe. Being unsafe, the latter are
|
|
Packit |
6c4009 |
not to be called when multiple threads are running or asynchronous
|
|
Packit |
6c4009 |
signals are enabled, and so the environment can be considered
|
|
Packit |
6c4009 |
effectively constant in these contexts, which makes the former safe.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{hostid}
|
|
Packit |
6c4009 |
@cindex hostid
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The function marked with @code{hostid} as an MT-Safety issue reads from
|
|
Packit |
6c4009 |
the system-wide data structures that hold the ``host ID'' of the
|
|
Packit |
6c4009 |
machine. These data structures cannot generally be modified atomically.
|
|
Packit |
6c4009 |
Since it is expected that the ``host ID'' will not normally change, the
|
|
Packit |
6c4009 |
function that reads from it (@code{gethostid}) is regarded as safe,
|
|
Packit |
6c4009 |
whereas the function that modifies it (@code{sethostid}) is marked with
|
|
Packit |
6c4009 |
@code{@mtasuconst{:@mtshostid{}}}, indicating it may require special
|
|
Packit |
6c4009 |
care if it is to be called. In this specific case, the special care
|
|
Packit |
6c4009 |
amounts to system-wide (not merely intra-process) coordination.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{sigintr}
|
|
Packit |
6c4009 |
@cindex sigintr
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{sigintr} as an MT-Safety issue access the
|
|
Packit |
6c4009 |
@code{_sigintr} internal data structure without any guards to ensure
|
|
Packit |
6c4009 |
safety in the presence of concurrent modifications.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
We do not mark these functions as MT- or AS-Unsafe, however, because
|
|
Packit |
6c4009 |
functions that modify the this data structure are all marked with
|
|
Packit |
6c4009 |
@code{const:sigintr} and regarded as unsafe. Being unsafe, the latter
|
|
Packit |
6c4009 |
are not to be called when multiple threads are running or asynchronous
|
|
Packit |
6c4009 |
signals are enabled, and so the data structure can be considered
|
|
Packit |
6c4009 |
effectively constant in these contexts, which makes the former safe.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{fd}
|
|
Packit |
6c4009 |
@cindex fd
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions annotated with @code{fd} as an AC-Safety issue may leak file
|
|
Packit |
6c4009 |
descriptors if asynchronous thread cancellation interrupts their
|
|
Packit |
6c4009 |
execution.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions that allocate or deallocate file descriptors will generally be
|
|
Packit |
6c4009 |
marked as such. Even if they attempted to protect the file descriptor
|
|
Packit |
6c4009 |
allocation and deallocation with cleanup regions, allocating a new
|
|
Packit |
6c4009 |
descriptor and storing its number where the cleanup region could release
|
|
Packit |
6c4009 |
it cannot be performed as a single atomic operation. Similarly,
|
|
Packit |
6c4009 |
releasing the descriptor and taking it out of the data structure
|
|
Packit |
6c4009 |
normally responsible for releasing it cannot be performed atomically.
|
|
Packit |
6c4009 |
There will always be a window in which the descriptor cannot be released
|
|
Packit |
6c4009 |
because it was not stored in the cleanup handler argument yet, or it was
|
|
Packit |
6c4009 |
already taken out before releasing it. It cannot be taken out after
|
|
Packit |
6c4009 |
release: an open descriptor could mean either that the descriptor still
|
|
Packit |
6c4009 |
has to be closed, or that it already did so but the descriptor was
|
|
Packit |
6c4009 |
reallocated by another thread or signal handler.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Such leaks could be internally avoided, with some performance penalty,
|
|
Packit |
6c4009 |
by temporarily disabling asynchronous thread cancellation. However,
|
|
Packit |
6c4009 |
since callers of allocation or deallocation functions would have to do
|
|
Packit |
6c4009 |
this themselves, to avoid the same sort of leak in their own layer, it
|
|
Packit |
6c4009 |
makes more sense for the library to assume they are taking care of it
|
|
Packit |
6c4009 |
than to impose a performance penalty that is redundant when the problem
|
|
Packit |
6c4009 |
is solved in upper layers, and insufficient when it is not.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This remark by itself does not cause a function to be regarded as
|
|
Packit |
6c4009 |
AC-Unsafe. However, cumulative effects of such leaks may pose a
|
|
Packit |
6c4009 |
problem for some programs. If this is the case, suspending asynchronous
|
|
Packit |
6c4009 |
cancellation for the duration of calls to such functions is recommended.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{mem}
|
|
Packit |
6c4009 |
@cindex mem
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions annotated with @code{mem} as an AC-Safety issue may leak
|
|
Packit |
6c4009 |
memory if asynchronous thread cancellation interrupts their execution.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The problem is similar to that of file descriptors: there is no atomic
|
|
Packit |
6c4009 |
interface to allocate memory and store its address in the argument to a
|
|
Packit |
6c4009 |
cleanup handler, or to release it and remove its address from that
|
|
Packit |
6c4009 |
argument, without at least temporarily disabling asynchronous
|
|
Packit |
6c4009 |
cancellation, which these functions do not do.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This remark does not by itself cause a function to be regarded as
|
|
Packit |
6c4009 |
generally AC-Unsafe. However, cumulative effects of such leaks may be
|
|
Packit |
6c4009 |
severe enough for some programs that disabling asynchronous cancellation
|
|
Packit |
6c4009 |
for the duration of calls to such functions may be required.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{cwd}
|
|
Packit |
6c4009 |
@cindex cwd
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Functions marked with @code{cwd} as an MT-Safety issue may temporarily
|
|
Packit |
6c4009 |
change the current working directory during their execution, which may
|
|
Packit |
6c4009 |
cause relative pathnames to be resolved in unexpected ways in other
|
|
Packit |
6c4009 |
threads or within asynchronous signal or cancellation handlers.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This is not enough of a reason to mark so-marked functions as MT- or
|
|
Packit |
6c4009 |
AS-Unsafe, but when this behavior is optional (e.g., @code{nftw} with
|
|
Packit |
6c4009 |
@code{FTW_CHDIR}), avoiding the option may be a good alternative to
|
|
Packit |
6c4009 |
using full pathnames or file descriptor-relative (e.g. @code{openat})
|
|
Packit |
6c4009 |
system calls.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{!posix}
|
|
Packit |
6c4009 |
@cindex !posix
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This remark, as an MT-, AS- or AC-Safety note to a function, indicates
|
|
Packit |
6c4009 |
the safety status of the function is known to differ from the specified
|
|
Packit |
6c4009 |
status in the POSIX standard. For example, POSIX does not require a
|
|
Packit |
6c4009 |
function to be Safe, but our implementation is, or vice-versa.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
For the time being, the absence of this remark does not imply the safety
|
|
Packit |
6c4009 |
properties we documented are identical to those mandated by POSIX for
|
|
Packit |
6c4009 |
the corresponding functions.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{:identifier}
|
|
Packit |
6c4009 |
@cindex :identifier
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Annotations may sometimes be followed by identifiers, intended to group
|
|
Packit |
6c4009 |
several functions that e.g. access the data structures in an unsafe way,
|
|
Packit |
6c4009 |
as in @code{race} and @code{const}, or to provide more specific
|
|
Packit |
6c4009 |
information, such as naming a signal in a function marked with
|
|
Packit |
6c4009 |
@code{sig}. It is envisioned that it may be applied to @code{lock} and
|
|
Packit |
6c4009 |
@code{corrupt} as well in the future.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In most cases, the identifier will name a set of functions, but it may
|
|
Packit |
6c4009 |
name global objects or function arguments, or identifiable properties or
|
|
Packit |
6c4009 |
logical components associated with them, with a notation such as
|
|
Packit |
6c4009 |
e.g. @code{:buf(arg)} to denote a buffer associated with the argument
|
|
Packit |
6c4009 |
@var{arg}, or @code{:tcattr(fd)} to denote the terminal attributes of a
|
|
Packit |
6c4009 |
file descriptor @var{fd}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The most common use for identifiers is to provide logical groups of
|
|
Packit |
6c4009 |
functions and arguments that need to be protected by the same
|
|
Packit |
6c4009 |
synchronization primitive in order to ensure safe operation in a given
|
|
Packit |
6c4009 |
context.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item @code{/condition}
|
|
Packit |
6c4009 |
@cindex /condition
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Some safety annotations may be conditional, in that they only apply if a
|
|
Packit |
6c4009 |
boolean expression involving arguments, global variables or even the
|
|
Packit |
6c4009 |
underlying kernel evaluates to true. Such conditions as
|
|
Packit |
6c4009 |
@code{/hurd} or @code{/!linux!bsd} indicate the preceding marker only
|
|
Packit |
6c4009 |
applies when the underlying kernel is the HURD, or when it is neither
|
|
Packit |
6c4009 |
Linux nor a BSD kernel, respectively. @code{/!ps} and
|
|
Packit |
6c4009 |
@code{/one_per_line} indicate the preceding marker only applies when
|
|
Packit |
6c4009 |
argument @var{ps} is NULL, or global variable @var{one_per_line} is
|
|
Packit |
6c4009 |
nonzero.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
When all marks that render a function unsafe are adorned with such
|
|
Packit |
6c4009 |
conditions, and none of the named conditions hold, then the function can
|
|
Packit |
6c4009 |
be regarded as safe.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Berkeley Unix, SVID, POSIX, Standards and Portability
|
|
Packit |
6c4009 |
@subsection Berkeley Unix
|
|
Packit |
6c4009 |
@cindex BSD Unix
|
|
Packit |
6c4009 |
@cindex 4.@var{n} BSD Unix
|
|
Packit |
6c4009 |
@cindex Berkeley Unix
|
|
Packit |
6c4009 |
@cindex SunOS
|
|
Packit |
6c4009 |
@cindex Unix, Berkeley
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@Theglibc{} defines facilities from some versions of Unix which
|
|
Packit |
6c4009 |
are not formally standardized, specifically from the 4.2 BSD, 4.3 BSD,
|
|
Packit |
6c4009 |
and 4.4 BSD Unix systems (also known as @dfn{Berkeley Unix}) and from
|
|
Packit |
6c4009 |
@dfn{SunOS} (a popular 4.2 BSD derivative that includes some Unix System
|
|
Packit |
6c4009 |
V functionality). These systems support most of the @w{ISO C} and POSIX
|
|
Packit |
6c4009 |
facilities, and 4.4 BSD and newer releases of SunOS in fact support them all.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The BSD facilities include symbolic links (@pxref{Symbolic Links}), the
|
|
Packit |
6c4009 |
@code{select} function (@pxref{Waiting for I/O}), the BSD signal
|
|
Packit |
6c4009 |
functions (@pxref{BSD Signal Handling}), and sockets (@pxref{Sockets}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node SVID, XPG, Berkeley Unix, Standards and Portability
|
|
Packit |
6c4009 |
@subsection SVID (The System V Interface Description)
|
|
Packit |
6c4009 |
@cindex SVID
|
|
Packit |
6c4009 |
@cindex System V Unix
|
|
Packit |
6c4009 |
@cindex Unix, System V
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The @dfn{System V Interface Description} (SVID) is a document describing
|
|
Packit |
6c4009 |
the AT&T Unix System V operating system. It is to some extent a
|
|
Packit |
6c4009 |
superset of the POSIX standard (@pxref{POSIX}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@Theglibc{} defines most of the facilities required by the SVID
|
|
Packit |
6c4009 |
that are not also required by the @w{ISO C} or POSIX standards, for
|
|
Packit |
6c4009 |
compatibility with System V Unix and other Unix systems (such as
|
|
Packit |
6c4009 |
SunOS) which include these facilities. However, many of the more
|
|
Packit |
6c4009 |
obscure and less generally useful facilities required by the SVID are
|
|
Packit |
6c4009 |
not included. (In fact, Unix System V itself does not provide them all.)
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The supported facilities from System V include the methods for
|
|
Packit |
6c4009 |
inter-process communication and shared memory, the @code{hsearch} and
|
|
Packit |
6c4009 |
@code{drand48} families of functions, @code{fmtmsg} and several of the
|
|
Packit |
6c4009 |
mathematical functions.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node XPG, , SVID, Standards and Portability
|
|
Packit |
6c4009 |
@subsection XPG (The X/Open Portability Guide)
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The X/Open Portability Guide, published by the X/Open Company, Ltd., is
|
|
Packit |
6c4009 |
a more general standard than POSIX. X/Open owns the Unix copyright and
|
|
Packit |
6c4009 |
the XPG specifies the requirements for systems which are intended to be
|
|
Packit |
6c4009 |
a Unix system.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@Theglibc{} complies to the X/Open Portability Guide, Issue 4.2,
|
|
Packit |
6c4009 |
with all extensions common to XSI (X/Open System Interface)
|
|
Packit |
6c4009 |
compliant systems and also all X/Open UNIX extensions.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The additions on top of POSIX are mainly derived from functionality
|
|
Packit |
6c4009 |
available in @w{System V} and BSD systems. Some of the really bad
|
|
Packit |
6c4009 |
mistakes in @w{System V} systems were corrected, though. Since
|
|
Packit |
6c4009 |
fulfilling the XPG standard with the Unix extensions is a
|
|
Packit |
6c4009 |
precondition for getting the Unix brand chances are good that the
|
|
Packit |
6c4009 |
functionality is available on commercial systems.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Using the Library, Roadmap to the Manual, Standards and Portability, Introduction
|
|
Packit |
6c4009 |
@section Using the Library
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
This section describes some of the practical issues involved in using
|
|
Packit |
6c4009 |
@theglibc{}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@menu
|
|
Packit |
6c4009 |
* Header Files:: How to include the header files in your
|
|
Packit |
6c4009 |
programs.
|
|
Packit |
6c4009 |
* Macro Definitions:: Some functions in the library may really
|
|
Packit |
6c4009 |
be implemented as macros.
|
|
Packit |
6c4009 |
* Reserved Names:: The C standard reserves some names for
|
|
Packit |
6c4009 |
the library, and some for users.
|
|
Packit |
6c4009 |
* Feature Test Macros:: How to control what names are defined.
|
|
Packit |
6c4009 |
@end menu
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Header Files, Macro Definitions, , Using the Library
|
|
Packit |
6c4009 |
@subsection Header Files
|
|
Packit |
6c4009 |
@cindex header files
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Libraries for use by C programs really consist of two parts: @dfn{header
|
|
Packit |
6c4009 |
files} that define types and macros and declare variables and
|
|
Packit |
6c4009 |
functions; and the actual library or @dfn{archive} that contains the
|
|
Packit |
6c4009 |
definitions of the variables and functions.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
(Recall that in C, a @dfn{declaration} merely provides information that
|
|
Packit |
6c4009 |
a function or variable exists and gives its type. For a function
|
|
Packit |
6c4009 |
declaration, information about the types of its arguments might be
|
|
Packit |
6c4009 |
provided as well. The purpose of declarations is to allow the compiler
|
|
Packit |
6c4009 |
to correctly process references to the declared variables and functions.
|
|
Packit |
6c4009 |
A @dfn{definition}, on the other hand, actually allocates storage for a
|
|
Packit |
6c4009 |
variable or says what a function does.)
|
|
Packit |
6c4009 |
@cindex definition (compared to declaration)
|
|
Packit |
6c4009 |
@cindex declaration (compared to definition)
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In order to use the facilities in @theglibc{}, you should be sure
|
|
Packit |
6c4009 |
that your program source files include the appropriate header files.
|
|
Packit |
6c4009 |
This is so that the compiler has declarations of these facilities
|
|
Packit |
6c4009 |
available and can correctly process references to them. Once your
|
|
Packit |
6c4009 |
program has been compiled, the linker resolves these references to
|
|
Packit |
6c4009 |
the actual definitions provided in the archive file.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Header files are included into a program source file by the
|
|
Packit |
6c4009 |
@samp{#include} preprocessor directive. The C language supports two
|
|
Packit |
6c4009 |
forms of this directive; the first,
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
#include "@var{header}"
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
is typically used to include a header file @var{header} that you write
|
|
Packit |
6c4009 |
yourself; this would contain definitions and declarations describing the
|
|
Packit |
6c4009 |
interfaces between the different parts of your particular application.
|
|
Packit |
6c4009 |
By contrast,
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
#include <file.h>
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
is typically used to include a header file @file{file.h} that contains
|
|
Packit |
6c4009 |
definitions and declarations for a standard library. This file would
|
|
Packit |
6c4009 |
normally be installed in a standard place by your system administrator.
|
|
Packit |
6c4009 |
You should use this second form for the C library header files.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Typically, @samp{#include} directives are placed at the top of the C
|
|
Packit |
6c4009 |
source file, before any other code. If you begin your source files with
|
|
Packit |
6c4009 |
some comments explaining what the code in the file does (a good idea),
|
|
Packit |
6c4009 |
put the @samp{#include} directives immediately afterwards, following the
|
|
Packit |
6c4009 |
feature test macro definition (@pxref{Feature Test Macros}).
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
For more information about the use of header files and @samp{#include}
|
|
Packit |
6c4009 |
directives, @pxref{Header Files,,, cpp.info, The GNU C Preprocessor
|
|
Packit |
6c4009 |
Manual}.@refill
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@Theglibc{} provides several header files, each of which contains
|
|
Packit |
6c4009 |
the type and macro definitions and variable and function declarations
|
|
Packit |
6c4009 |
for a group of related facilities. This means that your programs may
|
|
Packit |
6c4009 |
need to include several header files, depending on exactly which
|
|
Packit |
6c4009 |
facilities you are using.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Some library header files include other library header files
|
|
Packit |
6c4009 |
automatically. However, as a matter of programming style, you should
|
|
Packit |
6c4009 |
not rely on this; it is better to explicitly include all the header
|
|
Packit |
6c4009 |
files required for the library facilities you are using. The @glibcadj{}
|
|
Packit |
6c4009 |
header files have been written in such a way that it doesn't
|
|
Packit |
6c4009 |
matter if a header file is accidentally included more than once;
|
|
Packit |
6c4009 |
including a header file a second time has no effect. Likewise, if your
|
|
Packit |
6c4009 |
program needs to include multiple header files, the order in which they
|
|
Packit |
6c4009 |
are included doesn't matter.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@strong{Compatibility Note:} Inclusion of standard header files in any
|
|
Packit |
6c4009 |
order and any number of times works in any @w{ISO C} implementation.
|
|
Packit |
6c4009 |
However, this has traditionally not been the case in many older C
|
|
Packit |
6c4009 |
implementations.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Strictly speaking, you don't @emph{have to} include a header file to use
|
|
Packit |
6c4009 |
a function it declares; you could declare the function explicitly
|
|
Packit |
6c4009 |
yourself, according to the specifications in this manual. But it is
|
|
Packit |
6c4009 |
usually better to include the header file because it may define types
|
|
Packit |
6c4009 |
and macros that are not otherwise available and because it may define
|
|
Packit |
6c4009 |
more efficient macro replacements for some functions. It is also a sure
|
|
Packit |
6c4009 |
way to have the correct declaration.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Macro Definitions, Reserved Names, Header Files, Using the Library
|
|
Packit |
6c4009 |
@subsection Macro Definitions of Functions
|
|
Packit |
6c4009 |
@cindex shadowing functions with macros
|
|
Packit |
6c4009 |
@cindex removing macros that shadow functions
|
|
Packit |
6c4009 |
@cindex undefining macros that shadow functions
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If we describe something as a function in this manual, it may have a
|
|
Packit |
6c4009 |
macro definition as well. This normally has no effect on how your
|
|
Packit |
6c4009 |
program runs---the macro definition does the same thing as the function
|
|
Packit |
6c4009 |
would. In particular, macro equivalents for library functions evaluate
|
|
Packit |
6c4009 |
arguments exactly once, in the same way that a function call would. The
|
|
Packit |
6c4009 |
main reason for these macro definitions is that sometimes they can
|
|
Packit |
6c4009 |
produce an inline expansion that is considerably faster than an actual
|
|
Packit |
6c4009 |
function call.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Taking the address of a library function works even if it is also
|
|
Packit |
6c4009 |
defined as a macro. This is because, in this context, the name of the
|
|
Packit |
6c4009 |
function isn't followed by the left parenthesis that is syntactically
|
|
Packit |
6c4009 |
necessary to recognize a macro call.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
You might occasionally want to avoid using the macro definition of a
|
|
Packit |
6c4009 |
function---perhaps to make your program easier to debug. There are
|
|
Packit |
6c4009 |
two ways you can do this:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
You can avoid a macro definition in a specific use by enclosing the name
|
|
Packit |
6c4009 |
of the function in parentheses. This works because the name of the
|
|
Packit |
6c4009 |
function doesn't appear in a syntactic context where it is recognizable
|
|
Packit |
6c4009 |
as a macro call.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
You can suppress any macro definition for a whole source file by using
|
|
Packit |
6c4009 |
the @samp{#undef} preprocessor directive, unless otherwise stated
|
|
Packit |
6c4009 |
explicitly in the description of that facility.
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
For example, suppose the header file @file{stdlib.h} declares a function
|
|
Packit |
6c4009 |
named @code{abs} with
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
extern int abs (int);
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
and also provides a macro definition for @code{abs}. Then, in:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
#include <stdlib.h>
|
|
Packit |
6c4009 |
int f (int *i) @{ return abs (++*i); @}
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@noindent
|
|
Packit |
6c4009 |
the reference to @code{abs} might refer to either a macro or a function.
|
|
Packit |
6c4009 |
On the other hand, in each of the following examples the reference is
|
|
Packit |
6c4009 |
to a function and not a macro.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@smallexample
|
|
Packit |
6c4009 |
#include <stdlib.h>
|
|
Packit |
6c4009 |
int g (int *i) @{ return (abs) (++*i); @}
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
#undef abs
|
|
Packit |
6c4009 |
int h (int *i) @{ return abs (++*i); @}
|
|
Packit |
6c4009 |
@end smallexample
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Since macro definitions that double for a function behave in
|
|
Packit |
6c4009 |
exactly the same way as the actual function version, there is usually no
|
|
Packit |
6c4009 |
need for any of these methods. In fact, removing macro definitions usually
|
|
Packit |
6c4009 |
just makes your program slower.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Reserved Names, Feature Test Macros, Macro Definitions, Using the Library
|
|
Packit |
6c4009 |
@subsection Reserved Names
|
|
Packit |
6c4009 |
@cindex reserved names
|
|
Packit |
6c4009 |
@cindex name space
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
The names of all library types, macros, variables and functions that
|
|
Packit |
6c4009 |
come from the @w{ISO C} standard are reserved unconditionally; your program
|
|
Packit |
6c4009 |
@strong{may not} redefine these names. All other library names are
|
|
Packit |
6c4009 |
reserved if your program explicitly includes the header file that
|
|
Packit |
6c4009 |
defines or declares them. There are several reasons for these
|
|
Packit |
6c4009 |
restrictions:
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Other people reading your code could get very confused if you were using
|
|
Packit |
6c4009 |
a function named @code{exit} to do something completely different from
|
|
Packit |
6c4009 |
what the standard @code{exit} function does, for example. Preventing
|
|
Packit |
6c4009 |
this situation helps to make your programs easier to understand and
|
|
Packit |
6c4009 |
contributes to modularity and maintainability.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
It avoids the possibility of a user accidentally redefining a library
|
|
Packit |
6c4009 |
function that is called by other library functions. If redefinition
|
|
Packit |
6c4009 |
were allowed, those other functions would not work properly.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
It allows the compiler to do whatever special optimizations it pleases
|
|
Packit |
6c4009 |
on calls to these functions, without the possibility that they may have
|
|
Packit |
6c4009 |
been redefined by the user. Some library facilities, such as those for
|
|
Packit |
6c4009 |
dealing with variadic arguments (@pxref{Variadic Functions})
|
|
Packit |
6c4009 |
and non-local exits (@pxref{Non-Local Exits}), actually require a
|
|
Packit |
6c4009 |
considerable amount of cooperation on the part of the C compiler, and
|
|
Packit |
6c4009 |
with respect to the implementation, it might be easier for the compiler
|
|
Packit |
6c4009 |
to treat these as built-in parts of the language.
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In addition to the names documented in this manual, reserved names
|
|
Packit |
6c4009 |
include all external identifiers (global functions and variables) that
|
|
Packit |
6c4009 |
begin with an underscore (@samp{_}) and all identifiers regardless of
|
|
Packit |
6c4009 |
use that begin with either two underscores or an underscore followed by
|
|
Packit |
6c4009 |
a capital letter are reserved names. This is so that the library and
|
|
Packit |
6c4009 |
header files can define functions, variables, and macros for internal
|
|
Packit |
6c4009 |
purposes without risk of conflict with names in user programs.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Some additional classes of identifier names are reserved for future
|
|
Packit |
6c4009 |
extensions to the C language or the POSIX.1 environment. While using these
|
|
Packit |
6c4009 |
names for your own purposes right now might not cause a problem, they do
|
|
Packit |
6c4009 |
raise the possibility of conflict with future versions of the C
|
|
Packit |
6c4009 |
or POSIX standards, so you should avoid these names.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Names beginning with a capital @samp{E} followed a digit or uppercase
|
|
Packit |
6c4009 |
letter may be used for additional error code names. @xref{Error
|
|
Packit |
6c4009 |
Reporting}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Names that begin with either @samp{is} or @samp{to} followed by a
|
|
Packit |
6c4009 |
lowercase letter may be used for additional character testing and
|
|
Packit |
6c4009 |
conversion functions. @xref{Character Handling}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Names that begin with @samp{LC_} followed by an uppercase letter may be
|
|
Packit |
6c4009 |
used for additional macros specifying locale attributes.
|
|
Packit |
6c4009 |
@xref{Locales}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Names of all existing mathematics functions (@pxref{Mathematics})
|
|
Packit |
6c4009 |
suffixed with @samp{f} or @samp{l} are reserved for corresponding
|
|
Packit |
6c4009 |
functions that operate on @code{float} and @code{long double} arguments,
|
|
Packit |
6c4009 |
respectively.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Names that begin with @samp{SIG} followed by an uppercase letter are
|
|
Packit |
6c4009 |
reserved for additional signal names. @xref{Standard Signals}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Names that begin with @samp{SIG_} followed by an uppercase letter are
|
|
Packit |
6c4009 |
reserved for additional signal actions. @xref{Basic Signal Handling}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Names beginning with @samp{str}, @samp{mem}, or @samp{wcs} followed by a
|
|
Packit |
6c4009 |
lowercase letter are reserved for additional string and array functions.
|
|
Packit |
6c4009 |
@xref{String and Array Utilities}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
Names that end with @samp{_t} are reserved for additional type names.
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
In addition, some individual header files reserve names beyond
|
|
Packit |
6c4009 |
those that they actually define. You only need to worry about these
|
|
Packit |
6c4009 |
restrictions if your program includes that particular header file.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
The header file @file{dirent.h} reserves names prefixed with
|
|
Packit |
6c4009 |
@samp{d_}.
|
|
Packit |
6c4009 |
@pindex dirent.h
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
The header file @file{fcntl.h} reserves names prefixed with
|
|
Packit |
6c4009 |
@samp{l_}, @samp{F_}, @samp{O_}, and @samp{S_}.
|
|
Packit |
6c4009 |
@pindex fcntl.h
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
The header file @file{grp.h} reserves names prefixed with @samp{gr_}.
|
|
Packit |
6c4009 |
@pindex grp.h
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
The header file @file{limits.h} reserves names suffixed with @samp{_MAX}.
|
|
Packit |
6c4009 |
@pindex limits.h
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
The header file @file{pwd.h} reserves names prefixed with @samp{pw_}.
|
|
Packit |
6c4009 |
@pindex pwd.h
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
The header file @file{signal.h} reserves names prefixed with @samp{sa_}
|
|
Packit |
6c4009 |
and @samp{SA_}.
|
|
Packit |
6c4009 |
@pindex signal.h
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
The header file @file{sys/stat.h} reserves names prefixed with @samp{st_}
|
|
Packit |
6c4009 |
and @samp{S_}.
|
|
Packit |
6c4009 |
@pindex sys/stat.h
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
The header file @file{sys/times.h} reserves names prefixed with @samp{tms_}.
|
|
Packit |
6c4009 |
@pindex sys/times.h
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
The header file @file{termios.h} reserves names prefixed with @samp{c_},
|
|
Packit |
6c4009 |
@samp{V}, @samp{I}, @samp{O}, and @samp{TC}; and names prefixed with
|
|
Packit |
6c4009 |
@samp{B} followed by a digit.
|
|
Packit |
6c4009 |
@pindex termios.h
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@comment Include the section on Creature Nest Macros.
|
|
Packit |
6c4009 |
@include creature.texi
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@node Roadmap to the Manual, , Using the Library, Introduction
|
|
Packit |
6c4009 |
@section Roadmap to the Manual
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
Here is an overview of the contents of the remaining chapters of
|
|
Packit |
6c4009 |
this manual.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c The chapter overview ordering is:
|
|
Packit |
6c4009 |
@c Error Reporting (2)
|
|
Packit |
6c4009 |
@c Virtual Memory Allocation and Paging (3)
|
|
Packit |
6c4009 |
@c Character Handling (4)
|
|
Packit |
6c4009 |
@c Strings and Array Utilities (5)
|
|
Packit |
6c4009 |
@c Character Set Handling (6)
|
|
Packit |
6c4009 |
@c Locales and Internationalization (7)
|
|
Packit |
6c4009 |
@c Searching and Sorting (9)
|
|
Packit |
6c4009 |
@c Pattern Matching (10)
|
|
Packit |
6c4009 |
@c Input/Output Overview (11)
|
|
Packit |
6c4009 |
@c Input/Output on Streams (12)
|
|
Packit |
6c4009 |
@c Low-level Input/Ooutput (13)
|
|
Packit |
6c4009 |
@c File System Interface (14)
|
|
Packit |
6c4009 |
@c Pipes and FIFOs (15)
|
|
Packit |
6c4009 |
@c Sockets (16)
|
|
Packit |
6c4009 |
@c Low-Level Terminal Interface (17)
|
|
Packit |
6c4009 |
@c Syslog (18)
|
|
Packit |
6c4009 |
@c Mathematics (19)
|
|
Packit |
6c4009 |
@c Aritmetic Functions (20)
|
|
Packit |
6c4009 |
@c Date and Time (21)
|
|
Packit |
6c4009 |
@c Non-Local Exist (23)
|
|
Packit |
6c4009 |
@c Signal Handling (24)
|
|
Packit |
6c4009 |
@c The Basic Program/System Interface (25)
|
|
Packit |
6c4009 |
@c Processes (26)
|
|
Packit |
6c4009 |
@c Job Control (28)
|
|
Packit |
6c4009 |
@c System Databases and Name Service Switch (29)
|
|
Packit |
6c4009 |
@c Users and Groups (30) -- References `User Database' and `Group Database'
|
|
Packit |
6c4009 |
@c System Management (31)
|
|
Packit |
6c4009 |
@c System Configuration Parameters (32)
|
|
Packit |
6c4009 |
@c C Language Facilities in the Library (AA)
|
|
Packit |
6c4009 |
@c Summary of Library Facilities (AB)
|
|
Packit |
6c4009 |
@c Installing (AC)
|
|
Packit |
6c4009 |
@c Library Maintenance (AD)
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@c The following chapters need overview text to be added:
|
|
Packit |
6c4009 |
@c Message Translation (8)
|
|
Packit |
6c4009 |
@c Resource Usage And Limitations (22)
|
|
Packit |
6c4009 |
@c Inter-Process Communication (27)
|
|
Packit |
6c4009 |
@c Debugging support (34)
|
|
Packit |
6c4009 |
@c POSIX Threads (35)
|
|
Packit |
6c4009 |
@c Internal Probes (36)
|
|
Packit |
6c4009 |
@c Platform-specific facilities (AE)
|
|
Packit |
6c4009 |
@c Contributors to (AF)
|
|
Packit |
6c4009 |
@c Free Software Needs Free Documentation (AG)
|
|
Packit |
6c4009 |
@c GNU Lesser General Public License (AH)
|
|
Packit |
6c4009 |
@c GNU Free Documentation License (AI)
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@itemize @bullet
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Error Reporting}, describes how errors detected by the library
|
|
Packit |
6c4009 |
are reported.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Memory}, describes @theglibc{}'s facilities for managing and
|
|
Packit |
6c4009 |
using virtual and real memory, including dynamic allocation of virtual
|
|
Packit |
6c4009 |
memory. If you do not know in advance how much memory your program
|
|
Packit |
6c4009 |
needs, you can allocate it dynamically instead, and manipulate it via
|
|
Packit |
6c4009 |
pointers.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Character Handling}, contains information about character
|
|
Packit |
6c4009 |
classification functions (such as @code{isspace}) and functions for
|
|
Packit |
6c4009 |
performing case conversion.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{String and Array Utilities}, has descriptions of functions for
|
|
Packit |
6c4009 |
manipulating strings (null-terminated character arrays) and general
|
|
Packit |
6c4009 |
byte arrays, including operations such as copying and comparison.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Character Set Handling}, contains information about manipulating
|
|
Packit |
6c4009 |
characters and strings using character sets larger than will fit in
|
|
Packit |
6c4009 |
the usual @code{char} data type.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Locales}, describes how selecting a particular country
|
|
Packit |
6c4009 |
or language affects the behavior of the library. For example, the locale
|
|
Packit |
6c4009 |
affects collation sequences for strings and how monetary values are
|
|
Packit |
6c4009 |
formatted.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Searching and Sorting}, contains information about functions
|
|
Packit |
6c4009 |
for searching and sorting arrays. You can use these functions on any
|
|
Packit |
6c4009 |
kind of array by providing an appropriate comparison function.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Pattern Matching}, presents functions for matching regular expressions
|
|
Packit |
6c4009 |
and shell file name patterns, and for expanding words as the shell does.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{I/O Overview}, gives an overall look at the input and output
|
|
Packit |
6c4009 |
facilities in the library, and contains information about basic concepts
|
|
Packit |
6c4009 |
such as file names.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{I/O on Streams}, describes I/O operations involving streams (or
|
|
Packit |
6c4009 |
@w{@code{FILE *}} objects). These are the normal C library functions
|
|
Packit |
6c4009 |
from @file{stdio.h}.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Low-Level I/O}, contains information about I/O operations
|
|
Packit |
6c4009 |
on file descriptors. File descriptors are a lower-level mechanism
|
|
Packit |
6c4009 |
specific to the Unix family of operating systems.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{File System Interface}, has descriptions of operations on entire
|
|
Packit |
6c4009 |
files, such as functions for deleting and renaming them and for creating
|
|
Packit |
6c4009 |
new directories. This chapter also contains information about how you
|
|
Packit |
6c4009 |
can access the attributes of a file, such as its owner and file protection
|
|
Packit |
6c4009 |
modes.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Pipes and FIFOs}, contains information about simple interprocess
|
|
Packit |
6c4009 |
communication mechanisms. Pipes allow communication between two related
|
|
Packit |
6c4009 |
processes (such as between a parent and child), while FIFOs allow
|
|
Packit |
6c4009 |
communication between processes sharing a common file system on the same
|
|
Packit |
6c4009 |
machine.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Sockets}, describes a more complicated interprocess communication
|
|
Packit |
6c4009 |
mechanism that allows processes running on different machines to
|
|
Packit |
6c4009 |
communicate over a network. This chapter also contains information about
|
|
Packit |
6c4009 |
Internet host addressing and how to use the system network databases.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Low-Level Terminal Interface}, describes how you can change the
|
|
Packit |
6c4009 |
attributes of a terminal device. If you want to disable echo of
|
|
Packit |
6c4009 |
characters typed by the user, for example, read this chapter.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Mathematics}, contains information about the math library
|
|
Packit |
6c4009 |
functions. These include things like random-number generators and
|
|
Packit |
6c4009 |
remainder functions on integers as well as the usual trigonometric and
|
|
Packit |
6c4009 |
exponential functions on floating-point numbers.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Arithmetic,, Low-Level Arithmetic Functions}, describes functions
|
|
Packit |
6c4009 |
for simple arithmetic, analysis of floating-point values, and reading
|
|
Packit |
6c4009 |
numbers from strings.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Date and Time}, describes functions for measuring both calendar time
|
|
Packit |
6c4009 |
and CPU time, as well as functions for setting alarms and timers.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Non-Local Exits}, contains descriptions of the @code{setjmp} and
|
|
Packit |
6c4009 |
@code{longjmp} functions. These functions provide a facility for
|
|
Packit |
6c4009 |
@code{goto}-like jumps which can jump from one function to another.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Signal Handling}, tells you all about signals---what they are,
|
|
Packit |
6c4009 |
how to establish a handler that is called when a particular kind of
|
|
Packit |
6c4009 |
signal is delivered, and how to prevent signals from arriving during
|
|
Packit |
6c4009 |
critical sections of your program.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Program Basics}, tells how your programs can access their
|
|
Packit |
6c4009 |
command-line arguments and environment variables.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Processes}, contains information about how to start new processes
|
|
Packit |
6c4009 |
and run programs.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Job Control}, describes functions for manipulating process groups
|
|
Packit |
6c4009 |
and the controlling terminal. This material is probably only of
|
|
Packit |
6c4009 |
interest if you are writing a shell or other program which handles job
|
|
Packit |
6c4009 |
control specially.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Name Service Switch}, describes the services which are available
|
|
Packit |
6c4009 |
for looking up names in the system databases, how to determine which
|
|
Packit |
6c4009 |
service is used for which database, and how these services are
|
|
Packit |
6c4009 |
implemented so that contributors can design their own services.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{User Database}, and @ref{Group Database}, tell you how to access
|
|
Packit |
6c4009 |
the system user and group databases.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{System Management}, describes functions for controlling and getting
|
|
Packit |
6c4009 |
information about the hardware and software configuration your program
|
|
Packit |
6c4009 |
is executing under.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{System Configuration}, tells you how you can get information about
|
|
Packit |
6c4009 |
various operating system limits. Most of these parameters are provided for
|
|
Packit |
6c4009 |
compatibility with POSIX.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Language Features}, contains information about library support for
|
|
Packit |
6c4009 |
standard parts of the C language, including things like the @code{sizeof}
|
|
Packit |
6c4009 |
operator and the symbolic constant @code{NULL}, how to write functions
|
|
Packit |
6c4009 |
accepting variable numbers of arguments, and constants describing the
|
|
Packit |
6c4009 |
ranges and other properties of the numerical types. There is also a simple
|
|
Packit |
6c4009 |
debugging mechanism which allows you to put assertions in your code, and
|
|
Packit |
6c4009 |
have diagnostic messages printed if the tests fail.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Library Summary}, gives a summary of all the functions, variables, and
|
|
Packit |
6c4009 |
macros in the library, with complete data types and function prototypes,
|
|
Packit |
6c4009 |
and says what standard or system each is derived from.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Installation}, explains how to build and install @theglibc{} on
|
|
Packit |
6c4009 |
your system, and how to report any bugs you might find.
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
@item
|
|
Packit |
6c4009 |
@ref{Maintenance}, explains how to add new functions or port the
|
|
Packit |
6c4009 |
library to a new system.
|
|
Packit |
6c4009 |
@end itemize
|
|
Packit |
6c4009 |
|
|
Packit |
6c4009 |
If you already know the name of the facility you are interested in, you
|
|
Packit |
6c4009 |
can look it up in @ref{Library Summary}. This gives you a summary of
|
|
Packit |
6c4009 |
its syntax and a pointer to where you can find a more detailed
|
|
Packit |
6c4009 |
description. This appendix is particularly useful if you just want to
|
|
Packit |
6c4009 |
verify the order and type of arguments to a function, for example. It
|
|
Packit |
6c4009 |
also tells you what standard or system each function, variable, or macro
|
|
Packit |
6c4009 |
is derived from.
|