mirror of
https://sourceware.org/git/glibc.git
synced 2024-11-26 06:50:07 +00:00
a8922de8c7
Fri Aug 9 17:38:58 1996 Ulrich Drepper <drepper@cygnus.com> * sysdeps/unix/sysv/linux/sys/timex.h: Include <sys/time.h> to get `struct timeval'. * sysdeps/unix/sysv/linux/sys/acct.h: Get time_t from <time.h>. * sysdeps/unix/sysv/linux/sys/module.h: Get size_t from <stddef.h>. * sysdeps/unix/sysv/linux/sys/io.h: Get definition of __P. * sysdeps/unix/sysv/linux/sys/klog.h: Likewise. * gmon/sys/gmon.h: Include <sys/types.h> to get u_long. * sysdeps/unix/sysv/linux/direntry.h: Complete types in <linux/dirent.h>. * io/fts.h: Include <sys/types.h> to get dev_t. Reported by Matthias Urlichs. * sysdeps/posix/tempname.c [USE_IN_LIBIO]: Don't clear _IO_file_flags. It's the same as _flags. Reported by Miquel van Smoorenburg <miquels@Q.cistron.nl>. Wed Aug 7 19:38:47 1996 Andreas Schwab <schwab@issan.informatik.uni-dortmund.de> * sysdeps/unix/sysv/linux/m68k/resourcebits.h: Add RLIMIT_AS.
1071 lines
42 KiB
Plaintext
1071 lines
42 KiB
Plaintext
@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, but usually
|
|
requires several GNU tools to be installed already.
|
|
@iftex
|
|
(@pxref{Tools for Installation}, below.)
|
|
@end iftex
|
|
|
|
@menu
|
|
* Tools for Installation:: We recommend using these tools to build.
|
|
* Supported Configurations:: What systems the GNU C library runs on.
|
|
@end menu
|
|
|
|
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.
|
|
|
|
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}.
|
|
|
|
@item --with-gnu-binutils
|
|
This option implies both @w{@samp{--with-gnu-ld}} and @w{@samp{--with-gnu-as}}.
|
|
On systems where GNU tools are the system tools, there is no need to
|
|
specify this option. These include GNU, GNU/Linux, and free BSD systems.
|
|
|
|
@c extra blank line makes it look better
|
|
@item --without-fp
|
|
@itemx --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.)
|
|
|
|
@item --enable-shared
|
|
@itemx --disable-shared
|
|
Enable or disable building of an ELF shared library on systems that
|
|
support it. The default is to build the shared library on systems using
|
|
ELF when the GNU @code{binutils} are available.
|
|
|
|
@item --enable-profile
|
|
@itemx --disable-profile
|
|
Enable or disable building of the profiled C library, @samp{-lc_p}. The
|
|
default is to build the profiled library. You may wish to disable it if
|
|
you don't plan to do profiling, because it doubles the build time of
|
|
compiling just the unprofiled static library.
|
|
|
|
@item --enable-omitfp
|
|
Enable building a highly-optimized but possibly undebuggable static C
|
|
library. This causes the normal static and shared (if enabled) C
|
|
libraries to be compiled with maximal optimization, including the
|
|
@samp{-fomit-frame-pointer} switch that makes debugging impossible on
|
|
many machines, and without debugging information (which makes the
|
|
binaries substantially smaller). An additional static library is
|
|
compiled with no optimization and full debugging information, and
|
|
installed as @samp{-lc_g}.
|
|
@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.)
|
|
|
|
|
|
To build the library and related programs, type @code{make}. This will
|
|
produce a lot of output, some of which may look 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 check}. 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 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.@refill
|
|
|
|
@node Tools for Installation
|
|
@appendixsubsec Recommended Tools to Install the GNU C Library
|
|
@cindex installation tools
|
|
@cindex tools, for installing library
|
|
|
|
We recommend installing the following GNU tools before attempting to
|
|
build the GNU C library:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
@code{make} 3.75
|
|
|
|
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.}
|
|
We recommend version GNU @code{make} version 3.75 or later.
|
|
|
|
@item
|
|
GCC 2.7.2
|
|
|
|
On most platforms, the GNU C library can only be compiled with the GNU C
|
|
compiler. We recommend GCC version 2.7.2 or later; earlier versions may
|
|
have problems.
|
|
|
|
@item
|
|
@code{binutils} 2.7
|
|
|
|
Using the GNU @code{binutils} (assembler, linker, and related tools) is
|
|
preferable when possible, and they are required to build an ELF shared C
|
|
library. We recommend @code{binutils} version 2.7 or later; earlier
|
|
versions are known to have problems or to not support all architectures.
|
|
@end itemize
|
|
|
|
@node Supported Configurations
|
|
@appendixsubsec Supported Configurations
|
|
@cindex configurations, all supported
|
|
|
|
The GNU C Library currently supports configurations that match the
|
|
following patterns:
|
|
|
|
@smallexample
|
|
alpha-dec-osf1
|
|
alpha-@var{anything}-linux
|
|
alpha-@var{anything}-linuxecoff
|
|
i@var{x}86-@var{anything}-bsd4.3
|
|
i@var{x}86-@var{anything}-gnu
|
|
i@var{x}86-@var{anything}-isc2.2
|
|
i@var{x}86-@var{anything}-isc3.@var{n}
|
|
i@var{x}86-@var{anything}-linux
|
|
i@var{x}86-@var{anything}-sco3.2
|
|
i@var{x}86-@var{anything}-sco3.2v4
|
|
i@var{x}86-@var{anything}-sysv
|
|
i@var{x}86-@var{anything}-sysv4
|
|
i@var{x}86-force_cpu386-none
|
|
i@var{x}86-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
|
|
|
|
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
|
|
|
|
@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{math} has all the mathematical 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}. 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.
|
|
|
|
@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 intended to be new specific categories. @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 generally-available function whose
|
|
implementation is system-dependent in should have either a generic or
|
|
stub implementation (there is no point in having both). Some rare functions
|
|
are only useful on specific systems and aren't defined at all on others;
|
|
these do not appear anywhere in the system-independent source code or makefiles
|
|
(including the @file{generic} and @file{stub} directories), only in the
|
|
system-dependent @file{Makefile} in the specific system's subdirectory.
|
|
|
|
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 originally by Roland McGrath. 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
|
|
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
|
|
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 startup code to support SunOS shared libraries was contributed by
|
|
Tom Quinn.
|
|
|
|
@item
|
|
The @code{mktime} function was contributed by Paul Eggert.
|
|
|
|
@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 and his many contributors.
|
|
|
|
@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 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 contributed by Kazumoto Kojima.
|
|
|
|
@item
|
|
The floating-point printing function used by @code{printf} and friends
|
|
and the floating-point reading function used by @code{scanf},
|
|
@code{strtod} and friends were written by Ulrich Drepper. The
|
|
multi-precision integer functions used in those functions are taken from
|
|
GNU MP, which was contributed by @value{tege}.
|
|
|
|
@item
|
|
The internationalization support in the library, and the support
|
|
programs @code{locale} and @code{localedef}, were written by Ulrich
|
|
Drepper. Ulrich Drepper adapted the support code for message catalogs
|
|
(@file{libintl.h}, etc.) from the GNU @code{gettext} package, which he
|
|
also wrote. He also contributed the @code{catgets} support and the
|
|
entire suite of multi-byte and wide-character support functions
|
|
(@file{wctype.h}, @file{wchar.h}, etc.).
|
|
|
|
@item
|
|
The implementations of the @file{nsswitch.conf} mechanism and the files
|
|
and DNS backends for it were designed and written by Ulrich Drepper and
|
|
Roland McGrath, based on a backend interface defined by Peter Eriksson.
|
|
|
|
@item
|
|
The port to Linux i386/ELF (@code{i386-@var{anything}-linux}) was
|
|
contributed by Ulrich Drepper, based in large part on work done in
|
|
Hongjiu Lu's Linux version of the GNU C Library.
|
|
|
|
@item
|
|
The port to Linux/m68k (@code{m68k-@var{anything}-linux}) was
|
|
contributed by Andreas Schwab.
|
|
|
|
@item
|
|
Richard Henderson contributed the ELF dynamic linking code and other
|
|
support for the Alpha processor.
|
|
|
|
@item
|
|
David Mosberger-Tang contributed the port to Linux/Alpha
|
|
(@code{alpha-@var{anything}-linux}).
|
|
|
|
@item
|
|
Stephen R. van den Berg contributed a highly-optimized @code{strstr} function.
|
|
|
|
@item
|
|
Ulrich Drepper contributed the @code{hsearch} and @code{drand48}
|
|
families of functions; reentrant @samp{@dots{}@code{_r}} versions of the
|
|
@code{random} family; System V shared memory and IPC support code; and
|
|
several highly-optimized string functions for i@var{x}86 processors.
|
|
|
|
@item
|
|
The math functions are taken from @code{fdlibm-5.1} by Sun
|
|
Microsystems, as modified by J.T. Conklin, Ian Lance Taylor,
|
|
Ulrich Drepper, Andreas Schwab, and Roland McGrath.
|
|
|
|
@item
|
|
The @code{libio} library used to implement @code{stdio} functions on
|
|
some platforms was written by Per Bothner and modified by Ulrich Drepper.
|
|
|
|
@item
|
|
The Internet-related code (most of the @file{inet} subdirectory) and
|
|
several other miscellaneous functions and header files have been
|
|
included from 4.4 BSD 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 Internet resolver code is taken directly from BIND 4.9.4, 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 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
|
|
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
|
|
|
|
@end itemize
|
|
|
|
@c @bye
|