2d7bd756efb1653076496b2f3941d07e711cc450
[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.
27
28 You need the latest version of GNU @code{make}.  Modifying the GNU C
29 Library to work with other @code{make} programs would be so hard that we
30 recommend you port GNU @code{make} instead.  @strong{Really.}@refill
31
32 To configure the GNU C library for your system, run the shell script
33 @file{configure} with @code{sh}.  Use an argument which is the
34 conventional GNU name for your system configuration---for example,
35 @samp{sparc-sun-sunos4.1}, for a Sun 4 running Sunos 4.1.
36 @xref{Installation, Installation, Installing GNU CC, gcc.info, Using and
37 Porting GNU CC}, for a full description of standard GNU configuration
38 names.  If you omit the configuration name, @file{configure} will try to
39 guess one for you by inspecting the system it is running on.  It may or
40 may not be able to come up with a guess, and the its guess might be
41 wrong.  @file{configure} will tell you the canonical name of the chosen
42 configuration before proceeding.
43
44 The GNU C Library currently supports configurations that match the
45 following patterns:
46
47 @smallexample
48 sparc-sun-sunos4.@var{n}
49 sparc-sun-solaris2.@var{n}
50 m68k-hp-bsd4.3
51 m68k-sun-sunos4.@var{n}
52 m68k-sony-newsos
53 mips-dec-ultrix4.@var{n}
54 i386-@var{anything}-bsd4.3
55 i386-@var{anything}-sysv
56 i386-@var{anything}-sysv4
57 i386-@var{anything}-sco3.2v2
58 i386-@var{anything}-sco3.2v4
59 i386-sequent-bsd
60 @end smallexample
61
62 While no other configurations are supported, there are handy aliases for
63 these few.  (These aliases work in other GNU software as well.)
64
65 @smallexample
66 sun4-sunos4.@var{n} sun4
67 sun4-solaris2.@var{n} sun4-sunos5.@var{n}
68 hp320-bsd4.3 hp300bsd
69 sun3-sunos4.@var{n} sun3
70 news
71 decstation
72 i386-svr4
73 i386-sco
74 i386-sco3.2v4
75 i386-sequent-dynix
76 @end smallexample
77
78 Here are some options that you should specify (if appropriate) when
79 you run @code{configure}:
80
81 @table @samp
82 @item --with-gnu-ld
83 Use this option if you plan to use GNU @code{ld} to link programs with
84 the GNU C Library.  (We strongly recommend that you do.)
85
86 @item --with-gnu-as
87 Use this option if you plan to use the GNU assembler, @code{gas}, when
88 building the GNU C Library.  On some systems, the library may not build
89 properly if you do @emph{not} use @code{gas}.
90
91 @c extra blank line makes it look better
92 @item --nfp
93
94 Use this option if your computer lacks hardware floating point support.
95
96 @item --prefix=@var{directory}
97 Install machine-independent data files in subdirectories of
98 @file{@var{directory}}.  (You can also set this in @file{configparms};
99 see below.)
100
101 @item --exec-prefix=@var{directory}
102 Install the library and other machine-dependent files in subdirectories
103 of @file{@var{directory}}.  (You can also set this in
104 @file{configparms}; see below.)
105 @end table
106
107 The simplest way to run @code{configure} is to do it in the directory
108 that contains the library sources.  This prepares to build the library
109 in that very directory.
110
111 You can prepare to build the library in some other directory by going
112 to that other directory to run @code{configure}.  In order to run
113 configure, you will have to specify a directory for it, like this:
114
115 @smallexample
116 mkdir ../hp320
117 cd ../hp320
118 ../src/configure hp320-bsd4.3
119 @end smallexample
120
121 @noindent
122 @code{configure} looks for the sources in whatever directory you
123 specified for finding @code{configure} itself.  It does not matter where
124 in the file system the source and build directories are---as long as you
125 specify the source directory when you run @code{configure}, you will get
126 the proper results.
127
128 This feature lets you keep sources and binaries in different
129 directories, and that makes it easy to build the library for several
130 different machines from the same set of sources.  Simply create a 
131 build directory for each target machine, and run @code{configure} in
132 that directory specifying the target machine's configuration name.
133
134 The library has a number of special-purpose configuration parameters.
135 These are defined in the file @file{Makeconfig}; see the comments in
136 that file for the details.
137
138 But don't edit the file @file{Makeconfig} yourself---instead, create a
139 file @file{configparms} in the directory where you are building the
140 library, and define in that file the parameters you want to specify.
141 @file{configparms} should @strong{not} be an edited copy of
142 @file{Makeconfig}; specify only the parameters that you want to
143 override.
144
145 Some of the machine-dependent code for some machines uses extensions in
146 the GNU C compiler, so you may need to compile the library with GCC.
147 (In fact, all of the existing complete ports require GCC.)
148
149 The current release of the C library contains some header files that the
150 compiler normally provides: @file{stddef.h}, @file{stdarg.h}, and
151 several files with names of the form @file{va-@var{machine}.h}.  The
152 versions of these files that came with older releases of GCC do not work
153 properly with the GNU C library.  The @file{stddef.h} file in release
154 2.2 and later of GCC is correct.  If you have release 2.2 or later of
155 GCC, use its version of @file{stddef.h} instead of the C library's.  To
156 do this, put the line @w{@samp{override stddef.h =}} in
157 @file{configparms}.  The other files are corrected in release 2.3 and
158 later of GCC.  @file{configure} will automatically detect whether the
159 installed @file{stdarg.h} and @file{va-@var{machine}.h} files are
160 compatible with the C library, and use its own if not.
161
162 There is a potential problem with the @code{size_t} type and versions of
163 GCC prior to release 2.4.  ANSI C requires that @code{size_t} always be
164 an unsigned type.  For compatibility with existing systems' header
165 files, GCC defines @code{size_t} in @file{stddef.h} to be whatever type
166 the system's @file{sys/types.h} defines it to be.  Most Unix systems
167 that define @code{size_t} in @file{sys/types.h}, define it to be a
168 signed type.  Some code in the library depends on @code{size_t} being an
169 unsigned type, and will not work correctly if it is signed.
170
171 The GNU C library code which expects @code{size_t} to be unsigned is
172 correct.  The definition of @code{size_t} as a signed type is incorrect.
173 Versions 2.4 and later of GCC always define @code{size_t} as an unsigned
174 type, and GCC's @file{fixincludes} script massages the system's
175 @file{sys/types.h} so as not to conflict with this.
176
177 In the meantime, we work around this problem by telling GCC explicitly
178 to use an unsigned type for @code{size_t} when compiling the GNU C
179 library.  @file{configure} will automatically detect what type GCC uses
180 for @code{size_t} arrange to override it if necessary.
181
182 To build the library, type @code{make lib}.  This will produce a lot of
183 output, some of which looks like errors from @code{make} (but isn't).
184 Look for error messages from @code{make} containing @samp{***}.  Those
185 indicate that something is really wrong.
186
187 To build and run some test programs which exercise some of the library
188 facilities, type @code{make tests}.  This will produce several files
189 with names like @file{@var{program}.out}.
190
191 To format the @cite{GNU C Library Reference Manual} for printing, type
192 @w{@code{make dvi}}.  To format the Info version of the manual for on
193 line reading with @kbd{C-h i} in Emacs or with the @code{info} program,
194 type @w{@code{make info}}.
195
196 To install the library and its header files, and the Info files of the
197 manual, type @code{make install}, after setting the installation
198 directories in @file{configparms}.  This will build things if necessary,
199 before installing them.@refill
200
201 @node Reporting Bugs
202 @appendixsec Reporting Bugs
203 @cindex reporting bugs
204
205 There are probably bugs in the GNU C library.  There are certainly
206 errors and omissions in this manual.  If you report them, they will get
207 fixed.  If you don't, no one will ever know about them and they will
208 remain unfixed for all eternity, if not longer.
209
210 To report a bug, first you must find it.  Hopefully, this will be the
211 hard part.  Once you've found a bug, make sure it's really a bug.  A
212 good way to do this is to see if the GNU C library behaves the same way
213 some other C library does.  If so, probably you are wrong and the
214 libraries are right (but not necessarily).  If not, one of the libraries
215 is probably wrong.
216
217 Once you're sure you've found a bug, try to narrow it down to the
218 smallest test case that reproduces the problem.  In the case of a C
219 library, you really only need to narrow it down to one library
220 function call, if possible.  This should not be too difficult.
221
222 The final step when you have a simple test case is to report the bug.
223 When reporting a bug, send your test case, the results you got, the
224 results you expected, what you think the problem might be (if you've
225 thought of anything), your system type, and the version of the GNU C
226 library which you are using.  Also include the files
227 @file{config.status} and @file{config.make} which are created by running
228 @file{configure}; they will be in whatever directory was current when
229 you ran @file{configure}.
230
231 If you think you have found some way in which the GNU C library does not
232 conform to the ANSI and POSIX standards (@pxref{Standards and
233 Portability}), that is definitely a bug.  Report it!@refill
234
235 Send bug reports to the Internet address
236 @samp{bug-glibc@@prep.ai.mit.edu} or the UUCP path
237 @samp{mit-eddie!prep.ai.mit.edu!bug-glibc}.  If you have other problems
238 with installation or use, please report those as well.@refill
239
240 If you are not sure how a function should behave, and this manual
241 doesn't tell you, that's a bug in the manual.  Report that too!  If the
242 function's behavior disagrees with the manual, then either the library
243 or the manual has a bug, so report the disagreement.  If you find any
244 errors or omissions in this manual, please report them to the Internet
245 address @samp{bug-glibc-manual@@prep.ai.mit.edu} or the UUCP path
246 @samp{mit-eddie!prep.ai.mit.edu!bug-glibc-manual}.
247
248 @node Source Layout
249 @appendixsec Adding New Functions
250
251 The process of building the library is driven by the makefiles, which
252 make heavy use of special features of GNU @code{make}.  The makefiles
253 are very complex, and you probably don't want to try to understand them.
254 But what they do is fairly straightforward, and only requires that you
255 define a few variables in the right places.
256
257 The library sources are divided into subdirectories, grouped by topic.
258 The @file{string} subdirectory has all the string-manipulation
259 functions, @file{stdio} has all the standard I/O functions, etc.
260
261 Each subdirectory contains a simple makefile, called @file{Makefile},
262 which defines a few @code{make} variables and then includes the global
263 makefile @file{Rules} with a line like:
264
265 @smallexample
266 include ../Rules
267 @end smallexample
268
269 @noindent
270 The basic variables that a subdirectory makefile defines are:
271
272 @table @code
273 @item subdir
274 The name of the subdirectory, for example @file{stdio}.
275 This variable @strong{must} be defined.
276
277 @item headers
278 The names of the header files in this section of the library,
279 such as @file{stdio.h}.
280
281 @item routines
282 @itemx aux
283 The names of the modules (source files) in this section of the library.
284 These should be simple names, such as @samp{strlen} (rather than
285 complete file names, such as @file{strlen.c}).  Use @code{routines} for
286 modules that define functions in the library, and @code{aux} for
287 auxiliary modules containing things like data definitions.  But the
288 values of @code{routines} and @code{aux} are just concatenated, so there
289 really is no practical difference.@refill
290
291 @item tests
292 The names of test programs for this section of the library.  These
293 should be simple names, such as @samp{tester} (rather than complete file
294 names, such as @file{tester.c}).  @w{@samp{make tests}} will build and
295 run all the test programs.  If a test program needs input, put the test
296 data in a file called @file{@var{test-program}.input}; it will be given to
297 the test program on its standard input.  If a test program wants to be
298 run with arguments, put the arguments (all on a single line) in a file
299 called @file{@var{test-program}.args}.@refill
300
301 @item others
302 The names of ``other'' programs associated with this section of the
303 library.  These are programs which are not tests per se, but are other
304 small programs included with the library.  They are built by
305 @w{@samp{make others}}.@refill
306
307 @item install-lib
308 @itemx install-data
309 @itemx install
310 Files to be installed by @w{@samp{make install}}.  Files listed in
311 @samp{install-lib} are installed in the directory specified by
312 @samp{libdir} in @file{configparms} or @file{Makeconfig}
313 (@pxref{Installation}).  Files listed in @code{install-data} are
314 installed in the directory specified by @samp{datadir} in
315 @file{configparms} or @file{Makeconfig}.  Files listed in @code{install}
316 are installed in the directory specified by @samp{bindir} in
317 @file{configparms} or @file{Makeconfig}.@refill
318
319 @item distribute
320 Other files from this subdirectory which should be put into a
321 distribution tar file.  You need not list here the makefile itself or
322 the source and header files listed in the other standard variables.
323 Only define @code{distribute} if there are files used in an unusual way
324 that should go into the distribution.
325
326 @item generated
327 Files which are generated by @file{Makefile} in this subdirectory.
328 These files will be removed by @w{@samp{make clean}}, and they will
329 never go into a distribution.
330
331 @item extra-objs
332 Extra object files which are built by @file{Makefile} in this
333 subdirectory.  This should be a list of file names like @file{foo.o};
334 the files will actually be found in whatever directory object files are
335 being built in.  These files will be removed by @w{@samp{make clean}}.
336 This variable is used for secondary object files needed to build
337 @code{others} or @code{tests}.
338 @end table
339
340 @node Porting
341 @appendixsec Porting the GNU C Library
342
343 The GNU C library is written to be easily portable to a variety of
344 machines and operating systems.  Machine- and operating system-dependent
345 functions are well separated to make it easy to add implementations for
346 new machines or operating systems.  This section describes the layout of
347 the library source tree and explains the mechanisms used to select
348 machine-dependent code to use.
349
350 All the machine-dependent and operating system-dependent files in the
351 library are in the subdirectory @file{sysdeps} under the top-level
352 library source directory.  This directory contains a hierarchy of
353 subdirectories (@pxref{Hierarchy Conventions}).
354
355 Each subdirectory of @file{sysdeps} contains source files for a
356 particular machine or operating system, or for a class of machine or
357 operating system (for example, systems by a particular vendor, or all
358 machines that use IEEE 754 floating-point format).  A configuration
359 specifies an ordered list of these subdirectories.  Each subdirectory
360 implicitly appends its parent directory to the list.  For example,
361 specifying the list @file{unix/bsd/vax} is equivalent to specifying the
362 list @file{unix/bsd/vax unix/bsd unix}.  A subdirectory can also specify
363 that it implies other subdirectories which are not directly above it in
364 the directory hierarchy.  If the file @file{Implies} exists in a
365 subdirectory, it lists other subdirectories of @file{sysdeps} which are
366 appended to the list, appearing after the subdirectory containing the
367 @file{Implies} file.  Lines in an @file{Implies} file that begin with a
368 @samp{#} character are ignored as comments.  For example,
369 @file{unix/bsd/Implies} contains:@refill
370 @smallexample
371 # BSD has Internet-related things.
372 unix/inet
373 @end smallexample
374 @noindent
375 and @file{unix/Implies} contains:
376 @need 300
377 @smallexample
378 posix
379 @end smallexample
380
381 @noindent
382 So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}.
383
384 @file{sysdeps} has two ``special'' subdirectories, called @file{generic}
385 and @file{stub}.  These two are always implicitly appended to the list
386 of subdirectories (in that order), so you needn't put them in an
387 @file{Implies} file, and you should not create any subdirectories under
388 them.  @file{generic} is for things that can be implemented in
389 machine-independent C, using only other machine-independent functions in
390 the C library.  @file{stub} is for @dfn{stub} versions of functions
391 which cannot be implemented on a particular machine or operating system.
392 The stub functions always return an error, and set @code{errno} to
393 @code{ENOSYS} (Function not implemented).  @xref{Error Reporting}.
394
395 A source file is known to be system-dependent by its having a version in
396 @file{generic} or @file{stub}; every system-dependent function should
397 have either a generic or stub implementation (there is no point in
398 having both).
399
400 If you come across a file that is in one of the main source directories
401 (@file{string}, @file{stdio}, etc.), and you want to write a machine- or
402 operating system-dependent version of it, move the file into
403 @file{sysdeps/generic} and write your new implementation in the
404 appropriate system-specific subdirectory.  Note that if a file is to be
405 system-dependent, it @strong{must not} appear in one of the main source
406 directories.@refill
407
408 There are a few special files that may exist in each subdirectory of
409 @file{sysdeps}:
410
411 @comment Blank lines after items make the table look better.
412 @table @file
413 @item Makefile
414
415 A makefile for this machine or operating system, or class of machine or
416 operating system.  This file is included by the library makefile
417 @file{Makerules}, which is used by the top-level makefile and the
418 subdirectory makefiles.  It can change the variables set in the
419 including makefile or add new rules.  It can use GNU @code{make}
420 conditional directives based on the variable @samp{subdir} (see above) to
421 select different sets of variables and rules for different sections of
422 the library.  It can also set the @code{make} variable
423 @samp{sysdep-routines}, to specify extra modules to be included in the
424 library.  You should use @samp{sysdep-routines} rather than adding
425 modules to @samp{routines} because the latter is used in determining
426 what to distribute for each subdirectory of the main source tree.@refill
427
428 Each makefile in a subdirectory in the ordered list of subdirectories to
429 be searched is included in order.  Since several system-dependent
430 makefiles may be included, each should append to @samp{sysdep-routines}
431 rather than simply setting it:
432
433 @smallexample
434 sysdep-routines := $(sysdep-routines) foo bar
435 @end smallexample
436
437 @need 1000
438 @item Subdirs
439
440 This file contains the names of new whole subdirectories under the
441 top-level library source tree that should be included for this system.
442 These subdirectories are treated just like the system-independent
443 subdirectories in the library source tree, such as @file{stdio} and
444 @file{math}.
445
446 Use this when there are completely new sets of functions and header
447 files that should go into the library for the system this subdirectory
448 of @file{sysdeps} implements.  For example,
449 @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
450 directory contains various network-oriented operations which only make
451 sense to put in the library on systems that support the Internet.@refill
452
453 @item Dist
454
455 This file contains the names of files (relative to the subdirectory of
456 @file{sysdeps} in which it appears) which should be included in the
457 distribution.  List any new files used by rules in the @file{Makefile}
458 in the same directory, or header files used by the source files in that
459 directory.  You don't need to list files that are implementations
460 (either C or assembly source) of routines whose names are given in the
461 machine-independent makefiles in the main source tree.
462
463 @item configure
464
465 This file is a shell script fragment to be run at configuration time.
466 The top-level @file{configure} script uses the shell @code{.} command to
467 read the @file{configure} file in each system-dependent directory
468 chosen, in order.  The @file{configure} files are often generated from
469 @file{configure.in} files using Autoconf.
470
471 A system-dependent @file{configure} script will usually add things to
472 the shell variables @samp{DEFS} and @samp{config_vars}; see the
473 top-level @file{configure} script for details.  The script can check for
474 @w{@samp{--with-@var{package}}} options that were passed to the
475 top-level @file{configure}.  For an option
476 @w{@samp{--with-@var{package}=var{@value}}} @file{configure} sets the
477 shell variable @w{@samp{with_@var{package}}} (with any dashes in
478 @var{package} converted to underscores) to @var{value}; if the option is
479 just @w{@samp{--with-@var{package}}} (no argument), then it sets
480 @w{@samp{with_@var{package}}} to @samp{yes}.
481
482 @item configure.in
483
484 This file is an Autoconf input fragment to be processed into the file
485 @file{configure} in this subdirectory.  @xref{Introduction,,,
486 autoconf.info, Autoconf: Generating Automatic Configuration Scripts},
487 for a description of Autoconf.  You should write either @file{configure}
488 or @file{configure.in}, but not both.  The first line of
489 @file{configure.in} should invoke the @code{m4} macro
490 @samp{GLIBC_PROVIDES}.  This macro does several @code{AC_PROVIDE} calls
491 for Autoconf macros which are used by the top-level @file{configure}
492 script; without this, those macros might be invoked again unnecessarily
493 by Autoconf.
494 @end table
495
496 That is the general system for how system-dependencies are isolated.
497 @iftex
498 The next section explains how to decide what directories in
499 @file{sysdeps} to use.  @ref{Porting to Unix}, has some tips on porting
500 the library to Unix variants.
501 @end iftex
502
503 @menu
504 * Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
505 * Porting to Unix::             Porting the library to an average
506                                    Unix-like system.
507 @end menu
508
509 @node Hierarchy Conventions
510 @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy
511
512 A GNU configuration name has three parts: the CPU type, the
513 manufacturer's name, and the operating system.  @file{configure} uses
514 these to pick the list of system-dependent directories to look for.  If
515 the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
516 directory @file{@var{machine}/fpu} is also used.  The operating system
517 often has a @dfn{base operating system}; for example, if the operating
518 system is @samp{sunos4.1}, the base operating system is @samp{unix/bsd}.
519 The algorithm used to pick the list of directories is simple:
520 @file{configure} makes a list of the base operating system,
521 manufacturer, CPU type, and operating system, in that order.  It then
522 concatenates all these together with slashes in between, to produce a
523 directory name; for example, the configuration @w{@samp{sparc-sun-sunos4.1}}
524 results in @file{unix/bsd/sun/sparc/sunos4.1}.  @file{configure} then
525 tries removing each element of the list in turn, so
526 @file{unix/bsd/sparc} and @file{sun/sparc} are also tried, among others.
527 Since the precise version number of the operating system is often not
528 important, and it would be very inconvenient, for example, to have
529 identical @file{sunos4.1.1} and @file{sunos4.1.2} directories,
530 @file{configure} tries successively less specific operating system names
531 by removing trailing suffixes starting with a period.
532
533 As an example, here is the complete list of directories that would be
534 tried for the configuration @w{@samp{sparc-sun-sunos4.1}} (without the
535 @w{@samp{--nfp}} option):
536
537 @smallexample
538 sparc/fpu
539 unix/bsd/sun/sunos4.1/sparc
540 unix/bsd/sun/sunos4.1
541 unix/bsd/sun/sunos4/sparc
542 unix/bsd/sun/sunos4
543 unix/bsd/sun/sunos/sparc
544 unix/bsd/sun/sunos
545 unix/bsd/sun/sparc
546 unix/bsd/sun
547 unix/bsd/sunos4.1/sparc
548 unix/bsd/sunos4.1
549 unix/bsd/sunos4/sparc
550 unix/bsd/sunos4
551 unix/bsd/sunos/sparc
552 unix/bsd/sunos
553 unix/bsd/sparc
554 unix/bsd
555 unix/sun/sunos4.1/sparc
556 unix/sun/sunos4.1
557 unix/sun/sunos4/sparc
558 unix/sun/sunos4
559 unix/sun/sunos/sparc
560 unix/sun/sunos
561 unix/sun/sparc
562 unix/sun
563 unix/sunos4.1/sparc
564 unix/sunos4.1
565 unix/sunos4/sparc
566 unix/sunos4
567 unix/sunos/sparc
568 unix/sunos
569 unix/sparc
570 unix
571 sun/sunos4.1/sparc
572 sun/sunos4.1
573 sun/sunos4/sparc
574 sun/sunos4
575 sun/sunos/sparc
576 sun/sunos
577 sun/sparc
578 sun
579 sunos4.1/sparc
580 sunos4.1
581 sunos4/sparc
582 sunos4
583 sunos/sparc
584 sunos
585 sparc
586 @end smallexample
587
588 Different machine architectures are conventionally subdirectories at the
589 top level of the @file{sysdeps} directory tree.  For example,
590 @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}.  These contain
591 files specific to those machine architectures, but not specific to any
592 particular operating system.  There might be subdirectories for
593 specializations of those architectures, such as
594 @w{@file{sysdeps/m68k/68020}}. Code which is specific to the
595 floating-point coprocessor used with a particular machine should go in
596 @w{@file{sysdeps/@var{machine}/fpu}}.
597
598 There are a few directories at the top level of the @file{sysdeps}
599 hierarchy that are not for particular machine architectures.
600
601 @table @file
602 @item generic
603 @itemx stub
604 As described above (@pxref{Porting}), these are the two subdirectories
605 that every configuration implicitly uses after all others.
606
607 @item ieee754
608 This directory is for code using the IEEE 754 floating-point format,
609 where the C type @code{float} is IEEE 754 single-precision format, and
610 @code{double} is IEEE 754 double-precision format.  Usually this
611 directory is referred to in the @file{Implies} file in a machine
612 architecture-specific directory, such as @file{m68k/Implies}.
613
614 @item posix
615 This directory contains implementations of things in the library in
616 terms of @sc{POSIX.1} functions.  This includes some of the @sc{POSIX.1}
617 functions themselves.  Of course, @sc{POSIX.1} cannot be completely
618 implemented in terms of itself, so a configuration using just
619 @file{posix} cannot be complete.
620
621 @item unix
622 This is the directory for Unix-like things.  @xref{Porting to Unix}.
623 @file{unix} implies @file{posix}.  There are some special-purpose
624 subdirectories of @file{unix}:
625
626 @table @file
627 @item unix/common
628 This directory is for things common to both BSD and System V release 4.
629 Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
630
631 @item unix/inet
632 This directory is for @code{socket} and related functions on Unix systems.
633 The @file{inet} top-level subdirectory is enabled by @file{unix/inet/Subdirs}.
634 @file{unix/common} implies @file{unix/inet}.
635 @end table
636
637 @item mach
638 This is the directory for things based on the Mach microkernel from CMU
639 (including the GNU operating system).  Other basic operating systems
640 (VMS, for example) would have their own directories at the top level of
641 the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
642 @end table
643
644 @node Porting to Unix
645 @appendixsubsec Porting the GNU C Library to Unix Systems
646
647 Most Unix systems are fundamentally very similar.  There are variations
648 between different machines, and variations in what facilities are
649 provided by the kernel.  But the interface to the operating system
650 facilities is, for the most part, pretty uniform and simple.
651
652 The code for Unix systems is in the directory @file{unix}, at the top
653 level of the @file{sysdeps} hierarchy.  This directory contains
654 subdirectories (and subdirectory trees) for various Unix variants.
655
656 The functions which are system calls in most Unix systems are
657 implemented in assembly code in files in @file{sysdeps/unix}.  These
658 files are named with a suffix of @samp{.S}; for example,
659 @file{__open.S}.  Files ending in @samp{.S} are run through the C
660 preprocessor before being fed to the assembler.
661
662 These files all use a set of macros that should be defined in
663 @file{sysdep.h}.  The @file{sysdep.h} file in @file{sysdeps/unix}
664 partially defines them; a @file{sysdep.h} file in another directory must
665 finish defining them for the particular machine and operating system
666 variant.  See @file{sysdeps/unix/sysdep.h} and the machine-specific
667 @file{sysdep.h} implementations to see what these macros are and what
668 they should do.@refill
669
670 The system-specific makefile for the @file{unix} directory (that is, the
671 file @file{sysdeps/unix/Makefile}) gives rules to generate several files
672 from the Unix system you are building the library on (which is assumed
673 to be the target system you are building the library @emph{for}).  All
674 the generated files are put in the directory where the object files are
675 kept; they should not affect the source tree itself.  The files
676 generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
677 @file{errlist.c} (for the @file{stdio} section of the library).
678
679 @ignore
680 @c This section might be a good idea if it is finished,
681 @c but there's no point including it as it stands. --rms
682 @c @appendixsec Compatibility with Traditional C
683
684 @c ??? This section is really short now.  Want to keep it? --roland
685
686 Although the GNU C library implements the ANSI C library facilities, you
687 @emph{can} use the GNU C library with traditional, ``pre-ANSI'' C
688 compilers.  However, you need to be careful because the content and
689 organization of the GNU C library header files differs from that of
690 traditional C implementations.  This means you may need to make changes
691 to your program in order to get it to compile.
692 @end ignore
693
694 @node Contributors
695 @appendixsec Contributors to the GNU C Library
696
697 The GNU C library was written almost entirely by Roland McGrath, who now
698 maintains it.  Some parts of the library were contributed or worked on
699 by other people.
700
701 @itemize @bullet
702 @item
703 The @code{getopt} function and related code were written by
704 Richard Stallman, @w{David J. MacKenzie}, and @w{Roland McGrath}.
705
706 @item
707 Most of the math functions are taken from 4.4 BSD; they have been
708 modified only slightly to work with the GNU C library.  The
709 Internet-related code (most of the @file{inet} subdirectory) and several
710 other miscellaneous functions and header files have been included with
711 little or no modification.
712
713 All code incorporated from 4.4 BSD is under the following copyright:
714
715 @quotation
716 @display
717 Copyright @copyright{} 1991 Regents of the University of California.
718 All rights reserved.
719 @end display
720
721 Redistribution and use in source and binary forms, with or without
722 modification, are permitted provided that the following conditions
723 are met:
724
725 @enumerate
726 @item
727 Redistributions of source code must retain the above copyright
728 notice, this list of conditions and the following disclaimer.
729 @item
730 Redistributions in binary form must reproduce the above copyright
731 notice, this list of conditions and the following disclaimer in the
732 documentation and/or other materials provided with the distribution.
733 @item
734 All advertising materials mentioning features or use of this software
735 must display the following acknowledgement:
736 @quotation
737         This product includes software developed by the University of
738         California, Berkeley and its contributors.
739 @end quotation
740 @item
741 Neither the name of the University nor the names of its contributors
742 may be used to endorse or promote products derived from this software
743 without specific prior written permission.
744 @end enumerate
745
746 @sc{this software is provided by the regents and contributors ``as is'' and
747 any express or implied warranties, including, but not limited to, the
748 implied warranties of merchantability and fitness for a particular purpose
749 are disclaimed.  in no event shall the regents or contributors be liable
750 for any direct, indirect, incidental, special, exemplary, or consequential
751 damages (including, but not limited to, procurement of substitute goods
752 or services; loss of use, data, or profits; or business interruption)
753 however caused and on any theory of liability, whether in contract, strict
754 liability, or tort (including negligence or otherwise) arising in any way
755 out of the use of this software, even if advised of the possibility of
756 such damage.}
757 @end quotation
758
759 @item
760 The random number generation functions @code{random}, @code{srandom},
761 @code{setstate} and @code{initstate}, which are also the basis for the
762 @code{rand} and @code{srand} functions, were written by Earl T. Cohen
763 for the University of California at Berkeley and are copyrighted by the
764 Regents of the University of California.  They have undergone minor
765 changes to fit into the GNU C library and to fit the ANSI C standard,
766 but the functional code is Berkeley's.@refill
767
768 @item
769 The merge sort function @code{qsort} was written by Michael J. Haertel.
770
771 @item
772 The quick sort function used as a fallback by @code{qsort} was written
773 by Douglas C. Schmidt.
774
775 @item
776 The memory allocation functions @code{malloc}, @code{realloc} and
777 @code{free} and related code were written by Michael J. Haertel.
778
779 @item
780 Fast implementations of many of the string functions (@code{memcpy},
781 @code{strlen}, etc.) were written by
782 @tex
783 Torbj\"orn
784 @end tex
785 @ifinfo
786 Torbjorn
787 @end ifinfo
788 Granlund.@refill
789
790 @item
791 Some of the support code for Mach is taken from Mach 3.0 by CMU,
792 and is under the following copyright terms:
793
794 @quotation
795 @display
796 Mach Operating System
797 Copyright @copyright{} 1991,1990,1989 Carnegie Mellon University
798 All Rights Reserved.
799 @end display
800
801 Permission to use, copy, modify and distribute this software and its
802 documentation is hereby granted, provided that both the copyright
803 notice and this permission notice appear in all copies of the
804 software, derivative works or modified versions, and any portions
805 thereof, and that both notices appear in supporting documentation.
806
807 @sc{carnegie mellon allows free use of this software in its ``as is''
808 condition.  carnegie mellon disclaims any liability of any kind for
809 any damages whatsoever resulting from the use of this software.}
810
811 Carnegie Mellon requests users of this software to return to
812
813 @display
814  Software Distribution Coordinator
815  School of Computer Science
816  Carnegie Mellon University
817  Pittsburgh PA 15213-3890
818 @end display
819
820 @noindent
821 or @samp{Software.Distribution@@CS.CMU.EDU} any improvements or
822 extensions that they make and grant Carnegie Mellon the rights to
823 redistribute these changes.
824 @end quotation
825
826 @item
827 The @file{tar.h} header file was written by David J. MacKenzie.
828
829 @item
830 The port to the MIPS DECStation running Ultrix 4
831 (@code{mips-dec-ultrix4})
832 was contributed by Brendan Kehoe and Ian Lance Taylor.
833
834 @item
835 The DES encryption function @code{crypt} and related functions were
836 contributed by Michael Glad.
837
838 @item
839 The @code{ftw} function was contributed by Ian Lance Taylor.
840
841 @item
842 The code to support SunOS shared libraries was contributed by Tom Quinn.
843
844 @item
845 The @code{mktime} function was contributed by Noel Cragg.
846
847 @item
848 The port to the Sequent Symmetry running Dynix version 3
849 (@code{i386-sequent-bsd}) was contributed by Jason Merrill.
850
851 @item
852 The timezone support code is derived from the public-domain timezone
853 package by Arthur David Olson.
854
855 @item
856 The Internet resolver code is taken directly from BIND 4.9.1, which is
857 under both the Berkeley copyright above and also:
858
859 @quotation
860 Portions Copyright @copyright{} 1993 by Digital Equipment Corporation.
861
862 Permission to use, copy, modify, and distribute this software for any
863 purpose with or without fee is hereby granted, provided that the above
864 copyright notice and this permission notice appear in all copies, and
865 that the name of Digital Equipment Corporation not be used in
866 advertising or publicity pertaining to distribution of the document or
867 software without specific, written prior permission.
868
869 @sc{the software is provided ``as is'' and digital equipment corp.
870 disclaims all warranties with regard to this software, including all
871 implied warranties of merchantability and fitness.  in no event shall
872 digital equipment corporation be liable for any special, direct,
873 indirect, or consequential damages or any damages whatsoever resulting
874 from loss of use, data or profits, whether in an action of contract,
875 negligence or other tortious action, arising out of or in connection
876 with the use or performance of this software.}
877 @end quotation
878 @end itemize
879
880 @c @bye