about summary refs log tree commit diff
path: root/manual
diff options
context:
space:
mode:
Diffstat (limited to 'manual')
-rw-r--r--manual/Makefile2
-rw-r--r--manual/install.texi227
-rw-r--r--manual/libc.texinfo2
3 files changed, 153 insertions, 78 deletions
diff --git a/manual/Makefile b/manual/Makefile
index 5db6a31f23..0652d4dea0 100644
--- a/manual/Makefile
+++ b/manual/Makefile
@@ -82,7 +82,7 @@ stamp-summary: summary.awk $(filter-out summary.texi, $(texis))
 # access to the documentation of the function, variables, and other
 # definitions.
 dir-add.info: xtract-typefun.awk $(texis)
-	(echo "INFO-DIR-SECTION GNU C library functions:";		\
+	(echo "INFO-DIR-SECTION GNU C library functions";		\
 	 echo "START-INFO-DIR-ENTRY";					\
 	 $(AWK) -f $^ | sort;						\
 	 echo "END-INFO-DIR-ENTRY") > $@.new
diff --git a/manual/install.texi b/manual/install.texi
index 3712643989..a68151852e 100644
--- a/manual/install.texi
+++ b/manual/install.texi
@@ -11,33 +11,42 @@ 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.
 
-Two components of GNU Libc are distributed as @dfn{add-on} bundles
-separate from the main distribution.  Unless you are doing an unusual
-installation, you should get them both.  Support for the @code{crypt}
-function is distributed separately because of US export restrictions.
-If you are outside the US or Canada, you must get @code{crypt} support
-from a site outside the US, such as @samp{ftp.ifi.uio.no}.
+Features can be added to GNU Libc via @dfn{add-on} bundles.  These are
+separate tarfiles which you unpack into the top level of the source
+tree.  Then you give @code{configure} the @samp{--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 @file{glibc-linuxthreads-@var{VERSION}.tar.gz}.
+Support for the @code{crypt} function is distributed separately because
+of United States export restrictions.  If you are outside the US or
+Canada, you must get @code{crypt} support from a site outside the US,
+such as @samp{ftp.ifi.uio.no}.
 @c Check this please someone:
 (Most non-US mirrors of @samp{ftp.gnu.org} will have it too.)  The file
-you need is @file{glibc-crypt-@var{VERSION}.tar.gz}.  Support for POSIX
-threads is maintained by someone else, so it's in a separate package.
-At the moment it is only available for Linux systems; this will change
-in the future.  Get it from the same place you got the main bundle; the
-file is @file{glibc-linuxthreads-@var{VERSION}.tar.gz}.  Both add-on
-bundles should be unpacked into the top level of the libc source tree.
+you need is @file{glibc-crypt-@var{VERSION}.tar.gz}.  
 
 You will need recent versions of several GNU tools: definitely GCC and
 GNU Make, and possibly others.  @xref{Tools for Compilation}, below.
 
 @menu
 * Configuring and compiling::   How to compile and test GNU libc.
+* Installation::                How to install it once you've got it compiled.
 * Tools for Compilation::       You'll need these first.
 * Supported Configurations::    What it runs on, what it doesn't.
+* Linux::                       Specific advice for Linux systems.
 * Reporting Bugs::              So they'll get fixed.
 @end menu
 
 @node Configuring and compiling
 @appendixsec Configuring and compiling GNU Libc
+@cindex configuring
+@cindex compiling
 
 GNU Libc cannot be compiled in the source directory.  You must create a
 separate directory for the object files.  This directory should be
@@ -54,14 +63,12 @@ $ ../glibc-2.1.0/configure @var{args...}
 
 @noindent
 @code{configure} takes many options, but you can get away with knowing
-only two: @samp{--enable-add-ons} and @samp{--prefix}.  The
-@samp{--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.  The
+only two: @samp{--prefix} and @samp{--enable-add-ons}.  The
 @code{--prefix} option tells configure where you want glibc installed.
-This defaults to @file{/usr/local}.  If you are installing glibc as your
-primary C library, give the option @samp{--prefix=/usr}, which will put
-components in @file{/usr} or @file{/} as appropriate.
+This defaults to @file{/usr/local}.  The @samp{--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 @var{CC} and @var{CFLAGS} variables in
 the environment when running @code{configure}.  @var{CC} selects the C
@@ -109,7 +116,6 @@ 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.)
 
-@c extra blank line makes it look better
 @item --without-fp
 Use this option if your computer lacks hardware floating-point support
 and your operating system does not emulate an FPU.
@@ -144,7 +150,6 @@ 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.
 
-@c another extra blank line
 @item --build=@var{build-system}
 @itemx --host=@var{host-system}
 These options are for cross-compiling.  If you give them both and
@@ -154,9 +159,16 @@ on @var{host-system}.  You'll probably need the @samp{--with-headers}
 option too, and you may have to override @var{configure}'s selection of
 the compiler and/or binutils.
 
-If you give just one of these, @code{configure} will get confused.  If
-@code{configure} doesn't correctly guess your system type for a native
-build, report that as a bug.
+If you give just @samp{--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 @code{i586-pc-linux-gnu} but you want
+to compile a library optimized for 386es, give
+@samp{--host=i386-pc-linux-gnu} or just @samp{--host=i386-linux}.  (A
+library compiled for a Pentium (@code{i586}) will still work on a 386,
+but it may be slower.)
+
+If you give just @samp{--build}, configure will get confused.
 @end table
 
 To build the library and related programs, type @code{make}.  This will
@@ -192,14 +204,57 @@ and test glibc as an unprivileged user.
 
 To format the @cite{GNU C Library Reference Manual} for printing, type
 @w{@code{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 @w{@code{make
+info}}, but it shouldn't be necessary.
+
+@node Installation
+@appendixsec Installing the C Library
+@cindex installing
 
 To install the library and its header files, and the Info files of the
 manual, type @code{make install}.  This will build things if necessary,
-before installing them.  If you want to install the files in a different
-place than the one specified at configuration time you can specify a
-value for the Makefile variable @code{install_root} on the command line.
-This is useful to create chroot'ed environment or to prepare binary
-releases.@refill
+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,
+@samp{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
+@file{/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
+(@samp{-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 (@file{/usr/lib/gcc-lib/@var{TARGET}/@var{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 @code{install_root} variable on the command line for
+@samp{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, @code{nscd} and @code{utmpd}, which you
+may or may not want to run.  @code{nscd} caches name service lookups; it
+can dramatically improve performance with NIS+, and may help with DNS as
+well.  @code{utmpd} allows programs that use the old format for the
+@file{utmp} file to coexist with new programs.  For more information see
+the files @file{nscd/README} and @file{login/README.utmpd}.
+
+One auxiliary program, @file{/usr/libexec/pt_chown}, is installed setuid
+@code{root}.  This program is invoked by the @code{grantpt} function; it
+sets the permissions on a pseudoterminal so it can be used by the
+calling process.  This means programs like @code{xterm} and
+@code{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 @code{devptsfs} or @code{devfs} filesystems providing
+pty slaves, you don't need this program; otherwise you do.  The source
+for @file{pt_chown} is in @file{login/programs/pt_chown.c}.
 
 @node Tools for Compilation
 @appendixsec Recommended Tools for Compilation
@@ -227,7 +282,9 @@ EGCS 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.
+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.)
 
 @item
 GNU @code{binutils} 2.8.1.0.23, 2.9.1, or 2.9.0.15
@@ -247,21 +304,13 @@ GNU @code{texinfo} 3.11
 To correctly translate and install the Texinfo documentation you need
 this version of the @code{texinfo} package.  Earlier versions do not
 understand all the tags used in the document, and the installation
-mechanisms for the info files is not present or works differently.
-
-On some Debian Linux based systems the @code{install-info} program
-supplied with the system works differently from the one we expect.  You
-must therefore run @code{make install} like this:
-
-@smallexample
-make INSTALL_INFO=/path/to/GNU/install-info install
-@end smallexample
+mechanism for the info files is not present or works differently.
 
 @item
 GNU @code{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; GNU awk 3.0 and
+work with any POSIX-compliant awk implementation; @code{gawk} 3.0 and
 @code{mawk} 1.3 are known to work.
 
 @item
@@ -350,25 +399,53 @@ Each case of @samp{i@var{x}86} can be @samp{i386}, @samp{i486},
 @samp{i586}, or @samp{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.
-
-While no other configurations are supported, there are handy aliases for
-these few.  (These aliases work in other GNU software as well.)
-
-@smallexample
-decstation
-hp320-bsd4.3 hp300bsd
-i486-gnu
-i586-linux
-i386-sco
-i386-sco3.2v4
-i386-sequent-dynix
-i386-svr4
-news
-sun3-sunos4.@var{n} sun3
-sun4-solaris2.@var{n} sun4-sunos5.@var{n}
-sun4-sunos4.@var{n} sun4
-@end smallexample
+available on all of them.  If you want the library to use instructions
+only available on newer processors, give GCC the appropriate @samp{-m}
+switches via @var{CFLAGS}.
+
+@node Linux
+@appendixsec Specific advice for Linux systems
+@cindex upgrading from libc5
+@cindex kernel header files
+
+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 @file{/usr/src/linux-dev}.  In that
+directory, run @samp{make config} and accept all the defaults.  Then
+configure glibc with the option
+@samp{--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
+@samp{make config} as above.  Then rename or delete @file{/usr/include},
+create a new @file{/usr/include}, and make the usual symbolic links of
+@file{/usr/include/linux} and @file{/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 @file{/usr/include/net} and @file{/usr/include/scsi} should
+@strong{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
+@file{/lib} and some in @file{/usr/lib}.  This is handled automatically
+if you configure glibc with @samp{--prefix=/usr}.  If you set some other
+prefix or allow it to default to @file{/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
+@url{http://www.imaxx.net/~thrytis/glibc} for details.
+
+You cannot use @code{nscd} with 2.0 kernels, due to bugs in the
+kernel-side thread support.  @code{nscd} happens to hit these bugs
+particularly hard, but you might have problems with any threaded
+program.
 
 @node Reporting Bugs
 @appendixsec Reporting Bugs
@@ -385,7 +462,13 @@ 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.
+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 (@pxref{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
@@ -393,22 +476,14 @@ 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.
-When reporting a bug, send your test case, the results you got, the
-results you expected, what you think the problem might be (if you've
-thought of anything), your system type, and the version of the GNU C
-library which you are using.  Also include the files
-@file{config.status} and @file{config.make} which are created by running
-@file{configure}; they will be in whatever directory was current when
-you ran @file{configure}.
-
-If you think you have found some way in which the GNU C library does not
-conform to the ISO and POSIX standards (@pxref{Standards and
-Portability}), that is definitely a bug.  Report it!@refill
-
-Send bug reports to the Internet address @email{bug-glibc@@gnu.org}
-using the @code{glibcbug} script which is installed by the GNU C
-library.  If you have other problems with installation or use, please
-report those as well.@refill
+Do this using the @code{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).
+@code{glibcbug} will insert the configuration information we need to
+see, and ship the report off to @email{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
diff --git a/manual/libc.texinfo b/manual/libc.texinfo
index b9d3d7a6d9..0beec66fd6 100644
--- a/manual/libc.texinfo
+++ b/manual/libc.texinfo
@@ -5,7 +5,7 @@
 @setchapternewpage odd
 
 @comment Tell install-info what to do.
-@dircategory GNU libraries:
+@dircategory GNU libraries
 @direntry
 * Libc: (libc).                 C library.
 @end direntry