Use MAP_ANON instead of MAP_ANONYMOUS.
[kopensolaris-gnu/glibc.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 369e50e..276750a 100644 (file)
--- a/INSTALL
+++ b/INSTALL
-Library Maintenance
-*******************
-
-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 a "special" subdirectory called `generic'.  It is
-always implicitly appended to the list of subdirectories, so you
-needn't put it in an `Implies' file, and you should not create any
-subdirectories under it intended to be new specific categories.
-`generic' serves two purposes.  First, the makefiles do not bother to
-look for a system-dependent version of a file that's not in `generic'.
-This means that any system-dependent source file must have an analogue
-in `generic', even if the routines defined by that file are not
-implemented on other platforms.  Second. the `generic' version of a
-system-dependent file is used if the makefiles do not find a version
-specific to the system you're compiling for.
-
-   If it is possible to implement the routines in a `generic' file in
-machine-independent C, using only other machine-independent functions in
-the C library, then you should do so.  Otherwise, make them stubs.  A
-"stub" function is a function which cannot be implemented on a
-particular machine or operating system.  Stub functions always return an
-error, and set `errno' to `ENOSYS' (Function not implemented).  *Note
-Error Reporting::.  If you define a stub function, you must place the
-statement `stub_warning(FUNCTION)', where FUNCTION is the name of your
-function, after its definition; also, you must include the file
-`<stub-tag.h>' into your file.  This causes the function to be listed
-in the installed `<gnu/stubs.h>', and makes GNU ld warn when the
-function is used.
-
-   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'
-directory), 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 `Linux', the
-base operating system is `unix/sysv'.  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
-`i686-linux-gnu' results in `unix/sysv/linux/i386/i686'.  `configure'
-then tries removing each element of the list in turn, so
-`unix/sysv/linux' and `unix/sysv' 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 `irix6.2' and `irix6.3' 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 `i686-linux-gnu' (with the `crypt' and
-`linuxthreads' add-on):
-
-     sysdeps/i386/elf
-     crypt/sysdeps/unix
-     linuxthreads/sysdeps/unix/sysv/linux
-     linuxthreads/sysdeps/pthread
-     linuxthreads/sysdeps/unix/sysv
-     linuxthreads/sysdeps/unix
-     linuxthreads/sysdeps/i386/i686
-     linuxthreads/sysdeps/i386
-     linuxthreads/sysdeps/pthread/no-cmpxchg
-     sysdeps/unix/sysv/linux/i386
-     sysdeps/unix/sysv/linux
-     sysdeps/gnu
-     sysdeps/unix/common
-     sysdeps/unix/mman
-     sysdeps/unix/inet
-     sysdeps/unix/sysv/i386/i686
-     sysdeps/unix/sysv/i386
-     sysdeps/unix/sysv
-     sysdeps/unix/i386
-     sysdeps/unix
-     sysdeps/posix
-     sysdeps/i386/i686
-     sysdeps/i386/i486
-     sysdeps/libm-i387/i686
-     sysdeps/i386/fpu
-     sysdeps/libm-i387
-     sysdeps/i386
-     sysdeps/wordsize-32
-     sysdeps/ieee754
-     sysdeps/libm-ieee754
-     sysdeps/generic
-
-   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'
-     As described above (*note Porting::.), this is the subdirectory
-     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'.
-
-`libm-ieee754'
-     This directory contains an implementation of a mathematical library
-     usable on platforms which use IEEE 754 conformant floating-point
-     arithmetic.
-
-`libm-i387'
-     This is a special case.  Ideally the code should be in
-     `sysdeps/i386/fpu' but for various reasons it is kept aside.
-
-`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.  `unix/inet/Subdirs' enables the `inet' top-level
-          subdirectory.  `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, which is generated automatically from
-specifications in files named `syscalls.list'.  There are several such
-files, one in `sysdeps/unix' and others in its subdirectories.  Some
-special system calls are implemented in files that are named with a
-suffix of `.S'; for example, `_exit.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
-(`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).
+Installing the GNU C Library
+****************************
+
+   Before you do anything else, you should read the file `FAQ' found at
+the top level of the source tree.  This file answers common questions
+and describes problems you may experience with compilation and
+installation.  It is updated more frequently than this manual.
+
+   Features can be added to GNU Libc via "add-on" bundles.  These are
+separate tarfiles which you unpack into the top level of the source
+tree.  Then you give `configure' the `--enable-add-ons' option to
+activate them, and they will be compiled into the library.  As of the
+2.1 release, two important components of glibc are distributed as
+"official" add-ons.  Unless you are doing an unusual installation, you
+should get them both.
+
+   Support for POSIX threads is maintained by someone else, so it's in a
+separate package.  It is only available for Linux systems, but this will
+change in the future.  Get it from the same place you got the main
+bundle; the file is `glibc-linuxthreads-VERSION.tar.gz'.  Support for
+the `crypt' function is distributed separately because of United States
+export restrictions.  If you are outside the US or Canada, you must get
+`crypt' support from a site outside the US, such as `ftp.ifi.uio.no'.
+(Most non-US mirrors of `ftp.gnu.org' will have it too.)  The file you
+need is `glibc-crypt-VERSION.tar.gz'.
+
+   You will need recent versions of several GNU tools: definitely GCC
+and GNU Make, and possibly others.  *Note Tools for Compilation::,
+below.
+
+Configuring and compiling GNU Libc
+==================================
+
+   GNU Libc cannot be compiled in the source directory.  You must
+create a separate directory for the object files.  This directory
+should be outside the source tree.  For example, if you have unpacked
+the glibc sources in `/src/gnu/glibc-2.1.0', create a directory
+`/src/gnu/glibc-build' to put the object files in.
+
+   From your object directory, run the shell script `configure' found
+at the top level of the source tree.  In the scenario above, you'd type
+
+     $ ../glibc-2.1.0/configure ARGS...
+
+`configure' takes many options, but you can get away with knowing only
+two: `--prefix' and `--enable-add-ons'.  The `--prefix' option tells
+configure where you want glibc installed.  This defaults to
+`/usr/local'.  The `--enable-add-ons' option tells configure to use all
+the add-on bundles it finds in the source directory.  Since important
+functionality is provided in add-ons, you should always give this
+option.
+
+   It may also be useful to set the CC and CFLAGS variables in the
+environment when running `configure'.  CC selects the C compiler that
+will be used, and CFLAGS sets optimization options for the compiler.
+
+   Here are all the useful options known by `configure':
+
+`--prefix=DIRECTORY'
+     Install machine-independent data files in subdirectories of
+     `DIRECTORY'.  The default is to install in `/usr/local'.
+
+`--exec-prefix=DIRECTORY'
+     Install the library and other machine-dependent files in
+     subdirectories of `DIRECTORY'.  The default is to the `--prefix'
+     directory if that option is given, or `/usr/local' otherwise.
+
+`--with-headers=DIRECTORY'
+     Look for kernel header files in DIRECTORY, not `/usr/include'.
+     Glibc needs information from the kernel's private header files.
+     It will normally look in `/usr/include' for them, but if you give
+     this option, it will look in DIRECTORY instead.
+
+     This option is primarily of use on a system where the headers in
+     `/usr/include' come from an older version of glibc.  Conflicts can
+     occasionally happen in this case.  Note that Linux libc5 qualifies
+     as an older version of glibc.  You can also use this option if you
+     want to compile glibc with a newer set of kernel headers than the
+     ones found in `/usr/include'.
+
+`--enable-add-ons[=LIST]'
+     Enable add-on packages in your source tree.  If this option is
+     given with no list, it enables all the add-on packages it finds.
+     If you do not wish to use some add-on package that you have
+     present in your source tree, give this option a list of the
+     add-ons that you *do* want used, like this:
+     `--enable-add-ons=crypt,linuxthreads'
+
+`--with-binutils=DIRECTORY'
+     Use the binutils (assembler and linker) in `DIRECTORY', not the
+     ones the C compiler would default to.  You could use this option if
+     the default binutils on your system cannot deal with all the
+     constructs in the GNU C library.  (`configure' will detect the
+     problem and suppress these constructs, so the library will still
+     be usable, but functionality may be lost--for example, you can not
+     build a shared libc with old binutils.)
+
+`--without-fp'
+     Use this option if your computer lacks hardware floating-point
+     support and your operating system does not emulate an FPU.
+
+`--disable-static'
+     Don't build static libraries.  Static libraries aren't that useful
+     these days, but we recommend you build them in case you need them.
+
+`--disable-shared'
+     Don't build shared libraries even if we could.  Not all systems
+     support shared libraries; you need ELF support and (currently) the
+     GNU linker.
+
+`--disable-profile'
+     Don't build libraries with profiling information.  You may want to
+     use this option if you don't plan to do profiling.
+
+`--enable-omitfp'
+     Use maximum optimization for the normal (static and shared)
+     libraries, and compile separate static libraries with debugging
+     information and no optimisation.  We recommend against this.  The
+     extra optimization doesn't gain you much, it may provoke compiler
+     bugs, and you won't be able to trace bugs through the C library.
+
+`--disable-versioning'
+     Don't compile the shared libraries with symbol version information.
+     Doing this will make the library that's built incompatible with old
+     binaries, so it's not recommended.
+
+`--enable-static-nss'
+     Compile static versions of the NSS (Name Service Switch) libraries.
+     This is not recommended because it defeats the purpose of NSS; a
+     program linked statically with the NSS libraries cannot be
+     dynamically reconfigured to use a different name database.
+
+`--build=BUILD-SYSTEM'
+`--host=HOST-SYSTEM'
+     These options are for cross-compiling.  If you give them both and
+     BUILD-SYSTEM is different from HOST-SYSTEM, `configure' will
+     prepare to cross-compile glibc from BUILD-SYSTEM to be used on
+     HOST-SYSTEM.  You'll probably need the `--with-headers' option
+     too, and you may have to override CONFIGURE's selection of the
+     compiler and/or binutils.
+
+     If you give just `--host', configure will prepare for a native
+     compile but use what you say instead of guessing what your system
+     is.  This is most useful to change the CPU submodel.  For example,
+     if configure guesses your machine as `i586-pc-linux-gnu' but you
+     want to compile a library optimized for 386es, give
+     `--host=i386-pc-linux-gnu' or just `--host=i386-linux'.  (A
+     library compiled for a Pentium (`i586') will still work on a 386,
+     but it may be slower.)
+
+     If you give just `--build', configure will get confused.
+
+   To build the library and related programs, type `make'.  This will
+produce a lot of output, some of which may look like errors from `make'
+but isn't.  Look for error messages from `make' containing `***'.
+Those indicate that something is really wrong.
+
+   The compilation process takes several hours even on fast hardware.
+Expect at least two hours for the default configuration on i586 for
+Linux.  For Hurd times are much longer.  Except for EGCS 1.1 (and later
+versions of EGCS), all supported versions of GCC have a problem which
+causes them to take several minutes to compile certain files in the
+iconvdata directory.  Do not panic if the compiler appears to hang.
+
+   If you want to run a parallel make, you can't just give `make' the
+`-j' option, because it won't be passed down to the sub-makes.
+Instead, edit the generated `Makefile' and uncomment the line
+
+     # PARALLELMFLAGS = -j 4
+
+You can change the `4' to some other number as appropriate for your
+system.
+
+   To build and run some test programs which exercise some of the
+library facilities, type `make check'.  This should complete
+successfully; if it doesn't, do not use the built library, and report a
+bug.  *Note Reporting Bugs::, for how to do that.  Note that some of
+the tests assume they are not being run by `root'.  We recommend you
+compile and test glibc as an unprivileged user.
+
+   To format the `GNU C Library Reference Manual' for printing, type
+`make dvi'.  You need a working TeX installation to do this.  The
+distribution already includes the on-line formatted version of the
+manual, as Info files.  You can regenerate those with `make info', but
+it shouldn't be necessary.
+
+Installing the C Library
+========================
+
+   To install the library and its header files, and the Info files of
+the manual, type `make install'.  This will build things if necessary,
+before installing them.  Don't rely on that; compile everything first.
+If you are installing glibc as your primary C library, we recommend you
+shut the system down to single-user mode first, and reboot afterward.
+This minimizes the risk of breaking things when the library changes out
+from underneath.
+
+   If you are upgrading from a previous installation of glibc 2.0 or
+2.1, `make install' will do the entire job.  If you're upgrading from
+Linux libc5 or some other C library, you need to rename the old
+`/usr/include' directory out of the way first, or you will end up with
+a mixture of header files from both libraries, and you won't be able to
+compile anything.  You may also need to reconfigure GCC to work with
+the new library.  The easiest way to do that is to figure out the
+compiler switches to make it work again
+(`-Wl,-dynamic-linker=/lib/ld-linux.so.2' should work on Linux systems)
+and use them to recompile gcc.  You can also edit the specs file
+(`/usr/lib/gcc-lib/TARGET/VERSION/specs'), but that is a bit of a black
+art.
+
+   You can install glibc somewhere other than where you configured it
+to go by setting the `install_root' variable on the command line for
+`make install'.  The value of this variable is prepended to all the
+paths for installation.  This is useful when setting up a chroot
+environment or preparing a binary distribution.
+
+   Glibc 2.1 includes two daemons, `nscd' and `utmpd', which you may or
+may not want to run.  `nscd' caches name service lookups; it can
+dramatically improve performance with NIS+, and may help with DNS as
+well.  `utmpd' allows programs that use the old format for the `utmp'
+file to coexist with new programs.  For more information see the files
+`nscd/README' and `login/README.utmpd'.
+
+   One auxiliary program, `/usr/libexec/pt_chown', is installed setuid
+`root'.  This program is invoked by the `grantpt' function; it sets the
+permissions on a pseudoterminal so it can be used by the calling
+process.  This means programs like `xterm' and `screen' do not have to
+be setuid to get a pty.  (There may be other reasons why they need
+privileges.)  If you are using a 2.1 Linux kernel with the `devptsfs'
+or `devfs' filesystems providing pty slaves, you don't need this
+program; otherwise you do.  The source for `pt_chown' is in
+`login/programs/pt_chown.c'.
+
+Recommended Tools for Compilation
+=================================
+
+   We recommend installing the following GNU tools before attempting to
+build the GNU C library:
+
+   * GNU `make' 3.75
+
+     You need the latest version of GNU `make'.  Modifying the GNU C
+     Library to work with other `make' programs would be so hard that we
+     recommend you port GNU `make' instead.  *Really.*  We recommend
+     version GNU `make' version 3.75 or 3.77.  All earlier versions
+     have severe bugs or lack features. Version 3.76 is known to have
+     bugs which only show up in big projects like GNU `libc'.  Version
+     3.76.1 seems OK but some people have reported problems.
+
+   * EGCS 1.1.1, 1.1 or 1.0.3
+
+     The GNU C library can only be compiled with the GNU C compiler
+     family.  We recommend EGCS 1.0.3 or higher.  GCC 2.8.1 and older
+     versions of EGCS may have problems, particularly on non-Intel
+     architectures.  GCC 2.7.x has catastrophic bugs and cannot be used
+     at all.  (You can use GCC 2.7.x to compile programs that use GNU
+     libc, but you may have problems, particularly with the math
+     functions.)
+
+     On Alpha machines you need at least EGCS 1.1.1.  Earlier versions
+     don't work reliably.
+
+     For PPC you might need some patches even on top of the last EGCS
+     version.  See the FAQ.
+
+   * GNU `binutils' 2.9.1, or 2.9.1.0.16
+
+     You must use GNU binutils (as and ld) if you want to build a shared
+     library.  Even if you don't, we recommend you use them anyway.  No
+     one has tested compilation with non-GNU binutils in a long time.
+
+     The quality of binutils releases has varied a bit recently.  The
+     bugs are in obscure features, but glibc uses quite a few of those.
+     2.9.1 and 2.9.1.0.16 are known to work.  Versions after 2.8.1.0.23
+     may or may not work.  Older versions definitely don't.  2.9.1.0.16
+     is required on some platforms, like PPC and Arm.
+
+     For PPC you might need some patches even on top of the last
+     binutils version.  See the FAQ.
+
+   * GNU `texinfo' 3.11
+
+     To correctly translate and install the Texinfo documentation you
+     need this version of the `texinfo' package.  Earlier versions do
+     not understand all the tags used in the document, and the
+     installation mechanism for the info files is not present or works
+     differently.
+
+   * GNU `awk' 3.0, or some other POSIX awk
+
+     Awk is used in several places to generate files.  The scripts
+     should work with any POSIX-compliant awk implementation; `gawk'
+     3.0 and `mawk' 1.3 are known to work.
+
+   * Perl 5
+
+     Perl is not required, but it is used if present to test the
+     installation.  We may decide to use it elsewhere in the future.
+
+If you change any of the `configure.in' files you will also need
+
+   * GNU `autoconf' 2.12
+
+and if you change any of the message translation files you will need
+
+   * GNU `gettext' 0.10.35 or later
+
+You may also need these packages if you upgrade your source tree using
+patches, although we try to avoid this.
+
+Supported Configurations
+========================
+
+   The GNU C Library currently supports configurations that match the
+following patterns:
+
+     alpha-*-linux
+     arm-*-linux
+     arm-*-linuxaout
+     arm-*-none
+     iX86-*-gnu
+     iX86-*-linux
+     m68k-*-linux
+     powerpc-*-linux
+     sparc-*-linux
+     sparc64-*-linux
+
+   Former releases of this library (version 1.09.1 and perhaps earlier
+versions) used to run on the following configurations:
+
+     alpha-dec-osf1
+     alpha-*-linuxecoff
+     iX86-*-bsd4.3
+     iX86-*-isc2.2
+     iX86-*-isc3.N
+     iX86-*-sco3.2
+     iX86-*-sco3.2v4
+     iX86-*-sysv
+     iX86-*-sysv4
+     iX86-force_cpu386-none
+     iX86-sequent-bsd
+     i960-nindy960-none
+     m68k-hp-bsd4.3
+     m68k-mvme135-none
+     m68k-mvme136-none
+     m68k-sony-newsos3
+     m68k-sony-newsos4
+     m68k-sun-sunos4.N
+     mips-dec-ultrix4.N
+     mips-sgi-irix4.N
+     sparc-sun-solaris2.N
+     sparc-sun-sunos4.N
+
+   Since no one has volunteered to test and fix these configurations,
+they are not supported at the moment.  They probably don't compile;
+they definitely don't work anymore.  Porting the library is not hard.
+If you are interested in doing a port, please contact the glibc
+maintainers by sending electronic mail to <bug-glibc@gnu.org>.
+
+   Each case of `iX86' can be `i386', `i486', `i586', or `i686'.  All
+of those configurations produce a library that can run on any of these
+processors.  The library will be optimized for the specified processor,
+but will not use instructions not available on all of them.  If you
+want the library to use instructions only available on newer
+processors, give GCC the appropriate `-m' switches via CFLAGS.
+
+Specific advice for Linux systems
+=================================
+
+   If you are installing GNU libc on a Linux system, you need to have
+the header files from a development kernel around for reference.  You
+do not need to use the development kernel, just have its headers where
+glibc can get at them.  The easiest way to do this is to unpack a
+development kernel in a directory such as `/usr/src/linux-dev'.  In that
+directory, run `make config' and accept all the defaults.  Then
+configure glibc with the option
+`--with-headers=/usr/src/linux-dev/include'.  Use the latest
+development kernel you can get your hands on.
+
+   An alternate tactic is to unpack the development kernel and run
+`make config' as above.  Then rename or delete `/usr/include', create a
+new `/usr/include', and make the usual symbolic links of
+`/usr/include/linux' and `/usr/include/asm' into the development kernel
+sources.  You can then configure glibc with no special options.  This
+tactic is recommended if you are upgrading from libc5, since you need
+to get rid of the old header files anyway.
+
+   Note that `/usr/include/net' and `/usr/include/scsi' should *not* be
+symlinks into the kernel sources.  GNU libc provides its own versions
+of these files.
+
+   Linux expects some components of the libc installation to be in
+`/lib' and some in `/usr/lib'.  This is handled automatically if you
+configure glibc with `--prefix=/usr'.  If you set some other prefix or
+allow it to default to `/usr/local', then all the components are
+installed there.
+
+   If you are upgrading from libc5, you need to recompile every shared
+library on your system against the new library for the sake of new code,
+but keep the old libraries around for old binaries to use.  This is
+complicated and difficult.  Consult the Glibc2 HOWTO at
+`http://www.imaxx.net/~thrytis/glibc' for details.
+
+   You cannot use `nscd' with 2.0 kernels, due to bugs in the
+kernel-side thread support.  `nscd' happens to hit these bugs
+particularly hard, but you might have problems with any threaded
+program.
+
+Reporting Bugs
+==============
+
+   There are probably bugs in the GNU C library.  There are certainly
+errors and omissions in this manual.  If you report them, they will get
+fixed.  If you don't, no one will ever know about them and they will
+remain unfixed for all eternity, if not longer.
+
+   To report a bug, first you must find it.  Hopefully, this will be the
+hard part.  Once you've found a bug, make sure it's really a bug.  A
+good way to do this is to see if the GNU C library behaves the same way
+some other C library does.  If so, probably you are wrong and the
+libraries are right (but not necessarily).  If not, one of the libraries
+is probably wrong.  It might not be the GNU library.  Many historical
+Unix C libraries permit things that we don't, such as closing a file
+twice.
+
+   If you think you have found some way in which the GNU C library does
+not conform to the ISO and POSIX standards (*note Standards and
+Portability::.), that is definitely a bug.  Report it!
+
+   Once you're sure you've found a bug, try to narrow it down to the
+smallest test case that reproduces the problem.  In the case of a C
+library, you really only need to narrow it down to one library function
+call, if possible.  This should not be too difficult.
+
+   The final step when you have a simple test case is to report the bug.
+Do this using the `glibcbug' script.  It is installed with libc, or if
+you haven't installed it, will be in your build directory.  Send your
+test case, the results you got, the results you expected, and what you
+think the problem might be (if you've thought of anything).  `glibcbug'
+will insert the configuration information we need to see, and ship the
+report off to <bug-glibc@gnu.org>.  Don't send a message there
+directly; it is fed to a program that expects mail to be formatted in a
+particular way.  Use the script.
+
+   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@gnu.org>.  If you refer to specific sections
+when reporting on the manual, please include the section names for
+easier identification.