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