aboutsummaryrefslogtreecommitdiff
path: root/manual/maint.texi
diff options
context:
space:
mode:
Diffstat (limited to 'manual/maint.texi')
-rw-r--r--manual/maint.texi966
1 files changed, 966 insertions, 0 deletions
diff --git a/manual/maint.texi b/manual/maint.texi
new file mode 100644
index 0000000..0d29d80
--- /dev/null
+++ b/manual/maint.texi
@@ -0,0 +1,966 @@
+@c \input /gd/gnu/doc/texinfo
+@c This is for making the `INSTALL' file for the distribution.
+@c Makeinfo ignores it when processing the file from the include.
+@setfilename INSTALL
+
+@node Maintenance, Copying, Library Summary, Top
+@appendix Library Maintenance
+
+@menu
+* Installation:: How to configure, compile and
+ install the GNU C library.
+* Reporting Bugs:: How to report bugs (if you want to
+ get them fixed) and other troubles
+ you may have with the GNU C library.
+* Source Layout:: How to add new functions or header files
+ to the GNU C library.
+* Porting:: How to port the GNU C library to
+ a new machine or operating system.
+* Contributors:: Contributors to the GNU C Library.
+@end menu
+
+@node Installation
+@appendixsec How to Install the GNU C Library
+@cindex installing the library
+
+Installation of the GNU C library is relatively simple.
+
+You need the latest version of GNU @code{make}. Modifying the GNU C
+Library to work with other @code{make} programs would be so hard that we
+recommend you port GNU @code{make} instead. @strong{Really.}@refill
+
+To configure the GNU C library for your system, run the shell script
+@file{configure} with @code{sh}. Use an argument which is the
+conventional GNU name for your system configuration---for example,
+@samp{sparc-sun-sunos4.1}, for a Sun 4 running Sunos 4.1.
+@xref{Installation, Installation, Installing GNU CC, gcc.info, Using and
+Porting GNU CC}, for a full description of standard GNU configuration
+names. If you omit the configuration name, @file{configure} will try to
+guess one for you by inspecting the system it is running on. It may or
+may not be able to come up with a guess, and the its guess might be
+wrong. @file{configure} will tell you the canonical name of the chosen
+configuration before proceeding.
+
+The GNU C Library currently supports configurations that match the
+following patterns:
+
+@smallexample
+alpha-dec-osf1
+i386-@var{anything}-bsd4.3
+i386-@var{anything}-gnu
+i386-@var{anything}-isc2.2
+i386-@var{anything}-isc3.@var{n}
+i386-@var{anything}-sco3.2
+i386-@var{anything}-sco3.2v4
+i386-@var{anything}-sysv
+i386-@var{anything}-sysv4
+i386-force_cpu386-none
+i386-sequent-bsd
+i960-nindy960-none
+m68k-hp-bsd4.3
+m68k-mvme135-none
+m68k-mvme136-none
+m68k-sony-newsos3
+m68k-sony-newsos4
+m68k-sun-sunos4.@var{n}
+mips-dec-ultrix4.@var{n}
+mips-sgi-irix4.@var{n}
+sparc-sun-solaris2.@var{n}
+sparc-sun-sunos4.@var{n}
+@end smallexample
+
+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
+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
+
+Here are some options that you should specify (if appropriate) when
+you run @code{configure}:
+
+@table @samp
+@item --with-gnu-ld
+Use this option if you plan to use GNU @code{ld} to link programs with
+the GNU C Library. (We strongly recommend that you do.) This option
+enables use of features that exist only in GNU @code{ld}; so if you
+configure for GNU @code{ld} you must use GNU @code{ld} @emph{every time}
+you link with the GNU C Library, and when building it.
+
+@item --with-gnu-as
+Use this option if you plan to use the GNU assembler, @code{gas}, when
+building the GNU C Library. On some systems, the library may not build
+properly if you do @emph{not} use @code{gas}.
+
+@c extra blank line makes it look better
+@item --nfp
+
+Use this option if your computer lacks hardware floating point support.
+
+@item --prefix=@var{directory}
+Install machine-independent data files in subdirectories of
+@file{@var{directory}}. (You can also set this in @file{configparms};
+see below.)
+
+@item --exec-prefix=@var{directory}
+Install the library and other machine-dependent files in subdirectories
+of @file{@var{directory}}. (You can also set this in
+@file{configparms}; see below.)
+@end table
+
+The simplest way to run @code{configure} is to do it in the directory
+that contains the library sources. This prepares to build the library
+in that very directory.
+
+You can prepare to build the library in some other directory by going
+to that other directory to run @code{configure}. In order to run
+configure, you will have to specify a directory for it, like this:
+
+@smallexample
+mkdir sun4
+cd sun4
+../configure sparc-sun-sunos4.1
+@end smallexample
+
+@noindent
+@code{configure} looks for the sources in whatever directory you
+specified for finding @code{configure} itself. It does not matter where
+in the file system the source and build directories are---as long as you
+specify the source directory when you run @code{configure}, you will get
+the proper results.
+
+This feature lets you keep sources and binaries in different
+directories, and that makes it easy to build the library for several
+different machines from the same set of sources. Simply create a
+build directory for each target machine, and run @code{configure} in
+that directory specifying the target machine's configuration name.
+
+The library has a number of special-purpose configuration parameters.
+These are defined in the file @file{Makeconfig}; see the comments in
+that file for the details.
+
+But don't edit the file @file{Makeconfig} yourself---instead, create a
+file @file{configparms} in the directory where you are building the
+library, and define in that file the parameters you want to specify.
+@file{configparms} should @strong{not} be an edited copy of
+@file{Makeconfig}; specify only the parameters that you want to
+override. To see how to set these parameters, find the section of
+@file{Makeconfig} that says ``These are the configuration variables.''
+Then for each parameter that you want to change, copy the definition
+from @file{Makeconfig} to your new @file{configparms} file, and change
+the value as appropriate for your system.
+
+It is easy to configure the GNU C library for cross-compilation by
+setting a few variables in @file{configparms}. Set @code{CC} to the
+cross-compiler for the target you configured the library for; it is
+important to use this same @code{CC} value when running
+@code{configure}, like this: @samp{CC=@var{target}-gcc configure
+@var{target}}. Set @code{BUILD_CC} to the compiler to use for for
+programs run on the build system as part of compiling the library. You
+may need to set @code{AR} and @code{RANLIB} to cross-compiling versions
+of @code{ar} and @code{ranlib} if the native tools are not configured to
+work with object files for the target you configured for.
+
+Some of the machine-dependent code for some machines uses extensions in
+the GNU C compiler, so you may need to compile the library with GCC.
+(In fact, all of the existing complete ports require GCC.)
+
+The current release of the C library contains some header files that the
+compiler normally provides: @file{stddef.h}, @file{stdarg.h}, and
+several files with names of the form @file{va-@var{machine}.h}. The
+versions of these files that came with older releases of GCC do not work
+properly with the GNU C library. The @file{stddef.h} file in release
+2.2 and later of GCC is correct. If you have release 2.2 or later of
+GCC, use its version of @file{stddef.h} instead of the C library's. To
+do this, put the line @w{@samp{override stddef.h =}} in
+@file{configparms}. The other files are corrected in release 2.3 and
+later of GCC. @file{configure} will automatically detect whether the
+installed @file{stdarg.h} and @file{va-@var{machine}.h} files are
+compatible with the C library, and use its own if not.
+
+There is a potential problem with the @code{size_t} type and versions of
+GCC prior to release 2.4. ANSI C requires that @code{size_t} always be
+an unsigned type. For compatibility with existing systems' header
+files, GCC defines @code{size_t} in @file{stddef.h} to be whatever type
+the system's @file{sys/types.h} defines it to be. Most Unix systems
+that define @code{size_t} in @file{sys/types.h}, define it to be a
+signed type. Some code in the library depends on @code{size_t} being an
+unsigned type, and will not work correctly if it is signed.
+
+The GNU C library code which expects @code{size_t} to be unsigned is
+correct. The definition of @code{size_t} as a signed type is incorrect.
+Versions 2.4 and later of GCC always define @code{size_t} as an unsigned
+type, and GCC's @file{fixincludes} script massages the system's
+@file{sys/types.h} so as not to conflict with this.
+
+In the meantime, we work around this problem by telling GCC explicitly
+to use an unsigned type for @code{size_t} when compiling the GNU C
+library. @file{configure} will automatically detect what type GCC uses
+for @code{size_t} arrange to override it if necessary.
+
+To build the library, type @code{make lib}. This will produce a lot of
+output, some of which looks like errors from @code{make} (but isn't).
+Look for error messages from @code{make} containing @samp{***}. Those
+indicate that something is really wrong.
+
+To build and run some test programs which exercise some of the library
+facilities, type @code{make tests}. This will produce several files
+with names like @file{@var{program}.out}.
+
+To format the @cite{GNU C Library Reference Manual} for printing, type
+@w{@code{make dvi}}. To format the Info version of the manual for on
+line reading with @kbd{C-h i} in Emacs or with the @code{info} program,
+type @w{@code{make info}}.
+
+To install the library and its header files, and the Info files of the
+manual, type @code{make install}, after setting the installation
+directories in @file{configparms}. This will build things if necessary,
+before installing them.@refill
+
+@node Reporting Bugs
+@appendixsec Reporting Bugs
+@cindex reporting bugs
+@cindex bugs, reporting
+
+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.
+
+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.
+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 ANSI and POSIX standards (@pxref{Standards and
+Portability}), that is definitely a bug. Report it!@refill
+
+Send bug reports to the Internet address
+@samp{bug-glibc@@prep.ai.mit.edu} or the UUCP path
+@samp{mit-eddie!prep.ai.mit.edu!bug-glibc}. If you have other problems
+with installation or use, please report those as well.@refill
+
+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 @samp{bug-glibc-manual@@prep.ai.mit.edu} or the UUCP path
+@samp{mit-eddie!prep.ai.mit.edu!bug-glibc-manual}.
+
+@node Source Layout
+@appendixsec Adding New Functions
+
+The process of building the library is driven by the makefiles, which
+make heavy use of special features of GNU @code{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 @file{string} subdirectory has all the string-manipulation
+functions, @file{stdio} has all the standard I/O functions, etc.
+
+Each subdirectory contains a simple makefile, called @file{Makefile},
+which defines a few @code{make} variables and then includes the global
+makefile @file{Rules} with a line like:
+
+@smallexample
+include ../Rules
+@end smallexample
+
+@noindent
+The basic variables that a subdirectory makefile defines are:
+
+@table @code
+@item subdir
+The name of the subdirectory, for example @file{stdio}.
+This variable @strong{must} be defined.
+
+@item headers
+The names of the header files in this section of the library,
+such as @file{stdio.h}.
+
+@item routines
+@itemx aux
+The names of the modules (source files) in this section of the library.
+These should be simple names, such as @samp{strlen} (rather than
+complete file names, such as @file{strlen.c}). Use @code{routines} for
+modules that define functions in the library, and @code{aux} for
+auxiliary modules containing things like data definitions. But the
+values of @code{routines} and @code{aux} are just concatenated, so there
+really is no practical difference.@refill
+
+@item tests
+The names of test programs for this section of the library. These
+should be simple names, such as @samp{tester} (rather than complete file
+names, such as @file{tester.c}). @w{@samp{make tests}} will build and
+run all the test programs. If a test program needs input, put the test
+data in a file called @file{@var{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 @file{@var{test-program}.args}.@refill
+
+@item 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
+@w{@samp{make others}}.@refill
+
+@item install-lib
+@itemx install-data
+@itemx install
+Files to be installed by @w{@samp{make install}}. Files listed in
+@samp{install-lib} are installed in the directory specified by
+@samp{libdir} in @file{configparms} or @file{Makeconfig}
+(@pxref{Installation}). Files listed in @code{install-data} are
+installed in the directory specified by @samp{datadir} in
+@file{configparms} or @file{Makeconfig}. Files listed in @code{install}
+are installed in the directory specified by @samp{bindir} in
+@file{configparms} or @file{Makeconfig}.@refill
+
+@item 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 @code{distribute} if there are files used in an unusual way
+that should go into the distribution.
+
+@item generated
+Files which are generated by @file{Makefile} in this subdirectory.
+These files will be removed by @w{@samp{make clean}}, and they will
+never go into a distribution.
+
+@item extra-objs
+Extra object files which are built by @file{Makefile} in this
+subdirectory. This should be a list of file names like @file{foo.o};
+the files will actually be found in whatever directory object files are
+being built in. These files will be removed by @w{@samp{make clean}}.
+This variable is used for secondary object files needed to build
+@code{others} or @code{tests}.
+@end table
+
+@node Porting
+@appendixsec 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 @file{sysdeps} under the top-level
+library source directory. This directory contains a hierarchy of
+subdirectories (@pxref{Hierarchy Conventions}).
+
+Each subdirectory of @file{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 @file{unix/bsd/vax} is equivalent to specifying the
+list @file{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 @file{Implies} exists in a
+subdirectory, it lists other subdirectories of @file{sysdeps} which are
+appended to the list, appearing after the subdirectory containing the
+@file{Implies} file. Lines in an @file{Implies} file that begin with a
+@samp{#} character are ignored as comments. For example,
+@file{unix/bsd/Implies} contains:@refill
+@smallexample
+# BSD has Internet-related things.
+unix/inet
+@end smallexample
+@noindent
+and @file{unix/Implies} contains:
+@need 300
+@smallexample
+posix
+@end smallexample
+
+@noindent
+So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}.
+
+@file{sysdeps} has two ``special'' subdirectories, called @file{generic}
+and @file{stub}. These two are always implicitly appended to the list
+of subdirectories (in that order), so you needn't put them in an
+@file{Implies} file, and you should not create any subdirectories under
+them. @file{generic} is for things that can be implemented in
+machine-independent C, using only other machine-independent functions in
+the C library. @file{stub} is for @dfn{stub} versions of functions
+which cannot be implemented on a particular machine or operating system.
+The stub functions always return an error, and set @code{errno} to
+@code{ENOSYS} (Function not implemented). @xref{Error Reporting}.
+
+A source file is known to be system-dependent by its having a version in
+@file{generic} or @file{stub}; every system-dependent function should
+have either a generic or stub implementation (there is no point in
+having both).
+
+If you come across a file that is in one of the main source directories
+(@file{string}, @file{stdio}, etc.), and you want to write a machine- or
+operating system-dependent version of it, move the file into
+@file{sysdeps/generic} and write your new implementation in the
+appropriate system-specific subdirectory. Note that if a file is to be
+system-dependent, it @strong{must not} appear in one of the main source
+directories.@refill
+
+There are a few special files that may exist in each subdirectory of
+@file{sysdeps}:
+
+@comment Blank lines after items make the table look better.
+@table @file
+@item Makefile
+
+A makefile for this machine or operating system, or class of machine or
+operating system. This file is included by the library makefile
+@file{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 @code{make}
+conditional directives based on the variable @samp{subdir} (see above) to
+select different sets of variables and rules for different sections of
+the library. It can also set the @code{make} variable
+@samp{sysdep-routines}, to specify extra modules to be included in the
+library. You should use @samp{sysdep-routines} rather than adding
+modules to @samp{routines} because the latter is used in determining
+what to distribute for each subdirectory of the main source tree.@refill
+
+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 @samp{sysdep-routines}
+rather than simply setting it:
+
+@smallexample
+sysdep-routines := $(sysdep-routines) foo bar
+@end smallexample
+
+@need 1000
+@item 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 @file{stdio} and
+@file{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 @file{sysdeps} implements. For example,
+@file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
+directory contains various network-oriented operations which only make
+sense to put in the library on systems that support the Internet.@refill
+
+@item Dist
+
+This file contains the names of files (relative to the subdirectory of
+@file{sysdeps} in which it appears) which should be included in the
+distribution. List any new files used by rules in the @file{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.
+
+@item configure
+
+This file is a shell script fragment to be run at configuration time.
+The top-level @file{configure} script uses the shell @code{.} command to
+read the @file{configure} file in each system-dependent directory
+chosen, in order. The @file{configure} files are often generated from
+@file{configure.in} files using Autoconf.
+
+A system-dependent @file{configure} script will usually add things to
+the shell variables @samp{DEFS} and @samp{config_vars}; see the
+top-level @file{configure} script for details. The script can check for
+@w{@samp{--with-@var{package}}} options that were passed to the
+top-level @file{configure}. For an option
+@w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the
+shell variable @w{@samp{with_@var{package}}} (with any dashes in
+@var{package} converted to underscores) to @var{value}; if the option is
+just @w{@samp{--with-@var{package}}} (no argument), then it sets
+@w{@samp{with_@var{package}}} to @samp{yes}.
+
+@item configure.in
+
+This file is an Autoconf input fragment to be processed into the file
+@file{configure} in this subdirectory. @xref{Introduction,,,
+autoconf.info, Autoconf: Generating Automatic Configuration Scripts},
+for a description of Autoconf. You should write either @file{configure}
+or @file{configure.in}, but not both. The first line of
+@file{configure.in} should invoke the @code{m4} macro
+@samp{GLIBC_PROVIDES}. This macro does several @code{AC_PROVIDE} calls
+for Autoconf macros which are used by the top-level @file{configure}
+script; without this, those macros might be invoked again unnecessarily
+by Autoconf.
+@end table
+
+That is the general system for how system-dependencies are isolated.
+@iftex
+The next section explains how to decide what directories in
+@file{sysdeps} to use. @ref{Porting to Unix}, has some tips on porting
+the library to Unix variants.
+@end iftex
+
+@menu
+* Hierarchy Conventions:: The layout of the @file{sysdeps} hierarchy.
+* Porting to Unix:: Porting the library to an average
+ Unix-like system.
+@end menu
+
+@node Hierarchy Conventions
+@appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy
+
+A GNU configuration name has three parts: the CPU type, the
+manufacturer's name, and the operating system. @file{configure} uses
+these to pick the list of system-dependent directories to look for. If
+the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
+directory @file{@var{machine}/fpu} is also used. The operating system
+often has a @dfn{base operating system}; for example, if the operating
+system is @samp{sunos4.1}, the base operating system is @samp{unix/bsd}.
+The algorithm used to pick the list of directories is simple:
+@file{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 @w{@samp{sparc-sun-sunos4.1}}
+results in @file{unix/bsd/sun/sparc/sunos4.1}. @file{configure} then
+tries removing each element of the list in turn, so
+@file{unix/bsd/sparc} and @file{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 @file{sunos4.1.1} and @file{sunos4.1.2} directories,
+@file{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 @w{@samp{sparc-sun-sunos4.1}} (without the
+@w{@samp{--nfp}} option):
+
+@smallexample
+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
+@end smallexample
+
+Different machine architectures are conventionally subdirectories at the
+top level of the @file{sysdeps} directory tree. For example,
+@w{@file{sysdeps/sparc}} and @w{@file{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
+@w{@file{sysdeps/m68k/68020}}. Code which is specific to the
+floating-point coprocessor used with a particular machine should go in
+@w{@file{sysdeps/@var{machine}/fpu}}.
+
+There are a few directories at the top level of the @file{sysdeps}
+hierarchy that are not for particular machine architectures.
+
+@table @file
+@item generic
+@itemx stub
+As described above (@pxref{Porting}), these are the two subdirectories
+that every configuration implicitly uses after all others.
+
+@item ieee754
+This directory is for code using the IEEE 754 floating-point format,
+where the C type @code{float} is IEEE 754 single-precision format, and
+@code{double} is IEEE 754 double-precision format. Usually this
+directory is referred to in the @file{Implies} file in a machine
+architecture-specific directory, such as @file{m68k/Implies}.
+
+@item posix
+This directory contains implementations of things in the library in
+terms of @sc{POSIX.1} functions. This includes some of the @sc{POSIX.1}
+functions themselves. Of course, @sc{POSIX.1} cannot be completely
+implemented in terms of itself, so a configuration using just
+@file{posix} cannot be complete.
+
+@item unix
+This is the directory for Unix-like things. @xref{Porting to Unix}.
+@file{unix} implies @file{posix}. There are some special-purpose
+subdirectories of @file{unix}:
+
+@table @file
+@item unix/common
+This directory is for things common to both BSD and System V release 4.
+Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
+
+@item unix/inet
+This directory is for @code{socket} and related functions on Unix systems.
+The @file{inet} top-level subdirectory is enabled by @file{unix/inet/Subdirs}.
+@file{unix/common} implies @file{unix/inet}.
+@end table
+
+@item 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 @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
+@end table
+
+@node Porting to Unix
+@appendixsubsec 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 @file{unix}, at the top
+level of the @file{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 @file{sysdeps/unix}. These
+files are named with a suffix of @samp{.S}; for example,
+@file{__open.S}. Files ending in @samp{.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
+@file{sysdep.h}. The @file{sysdep.h} file in @file{sysdeps/unix}
+partially defines them; a @file{sysdep.h} file in another directory must
+finish defining them for the particular machine and operating system
+variant. See @file{sysdeps/unix/sysdep.h} and the machine-specific
+@file{sysdep.h} implementations to see what these macros are and what
+they should do.@refill
+
+The system-specific makefile for the @file{unix} directory (that is, the
+file @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 @emph{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 @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
+@file{errlist.c} (for the @file{stdio} section of the library).
+
+@ignore
+@c This section might be a good idea if it is finished,
+@c but there's no point including it as it stands. --rms
+@c @appendixsec Compatibility with Traditional C
+
+@c ??? This section is really short now. Want to keep it? --roland
+
+Although the GNU C library implements the ANSI C library facilities, you
+@emph{can} use the GNU C library with traditional, ``pre-ANSI'' C
+compilers. However, you need to be careful because the content and
+organization of the GNU C library header files differs from that of
+traditional C implementations. This means you may need to make changes
+to your program in order to get it to compile.
+@end ignore
+
+@node Contributors
+@appendixsec Contributors to the GNU C Library
+
+The GNU C library was written almost entirely by Roland McGrath, who now
+maintains it. Some parts of the library were contributed or worked on
+by other people.
+
+@itemize @bullet
+@item
+The @code{getopt} function and related code were written by
+Richard Stallman, @w{David J. MacKenzie}, and @w{Roland McGrath}.
+
+@item
+Most of the math functions are taken from 4.4 BSD; they have been
+modified only slightly to work with the GNU C library. The
+Internet-related code (most of the @file{inet} subdirectory) and several
+other miscellaneous functions and header files have been included with
+little or no modification.
+
+All code incorporated from 4.4 BSD is under the following copyright:
+
+@quotation
+@display
+Copyright @copyright{} 1991 Regents of the University of California.
+All rights reserved.
+@end display
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+
+@enumerate
+@item
+Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+@item
+Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+@item
+All advertising materials mentioning features or use of this software
+must display the following acknowledgement:
+@quotation
+This product includes software developed by the University of
+California, Berkeley and its contributors.
+@end quotation
+@item
+Neither the name of the University nor the names of its contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission.
+@end enumerate
+
+@sc{this software is provided by the regents and contributors ``as is'' and
+any express or implied warranties, including, but not limited to, the
+implied warranties of merchantability and fitness for a particular purpose
+are disclaimed. in no event shall the regents or contributors be liable
+for any direct, indirect, incidental, special, exemplary, or consequential
+damages (including, but not limited to, procurement of substitute goods
+or services; loss of use, data, or profits; or business interruption)
+however caused and on any theory of liability, whether in contract, strict
+liability, or tort (including negligence or otherwise) arising in any way
+out of the use of this software, even if advised of the possibility of
+such damage.}
+@end quotation
+
+@item
+The random number generation functions @code{random}, @code{srandom},
+@code{setstate} and @code{initstate}, which are also the basis for the
+@code{rand} and @code{srand} functions, were written by Earl T. Cohen
+for the University of California at Berkeley and are copyrighted by the
+Regents of the University of California. They have undergone minor
+changes to fit into the GNU C library and to fit the ANSI C standard,
+but the functional code is Berkeley's.@refill
+
+@item
+The merge sort function @code{qsort} was written by Michael J. Haertel.
+
+@item
+The quick sort function used as a fallback by @code{qsort} was written
+by Douglas C. Schmidt.
+
+@item
+The memory allocation functions @code{malloc}, @code{realloc} and
+@code{free} and related code were written by Michael J. Haertel.
+
+@comment tege's name has an umlaut.
+@tex
+\xdef\SETtege{Torbj\"orn Granlund}
+@end tex
+@ifinfo
+@set tege Torbjorn Granlund
+@end ifinfo
+@item
+Fast implementations of many of the string functions (@code{memcpy},
+@code{strlen}, etc.) were written by @value{tege}.
+
+@item
+Some of the support code for Mach is taken from Mach 3.0 by CMU,
+and is under the following copyright terms:
+
+@quotation
+@display
+Mach Operating System
+Copyright @copyright{} 1991,1990,1989 Carnegie Mellon University
+All Rights Reserved.
+@end display
+
+Permission to use, copy, modify and distribute this software and its
+documentation is hereby granted, provided that both the copyright
+notice and this permission notice appear in all copies of the
+software, derivative works or modified versions, and any portions
+thereof, and that both notices appear in supporting documentation.
+
+@sc{carnegie mellon allows free use of this software in its ``as is''
+condition. carnegie mellon disclaims any liability of any kind for
+any damages whatsoever resulting from the use of this software.}
+
+Carnegie Mellon requests users of this software to return to
+
+@display
+ Software Distribution Coordinator
+ School of Computer Science
+ Carnegie Mellon University
+ Pittsburgh PA 15213-3890
+@end display
+
+@noindent
+or @samp{Software.Distribution@@CS.CMU.EDU} any improvements or
+extensions that they make and grant Carnegie Mellon the rights to
+redistribute these changes.
+@end quotation
+
+@item
+The @file{tar.h} header file was written by David J. MacKenzie.
+
+@item
+The port to the MIPS DECStation running Ultrix 4
+(@code{mips-dec-ultrix4})
+was contributed by Brendan Kehoe and Ian Lance Taylor.
+
+@item
+The DES encryption function @code{crypt} and related functions were
+contributed by Michael Glad.
+
+@item
+The @code{ftw} function was contributed by Ian Lance Taylor.
+
+@item
+The code to support SunOS shared libraries was contributed by Tom Quinn.
+
+@item
+The @code{mktime} function was contributed by Noel Cragg.
+
+@item
+The port to the Sequent Symmetry running Dynix version 3
+(@code{i386-sequent-bsd}) was contributed by Jason Merrill.
+
+@item
+The timezone support code is derived from the public-domain timezone
+package by Arthur David Olson.
+
+@item
+The Internet resolver code is taken directly from BIND 4.9.1, which is
+under both the Berkeley copyright above and also:
+
+@quotation
+Portions Copyright @copyright{} 1993 by Digital Equipment Corporation.
+
+Permission to use, copy, modify, and distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies, and
+that the name of Digital Equipment Corporation not be used in
+advertising or publicity pertaining to distribution of the document or
+software without specific, written prior permission.
+
+@sc{the software is provided ``as is'' and digital equipment corp.
+disclaims all warranties with regard to this software, including all
+implied warranties of merchantability and fitness. in no event shall
+digital equipment corporation be liable for any special, direct,
+indirect, or consequential damages or any damages whatsoever resulting
+from loss of use, data or profits, whether in an action of contract,
+negligence or other tortious action, arising out of or in connection
+with the use or performance of this software.}
+@end quotation
+
+@item
+The port to the DEC Alpha running OSF/1 (@code{alpha-dec-osf1}) was
+contributed by Brendan Kehoe, using some code written by Roland McGrath.
+
+@item
+The floating-point printing function used by @code{printf} and friends
+was written by Roland McGrath and @value{tege}. The multi-precision
+integer functions used in that function are taken from GNU MP, which was
+contributed by @value{tege}.
+
+@item
+The code to support Sun RPC is taken verbatim from Sun's
+@w{@sc{rpcsrc-4.0}} distribution, and is covered by this copyright:
+
+@quotation
+@display
+Copyright @copyright{} 1984, Sun Microsystems, Inc.
+@end display
+
+Sun RPC is a product of Sun Microsystems, Inc. and is provided for
+unrestricted use provided that this legend is included on all tape media
+and as a part of the software program in whole or part. Users may copy
+or modify Sun RPC without charge, but are not authorized to license or
+distribute it to anyone else except as part of a product or program
+developed by the user.
+
+@sc{sun rpc is provided as is with no warranties of any kind including the
+warranties of design, merchantibility and fitness for a particular
+purpose, or arising from a course of dealing, usage or trade practice.}
+
+Sun RPC is provided with no support and without any obligation on the
+part of Sun Microsystems, Inc. to assist in its use, correction,
+modification or enhancement.
+
+@sc{sun microsystems, inc. shall have no liability with respect to the
+infringement of copyrights, trade secrets or any patents by sun rpc
+or any part thereof.}
+
+In no event will Sun Microsystems, Inc. be liable for any lost revenue
+or profits or other special, indirect and consequential damages, even if
+Sun has been advised of the possibility of such damages.
+
+@display
+Sun Microsystems, Inc.
+2550 Garcia Avenue
+Mountain View, California 94043
+@end display
+@end quotation
+
+@item
+The port to SGI machines running Irix 4 (@code{mips-sgi-irix4}) was
+contributed by Tom Quinn.
+
+@item
+The port of the Mach and Hurd code to the MIPS architecture
+(@code{mips-@var{anything}-gnu}) was contribued by Kazumoto Kojima.
+@end itemize
+
+@c @bye