d880c085a149251758d6592d6cc8061b9d812532
[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 @example
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 example
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 @example
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 example
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 @example
116 mkdir ../hp320
117 cd ../hp320
118 ../src/configure hp320-bsd4.3
119 @end example
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 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.  If you report them,
206 they will get fixed.  If you don't, no one will ever know about them
207 and they will remain unfixed for all eternity, if not longer.
208
209 To report a bug, first you must find it.  Hopefully, this will be the
210 hard part.  Once you've found a bug, make sure it's really a bug.  A
211 good way to do this is to see if the GNU C library behaves the same way
212 some other C library does.  If so, probably you are wrong and the
213 libraries are right (but not necessarily).  If not, one of the libraries
214 is probably wrong.
215
216 Once you're sure you've found a bug, try to narrow it down to the
217 smallest test case that reproduces the problem.  In the case of a C
218 library, you really only need to narrow it down to one library
219 function call, if possible.  This should not be too difficult.
220
221 The final step when you have a simple test case is to report the bug.
222 When reporting a bug, send your test case, the results you got, the
223 results you expected, what you think the problem might be (if you've
224 thought of anything), your system type, and the version of the GNU C
225 library which you are using.  Also include the files
226 @file{config.status} and @file{config.make} which are created by running
227 @file{configure}; they will be in whatever directory was current when
228 you ran @file{configure}.
229
230 If you are not sure how a function should behave, and this manual
231 doesn't tell you, that's a bug in the manual.  Report that too!  If the
232 function's behavior disagrees with the manual, then either the library
233 or the manual has a bug, so report the disagreement.
234
235 If you think you have found some way in which the GNU C library does not
236 conform to the ANSI and POSIX standards (@pxref{Standards and
237 Portability}), that is definitely a bug.  Report it!@refill
238
239 Send bug reports to the Internet address
240 @samp{bug-glibc@@prep.ai.mit.edu} or the UUCP path
241 @samp{mit-eddie!prep.ai.mit.edu!bug-glibc}.  If you have other problems
242 with installation, use, or the documentation, please report those as
243 well.@refill
244
245 @node Source Layout
246 @appendixsec Adding New Functions
247
248 The process of building the library is driven by the makefiles, which
249 make heavy use of special features of GNU @code{make}.  The makefiles
250 are very complex, and you probably don't want to try to understand them.
251 But what they do is fairly straightforward, and only requires that you
252 define a few variables in the right places.
253
254 The library sources are divided into subdirectories, grouped by topic.
255 The @file{string} subdirectory has all the string-manipulation
256 functions, @file{stdio} has all the standard I/O functions, etc.
257
258 Each subdirectory contains a simple makefile, called @file{Makefile},
259 which defines a few @code{make} variables and then includes the global
260 makefile @file{Rules} with a line like:
261
262 @example
263 include ../Rules
264 @end example
265
266 @noindent
267 The basic variables that a subdirectory makefile defines are:
268
269 @table @code
270 @item subdir
271 The name of the subdirectory, for example @file{stdio}.
272 This variable @strong{must} be defined.
273
274 @item headers
275 The names of the header files in this section of the library,
276 such as @file{stdio.h}.
277
278 @item routines
279 @itemx aux
280 The names of the modules (source files) in this section of the library.
281 These should be simple names, such as @samp{strlen} (rather than
282 complete file names, such as @file{strlen.c}).  Use @code{routines} for
283 modules that define functions in the library, and @code{aux} for
284 auxiliary modules containing things like data definitions.  But the
285 values of @code{routines} and @code{aux} are just concatenated, so there
286 really is no practical difference.@refill
287
288 @item tests
289 The names of test programs for this section of the library.  These
290 should be simple names, such as @samp{tester} (rather than complete file
291 names, such as @file{tester.c}).  @w{@samp{make tests}} will build and
292 run all the test programs.  If a test program needs input, put the test
293 data in a file called @file{@var{test-program}.input}; it will be given to
294 the test program on its standard input.  If a test program wants to be
295 run with arguments, put the arguments (all on a single line) in a file
296 called @file{@var{test-program}.args}.@refill
297
298 @item others
299 The names of ``other'' programs associated with this section of the
300 library.  These are programs which are not tests per se, but are other
301 small programs included with the library.  They are built by
302 @w{@samp{make others}}.@refill
303
304 @item install-lib
305 @itemx install-data
306 @itemx install
307 Files to be installed by @w{@samp{make install}}.  Things listed in
308 @samp{install-lib} are installed in the directory specified by
309 @samp{libdir} in @file{Makeconfig} (@pxref{Installation}).  Files listed
310 in @code{install-data} are installed in the directory specified by
311 @samp{datadir} in @file{configparms} or @file{Makeconfig}.  Files listed
312 in @code{install} are installed in the directory specified by
313 @samp{bindir} in @file{Makeconfig}.@refill
314
315 @item distribute
316 Other files from this subdirectory which should be put into a
317 distribution tar file.  You need not list here the makefile itself or
318 the source and header files listed in the other standard variables.
319 Only define @code{distribute} if there are files used in an unusual way
320 that should go into the distribution.
321
322 @item generated
323 Files which are generated by @file{Makefile} in this subdirectory.
324 These files will be removed by @w{@samp{make clean}}, and they will
325 never go into a distribution.
326
327 @item extra-objs
328 Extra object files which are built by @file{Makefile} in this
329 subdirectory.  This should be a list of file names like @file{foo.o};
330 the files will actually be found in whatever directory object files are
331 being built in.  These files will be removed by @w{@samp{make clean}}.
332 This variable is used for secondary object files needed to build
333 @code{others} or @code{tests}.
334 @end table
335
336 @node Porting
337 @appendixsec Porting the GNU C Library
338
339 The GNU C library is written to be easily portable to a variety of
340 machines and operating systems.  Machine- and operating system-dependent
341 functions are well separated to make it easy to add implementations for
342 new machines or operating systems.  This section describes the layout of
343 the library source tree and explains the mechanisms used to select
344 machine-dependent code to use.
345
346 All the machine-dependent and operating system-dependent files in the
347 library are in the subdirectory @file{sysdeps} under the top-level
348 library source directory.  This directory contains a hierarchy of
349 subdirectories (@pxref{Hierarchy Conventions}).
350
351 Each subdirectory of @file{sysdeps} contains source files for a
352 particular machine or operating system, or for a class of machine or
353 operating system (for example, systems by a particular vendor, or all
354 machines that use IEEE 754 floating-point format).  A configuration
355 specifies an ordered list of these subdirectories.  Each subdirectory
356 implicitly appends its parent directory to the list.  For example,
357 specifying the list @file{unix/bsd/vax} is equivalent to specifying the
358 list @file{unix/bsd/vax unix/bsd unix}.  A subdirectory can also specify
359 that it implies other subdirectories which are not directly above it in
360 the directory hierarchy.  If the file @file{Implies} exists in a
361 subdirectory, it lists other subdirectories of @file{sysdeps} which are
362 appended to the list, appearing after the subdirectory containing the
363 @file{Implies} file.  Lines in an @file{Implies} file that begin with a
364 @samp{#} character are ignored as comments.  For example,
365 @file{unix/bsd/Implies} contains:@refill
366 @example
367 # BSD has Internet-related things.
368 unix/inet
369 @end example
370 @noindent
371 and @file{unix/Implies} contains:
372 @example
373 posix
374 @end example
375
376 @noindent
377 So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}.
378
379 @file{sysdeps} has two ``special'' subdirectories, called @file{generic}
380 and @file{stub}.  These two are always implicitly appended to the list
381 of subdirectories (in that order), so you needn't put them in an
382 @file{Implies} file, and you should not create any subdirectories under
383 them.  @file{generic} is for things that can be implemented in
384 machine-independent C, using only other machine-independent functions in
385 the C library.  @file{stub} is for @dfn{stub} versions of functions
386 which cannot be implemented on a particular machine or operating system.
387 The stub functions always return an error, and set @code{errno} to
388 @code{ENOSYS} (Function not implemented).  @xref{Error Reporting}.
389
390 A source file is known to be system-dependent by its having a version in
391 @file{generic} or @file{stub}; every system-dependent function should
392 have either a generic or stub implementation (there is no point in
393 having both).
394
395 If you come across a file that is in one of the main source directories
396 (@file{string}, @file{stdio}, etc.), and you want to write a machine- or
397 operating system-dependent version of it, move the file into
398 @file{sysdeps/generic} and write your new implementation in the
399 appropriate system-specific subdirectory.  Note that if a file is to be
400 system-dependent, it @strong{must not} appear in one of the main source
401 directories.@refill
402
403 There are a few special files that may exist in each subdirectory of
404 @file{sysdeps}:
405
406 @table @file
407 @item Makefile
408 A makefile for this machine or operating system, or class of machine or
409 operating system.  This file is included by the library makefile
410 @file{Makerules}, which is used by the top-level makefile and the
411 subdirectory makefiles.  It can change the variables set in the
412 including makefile or add new rules.  It can use GNU @code{make}
413 conditional directives based on the variable @samp{subdir} (see above) to
414 select different sets of variables and rules for different sections of
415 the library.  It can also set the @code{make} variable
416 @samp{sysdep-routines}, to specify extra modules to be included in the
417 library.  You should use @samp{sysdep-routines} rather than adding
418 modules to @samp{routines} because the latter is used in determining
419 what to distribute for each subdirectory of the main source tree.@refill
420
421 Each makefile in a subdirectory in the ordered list of subdirectories to
422 be searched is included in order.  Since several system-dependent
423 makefiles may be included, each should append to @samp{sysdep-routines}
424 rather than simply setting it:
425
426 @example
427 sysdep-routines := $(sysdep-routines) foo bar
428 @end example
429
430 @item Subdirs
431 This file contains the names of new whole subdirectories under the
432 top-level library source tree that should be included for this system.
433 These subdirectories are treated just like the system-independent
434 subdirectories in the library source tree, such as @file{stdio} and
435 @file{math}.
436
437 Use this when there are whole new sets of routines and header files that
438 should go into the library for the system this subdirectory of
439 @file{sysdeps} implements.  For example,
440 @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
441 directory contains various network-oriented operations which only make
442 sense to put in the library on systems that support the Internet.@refill
443
444 @item Dist
445 This file contains the names of files (relative to the subdirectory of
446 @file{sysdeps} in which it appears) which should be included in the
447 distribution.  List any new files used by rules in the @file{Makefile}
448 in the same directory, or header files used by the source files in that
449 directory.  You don't need to list files that are implementations
450 (either C or assembly source) of routines whose names are given in the
451 machine-independent makefiles in the main source tree.
452
453 @item configure
454 This file is a shell script fragment to be run at configuration time.
455 The top-level @file{configure} script uses the shell @code{.} command to
456 read the @file{configure} file in each system-dependent directory
457 chosen.  The @file{configure} files are usually generated from
458 @file{configure.in} files using Autoconf.  A system-dependent
459 @file{configure} script will usually add things to the shell variables
460 @samp{DEFS} and @samp{config_vars}; see the top-level @file{configure}
461 script for details.
462
463 @item configure.in
464 This file is an Autoconf input fragment to be processed into
465 @file{configure}.  You should write either @file{configure} or
466 @file{configure.in}, but not both.  The first line of @file{configure}
467 should invoke the @code{m4} macro @samp{GLIBC_PROVIDES}.  This macro
468 does several @code{AC_PROVIDE} calls for Autoconf macros which are used
469 by the top-level @file{configure} script; without this, those macros
470 might be invoked again unnecessarily by Autoconf.
471 @end table
472
473 That is the general system for how system-dependencies are isolated.
474 @iftex
475 The next section explains how to decide what directories in
476 @file{sysdeps} to use.  @ref{Porting to Unix}, has some tips on porting
477 the library to Unix variants.
478 @end iftex
479
480 @menu
481 * Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
482 * Porting to Unix::             Porting the library to an average
483                                    Unix-like system.
484 @end menu
485
486 @node Hierarchy Conventions
487 @appendixsubsec The Layout of the @file{sysdeps} Directory Hierarchy
488
489 A GNU configuration name has three parts: the CPU type, the
490 manufacturer's name, and the operating system.  @file{configure} uses
491 these to pick the list of system-dependent directories to look for.  If
492 the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
493 directory @file{@var{machine}/fpu} is also used.  The operating system
494 often has a @dfn{base operating system}; for example, if the operating
495 system is @samp{sunos4.1}, the base operating system is @samp{unix/bsd}.
496 The algorithm used to pick the list of directories is simple:
497 @file{configure} makes a list of the base operating system,
498 manufacturer, CPU type, and operating system, in that order.  It then
499 concatenates all these together with slashes in between, to produce a
500 directory name; for example, the configuration @w{@samp{sparc-sun-sunos4.1}}
501 results in @file{unix/bsd/sun/sparc/sunos4.1}.  @file{configure} then
502 tries removing each element of the list in turn, so
503 @file{unix/bsd/sparc} and @file{sun/sparc} are also tried, among others.
504 Since the precise version number of the operating system is often not
505 important, and it would be very inconvenient, for example, to have
506 identical @file{sunos4.1.1} and @file{sunos4.1.2} directories,
507 @file{configure} tries successively less specific operating system names
508 by removing trailing suffixes starting with a period.
509
510 As an example, here is the complete list of directories that would be
511 tried for the configuration @w{@samp{sparc-sun-sunos4.1}} (without the
512 @w{@samp{--nfp}} option):
513
514 @example
515 sparc/fpu
516 unix/bsd/sun/sunos4.1/sparc
517 unix/bsd/sun/sunos4.1
518 unix/bsd/sun/sunos4/sparc
519 unix/bsd/sun/sunos4
520 unix/bsd/sun/sunos/sparc
521 unix/bsd/sun/sunos
522 unix/bsd/sun/sparc
523 unix/bsd/sun
524 unix/bsd/sunos4.1/sparc
525 unix/bsd/sunos4.1
526 unix/bsd/sunos4/sparc
527 unix/bsd/sunos4
528 unix/bsd/sunos/sparc
529 unix/bsd/sunos
530 unix/bsd/sparc
531 unix/bsd
532 unix/sun/sunos4.1/sparc
533 unix/sun/sunos4.1
534 unix/sun/sunos4/sparc
535 unix/sun/sunos4
536 unix/sun/sunos/sparc
537 unix/sun/sunos
538 unix/sun/sparc
539 unix/sun
540 unix/sunos4.1/sparc
541 unix/sunos4.1
542 unix/sunos4/sparc
543 unix/sunos4
544 unix/sunos/sparc
545 unix/sunos
546 unix/sparc
547 unix
548 sun/sunos4.1/sparc
549 sun/sunos4.1
550 sun/sunos4/sparc
551 sun/sunos4
552 sun/sunos/sparc
553 sun/sunos
554 sun/sparc
555 sun
556 sunos4.1/sparc
557 sunos4.1
558 sunos4/sparc
559 sunos4
560 sunos/sparc
561 sunos
562 sparc
563 @end example
564
565 Different machine architectures are generally at the top level of the
566 @file{sysdeps} directory tree.  For example, @w{@file{sysdeps/sparc}}
567 and @w{@file{sysdeps/m68k}}.  These contain files specific to those
568 machine architectures, but not specific to any particular operating
569 system.  There might be subdirectories for specializations of those
570 architectures, such as @w{@file{sysdeps/m68k/68020}}. Code which is
571 specific to the floating-point coprocessor used with a particular
572 machine should go in @w{@file{sysdeps/@var{machine}/fpu}}.
573
574 There are a few directories at the top level of the @file{sysdeps}
575 hierarchy that are not for particular machine architectures.
576
577 @table @file
578 @item generic
579 @itemx stub
580 As described above (@pxref{Porting}), these are the two subdirectories
581 that every configuration implicitly uses after all others.
582
583 @item ieee754
584 This directory is for code using the IEEE 754 floating-point format,
585 where the C type @code{float} is IEEE 754 single-precision format, and
586 @code{double} is IEEE 754 double-precision format.  Usually this
587 directory is referred to in the @file{Implies} file in a machine
588 architecture-specific directory, such as @file{m68k/Implies}.
589
590 @item posix
591 This directory contains implementations of things in the library in
592 terms of @sc{POSIX.1} functions.  This includes some of the @sc{POSIX.1}
593 functions themselves.  Of course, @sc{POSIX.1} cannot be completely
594 implemented in terms of itself, so a configuration using just
595 @file{posix} cannot be complete.
596
597 @item unix
598 This is the directory for Unix-like things.  @xref{Porting to Unix}.
599 @file{unix} implies @file{posix}.  There are some special-purpose
600 subdirectories of @file{unix}:
601
602 @table @file
603 @item unix/common
604 This directory is for things common to both BSD and System V release 4.
605 Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
606
607 @item unix/inet
608 This directory is for @code{socket} and related functions on Unix systems.
609 The @file{inet} top-level subdirectory is enabled by @file{unix/inet/Subdirs}.
610 @file{unix/common} implies @file{unix/inet}.
611 @end table
612
613 @item mach
614 This is the directory for things based on the Mach microkernel from CMU
615 (including the GNU operating system).  Other basic operating systems
616 (VMS, for example) would have their own directories at the top level of
617 the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
618 @end table
619
620 @node Porting to Unix
621 @appendixsubsec Porting the GNU C Library to Unix Systems
622
623 Most Unix systems are fundamentally very similar.  There are variations
624 between different machines, and variations in what facilities are
625 provided by the kernel.  But the interface to the operating system
626 facilities is, for the most part, pretty uniform and simple.
627
628 The code for Unix systems is in the directory @file{unix}, at the top
629 level of the @file{sysdeps} hierarchy.  This directory contains
630 subdirectories (and subdirectory trees) for various Unix variants.
631
632 The functions which are system calls in most Unix systems are
633 implemented in assembly code in files in @file{sysdeps/unix}.  These
634 files are named with a suffix of @samp{.S}; for example,
635 @file{__open.S}.  Files ending in @samp{.S} are run through the C
636 preprocessor before being fed to the assembler.
637
638 These files all use a set of macros that should be defined in
639 @file{sysdep.h}.  The @file{sysdep.h} file in @file{sysdeps/unix}
640 partially defines them; a @file{sysdep.h} file in another directory must
641 finish defining them for the particular machine and operating system
642 variant.  See @file{sysdeps/unix/sysdep.h} and the machine-specific
643 @file{sysdep.h} implementations to see what these macros are and what
644 they should do.@refill
645
646 The system-specific makefile for the @file{unix} directory,
647 @file{sysdeps/unix/Makefile}, gives rules to generate several files from
648 the Unix system you are building the library on (which is assumed to be
649 the target system you are building the library @emph{for}).  All the
650 generated files are put in the directory where the object files are
651 kept; they should not affect the source tree itself.  The files
652 generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
653 @file{errlist.c} (for the @file{stdio} section of the library).
654
655 @ignore
656 @c This section might be a good idea if it is finished,
657 @c but there's no point including it as it stands. --rms
658 @c @appendixsec Compatibility with Traditional C
659
660 @c ??? This section is really short now.  Want to keep it? --roland
661
662 Although the GNU C library implements the ANSI C library facilities, you
663 @emph{can} use the GNU C library with traditional, ``pre-ANSI'' C
664 compilers.  However, you need to be careful because the content and
665 organization of the GNU C library header files differs from that of
666 traditional C implementations.  This means you may need to make changes
667 to your program in order to get it to compile.
668 @end ignore
669
670 @node Contributors
671 @appendixsec Contributors to the GNU C Library
672
673 The GNU C library was written almost entirely by Roland McGrath.
674 Some parts of the library were contributed by other people.
675
676 @itemize @bullet
677 @item
678 The @code{getopt} function and related code were written by
679 @w{Richard Stallman}, @w{David J. MacKenzie}, and @w{Roland McGrath}.
680
681 @item
682 Most of the math functions are taken from 4.4 BSD; they have been
683 modified only slightly to work with the GNU C library.  The
684 Internet-related code (most of the @file{inet} subdirectory) and several
685 other miscellaneous functions and header files have been included with
686 little or no modification.
687
688 All code incorporated from 4.4 BSD is under the following copyright:
689
690 @quotation
691 @display
692 Copyright @copyright{} 1991 Regents of the University of California.
693 All rights reserved.
694 @end display
695
696 Redistribution and use in source and binary forms, with or without
697 modification, are permitted provided that the following conditions
698 are met:
699
700 @enumerate
701 @item
702 Redistributions of source code must retain the above copyright
703 notice, this list of conditions and the following disclaimer.
704 @item
705 Redistributions in binary form must reproduce the above copyright
706 notice, this list of conditions and the following disclaimer in the
707 documentation and/or other materials provided with the distribution.
708 @item
709 All advertising materials mentioning features or use of this software
710 must display the following acknowledgement:
711 @quotation
712         This product includes software developed by the University of
713         California, Berkeley and its contributors.
714 @end quotation
715 @item
716 Neither the name of the University nor the names of its contributors
717 may be used to endorse or promote products derived from this software
718 without specific prior written permission.
719 @end enumerate
720
721 @sc{this software is provided by the regents and contributors ``as is'' and
722 any express or implied warranties, including, but not limited to, the
723 implied warranties of merchantability and fitness for a particular purpose
724 are disclaimed.  in no event shall the regents or contributors be liable
725 for any direct, indirect, incidental, special, exemplary, or consequential
726 damages (including, but not limited to, procurement of substitute goods
727 or services; loss of use, data, or profits; or business interruption)
728 however caused and on any theory of liability, whether in contract, strict
729 liability, or tort (including negligence or otherwise) arising in any way
730 out of the use of this software, even if advised of the possibility of
731 such damage.}
732 @end quotation
733
734 @item
735 The random number generation functions @code{random}, @code{srandom},
736 @code{setstate} and @code{initstate}, which are also the basis for the
737 @code{rand} and @code{srand} functions, were written by Earl T. Cohen
738 for the University of California at Berkeley and are copyrighted by the
739 Regents of the University of California.  They have undergone minor
740 changes to fit into the GNU C library and to fit the ANSI C standard,
741 but the functional code is Berkeley's.@refill
742
743 @item
744 The merge sort function @code{qsort} was written by Michael J. Haertel.
745
746 @item
747 The quick sort function used as a fallback by @code{qsort} was written
748 by Douglas C. Schmidt.
749
750 @item
751 The memory allocation functions @code{malloc}, @code{realloc} and
752 @code{free} and related code were written by Michael J. Haertel.
753
754 @item
755 Fast implementations of many of the string functions (@code{memcpy},
756 @code{strlen}, etc.) were written by
757 @tex
758 Torbj\"orn
759 @end tex
760 @ifinfo
761 Torbjorn
762 @end ifinfo
763 Granlund.@refill
764
765 @item
766 Some of the support code for Mach is taken from Mach 3.0 by CMU,
767 and is under the following copyright terms:
768
769 @quotation
770 @display
771 Mach Operating System
772 Copyright @copyright{} 1991,1990,1989 Carnegie Mellon University
773 All Rights Reserved.
774 @end display
775
776 Permission to use, copy, modify and distribute this software and its
777 documentation is hereby granted, provided that both the copyright
778 notice and this permission notice appear in all copies of the
779 software, derivative works or modified versions, and any portions
780 thereof, and that both notices appear in supporting documentation.
781
782 @sc{carnegie mellon allows free use of this software in its ``as is''
783 condition.  carnegie mellon disclaims any liability of any kind for
784 any damages whatsoever resulting from the use of this software.}
785
786 Carnegie Mellon requests users of this software to return to
787
788 @display
789  Software Distribution Coordinator
790  School of Computer Science
791  Carnegie Mellon University
792  Pittsburgh PA 15213-3890
793 @end display
794
795 @noindent
796 or @samp{Software.Distribution@@CS.CMU.EDU} any improvements or
797 extensions that they make and grant Carnegie Mellon the rights to
798 redistribute these changes.
799 @end quotation
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 code to support SunOS shared libraries was contributed by Tom Quinn.
818
819 @item
820 The @code{mktime} function was contributed by Noel Cragg.
821
822 @item
823 The port to the Sequent Symmetry running Dynix version 3
824 (@code{i386-sequent-bsd}) was contributed by Jason Merrill.
825
826 @item
827 The timezone support code is derived from the public-domain timezone
828 package by Arthur David Olsen.
829
830 @item
831 The Internet resolver code is taken directly from BIND 4.9.1, which is
832 under both the Berkeley copyright above and also:
833
834 @quotation
835 @display
836 Portions Copyright @copyright{} 1993 by Digital Equipment Corporation.
837 @end display
838
839 Permission to use, copy, modify, and distribute this software for any
840 purpose with or without fee is hereby granted, provided that the above
841 copyright notice and this permission notice appear in all copies, and
842 that the name of Digital Equipment Corporation not be used in
843 advertising or publicity pertaining to distribution of the document or
844 software without specific, written prior permission.
845
846 @sc{the software is provided ``as is'' and digital equipment corp.
847 disclaims all warranties with regard to this software, including all
848 implied warranties of merchantability and fitness.  in no event shall
849 digital equipment corporation be liable for any special, direct,
850 indirect, or consequential damages or any damages whatsoever resulting
851 from loss of use, data or profits, whether in an action of contract,
852 negligence or other tortious action, arising out of or in connection
853 with the use or performance of this software.}
854 @end quotation
855 @end itemize
856
857 @c @bye