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