path: root/doc/info/chap/introduction.texinfo

@node Introduction
@chapter Introduction

@cpindex Hosted environment
@cpindex Unhosted environment
The C programming language does not provide
any built-in functions or constant values.
It only, provides a few basic numerical
data types. In fact, it does not even call
the function @code{main}. All of these
facilities are provided by the C standard
library. A C environment with a C standard
library is called a hosted environment; one
without it is called an unhosted environment.
Almost all software written in C are written
in hosted C@. There are practically only two
types of software not written in an unhosted
environment, the C standard library (commonly
called @command{libc}) implementations
themself, and operating system kernels and
programs started before it.

The Stockholm C Standard Library, or simply
@command{slibc}, described in this document,
is an implementaton of a C standard library for
@sc{POSIX} systems. It is aimed at supporting
@sc{C99} and newer dialects of @sc{ISO}@tie{}C,
and no other programming languages. @command{slibc}
is not aimed to replace an existing @command{libc}
implementation or suiting a particular niche.
Rather, @command{slibc} is intended as a learning
experiences for its developer. It does however,
add extensions (features) that are not defined
by the standards it covers or even existing
@command{libc} implementations.

@command{slibc}'s header files document all
features it implements. This manual is intended
as a more extensive documentation. It is written
with the assumption that you are familiar with
the C programming language.


@menu
* Reserved Names::                            Names you should not use for your functions and variables.
* Feature-Test Macros::                       Specifying features that should be available.
@end menu



@node Reserved Names
@section Reserved Names

@cpindex Reserved names
@cpindex Names, reserved
The names of all types, variables, functions and
macros, that comes from the @sc{ISO}@tie{}C standard
are reserved. Additionally, all names that are
defined or declared from an explicitly included
header file is reserved.

It is important for maintainability that reserved
names are not redefined. But it is also important
because the C compiler can do special optimisations
bases on the semantics of the standardised function.
It may even replace the function calls, with functions
built into the compiler.

