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}:
54 Use this option if you plan to use GNU @code{ld} to link programs with
55 the GNU C Library. (We strongly recommend that you do.) This option
56 enables use of features that exist only in GNU @code{ld}; so if you
57 configure for GNU @code{ld} you must use GNU @code{ld} @emph{every time}
58 you link with the GNU C Library, and when building it.
61 Use this option if you plan to use the GNU assembler, @code{gas}, when
62 building the GNU C Library. On some systems, the library may not build
63 properly if you do @emph{not} use @code{gas}.
65 @item --with-gnu-binutils
66 This option implies both @w{@samp{--with-gnu-ld}} and @w{@samp{--with-gnu-as}}.
67 On systems where GNU tools are the system tools, there is no need to
68 specify this option. These include GNU, GNU/Linux, and free BSD systems.
70 @c extra blank line makes it look better
74 Use this option if your computer lacks hardware floating-point support.
76 @item --prefix=@var{directory}
77 Install machine-independent data files in subdirectories of
78 @file{@var{directory}}. (You can also set this in @file{configparms};
79 see below.) The default is to install in `/usr/local'.
81 @item --exec-prefix=@var{directory}
82 Install the library and other machine-dependent files in subdirectories
83 of @file{@var{directory}}. (You can also set this in
84 @file{configparms}; see below.) The default is to use <prefix>/bin
88 @itemx --disable-shared
89 Enable or disable building of an ELF shared library on systems that
90 support it. The default is to build the shared library on systems using
91 ELF when the GNU @code{binutils} are available.
93 @item --enable-profile
94 @itemx --disable-profile
95 Enable or disable building of the profiled C library, @samp{-lc_p}. The
96 default is to build the profiled library. You may wish to disable it if
97 you don't plan to do profiling, because it doubles the build time of
98 compiling just the unprofiled static library.
100 @item --enable-omitfp
101 Enable building a highly-optimized but possibly undebuggable static C
102 library. This causes the normal static and shared (if enabled) C
103 libraries to be compiled with maximal optimization, including the
104 @samp{-fomit-frame-pointer} switch that makes debugging impossible on
105 many machines, and without debugging information (which makes the
106 binaries substantially smaller). An additional static library is
107 compiled with no optimization and full debugging information, and
108 installed as @samp{-lc_g}.
111 The simplest way to run @code{configure} is to do it in the directory
112 that contains the library sources. This prepares to build the library
113 in that very directory.
115 You can prepare to build the library in some other directory by going
116 to that other directory to run @code{configure}. In order to run
117 configure, you will have to specify a directory for it, like this:
122 ../configure sparc-sun-sunos4.1
126 @code{configure} looks for the sources in whatever directory you
127 specified for finding @code{configure} itself. It does not matter where
128 in the file system the source and build directories are---as long as you
129 specify the source directory when you run @code{configure}, you will get
132 This feature lets you keep sources and binaries in different
133 directories, and that makes it easy to build the library for several
134 different machines from the same set of sources. Simply create a
135 build directory for each target machine, and run @code{configure} in
136 that directory specifying the target machine's configuration name.
138 The library has a number of special-purpose configuration parameters.
139 These are defined in the file @file{Makeconfig}; see the comments in
140 that file for the details.
142 But don't edit the file @file{Makeconfig} yourself---instead, create a
143 file @file{configparms} in the directory where you are building the
144 library, and define in that file the parameters you want to specify.
145 @file{configparms} should @strong{not} be an edited copy of
146 @file{Makeconfig}; specify only the parameters that you want to
147 override. To see how to set these parameters, find the section of
148 @file{Makeconfig} that says ``These are the configuration variables.''
149 Then for each parameter that you want to change, copy the definition
150 from @file{Makeconfig} to your new @file{configparms} file, and change
151 the value as appropriate for your system.
153 It is easy to configure the GNU C library for cross-compilation by
154 setting a few variables in @file{configparms}. Set @code{CC} to the
155 cross-compiler for the target you configured the library for; it is
156 important to use this same @code{CC} value when running
157 @code{configure}, like this: @samp{CC=@var{target}-gcc configure
158 @var{target}}. Set @code{BUILD_CC} to the compiler to use for for
159 programs run on the build system as part of compiling the library. You
160 may need to set @code{AR} and @code{RANLIB} to cross-compiling versions
161 of @code{ar} and @code{ranlib} if the native tools are not configured to
162 work with object files for the target you configured for.
164 Some of the machine-dependent code for some machines uses extensions in
165 the GNU C compiler, so you may need to compile the library with GCC.
166 (In fact, all of the existing complete ports require GCC.)
169 To build the library and related programs, type @code{make}. This will
170 produce a lot of output, some of which may look like errors from
171 @code{make} (but isn't). Look for error messages from @code{make}
172 containing @samp{***}. Those indicate that something is really wrong.
174 To build and run some test programs which exercise some of the library
175 facilities, type @code{make check}. This will produce several files
176 with names like @file{@var{program}.out}.
178 To format the @cite{GNU C Library Reference Manual} for printing, type
179 @w{@code{make dvi}}. You need a working @TeX{} installation to do this.
181 To install the library and its header files, and the Info files of the
182 manual, type @code{make install}. This will build things if necessary,
183 before installing them. If you want to install the files in a different
184 place than the one specified at configuration time you can specify a
185 value for the Makefile variable @code{install_root} on the command line.
186 This is useful to create chroot'ed environment or to prepare binary
189 @node Tools for Installation
190 @appendixsubsec Recommended Tools to Install the GNU C Library
191 @cindex installation tools
192 @cindex tools, for installing library
194 We recommend installing the following GNU tools before attempting to
195 build the GNU C library:
201 You need the latest version of GNU @code{make}. Modifying the GNU C
202 Library to work with other @code{make} programs would be so hard that we
203 recommend you port GNU @code{make} instead. @strong{Really.} We
204 recommend version GNU @code{make} version 3.75, 3.76.1 or later.
205 Version 3.76 is known to have a bug which only shows up in big projects
206 like GNU @code{libc}.
211 On most platforms, the GNU C library can only be compiled with the GNU C
212 compiler. We recommend GCC version 2.7.2 or later; earlier versions may
215 On PowerPC, GCC versions dated earlier than 970904 are known not to work
216 (they crash), including 2.7.2.
219 @code{binutils} 2.8.1
221 Using the GNU @code{binutils} (assembler, linker, and related tools) is
222 preferable when possible, and they are required to build an ELF shared C
223 library. We recommend @code{binutils} version 2.8.1 or later; earlier
224 versions are known to have problems or to not support all architectures.
229 To correctly translate and install the Texinfo documentation you need
230 this version of the @code{texinfo} package. Former versions did not
231 understand all the tags used in the document and also the installation
232 mechanisms for the info files was not present or worked differently.
234 On some Debian Linux based systems the used @code{install-info} program
235 works differently. Here you have to run make like this:
238 make INSTALL_INFO=/path/to/GNU/install-info install
242 If you change any configuration file you will need also
250 and if you change any of the message translation files you will also need
254 @code{GNU gettext} 0.10 or later
258 If you upgrade your source tree using the patches made available you probably
259 will need those package above in any case.
262 @node Supported Configurations
263 @appendixsubsec Supported Configurations
264 @cindex configurations, all supported
266 The GNU C Library currently supports configurations that match the
270 alpha-@var{anything}-linux
271 i@var{x}86-@var{anything}-gnu
272 i@var{x}86-@var{anything}-linux
273 m68k-@var{anything}-linux
274 powerpc-@var{anything}-linux
277 Former releases of this library (version 1.09.1 and perhaps earlier
278 versions) used to run on the following configurations:
282 alpha-@var{anything}-linuxecoff
283 i@var{x}86-@var{anything}-bsd4.3
284 i@var{x}86-@var{anything}-isc2.2
285 i@var{x}86-@var{anything}-isc3.@var{n}
286 i@var{x}86-@var{anything}-sco3.2
287 i@var{x}86-@var{anything}-sco3.2v4
288 i@var{x}86-@var{anything}-sysv
289 i@var{x}86-@var{anything}-sysv4
290 i@var{x}86-force_cpu386-none
291 i@var{x}86-sequent-bsd
298 m68k-sun-sunos4.@var{n}
299 mips-dec-ultrix4.@var{n}
300 mips-sgi-irix4.@var{n}
301 sparc-sun-solaris2.@var{n}
302 sparc-sun-sunos4.@var{n}
305 Since no one has volunteered to test and fix the above configurations,
306 these are not supported at the moment. It's expected that these don't
307 work anymore. Porting the library is not hard. If you are interested
308 in doing a port, please contact the glibc maintainers by sending
309 electronic mail to @email{bug-glibc@@prep.ai.mit.edu}.
311 Each case of @samp{i@var{x}86} can be @samp{i386}, @samp{i486},
312 @samp{i586}, or @samp{i686}. All of those configurations produce a
313 library that can run on any of these processors. The library will be
314 optimized for the specified processor, but will not use instructions not
315 available on all of them.
317 While no other configurations are supported, there are handy aliases for
318 these few. (These aliases work in other GNU software as well.)
322 hp320-bsd4.3 hp300bsd
330 sun3-sunos4.@var{n} sun3
331 sun4-solaris2.@var{n} sun4-sunos5.@var{n}
332 sun4-sunos4.@var{n} sun4
336 @appendixsec Reporting Bugs
337 @cindex reporting bugs
338 @cindex bugs, reporting
340 There are probably bugs in the GNU C library. There are certainly
341 errors and omissions in this manual. If you report them, they will get
342 fixed. If you don't, no one will ever know about them and they will
343 remain unfixed for all eternity, if not longer.
345 To report a bug, first you must find it. Hopefully, this will be the
346 hard part. Once you've found a bug, make sure it's really a bug. A
347 good way to do this is to see if the GNU C library behaves the same way
348 some other C library does. If so, probably you are wrong and the
349 libraries are right (but not necessarily). If not, one of the libraries
352 Once you're sure you've found a bug, try to narrow it down to the
353 smallest test case that reproduces the problem. In the case of a C
354 library, you really only need to narrow it down to one library
355 function call, if possible. This should not be too difficult.
357 The final step when you have a simple test case is to report the bug.
358 When reporting a bug, send your test case, the results you got, the
359 results you expected, what you think the problem might be (if you've
360 thought of anything), your system type, and the version of the GNU C
361 library which you are using. Also include the files
362 @file{config.status} and @file{config.make} which are created by running
363 @file{configure}; they will be in whatever directory was current when
364 you ran @file{configure}.
366 If you think you have found some way in which the GNU C library does not
367 conform to the ISO and POSIX standards (@pxref{Standards and
368 Portability}), that is definitely a bug. Report it!@refill
370 Send bug reports to the Internet address
371 @email{bug-glibc@@prep.ai.mit.edu} or the UUCP path
372 @email{mit-eddie!prep.ai.mit.edu!bug-glibc}. If you have other problems
373 with installation or use, please report those as well.@refill
375 If you are not sure how a function should behave, and this manual
376 doesn't tell you, that's a bug in the manual. Report that too! If the
377 function's behavior disagrees with the manual, then either the library
378 or the manual has a bug, so report the disagreement. If you find any
379 errors or omissions in this manual, please report them to the Internet
380 address @email{bug-glibc-manual@@prep.ai.mit.edu} or the UUCP path
381 @email{mit-eddie!prep.ai.mit.edu!bug-glibc-manual}.
384 @appendixsec Adding New Functions
386 The process of building the library is driven by the makefiles, which
387 make heavy use of special features of GNU @code{make}. The makefiles
388 are very complex, and you probably don't want to try to understand them.
389 But what they do is fairly straightforward, and only requires that you
390 define a few variables in the right places.
392 The library sources are divided into subdirectories, grouped by topic.
394 The @file{string} subdirectory has all the string-manipulation
395 functions, @file{math} has all the mathematical functions, etc.
397 Each subdirectory contains a simple makefile, called @file{Makefile},
398 which defines a few @code{make} variables and then includes the global
399 makefile @file{Rules} with a line like:
406 The basic variables that a subdirectory makefile defines are:
410 The name of the subdirectory, for example @file{stdio}.
411 This variable @strong{must} be defined.
414 The names of the header files in this section of the library,
415 such as @file{stdio.h}.
419 The names of the modules (source files) in this section of the library.
420 These should be simple names, such as @samp{strlen} (rather than
421 complete file names, such as @file{strlen.c}). Use @code{routines} for
422 modules that define functions in the library, and @code{aux} for
423 auxiliary modules containing things like data definitions. But the
424 values of @code{routines} and @code{aux} are just concatenated, so there
425 really is no practical difference.@refill
428 The names of test programs for this section of the library. These
429 should be simple names, such as @samp{tester} (rather than complete file
430 names, such as @file{tester.c}). @w{@samp{make tests}} will build and
431 run all the test programs. If a test program needs input, put the test
432 data in a file called @file{@var{test-program}.input}; it will be given to
433 the test program on its standard input. If a test program wants to be
434 run with arguments, put the arguments (all on a single line) in a file
435 called @file{@var{test-program}.args}. Test programs should exit with
436 zero status when the test passes, and nonzero status when the test
437 indicates a bug in the library or error in building.
440 The names of ``other'' programs associated with this section of the
441 library. These are programs which are not tests per se, but are other
442 small programs included with the library. They are built by
443 @w{@samp{make others}}.@refill
448 Files to be installed by @w{@samp{make install}}. Files listed in
449 @samp{install-lib} are installed in the directory specified by
450 @samp{libdir} in @file{configparms} or @file{Makeconfig}
451 (@pxref{Installation}). Files listed in @code{install-data} are
452 installed in the directory specified by @samp{datadir} in
453 @file{configparms} or @file{Makeconfig}. Files listed in @code{install}
454 are installed in the directory specified by @samp{bindir} in
455 @file{configparms} or @file{Makeconfig}.@refill
458 Other files from this subdirectory which should be put into a
459 distribution tar file. You need not list here the makefile itself or
460 the source and header files listed in the other standard variables.
461 Only define @code{distribute} if there are files used in an unusual way
462 that should go into the distribution.
465 Files which are generated by @file{Makefile} in this subdirectory.
466 These files will be removed by @w{@samp{make clean}}, and they will
467 never go into a distribution.
470 Extra object files which are built by @file{Makefile} in this
471 subdirectory. This should be a list of file names like @file{foo.o};
472 the files will actually be found in whatever directory object files are
473 being built in. These files will be removed by @w{@samp{make clean}}.
474 This variable is used for secondary object files needed to build
475 @code{others} or @code{tests}.
479 @appendixsec Porting the GNU C Library
481 The GNU C library is written to be easily portable to a variety of
482 machines and operating systems. Machine- and operating system-dependent
483 functions are well separated to make it easy to add implementations for
484 new machines or operating systems. This section describes the layout of
485 the library source tree and explains the mechanisms used to select
486 machine-dependent code to use.
488 All the machine-dependent and operating system-dependent files in the
489 library are in the subdirectory @file{sysdeps} under the top-level
490 library source directory. This directory contains a hierarchy of
491 subdirectories (@pxref{Hierarchy Conventions}).
493 Each subdirectory of @file{sysdeps} contains source files for a
494 particular machine or operating system, or for a class of machine or
495 operating system (for example, systems by a particular vendor, or all
496 machines that use IEEE 754 floating-point format). A configuration
497 specifies an ordered list of these subdirectories. Each subdirectory
498 implicitly appends its parent directory to the list. For example,
499 specifying the list @file{unix/bsd/vax} is equivalent to specifying the
500 list @file{unix/bsd/vax unix/bsd unix}. A subdirectory can also specify
501 that it implies other subdirectories which are not directly above it in
502 the directory hierarchy. If the file @file{Implies} exists in a
503 subdirectory, it lists other subdirectories of @file{sysdeps} which are
504 appended to the list, appearing after the subdirectory containing the
505 @file{Implies} file. Lines in an @file{Implies} file that begin with a
506 @samp{#} character are ignored as comments. For example,
507 @file{unix/bsd/Implies} contains:@refill
509 # BSD has Internet-related things.
513 and @file{unix/Implies} contains:
520 So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}.
522 @file{sysdeps} has two ``special'' subdirectories, called @file{generic}
523 and @file{stub}. These two are always implicitly appended to the list
524 of subdirectories (in that order), so you needn't put them in an
525 @file{Implies} file, and you should not create any subdirectories under
526 them intended to be new specific categories. @file{generic} is for
527 things that can be implemented in machine-independent C, using only
528 other machine-independent functions in the C library. @file{stub} is
529 for @dfn{stub} versions of functions which cannot be implemented on a
530 particular machine or operating system. The stub functions always
531 return an error, and set @code{errno} to @code{ENOSYS} (Function not
532 implemented). @xref{Error Reporting}.
534 A source file is known to be system-dependent by its having a version in
535 @file{generic} or @file{stub}; every generally-available function whose
536 implementation is system-dependent in should have either a generic or
537 stub implementation (there is no point in having both). Some rare functions
538 are only useful on specific systems and aren't defined at all on others;
539 these do not appear anywhere in the system-independent source code or makefiles
540 (including the @file{generic} and @file{stub} directories), only in the
541 system-dependent @file{Makefile} in the specific system's subdirectory.
543 If you come across a file that is in one of the main source directories
544 (@file{string}, @file{stdio}, etc.), and you want to write a machine- or
545 operating system-dependent version of it, move the file into
546 @file{sysdeps/generic} and write your new implementation in the
547 appropriate system-specific subdirectory. Note that if a file is to be
548 system-dependent, it @strong{must not} appear in one of the main source
551 There are a few special files that may exist in each subdirectory of
554 @comment Blank lines after items make the table look better.
558 A makefile for this machine or operating system, or class of machine or
559 operating system. This file is included by the library makefile
560 @file{Makerules}, which is used by the top-level makefile and the
561 subdirectory makefiles. It can change the variables set in the
562 including makefile or add new rules. It can use GNU @code{make}
563 conditional directives based on the variable @samp{subdir} (see above) to
564 select different sets of variables and rules for different sections of
565 the library. It can also set the @code{make} variable
566 @samp{sysdep-routines}, to specify extra modules to be included in the
567 library. You should use @samp{sysdep-routines} rather than adding
568 modules to @samp{routines} because the latter is used in determining
569 what to distribute for each subdirectory of the main source tree.@refill
571 Each makefile in a subdirectory in the ordered list of subdirectories to
572 be searched is included in order. Since several system-dependent
573 makefiles may be included, each should append to @samp{sysdep-routines}
574 rather than simply setting it:
577 sysdep-routines := $(sysdep-routines) foo bar
583 This file contains the names of new whole subdirectories under the
584 top-level library source tree that should be included for this system.
585 These subdirectories are treated just like the system-independent
586 subdirectories in the library source tree, such as @file{stdio} and
589 Use this when there are completely new sets of functions and header
590 files that should go into the library for the system this subdirectory
591 of @file{sysdeps} implements. For example,
592 @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
593 directory contains various network-oriented operations which only make
594 sense to put in the library on systems that support the Internet.@refill
598 This file contains the names of files (relative to the subdirectory of
599 @file{sysdeps} in which it appears) which should be included in the
600 distribution. List any new files used by rules in the @file{Makefile}
601 in the same directory, or header files used by the source files in that
602 directory. You don't need to list files that are implementations
603 (either C or assembly source) of routines whose names are given in the
604 machine-independent makefiles in the main source tree.
608 This file is a shell script fragment to be run at configuration time.
609 The top-level @file{configure} script uses the shell @code{.} command to
610 read the @file{configure} file in each system-dependent directory
611 chosen, in order. The @file{configure} files are often generated from
612 @file{configure.in} files using Autoconf.
614 A system-dependent @file{configure} script will usually add things to
615 the shell variables @samp{DEFS} and @samp{config_vars}; see the
616 top-level @file{configure} script for details. The script can check for
617 @w{@samp{--with-@var{package}}} options that were passed to the
618 top-level @file{configure}. For an option
619 @w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the
620 shell variable @w{@samp{with_@var{package}}} (with any dashes in
621 @var{package} converted to underscores) to @var{value}; if the option is
622 just @w{@samp{--with-@var{package}}} (no argument), then it sets
623 @w{@samp{with_@var{package}}} to @samp{yes}.
627 This file is an Autoconf input fragment to be processed into the file
628 @file{configure} in this subdirectory. @xref{Introduction,,,
629 autoconf.info, Autoconf: Generating Automatic Configuration Scripts},
630 for a description of Autoconf. You should write either @file{configure}
631 or @file{configure.in}, but not both. The first line of
632 @file{configure.in} should invoke the @code{m4} macro
633 @samp{GLIBC_PROVIDES}. This macro does several @code{AC_PROVIDE} calls
634 for Autoconf macros which are used by the top-level @file{configure}
635 script; without this, those macros might be invoked again unnecessarily
639 That is the general system for how system-dependencies are isolated.
641 The next section explains how to decide what directories in
642 @file{sysdeps} to use. @ref{Porting to Unix}, has some tips on porting
643 the library to Unix variants.
647 * Hierarchy Conventions:: The layout of the @file{sysdeps} hierarchy.
648 * Porting to Unix:: Porting the library to an average
652 @node Hierarchy Conventions
653 @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy
655 A GNU configuration name has three parts: the CPU type, the
656 manufacturer's name, and the operating system. @file{configure} uses
657 these to pick the list of system-dependent directories to look for. If
658 the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
659 directory @file{@var{machine}/fpu} is also used. The operating system
660 often has a @dfn{base operating system}; for example, if the operating
661 system is @samp{sunos4.1}, the base operating system is @samp{unix/bsd}.
662 The algorithm used to pick the list of directories is simple:
663 @file{configure} makes a list of the base operating system,
664 manufacturer, CPU type, and operating system, in that order. It then
665 concatenates all these together with slashes in between, to produce a
666 directory name; for example, the configuration @w{@samp{sparc-sun-sunos4.1}}
667 results in @file{unix/bsd/sun/sparc/sunos4.1}. @file{configure} then
668 tries removing each element of the list in turn, so
669 @file{unix/bsd/sparc} and @file{sun/sparc} are also tried, among others.
670 Since the precise version number of the operating system is often not
671 important, and it would be very inconvenient, for example, to have
672 identical @file{sunos4.1.1} and @file{sunos4.1.2} directories,
673 @file{configure} tries successively less specific operating system names
674 by removing trailing suffixes starting with a period.
676 As an example, here is the complete list of directories that would be
677 tried for the configuration @w{@samp{sparc-sun-sunos4.1}} (without the
678 @w{@samp{--nfp}} option):
682 unix/bsd/sun/sunos4.1/sparc
683 unix/bsd/sun/sunos4.1
684 unix/bsd/sun/sunos4/sparc
686 unix/bsd/sun/sunos/sparc
690 unix/bsd/sunos4.1/sparc
692 unix/bsd/sunos4/sparc
698 unix/sun/sunos4.1/sparc
700 unix/sun/sunos4/sparc
731 Different machine architectures are conventionally subdirectories at the
732 top level of the @file{sysdeps} directory tree. For example,
733 @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}. These contain
734 files specific to those machine architectures, but not specific to any
735 particular operating system. There might be subdirectories for
736 specializations of those architectures, such as
737 @w{@file{sysdeps/m68k/68020}}. Code which is specific to the
738 floating-point coprocessor used with a particular machine should go in
739 @w{@file{sysdeps/@var{machine}/fpu}}.
741 There are a few directories at the top level of the @file{sysdeps}
742 hierarchy that are not for particular machine architectures.
747 As described above (@pxref{Porting}), these are the two subdirectories
748 that every configuration implicitly uses after all others.
751 This directory is for code using the IEEE 754 floating-point format,
752 where the C type @code{float} is IEEE 754 single-precision format, and
753 @code{double} is IEEE 754 double-precision format. Usually this
754 directory is referred to in the @file{Implies} file in a machine
755 architecture-specific directory, such as @file{m68k/Implies}.
758 This directory contains implementations of things in the library in
759 terms of @sc{POSIX.1} functions. This includes some of the @sc{POSIX.1}
760 functions themselves. Of course, @sc{POSIX.1} cannot be completely
761 implemented in terms of itself, so a configuration using just
762 @file{posix} cannot be complete.
765 This is the directory for Unix-like things. @xref{Porting to Unix}.
766 @file{unix} implies @file{posix}. There are some special-purpose
767 subdirectories of @file{unix}:
771 This directory is for things common to both BSD and System V release 4.
772 Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
775 This directory is for @code{socket} and related functions on Unix systems.
776 The @file{inet} top-level subdirectory is enabled by @file{unix/inet/Subdirs}.
777 @file{unix/common} implies @file{unix/inet}.
781 This is the directory for things based on the Mach microkernel from CMU
782 (including the GNU operating system). Other basic operating systems
783 (VMS, for example) would have their own directories at the top level of
784 the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
787 @node Porting to Unix
788 @appendixsubsec Porting the GNU C Library to Unix Systems
790 Most Unix systems are fundamentally very similar. There are variations
791 between different machines, and variations in what facilities are
792 provided by the kernel. But the interface to the operating system
793 facilities is, for the most part, pretty uniform and simple.
795 The code for Unix systems is in the directory @file{unix}, at the top
796 level of the @file{sysdeps} hierarchy. This directory contains
797 subdirectories (and subdirectory trees) for various Unix variants.
799 The functions which are system calls in most Unix systems are
800 implemented in assembly code, which is generated automatically from
801 specifications in the file @file{sysdeps/unix/syscalls.list}. Some
802 special system calls are implemented in files that are named with a
803 suffix of @samp{.S}; for example, @file{_exit.S}. Files ending in
804 @samp{.S} are run through the C preprocessor before being fed to the
807 These files all use a set of macros that should be defined in
808 @file{sysdep.h}. The @file{sysdep.h} file in @file{sysdeps/unix}
809 partially defines them; a @file{sysdep.h} file in another directory must
810 finish defining them for the particular machine and operating system
811 variant. See @file{sysdeps/unix/sysdep.h} and the machine-specific
812 @file{sysdep.h} implementations to see what these macros are and what
813 they should do.@refill
815 The system-specific makefile for the @file{unix} directory (that is, the
816 file @file{sysdeps/unix/Makefile}) gives rules to generate several files
817 from the Unix system you are building the library on (which is assumed
818 to be the target system you are building the library @emph{for}). All
819 the generated files are put in the directory where the object files are
820 kept; they should not affect the source tree itself. The files
821 generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
822 @file{errlist.c} (for the @file{stdio} section of the library).
825 @c This section might be a good idea if it is finished,
826 @c but there's no point including it as it stands. --rms
827 @c @appendixsec Compatibility with Traditional C
829 @c ??? This section is really short now. Want to keep it? --roland
831 Although the GNU C library implements the @w{ISO C} library facilities, you
832 @emph{can} use the GNU C library with traditional, ``pre-ISO'' C
833 compilers. However, you need to be careful because the content and
834 organization of the GNU C library header files differs from that of
835 traditional C implementations. This means you may need to make changes
836 to your program in order to get it to compile.
840 @appendixsec Contributors to the GNU C Library
842 The GNU C library was written originally by Roland McGrath. Some parts
843 of the library were contributed or worked on by other people.
847 The @code{getopt} function and related code were written by
848 Richard Stallman, @w{David J. MacKenzie}, and @w{Roland McGrath}.
851 The merge sort function @code{qsort} was written by Michael J. Haertel.
854 The quick sort function used as a fallback by @code{qsort} was written
855 by Douglas C. Schmidt.
858 The memory allocation functions @code{malloc}, @code{realloc} and
859 @code{free} and related code were written by Michael J. Haertel.
862 Fast implementations of many of the string functions (@code{memcpy},
863 @code{strlen}, etc.) were written by Torbj@"orn Granlund.
866 The @file{tar.h} header file was written by David J. MacKenzie.
869 The port to the MIPS DECStation running Ultrix 4
870 (@code{mips-dec-ultrix4})
871 was contributed by Brendan Kehoe and Ian Lance Taylor.
874 The DES encryption function @code{crypt} and related functions were
875 contributed by Michael Glad.
878 The @code{ftw} and @code{nftw} function was contributed by Ulrich Drepper.
881 The startup code to support SunOS shared libraries was contributed by
885 The @code{mktime} function was contributed by Paul Eggert.
888 The port to the Sequent Symmetry running Dynix version 3
889 (@code{i386-sequent-bsd}) was contributed by Jason Merrill.
892 The timezone support code is derived from the public-domain timezone
893 package by Arthur David Olson and his many contributors.
896 The port to the DEC Alpha running OSF/1 (@code{alpha-dec-osf1}) was
897 contributed by Brendan Kehoe, using some code written by Roland McGrath.
900 The port to SGI machines running Irix 4 (@code{mips-sgi-irix4}) was
901 contributed by Tom Quinn.
904 The port of the Mach and Hurd code to the MIPS architecture
905 (@code{mips-@var{anything}-gnu}) was contributed by Kazumoto Kojima.
908 The floating-point printing function used by @code{printf} and friends
909 and the floating-point reading function used by @code{scanf},
910 @code{strtod} and friends were written by Ulrich Drepper. The
911 multi-precision integer functions used in those functions are taken from
912 GNU MP, which was contributed by Torbj@"orn Granlund.
915 The internationalization support in the library, and the support
916 programs @code{locale} and @code{localedef}, were written by Ulrich
917 Drepper. Ulrich Drepper adapted the support code for message catalogs
918 (@file{libintl.h}, etc.) from the GNU @code{gettext} package, which he
919 also wrote. He also contributed the @code{catgets} support and the
920 entire suite of multi-byte and wide-character support functions
921 (@file{wctype.h}, @file{wchar.h}, etc.).
924 The implementations of the @file{nsswitch.conf} mechanism and the files
925 and DNS backends for it were designed and written by Ulrich Drepper and
926 Roland McGrath, based on a backend interface defined by Peter Eriksson.
929 The port to Linux i386/ELF (@code{i386-@var{anything}-linux}) was
930 contributed by Ulrich Drepper, based in large part on work done in
931 Hongjiu Lu's Linux version of the GNU C Library.
934 The port to Linux/m68k (@code{m68k-@var{anything}-linux}) was
935 contributed by Andreas Schwab.
938 The ports to Linux/ARM (@code{arm-@var{ANYTHING}-linuxaout}) and ARM
939 standalone (@code{arm-@var{ANYTHING}-none}), as well as parts of the
940 IPv6 support code, were contributed by Philip Blundell.
943 Richard Henderson contributed the ELF dynamic linking code and other
944 support for the Alpha processor.
947 David Mosberger-Tang contributed the port to Linux/Alpha
948 (@code{alpha-@var{anything}-linux}).
951 The port to Linux on PowerPC (@code{powerpc-@var{anything}-linux})
952 was contributed by Geoffrey Keating.
955 Miles Bader wrote the argp argument-parsing package, and the argz/envz
959 Stephen R. van den Berg contributed a highly-optimized @code{strstr} function.
962 Ulrich Drepper contributed the @code{hsearch} and @code{drand48}
963 families of functions; reentrant @samp{@dots{}@code{_r}} versions of the
964 @code{random} family; System V shared memory and IPC support code; and
965 several highly-optimized string functions for i@var{x}86 processors.
968 The math functions are taken from @code{fdlibm-5.1} by Sun
969 Microsystems, as modified by J.T. Conklin, Ian Lance Taylor,
970 Ulrich Drepper, Andreas Schwab, and Roland McGrath.
973 The @code{libio} library used to implement @code{stdio} functions on
974 some platforms was written by Per Bothner and modified by Ulrich Drepper.
977 The Internet-related code (most of the @file{inet} subdirectory) and
978 several other miscellaneous functions and header files have been
979 included from 4.4 BSD with little or no modification.
981 All code incorporated from 4.4 BSD is under the following copyright:
985 Copyright @copyright{} 1991 Regents of the University of California.
989 Redistribution and use in source and binary forms, with or without
990 modification, are permitted provided that the following conditions
995 Redistributions of source code must retain the above copyright
996 notice, this list of conditions and the following disclaimer.
998 Redistributions in binary form must reproduce the above copyright
999 notice, this list of conditions and the following disclaimer in the
1000 documentation and/or other materials provided with the distribution.
1002 All advertising materials mentioning features or use of this software
1003 must display the following acknowledgement:
1005 This product includes software developed by the University of
1006 California, Berkeley and its contributors.
1009 Neither the name of the University nor the names of its contributors
1010 may be used to endorse or promote products derived from this software
1011 without specific prior written permission.
1014 @sc{this software is provided by the regents and contributors ``as is'' and
1015 any express or implied warranties, including, but not limited to, the
1016 implied warranties of merchantability and fitness for a particular purpose
1017 are disclaimed. in no event shall the regents or contributors be liable
1018 for any direct, indirect, incidental, special, exemplary, or consequential
1019 damages (including, but not limited to, procurement of substitute goods
1020 or services; loss of use, data, or profits; or business interruption)
1021 however caused and on any theory of liability, whether in contract, strict
1022 liability, or tort (including negligence or otherwise) arising in any way
1023 out of the use of this software, even if advised of the possibility of
1028 The random number generation functions @code{random}, @code{srandom},
1029 @code{setstate} and @code{initstate}, which are also the basis for the
1030 @code{rand} and @code{srand} functions, were written by Earl T. Cohen
1031 for the University of California at Berkeley and are copyrighted by the
1032 Regents of the University of California. They have undergone minor
1033 changes to fit into the GNU C library and to fit the @w{ISO C} standard,
1034 but the functional code is Berkeley's.@refill
1037 The Internet resolver code is taken directly from BIND 4.9.5, which is
1038 under both the Berkeley copyright above and also:
1041 Portions Copyright @copyright{} 1993 by Digital Equipment Corporation.
1043 Permission to use, copy, modify, and distribute this software for any
1044 purpose with or without fee is hereby granted, provided that the above
1045 copyright notice and this permission notice appear in all copies, and
1046 that the name of Digital Equipment Corporation not be used in
1047 advertising or publicity pertaining to distribution of the document or
1048 software without specific, written prior permission.
1050 @sc{the software is provided ``as is'' and digital equipment corp.
1051 disclaims all warranties with regard to this software, including all
1052 implied warranties of merchantability and fitness. in no event shall
1053 digital equipment corporation be liable for any special, direct,
1054 indirect, or consequential damages or any damages whatsoever resulting
1055 from loss of use, data or profits, whether in an action of contract,
1056 negligence or other tortious action, arising out of or in connection
1057 with the use or performance of this software.}
1061 The code to support Sun RPC is taken verbatim from Sun's
1062 @w{@sc{rpcsrc-4.0}} distribution, and is covered by this copyright:
1066 Copyright @copyright{} 1984, Sun Microsystems, Inc.
1069 Sun RPC is a product of Sun Microsystems, Inc. and is provided for
1070 unrestricted use provided that this legend is included on all tape media
1071 and as a part of the software program in whole or part. Users may copy
1072 or modify Sun RPC without charge, but are not authorized to license or
1073 distribute it to anyone else except as part of a product or program
1074 developed by the user.
1076 @sc{sun rpc is provided as is with no warranties of any kind including the
1077 warranties of design, merchantibility and fitness for a particular
1078 purpose, or arising from a course of dealing, usage or trade practice.}
1080 Sun RPC is provided with no support and without any obligation on the
1081 part of Sun Microsystems, Inc. to assist in its use, correction,
1082 modification or enhancement.
1084 @sc{sun microsystems, inc. shall have no liability with respect to the
1085 infringement of copyrights, trade secrets or any patents by sun rpc
1086 or any part thereof.}
1088 In no event will Sun Microsystems, Inc. be liable for any lost revenue
1089 or profits or other special, indirect and consequential damages, even if
1090 Sun has been advised of the possibility of such damages.
1093 Sun Microsystems, Inc.
1095 Mountain View, California 94043
1100 Some of the support code for Mach is taken from Mach 3.0 by CMU,
1101 and is under the following copyright terms:
1105 Mach Operating System
1106 Copyright @copyright{} 1991,1990,1989 Carnegie Mellon University
1107 All Rights Reserved.
1110 Permission to use, copy, modify and distribute this software and its
1111 documentation is hereby granted, provided that both the copyright
1112 notice and this permission notice appear in all copies of the
1113 software, derivative works or modified versions, and any portions
1114 thereof, and that both notices appear in supporting documentation.
1116 @sc{carnegie mellon allows free use of this software in its ``as is''
1117 condition. carnegie mellon disclaims any liability of any kind for
1118 any damages whatsoever resulting from the use of this software.}
1120 Carnegie Mellon requests users of this software to return to
1123 Software Distribution Coordinator
1124 School of Computer Science
1125 Carnegie Mellon University
1126 Pittsburgh PA 15213-3890
1130 or @email{Software.Distribution@@CS.CMU.EDU} any improvements or
1131 extensions that they make and grant Carnegie Mellon the rights to
1132 redistribute these changes.