bunch of updates
[kopensolaris-gnu/glibc.git] / manual / maint.texi
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.
4 @setfilename INSTALL
5
6 @node Maintenance, Copying, Library Summary, Top
7 @appendix Library Maintenance
8
9 @menu
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
16                              to the GNU C library.
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.
20 @end menu
21
22 @node Installation
23 @appendixsec How to Install the GNU C Library
24 @cindex installing the library
25
26 Installation of the GNU C library is relatively simple, but usually
27 requires several GNU tools to be installed already.
28 @iftex
29 (@pxref{Tools for Installation}, below.)
30 @end iftex
31
32 @menu
33 * Tools for Installation::      We recommend using these tools to build.
34 * Supported Configurations::    What systems the GNU C library runs on.
35 @end menu
36
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.
48
49 Here are some options that you should specify (if appropriate) when
50 you run @code{configure}:
51
52 @table @samp
53 @item --with-gnu-ld
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.
59
60 @item --with-gnu-as
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}.
64
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.
69
70 @c extra blank line makes it look better
71 @item --without-fp
72 @itemx --nfp
73
74 Use this option if your computer lacks hardware floating-point support.
75
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.)
80
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.)
85
86 @item --enable-shared
87 @itemx --disable-shared
88 Enable or disable building of an ELF shared library on systems that
89 support it.  The default is to build the shared library on systems using
90 ELF when the GNU @code{binutils} are available.
91
92 @item --enable-profile
93 @itemx --disable-profile
94 Enable or disable building of the profiled C library, @samp{-lc_p}.  The
95 default is to build the profiled library.  You may wish to disable it if
96 you don't plan to do profiling, because it doubles the build time of
97 compiling just the unprofiled static library.
98
99 @item --enable-omitfp
100 Enable building a highly-optimized but possibly undebuggable static C
101 library.  This causes the normal static and shared (if enabled) C
102 libraries to be compiled with maximal optimization, including the
103 @samp{-fomit-frame-pointer} switch that makes debugging impossible on
104 many machines, and without debugging information (which makes the
105 binaries substantially smaller).  An additional static library is
106 compiled with no optimization and full debugging information, and
107 installed as @samp{-lc_g}.
108 @end table
109
110 The simplest way to run @code{configure} is to do it in the directory
111 that contains the library sources.  This prepares to build the library
112 in that very directory.
113
114 You can prepare to build the library in some other directory by going
115 to that other directory to run @code{configure}.  In order to run
116 configure, you will have to specify a directory for it, like this:
117
118 @smallexample
119 mkdir sun4
120 cd sun4
121 ../configure sparc-sun-sunos4.1
122 @end smallexample
123
124 @noindent
125 @code{configure} looks for the sources in whatever directory you
126 specified for finding @code{configure} itself.  It does not matter where
127 in the file system the source and build directories are---as long as you
128 specify the source directory when you run @code{configure}, you will get
129 the proper results.
130
131 This feature lets you keep sources and binaries in different
132 directories, and that makes it easy to build the library for several
133 different machines from the same set of sources.  Simply create a
134 build directory for each target machine, and run @code{configure} in
135 that directory specifying the target machine's configuration name.
136
137 The library has a number of special-purpose configuration parameters.
138 These are defined in the file @file{Makeconfig}; see the comments in
139 that file for the details.
140
141 But don't edit the file @file{Makeconfig} yourself---instead, create a
142 file @file{configparms} in the directory where you are building the
143 library, and define in that file the parameters you want to specify.
144 @file{configparms} should @strong{not} be an edited copy of
145 @file{Makeconfig}; specify only the parameters that you want to
146 override.  To see how to set these parameters, find the section of
147 @file{Makeconfig} that says ``These are the configuration variables.''
148 Then for each parameter that you want to change, copy the definition
149 from @file{Makeconfig} to your new @file{configparms} file, and change
150 the value as appropriate for your system.
151
152 It is easy to configure the GNU C library for cross-compilation by
153 setting a few variables in @file{configparms}.  Set @code{CC} to the
154 cross-compiler for the target you configured the library for; it is
155 important to use this same @code{CC} value when running
156 @code{configure}, like this: @samp{CC=@var{target}-gcc configure
157 @var{target}}.  Set @code{BUILD_CC} to the compiler to use for for
158 programs run on the build system as part of compiling the library.  You
159 may need to set @code{AR} and @code{RANLIB} to cross-compiling versions
160 of @code{ar} and @code{ranlib} if the native tools are not configured to
161 work with object files for the target you configured for.
162
163 Some of the machine-dependent code for some machines uses extensions in
164 the GNU C compiler, so you may need to compile the library with GCC.
165 (In fact, all of the existing complete ports require GCC.)
166
167
168 To build the library and related programs, type @code{make}.  This will
169 produce a lot of output, some of which may look like errors from
170 @code{make} (but isn't).  Look for error messages from @code{make}
171 containing @samp{***}.  Those indicate that something is really wrong.
172
173 To build and run some test programs which exercise some of the library
174 facilities, type @code{make check}.  This will produce several files
175 with names like @file{@var{program}.out}.
176
177 To format the @cite{GNU C Library Reference Manual} for printing, type
178 @w{@code{make dvi}}.
179
180 To install the library and its header files, and the Info files of the
181 manual, type @code{make install}.  This will build things if necessary,
182 before installing them.@refill
183
184 @node Tools for Installation
185 @appendixsubsec Recommended Tools to Install the GNU C Library
186 @cindex installation tools
187 @cindex tools, for installing library
188
189 We recommend installing the following GNU tools before attempting to
190 build the GNU C library:
191
192 @itemize @bullet
193 @item
194 @code{make} 3.75
195
196 You need the latest version of GNU @code{make}.  Modifying the GNU C
197 Library to work with other @code{make} programs would be so hard that we
198 recommend you port GNU @code{make} instead.  @strong{Really.}
199 We recommend version GNU @code{make} version 3.75 or later.
200
201 @item
202 GCC 2.7.2
203
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
206 have problems.
207
208 @item
209 @code{binutils} 2.6
210
211 Using the GNU @code{binutils} (assembler, linker, and related tools) is
212 preferable when possible, and they are required to build an ELF shared C
213 library.  We recommend @code{binutils} version 2.6 or later; earlier
214 versions are known to have problems.
215 @end itemize
216
217 @node Supported Configurations
218 @appendixsubsec Supported Configurations
219 @cindex configurations, all supported
220
221 The GNU C Library currently supports configurations that match the
222 following patterns:
223
224 @smallexample
225 alpha-dec-osf1
226 i@var{x}86-@var{anything}-bsd4.3
227 i@var{x}86-@var{anything}-gnu
228 i@var{x}86-@var{anything}-isc2.2
229 i@var{x}86-@var{anything}-isc3.@var{n}
230 i@var{x}86-@var{anything}-linux
231 i@var{x}86-@var{anything}-sco3.2
232 i@var{x}86-@var{anything}-sco3.2v4
233 i@var{x}86-@var{anything}-sysv
234 i@var{x}86-@var{anything}-sysv4
235 i@var{x}86-force_cpu386-none
236 i@var{x}86-sequent-bsd
237 i960-nindy960-none
238 m68k-hp-bsd4.3
239 m68k-mvme135-none
240 m68k-mvme136-none
241 m68k-sony-newsos3
242 m68k-sony-newsos4
243 m68k-sun-sunos4.@var{n}
244 mips-dec-ultrix4.@var{n}
245 mips-sgi-irix4.@var{n}
246 sparc-sun-solaris2.@var{n}
247 sparc-sun-sunos4.@var{n}
248 @end smallexample
249
250 Each case of @samp{i@var{x}86} can be @samp{i386}, @samp{i486}, or
251 @samp{i586}.  All of those configurations produce a library that can run
252 on any of these processors.  The library will be optimized for the
253 specified processor, but will not use instructions not available on all
254 of them.
255
256 While no other configurations are supported, there are handy aliases for
257 these few.  (These aliases work in other GNU software as well.)
258
259 @smallexample
260 decstation
261 hp320-bsd4.3 hp300bsd
262 i486-gnu
263 i586-linux
264 i386-sco
265 i386-sco3.2v4
266 i386-sequent-dynix
267 i386-svr4
268 news
269 sun3-sunos4.@var{n} sun3
270 sun4-solaris2.@var{n} sun4-sunos5.@var{n}
271 sun4-sunos4.@var{n} sun4
272 @end smallexample
273
274 @node Reporting Bugs
275 @appendixsec Reporting Bugs
276 @cindex reporting bugs
277 @cindex bugs, reporting
278
279 There are probably bugs in the GNU C library.  There are certainly
280 errors and omissions in this manual.  If you report them, they will get
281 fixed.  If you don't, no one will ever know about them and they will
282 remain unfixed for all eternity, if not longer.
283
284 To report a bug, first you must find it.  Hopefully, this will be the
285 hard part.  Once you've found a bug, make sure it's really a bug.  A
286 good way to do this is to see if the GNU C library behaves the same way
287 some other C library does.  If so, probably you are wrong and the
288 libraries are right (but not necessarily).  If not, one of the libraries
289 is probably wrong.
290
291 Once you're sure you've found a bug, try to narrow it down to the
292 smallest test case that reproduces the problem.  In the case of a C
293 library, you really only need to narrow it down to one library
294 function call, if possible.  This should not be too difficult.
295
296 The final step when you have a simple test case is to report the bug.
297 When reporting a bug, send your test case, the results you got, the
298 results you expected, what you think the problem might be (if you've
299 thought of anything), your system type, and the version of the GNU C
300 library which you are using.  Also include the files
301 @file{config.status} and @file{config.make} which are created by running
302 @file{configure}; they will be in whatever directory was current when
303 you ran @file{configure}.
304
305 If you think you have found some way in which the GNU C library does not
306 conform to the ANSI and POSIX standards (@pxref{Standards and
307 Portability}), that is definitely a bug.  Report it!@refill
308
309 Send bug reports to the Internet address
310 @samp{bug-glibc@@prep.ai.mit.edu} or the UUCP path
311 @samp{mit-eddie!prep.ai.mit.edu!bug-glibc}.  If you have other problems
312 with installation or use, please report those as well.@refill
313
314 If you are not sure how a function should behave, and this manual
315 doesn't tell you, that's a bug in the manual.  Report that too!  If the
316 function's behavior disagrees with the manual, then either the library
317 or the manual has a bug, so report the disagreement.  If you find any
318 errors or omissions in this manual, please report them to the Internet
319 address @samp{bug-glibc-manual@@prep.ai.mit.edu} or the UUCP path
320 @samp{mit-eddie!prep.ai.mit.edu!bug-glibc-manual}.
321
322 @node Source Layout
323 @appendixsec Adding New Functions
324
325 The process of building the library is driven by the makefiles, which
326 make heavy use of special features of GNU @code{make}.  The makefiles
327 are very complex, and you probably don't want to try to understand them.
328 But what they do is fairly straightforward, and only requires that you
329 define a few variables in the right places.
330
331 The library sources are divided into subdirectories, grouped by topic.
332 The @file{string} subdirectory has all the string-manipulation
333 functions, @file{stdio} has all the standard I/O functions, etc.
334
335 Each subdirectory contains a simple makefile, called @file{Makefile},
336 which defines a few @code{make} variables and then includes the global
337 makefile @file{Rules} with a line like:
338
339 @smallexample
340 include ../Rules
341 @end smallexample
342
343 @noindent
344 The basic variables that a subdirectory makefile defines are:
345
346 @table @code
347 @item subdir
348 The name of the subdirectory, for example @file{stdio}.
349 This variable @strong{must} be defined.
350
351 @item headers
352 The names of the header files in this section of the library,
353 such as @file{stdio.h}.
354
355 @item routines
356 @itemx aux
357 The names of the modules (source files) in this section of the library.
358 These should be simple names, such as @samp{strlen} (rather than
359 complete file names, such as @file{strlen.c}).  Use @code{routines} for
360 modules that define functions in the library, and @code{aux} for
361 auxiliary modules containing things like data definitions.  But the
362 values of @code{routines} and @code{aux} are just concatenated, so there
363 really is no practical difference.@refill
364
365 @item tests
366 The names of test programs for this section of the library.  These
367 should be simple names, such as @samp{tester} (rather than complete file
368 names, such as @file{tester.c}).  @w{@samp{make tests}} will build and
369 run all the test programs.  If a test program needs input, put the test
370 data in a file called @file{@var{test-program}.input}; it will be given to
371 the test program on its standard input.  If a test program wants to be
372 run with arguments, put the arguments (all on a single line) in a file
373 called @file{@var{test-program}.args}.@refill
374
375 @item others
376 The names of ``other'' programs associated with this section of the
377 library.  These are programs which are not tests per se, but are other
378 small programs included with the library.  They are built by
379 @w{@samp{make others}}.@refill
380
381 @item install-lib
382 @itemx install-data
383 @itemx install
384 Files to be installed by @w{@samp{make install}}.  Files listed in
385 @samp{install-lib} are installed in the directory specified by
386 @samp{libdir} in @file{configparms} or @file{Makeconfig}
387 (@pxref{Installation}).  Files listed in @code{install-data} are
388 installed in the directory specified by @samp{datadir} in
389 @file{configparms} or @file{Makeconfig}.  Files listed in @code{install}
390 are installed in the directory specified by @samp{bindir} in
391 @file{configparms} or @file{Makeconfig}.@refill
392
393 @item distribute
394 Other files from this subdirectory which should be put into a
395 distribution tar file.  You need not list here the makefile itself or
396 the source and header files listed in the other standard variables.
397 Only define @code{distribute} if there are files used in an unusual way
398 that should go into the distribution.
399
400 @item generated
401 Files which are generated by @file{Makefile} in this subdirectory.
402 These files will be removed by @w{@samp{make clean}}, and they will
403 never go into a distribution.
404
405 @item extra-objs
406 Extra object files which are built by @file{Makefile} in this
407 subdirectory.  This should be a list of file names like @file{foo.o};
408 the files will actually be found in whatever directory object files are
409 being built in.  These files will be removed by @w{@samp{make clean}}.
410 This variable is used for secondary object files needed to build
411 @code{others} or @code{tests}.
412 @end table
413
414 @node Porting
415 @appendixsec Porting the GNU C Library
416
417 The GNU C library is written to be easily portable to a variety of
418 machines and operating systems.  Machine- and operating system-dependent
419 functions are well separated to make it easy to add implementations for
420 new machines or operating systems.  This section describes the layout of
421 the library source tree and explains the mechanisms used to select
422 machine-dependent code to use.
423
424 All the machine-dependent and operating system-dependent files in the
425 library are in the subdirectory @file{sysdeps} under the top-level
426 library source directory.  This directory contains a hierarchy of
427 subdirectories (@pxref{Hierarchy Conventions}).
428
429 Each subdirectory of @file{sysdeps} contains source files for a
430 particular machine or operating system, or for a class of machine or
431 operating system (for example, systems by a particular vendor, or all
432 machines that use IEEE 754 floating-point format).  A configuration
433 specifies an ordered list of these subdirectories.  Each subdirectory
434 implicitly appends its parent directory to the list.  For example,
435 specifying the list @file{unix/bsd/vax} is equivalent to specifying the
436 list @file{unix/bsd/vax unix/bsd unix}.  A subdirectory can also specify
437 that it implies other subdirectories which are not directly above it in
438 the directory hierarchy.  If the file @file{Implies} exists in a
439 subdirectory, it lists other subdirectories of @file{sysdeps} which are
440 appended to the list, appearing after the subdirectory containing the
441 @file{Implies} file.  Lines in an @file{Implies} file that begin with a
442 @samp{#} character are ignored as comments.  For example,
443 @file{unix/bsd/Implies} contains:@refill
444 @smallexample
445 # BSD has Internet-related things.
446 unix/inet
447 @end smallexample
448 @noindent
449 and @file{unix/Implies} contains:
450 @need 300
451 @smallexample
452 posix
453 @end smallexample
454
455 @noindent
456 So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}.
457
458 @file{sysdeps} has two ``special'' subdirectories, called @file{generic}
459 and @file{stub}.  These two are always implicitly appended to the list
460 of subdirectories (in that order), so you needn't put them in an
461 @file{Implies} file, and you should not create any subdirectories under
462 them.  @file{generic} is for things that can be implemented in
463 machine-independent C, using only other machine-independent functions in
464 the C library.  @file{stub} is for @dfn{stub} versions of functions
465 which cannot be implemented on a particular machine or operating system.
466 The stub functions always return an error, and set @code{errno} to
467 @code{ENOSYS} (Function not implemented).  @xref{Error Reporting}.
468
469 A source file is known to be system-dependent by its having a version in
470 @file{generic} or @file{stub}; every system-dependent function should
471 have either a generic or stub implementation (there is no point in
472 having both).
473
474 If you come across a file that is in one of the main source directories
475 (@file{string}, @file{stdio}, etc.), and you want to write a machine- or
476 operating system-dependent version of it, move the file into
477 @file{sysdeps/generic} and write your new implementation in the
478 appropriate system-specific subdirectory.  Note that if a file is to be
479 system-dependent, it @strong{must not} appear in one of the main source
480 directories.@refill
481
482 There are a few special files that may exist in each subdirectory of
483 @file{sysdeps}:
484
485 @comment Blank lines after items make the table look better.
486 @table @file
487 @item Makefile
488
489 A makefile for this machine or operating system, or class of machine or
490 operating system.  This file is included by the library makefile
491 @file{Makerules}, which is used by the top-level makefile and the
492 subdirectory makefiles.  It can change the variables set in the
493 including makefile or add new rules.  It can use GNU @code{make}
494 conditional directives based on the variable @samp{subdir} (see above) to
495 select different sets of variables and rules for different sections of
496 the library.  It can also set the @code{make} variable
497 @samp{sysdep-routines}, to specify extra modules to be included in the
498 library.  You should use @samp{sysdep-routines} rather than adding
499 modules to @samp{routines} because the latter is used in determining
500 what to distribute for each subdirectory of the main source tree.@refill
501
502 Each makefile in a subdirectory in the ordered list of subdirectories to
503 be searched is included in order.  Since several system-dependent
504 makefiles may be included, each should append to @samp{sysdep-routines}
505 rather than simply setting it:
506
507 @smallexample
508 sysdep-routines := $(sysdep-routines) foo bar
509 @end smallexample
510
511 @need 1000
512 @item Subdirs
513
514 This file contains the names of new whole subdirectories under the
515 top-level library source tree that should be included for this system.
516 These subdirectories are treated just like the system-independent
517 subdirectories in the library source tree, such as @file{stdio} and
518 @file{math}.
519
520 Use this when there are completely new sets of functions and header
521 files that should go into the library for the system this subdirectory
522 of @file{sysdeps} implements.  For example,
523 @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
524 directory contains various network-oriented operations which only make
525 sense to put in the library on systems that support the Internet.@refill
526
527 @item Dist
528
529 This file contains the names of files (relative to the subdirectory of
530 @file{sysdeps} in which it appears) which should be included in the
531 distribution.  List any new files used by rules in the @file{Makefile}
532 in the same directory, or header files used by the source files in that
533 directory.  You don't need to list files that are implementations
534 (either C or assembly source) of routines whose names are given in the
535 machine-independent makefiles in the main source tree.
536
537 @item configure
538
539 This file is a shell script fragment to be run at configuration time.
540 The top-level @file{configure} script uses the shell @code{.} command to
541 read the @file{configure} file in each system-dependent directory
542 chosen, in order.  The @file{configure} files are often generated from
543 @file{configure.in} files using Autoconf.
544
545 A system-dependent @file{configure} script will usually add things to
546 the shell variables @samp{DEFS} and @samp{config_vars}; see the
547 top-level @file{configure} script for details.  The script can check for
548 @w{@samp{--with-@var{package}}} options that were passed to the
549 top-level @file{configure}.  For an option
550 @w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the
551 shell variable @w{@samp{with_@var{package}}} (with any dashes in
552 @var{package} converted to underscores) to @var{value}; if the option is
553 just @w{@samp{--with-@var{package}}} (no argument), then it sets
554 @w{@samp{with_@var{package}}} to @samp{yes}.
555
556 @item configure.in
557
558 This file is an Autoconf input fragment to be processed into the file
559 @file{configure} in this subdirectory.  @xref{Introduction,,,
560 autoconf.info, Autoconf: Generating Automatic Configuration Scripts},
561 for a description of Autoconf.  You should write either @file{configure}
562 or @file{configure.in}, but not both.  The first line of
563 @file{configure.in} should invoke the @code{m4} macro
564 @samp{GLIBC_PROVIDES}.  This macro does several @code{AC_PROVIDE} calls
565 for Autoconf macros which are used by the top-level @file{configure}
566 script; without this, those macros might be invoked again unnecessarily
567 by Autoconf.
568 @end table
569
570 That is the general system for how system-dependencies are isolated.
571 @iftex
572 The next section explains how to decide what directories in
573 @file{sysdeps} to use.  @ref{Porting to Unix}, has some tips on porting
574 the library to Unix variants.
575 @end iftex
576
577 @menu
578 * Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
579 * Porting to Unix::             Porting the library to an average
580                                    Unix-like system.
581 @end menu
582
583 @node Hierarchy Conventions
584 @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy
585
586 A GNU configuration name has three parts: the CPU type, the
587 manufacturer's name, and the operating system.  @file{configure} uses
588 these to pick the list of system-dependent directories to look for.  If
589 the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
590 directory @file{@var{machine}/fpu} is also used.  The operating system
591 often has a @dfn{base operating system}; for example, if the operating
592 system is @samp{sunos4.1}, the base operating system is @samp{unix/bsd}.
593 The algorithm used to pick the list of directories is simple:
594 @file{configure} makes a list of the base operating system,
595 manufacturer, CPU type, and operating system, in that order.  It then
596 concatenates all these together with slashes in between, to produce a
597 directory name; for example, the configuration @w{@samp{sparc-sun-sunos4.1}}
598 results in @file{unix/bsd/sun/sparc/sunos4.1}.  @file{configure} then
599 tries removing each element of the list in turn, so
600 @file{unix/bsd/sparc} and @file{sun/sparc} are also tried, among others.
601 Since the precise version number of the operating system is often not
602 important, and it would be very inconvenient, for example, to have
603 identical @file{sunos4.1.1} and @file{sunos4.1.2} directories,
604 @file{configure} tries successively less specific operating system names
605 by removing trailing suffixes starting with a period.
606
607 As an example, here is the complete list of directories that would be
608 tried for the configuration @w{@samp{sparc-sun-sunos4.1}} (without the
609 @w{@samp{--nfp}} option):
610
611 @smallexample
612 sparc/fpu
613 unix/bsd/sun/sunos4.1/sparc
614 unix/bsd/sun/sunos4.1
615 unix/bsd/sun/sunos4/sparc
616 unix/bsd/sun/sunos4
617 unix/bsd/sun/sunos/sparc
618 unix/bsd/sun/sunos
619 unix/bsd/sun/sparc
620 unix/bsd/sun
621 unix/bsd/sunos4.1/sparc
622 unix/bsd/sunos4.1
623 unix/bsd/sunos4/sparc
624 unix/bsd/sunos4
625 unix/bsd/sunos/sparc
626 unix/bsd/sunos
627 unix/bsd/sparc
628 unix/bsd
629 unix/sun/sunos4.1/sparc
630 unix/sun/sunos4.1
631 unix/sun/sunos4/sparc
632 unix/sun/sunos4
633 unix/sun/sunos/sparc
634 unix/sun/sunos
635 unix/sun/sparc
636 unix/sun
637 unix/sunos4.1/sparc
638 unix/sunos4.1
639 unix/sunos4/sparc
640 unix/sunos4
641 unix/sunos/sparc
642 unix/sunos
643 unix/sparc
644 unix
645 sun/sunos4.1/sparc
646 sun/sunos4.1
647 sun/sunos4/sparc
648 sun/sunos4
649 sun/sunos/sparc
650 sun/sunos
651 sun/sparc
652 sun
653 sunos4.1/sparc
654 sunos4.1
655 sunos4/sparc
656 sunos4
657 sunos/sparc
658 sunos
659 sparc
660 @end smallexample
661
662 Different machine architectures are conventionally subdirectories at the
663 top level of the @file{sysdeps} directory tree.  For example,
664 @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}.  These contain
665 files specific to those machine architectures, but not specific to any
666 particular operating system.  There might be subdirectories for
667 specializations of those architectures, such as
668 @w{@file{sysdeps/m68k/68020}}. Code which is specific to the
669 floating-point coprocessor used with a particular machine should go in
670 @w{@file{sysdeps/@var{machine}/fpu}}.
671
672 There are a few directories at the top level of the @file{sysdeps}
673 hierarchy that are not for particular machine architectures.
674
675 @table @file
676 @item generic
677 @itemx stub
678 As described above (@pxref{Porting}), these are the two subdirectories
679 that every configuration implicitly uses after all others.
680
681 @item ieee754
682 This directory is for code using the IEEE 754 floating-point format,
683 where the C type @code{float} is IEEE 754 single-precision format, and
684 @code{double} is IEEE 754 double-precision format.  Usually this
685 directory is referred to in the @file{Implies} file in a machine
686 architecture-specific directory, such as @file{m68k/Implies}.
687
688 @item posix
689 This directory contains implementations of things in the library in
690 terms of @sc{POSIX.1} functions.  This includes some of the @sc{POSIX.1}
691 functions themselves.  Of course, @sc{POSIX.1} cannot be completely
692 implemented in terms of itself, so a configuration using just
693 @file{posix} cannot be complete.
694
695 @item unix
696 This is the directory for Unix-like things.  @xref{Porting to Unix}.
697 @file{unix} implies @file{posix}.  There are some special-purpose
698 subdirectories of @file{unix}:
699
700 @table @file
701 @item unix/common
702 This directory is for things common to both BSD and System V release 4.
703 Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
704
705 @item unix/inet
706 This directory is for @code{socket} and related functions on Unix systems.
707 The @file{inet} top-level subdirectory is enabled by @file{unix/inet/Subdirs}.
708 @file{unix/common} implies @file{unix/inet}.
709 @end table
710
711 @item mach
712 This is the directory for things based on the Mach microkernel from CMU
713 (including the GNU operating system).  Other basic operating systems
714 (VMS, for example) would have their own directories at the top level of
715 the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
716 @end table
717
718 @node Porting to Unix
719 @appendixsubsec Porting the GNU C Library to Unix Systems
720
721 Most Unix systems are fundamentally very similar.  There are variations
722 between different machines, and variations in what facilities are
723 provided by the kernel.  But the interface to the operating system
724 facilities is, for the most part, pretty uniform and simple.
725
726 The code for Unix systems is in the directory @file{unix}, at the top
727 level of the @file{sysdeps} hierarchy.  This directory contains
728 subdirectories (and subdirectory trees) for various Unix variants.
729
730 The functions which are system calls in most Unix systems are
731 implemented in assembly code in files in @file{sysdeps/unix}.  These
732 files are named with a suffix of @samp{.S}; for example,
733 @file{__open.S}.  Files ending in @samp{.S} are run through the C
734 preprocessor before being fed to the assembler.
735
736 These files all use a set of macros that should be defined in
737 @file{sysdep.h}.  The @file{sysdep.h} file in @file{sysdeps/unix}
738 partially defines them; a @file{sysdep.h} file in another directory must
739 finish defining them for the particular machine and operating system
740 variant.  See @file{sysdeps/unix/sysdep.h} and the machine-specific
741 @file{sysdep.h} implementations to see what these macros are and what
742 they should do.@refill
743
744 The system-specific makefile for the @file{unix} directory (that is, the
745 file @file{sysdeps/unix/Makefile}) gives rules to generate several files
746 from the Unix system you are building the library on (which is assumed
747 to be the target system you are building the library @emph{for}).  All
748 the generated files are put in the directory where the object files are
749 kept; they should not affect the source tree itself.  The files
750 generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
751 @file{errlist.c} (for the @file{stdio} section of the library).
752
753 @ignore
754 @c This section might be a good idea if it is finished,
755 @c but there's no point including it as it stands. --rms
756 @c @appendixsec Compatibility with Traditional C
757
758 @c ??? This section is really short now.  Want to keep it? --roland
759
760 Although the GNU C library implements the ANSI C library facilities, you
761 @emph{can} use the GNU C library with traditional, ``pre-ANSI'' C
762 compilers.  However, you need to be careful because the content and
763 organization of the GNU C library header files differs from that of
764 traditional C implementations.  This means you may need to make changes
765 to your program in order to get it to compile.
766 @end ignore
767
768 @node Contributors
769 @appendixsec Contributors to the GNU C Library
770
771 The GNU C library was written originally by Roland McGrath.  Some parts
772 of the library were contributed or worked on by other people.
773
774 @itemize @bullet
775 @item
776 The @code{getopt} function and related code were written by
777 Richard Stallman, @w{David J. MacKenzie}, and @w{Roland McGrath}.
778
779 @item
780 The merge sort function @code{qsort} was written by Michael J. Haertel.
781
782 @item
783 The quick sort function used as a fallback by @code{qsort} was written
784 by Douglas C. Schmidt.
785
786 @item
787 The memory allocation functions @code{malloc}, @code{realloc} and
788 @code{free} and related code were written by Michael J. Haertel.
789
790 @comment tege's name has an umlaut.
791 @tex
792 \xdef\SETtege{Torbj\"orn Granlund}
793 @end tex
794 @ifinfo
795 @set tege Torbjorn Granlund
796 @end ifinfo
797 @item
798 Fast implementations of many of the string functions (@code{memcpy},
799 @code{strlen}, etc.) were written by @value{tege}.
800
801 @item
802 The @file{tar.h} header file was written by David J. MacKenzie.
803
804 @item
805 The port to the MIPS DECStation running Ultrix 4
806 (@code{mips-dec-ultrix4})
807 was contributed by Brendan Kehoe and Ian Lance Taylor.
808
809 @item
810 The DES encryption function @code{crypt} and related functions were
811 contributed by Michael Glad.
812
813 @item
814 The @code{ftw} function was contributed by Ian Lance Taylor.
815
816 @item
817 The startup code to support SunOS shared libraries was contributed by
818 Tom Quinn.
819
820 @item
821 The @code{mktime} function was contributed by Paul Eggert.
822
823 @item
824 The port to the Sequent Symmetry running Dynix version 3
825 (@code{i386-sequent-bsd}) was contributed by Jason Merrill.
826
827 @item
828 The timezone support code is derived from the public-domain timezone
829 package by Arthur David Olson and his many contributors.
830
831 @item
832 The port to the DEC Alpha running OSF/1 (@code{alpha-dec-osf1}) was
833 contributed by Brendan Kehoe, using some code written by Roland McGrath.
834
835 @item
836 The port to SGI machines running Irix 4 (@code{mips-sgi-irix4}) was
837 contributed by Tom Quinn.
838
839 @item
840 The port of the Mach and Hurd code to the MIPS architecture
841 (@code{mips-@var{anything}-gnu}) was contributed by Kazumoto Kojima.
842
843 @item
844 The floating-point printing function used by @code{printf} and friends
845 and the floating-point reading function used by @code{scanf},
846 @code{strtod} and friends were written by Ulrich Drepper.  The
847 multi-precision integer functions used in those functions are taken from
848 GNU MP, which was contributed by @value{tege}.
849
850 @item
851 The internationalization support in the library, and the support programs
852 @code{locale} and @code{localedef}, were written by Ulrich Drepper.
853 Ulrich Drepper adapted the support code for message catalogs
854 (@file{libintl.h}, etc.) from the GNU @code{gettext} package, which he
855 also wrote.  He also contributed the entire suite of multi-byte and
856 wide-character support functions (@file{wctype.h}, @file{wchar.h}, etc.).
857
858 @item
859 The port to Linux i386/ELF (@code{i386-@var{anything}-linux}) was
860 contributed by Ulrich Drepper, based in large part on work done in
861 Hongjiu Lu's Linux version of the GNU C Library.
862
863 @item
864 The port to Linux/m68k (@code{m68k-@var{anything}-linux}) was
865 contributed by Andreas Schwab.
866
867 @item
868 Stephen R. van den Berg contributed a highly-optimized @code{strstr} function.
869
870 @item
871 Ulrich Drepper contributed the @code{hsearch} and @code{drand48}
872 families of functions; reentrant @samp{@dots{}@code{_r}} versions of the
873 @code{random} family; System V shared memory and IPC support code; and
874 several highly-optimized string functions for i@var{x}86 processors.
875
876 @item
877 The Internet-related code (most of the @file{inet} subdirectory) and
878 several other miscellaneous functions and header files have been
879 included from 4.4 BSD with little or no modification.
880
881 All code incorporated from 4.4 BSD is under the following copyright:
882
883 @quotation
884 @display
885 Copyright @copyright{} 1991 Regents of the University of California.
886 All rights reserved.
887 @end display
888
889 Redistribution and use in source and binary forms, with or without
890 modification, are permitted provided that the following conditions
891 are met:
892
893 @enumerate
894 @item
895 Redistributions of source code must retain the above copyright
896 notice, this list of conditions and the following disclaimer.
897 @item
898 Redistributions in binary form must reproduce the above copyright
899 notice, this list of conditions and the following disclaimer in the
900 documentation and/or other materials provided with the distribution.
901 @item
902 All advertising materials mentioning features or use of this software
903 must display the following acknowledgement:
904 @quotation
905 This product includes software developed by the University of
906 California, Berkeley and its contributors.
907 @end quotation
908 @item
909 Neither the name of the University nor the names of its contributors
910 may be used to endorse or promote products derived from this software
911 without specific prior written permission.
912 @end enumerate
913
914 @sc{this software is provided by the regents and contributors ``as is'' and
915 any express or implied warranties, including, but not limited to, the
916 implied warranties of merchantability and fitness for a particular purpose
917 are disclaimed.  in no event shall the regents or contributors be liable
918 for any direct, indirect, incidental, special, exemplary, or consequential
919 damages (including, but not limited to, procurement of substitute goods
920 or services; loss of use, data, or profits; or business interruption)
921 however caused and on any theory of liability, whether in contract, strict
922 liability, or tort (including negligence or otherwise) arising in any way
923 out of the use of this software, even if advised of the possibility of
924 such damage.}
925 @end quotation
926
927 @item
928 The random number generation functions @code{random}, @code{srandom},
929 @code{setstate} and @code{initstate}, which are also the basis for the
930 @code{rand} and @code{srand} functions, were written by Earl T. Cohen
931 for the University of California at Berkeley and are copyrighted by the
932 Regents of the University of California.  They have undergone minor
933 changes to fit into the GNU C library and to fit the ANSI C standard,
934 but the functional code is Berkeley's.@refill
935
936 @item
937 The Internet resolver code is taken directly from BIND 4.9.3, which is
938 under both the Berkeley copyright above and also:
939
940 @quotation
941 Portions Copyright @copyright{} 1993 by Digital Equipment Corporation.
942
943 Permission to use, copy, modify, and distribute this software for any
944 purpose with or without fee is hereby granted, provided that the above
945 copyright notice and this permission notice appear in all copies, and
946 that the name of Digital Equipment Corporation not be used in
947 advertising or publicity pertaining to distribution of the document or
948 software without specific, written prior permission.
949
950 @sc{the software is provided ``as is'' and digital equipment corp.
951 disclaims all warranties with regard to this software, including all
952 implied warranties of merchantability and fitness.  in no event shall
953 digital equipment corporation be liable for any special, direct,
954 indirect, or consequential damages or any damages whatsoever resulting
955 from loss of use, data or profits, whether in an action of contract,
956 negligence or other tortious action, arising out of or in connection
957 with the use or performance of this software.}
958 @end quotation
959
960 @item
961 The code to support Sun RPC is taken verbatim from Sun's
962 @w{@sc{rpcsrc-4.0}} distribution, and is covered by this copyright:
963
964 @quotation
965 @display
966 Copyright @copyright{} 1984, Sun Microsystems, Inc.
967 @end display
968
969 Sun RPC is a product of Sun Microsystems, Inc. and is provided for
970 unrestricted use provided that this legend is included on all tape media
971 and as a part of the software program in whole or part.  Users may copy
972 or modify Sun RPC without charge, but are not authorized to license or
973 distribute it to anyone else except as part of a product or program
974 developed by the user.
975
976 @sc{sun rpc is provided as is with no warranties of any kind including the
977 warranties of design, merchantibility and fitness for a particular
978 purpose, or arising from a course of dealing, usage or trade practice.}
979
980 Sun RPC is provided with no support and without any obligation on the
981 part of Sun Microsystems, Inc. to assist in its use, correction,
982 modification or enhancement.
983
984 @sc{sun microsystems, inc. shall have no liability with respect to the
985 infringement of copyrights, trade secrets or any patents by sun rpc
986 or any part thereof.}
987
988 In no event will Sun Microsystems, Inc. be liable for any lost revenue
989 or profits or other special, indirect and consequential damages, even if
990 Sun has been advised of the possibility of such damages.
991
992 @display
993 Sun Microsystems, Inc.
994 2550 Garcia Avenue
995 Mountain View, California  94043
996 @end display
997 @end quotation
998
999 @item
1000 Some of the support code for Mach is taken from Mach 3.0 by CMU,
1001 and is under the following copyright terms:
1002
1003 @quotation
1004 @display
1005 Mach Operating System
1006 Copyright @copyright{} 1991,1990,1989 Carnegie Mellon University
1007 All Rights Reserved.
1008 @end display
1009
1010 Permission to use, copy, modify and distribute this software and its
1011 documentation is hereby granted, provided that both the copyright
1012 notice and this permission notice appear in all copies of the
1013 software, derivative works or modified versions, and any portions
1014 thereof, and that both notices appear in supporting documentation.
1015
1016 @sc{carnegie mellon allows free use of this software in its ``as is''
1017 condition.  carnegie mellon disclaims any liability of any kind for
1018 any damages whatsoever resulting from the use of this software.}
1019
1020 Carnegie Mellon requests users of this software to return to
1021
1022 @display
1023  Software Distribution Coordinator
1024  School of Computer Science
1025  Carnegie Mellon University
1026  Pittsburgh PA 15213-3890
1027 @end display
1028
1029 @noindent
1030 or @samp{Software.Distribution@@CS.CMU.EDU} any improvements or
1031 extensions that they make and grant Carnegie Mellon the rights to
1032 redistribute these changes.
1033 @end quotation
1034
1035 @end itemize
1036
1037 @c @bye