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