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
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.@refill
185 @node Tools for Installation
186 @appendixsubsec Recommended Tools to Install the GNU C Library
187 @cindex installation tools
188 @cindex tools, for installing library
190 We recommend installing the following GNU tools before attempting to
191 build the GNU C library:
197 You need the latest version of GNU @code{make}. Modifying the GNU C
198 Library to work with other @code{make} programs would be so hard that we
199 recommend you port GNU @code{make} instead. @strong{Really.}
200 We recommend version GNU @code{make} version 3.75 or later.
205 On most platforms, the GNU C library can only be compiled with the GNU C
206 compiler. We recommend GCC version 2.7.2 or later; earlier versions may
212 Using the GNU @code{binutils} (assembler, linker, and related tools) is
213 preferable when possible, and they are required to build an ELF shared C
214 library. We recommend @code{binutils} version 2.8 or later; earlier
215 versions are known to have problems or to not support all architectures.
218 @node Supported Configurations
219 @appendixsubsec Supported Configurations
220 @cindex configurations, all supported
222 The GNU C Library currently supports configurations that match the
226 alpha-@var{anything}-linux
227 i@var{x}86-@var{anything}-gnu
228 i@var{x}86-@var{anything}-linux
229 m68k-@var{anything}-linux
232 Former releases of this library (version 1.09.1 and perhaps earlier
233 versions) used to run on the following configurations:
237 alpha-@var{anything}-linuxecoff
238 i@var{x}86-@var{anything}-bsd4.3
239 i@var{x}86-@var{anything}-isc2.2
240 i@var{x}86-@var{anything}-isc3.@var{n}
241 i@var{x}86-@var{anything}-sco3.2
242 i@var{x}86-@var{anything}-sco3.2v4
243 i@var{x}86-@var{anything}-sysv
244 i@var{x}86-@var{anything}-sysv4
245 i@var{x}86-force_cpu386-none
246 i@var{x}86-sequent-bsd
253 m68k-sun-sunos4.@var{n}
254 mips-dec-ultrix4.@var{n}
255 mips-sgi-irix4.@var{n}
256 sparc-sun-solaris2.@var{n}
257 sparc-sun-sunos4.@var{n}
260 Since no one has volunteered to test and fix the above configurations,
261 these are not supported at the moment. It's expected that these don't
262 work anymore. Porting the library is not hard. If you are interested
263 in doing a port, please contact the glibc maintainers by sending
264 electronic mail to @email{bug-glibc@@prep.ai.mit.edu}.
266 Each case of @samp{i@var{x}86} can be @samp{i386}, @samp{i486},
267 @samp{i586}, or @samp{i686}. All of those configurations produce a
268 library that can run on any of these processors. The library will be
269 optimized for the specified processor, but will not use instructions not
270 available on all of them.
272 While no other configurations are supported, there are handy aliases for
273 these few. (These aliases work in other GNU software as well.)
277 hp320-bsd4.3 hp300bsd
285 sun3-sunos4.@var{n} sun3
286 sun4-solaris2.@var{n} sun4-sunos5.@var{n}
287 sun4-sunos4.@var{n} sun4
291 @appendixsec Reporting Bugs
292 @cindex reporting bugs
293 @cindex bugs, reporting
295 There are probably bugs in the GNU C library. There are certainly
296 errors and omissions in this manual. If you report them, they will get
297 fixed. If you don't, no one will ever know about them and they will
298 remain unfixed for all eternity, if not longer.
300 To report a bug, first you must find it. Hopefully, this will be the
301 hard part. Once you've found a bug, make sure it's really a bug. A
302 good way to do this is to see if the GNU C library behaves the same way
303 some other C library does. If so, probably you are wrong and the
304 libraries are right (but not necessarily). If not, one of the libraries
307 Once you're sure you've found a bug, try to narrow it down to the
308 smallest test case that reproduces the problem. In the case of a C
309 library, you really only need to narrow it down to one library
310 function call, if possible. This should not be too difficult.
312 The final step when you have a simple test case is to report the bug.
313 When reporting a bug, send your test case, the results you got, the
314 results you expected, what you think the problem might be (if you've
315 thought of anything), your system type, and the version of the GNU C
316 library which you are using. Also include the files
317 @file{config.status} and @file{config.make} which are created by running
318 @file{configure}; they will be in whatever directory was current when
319 you ran @file{configure}.
321 If you think you have found some way in which the GNU C library does not
322 conform to the ISO and POSIX standards (@pxref{Standards and
323 Portability}), that is definitely a bug. Report it!@refill
325 Send bug reports to the Internet address
326 @email{bug-glibc@@prep.ai.mit.edu} or the UUCP path
327 @email{mit-eddie!prep.ai.mit.edu!bug-glibc}. If you have other problems
328 with installation or use, please report those as well.@refill
330 If you are not sure how a function should behave, and this manual
331 doesn't tell you, that's a bug in the manual. Report that too! If the
332 function's behavior disagrees with the manual, then either the library
333 or the manual has a bug, so report the disagreement. If you find any
334 errors or omissions in this manual, please report them to the Internet
335 address @email{bug-glibc-manual@@prep.ai.mit.edu} or the UUCP path
336 @email{mit-eddie!prep.ai.mit.edu!bug-glibc-manual}.
339 @appendixsec Adding New Functions
341 The process of building the library is driven by the makefiles, which
342 make heavy use of special features of GNU @code{make}. The makefiles
343 are very complex, and you probably don't want to try to understand them.
344 But what they do is fairly straightforward, and only requires that you
345 define a few variables in the right places.
347 The library sources are divided into subdirectories, grouped by topic.
349 The @file{string} subdirectory has all the string-manipulation
350 functions, @file{math} has all the mathematical functions, etc.
352 Each subdirectory contains a simple makefile, called @file{Makefile},
353 which defines a few @code{make} variables and then includes the global
354 makefile @file{Rules} with a line like:
361 The basic variables that a subdirectory makefile defines are:
365 The name of the subdirectory, for example @file{stdio}.
366 This variable @strong{must} be defined.
369 The names of the header files in this section of the library,
370 such as @file{stdio.h}.
374 The names of the modules (source files) in this section of the library.
375 These should be simple names, such as @samp{strlen} (rather than
376 complete file names, such as @file{strlen.c}). Use @code{routines} for
377 modules that define functions in the library, and @code{aux} for
378 auxiliary modules containing things like data definitions. But the
379 values of @code{routines} and @code{aux} are just concatenated, so there
380 really is no practical difference.@refill
383 The names of test programs for this section of the library. These
384 should be simple names, such as @samp{tester} (rather than complete file
385 names, such as @file{tester.c}). @w{@samp{make tests}} will build and
386 run all the test programs. If a test program needs input, put the test
387 data in a file called @file{@var{test-program}.input}; it will be given to
388 the test program on its standard input. If a test program wants to be
389 run with arguments, put the arguments (all on a single line) in a file
390 called @file{@var{test-program}.args}. Test programs should exit with
391 zero status when the test passes, and nonzero status when the test
392 indicates a bug in the library or error in building.
395 The names of ``other'' programs associated with this section of the
396 library. These are programs which are not tests per se, but are other
397 small programs included with the library. They are built by
398 @w{@samp{make others}}.@refill
403 Files to be installed by @w{@samp{make install}}. Files listed in
404 @samp{install-lib} are installed in the directory specified by
405 @samp{libdir} in @file{configparms} or @file{Makeconfig}
406 (@pxref{Installation}). Files listed in @code{install-data} are
407 installed in the directory specified by @samp{datadir} in
408 @file{configparms} or @file{Makeconfig}. Files listed in @code{install}
409 are installed in the directory specified by @samp{bindir} in
410 @file{configparms} or @file{Makeconfig}.@refill
413 Other files from this subdirectory which should be put into a
414 distribution tar file. You need not list here the makefile itself or
415 the source and header files listed in the other standard variables.
416 Only define @code{distribute} if there are files used in an unusual way
417 that should go into the distribution.
420 Files which are generated by @file{Makefile} in this subdirectory.
421 These files will be removed by @w{@samp{make clean}}, and they will
422 never go into a distribution.
425 Extra object files which are built by @file{Makefile} in this
426 subdirectory. This should be a list of file names like @file{foo.o};
427 the files will actually be found in whatever directory object files are
428 being built in. These files will be removed by @w{@samp{make clean}}.
429 This variable is used for secondary object files needed to build
430 @code{others} or @code{tests}.
434 @appendixsec Porting the GNU C Library
436 The GNU C library is written to be easily portable to a variety of
437 machines and operating systems. Machine- and operating system-dependent
438 functions are well separated to make it easy to add implementations for
439 new machines or operating systems. This section describes the layout of
440 the library source tree and explains the mechanisms used to select
441 machine-dependent code to use.
443 All the machine-dependent and operating system-dependent files in the
444 library are in the subdirectory @file{sysdeps} under the top-level
445 library source directory. This directory contains a hierarchy of
446 subdirectories (@pxref{Hierarchy Conventions}).
448 Each subdirectory of @file{sysdeps} contains source files for a
449 particular machine or operating system, or for a class of machine or
450 operating system (for example, systems by a particular vendor, or all
451 machines that use IEEE 754 floating-point format). A configuration
452 specifies an ordered list of these subdirectories. Each subdirectory
453 implicitly appends its parent directory to the list. For example,
454 specifying the list @file{unix/bsd/vax} is equivalent to specifying the
455 list @file{unix/bsd/vax unix/bsd unix}. A subdirectory can also specify
456 that it implies other subdirectories which are not directly above it in
457 the directory hierarchy. If the file @file{Implies} exists in a
458 subdirectory, it lists other subdirectories of @file{sysdeps} which are
459 appended to the list, appearing after the subdirectory containing the
460 @file{Implies} file. Lines in an @file{Implies} file that begin with a
461 @samp{#} character are ignored as comments. For example,
462 @file{unix/bsd/Implies} contains:@refill
464 # BSD has Internet-related things.
468 and @file{unix/Implies} contains:
475 So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}.
477 @file{sysdeps} has two ``special'' subdirectories, called @file{generic}
478 and @file{stub}. These two are always implicitly appended to the list
479 of subdirectories (in that order), so you needn't put them in an
480 @file{Implies} file, and you should not create any subdirectories under
481 them intended to be new specific categories. @file{generic} is for
482 things that can be implemented in machine-independent C, using only
483 other machine-independent functions in the C library. @file{stub} is
484 for @dfn{stub} versions of functions which cannot be implemented on a
485 particular machine or operating system. The stub functions always
486 return an error, and set @code{errno} to @code{ENOSYS} (Function not
487 implemented). @xref{Error Reporting}.
489 A source file is known to be system-dependent by its having a version in
490 @file{generic} or @file{stub}; every generally-available function whose
491 implementation is system-dependent in should have either a generic or
492 stub implementation (there is no point in having both). Some rare functions
493 are only useful on specific systems and aren't defined at all on others;
494 these do not appear anywhere in the system-independent source code or makefiles
495 (including the @file{generic} and @file{stub} directories), only in the
496 system-dependent @file{Makefile} in the specific system's subdirectory.
498 If you come across a file that is in one of the main source directories
499 (@file{string}, @file{stdio}, etc.), and you want to write a machine- or
500 operating system-dependent version of it, move the file into
501 @file{sysdeps/generic} and write your new implementation in the
502 appropriate system-specific subdirectory. Note that if a file is to be
503 system-dependent, it @strong{must not} appear in one of the main source
506 There are a few special files that may exist in each subdirectory of
509 @comment Blank lines after items make the table look better.
513 A makefile for this machine or operating system, or class of machine or
514 operating system. This file is included by the library makefile
515 @file{Makerules}, which is used by the top-level makefile and the
516 subdirectory makefiles. It can change the variables set in the
517 including makefile or add new rules. It can use GNU @code{make}
518 conditional directives based on the variable @samp{subdir} (see above) to
519 select different sets of variables and rules for different sections of
520 the library. It can also set the @code{make} variable
521 @samp{sysdep-routines}, to specify extra modules to be included in the
522 library. You should use @samp{sysdep-routines} rather than adding
523 modules to @samp{routines} because the latter is used in determining
524 what to distribute for each subdirectory of the main source tree.@refill
526 Each makefile in a subdirectory in the ordered list of subdirectories to
527 be searched is included in order. Since several system-dependent
528 makefiles may be included, each should append to @samp{sysdep-routines}
529 rather than simply setting it:
532 sysdep-routines := $(sysdep-routines) foo bar
538 This file contains the names of new whole subdirectories under the
539 top-level library source tree that should be included for this system.
540 These subdirectories are treated just like the system-independent
541 subdirectories in the library source tree, such as @file{stdio} and
544 Use this when there are completely new sets of functions and header
545 files that should go into the library for the system this subdirectory
546 of @file{sysdeps} implements. For example,
547 @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
548 directory contains various network-oriented operations which only make
549 sense to put in the library on systems that support the Internet.@refill
553 This file contains the names of files (relative to the subdirectory of
554 @file{sysdeps} in which it appears) which should be included in the
555 distribution. List any new files used by rules in the @file{Makefile}
556 in the same directory, or header files used by the source files in that
557 directory. You don't need to list files that are implementations
558 (either C or assembly source) of routines whose names are given in the
559 machine-independent makefiles in the main source tree.
563 This file is a shell script fragment to be run at configuration time.
564 The top-level @file{configure} script uses the shell @code{.} command to
565 read the @file{configure} file in each system-dependent directory
566 chosen, in order. The @file{configure} files are often generated from
567 @file{configure.in} files using Autoconf.
569 A system-dependent @file{configure} script will usually add things to
570 the shell variables @samp{DEFS} and @samp{config_vars}; see the
571 top-level @file{configure} script for details. The script can check for
572 @w{@samp{--with-@var{package}}} options that were passed to the
573 top-level @file{configure}. For an option
574 @w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the
575 shell variable @w{@samp{with_@var{package}}} (with any dashes in
576 @var{package} converted to underscores) to @var{value}; if the option is
577 just @w{@samp{--with-@var{package}}} (no argument), then it sets
578 @w{@samp{with_@var{package}}} to @samp{yes}.
582 This file is an Autoconf input fragment to be processed into the file
583 @file{configure} in this subdirectory. @xref{Introduction,,,
584 autoconf.info, Autoconf: Generating Automatic Configuration Scripts},
585 for a description of Autoconf. You should write either @file{configure}
586 or @file{configure.in}, but not both. The first line of
587 @file{configure.in} should invoke the @code{m4} macro
588 @samp{GLIBC_PROVIDES}. This macro does several @code{AC_PROVIDE} calls
589 for Autoconf macros which are used by the top-level @file{configure}
590 script; without this, those macros might be invoked again unnecessarily
594 That is the general system for how system-dependencies are isolated.
596 The next section explains how to decide what directories in
597 @file{sysdeps} to use. @ref{Porting to Unix}, has some tips on porting
598 the library to Unix variants.
602 * Hierarchy Conventions:: The layout of the @file{sysdeps} hierarchy.
603 * Porting to Unix:: Porting the library to an average
607 @node Hierarchy Conventions
608 @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy
610 A GNU configuration name has three parts: the CPU type, the
611 manufacturer's name, and the operating system. @file{configure} uses
612 these to pick the list of system-dependent directories to look for. If
613 the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
614 directory @file{@var{machine}/fpu} is also used. The operating system
615 often has a @dfn{base operating system}; for example, if the operating
616 system is @samp{sunos4.1}, the base operating system is @samp{unix/bsd}.
617 The algorithm used to pick the list of directories is simple:
618 @file{configure} makes a list of the base operating system,
619 manufacturer, CPU type, and operating system, in that order. It then
620 concatenates all these together with slashes in between, to produce a
621 directory name; for example, the configuration @w{@samp{sparc-sun-sunos4.1}}
622 results in @file{unix/bsd/sun/sparc/sunos4.1}. @file{configure} then
623 tries removing each element of the list in turn, so
624 @file{unix/bsd/sparc} and @file{sun/sparc} are also tried, among others.
625 Since the precise version number of the operating system is often not
626 important, and it would be very inconvenient, for example, to have
627 identical @file{sunos4.1.1} and @file{sunos4.1.2} directories,
628 @file{configure} tries successively less specific operating system names
629 by removing trailing suffixes starting with a period.
631 As an example, here is the complete list of directories that would be
632 tried for the configuration @w{@samp{sparc-sun-sunos4.1}} (without the
633 @w{@samp{--nfp}} option):
637 unix/bsd/sun/sunos4.1/sparc
638 unix/bsd/sun/sunos4.1
639 unix/bsd/sun/sunos4/sparc
641 unix/bsd/sun/sunos/sparc
645 unix/bsd/sunos4.1/sparc
647 unix/bsd/sunos4/sparc
653 unix/sun/sunos4.1/sparc
655 unix/sun/sunos4/sparc
686 Different machine architectures are conventionally subdirectories at the
687 top level of the @file{sysdeps} directory tree. For example,
688 @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}. These contain
689 files specific to those machine architectures, but not specific to any
690 particular operating system. There might be subdirectories for
691 specializations of those architectures, such as
692 @w{@file{sysdeps/m68k/68020}}. Code which is specific to the
693 floating-point coprocessor used with a particular machine should go in
694 @w{@file{sysdeps/@var{machine}/fpu}}.
696 There are a few directories at the top level of the @file{sysdeps}
697 hierarchy that are not for particular machine architectures.
702 As described above (@pxref{Porting}), these are the two subdirectories
703 that every configuration implicitly uses after all others.
706 This directory is for code using the IEEE 754 floating-point format,
707 where the C type @code{float} is IEEE 754 single-precision format, and
708 @code{double} is IEEE 754 double-precision format. Usually this
709 directory is referred to in the @file{Implies} file in a machine
710 architecture-specific directory, such as @file{m68k/Implies}.
713 This directory contains implementations of things in the library in
714 terms of @sc{POSIX.1} functions. This includes some of the @sc{POSIX.1}
715 functions themselves. Of course, @sc{POSIX.1} cannot be completely
716 implemented in terms of itself, so a configuration using just
717 @file{posix} cannot be complete.
720 This is the directory for Unix-like things. @xref{Porting to Unix}.
721 @file{unix} implies @file{posix}. There are some special-purpose
722 subdirectories of @file{unix}:
726 This directory is for things common to both BSD and System V release 4.
727 Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
730 This directory is for @code{socket} and related functions on Unix systems.
731 The @file{inet} top-level subdirectory is enabled by @file{unix/inet/Subdirs}.
732 @file{unix/common} implies @file{unix/inet}.
736 This is the directory for things based on the Mach microkernel from CMU
737 (including the GNU operating system). Other basic operating systems
738 (VMS, for example) would have their own directories at the top level of
739 the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
742 @node Porting to Unix
743 @appendixsubsec Porting the GNU C Library to Unix Systems
745 Most Unix systems are fundamentally very similar. There are variations
746 between different machines, and variations in what facilities are
747 provided by the kernel. But the interface to the operating system
748 facilities is, for the most part, pretty uniform and simple.
750 The code for Unix systems is in the directory @file{unix}, at the top
751 level of the @file{sysdeps} hierarchy. This directory contains
752 subdirectories (and subdirectory trees) for various Unix variants.
754 The functions which are system calls in most Unix systems are
755 implemented in assembly code, which is generated automatically from
756 specifications in the file @file{sysdeps/unix/syscalls.list}. Some
757 special system calls are implemented in files that are named with a
758 suffix of @samp{.S}; for example, @file{_exit.S}. Files ending in
759 @samp{.S} are run through the C preprocessor before being fed to the
762 These files all use a set of macros that should be defined in
763 @file{sysdep.h}. The @file{sysdep.h} file in @file{sysdeps/unix}
764 partially defines them; a @file{sysdep.h} file in another directory must
765 finish defining them for the particular machine and operating system
766 variant. See @file{sysdeps/unix/sysdep.h} and the machine-specific
767 @file{sysdep.h} implementations to see what these macros are and what
768 they should do.@refill
770 The system-specific makefile for the @file{unix} directory (that is, the
771 file @file{sysdeps/unix/Makefile}) gives rules to generate several files
772 from the Unix system you are building the library on (which is assumed
773 to be the target system you are building the library @emph{for}). All
774 the generated files are put in the directory where the object files are
775 kept; they should not affect the source tree itself. The files
776 generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
777 @file{errlist.c} (for the @file{stdio} section of the library).
780 @c This section might be a good idea if it is finished,
781 @c but there's no point including it as it stands. --rms
782 @c @appendixsec Compatibility with Traditional C
784 @c ??? This section is really short now. Want to keep it? --roland
786 Although the GNU C library implements the @w{ISO C} library facilities, you
787 @emph{can} use the GNU C library with traditional, ``pre-ISO'' C
788 compilers. However, you need to be careful because the content and
789 organization of the GNU C library header files differs from that of
790 traditional C implementations. This means you may need to make changes
791 to your program in order to get it to compile.
795 @appendixsec Contributors to the GNU C Library
797 The GNU C library was written originally by Roland McGrath. Some parts
798 of the library were contributed or worked on by other people.
802 The @code{getopt} function and related code were written by
803 Richard Stallman, @w{David J. MacKenzie}, and @w{Roland McGrath}.
806 The merge sort function @code{qsort} was written by Michael J. Haertel.
809 The quick sort function used as a fallback by @code{qsort} was written
810 by Douglas C. Schmidt.
813 The memory allocation functions @code{malloc}, @code{realloc} and
814 @code{free} and related code were written by Michael J. Haertel.
817 Fast implementations of many of the string functions (@code{memcpy},
818 @code{strlen}, etc.) were written by Torbj@"orn Granlund.
821 The @file{tar.h} header file was written by David J. MacKenzie.
824 The port to the MIPS DECStation running Ultrix 4
825 (@code{mips-dec-ultrix4})
826 was contributed by Brendan Kehoe and Ian Lance Taylor.
829 The DES encryption function @code{crypt} and related functions were
830 contributed by Michael Glad.
833 The @code{ftw} function was contributed by Ian Lance Taylor.
836 The startup code to support SunOS shared libraries was contributed by
840 The @code{mktime} function was contributed by Paul Eggert.
843 The port to the Sequent Symmetry running Dynix version 3
844 (@code{i386-sequent-bsd}) was contributed by Jason Merrill.
847 The timezone support code is derived from the public-domain timezone
848 package by Arthur David Olson and his many contributors.
851 The port to the DEC Alpha running OSF/1 (@code{alpha-dec-osf1}) was
852 contributed by Brendan Kehoe, using some code written by Roland McGrath.
855 The port to SGI machines running Irix 4 (@code{mips-sgi-irix4}) was
856 contributed by Tom Quinn.
859 The port of the Mach and Hurd code to the MIPS architecture
860 (@code{mips-@var{anything}-gnu}) was contributed by Kazumoto Kojima.
863 The floating-point printing function used by @code{printf} and friends
864 and the floating-point reading function used by @code{scanf},
865 @code{strtod} and friends were written by Ulrich Drepper. The
866 multi-precision integer functions used in those functions are taken from
867 GNU MP, which was contributed by Torbj@"orn Granlund.
870 The internationalization support in the library, and the support
871 programs @code{locale} and @code{localedef}, were written by Ulrich
872 Drepper. Ulrich Drepper adapted the support code for message catalogs
873 (@file{libintl.h}, etc.) from the GNU @code{gettext} package, which he
874 also wrote. He also contributed the @code{catgets} support and the
875 entire suite of multi-byte and wide-character support functions
876 (@file{wctype.h}, @file{wchar.h}, etc.).
879 The implementations of the @file{nsswitch.conf} mechanism and the files
880 and DNS backends for it were designed and written by Ulrich Drepper and
881 Roland McGrath, based on a backend interface defined by Peter Eriksson.
884 The port to Linux i386/ELF (@code{i386-@var{anything}-linux}) was
885 contributed by Ulrich Drepper, based in large part on work done in
886 Hongjiu Lu's Linux version of the GNU C Library.
889 The port to Linux/m68k (@code{m68k-@var{anything}-linux}) was
890 contributed by Andreas Schwab.
893 Richard Henderson contributed the ELF dynamic linking code and other
894 support for the Alpha processor.
897 David Mosberger-Tang contributed the port to Linux/Alpha
898 (@code{alpha-@var{anything}-linux}).
901 Miles Bader wrote the argp argument-parsing package, and the argz/envz
905 Stephen R. van den Berg contributed a highly-optimized @code{strstr} function.
908 Ulrich Drepper contributed the @code{hsearch} and @code{drand48}
909 families of functions; reentrant @samp{@dots{}@code{_r}} versions of the
910 @code{random} family; System V shared memory and IPC support code; and
911 several highly-optimized string functions for i@var{x}86 processors.
914 The math functions are taken from @code{fdlibm-5.1} by Sun
915 Microsystems, as modified by J.T. Conklin, Ian Lance Taylor,
916 Ulrich Drepper, Andreas Schwab, and Roland McGrath.
919 The @code{libio} library used to implement @code{stdio} functions on
920 some platforms was written by Per Bothner and modified by Ulrich Drepper.
923 The Internet-related code (most of the @file{inet} subdirectory) and
924 several other miscellaneous functions and header files have been
925 included from 4.4 BSD with little or no modification.
927 All code incorporated from 4.4 BSD is under the following copyright:
931 Copyright @copyright{} 1991 Regents of the University of California.
935 Redistribution and use in source and binary forms, with or without
936 modification, are permitted provided that the following conditions
941 Redistributions of source code must retain the above copyright
942 notice, this list of conditions and the following disclaimer.
944 Redistributions in binary form must reproduce the above copyright
945 notice, this list of conditions and the following disclaimer in the
946 documentation and/or other materials provided with the distribution.
948 All advertising materials mentioning features or use of this software
949 must display the following acknowledgement:
951 This product includes software developed by the University of
952 California, Berkeley and its contributors.
955 Neither the name of the University nor the names of its contributors
956 may be used to endorse or promote products derived from this software
957 without specific prior written permission.
960 @sc{this software is provided by the regents and contributors ``as is'' and
961 any express or implied warranties, including, but not limited to, the
962 implied warranties of merchantability and fitness for a particular purpose
963 are disclaimed. in no event shall the regents or contributors be liable
964 for any direct, indirect, incidental, special, exemplary, or consequential
965 damages (including, but not limited to, procurement of substitute goods
966 or services; loss of use, data, or profits; or business interruption)
967 however caused and on any theory of liability, whether in contract, strict
968 liability, or tort (including negligence or otherwise) arising in any way
969 out of the use of this software, even if advised of the possibility of
974 The random number generation functions @code{random}, @code{srandom},
975 @code{setstate} and @code{initstate}, which are also the basis for the
976 @code{rand} and @code{srand} functions, were written by Earl T. Cohen
977 for the University of California at Berkeley and are copyrighted by the
978 Regents of the University of California. They have undergone minor
979 changes to fit into the GNU C library and to fit the @w{ISO C} standard,
980 but the functional code is Berkeley's.@refill
983 The Internet resolver code is taken directly from BIND 4.9.5, which is
984 under both the Berkeley copyright above and also:
987 Portions Copyright @copyright{} 1993 by Digital Equipment Corporation.
989 Permission to use, copy, modify, and distribute this software for any
990 purpose with or without fee is hereby granted, provided that the above
991 copyright notice and this permission notice appear in all copies, and
992 that the name of Digital Equipment Corporation not be used in
993 advertising or publicity pertaining to distribution of the document or
994 software without specific, written prior permission.
996 @sc{the software is provided ``as is'' and digital equipment corp.
997 disclaims all warranties with regard to this software, including all
998 implied warranties of merchantability and fitness. in no event shall
999 digital equipment corporation be liable for any special, direct,
1000 indirect, or consequential damages or any damages whatsoever resulting
1001 from loss of use, data or profits, whether in an action of contract,
1002 negligence or other tortious action, arising out of or in connection
1003 with the use or performance of this software.}
1007 The code to support Sun RPC is taken verbatim from Sun's
1008 @w{@sc{rpcsrc-4.0}} distribution, and is covered by this copyright:
1012 Copyright @copyright{} 1984, Sun Microsystems, Inc.
1015 Sun RPC is a product of Sun Microsystems, Inc. and is provided for
1016 unrestricted use provided that this legend is included on all tape media
1017 and as a part of the software program in whole or part. Users may copy
1018 or modify Sun RPC without charge, but are not authorized to license or
1019 distribute it to anyone else except as part of a product or program
1020 developed by the user.
1022 @sc{sun rpc is provided as is with no warranties of any kind including the
1023 warranties of design, merchantibility and fitness for a particular
1024 purpose, or arising from a course of dealing, usage or trade practice.}
1026 Sun RPC is provided with no support and without any obligation on the
1027 part of Sun Microsystems, Inc. to assist in its use, correction,
1028 modification or enhancement.
1030 @sc{sun microsystems, inc. shall have no liability with respect to the
1031 infringement of copyrights, trade secrets or any patents by sun rpc
1032 or any part thereof.}
1034 In no event will Sun Microsystems, Inc. be liable for any lost revenue
1035 or profits or other special, indirect and consequential damages, even if
1036 Sun has been advised of the possibility of such damages.
1039 Sun Microsystems, Inc.
1041 Mountain View, California 94043
1046 Some of the support code for Mach is taken from Mach 3.0 by CMU,
1047 and is under the following copyright terms:
1051 Mach Operating System
1052 Copyright @copyright{} 1991,1990,1989 Carnegie Mellon University
1053 All Rights Reserved.
1056 Permission to use, copy, modify and distribute this software and its
1057 documentation is hereby granted, provided that both the copyright
1058 notice and this permission notice appear in all copies of the
1059 software, derivative works or modified versions, and any portions
1060 thereof, and that both notices appear in supporting documentation.
1062 @sc{carnegie mellon allows free use of this software in its ``as is''
1063 condition. carnegie mellon disclaims any liability of any kind for
1064 any damages whatsoever resulting from the use of this software.}
1066 Carnegie Mellon requests users of this software to return to
1069 Software Distribution Coordinator
1070 School of Computer Science
1071 Carnegie Mellon University
1072 Pittsburgh PA 15213-3890
1076 or @email{Software.Distribution@@CS.CMU.EDU} any improvements or
1077 extensions that they make and grant Carnegie Mellon the rights to
1078 redistribute these changes.