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-binutils=DIRECTORY'
25      Use the binutils (assembler and linker) in `DIRECTORY', not the
26      ones the C compiler would default to.  You could use this option if
27      the default binutils on your system cannot deal with all the
28      constructs in the GNU C library.  (`configure' will detect the
29      problem and suppress these constructs, so the library will still
30      be usable, but functionality may be lost--for example, you can not
31      build a shared libc with old binutils.)
32
33 `--without-fp'
34 `--nfp'
35      Use this option if your computer lacks hardware floating-point
36      support and your operating system does not emulate an FPU.
37
38 `--prefix=DIRECTORY'
39      Install machine-independent data files in subdirectories of
40      `DIRECTORY'.  (You can also set this in `configparms'; see below.)
41      The default is to install in `/usr/local'.
42
43 `--exec-prefix=DIRECTORY'
44      Install the library and other machine-dependent files in
45      subdirectories of `DIRECTORY'.  (You can also set this in
46      `configparms'; see below.)  The default is to use <prefix>/bin and
47      <prefix>/sbin.
48
49 `--enable-shared'
50 `--disable-shared'
51      Enable or disable building of an ELF shared library on systems that
52      support it.  The default is to build the shared library on systems
53      using ELF when the GNU `binutils' are available.
54
55 `--enable-profile'
56 `--disable-profile'
57      Enable or disable building of the profiled C library, `-lc_p'.  The
58      default is to build the profiled library.  You may wish to disable
59      it if you don't plan to do profiling, because it doubles the build
60      time of compiling just the unprofiled static library.
61
62 `--enable-omitfp'
63      Enable building a highly-optimized but possibly undebuggable
64      static C library.  This causes the normal static and shared (if
65      enabled) C libraries to be compiled with maximal optimization,
66      including the `-fomit-frame-pointer' switch that makes debugging
67      impossible on many machines, and without debugging information
68      (which makes the binaries substantially smaller).  An additional
69      static library is compiled with no optimization and full debugging
70      information, and installed as `-lc_g'.
71
72    The simplest way to run `configure' is to do it in the directory
73 that contains the library sources.  This prepares to build the library
74 in that very directory.
75
76    You can prepare to build the library in some other directory by going
77 to that other directory to run `configure'.  In order to run configure,
78 you will have to specify a directory for it, like this:
79
80      mkdir sun4
81      cd sun4
82      ../configure sparc-sun-sunos4.1
83
84 `configure' looks for the sources in whatever directory you specified
85 for finding `configure' itself.  It does not matter where in the file
86 system the source and build directories are--as long as you specify the
87 source directory when you run `configure', you will get the proper
88 results.
89
90    This feature lets you keep sources and binaries in different
91 directories, and that makes it easy to build the library for several
92 different machines from the same set of sources.  Simply create a build
93 directory for each target machine, and run `configure' in that
94 directory specifying the target machine's configuration name.
95
96    The library has a number of special-purpose configuration parameters.
97 These are defined in the file `Makeconfig'; see the comments in that
98 file for the details.
99
100    But don't edit the file `Makeconfig' yourself--instead, create a
101 file `configparms' in the directory where you are building the library,
102 and define in that file the parameters you want to specify.
103 `configparms' should *not* be an edited copy of `Makeconfig'; specify
104 only the parameters that you want to override.  To see how to set these
105 parameters, find the section of `Makeconfig' that says "These are the
106 configuration variables." Then for each parameter that you want to
107 change, copy the definition from `Makeconfig' to your new `configparms'
108 file, and change the value as appropriate for your system.
109
110    It is easy to configure the GNU C library for cross-compilation by
111 setting a few variables in `configparms'.  Set `CC' to the
112 cross-compiler for the target you configured the library for; it is
113 important to use this same `CC' value when running `configure', like
114 this: `CC=TARGET-gcc configure TARGET'.  Set `BUILD_CC' to the compiler
115 to use for for programs run on the build system as part of compiling
116 the library.  You may need to set `AR' and `RANLIB' to cross-compiling
117 versions of `ar' and `ranlib' if the native tools are not configured to
118 work with object files for the target you configured for.
119
120    Some of the machine-dependent code for some machines uses extensions
121 in the GNU C compiler, so you may need to compile the library with GCC.
122 (In fact, all of the existing complete ports require GCC.)
123
124    To build the library and related programs, type `make'.  This will
125 produce a lot of output, some of which may look like errors from `make'
126 (but isn't).  Look for error messages from `make' containing `***'.
127 Those indicate that something is really wrong.
128
129    To build and run some test programs which exercise some of the
130 library facilities, type `make check'.  This will produce several files
131 with names like `PROGRAM.out'.
132
133    To format the `GNU C Library Reference Manual' for printing, type
134 `make dvi'.  You need a working TeX installation to do this.
135
136    To install the library and its header files, and the Info files of
137 the manual, type `make install'.  This will build things if necessary,
138 before installing them.  If you want to install the files in a different
139 place than the one specified at configuration time you can specify a
140 value for the Makefile variable `install_root' on the command line.
141 This is useful to create chroot'ed environment or to prepare binary
142 releases.
143
144 Recommended Tools to Install the GNU C Library
145 ----------------------------------------------
146
147    We recommend installing the following GNU tools before attempting to
148 build the GNU C library:
149
150    * `make' 3.76.1
151
152      You need the latest version of GNU `make'.  Modifying the GNU C
153      Library to work with other `make' programs would be so hard that we
154      recommend you port GNU `make' instead.  *Really.*  We recommend
155      version GNU `make' version 3.75, 3.76.1 or later.  Version 3.76 is
156      known to have a bug which only shows up in big projects like GNU
157      `libc'.
158
159    * GCC 2.7.2.3
160
161      On most platforms, the GNU C library can only be compiled with the
162      GNU C compiler.  We recommend GCC version 2.7.2 or later; earlier
163      versions may have problems.
164
165      On PowerPC, GCC versions dated earlier than 970904 are known not
166      to work (they crash), including 2.7.2.
167
168    * `binutils' 2.8.1
169
170      Using the GNU `binutils' (assembler, linker, and related tools) is
171      preferable when possible, and they are required to build an ELF
172      shared C library.  We recommend `binutils' version 2.8.1 or later;
173      earlier versions are known to have problems or to not support all
174      architectures.
175
176    * `texinfo' 3.11
177
178      To correctly translate and install the Texinfo documentation you
179      need this version of the `texinfo' package.  Former versions did
180      not understand all the tags used in the document and also the
181      installation mechanisms for the info files was not present or
182      worked differently.
183
184      On some Debian Linux based systems the used `install-info' program
185      works differently.  Here you have to run make like this:
186
187           make INSTALL_INFO=/path/to/GNU/install-info install
188
189    If you change any configuration file you will need also
190
191    * `autoconf' 2.12
192
193 and if you change any of the message translation files you will also
194 need
195
196    * `GNU gettext' 0.10 or later
197
198 If you upgrade your source tree using the patches made available you
199 probably will need those package above in any case.
200
201 Supported Configurations
202 ------------------------
203
204    The GNU C Library currently supports configurations that match the
205 following patterns:
206
207      alpha-ANYTHING-linux
208      iX86-ANYTHING-gnu
209      iX86-ANYTHING-linux
210      m68k-ANYTHING-linux
211      powerpc-ANYTHING-linux
212      sparc64-ANYTHING-linux
213
214    Former releases of this library (version 1.09.1 and perhaps earlier
215 versions) used to run on the following configurations:
216
217      alpha-dec-osf1
218      alpha-ANYTHING-linuxecoff
219      iX86-ANYTHING-bsd4.3
220      iX86-ANYTHING-isc2.2
221      iX86-ANYTHING-isc3.N
222      iX86-ANYTHING-sco3.2
223      iX86-ANYTHING-sco3.2v4
224      iX86-ANYTHING-sysv
225      iX86-ANYTHING-sysv4
226      iX86-force_cpu386-none
227      iX86-sequent-bsd
228      i960-nindy960-none
229      m68k-hp-bsd4.3
230      m68k-mvme135-none
231      m68k-mvme136-none
232      m68k-sony-newsos3
233      m68k-sony-newsos4
234      m68k-sun-sunos4.N
235      mips-dec-ultrix4.N
236      mips-sgi-irix4.N
237      sparc-sun-solaris2.N
238      sparc-sun-sunos4.N
239
240    Since no one has volunteered to test and fix the above
241 configurations, these are not supported at the moment.  It's expected
242 that these don't work anymore.  Porting the library is not hard.  If
243 you are interested in doing a port, please contact the glibc
244 maintainers by sending electronic mail to <bug-glibc@prep.ai.mit.edu>.
245
246    Each case of `iX86' can be `i386', `i486', `i586', or `i686'.  All
247 of those configurations produce a library that can run on any of these
248 processors.  The library will be optimized for the specified processor,
249 but will not use instructions not available on all of them.
250
251    While no other configurations are supported, there are handy aliases
252 for these few.  (These aliases work in other GNU software as well.)
253
254      decstation
255      hp320-bsd4.3 hp300bsd
256      i486-gnu
257      i586-linux
258      i386-sco
259      i386-sco3.2v4
260      i386-sequent-dynix
261      i386-svr4
262      news
263      sun3-sunos4.N sun3
264      sun4-solaris2.N sun4-sunos5.N
265      sun4-sunos4.N sun4
266
267 Reporting Bugs
268 ==============
269
270    There are probably bugs in the GNU C library.  There are certainly
271 errors and omissions in this manual.  If you report them, they will get
272 fixed.  If you don't, no one will ever know about them and they will
273 remain unfixed for all eternity, if not longer.
274
275    To report a bug, first you must find it.  Hopefully, this will be the
276 hard part.  Once you've found a bug, make sure it's really a bug.  A
277 good way to do this is to see if the GNU C library behaves the same way
278 some other C library does.  If so, probably you are wrong and the
279 libraries are right (but not necessarily).  If not, one of the libraries
280 is probably wrong.
281
282    Once you're sure you've found a bug, try to narrow it down to the
283 smallest test case that reproduces the problem.  In the case of a C
284 library, you really only need to narrow it down to one library function
285 call, if possible.  This should not be too difficult.
286
287    The final step when you have a simple test case is to report the bug.
288 When reporting a bug, send your test case, the results you got, the
289 results you expected, what you think the problem might be (if you've
290 thought of anything), your system type, and the version of the GNU C
291 library which you are using.  Also include the files `config.status'
292 and `config.make' which are created by running `configure'; they will
293 be in whatever directory was current when you ran `configure'.
294
295    If you think you have found some way in which the GNU C library does
296 not conform to the ISO and POSIX standards (*note Standards and
297 Portability::.), that is definitely a bug.  Report it!
298
299    Send bug reports to the Internet address <bug-glibc@prep.ai.mit.edu>
300 or the UUCP path <mit-eddie!prep.ai.mit.edu!bug-glibc>.  If you have
301 other problems with installation or use, please report those as well.
302
303    If you are not sure how a function should behave, and this manual
304 doesn't tell you, that's a bug in the manual.  Report that too!  If the
305 function's behavior disagrees with the manual, then either the library
306 or the manual has a bug, so report the disagreement.  If you find any
307 errors or omissions in this manual, please report them to the Internet
308 address <bug-glibc-manual@prep.ai.mit.edu> or the UUCP path
309 <mit-eddie!prep.ai.mit.edu!bug-glibc-manual>.
310
311 Adding New Functions
312 ====================
313
314    The process of building the library is driven by the makefiles, which
315 make heavy use of special features of GNU `make'.  The makefiles are
316 very complex, and you probably don't want to try to understand them.
317 But what they do is fairly straightforward, and only requires that you
318 define a few variables in the right places.
319
320    The library sources are divided into subdirectories, grouped by
321 topic.
322
323    The `string' subdirectory has all the string-manipulation functions,
324 `math' has all the mathematical functions, etc.
325
326    Each subdirectory contains a simple makefile, called `Makefile',
327 which defines a few `make' variables and then includes the global
328 makefile `Rules' with a line like:
329
330      include ../Rules
331
332 The basic variables that a subdirectory makefile defines are:
333
334 `subdir'
335      The name of the subdirectory, for example `stdio'.  This variable
336      *must* be defined.
337
338 `headers'
339      The names of the header files in this section of the library, such
340      as `stdio.h'.
341
342 `routines'
343 `aux'
344      The names of the modules (source files) in this section of the
345      library.  These should be simple names, such as `strlen' (rather
346      than complete file names, such as `strlen.c').  Use `routines' for
347      modules that define functions in the library, and `aux' for
348      auxiliary modules containing things like data definitions.  But the
349      values of `routines' and `aux' are just concatenated, so there
350      really is no practical difference.
351
352 `tests'
353      The names of test programs for this section of the library.  These
354      should be simple names, such as `tester' (rather than complete file
355      names, such as `tester.c').  `make tests' will build and run all
356      the test programs.  If a test program needs input, put the test
357      data in a file called `TEST-PROGRAM.input'; it will be given to
358      the test program on its standard input.  If a test program wants
359      to be run with arguments, put the arguments (all on a single line)
360      in a file called `TEST-PROGRAM.args'.  Test programs should exit
361      with zero status when the test passes, and nonzero status when the
362      test indicates a bug in the library or error in building.
363
364 `others'
365      The names of "other" programs associated with this section of the
366      library.  These are programs which are not tests per se, but are
367      other small programs included with the library.  They are built by
368      `make others'.
369
370 `install-lib'
371 `install-data'
372 `install'
373      Files to be installed by `make install'.  Files listed in
374      `install-lib' are installed in the directory specified by `libdir'
375      in `configparms' or `Makeconfig' (*note Installation::.).  Files
376      listed in `install-data' are installed in the directory specified
377      by `datadir' in `configparms' or `Makeconfig'.  Files listed in
378      `install' are installed in the directory specified by `bindir' in
379      `configparms' or `Makeconfig'.
380
381 `distribute'
382      Other files from this subdirectory which should be put into a
383      distribution tar file.  You need not list here the makefile itself
384      or the source and header files listed in the other standard
385      variables.  Only define `distribute' if there are files used in an
386      unusual way that should go into the distribution.
387
388 `generated'
389      Files which are generated by `Makefile' in this subdirectory.
390      These files will be removed by `make clean', and they will never
391      go into a distribution.
392
393 `extra-objs'
394      Extra object files which are built by `Makefile' in this
395      subdirectory.  This should be a list of file names like `foo.o';
396      the files will actually be found in whatever directory object
397      files are being built in.  These files will be removed by
398      `make clean'.  This variable is used for secondary object files
399      needed to build `others' or `tests'.
400
401 Porting the GNU C Library
402 =========================
403
404    The GNU C library is written to be easily portable to a variety of
405 machines and operating systems.  Machine- and operating system-dependent
406 functions are well separated to make it easy to add implementations for
407 new machines or operating systems.  This section describes the layout of
408 the library source tree and explains the mechanisms used to select
409 machine-dependent code to use.
410
411    All the machine-dependent and operating system-dependent files in the
412 library are in the subdirectory `sysdeps' under the top-level library
413 source directory.  This directory contains a hierarchy of
414 subdirectories (*note Hierarchy Conventions::.).
415
416    Each subdirectory of `sysdeps' contains source files for a
417 particular machine or operating system, or for a class of machine or
418 operating system (for example, systems by a particular vendor, or all
419 machines that use IEEE 754 floating-point format).  A configuration
420 specifies an ordered list of these subdirectories.  Each subdirectory
421 implicitly appends its parent directory to the list.  For example,
422 specifying the list `unix/bsd/vax' is equivalent to specifying the list
423 `unix/bsd/vax unix/bsd unix'.  A subdirectory can also specify that it
424 implies other subdirectories which are not directly above it in the
425 directory hierarchy.  If the file `Implies' exists in a subdirectory,
426 it lists other subdirectories of `sysdeps' which are appended to the
427 list, appearing after the subdirectory containing the `Implies' file.
428 Lines in an `Implies' file that begin with a `#' character are ignored
429 as comments.  For example, `unix/bsd/Implies' contains:
430      # BSD has Internet-related things.
431      unix/inet
432
433 and `unix/Implies' contains:
434      posix
435
436 So the final list is `unix/bsd/vax unix/bsd unix/inet unix posix'.
437
438    `sysdeps' has a "special" subdirectory called `generic'.  It is
439 always implicitly appended to the list of subdirectories, so you
440 needn't put it in an `Implies' file, and you should not create any
441 subdirectories under it intended to be new specific categories.
442 `generic' serves two purposes.  First, the makefiles do not bother to
443 look for a system-dependent version of a file that's not in `generic'.
444 This means that any system-dependent source file must have an analogue
445 in `generic', even if the routines defined by that file are not
446 implemented on other platforms.  Second. the `generic' version of a
447 system-dependent file is used if the makefiles do not find a version
448 specific to the system you're compiling for.
449
450    If it is possible to implement the routines in a `generic' file in
451 machine-independent C, using only other machine-independent functions in
452 the C library, then you should do so.  Otherwise, make them stubs.  A
453 "stub" function is a function which cannot be implemented on a
454 particular machine or operating system.  Stub functions always return an
455 error, and set `errno' to `ENOSYS' (Function not implemented).  *Note
456 Error Reporting::.  If you define a stub function, you must place the
457 statement `stub_warning(FUNCTION)', where FUNCTION is the name of your
458 function, after its definition; also, you must include the file
459 `<stub-tag.h>' into your file.  This causes the function to be listed
460 in the installed `<gnu/stubs.h>', and makes GNU ld warn when the
461 function is used.
462
463    Some rare functions are only useful on specific systems and aren't
464 defined at all on others; these do not appear anywhere in the
465 system-independent source code or makefiles (including the `generic'
466 and `stub' directories), only in the system-dependent `Makefile' in the
467 specific system's subdirectory.
468
469    If you come across a file that is in one of the main source
470 directories (`string', `stdio', etc.), and you want to write a machine-
471 or operating system-dependent version of it, move the file into
472 `sysdeps/generic' and write your new implementation in the appropriate
473 system-specific subdirectory.  Note that if a file is to be
474 system-dependent, it *must not* appear in one of the main source
475 directories.
476
477    There are a few special files that may exist in each subdirectory of
478 `sysdeps':
479
480 `Makefile'
481      A makefile for this machine or operating system, or class of
482      machine or operating system.  This file is included by the library
483      makefile `Makerules', which is used by the top-level makefile and
484      the subdirectory makefiles.  It can change the variables set in the
485      including makefile or add new rules.  It can use GNU `make'
486      conditional directives based on the variable `subdir' (see above)
487      to select different sets of variables and rules for different
488      sections of the library.  It can also set the `make' variable
489      `sysdep-routines', to specify extra modules to be included in the
490      library.  You should use `sysdep-routines' rather than adding
491      modules to `routines' because the latter is used in determining
492      what to distribute for each subdirectory of the main source tree.
493
494      Each makefile in a subdirectory in the ordered list of
495      subdirectories to be searched is included in order.  Since several
496      system-dependent makefiles may be included, each should append to
497      `sysdep-routines' rather than simply setting it:
498
499           sysdep-routines := $(sysdep-routines) foo bar
500
501 `Subdirs'
502      This file contains the names of new whole subdirectories under the
503      top-level library source tree that should be included for this
504      system.  These subdirectories are treated just like the
505      system-independent subdirectories in the library source tree, such
506      as `stdio' and `math'.
507
508      Use this when there are completely new sets of functions and header
509      files that should go into the library for the system this
510      subdirectory of `sysdeps' implements.  For example,
511      `sysdeps/unix/inet/Subdirs' contains `inet'; the `inet' directory
512      contains various network-oriented operations which only make sense
513      to put in the library on systems that support the Internet.
514
515 `Dist'
516      This file contains the names of files (relative to the
517      subdirectory of `sysdeps' in which it appears) which should be
518      included in the distribution.  List any new files used by rules in
519      the `Makefile' in the same directory, or header files used by the
520      source files in that directory.  You don't need to list files that
521      are implementations (either C or assembly source) of routines
522      whose names are given in the machine-independent makefiles in the
523      main source tree.
524
525 `configure'
526      This file is a shell script fragment to be run at configuration
527      time.  The top-level `configure' script uses the shell `.' command
528      to read the `configure' file in each system-dependent directory
529      chosen, in order.  The `configure' files are often generated from
530      `configure.in' files using Autoconf.
531
532      A system-dependent `configure' script will usually add things to
533      the shell variables `DEFS' and `config_vars'; see the top-level
534      `configure' script for details.  The script can check for
535      `--with-PACKAGE' options that were passed to the top-level
536      `configure'.  For an option `--with-PACKAGE=VALUE' `configure'
537      sets the shell variable `with_PACKAGE' (with any dashes in PACKAGE
538      converted to underscores) to VALUE; if the option is just
539      `--with-PACKAGE' (no argument), then it sets `with_PACKAGE' to
540      `yes'.
541
542 `configure.in'
543      This file is an Autoconf input fragment to be processed into the
544      file `configure' in this subdirectory.  *Note Introduction:
545      (autoconf.info)Introduction, for a description of Autoconf.  You
546      should write either `configure' or `configure.in', but not both.
547      The first line of `configure.in' should invoke the `m4' macro
548      `GLIBC_PROVIDES'.  This macro does several `AC_PROVIDE' calls for
549      Autoconf macros which are used by the top-level `configure'
550      script; without this, those macros might be invoked again
551      unnecessarily by Autoconf.
552
553    That is the general system for how system-dependencies are isolated.
554
555 Layout of the `sysdeps' Directory Hierarchy
556 -------------------------------------------
557
558    A GNU configuration name has three parts: the CPU type, the
559 manufacturer's name, and the operating system.  `configure' uses these
560 to pick the list of system-dependent directories to look for.  If the
561 `--nfp' option is *not* passed to `configure', the directory
562 `MACHINE/fpu' is also used.  The operating system often has a "base
563 operating system"; for example, if the operating system is `sunos4.1',
564 the base operating system is `unix/bsd'.  The algorithm used to pick
565 the list of directories is simple: `configure' makes a list of the base
566 operating system, manufacturer, CPU type, and operating system, in that
567 order.  It then concatenates all these together with slashes in
568 between, to produce a directory name; for example, the configuration
569 `sparc-sun-sunos4.1' results in `unix/bsd/sun/sparc/sunos4.1'.
570 `configure' then tries removing each element of the list in turn, so
571 `unix/bsd/sparc' and `sun/sparc' are also tried, among others.  Since
572 the precise version number of the operating system is often not
573 important, and it would be very inconvenient, for example, to have
574 identical `sunos4.1.1' and `sunos4.1.2' directories, `configure' tries
575 successively less specific operating system names by removing trailing
576 suffixes starting with a period.
577
578    As an example, here is the complete list of directories that would be
579 tried for the configuration `sparc-sun-sunos4.1' (without the `--nfp'
580 option):
581
582      sparc/fpu
583      unix/bsd/sun/sunos4.1/sparc
584      unix/bsd/sun/sunos4.1
585      unix/bsd/sun/sunos4/sparc
586      unix/bsd/sun/sunos4
587      unix/bsd/sun/sunos/sparc
588      unix/bsd/sun/sunos
589      unix/bsd/sun/sparc
590      unix/bsd/sun
591      unix/bsd/sunos4.1/sparc
592      unix/bsd/sunos4.1
593      unix/bsd/sunos4/sparc
594      unix/bsd/sunos4
595      unix/bsd/sunos/sparc
596      unix/bsd/sunos
597      unix/bsd/sparc
598      unix/bsd
599      unix/sun/sunos4.1/sparc
600      unix/sun/sunos4.1
601      unix/sun/sunos4/sparc
602      unix/sun/sunos4
603      unix/sun/sunos/sparc
604      unix/sun/sunos
605      unix/sun/sparc
606      unix/sun
607      unix/sunos4.1/sparc
608      unix/sunos4.1
609      unix/sunos4/sparc
610      unix/sunos4
611      unix/sunos/sparc
612      unix/sunos
613      unix/sparc
614      unix
615      sun/sunos4.1/sparc
616      sun/sunos4.1
617      sun/sunos4/sparc
618      sun/sunos4
619      sun/sunos/sparc
620      sun/sunos
621      sun/sparc
622      sun
623      sunos4.1/sparc
624      sunos4.1
625      sunos4/sparc
626      sunos4
627      sunos/sparc
628      sunos
629      sparc
630
631    Different machine architectures are conventionally subdirectories at
632 the top level of the `sysdeps' directory tree.  For example,
633 `sysdeps/sparc' and `sysdeps/m68k'.  These contain files specific to
634 those machine architectures, but not specific to any particular
635 operating system.  There might be subdirectories for specializations of
636 those architectures, such as `sysdeps/m68k/68020'. Code which is
637 specific to the floating-point coprocessor used with a particular
638 machine should go in `sysdeps/MACHINE/fpu'.
639
640    There are a few directories at the top level of the `sysdeps'
641 hierarchy that are not for particular machine architectures.
642
643 `generic'
644      As described above (*note Porting::.), this is the subdirectory
645      that every configuration implicitly uses after all 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' and `nftw' function was contributed by Ulrich Drepper.
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    * The ports to Linux/ARM (`arm-ANYTHING-linuxaout') and ARM
798      standalone (`arm-ANYTHING-none'), as well as parts of the IPv6
799      support code, were contributed by Philip Blundell.
800
801    * Richard Henderson contributed the ELF dynamic linking code and
802      other support for the Alpha processor.
803
804    * David Mosberger-Tang contributed the port to Linux/Alpha
805      (`alpha-ANYTHING-linux').
806
807    * The port to Linux on PowerPC (`powerpc-ANYTHING-linux') was
808      contributed by Geoffrey Keating.
809
810    * Miles Bader wrote the argp argument-parsing package, and the
811      argz/envz interfaces.
812
813    * Stephen R. van den Berg contributed a highly-optimized `strstr'
814      function.
815
816    * Ulrich Drepper contributed the `hsearch' and `drand48' families of
817      functions; reentrant `...`_r'' versions of the `random' family;
818      System V shared memory and IPC support code; and several
819      highly-optimized string functions for iX86 processors.
820
821    * The math functions are taken from `fdlibm-5.1' by Sun
822      Microsystems, as modified by J.T. Conklin, Ian Lance Taylor,
823      Ulrich Drepper, Andreas Schwab, and Roland McGrath.
824
825    * The `libio' library used to implement `stdio' functions on some
826      platforms was written by Per Bothner and modified by Ulrich
827      Drepper.
828
829    * The Internet-related code (most of the `inet' subdirectory) and
830      several other miscellaneous functions and header files have been
831      included from 4.4 BSD with little or no modification.
832
833      All code incorporated from 4.4 BSD is under the following
834      copyright:
835
836                Copyright (C) 1991 Regents of the University of California.
837                All rights reserved.
838
839           Redistribution and use in source and binary forms, with or
840           without modification, are permitted provided that the
841           following conditions are met:
842
843             1. Redistributions of source code must retain the above
844                copyright notice, this list of conditions and the
845                following disclaimer.
846
847             2. Redistributions in binary form must reproduce the above
848                copyright notice, this list of conditions and the
849                following disclaimer in the documentation and/or other
850                materials provided with the distribution.
851
852             3. All advertising materials mentioning features or use of
853                this software must display the following acknowledgement:
854                     This product includes software developed by the
855                     University of California, Berkeley and its
856                     contributors.
857
858             4. Neither the name of the University nor the names of its
859                contributors may be used to endorse or promote products
860                derived from this software without specific prior
861                written permission.
862
863           THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS "AS
864           IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
865           LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
866           FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT
867           SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
868           INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
869           DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
870           SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
871           OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
872           LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
873           (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
874           THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
875           OF SUCH DAMAGE.
876
877    * The random number generation functions `random', `srandom',
878      `setstate' and `initstate', which are also the basis for the
879      `rand' and `srand' functions, were written by Earl T. Cohen for
880      the University of California at Berkeley and are copyrighted by the
881      Regents of the University of California.  They have undergone minor
882      changes to fit into the GNU C library and to fit the ISO C
883      standard, but the functional code is Berkeley's.
884
885    * The Internet resolver code is taken directly from BIND 4.9.5,
886      which is under both the Berkeley copyright above and also:
887
888           Portions Copyright (C) 1993 by Digital Equipment Corporation.
889
890           Permission to use, copy, modify, and distribute this software
891           for any purpose with or without fee is hereby granted,
892           provided that the above copyright notice and this permission
893           notice appear in all copies, and that the name of Digital
894           Equipment Corporation not be used in advertising or publicity
895           pertaining to distribution of the document or software
896           without specific, written prior permission.
897
898           THE SOFTWARE IS PROVIDED "AS IS" AND DIGITAL EQUIPMENT CORP.
899           DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE,
900           INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
901           FITNESS.  IN NO EVENT SHALL DIGITAL EQUIPMENT CORPORATION BE
902           LIABLE FOR ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL
903           DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
904           DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
905           OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
906           WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
907
908    * The code to support Sun RPC is taken verbatim from Sun's
909      RPCSRC-4.0 distribution, and is covered by this copyright:
910
911                Copyright (C) 1984, Sun Microsystems, Inc.
912
913           Sun RPC is a product of Sun Microsystems, Inc. and is
914           provided for unrestricted use provided that this legend is
915           included on all tape media and as a part of the software
916           program in whole or part.  Users may copy or modify Sun RPC
917           without charge, but are not authorized to license or
918           distribute it to anyone else except as part of a product or
919           program developed by the user.
920
921           SUN RPC IS PROVIDED AS IS WITH NO WARRANTIES OF ANY KIND
922           INCLUDING THE WARRANTIES OF DESIGN, MERCHANTIBILITY AND
923           FITNESS FOR A PARTICULAR PURPOSE, OR ARISING FROM A COURSE OF
924           DEALING, USAGE OR TRADE PRACTICE.
925
926           Sun RPC is provided with no support and without any
927           obligation on the part of Sun Microsystems, Inc. to assist in
928           its use, correction, modification or enhancement.
929
930           SUN MICROSYSTEMS, INC. SHALL HAVE NO LIABILITY WITH RESPECT
931           TO THE INFRINGEMENT OF COPYRIGHTS, TRADE SECRETS OR ANY
932           PATENTS BY SUN RPC OR ANY PART THEREOF.
933
934           In no event will Sun Microsystems, Inc. be liable for any
935           lost revenue or profits or other special, indirect and
936           consequential damages, even if Sun has been advised of the
937           possibility of such damages.
938
939                Sun Microsystems, Inc.
940                2550 Garcia Avenue
941                Mountain View, California  94043
942
943    * Some of the support code for Mach is taken from Mach 3.0 by CMU,
944      and is under the following copyright terms:
945
946                Mach Operating System
947                Copyright (C) 1991,1990,1989 Carnegie Mellon University
948                All Rights Reserved.
949
950           Permission to use, copy, modify and distribute this software
951           and its documentation is hereby granted, provided that both
952           the copyright notice and this permission notice appear in all
953           copies of the software, derivative works or modified
954           versions, and any portions thereof, and that both notices
955           appear in supporting documentation.
956
957           CARNEGIE MELLON ALLOWS FREE USE OF THIS SOFTWARE IN ITS "AS
958           IS" CONDITION.  CARNEGIE MELLON DISCLAIMS ANY LIABILITY OF
959           ANY KIND FOR ANY DAMAGES WHATSOEVER RESULTING FROM THE USE OF
960           THIS SOFTWARE.
961
962           Carnegie Mellon requests users of this software to return to
963
964                 Software Distribution Coordinator
965                 School of Computer Science
966                 Carnegie Mellon University
967                 Pittsburgh PA 15213-3890
968
969           or <Software.Distribution@CS.CMU.EDU> any improvements or
970           extensions that they make and grant Carnegie Mellon the
971           rights to redistribute these changes.
972
973    * The code for the database library `libdb' comes from the 2.3
974      release of Berkeley DB. That code is under the same copyright as
975      4.4 BSD and also:
976
977                Copyright (C) 1990, 1993, 1994, 1995, 1996, 1997
978                Sleepycat Software.  All rights reserved.
979
980           Redistribution and use in source and binary forms, with or
981           without modification, are permitted provided that the
982           following conditions are met:
983
984             1. Redistributions of source code must retain the above
985                copyright notice, this list of conditions and the
986                following disclaimer.
987
988             2. Redistributions in binary form must reproduce the above
989                copyright notice, this list of conditions and the
990                following disclaimer in the documentation and/or other
991                materials provided with the distribution.
992
993             3. Redistributions in any form must be accompanied by
994                information on how to obtain complete source code for
995                the DB software and any accompanying software that uses
996                the DB software.  The source code must either be
997                included in the distribution or be available for no more
998                than the cost of distribution plus a nominal fee, and
999                must be freely redistributable under reasonable
1000                conditions.  For an executable file, complete source
1001                code means the source code for all modules it contains.
1002                It does not mean source code for modules or files that
1003                typically accompany the operating system on which the
1004                executable file runs, e.g., standard library modules or
1005                system header files.
1006
1007           THIS SOFTWARE IS PROVIDED BY SLEEPYCAT SOFTWARE "AS IS" AND
1008           ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
1009           TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
1010           A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL
1011           SLEEPYCAT SOFTWARE BE LIABLE FOR ANY DIRECT, INDIRECT,
1012           INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
1013           (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE
1014           GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
1015           INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
1016           WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
1017           NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
1018           THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
1019           DAMAGE.
1020
1021                Portions copyright (C) 1995, 1996
1022                The President and Fellows of Harvard University.
1023                All rights reserved.
1024
1025           Redistribution and use in source and binary forms, with or
1026           without modification, are permitted provided that the
1027           following conditions are met:
1028             1. Redistributions of source code must retain the above
1029                copyright notice, this list of conditions and the
1030                following disclaimer.
1031
1032             2. Redistributions in binary form must reproduce the above
1033                copyright notice, this list of conditions and the
1034                following disclaimer in the documentation and/or other
1035                materials provided with the distribution.
1036
1037             3. All advertising materials mentioning features or use of
1038                this software must display the following acknowledgement:
1039                      This product includes software developed by
1040                     Harvard University  and its contributors.
1041
1042             4. Neither the name of the University nor the names of its
1043                contributors may be used to endorse or promote products
1044                derived from this software without specific prior
1045                written permission.
1046
1047           THIS SOFTWARE IS PROVIDED BY HARVARD AND ITS CONTRIBUTORS "AS
1048           IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
1049           LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
1050           FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT
1051           SHALL HARVARD OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
1052           INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
1053           DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
1054           SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
1055           OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
1056           LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
1057           (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF
1058           THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY
1059           OF SUCH DAMAGE.
1060
1061           For a license to use, redistribute or sell DB software under
1062           conditions other than those described above, or to purchase
1063           support for this software, please contact Sleepycat Software
1064           at
1065
1066                 Sleepycat Software
1067                 394 E. Riding Dr.
1068                 Carlisle, MA 01741
1069                 USA
1070                 +1-508-287-4781
1071
1072           or <db@sleepycat.com>.
1073
1074