Update from main archive 960813
[kopensolaris-gnu/glibc.git] / INSTALL
1 Library Maintenance
2 *******************
3
4 How to Install the GNU C Library
5 ================================
6
7    Installation of the GNU C library is relatively simple, but usually
8 requires several GNU tools to be installed already.
9
10    To configure the GNU C library for your system, run the shell script
11 `configure' with `sh'.  Use an argument which is the conventional GNU
12 name for your system configuration--for example, `sparc-sun-sunos4.1',
13 for a Sun 4 running SunOS 4.1.  *Note Installation:
14 (gcc.info)Installation, for a full description of standard GNU
15 configuration names.  If you omit the configuration name, `configure'
16 will try to guess one for you by inspecting the system it is running
17 on.  It may or may not be able to come up with a guess, and the its
18 guess might be wrong.  `configure' will tell you the canonical name of
19 the chosen configuration before proceeding.
20
21    Here are some options that you should specify (if appropriate) when
22 you run `configure':
23
24 `--with-gnu-ld'
25      Use this option if you plan to use GNU `ld' to link programs with
26      the GNU C Library.  (We strongly recommend that you do.)  This
27      option enables use of features that exist only in GNU `ld'; so if
28      you configure for GNU `ld' you must use GNU `ld' *every time* you
29      link with the GNU C Library, and when building it.
30
31 `--with-gnu-as'
32      Use this option if you plan to use the GNU assembler, `gas', when
33      building the GNU C Library.  On some systems, the library may not
34      build properly if you do *not* use `gas'.
35
36 `--with-gnu-binutils'
37      This option implies both `--with-gnu-ld' and `--with-gnu-as'.  On
38      systems where GNU tools are the system tools, there is no need to
39      specify this option.  These include GNU, GNU/Linux, and free BSD
40      systems.
41
42 `--without-fp'
43 `--nfp'
44      Use this option if your computer lacks hardware floating-point
45      support.
46
47 `--prefix=DIRECTORY'
48      Install machine-independent data files in subdirectories of
49      `DIRECTORY'.  (You can also set this in `configparms'; see below.)
50
51 `--exec-prefix=DIRECTORY'
52      Install the library and other machine-dependent files in
53      subdirectories of `DIRECTORY'.  (You can also set this in
54      `configparms'; see below.)
55
56 `--enable-shared'
57 `--disable-shared'
58      Enable or disable building of an ELF shared library on systems that
59      support it.  The default is to build the shared library on systems
60      using ELF when the GNU `binutils' are available.
61
62 `--enable-profile'
63 `--disable-profile'
64      Enable or disable building of the profiled C library, `-lc_p'.  The
65      default is to build the profiled library.  You may wish to disable
66      it if you don't plan to do profiling, because it doubles the build
67      time of compiling just the unprofiled static library.
68
69 `--enable-omitfp'
70      Enable building a highly-optimized but possibly undebuggable
71      static C library.  This causes the normal static and shared (if
72      enabled) C libraries to be compiled with maximal optimization,
73      including the `-fomit-frame-pointer' switch that makes debugging
74      impossible on many machines, and without debugging information
75      (which makes the binaries substantially smaller).  An additional
76      static library is compiled with no optimization and full debugging
77      information, and installed as `-lc_g'.
78
79    The simplest way to run `configure' is to do it in the directory
80 that contains the library sources.  This prepares to build the library
81 in that very directory.
82
83    You can prepare to build the library in some other directory by going
84 to that other directory to run `configure'.  In order to run configure,
85 you will have to specify a directory for it, like this:
86
87      mkdir sun4
88      cd sun4
89      ../configure sparc-sun-sunos4.1
90
91 `configure' looks for the sources in whatever directory you specified
92 for finding `configure' itself.  It does not matter where in the file
93 system the source and build directories are--as long as you specify the
94 source directory when you run `configure', you will get the proper
95 results.
96
97    This feature lets you keep sources and binaries in different
98 directories, and that makes it easy to build the library for several
99 different machines from the same set of sources.  Simply create a build
100 directory for each target machine, and run `configure' in that
101 directory specifying the target machine's configuration name.
102
103    The library has a number of special-purpose configuration parameters.
104 These are defined in the file `Makeconfig'; see the comments in that
105 file for the details.
106
107    But don't edit the file `Makeconfig' yourself--instead, create a
108 file `configparms' in the directory where you are building the library,
109 and define in that file the parameters you want to specify.
110 `configparms' should *not* be an edited copy of `Makeconfig'; specify
111 only the parameters that you want to override.  To see how to set these
112 parameters, find the section of `Makeconfig' that says "These are the
113 configuration variables." Then for each parameter that you want to
114 change, copy the definition from `Makeconfig' to your new `configparms'
115 file, and change the value as appropriate for your system.
116
117    It is easy to configure the GNU C library for cross-compilation by
118 setting a few variables in `configparms'.  Set `CC' to the
119 cross-compiler for the target you configured the library for; it is
120 important to use this same `CC' value when running `configure', like
121 this: `CC=TARGET-gcc configure TARGET'.  Set `BUILD_CC' to the compiler
122 to use for for programs run on the build system as part of compiling
123 the library.  You may need to set `AR' and `RANLIB' to cross-compiling
124 versions of `ar' and `ranlib' if the native tools are not configured to
125 work with object files for the target you configured for.
126
127    Some of the machine-dependent code for some machines uses extensions
128 in the GNU C compiler, so you may need to compile the library with GCC.
129 (In fact, all of the existing complete ports require GCC.)
130
131    To build the library and related programs, type `make'.  This will
132 produce a lot of output, some of which may look like errors from `make'
133 (but isn't).  Look for error messages from `make' containing `***'.
134 Those indicate that something is really wrong.
135
136    To build and run some test programs which exercise some of the
137 library facilities, type `make check'.  This will produce several files
138 with names like `PROGRAM.out'.
139
140    To format the `GNU C Library Reference Manual' for printing, type
141 `make dvi'.
142
143    To install the library and its header files, and the Info files of
144 the manual, type `make install'.  This will build things if necessary,
145 before installing them.
146
147 Recommended Tools to Install the GNU C Library
148 ----------------------------------------------
149
150    We recommend installing the following GNU tools before attempting to
151 build the GNU C library:
152
153    * `make' 3.75
154
155      You need the latest version of GNU `make'.  Modifying the GNU C
156      Library to work with other `make' programs would be so hard that we
157      recommend you port GNU `make' instead.  *Really.* We recommend
158      version GNU `make' version 3.75 or later.
159
160    * GCC 2.7.2
161
162      On most platforms, the GNU C library can only be compiled with the
163      GNU C compiler.  We recommend GCC version 2.7.2 or later; earlier
164      versions may have problems.
165
166    * `binutils' 2.7
167
168      Using the GNU `binutils' (assembler, linker, and related tools) is
169      preferable when possible, and they are required to build an ELF
170      shared C library.  We recommend `binutils' version 2.7 or later;
171      earlier versions are known to have problems or to not support all
172      architectures.
173
174 Supported Configurations
175 ------------------------
176
177    The GNU C Library currently supports configurations that match the
178 following patterns:
179
180      alpha-dec-osf1
181      alpha-ANYTHING-linux
182      alpha-ANYTHING-linuxecoff
183      iX86-ANYTHING-bsd4.3
184      iX86-ANYTHING-gnu
185      iX86-ANYTHING-isc2.2
186      iX86-ANYTHING-isc3.N
187      iX86-ANYTHING-linux
188      iX86-ANYTHING-sco3.2
189      iX86-ANYTHING-sco3.2v4
190      iX86-ANYTHING-sysv
191      iX86-ANYTHING-sysv4
192      iX86-force_cpu386-none
193      iX86-sequent-bsd
194      i960-nindy960-none
195      m68k-hp-bsd4.3
196      m68k-mvme135-none
197      m68k-mvme136-none
198      m68k-sony-newsos3
199      m68k-sony-newsos4
200      m68k-sun-sunos4.N
201      mips-dec-ultrix4.N
202      mips-sgi-irix4.N
203      sparc-sun-solaris2.N
204      sparc-sun-sunos4.N
205
206    Each case of `iX86' can be `i386', `i486', `i586', or `i686'..  All
207 of those configurations produce a library that can run on any of these
208 processors.  The library will be optimized for the specified processor,
209 but will not use instructions not available on all of them.
210
211    While no other configurations are supported, there are handy aliases
212 for these few.  (These aliases work in other GNU software as well.)
213
214      decstation
215      hp320-bsd4.3 hp300bsd
216      i486-gnu
217      i586-linux
218      i386-sco
219      i386-sco3.2v4
220      i386-sequent-dynix
221      i386-svr4
222      news
223      sun3-sunos4.N sun3
224      sun4-solaris2.N sun4-sunos5.N
225      sun4-sunos4.N sun4
226
227 Reporting Bugs
228 ==============
229
230    There are probably bugs in the GNU C library.  There are certainly
231 errors and omissions in this manual.  If you report them, they will get
232 fixed.  If you don't, no one will ever know about them and they will
233 remain unfixed for all eternity, if not longer.
234
235    To report a bug, first you must find it.  Hopefully, this will be the
236 hard part.  Once you've found a bug, make sure it's really a bug.  A
237 good way to do this is to see if the GNU C library behaves the same way
238 some other C library does.  If so, probably you are wrong and the
239 libraries are right (but not necessarily).  If not, one of the libraries
240 is probably wrong.
241
242    Once you're sure you've found a bug, try to narrow it down to the
243 smallest test case that reproduces the problem.  In the case of a C
244 library, you really only need to narrow it down to one library function
245 call, if possible.  This should not be too difficult.
246
247    The final step when you have a simple test case is to report the bug.
248 When reporting a bug, send your test case, the results you got, the
249 results you expected, what you think the problem might be (if you've
250 thought of anything), your system type, and the version of the GNU C
251 library which you are using.  Also include the files `config.status'
252 and `config.make' which are created by running `configure'; they will
253 be in whatever directory was current when you ran `configure'.
254
255    If you think you have found some way in which the GNU C library does
256 not conform to the ANSI and POSIX standards (*note Standards and
257 Portability::.), that is definitely a bug.  Report it!
258
259    Send bug reports to the Internet address `bug-glibc@prep.ai.mit.edu'
260 or the UUCP path `mit-eddie!prep.ai.mit.edu!bug-glibc'.  If you have
261 other problems with installation or use, please report those as well.
262
263    If you are not sure how a function should behave, and this manual
264 doesn't tell you, that's a bug in the manual.  Report that too!  If the
265 function's behavior disagrees with the manual, then either the library
266 or the manual has a bug, so report the disagreement.  If you find any
267 errors or omissions in this manual, please report them to the Internet
268 address `bug-glibc-manual@prep.ai.mit.edu' or the UUCP path
269 `mit-eddie!prep.ai.mit.edu!bug-glibc-manual'.
270
271 Adding New Functions
272 ====================
273
274    The process of building the library is driven by the makefiles, which
275 make heavy use of special features of GNU `make'.  The makefiles are
276 very complex, and you probably don't want to try to understand them.
277 But what they do is fairly straightforward, and only requires that you
278 define a few variables in the right places.
279
280    The library sources are divided into subdirectories, grouped by
281 topic.
282
283    The `string' subdirectory has all the string-manipulation functions,
284 `math' has all the mathematical functions, etc.
285
286    Each subdirectory contains a simple makefile, called `Makefile',
287 which defines a few `make' variables and then includes the global
288 makefile `Rules' with a line like:
289
290      include ../Rules
291
292 The basic variables that a subdirectory makefile defines are:
293
294 `subdir'
295      The name of the subdirectory, for example `stdio'.  This variable
296      *must* be defined.
297
298 `headers'
299      The names of the header files in this section of the library, such
300      as `stdio.h'.
301
302 `routines'
303 `aux'
304      The names of the modules (source files) in this section of the
305      library.  These should be simple names, such as `strlen' (rather
306      than complete file names, such as `strlen.c').  Use `routines' for
307      modules that define functions in the library, and `aux' for
308      auxiliary modules containing things like data definitions.  But the
309      values of `routines' and `aux' are just concatenated, so there
310      really is no practical difference.
311
312 `tests'
313      The names of test programs for this section of the library.  These
314      should be simple names, such as `tester' (rather than complete file
315      names, such as `tester.c').  `make tests' will build and run all
316      the test programs.  If a test program needs input, put the test
317      data in a file called `TEST-PROGRAM.input'; it will be given to
318      the test program on its standard input.  If a test program wants
319      to be run with arguments, put the arguments (all on a single line)
320      in a file called `TEST-PROGRAM.args'.  Test programs should exit
321      with zero status when the test passes, and nonzero status when the
322      test indicates a bug in the library or error in building.
323
324 `others'
325      The names of "other" programs associated with this section of the
326      library.  These are programs which are not tests per se, but are
327      other small programs included with the library.  They are built by
328      `make others'.
329
330 `install-lib'
331 `install-data'
332 `install'
333      Files to be installed by `make install'.  Files listed in
334      `install-lib' are installed in the directory specified by `libdir'
335      in `configparms' or `Makeconfig' (*note Installation::.).  Files
336      listed in `install-data' are installed in the directory specified
337      by `datadir' in `configparms' or `Makeconfig'.  Files listed in
338      `install' are installed in the directory specified by `bindir' in
339      `configparms' or `Makeconfig'.
340
341 `distribute'
342      Other files from this subdirectory which should be put into a
343      distribution tar file.  You need not list here the makefile itself
344      or the source and header files listed in the other standard
345      variables.  Only define `distribute' if there are files used in an
346      unusual way that should go into the distribution.
347
348 `generated'
349      Files which are generated by `Makefile' in this subdirectory.
350      These files will be removed by `make clean', and they will never
351      go into a distribution.
352
353 `extra-objs'
354      Extra object files which are built by `Makefile' in this
355      subdirectory.  This should be a list of file names like `foo.o';
356      the files will actually be found in whatever directory object
357      files are being built in.  These files will be removed by
358      `make clean'.  This variable is used for secondary object files
359      needed to build `others' or `tests'.
360
361 Porting the GNU C Library
362 =========================
363
364    The GNU C library is written to be easily portable to a variety of
365 machines and operating systems.  Machine- and operating system-dependent
366 functions are well separated to make it easy to add implementations for
367 new machines or operating systems.  This section describes the layout of
368 the library source tree and explains the mechanisms used to select
369 machine-dependent code to use.
370
371    All the machine-dependent and operating system-dependent files in the
372 library are in the subdirectory `sysdeps' under the top-level library
373 source directory.  This directory contains a hierarchy of
374 subdirectories (*note Hierarchy Conventions::.).
375
376    Each subdirectory of `sysdeps' contains source files for a
377 particular machine or operating system, or for a class of machine or
378 operating system (for example, systems by a particular vendor, or all
379 machines that use IEEE 754 floating-point format).  A configuration
380 specifies an ordered list of these subdirectories.  Each subdirectory
381 implicitly appends its parent directory to the list.  For example,
382 specifying the list `unix/bsd/vax' is equivalent to specifying the list
383 `unix/bsd/vax unix/bsd unix'.  A subdirectory can also specify that it
384 implies other subdirectories which are not directly above it in the
385 directory hierarchy.  If the file `Implies' exists in a subdirectory,
386 it lists other subdirectories of `sysdeps' which are appended to the
387 list, appearing after the subdirectory containing the `Implies' file.
388 Lines in an `Implies' file that begin with a `#' character are ignored
389 as comments.  For example, `unix/bsd/Implies' contains:
390      # BSD has Internet-related things.
391      unix/inet
392
393 and `unix/Implies' contains:
394      posix
395
396 So the final list is `unix/bsd/vax unix/bsd unix/inet unix posix'.
397
398    `sysdeps' has two "special" subdirectories, called `generic' and
399 `stub'.  These two are always implicitly appended to the list of
400 subdirectories (in that order), so you needn't put them in an `Implies'
401 file, and you should not create any subdirectories under them intended
402 to be new specific categories.  `generic' is for things that can be
403 implemented in machine-independent C, using only other
404 machine-independent functions in the C library.  `stub' is for "stub"
405 versions of functions which cannot be implemented on a particular
406 machine or operating system.  The stub functions always return an
407 error, and set `errno' to `ENOSYS' (Function not implemented).  *Note
408 Error Reporting::.
409
410    A source file is known to be system-dependent by its having a
411 version in `generic' or `stub'; every generally-available function whose
412 implementation is system-dependent in should have either a generic or
413 stub implementation (there is no point in having both).  Some rare
414 functions are only useful on specific systems and aren't defined at all
415 on others; these do not appear anywhere in the system-independent
416 source code or makefiles (including the `generic' and `stub'
417 directories), only in the system-dependent `Makefile' in the specific
418 system's subdirectory.
419
420    If you come across a file that is in one of the main source
421 directories (`string', `stdio', etc.), and you want to write a machine-
422 or operating system-dependent version of it, move the file into
423 `sysdeps/generic' and write your new implementation in the appropriate
424 system-specific subdirectory.  Note that if a file is to be
425 system-dependent, it *must not* appear in one of the main source
426 directories.
427
428    There are a few special files that may exist in each subdirectory of
429 `sysdeps':
430
431 `Makefile'
432      A makefile for this machine or operating system, or class of
433      machine or operating system.  This file is included by the library
434      makefile `Makerules', which is used by the top-level makefile and
435      the subdirectory makefiles.  It can change the variables set in the
436      including makefile or add new rules.  It can use GNU `make'
437      conditional directives based on the variable `subdir' (see above)
438      to select different sets of variables and rules for different
439      sections of the library.  It can also set the `make' variable
440      `sysdep-routines', to specify extra modules to be included in the
441      library.  You should use `sysdep-routines' rather than adding
442      modules to `routines' because the latter is used in determining
443      what to distribute for each subdirectory of the main source tree.
444
445      Each makefile in a subdirectory in the ordered list of
446      subdirectories to be searched is included in order.  Since several
447      system-dependent makefiles may be included, each should append to
448      `sysdep-routines' rather than simply setting it:
449
450           sysdep-routines := $(sysdep-routines) foo bar
451
452 `Subdirs'
453      This file contains the names of new whole subdirectories under the
454      top-level library source tree that should be included for this
455      system.  These subdirectories are treated just like the
456      system-independent subdirectories in the library source tree, such
457      as `stdio' and `math'.
458
459      Use this when there are completely new sets of functions and header
460      files that should go into the library for the system this
461      subdirectory of `sysdeps' implements.  For example,
462      `sysdeps/unix/inet/Subdirs' contains `inet'; the `inet' directory
463      contains various network-oriented operations which only make sense
464      to put in the library on systems that support the Internet.
465
466 `Dist'
467      This file contains the names of files (relative to the
468      subdirectory of `sysdeps' in which it appears) which should be
469      included in the distribution.  List any new files used by rules in
470      the `Makefile' in the same directory, or header files used by the
471      source files in that directory.  You don't need to list files that
472      are implementations (either C or assembly source) of routines
473      whose names are given in the machine-independent makefiles in the
474      main source tree.
475
476 `configure'
477      This file is a shell script fragment to be run at configuration
478      time.  The top-level `configure' script uses the shell `.' command
479      to read the `configure' file in each system-dependent directory
480      chosen, in order.  The `configure' files are often generated from
481      `configure.in' files using Autoconf.
482
483      A system-dependent `configure' script will usually add things to
484      the shell variables `DEFS' and `config_vars'; see the top-level
485      `configure' script for details.  The script can check for
486      `--with-PACKAGE' options that were passed to the top-level
487      `configure'.  For an option `--with-PACKAGE=VALUE' `configure'
488      sets the shell variable `with_PACKAGE' (with any dashes in PACKAGE
489      converted to underscores) to VALUE; if the option is just
490      `--with-PACKAGE' (no argument), then it sets `with_PACKAGE' to
491      `yes'.
492
493 `configure.in'
494      This file is an Autoconf input fragment to be processed into the
495      file `configure' in this subdirectory.  *Note Introduction:
496      (autoconf.info)Introduction, for a description of Autoconf.  You
497      should write either `configure' or `configure.in', but not both.
498      The first line of `configure.in' should invoke the `m4' macro
499      `GLIBC_PROVIDES'.  This macro does several `AC_PROVIDE' calls for
500      Autoconf macros which are used by the top-level `configure'
501      script; without this, those macros might be invoked again
502      unnecessarily by Autoconf.
503
504    That is the general system for how system-dependencies are isolated.
505
506 Layout of the `sysdeps' Directory Hierarchy
507 -------------------------------------------
508
509    A GNU configuration name has three parts: the CPU type, the
510 manufacturer's name, and the operating system.  `configure' uses these
511 to pick the list of system-dependent directories to look for.  If the
512 `--nfp' option is *not* passed to `configure', the directory
513 `MACHINE/fpu' is also used.  The operating system often has a "base
514 operating system"; for example, if the operating system is `sunos4.1',
515 the base operating system is `unix/bsd'.  The algorithm used to pick
516 the list of directories is simple: `configure' makes a list of the base
517 operating system, manufacturer, CPU type, and operating system, in that
518 order.  It then concatenates all these together with slashes in
519 between, to produce a directory name; for example, the configuration
520 `sparc-sun-sunos4.1' results in `unix/bsd/sun/sparc/sunos4.1'.
521 `configure' then tries removing each element of the list in turn, so
522 `unix/bsd/sparc' and `sun/sparc' are also tried, among others.  Since
523 the precise version number of the operating system is often not
524 important, and it would be very inconvenient, for example, to have
525 identical `sunos4.1.1' and `sunos4.1.2' directories, `configure' tries
526 successively less specific operating system names by removing trailing
527 suffixes starting with a period.
528
529    As an example, here is the complete list of directories that would be
530 tried for the configuration `sparc-sun-sunos4.1' (without the `--nfp'
531 option):
532
533      sparc/fpu
534      unix/bsd/sun/sunos4.1/sparc
535      unix/bsd/sun/sunos4.1
536      unix/bsd/sun/sunos4/sparc
537      unix/bsd/sun/sunos4
538      unix/bsd/sun/sunos/sparc
539      unix/bsd/sun/sunos
540      unix/bsd/sun/sparc
541      unix/bsd/sun
542      unix/bsd/sunos4.1/sparc
543      unix/bsd/sunos4.1
544      unix/bsd/sunos4/sparc
545      unix/bsd/sunos4
546      unix/bsd/sunos/sparc
547      unix/bsd/sunos
548      unix/bsd/sparc
549      unix/bsd
550      unix/sun/sunos4.1/sparc
551      unix/sun/sunos4.1
552      unix/sun/sunos4/sparc
553      unix/sun/sunos4
554      unix/sun/sunos/sparc
555      unix/sun/sunos
556      unix/sun/sparc
557      unix/sun
558      unix/sunos4.1/sparc
559      unix/sunos4.1
560      unix/sunos4/sparc
561      unix/sunos4
562      unix/sunos/sparc
563      unix/sunos
564      unix/sparc
565      unix
566      sun/sunos4.1/sparc
567      sun/sunos4.1
568      sun/sunos4/sparc
569      sun/sunos4
570      sun/sunos/sparc
571      sun/sunos
572      sun/sparc
573      sun
574      sunos4.1/sparc
575      sunos4.1
576      sunos4/sparc
577      sunos4
578      sunos/sparc
579      sunos
580      sparc
581
582    Different machine architectures are conventionally subdirectories at
583 the top level of the `sysdeps' directory tree.  For example,
584 `sysdeps/sparc' and `sysdeps/m68k'.  These contain files specific to
585 those machine architectures, but not specific to any particular
586 operating system.  There might be subdirectories for specializations of
587 those architectures, such as `sysdeps/m68k/68020'. Code which is
588 specific to the floating-point coprocessor used with a particular
589 machine should go in `sysdeps/MACHINE/fpu'.
590
591    There are a few directories at the top level of the `sysdeps'
592 hierarchy that are not for particular machine architectures.
593
594 `generic'
595 `stub'
596      As described above (*note Porting::.), these are the two
597      subdirectories that every configuration implicitly uses after all
598      others.
599
600 `ieee754'
601      This directory is for code using the IEEE 754 floating-point
602      format, where the C type `float' is IEEE 754 single-precision
603      format, and `double' is IEEE 754 double-precision format.  Usually
604      this directory is referred to in the `Implies' file in a machine
605      architecture-specific directory, such as `m68k/Implies'.
606
607 `posix'
608      This directory contains implementations of things in the library in
609      terms of POSIX.1 functions.  This includes some of the POSIX.1
610      functions themselves.  Of course, POSIX.1 cannot be completely
611      implemented in terms of itself, so a configuration using just
612      `posix' cannot be complete.
613
614 `unix'
615      This is the directory for Unix-like things.  *Note Porting to
616      Unix::.  `unix' implies `posix'.  There are some special-purpose
617      subdirectories of `unix':
618
619     `unix/common'
620           This directory is for things common to both BSD and System V
621           release 4.  Both `unix/bsd' and `unix/sysv/sysv4' imply
622           `unix/common'.
623
624     `unix/inet'
625           This directory is for `socket' and related functions on Unix
626           systems.  The `inet' top-level subdirectory is enabled by
627           `unix/inet/Subdirs'.  `unix/common' implies `unix/inet'.
628
629 `mach'
630      This is the directory for things based on the Mach microkernel
631      from CMU (including the GNU operating system).  Other basic
632      operating systems (VMS, for example) would have their own
633      directories at the top level of the `sysdeps' hierarchy, parallel
634      to `unix' and `mach'.
635
636 Porting the GNU C Library to Unix Systems
637 -----------------------------------------
638
639    Most Unix systems are fundamentally very similar.  There are
640 variations between different machines, and variations in what
641 facilities are provided by the kernel.  But the interface to the
642 operating system facilities is, for the most part, pretty uniform and
643 simple.
644
645    The code for Unix systems is in the directory `unix', at the top
646 level of the `sysdeps' hierarchy.  This directory contains
647 subdirectories (and subdirectory trees) for various Unix variants.
648
649    The functions which are system calls in most Unix systems are
650 implemented in assembly code in files in `sysdeps/unix'.  These files
651 are named with a suffix of `.S'; for example, `__open.S'.  Files ending
652 in `.S' are run through the C preprocessor before being fed to the
653 assembler.
654
655    These files all use a set of macros that should be defined in
656 `sysdep.h'.  The `sysdep.h' file in `sysdeps/unix' partially defines
657 them; a `sysdep.h' file in another directory must finish defining them
658 for the particular machine and operating system variant.  See
659 `sysdeps/unix/sysdep.h' and the machine-specific `sysdep.h'
660 implementations to see what these macros are and what they should do.
661
662    The system-specific makefile for the `unix' directory (that is, the
663 file `sysdeps/unix/Makefile') gives rules to generate several files
664 from the Unix system you are building the library on (which is assumed
665 to be the target system you are building the library *for*).  All the
666 generated files are put in the directory where the object files are
667 kept; they should not affect the source tree itself.  The files
668 generated are `ioctls.h', `errnos.h', `sys/param.h', and `errlist.c'
669 (for the `stdio' section of the library).
670
671 Contributors to the GNU C Library
672 =================================
673
674    The GNU C library was written originally by Roland McGrath.  Some
675 parts of the library were contributed or worked on by other people.
676
677    * The `getopt' function and related code were written by Richard
678      Stallman, David J. MacKenzie, and Roland McGrath.
679
680    * The merge sort function `qsort' was written by Michael J. Haertel.
681
682    * The quick sort function used as a fallback by `qsort' was written
683      by Douglas C. Schmidt.
684
685    * The memory allocation functions `malloc', `realloc' and `free' and
686      related code were written by Michael J. Haertel.
687
688    * Fast implementations of many of the string functions (`memcpy',
689      `strlen', etc.) were written by Torbjorn Granlund.
690
691    * The `tar.h' header file was written by David J. MacKenzie.
692
693    * The port to the MIPS DECStation running Ultrix 4
694      (`mips-dec-ultrix4') was contributed by Brendan Kehoe and Ian
695      Lance Taylor.
696
697    * The DES encryption function `crypt' and related functions were
698      contributed by Michael Glad.
699
700    * The `ftw' function was contributed by Ian Lance Taylor.
701
702    * The startup code to support SunOS shared libraries was contributed
703      by Tom Quinn.
704
705    * The `mktime' function was contributed by Paul Eggert.
706
707    * The port to the Sequent Symmetry running Dynix version 3
708      (`i386-sequent-bsd') was contributed by Jason Merrill.
709
710    * The timezone support code is derived from the public-domain
711      timezone package by Arthur David Olson and his many contributors.
712
713    * The port to the DEC Alpha running OSF/1 (`alpha-dec-osf1') was
714      contributed by Brendan Kehoe, using some code written by Roland
715      McGrath.
716
717    * The port to SGI machines running Irix 4 (`mips-sgi-irix4') was
718      contributed by Tom Quinn.
719
720    * The port of the Mach and Hurd code to the MIPS architecture
721      (`mips-ANYTHING-gnu') was contributed by Kazumoto Kojima.
722
723    * The floating-point printing function used by `printf' and friends
724      and the floating-point reading function used by `scanf', `strtod'
725      and friends were written by Ulrich Drepper.  The multi-precision
726      integer functions used in those functions are taken from GNU MP,
727      which was contributed by Torbjorn Granlund.
728
729    * The internationalization support in the library, and the support
730      programs `locale' and `localedef', were written by Ulrich Drepper.
731      Ulrich Drepper adapted the support code for message catalogs
732      (`libintl.h', etc.) from the GNU `gettext' package, which he also
733      wrote.  He also contributed the `catgets' support and the entire
734      suite of multi-byte and wide-character support functions
735      (`wctype.h', `wchar.h', etc.).
736
737    * The implementations of the `nsswitch.conf' mechanism and the files
738      and DNS backends for it were designed and written by Ulrich
739      Drepper and Roland McGrath, based on a backend interface defined
740      by Peter Eriksson.
741
742    * The port to Linux i386/ELF (`i386-ANYTHING-linux') was contributed
743      by Ulrich Drepper, based in large part on work done in Hongjiu
744      Lu's Linux version of the GNU C Library.
745
746    * The port to Linux/m68k (`m68k-ANYTHING-linux') was contributed by
747      Andreas Schwab.
748
749    * Richard Henderson contributed the ELF dynamic linking code and
750      other support for the Alpha processor.
751
752    * David Mosberger-Tang contributed the port to Linux/Alpha
753      (`alpha-ANYTHING-linux').
754
755    * Stephen R. van den Berg contributed a highly-optimized `strstr'
756      function.
757
758    * Ulrich Drepper contributed the `hsearch' and `drand48' families of
759      functions; reentrant `...`_r'' versions of the `random' family;
760      System V shared memory and IPC support code; and several
761      highly-optimized string functions for iX86 processors.
762
763    * The math functions are taken from `fdlibm-5.1' by Sun
764      Microsystems, as modified by J.T. Conklin, Ian Lance Taylor,
765      Ulrich Drepper, Andreas Schwab, and Roland McGrath.
766
767    * The `libio' library used to implement `stdio' functions on some
768      platforms was written by Per Bothner and modified by Ulrich
769      Drepper.
770
771    * The Internet-related code (most of the `inet' subdirectory) and
772      several other miscellaneous functions and header files have been
773      included from 4.4 BSD with little or no modification.
774
775      All code incorporated from 4.4 BSD is under the following
776      copyright:
777
778                Copyright (C) 1991 Regents of the University of California.
779                All rights reserved.
780
781           Redistribution and use in source and binary forms, with or
782           without modification, are permitted provided that the
783           following conditions are met:
784
785             1. Redistributions of source code must retain the above
786                copyright notice, this list of conditions and the
787                following disclaimer.
788
789             2. Redistributions in binary form must reproduce the above
790                copyright notice, this list of conditions and the
791                following disclaimer in the documentation and/or other
792                materials provided with the distribution.
793
794             3. All advertising materials mentioning features or use of
795                this software must display the following acknowledgement:
796                     This product includes software developed by the
797                     University of California, Berkeley and its
798                     contributors.
799
800             4. Neither the name of the University nor the names of its
801                contributors may be used to endorse or promote products
802                derived from this software without specific prior
803                written permission.
804
805           THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS
806           IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
807           LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
808           FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT
809           SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
810           INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
811           DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
812           SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
813           OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
814           LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
815           (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
816           THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
817           OF SUCH DAMAGE.
818
819    * The random number generation functions `random', `srandom',
820      `setstate' and `initstate', which are also the basis for the
821      `rand' and `srand' functions, were written by Earl T. Cohen for
822      the University of California at Berkeley and are copyrighted by the
823      Regents of the University of California.  They have undergone minor
824      changes to fit into the GNU C library and to fit the ANSI C
825      standard, but the functional code is Berkeley's.
826
827    * The Internet resolver code is taken directly from BIND 4.9.5,
828      which is under both the Berkeley copyright above and also:
829
830           Portions Copyright (C) 1993 by Digital Equipment Corporation.
831
832           Permission to use, copy, modify, and distribute this software
833           for any purpose with or without fee is hereby granted,
834           provided that the above copyright notice and this permission
835           notice appear in all copies, and that the name of Digital
836           Equipment Corporation not be used in advertising or publicity
837           pertaining to distribution of the document or software
838           without specific, written prior permission.
839
840           THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP.
841           DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
842           INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
843           FITNESS.  IN NO EVENT SHALL DIGITAL EQUIPMENT CORPORATION BE
844           LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
845           DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
846           DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
847           OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
848           WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
849
850    * The code to support Sun RPC is taken verbatim from Sun's
851      RPCSRC-4.0 distribution, and is covered by this copyright:
852
853                Copyright (C) 1984, Sun Microsystems, Inc.
854
855           Sun RPC is a product of Sun Microsystems, Inc. and is
856           provided for unrestricted use provided that this legend is
857           included on all tape media and as a part of the software
858           program in whole or part.  Users may copy or modify Sun RPC
859           without charge, but are not authorized to license or
860           distribute it to anyone else except as part of a product or
861           program developed by the user.
862
863           SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND
864           INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND
865           FITNESS FOR A PARTICULAR PURPOSE, OR ARISING FROM A COURSE OF
866           DEALING, USAGE OR TRADE PRACTICE.
867
868           Sun RPC is provided with no support and without any
869           obligation on the part of Sun Microsystems, Inc. to assist in
870           its use, correction, modification or enhancement.
871
872           SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT
873           TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY
874           PATENTS BY SUN RPC OR ANY PART THEREOF.
875
876           In no event will Sun Microsystems, Inc. be liable for any
877           lost revenue or profits or other special, indirect and
878           consequential damages, even if Sun has been advised of the
879           possibility of such damages.
880
881                Sun Microsystems, Inc.
882                2550 Garcia Avenue
883                Mountain View, California  94043
884
885    * Some of the support code for Mach is taken from Mach 3.0 by CMU,
886      and is under the following copyright terms:
887
888                Mach Operating System
889                Copyright (C) 1991,1990,1989 Carnegie Mellon University
890                All Rights Reserved.
891
892           Permission to use, copy, modify and distribute this software
893           and its documentation is hereby granted, provided that both
894           the copyright notice and this permission notice appear in all
895           copies of the software, derivative works or modified
896           versions, and any portions thereof, and that both notices
897           appear in supporting documentation.
898
899           CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS
900           IS" CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF
901           ANY KIND FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF
902           THIS SOFTWARE.
903
904           Carnegie Mellon requests users of this software to return to
905
906                 Software Distribution Coordinator
907                 School of Computer Science
908                 Carnegie Mellon University
909                 Pittsburgh PA 15213-3890
910
911           or `Software.Distribution@CS.CMU.EDU' any improvements or
912           extensions that they make and grant Carnegie Mellon the
913           rights to redistribute these changes.
914