1 @c \input /gd/gnu/doc/texinfo
2 @c This is for making the `INSTALL' file for the distribution.
3 @c Makeinfo ignores it when processing the file from the include.
6 @node Maintenance, Copying, Library Summary, Top
7 @appendix Library Maintenance
10 * Installation:: How to configure, compile and
11 install the GNU C library.
12 * Reporting Bugs:: How to report bugs (if you want to
13 get them fixed) and other troubles
14 you may have with the GNU C library.
15 * Source Layout:: How to add new functions or header files
17 * Porting:: How to port the GNU C library to
18 a new machine or operating system.
19 * Contributors:: Contributors to the GNU C Library.
23 @appendixsec How to Install the GNU C Library
24 @cindex installing the library
26 Installation of the GNU C library is relatively simple, but usually
27 requires several GNU tools to be installed already.
29 (@pxref{Tools for Installation}, below.)
33 * Tools for Installation:: We recommend using these tools to build.
34 * Supported Configurations:: What systems the GNU C library runs on.
37 To configure the GNU C library for your system, run the shell script
38 @file{configure} with @code{sh}. Use an argument which is the
39 conventional GNU name for your system configuration---for example,
40 @samp{sparc-sun-sunos4.1}, for a Sun 4 running SunOS 4.1.
41 @xref{Installation, Installation, Installing GNU CC, gcc.info, Using and
42 Porting GNU CC}, for a full description of standard GNU configuration
43 names. If you omit the configuration name, @file{configure} will try to
44 guess one for you by inspecting the system it is running on. It may or
45 may not be able to come up with a guess, and the its guess might be
46 wrong. @file{configure} will tell you the canonical name of the chosen
47 configuration before proceeding.
49 Here are some options that you should specify (if appropriate) when
50 you run @code{configure}:
53 @item --with-binutils=@var{directory}
54 Use the binutils (assembler and linker) in @file{@var{directory}}, not
55 the ones the C compiler would default to. You could use this option if
56 the default binutils on your system cannot deal with all the constructs
57 in the GNU C library. (@code{configure} will detect the problem and
58 suppress these constructs, so the library will still be usable, but
59 functionality may be lost---for example, you can not build a shared libc
62 @c extra blank line makes it look better
66 Use this option if your computer lacks hardware floating-point support
67 and your operating system does not emulate an FPU.
69 @item --prefix=@var{directory}
70 Install machine-independent data files in subdirectories of
71 @file{@var{directory}}. (You can also set this in @file{configparms};
72 see below.) The default is to install in `/usr/local'.
74 @item --exec-prefix=@var{directory}
75 Install the library and other machine-dependent files in subdirectories
76 of @file{@var{directory}}. (You can also set this in
77 @file{configparms}; see below.) The default is to use <prefix>/bin
81 @itemx --disable-shared
82 Enable or disable building of an ELF shared library on systems that
83 support it. The default is to build the shared library on systems using
84 ELF when the GNU @code{binutils} are available.
86 @item --enable-profile
87 @itemx --disable-profile
88 Enable or disable building of the profiled C library, @samp{-lc_p}. The
89 default is to build the profiled library. You may wish to disable it if
90 you don't plan to do profiling, because it doubles the build time of
91 compiling just the unprofiled static library.
94 Enable building a highly-optimized but possibly undebuggable static C
95 library. This causes the normal static and shared (if enabled) C
96 libraries to be compiled with maximal optimization, including the
97 @samp{-fomit-frame-pointer} switch that makes debugging impossible on
98 many machines, and without debugging information (which makes the
99 binaries substantially smaller). An additional static library is
100 compiled with no optimization and full debugging information, and
101 installed as @samp{-lc_g}.
104 The simplest way to run @code{configure} is to do it in the directory
105 that contains the library sources. This prepares to build the library
106 in that very directory.
108 You can prepare to build the library in some other directory by going
109 to that other directory to run @code{configure}. In order to run
110 configure, you will have to specify a directory for it, like this:
115 ../configure sparc-sun-sunos4.1
119 @code{configure} looks for the sources in whatever directory you
120 specified for finding @code{configure} itself. It does not matter where
121 in the file system the source and build directories are---as long as you
122 specify the source directory when you run @code{configure}, you will get
125 This feature lets you keep sources and binaries in different
126 directories, and that makes it easy to build the library for several
127 different machines from the same set of sources. Simply create a
128 build directory for each target machine, and run @code{configure} in
129 that directory specifying the target machine's configuration name.
131 The library has a number of special-purpose configuration parameters.
132 These are defined in the file @file{Makeconfig}; see the comments in
133 that file for the details.
135 But don't edit the file @file{Makeconfig} yourself---instead, create a
136 file @file{configparms} in the directory where you are building the
137 library, and define in that file the parameters you want to specify.
138 @file{configparms} should @strong{not} be an edited copy of
139 @file{Makeconfig}; specify only the parameters that you want to
140 override. To see how to set these parameters, find the section of
141 @file{Makeconfig} that says ``These are the configuration variables.''
142 Then for each parameter that you want to change, copy the definition
143 from @file{Makeconfig} to your new @file{configparms} file, and change
144 the value as appropriate for your system.
146 It is easy to configure the GNU C library for cross-compilation by
147 setting a few variables in @file{configparms}. Set @code{CC} to the
148 cross-compiler for the target you configured the library for; it is
149 important to use this same @code{CC} value when running
150 @code{configure}, like this: @samp{CC=@var{target}-gcc configure
151 @var{target}}. Set @code{BUILD_CC} to the compiler to use for for
152 programs run on the build system as part of compiling the library. You
153 may need to set @code{AR} and @code{RANLIB} to cross-compiling versions
154 of @code{ar} and @code{ranlib} if the native tools are not configured to
155 work with object files for the target you configured for.
157 Some of the machine-dependent code for some machines uses extensions in
158 the GNU C compiler, so you may need to compile the library with GCC.
159 (In fact, all of the existing complete ports require GCC.)
162 To build the library and related programs, type @code{make}. This will
163 produce a lot of output, some of which may look like errors from
164 @code{make} (but isn't). Look for error messages from @code{make}
165 containing @samp{***}. Those indicate that something is really wrong.
167 To build and run some test programs which exercise some of the library
168 facilities, type @code{make check}. This will produce several files
169 with names like @file{@var{program}.out}.
171 To format the @cite{GNU C Library Reference Manual} for printing, type
172 @w{@code{make dvi}}. You need a working @TeX{} installation to do this.
174 To install the library and its header files, and the Info files of the
175 manual, type @code{make install}. This will build things if necessary,
176 before installing them. If you want to install the files in a different
177 place than the one specified at configuration time you can specify a
178 value for the Makefile variable @code{install_root} on the command line.
179 This is useful to create chroot'ed environment or to prepare binary
182 @node Tools for Installation
183 @appendixsubsec Recommended Tools to Install the GNU C Library
184 @cindex installation tools
185 @cindex tools, for installing library
187 We recommend installing the following GNU tools before attempting to
188 build the GNU C library:
194 You need the latest version of GNU @code{make}. Modifying the GNU C
195 Library to work with other @code{make} programs would be so hard that we
196 recommend you port GNU @code{make} instead. @strong{Really.} We
197 recommend version GNU @code{make} version 3.75, 3.76.1 or later.
198 Version 3.76 is known to have a bug which only shows up in big projects
199 like GNU @code{libc}.
204 On most platforms, the GNU C library can only be compiled with the GNU C
205 compiler. We recommend GCC version 2.7.2 or later; earlier versions may
208 On PowerPC, GCC versions dated earlier than 970904 are known not to work
209 (they crash), including 2.7.2.
212 @code{binutils} 2.8.1
214 Using the GNU @code{binutils} (assembler, linker, and related tools) is
215 preferable when possible, and they are required to build an ELF shared C
216 library. We recommend @code{binutils} version 2.8.1 or later; earlier
217 versions are known to have problems or to not support all architectures.
222 To correctly translate and install the Texinfo documentation you need
223 this version of the @code{texinfo} package. Former versions did not
224 understand all the tags used in the document and also the installation
225 mechanisms for the info files was not present or worked differently.
227 On some Debian Linux based systems the used @code{install-info} program
228 works differently. Here you have to run make like this:
231 make INSTALL_INFO=/path/to/GNU/install-info install
235 If you change any configuration file you will need also
243 and if you change any of the message translation files you will also need
247 @code{GNU gettext} 0.10 or later
251 If you upgrade your source tree using the patches made available you probably
252 will need those package above in any case.
255 @node Supported Configurations
256 @appendixsubsec Supported Configurations
257 @cindex configurations, all supported
259 The GNU C Library currently supports configurations that match the
263 alpha-@var{anything}-linux
264 i@var{x}86-@var{anything}-gnu
265 i@var{x}86-@var{anything}-linux
266 m68k-@var{anything}-linux
267 powerpc-@var{anything}-linux
268 sparc64-@var{anything}-linux
271 Former releases of this library (version 1.09.1 and perhaps earlier
272 versions) used to run on the following configurations:
276 alpha-@var{anything}-linuxecoff
277 i@var{x}86-@var{anything}-bsd4.3
278 i@var{x}86-@var{anything}-isc2.2
279 i@var{x}86-@var{anything}-isc3.@var{n}
280 i@var{x}86-@var{anything}-sco3.2
281 i@var{x}86-@var{anything}-sco3.2v4
282 i@var{x}86-@var{anything}-sysv
283 i@var{x}86-@var{anything}-sysv4
284 i@var{x}86-force_cpu386-none
285 i@var{x}86-sequent-bsd
292 m68k-sun-sunos4.@var{n}
293 mips-dec-ultrix4.@var{n}
294 mips-sgi-irix4.@var{n}
295 sparc-sun-solaris2.@var{n}
296 sparc-sun-sunos4.@var{n}
299 Since no one has volunteered to test and fix the above configurations,
300 these are not supported at the moment. It's expected that these don't
301 work anymore. Porting the library is not hard. If you are interested
302 in doing a port, please contact the glibc maintainers by sending
303 electronic mail to @email{bug-glibc@@prep.ai.mit.edu}.
305 Each case of @samp{i@var{x}86} can be @samp{i386}, @samp{i486},
306 @samp{i586}, or @samp{i686}. All of those configurations produce a
307 library that can run on any of these processors. The library will be
308 optimized for the specified processor, but will not use instructions not
309 available on all of them.
311 While no other configurations are supported, there are handy aliases for
312 these few. (These aliases work in other GNU software as well.)
316 hp320-bsd4.3 hp300bsd
324 sun3-sunos4.@var{n} sun3
325 sun4-solaris2.@var{n} sun4-sunos5.@var{n}
326 sun4-sunos4.@var{n} sun4
330 @appendixsec Reporting Bugs
331 @cindex reporting bugs
332 @cindex bugs, reporting
334 There are probably bugs in the GNU C library. There are certainly
335 errors and omissions in this manual. If you report them, they will get
336 fixed. If you don't, no one will ever know about them and they will
337 remain unfixed for all eternity, if not longer.
339 To report a bug, first you must find it. Hopefully, this will be the
340 hard part. Once you've found a bug, make sure it's really a bug. A
341 good way to do this is to see if the GNU C library behaves the same way
342 some other C library does. If so, probably you are wrong and the
343 libraries are right (but not necessarily). If not, one of the libraries
346 Once you're sure you've found a bug, try to narrow it down to the
347 smallest test case that reproduces the problem. In the case of a C
348 library, you really only need to narrow it down to one library
349 function call, if possible. This should not be too difficult.
351 The final step when you have a simple test case is to report the bug.
352 When reporting a bug, send your test case, the results you got, the
353 results you expected, what you think the problem might be (if you've
354 thought of anything), your system type, and the version of the GNU C
355 library which you are using. Also include the files
356 @file{config.status} and @file{config.make} which are created by running
357 @file{configure}; they will be in whatever directory was current when
358 you ran @file{configure}.
360 If you think you have found some way in which the GNU C library does not
361 conform to the ISO and POSIX standards (@pxref{Standards and
362 Portability}), that is definitely a bug. Report it!@refill
364 Send bug reports to the Internet address
365 @email{bug-glibc@@prep.ai.mit.edu} or the UUCP path
366 @email{mit-eddie!prep.ai.mit.edu!bug-glibc}. If you have other problems
367 with installation or use, please report those as well.@refill
369 If you are not sure how a function should behave, and this manual
370 doesn't tell you, that's a bug in the manual. Report that too! If the
371 function's behavior disagrees with the manual, then either the library
372 or the manual has a bug, so report the disagreement. If you find any
373 errors or omissions in this manual, please report them to the Internet
374 address @email{bug-glibc-manual@@prep.ai.mit.edu} or the UUCP path
375 @email{mit-eddie!prep.ai.mit.edu!bug-glibc-manual}.
378 @appendixsec Adding New Functions
380 The process of building the library is driven by the makefiles, which
381 make heavy use of special features of GNU @code{make}. The makefiles
382 are very complex, and you probably don't want to try to understand them.
383 But what they do is fairly straightforward, and only requires that you
384 define a few variables in the right places.
386 The library sources are divided into subdirectories, grouped by topic.
388 The @file{string} subdirectory has all the string-manipulation
389 functions, @file{math} has all the mathematical functions, etc.
391 Each subdirectory contains a simple makefile, called @file{Makefile},
392 which defines a few @code{make} variables and then includes the global
393 makefile @file{Rules} with a line like:
400 The basic variables that a subdirectory makefile defines are:
404 The name of the subdirectory, for example @file{stdio}.
405 This variable @strong{must} be defined.
408 The names of the header files in this section of the library,
409 such as @file{stdio.h}.
413 The names of the modules (source files) in this section of the library.
414 These should be simple names, such as @samp{strlen} (rather than
415 complete file names, such as @file{strlen.c}). Use @code{routines} for
416 modules that define functions in the library, and @code{aux} for
417 auxiliary modules containing things like data definitions. But the
418 values of @code{routines} and @code{aux} are just concatenated, so there
419 really is no practical difference.@refill
422 The names of test programs for this section of the library. These
423 should be simple names, such as @samp{tester} (rather than complete file
424 names, such as @file{tester.c}). @w{@samp{make tests}} will build and
425 run all the test programs. If a test program needs input, put the test
426 data in a file called @file{@var{test-program}.input}; it will be given to
427 the test program on its standard input. If a test program wants to be
428 run with arguments, put the arguments (all on a single line) in a file
429 called @file{@var{test-program}.args}. Test programs should exit with
430 zero status when the test passes, and nonzero status when the test
431 indicates a bug in the library or error in building.
434 The names of ``other'' programs associated with this section of the
435 library. These are programs which are not tests per se, but are other
436 small programs included with the library. They are built by
437 @w{@samp{make others}}.@refill
442 Files to be installed by @w{@samp{make install}}. Files listed in
443 @samp{install-lib} are installed in the directory specified by
444 @samp{libdir} in @file{configparms} or @file{Makeconfig}
445 (@pxref{Installation}). Files listed in @code{install-data} are
446 installed in the directory specified by @samp{datadir} in
447 @file{configparms} or @file{Makeconfig}. Files listed in @code{install}
448 are installed in the directory specified by @samp{bindir} in
449 @file{configparms} or @file{Makeconfig}.@refill
452 Other files from this subdirectory which should be put into a
453 distribution tar file. You need not list here the makefile itself or
454 the source and header files listed in the other standard variables.
455 Only define @code{distribute} if there are files used in an unusual way
456 that should go into the distribution.
459 Files which are generated by @file{Makefile} in this subdirectory.
460 These files will be removed by @w{@samp{make clean}}, and they will
461 never go into a distribution.
464 Extra object files which are built by @file{Makefile} in this
465 subdirectory. This should be a list of file names like @file{foo.o};
466 the files will actually be found in whatever directory object files are
467 being built in. These files will be removed by @w{@samp{make clean}}.
468 This variable is used for secondary object files needed to build
469 @code{others} or @code{tests}.
473 @appendixsec Porting the GNU C Library
475 The GNU C library is written to be easily portable to a variety of
476 machines and operating systems. Machine- and operating system-dependent
477 functions are well separated to make it easy to add implementations for
478 new machines or operating systems. This section describes the layout of
479 the library source tree and explains the mechanisms used to select
480 machine-dependent code to use.
482 All the machine-dependent and operating system-dependent files in the
483 library are in the subdirectory @file{sysdeps} under the top-level
484 library source directory. This directory contains a hierarchy of
485 subdirectories (@pxref{Hierarchy Conventions}).
487 Each subdirectory of @file{sysdeps} contains source files for a
488 particular machine or operating system, or for a class of machine or
489 operating system (for example, systems by a particular vendor, or all
490 machines that use IEEE 754 floating-point format). A configuration
491 specifies an ordered list of these subdirectories. Each subdirectory
492 implicitly appends its parent directory to the list. For example,
493 specifying the list @file{unix/bsd/vax} is equivalent to specifying the
494 list @file{unix/bsd/vax unix/bsd unix}. A subdirectory can also specify
495 that it implies other subdirectories which are not directly above it in
496 the directory hierarchy. If the file @file{Implies} exists in a
497 subdirectory, it lists other subdirectories of @file{sysdeps} which are
498 appended to the list, appearing after the subdirectory containing the
499 @file{Implies} file. Lines in an @file{Implies} file that begin with a
500 @samp{#} character are ignored as comments. For example,
501 @file{unix/bsd/Implies} contains:@refill
503 # BSD has Internet-related things.
507 and @file{unix/Implies} contains:
514 So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}.
516 @file{sysdeps} has two ``special'' subdirectories, called @file{generic}
517 and @file{stub}. These two are always implicitly appended to the list
518 of subdirectories (in that order), so you needn't put them in an
519 @file{Implies} file, and you should not create any subdirectories under
520 them intended to be new specific categories. @file{generic} is for
521 things that can be implemented in machine-independent C, using only
522 other machine-independent functions in the C library. @file{stub} is
523 for @dfn{stub} versions of functions which cannot be implemented on a
524 particular machine or operating system. The stub functions always
525 return an error, and set @code{errno} to @code{ENOSYS} (Function not
526 implemented). @xref{Error Reporting}.
528 A source file is known to be system-dependent by its having a version in
529 @file{generic} or @file{stub}; every generally-available function whose
530 implementation is system-dependent in should have either a generic or
531 stub implementation (there is no point in having both). Some rare functions
532 are only useful on specific systems and aren't defined at all on others;
533 these do not appear anywhere in the system-independent source code or makefiles
534 (including the @file{generic} and @file{stub} directories), only in the
535 system-dependent @file{Makefile} in the specific system's subdirectory.
537 If you come across a file that is in one of the main source directories
538 (@file{string}, @file{stdio}, etc.), and you want to write a machine- or
539 operating system-dependent version of it, move the file into
540 @file{sysdeps/generic} and write your new implementation in the
541 appropriate system-specific subdirectory. Note that if a file is to be
542 system-dependent, it @strong{must not} appear in one of the main source
545 There are a few special files that may exist in each subdirectory of
548 @comment Blank lines after items make the table look better.
552 A makefile for this machine or operating system, or class of machine or
553 operating system. This file is included by the library makefile
554 @file{Makerules}, which is used by the top-level makefile and the
555 subdirectory makefiles. It can change the variables set in the
556 including makefile or add new rules. It can use GNU @code{make}
557 conditional directives based on the variable @samp{subdir} (see above) to
558 select different sets of variables and rules for different sections of
559 the library. It can also set the @code{make} variable
560 @samp{sysdep-routines}, to specify extra modules to be included in the
561 library. You should use @samp{sysdep-routines} rather than adding
562 modules to @samp{routines} because the latter is used in determining
563 what to distribute for each subdirectory of the main source tree.@refill
565 Each makefile in a subdirectory in the ordered list of subdirectories to
566 be searched is included in order. Since several system-dependent
567 makefiles may be included, each should append to @samp{sysdep-routines}
568 rather than simply setting it:
571 sysdep-routines := $(sysdep-routines) foo bar
577 This file contains the names of new whole subdirectories under the
578 top-level library source tree that should be included for this system.
579 These subdirectories are treated just like the system-independent
580 subdirectories in the library source tree, such as @file{stdio} and
583 Use this when there are completely new sets of functions and header
584 files that should go into the library for the system this subdirectory
585 of @file{sysdeps} implements. For example,
586 @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
587 directory contains various network-oriented operations which only make
588 sense to put in the library on systems that support the Internet.@refill
592 This file contains the names of files (relative to the subdirectory of
593 @file{sysdeps} in which it appears) which should be included in the
594 distribution. List any new files used by rules in the @file{Makefile}
595 in the same directory, or header files used by the source files in that
596 directory. You don't need to list files that are implementations
597 (either C or assembly source) of routines whose names are given in the
598 machine-independent makefiles in the main source tree.
602 This file is a shell script fragment to be run at configuration time.
603 The top-level @file{configure} script uses the shell @code{.} command to
604 read the @file{configure} file in each system-dependent directory
605 chosen, in order. The @file{configure} files are often generated from
606 @file{configure.in} files using Autoconf.
608 A system-dependent @file{configure} script will usually add things to
609 the shell variables @samp{DEFS} and @samp{config_vars}; see the
610 top-level @file{configure} script for details. The script can check for
611 @w{@samp{--with-@var{package}}} options that were passed to the
612 top-level @file{configure}. For an option
613 @w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the
614 shell variable @w{@samp{with_@var{package}}} (with any dashes in
615 @var{package} converted to underscores) to @var{value}; if the option is
616 just @w{@samp{--with-@var{package}}} (no argument), then it sets
617 @w{@samp{with_@var{package}}} to @samp{yes}.
621 This file is an Autoconf input fragment to be processed into the file
622 @file{configure} in this subdirectory. @xref{Introduction,,,
623 autoconf.info, Autoconf: Generating Automatic Configuration Scripts},
624 for a description of Autoconf. You should write either @file{configure}
625 or @file{configure.in}, but not both. The first line of
626 @file{configure.in} should invoke the @code{m4} macro
627 @samp{GLIBC_PROVIDES}. This macro does several @code{AC_PROVIDE} calls
628 for Autoconf macros which are used by the top-level @file{configure}
629 script; without this, those macros might be invoked again unnecessarily
633 That is the general system for how system-dependencies are isolated.
635 The next section explains how to decide what directories in
636 @file{sysdeps} to use. @ref{Porting to Unix}, has some tips on porting
637 the library to Unix variants.
641 * Hierarchy Conventions:: The layout of the @file{sysdeps} hierarchy.
642 * Porting to Unix:: Porting the library to an average
646 @node Hierarchy Conventions
647 @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy
649 A GNU configuration name has three parts: the CPU type, the
650 manufacturer's name, and the operating system. @file{configure} uses
651 these to pick the list of system-dependent directories to look for. If
652 the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
653 directory @file{@var{machine}/fpu} is also used. The operating system
654 often has a @dfn{base operating system}; for example, if the operating
655 system is @samp{sunos4.1}, the base operating system is @samp{unix/bsd}.
656 The algorithm used to pick the list of directories is simple:
657 @file{configure} makes a list of the base operating system,
658 manufacturer, CPU type, and operating system, in that order. It then
659 concatenates all these together with slashes in between, to produce a
660 directory name; for example, the configuration @w{@samp{sparc-sun-sunos4.1}}
661 results in @file{unix/bsd/sun/sparc/sunos4.1}. @file{configure} then
662 tries removing each element of the list in turn, so
663 @file{unix/bsd/sparc} and @file{sun/sparc} are also tried, among others.
664 Since the precise version number of the operating system is often not
665 important, and it would be very inconvenient, for example, to have
666 identical @file{sunos4.1.1} and @file{sunos4.1.2} directories,
667 @file{configure} tries successively less specific operating system names
668 by removing trailing suffixes starting with a period.
670 As an example, here is the complete list of directories that would be
671 tried for the configuration @w{@samp{sparc-sun-sunos4.1}} (without the
672 @w{@samp{--nfp}} option):
676 unix/bsd/sun/sunos4.1/sparc
677 unix/bsd/sun/sunos4.1
678 unix/bsd/sun/sunos4/sparc
680 unix/bsd/sun/sunos/sparc
684 unix/bsd/sunos4.1/sparc
686 unix/bsd/sunos4/sparc
692 unix/sun/sunos4.1/sparc
694 unix/sun/sunos4/sparc
725 Different machine architectures are conventionally subdirectories at the
726 top level of the @file{sysdeps} directory tree. For example,
727 @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}. These contain
728 files specific to those machine architectures, but not specific to any
729 particular operating system. There might be subdirectories for
730 specializations of those architectures, such as
731 @w{@file{sysdeps/m68k/68020}}. Code which is specific to the
732 floating-point coprocessor used with a particular machine should go in
733 @w{@file{sysdeps/@var{machine}/fpu}}.
735 There are a few directories at the top level of the @file{sysdeps}
736 hierarchy that are not for particular machine architectures.
741 As described above (@pxref{Porting}), these are the two subdirectories
742 that every configuration implicitly uses after all others.
745 This directory is for code using the IEEE 754 floating-point format,
746 where the C type @code{float} is IEEE 754 single-precision format, and
747 @code{double} is IEEE 754 double-precision format. Usually this
748 directory is referred to in the @file{Implies} file in a machine
749 architecture-specific directory, such as @file{m68k/Implies}.
752 This directory contains implementations of things in the library in
753 terms of @sc{POSIX.1} functions. This includes some of the @sc{POSIX.1}
754 functions themselves. Of course, @sc{POSIX.1} cannot be completely
755 implemented in terms of itself, so a configuration using just
756 @file{posix} cannot be complete.
759 This is the directory for Unix-like things. @xref{Porting to Unix}.
760 @file{unix} implies @file{posix}. There are some special-purpose
761 subdirectories of @file{unix}:
765 This directory is for things common to both BSD and System V release 4.
766 Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
769 This directory is for @code{socket} and related functions on Unix systems.
770 The @file{inet} top-level subdirectory is enabled by @file{unix/inet/Subdirs}.
771 @file{unix/common} implies @file{unix/inet}.
775 This is the directory for things based on the Mach microkernel from CMU
776 (including the GNU operating system). Other basic operating systems
777 (VMS, for example) would have their own directories at the top level of
778 the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
781 @node Porting to Unix
782 @appendixsubsec Porting the GNU C Library to Unix Systems
784 Most Unix systems are fundamentally very similar. There are variations
785 between different machines, and variations in what facilities are
786 provided by the kernel. But the interface to the operating system
787 facilities is, for the most part, pretty uniform and simple.
789 The code for Unix systems is in the directory @file{unix}, at the top
790 level of the @file{sysdeps} hierarchy. This directory contains
791 subdirectories (and subdirectory trees) for various Unix variants.
793 The functions which are system calls in most Unix systems are
794 implemented in assembly code, which is generated automatically from
795 specifications in the file @file{sysdeps/unix/syscalls.list}. Some
796 special system calls are implemented in files that are named with a
797 suffix of @samp{.S}; for example, @file{_exit.S}. Files ending in
798 @samp{.S} are run through the C preprocessor before being fed to the
801 These files all use a set of macros that should be defined in
802 @file{sysdep.h}. The @file{sysdep.h} file in @file{sysdeps/unix}
803 partially defines them; a @file{sysdep.h} file in another directory must
804 finish defining them for the particular machine and operating system
805 variant. See @file{sysdeps/unix/sysdep.h} and the machine-specific
806 @file{sysdep.h} implementations to see what these macros are and what
807 they should do.@refill
809 The system-specific makefile for the @file{unix} directory (that is, the
810 file @file{sysdeps/unix/Makefile}) gives rules to generate several files
811 from the Unix system you are building the library on (which is assumed
812 to be the target system you are building the library @emph{for}). All
813 the generated files are put in the directory where the object files are
814 kept; they should not affect the source tree itself. The files
815 generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
816 @file{errlist.c} (for the @file{stdio} section of the library).
819 @c This section might be a good idea if it is finished,
820 @c but there's no point including it as it stands. --rms
821 @c @appendixsec Compatibility with Traditional C
823 @c ??? This section is really short now. Want to keep it? --roland
825 Although the GNU C library implements the @w{ISO C} library facilities, you
826 @emph{can} use the GNU C library with traditional, ``pre-ISO'' C
827 compilers. However, you need to be careful because the content and
828 organization of the GNU C library header files differs from that of
829 traditional C implementations. This means you may need to make changes
830 to your program in order to get it to compile.
834 @appendixsec Contributors to the GNU C Library
836 The GNU C library was written originally by Roland McGrath. Some parts
837 of the library were contributed or worked on by other people.
841 The @code{getopt} function and related code were written by
842 Richard Stallman, @w{David J. MacKenzie}, and @w{Roland McGrath}.
845 The merge sort function @code{qsort} was written by Michael J. Haertel.
848 The quick sort function used as a fallback by @code{qsort} was written
849 by Douglas C. Schmidt.
852 The memory allocation functions @code{malloc}, @code{realloc} and
853 @code{free} and related code were written by Michael J. Haertel.
856 Fast implementations of many of the string functions (@code{memcpy},
857 @code{strlen}, etc.) were written by Torbj@"orn Granlund.
860 The @file{tar.h} header file was written by David J. MacKenzie.
863 The port to the MIPS DECStation running Ultrix 4
864 (@code{mips-dec-ultrix4})
865 was contributed by Brendan Kehoe and Ian Lance Taylor.
868 The DES encryption function @code{crypt} and related functions were
869 contributed by Michael Glad.
872 The @code{ftw} and @code{nftw} function was contributed by Ulrich Drepper.
875 The startup code to support SunOS shared libraries was contributed by
879 The @code{mktime} function was contributed by Paul Eggert.
882 The port to the Sequent Symmetry running Dynix version 3
883 (@code{i386-sequent-bsd}) was contributed by Jason Merrill.
886 The timezone support code is derived from the public-domain timezone
887 package by Arthur David Olson and his many contributors.
890 The port to the DEC Alpha running OSF/1 (@code{alpha-dec-osf1}) was
891 contributed by Brendan Kehoe, using some code written by Roland McGrath.
894 The port to SGI machines running Irix 4 (@code{mips-sgi-irix4}) was
895 contributed by Tom Quinn.
898 The port of the Mach and Hurd code to the MIPS architecture
899 (@code{mips-@var{anything}-gnu}) was contributed by Kazumoto Kojima.
902 The floating-point printing function used by @code{printf} and friends
903 and the floating-point reading function used by @code{scanf},
904 @code{strtod} and friends were written by Ulrich Drepper. The
905 multi-precision integer functions used in those functions are taken from
906 GNU MP, which was contributed by Torbj@"orn Granlund.
909 The internationalization support in the library, and the support
910 programs @code{locale} and @code{localedef}, were written by Ulrich
911 Drepper. Ulrich Drepper adapted the support code for message catalogs
912 (@file{libintl.h}, etc.) from the GNU @code{gettext} package, which he
913 also wrote. He also contributed the @code{catgets} support and the
914 entire suite of multi-byte and wide-character support functions
915 (@file{wctype.h}, @file{wchar.h}, etc.).
918 The implementations of the @file{nsswitch.conf} mechanism and the files
919 and DNS backends for it were designed and written by Ulrich Drepper and
920 Roland McGrath, based on a backend interface defined by Peter Eriksson.
923 The port to Linux i386/ELF (@code{i386-@var{anything}-linux}) was
924 contributed by Ulrich Drepper, based in large part on work done in
925 Hongjiu Lu's Linux version of the GNU C Library.
928 The port to Linux/m68k (@code{m68k-@var{anything}-linux}) was
929 contributed by Andreas Schwab.
932 The ports to Linux/ARM (@code{arm-@var{ANYTHING}-linuxaout}) and ARM
933 standalone (@code{arm-@var{ANYTHING}-none}), as well as parts of the
934 IPv6 support code, were contributed by Philip Blundell.
937 Richard Henderson contributed the ELF dynamic linking code and other
938 support for the Alpha processor.
941 David Mosberger-Tang contributed the port to Linux/Alpha
942 (@code{alpha-@var{anything}-linux}).
945 The port to Linux on PowerPC (@code{powerpc-@var{anything}-linux})
946 was contributed by Geoffrey Keating.
949 Miles Bader wrote the argp argument-parsing package, and the argz/envz
953 Stephen R. van den Berg contributed a highly-optimized @code{strstr} function.
956 Ulrich Drepper contributed the @code{hsearch} and @code{drand48}
957 families of functions; reentrant @samp{@dots{}@code{_r}} versions of the
958 @code{random} family; System V shared memory and IPC support code; and
959 several highly-optimized string functions for i@var{x}86 processors.
962 The math functions are taken from @code{fdlibm-5.1} by Sun
963 Microsystems, as modified by J.T. Conklin, Ian Lance Taylor,
964 Ulrich Drepper, Andreas Schwab, and Roland McGrath.
967 The @code{libio} library used to implement @code{stdio} functions on
968 some platforms was written by Per Bothner and modified by Ulrich Drepper.
971 The Internet-related code (most of the @file{inet} subdirectory) and
972 several other miscellaneous functions and header files have been
973 included from 4.4 BSD with little or no modification.
975 All code incorporated from 4.4 BSD is under the following copyright:
979 Copyright @copyright{} 1991 Regents of the University of California.
983 Redistribution and use in source and binary forms, with or without
984 modification, are permitted provided that the following conditions
989 Redistributions of source code must retain the above copyright
990 notice, this list of conditions and the following disclaimer.
992 Redistributions in binary form must reproduce the above copyright
993 notice, this list of conditions and the following disclaimer in the
994 documentation and/or other materials provided with the distribution.
996 All advertising materials mentioning features or use of this software
997 must display the following acknowledgement:
999 This product includes software developed by the University of
1000 California, Berkeley and its contributors.
1003 Neither the name of the University nor the names of its contributors
1004 may be used to endorse or promote products derived from this software
1005 without specific prior written permission.
1008 @sc{this software is provided by the regents and contributors ``as is'' and
1009 any express or implied warranties, including, but not limited to, the
1010 implied warranties of merchantability and fitness for a particular purpose
1011 are disclaimed. in no event shall the regents or contributors be liable
1012 for any direct, indirect, incidental, special, exemplary, or consequential
1013 damages (including, but not limited to, procurement of substitute goods
1014 or services; loss of use, data, or profits; or business interruption)
1015 however caused and on any theory of liability, whether in contract, strict
1016 liability, or tort (including negligence or otherwise) arising in any way
1017 out of the use of this software, even if advised of the possibility of
1022 The random number generation functions @code{random}, @code{srandom},
1023 @code{setstate} and @code{initstate}, which are also the basis for the
1024 @code{rand} and @code{srand} functions, were written by Earl T. Cohen
1025 for the University of California at Berkeley and are copyrighted by the
1026 Regents of the University of California. They have undergone minor
1027 changes to fit into the GNU C library and to fit the @w{ISO C} standard,
1028 but the functional code is Berkeley's.@refill
1031 The Internet resolver code is taken directly from BIND 4.9.5, which is
1032 under both the Berkeley copyright above and also:
1035 Portions Copyright @copyright{} 1993 by Digital Equipment Corporation.
1037 Permission to use, copy, modify, and distribute this software for any
1038 purpose with or without fee is hereby granted, provided that the above
1039 copyright notice and this permission notice appear in all copies, and
1040 that the name of Digital Equipment Corporation not be used in
1041 advertising or publicity pertaining to distribution of the document or
1042 software without specific, written prior permission.
1044 @sc{the software is provided ``as is'' and digital equipment corp.
1045 disclaims all warranties with regard to this software, including all
1046 implied warranties of merchantability and fitness. in no event shall
1047 digital equipment corporation be liable for any special, direct,
1048 indirect, or consequential damages or any damages whatsoever resulting
1049 from loss of use, data or profits, whether in an action of contract,
1050 negligence or other tortious action, arising out of or in connection
1051 with the use or performance of this software.}
1055 The code to support Sun RPC is taken verbatim from Sun's
1056 @w{@sc{rpcsrc-4.0}} distribution, and is covered by this copyright:
1060 Copyright @copyright{} 1984, Sun Microsystems, Inc.
1063 Sun RPC is a product of Sun Microsystems, Inc. and is provided for
1064 unrestricted use provided that this legend is included on all tape media
1065 and as a part of the software program in whole or part. Users may copy
1066 or modify Sun RPC without charge, but are not authorized to license or
1067 distribute it to anyone else except as part of a product or program
1068 developed by the user.
1070 @sc{sun rpc is provided as is with no warranties of any kind including the
1071 warranties of design, merchantibility and fitness for a particular
1072 purpose, or arising from a course of dealing, usage or trade practice.}
1074 Sun RPC is provided with no support and without any obligation on the
1075 part of Sun Microsystems, Inc. to assist in its use, correction,
1076 modification or enhancement.
1078 @sc{sun microsystems, inc. shall have no liability with respect to the
1079 infringement of copyrights, trade secrets or any patents by sun rpc
1080 or any part thereof.}
1082 In no event will Sun Microsystems, Inc. be liable for any lost revenue
1083 or profits or other special, indirect and consequential damages, even if
1084 Sun has been advised of the possibility of such damages.
1087 Sun Microsystems, Inc.
1089 Mountain View, California 94043
1094 Some of the support code for Mach is taken from Mach 3.0 by CMU,
1095 and is under the following copyright terms:
1099 Mach Operating System
1100 Copyright @copyright{} 1991,1990,1989 Carnegie Mellon University
1101 All Rights Reserved.
1104 Permission to use, copy, modify and distribute this software and its
1105 documentation is hereby granted, provided that both the copyright
1106 notice and this permission notice appear in all copies of the
1107 software, derivative works or modified versions, and any portions
1108 thereof, and that both notices appear in supporting documentation.
1110 @sc{carnegie mellon allows free use of this software in its ``as is''
1111 condition. carnegie mellon disclaims any liability of any kind for
1112 any damages whatsoever resulting from the use of this software.}
1114 Carnegie Mellon requests users of this software to return to
1117 Software Distribution Coordinator
1118 School of Computer Science
1119 Carnegie Mellon University
1120 Pittsburgh PA 15213-3890
1124 or @email{Software.Distribution@@CS.CMU.EDU} any improvements or
1125 extensions that they make and grant Carnegie Mellon the rights to
1126 redistribute these changes.
1130 The code for the database library @file{libdb} comes from the 2.3
1131 release of Berkeley DB. That code is under the same copyright as 4.4 BSD
1136 Copyright @copyright{} 1990, 1993, 1994, 1995, 1996, 1997
1137 Sleepycat Software. All rights reserved.
1140 Redistribution and use in source and binary forms, with or without
1141 modification, are permitted provided that the following conditions
1146 Redistributions of source code must retain the above copyright
1147 notice, this list of conditions and the following disclaimer.
1149 Redistributions in binary form must reproduce the above copyright
1150 notice, this list of conditions and the following disclaimer in the
1151 documentation and/or other materials provided with the distribution.
1153 Redistributions in any form must be accompanied by information on
1154 how to obtain complete source code for the DB software and any
1155 accompanying software that uses the DB software. The source code
1156 must either be included in the distribution or be available for no
1157 more than the cost of distribution plus a nominal fee, and must be
1158 freely redistributable under reasonable conditions. For an
1159 executable file, complete source code means the source code for all
1160 modules it contains. It does not mean source code for modules or
1161 files that typically accompany the operating system on which the
1162 executable file runs, e.g., standard library modules or system
1166 @sc{this software is provided by sleepycat software ``as is'' and
1167 any express or implied warranties, including, but not limited to, the
1168 implied warranties of merchantability and fitness for a particular purpose
1169 are disclaimed. in no event shall sleepycat software be liable
1170 for any direct, indirect, incidental, special, exemplary, or consequential
1171 damages (including, but not limited to, procurement of substitute goods
1172 or services; loss of use, data, or profits; or business interruption)
1173 however caused and on any theory of liability, whether in contract, strict
1174 liability, or tort (including negligence or otherwise) arising in any way
1175 out of the use of this software, even if advised of the possibility of
1179 Portions copyright @copyright{} 1995, 1996
1180 The President and Fellows of Harvard University.
1181 All rights reserved.
1184 Redistribution and use in source and binary forms, with or without
1185 modification, are permitted provided that the following conditions
1189 Redistributions of source code must retain the above copyright
1190 notice, this list of conditions and the following disclaimer.
1192 Redistributions in binary form must reproduce the above copyright
1193 notice, this list of conditions and the following disclaimer in the
1194 documentation and/or other materials provided with the distribution.
1196 All advertising materials mentioning features or use of this software
1197 must display the following acknowledgement:
1199 This product includes software developed by Harvard University
1200 and its contributors.
1203 Neither the name of the University nor the names of its contributors
1204 may be used to endorse or promote products derived from this software
1205 without specific prior written permission.
1208 @sc{this software is provided by harvard and its contributors ``as is'' and
1209 any express or implied warranties, including, but not limited to, the
1210 implied warranties of merchantability and fitness for a particular purpose
1211 are disclaimed. in no event shall harvard or its contributors be liable
1212 for any direct, indirect, incidental, special, exemplary, or consequential
1213 damages (including, but not limited to, procurement of substitute goods
1214 or services; loss of use, data, or profits; or business interruption)
1215 however caused and on any theory of liability, whether in contract, strict
1216 liability, or tort (including negligence or otherwise) arising in any way
1217 out of the use of this software, even if advised of the possibility of
1221 For a license to use, redistribute or sell DB software under conditions
1222 other than those described above, or to purchase support for this
1223 software, please contact Sleepycat Software at
1233 or @email{db@@sleepycat.com}.