- If you are not sure how a function should behave, and this manual
-doesn't tell you, that's a bug in the manual. Report that too! If the
-function's behavior disagrees with the manual, then either the library
-or the manual has a bug, so report the disagreement. If you find any
-errors or omissions in this manual, please report them to the Internet
-address `bug-glibc-manual@prep.ai.mit.edu' or the UUCP path
-`mit-eddie!prep.ai.mit.edu!bug-glibc-manual'.
-
-Adding New Functions
-====================
-
- The process of building the library is driven by the makefiles, which
-make heavy use of special features of GNU `make'. The makefiles are
-very complex, and you probably don't want to try to understand them.
-But what they do is fairly straightforward, and only requires that you
-define a few variables in the right places.
-
- The library sources are divided into subdirectories, grouped by
-topic.
-
- The `string' subdirectory has all the string-manipulation functions,
-`math' has all the mathematical functions, etc.
-
- Each subdirectory contains a simple makefile, called `Makefile',
-which defines a few `make' variables and then includes the global
-makefile `Rules' with a line like:
-
- include ../Rules
-
-The basic variables that a subdirectory makefile defines are:
-
-`subdir'
- The name of the subdirectory, for example `stdio'. This variable
- *must* be defined.
-
-`headers'
- The names of the header files in this section of the library, such
- as `stdio.h'.
-
-`routines'
-`aux'
- The names of the modules (source files) in this section of the
- library. These should be simple names, such as `strlen' (rather
- than complete file names, such as `strlen.c'). Use `routines' for
- modules that define functions in the library, and `aux' for
- auxiliary modules containing things like data definitions. But the
- values of `routines' and `aux' are just concatenated, so there
- really is no practical difference.
-
-`tests'
- The names of test programs for this section of the library. These
- should be simple names, such as `tester' (rather than complete file
- names, such as `tester.c'). `make tests' will build and run all
- the test programs. If a test program needs input, put the test
- data in a file called `TEST-PROGRAM.input'; it will be given to
- the test program on its standard input. If a test program wants
- to be run with arguments, put the arguments (all on a single line)
- in a file called `TEST-PROGRAM.args'. Test programs should exit
- with zero status when the test passes, and nonzero status when the
- test indicates a bug in the library or error in building.
-
-`others'
- The names of "other" programs associated with this section of the
- library. These are programs which are not tests per se, but are
- other small programs included with the library. They are built by
- `make others'.
-
-`install-lib'
-`install-data'
-`install'
- Files to be installed by `make install'. Files listed in
- `install-lib' are installed in the directory specified by `libdir'
- in `configparms' or `Makeconfig' (*note Installation::.). Files
- listed in `install-data' are installed in the directory specified
- by `datadir' in `configparms' or `Makeconfig'. Files listed in
- `install' are installed in the directory specified by `bindir' in
- `configparms' or `Makeconfig'.
-
-`distribute'
- Other files from this subdirectory which should be put into a
- distribution tar file. You need not list here the makefile itself
- or the source and header files listed in the other standard
- variables. Only define `distribute' if there are files used in an
- unusual way that should go into the distribution.
-
-`generated'
- Files which are generated by `Makefile' in this subdirectory.
- These files will be removed by `make clean', and they will never
- go into a distribution.
-
-`extra-objs'
- Extra object files which are built by `Makefile' in this
- subdirectory. This should be a list of file names like `foo.o';
- the files will actually be found in whatever directory object
- files are being built in. These files will be removed by
- `make clean'. This variable is used for secondary object files
- needed to build `others' or `tests'.
-
-Porting the GNU C Library
-=========================
-
- The GNU C library is written to be easily portable to a variety of
-machines and operating systems. Machine- and operating system-dependent
-functions are well separated to make it easy to add implementations for
-new machines or operating systems. This section describes the layout of
-the library source tree and explains the mechanisms used to select
-machine-dependent code to use.
-
- All the machine-dependent and operating system-dependent files in the
-library are in the subdirectory `sysdeps' under the top-level library
-source directory. This directory contains a hierarchy of
-subdirectories (*note Hierarchy Conventions::.).
-
- Each subdirectory of `sysdeps' contains source files for a
-particular machine or operating system, or for a class of machine or
-operating system (for example, systems by a particular vendor, or all
-machines that use IEEE 754 floating-point format). A configuration
-specifies an ordered list of these subdirectories. Each subdirectory
-implicitly appends its parent directory to the list. For example,
-specifying the list `unix/bsd/vax' is equivalent to specifying the list
-`unix/bsd/vax unix/bsd unix'. A subdirectory can also specify that it
-implies other subdirectories which are not directly above it in the
-directory hierarchy. If the file `Implies' exists in a subdirectory,
-it lists other subdirectories of `sysdeps' which are appended to the
-list, appearing after the subdirectory containing the `Implies' file.
-Lines in an `Implies' file that begin with a `#' character are ignored
-as comments. For example, `unix/bsd/Implies' contains:
- # BSD has Internet-related things.
- unix/inet
-
-and `unix/Implies' contains:
- posix
-
-So the final list is `unix/bsd/vax unix/bsd unix/inet unix posix'.
-
- `sysdeps' has two "special" subdirectories, called `generic' and
-`stub'. These two are always implicitly appended to the list of
-subdirectories (in that order), so you needn't put them in an `Implies'
-file, and you should not create any subdirectories under them intended
-to be new specific categories. `generic' is for things that can be
-implemented in machine-independent C, using only other
-machine-independent functions in the C library. `stub' is for "stub"
-versions of functions which cannot be implemented on a particular
-machine or operating system. The stub functions always return an
-error, and set `errno' to `ENOSYS' (Function not implemented). *Note
-Error Reporting::.
-
- A source file is known to be system-dependent by its having a
-version in `generic' or `stub'; every generally-available function whose
-implementation is system-dependent in should have either a generic or
-stub implementation (there is no point in having both). Some rare
-functions are only useful on specific systems and aren't defined at all
-on others; these do not appear anywhere in the system-independent
-source code or makefiles (including the `generic' and `stub'
-directories), only in the system-dependent `Makefile' in the specific
-system's subdirectory.
-
- If you come across a file that is in one of the main source
-directories (`string', `stdio', etc.), and you want to write a machine-
-or operating system-dependent version of it, move the file into
-`sysdeps/generic' and write your new implementation in the appropriate
-system-specific subdirectory. Note that if a file is to be
-system-dependent, it *must not* appear in one of the main source
-directories.
-
- There are a few special files that may exist in each subdirectory of
-`sysdeps':
-
-`Makefile'
- A makefile for this machine or operating system, or class of
- machine or operating system. This file is included by the library
- makefile `Makerules', which is used by the top-level makefile and
- the subdirectory makefiles. It can change the variables set in the
- including makefile or add new rules. It can use GNU `make'
- conditional directives based on the variable `subdir' (see above)
- to select different sets of variables and rules for different
- sections of the library. It can also set the `make' variable
- `sysdep-routines', to specify extra modules to be included in the
- library. You should use `sysdep-routines' rather than adding
- modules to `routines' because the latter is used in determining
- what to distribute for each subdirectory of the main source tree.
-
- Each makefile in a subdirectory in the ordered list of
- subdirectories to be searched is included in order. Since several
- system-dependent makefiles may be included, each should append to
- `sysdep-routines' rather than simply setting it:
-
- sysdep-routines := $(sysdep-routines) foo bar
-
-`Subdirs'
- This file contains the names of new whole subdirectories under the
- top-level library source tree that should be included for this
- system. These subdirectories are treated just like the
- system-independent subdirectories in the library source tree, such
- as `stdio' and `math'.
-
- Use this when there are completely new sets of functions and header
- files that should go into the library for the system this
- subdirectory of `sysdeps' implements. For example,
- `sysdeps/unix/inet/Subdirs' contains `inet'; the `inet' directory
- contains various network-oriented operations which only make sense
- to put in the library on systems that support the Internet.
-
-`Dist'
- This file contains the names of files (relative to the
- subdirectory of `sysdeps' in which it appears) which should be
- included in the distribution. List any new files used by rules in
- the `Makefile' in the same directory, or header files used by the
- source files in that directory. You don't need to list files that
- are implementations (either C or assembly source) of routines
- whose names are given in the machine-independent makefiles in the
- main source tree.
-
-`configure'
- This file is a shell script fragment to be run at configuration
- time. The top-level `configure' script uses the shell `.' command
- to read the `configure' file in each system-dependent directory
- chosen, in order. The `configure' files are often generated from
- `configure.in' files using Autoconf.
-
- A system-dependent `configure' script will usually add things to
- the shell variables `DEFS' and `config_vars'; see the top-level
- `configure' script for details. The script can check for
- `--with-PACKAGE' options that were passed to the top-level
- `configure'. For an option `--with-PACKAGE=VALUE' `configure'
- sets the shell variable `with_PACKAGE' (with any dashes in PACKAGE
- converted to underscores) to VALUE; if the option is just
- `--with-PACKAGE' (no argument), then it sets `with_PACKAGE' to
- `yes'.
-
-`configure.in'
- This file is an Autoconf input fragment to be processed into the
- file `configure' in this subdirectory. *Note Introduction:
- (autoconf.info)Introduction, for a description of Autoconf. You
- should write either `configure' or `configure.in', but not both.
- The first line of `configure.in' should invoke the `m4' macro
- `GLIBC_PROVIDES'. This macro does several `AC_PROVIDE' calls for
- Autoconf macros which are used by the top-level `configure'
- script; without this, those macros might be invoked again
- unnecessarily by Autoconf.
-
- That is the general system for how system-dependencies are isolated.
-
-Layout of the `sysdeps' Directory Hierarchy
--------------------------------------------
-
- A GNU configuration name has three parts: the CPU type, the
-manufacturer's name, and the operating system. `configure' uses these
-to pick the list of system-dependent directories to look for. If the
-`--nfp' option is *not* passed to `configure', the directory
-`MACHINE/fpu' is also used. The operating system often has a "base
-operating system"; for example, if the operating system is `sunos4.1',
-the base operating system is `unix/bsd'. The algorithm used to pick
-the list of directories is simple: `configure' makes a list of the base
-operating system, manufacturer, CPU type, and operating system, in that
-order. It then concatenates all these together with slashes in
-between, to produce a directory name; for example, the configuration
-`sparc-sun-sunos4.1' results in `unix/bsd/sun/sparc/sunos4.1'.
-`configure' then tries removing each element of the list in turn, so
-`unix/bsd/sparc' and `sun/sparc' are also tried, among others. Since
-the precise version number of the operating system is often not
-important, and it would be very inconvenient, for example, to have
-identical `sunos4.1.1' and `sunos4.1.2' directories, `configure' tries
-successively less specific operating system names by removing trailing
-suffixes starting with a period.
-
- As an example, here is the complete list of directories that would be
-tried for the configuration `sparc-sun-sunos4.1' (without the `--nfp'
-option):
-
- sparc/fpu
- unix/bsd/sun/sunos4.1/sparc
- unix/bsd/sun/sunos4.1
- unix/bsd/sun/sunos4/sparc
- unix/bsd/sun/sunos4
- unix/bsd/sun/sunos/sparc
- unix/bsd/sun/sunos
- unix/bsd/sun/sparc
- unix/bsd/sun
- unix/bsd/sunos4.1/sparc
- unix/bsd/sunos4.1
- unix/bsd/sunos4/sparc
- unix/bsd/sunos4
- unix/bsd/sunos/sparc
- unix/bsd/sunos
- unix/bsd/sparc
- unix/bsd
- unix/sun/sunos4.1/sparc
- unix/sun/sunos4.1
- unix/sun/sunos4/sparc
- unix/sun/sunos4
- unix/sun/sunos/sparc
- unix/sun/sunos
- unix/sun/sparc
- unix/sun
- unix/sunos4.1/sparc
- unix/sunos4.1
- unix/sunos4/sparc
- unix/sunos4
- unix/sunos/sparc
- unix/sunos
- unix/sparc
- unix
- sun/sunos4.1/sparc
- sun/sunos4.1
- sun/sunos4/sparc
- sun/sunos4
- sun/sunos/sparc
- sun/sunos
- sun/sparc
- sun
- sunos4.1/sparc
- sunos4.1
- sunos4/sparc
- sunos4
- sunos/sparc
- sunos
- sparc
-
- Different machine architectures are conventionally subdirectories at
-the top level of the `sysdeps' directory tree. For example,
-`sysdeps/sparc' and `sysdeps/m68k'. These contain files specific to
-those machine architectures, but not specific to any particular
-operating system. There might be subdirectories for specializations of
-those architectures, such as `sysdeps/m68k/68020'. Code which is
-specific to the floating-point coprocessor used with a particular
-machine should go in `sysdeps/MACHINE/fpu'.
-
- There are a few directories at the top level of the `sysdeps'
-hierarchy that are not for particular machine architectures.
-
-`generic'
-`stub'
- As described above (*note Porting::.), these are the two
- subdirectories that every configuration implicitly uses after all
- others.
-
-`ieee754'
- This directory is for code using the IEEE 754 floating-point
- format, where the C type `float' is IEEE 754 single-precision
- format, and `double' is IEEE 754 double-precision format. Usually
- this directory is referred to in the `Implies' file in a machine
- architecture-specific directory, such as `m68k/Implies'.
-
-`posix'
- This directory contains implementations of things in the library in
- terms of POSIX.1 functions. This includes some of the POSIX.1
- functions themselves. Of course, POSIX.1 cannot be completely
- implemented in terms of itself, so a configuration using just
- `posix' cannot be complete.
-
-`unix'
- This is the directory for Unix-like things. *Note Porting to
- Unix::. `unix' implies `posix'. There are some special-purpose
- subdirectories of `unix':
-
- `unix/common'
- This directory is for things common to both BSD and System V
- release 4. Both `unix/bsd' and `unix/sysv/sysv4' imply
- `unix/common'.
-
- `unix/inet'
- This directory is for `socket' and related functions on Unix
- systems. The `inet' top-level subdirectory is enabled by
- `unix/inet/Subdirs'. `unix/common' implies `unix/inet'.
-
-`mach'
- This is the directory for things based on the Mach microkernel
- from CMU (including the GNU operating system). Other basic
- operating systems (VMS, for example) would have their own
- directories at the top level of the `sysdeps' hierarchy, parallel
- to `unix' and `mach'.
-
-Porting the GNU C Library to Unix Systems
------------------------------------------
-
- Most Unix systems are fundamentally very similar. There are
-variations between different machines, and variations in what
-facilities are provided by the kernel. But the interface to the
-operating system facilities is, for the most part, pretty uniform and
-simple.
-
- The code for Unix systems is in the directory `unix', at the top
-level of the `sysdeps' hierarchy. This directory contains
-subdirectories (and subdirectory trees) for various Unix variants.
-
- The functions which are system calls in most Unix systems are
-implemented in assembly code in files in `sysdeps/unix'. These files
-are named with a suffix of `.S'; for example, `__open.S'. Files ending
-in `.S' are run through the C preprocessor before being fed to the
-assembler.
-
- These files all use a set of macros that should be defined in
-`sysdep.h'. The `sysdep.h' file in `sysdeps/unix' partially defines
-them; a `sysdep.h' file in another directory must finish defining them
-for the particular machine and operating system variant. See
-`sysdeps/unix/sysdep.h' and the machine-specific `sysdep.h'
-implementations to see what these macros are and what they should do.
-
- The system-specific makefile for the `unix' directory (that is, the
-file `sysdeps/unix/Makefile') gives rules to generate several files
-from the Unix system you are building the library on (which is assumed
-to be the target system you are building the library *for*). All the
-generated files are put in the directory where the object files are
-kept; they should not affect the source tree itself. The files
-generated are `ioctls.h', `errnos.h', `sys/param.h', and `errlist.c'
-(for the `stdio' section of the library).
-
-Contributors to the GNU C Library
-=================================