The names that are reserved is not implemented to
those documented in this manual. Some names are
reserved for future use, for the C standard library
to use internally, and for the compiler to define
to give information about the platform. Names
starting with at least one underscore (`_') are
reserved for the two latter. The names that are
reserved for the C and @sc{POSIX} standards, and the
operating system, are:

@itemize @bullet{}
@item
Names that begin with an uppercase @code{E} and
a digit or uppercase letter. These are used for
error-codes names.

@item
Names that begin with @code{LC_} and an uppercase
letter are reserved for locale attributes.

@item
Names that being with @code{SIG} and an uppercase
letter are reserved for signal names.

@item
Names that being with @code{SIG_} and an uppercase
letter are reserved for signal actions.

@item
Names that begin with @code{is} and a lowercase
letter are reserved for character type testing.

@item
Names that begin with @code{mem} and a lowercase
letter are reserved for functions that operate
over character arrays.

@item
Names that begin with @code{str} and a lowercase
letter are reserved for functions that operate
over strings.

@item
Names that begin with @code{to} and a lowercase
letter are reserved for character type conversion.

@item
Names that begin with @code{wmem} and a lowercase
letter are reserved for functions that operate
over wide-character arrays.

@item
Names that begin with @code{wcs} and a lowercase
letter are reserved for functions that operate
over wide-character strings.

@item
Names that end with @code{_t} ae reserved for
type definitions.

@item
Names of existing mathematics functions, suffixed
with @code{f} or @code{l} are reserved for
@code{float}- and @code{long double}-variants
of corresponding functions.

@item
@hfindex dirent.h
Names that begin with @code{d_} are reserved
for @file{<dirent.h>}.

@item
@hfindex fcntl.h
Names that begin with @code{F_}, @code{O_},
or @code{l_} are reserved for @file{<fcntl.h>}.

@item
@hfindex grp.h
Names that begin with @code{gr_} are reserved
for @file{<grp.h>}.

@item
@hfindex limits.h
Names that end with @code{_MAX} are reserved
for @file{<limits.h>}.

@item
@hfindex pwd.h
Names that begin with @code{pw_} are reserved
for @file{<pwd.h>}.

@item
@hfindex signal.h
Names that begin with @code{sa_} or @code{SA_}
are reserved for @file{<signal.h>}.

@item
@hfindex sys/stat.h
Names that begin with @code{st_} or @code{S_}
are reserved for @file{<sys/stat.h>}.

@item
@hfindex sys/times.h
Names that begin with @code{tms_} are reserved
for @file{<sys/times.h>}.

@item
@hfindex termios.h
Names that begin with @code{B} and a digit,
@code{I}, @code{O}, @code{TB}, @code{V}, or
@code{c_} are reserved for @file{<termios.h>}.
@end itemize

It is possible for libraries to avoid restrictions
by prefixing all names with the name of the library
(starting with @code{lib}.) Names that are reserved
for specific header files do not need to considered
unless the header file is included.



@node Feature-Test Macros
@section Feature-Test Macros

@cpindex Feature-test macros
@cpindex Enable features
@cpindex Disable features
@cpindex Extensions
The exact set of features that are make available
by @command{slibc}, depend on which feature-test
macros that are defined.

@command{slibc} specifies four feature-test macros:

@table @code
@item _PORTABLE_SOURCE
@lvindex _PORTABLE_SOURCE
@cpindex Portability
Disables all non-@sc{POSIX} extensions, and
otherwise help ensure that the source is portable.

@item _LIBRARY_HEADER
@lvindex _LIBRARY_HEADER
@cpindex Portability
Alternative to @code{_PORTABLE_SOURCE} that should
be used in header files for libraries. This allows
you to be sure that your library is portable between
@code{libc}:s, and that sources using your library
does not been to be compiled with the same @code{libc}.
It is important to use this instead of
@code{_PORTABLE_SOURCE} in library header files,
otherwise the user of the library cannot fully utilise
@code{_PORTABLE_SOURCE}@.

@item _ALL_SOURCE
@lvindex _ALL_SOURCE
@cpindex Portability
Enables all support extensions.
@* TODO: This is not implemented yet.

@item _SLIBC_SOURCE
@lvindex _SLIBC_SOURCE
Enables extensions added by @command{slibc},
and extensions added in other @command{libc}:s
that are considered to be good extensions.
@end table

@cpindex Portability
For programs that are intended to be portable,
it is recommended to develop the software with
@code{_PORTABLE_SOURCE} defined, by adding the
flag @code{-D_PORTABLE_SOURCE} when compiling
the software, to ensure that you are not using
any non-portable extensions. You should also
occasionally compile with the @code{_ALL_SOURCE}
macro defined instead of the @code{_PORTABLE_SOURCE}
defined, to ensure that you do not define names
that may conflict with other @command{libc}:s.

@cpindex Suppress warnings
@cpindex Warnings, suppress
@lvindex _SLIBC_SUPPRESS_WARNINGS
Additionally, @command{slibc} specifies the
@code{_SLIBC_SUPPRESS_WARNINGS} macro. If this
macro defined, all warnings @command{slibc}
defines for header files and functions are disabled.

@command{slibc} also recognises feature-test
macros defined by other projects.

@table @code
@item _ISOC89_SOURCE
@itemx _ISOC90_SOURCE
@cpindex @sc{ISO}@tie{}C
@cpindex C90
@cpindex C89
@cpindex @sc{ANSI}@tie{}C
@lvindex _ISOC90_SOURCE
@lvindex _ISOC89_SOURCE
Enables functionality from the @sc{ISO}@tie{}C90
standard, even if the program is not compiled
with C90.

Note, @sc{ISO}@tie{}C89, @sc{ISO}@tie{}C90,
@sc{ANSI}@tie{}C and Standard C, all refer to
the same standard.

@item _ISOC99_SOURCE
@cpindex @sc{ISO}@tie{}C
@cpindex C99
@lvindex _ISOC99_SOURCE
Enables functionality from the @sc{ISO}@tie{}C99
standard, even if the program is not compiled
with C99.

@item _ISOC11_SOURCE
@cpindex @sc{ISO}@tie{}C
@cpindex C11
@lvindex _ISOC11_SOURCE
Enables functionality from the @sc{ISO}@tie{}C11
standard, even if the program is not compiled
with C11.

@item _POSIX_SOURCE
@cpindex @sc{POSIX}
@cpindex @sc{ISO}@tie{}C
@lvindex _POSIX_SOURCE
Enables functionality from the @sc{POSIX}.1
standard (@sc{IEEE} Standard 1003.1) as well
as @sc{ISO}@tie{}C@. @code{_POSIX_SOURCE} is
automatically enabled if @code{_POSIX_C_SOURCE}
is defined and has a positive value.

@item _POSIX_C_SOURCE >= 1L
@cpindex @sc{POSIX}
@lvindex _POSIX_C_SOURCE
Enables functionality from the 1990 edition
of the @sc{POSIX}.1 standard (@sc{IEEE}
Standard 1003.1-1990).

@item _POSIX_C_SOURCE >= 2L
@cpindex @sc{POSIX}
@lvindex _POSIX_C_SOURCE
Enables functionality from the 1992 edition
of the @sc{POSIX}.2 standard (@sc{IEEE}
Standard 1003.2-1992).

@item _POSIX_C_SOURCE >= 199309L
@cpindex @sc{POSIX}
@lvindex _POSIX_C_SOURCE
Enables functionality from the 1993 edition
of the @sc{POSIX}.1b standard (@sc{IEEE}
Standard 1003.1b-1993).

@item _POSIX_C_SOURCE >= 199506L
@cpindex @sc{POSIX}
@lvindex _POSIX_C_SOURCE
Enables functionality from the 1996 edition
of the @sc{POSIX}.1 standard (@sc{ISO}/@sc{IEC}
9945-1: 1996).

@item _BSD_SOURCE
@cpindex @sc{BSD}
@lvindex _BSD_SOURCE
Enables functionality from @sc{BSD}, as well
as @sc{ISO}@tie{}C, @sc{POSIX}.1, and @sc{POSIX}.2.
Note that some @sc{BSD} function conflicts with
@sc{POSIX}.1.

@lvindex _BSD_COMPATIBLE_SOURCE
@lvindex _POSIX_COMPATIBLE_SOURCE
To enable the @sc{BSD} functionality that conflicts
with @sc{POSIX}.1 functionality, also define
@code{_BSD_COMPATIBLE_SOURCE}@. If you however
prefer to use the @sc{POSIX}.1 functionality, define
@code{_POSIX_COMPATIBLE_SOURCE} to suppress warnings
about conflicts. These two feature-test macros are
specific to @command{slibc}.

@item _SVID_SOURCE
@cpindex @sc{SVID}
@cpindex System V Interface Description
@lvindex _SVID_SOURCE
Enables functionality from @i{System V Interface
Description} (@sc{SVID}), as well as @sc{ISO}@tie{}C,
@sc{POSIX}.1, @sc{POSIX}.2, and X/Open.

@item _XOPEN_SOURCE
@cpindex X/Open Portability Guide
@lvindex _XOPEN_SOURCE
Enables functionality from @i{X/Open Portability Guide},
included in @sc{BSD} and @sc{SVID}, as well as
@sc{POSIX}.1 and @sc{POSIX}.2.

@item _XOPEN_SOURCE_EXTENDED
@cpindex X/Open Portability Guide
@lvindex _XOPEN_SOURCE
@lvindex _XOPEN_SOURCE_EXTENDED
Enables all functionality that @code{_XOPEN_SOURCE}
enables, and functionality that is required for the
X/Open Unix brand.

@item _XOPEN_SOURCE >= 500
@cpindex X/Open Portability Guide
@cpindex Single Unix Specification
@cpindex @sc{SUS}
@lvindex _XOPEN_SOURCE
@lvindex _XOPEN_SOURCE_EXTENDED
Enables all functionality that @code{_XOPEN_SOURCE_EXTENDED}
enables. It also enables functionality from version 2
of the @i{Single Unix Specification} (@sc{SUS}).

@item _GNU_SOURCE
@cpindex @sc{GNU}'s not Unix
@cpindex @sc{GNU} C Libraries
@lvindex _GNU_SOURCE
Enables all functionality from @sc{ISO}@tie{}C89,
@sc{ISO}@tie{}C99, @sc{POSIX}.1, @sc{POSIX}.2,
@sc{BSD}, @sc{SVID}, X/Open, @sc{SUS}, the
Large File Support extension, and extensions
derived from the @sc{GNU} C Libraries. It also
defines @code{_ATFILE_SOURCE}@.

@lvindex _BSD_SOURCE
@sc{POSIX}.1 takes precedence when there are
conflicts between @sc{POSIX}.1 and @sc{BSD}
or @sc{SVID}@. To override this, define
@code{_BSD_SOURCE}@.

@code{_GNU_SOURCE} does not automatically
define @code{_BSD_SOURCE} or @code{_SVID_SOURCE}@.

@item _PLAN9_SOURCE
@cpindex Plan 9 from Bell Labs
@lvindex _PLAN9_SOURCE
Enables extensions from Plan 9 from Bell Labs
C standard library.

@end table
@c TODO: _LARGEFILE_SUPPORT
@c TODO: _LARGEFILE64_SUPPORT
@c TODO: _FILE_OFFSET_BITS
@c TODO: _ATFILE_SOURCE
@c TODO: _DEFAULT_SOURCE
@c TODO: _REETRANT
@c TODO: _THREADSAFE (alias for _REETRANT)
@c TODO: _POSIX_C_SOURCE >= 200112L
@c TODO: _POSIX_C_SOURCE >= 200809L
@c TODO: _XOPEN_SOURCE >= 600