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