bd8f7ed314dc69e0a55d7370d763be9bbf72a4e9
[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 @table @file                    @c Blank lines after items make it look better.
412 @item Makefile
413
414 A makefile for this machine or operating system, or class of machine or
415 operating system.  This file is included by the library makefile
416 @file{Makerules}, which is used by the top-level makefile and the
417 subdirectory makefiles.  It can change the variables set in the
418 including makefile or add new rules.  It can use GNU @code{make}
419 conditional directives based on the variable @samp{subdir} (see above) to
420 select different sets of variables and rules for different sections of
421 the library.  It can also set the @code{make} variable
422 @samp{sysdep-routines}, to specify extra modules to be included in the
423 library.  You should use @samp{sysdep-routines} rather than adding
424 modules to @samp{routines} because the latter is used in determining
425 what to distribute for each subdirectory of the main source tree.@refill
426
427 Each makefile in a subdirectory in the ordered list of subdirectories to
428 be searched is included in order.  Since several system-dependent
429 makefiles may be included, each should append to @samp{sysdep-routines}
430 rather than simply setting it:
431
432 @smallexample
433 sysdep-routines := $(sysdep-routines) foo bar
434 @end smallexample
435
436 @need 1000
437 @item Subdirs
438
439 This file contains the names of new whole subdirectories under the
440 top-level library source tree that should be included for this system.
441 These subdirectories are treated just like the system-independent
442 subdirectories in the library source tree, such as @file{stdio} and
443 @file{math}.
444
445 Use this when there are completely new sets of functions and header
446 files that should go into the library for the system this subdirectory
447 of @file{sysdeps} implements.  For example,
448 @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
449 directory contains various network-oriented operations which only make
450 sense to put in the library on systems that support the Internet.@refill
451
452 @item Dist
453
454 This file contains the names of files (relative to the subdirectory of
455 @file{sysdeps} in which it appears) which should be included in the
456 distribution.  List any new files used by rules in the @file{Makefile}
457 in the same directory, or header files used by the source files in that
458 directory.  You don't need to list files that are implementations
459 (either C or assembly source) of routines whose names are given in the
460 machine-independent makefiles in the main source tree.
461
462 @item configure
463
464 This file is a shell script fragment to be run at configuration time.
465 The top-level @file{configure} script uses the shell @code{.} command to
466 read the @file{configure} file in each system-dependent directory
467 chosen.  The @file{configure} files are usually generated from
468 @file{configure.in} files using Autoconf.  A system-dependent
469 @file{configure} script will usually add things to the shell variables
470 @samp{DEFS} and @samp{config_vars}; see the top-level @file{configure}
471 script for details.
472
473 @item configure.in
474
475 This file is an Autoconf input fragment to be processed into the file
476 @file{configure} in this subdirectory.  @xref{Introduction,,,
477 autoconf.info, Autoconf: Generating Automatic Configuration Scripts},
478 for a description of Autoconf.  You should write either @file{configure}
479 or @file{configure.in}, but not both.  The first line of
480 @file{configure} should invoke the @code{m4} macro
481 @samp{GLIBC_PROVIDES}.  This macro does several @code{AC_PROVIDE} calls
482 for Autoconf macros which are used by the top-level @file{configure}
483 script; without this, those macros might be invoked again unnecessarily
484 by Autoconf.
485 @end table
486
487 That is the general system for how system-dependencies are isolated.
488 @iftex
489 The next section explains how to decide what directories in
490 @file{sysdeps} to use.  @ref{Porting to Unix}, has some tips on porting
491 the library to Unix variants.
492 @end iftex
493
494 @menu
495 * Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
496 * Porting to Unix::             Porting the library to an average
497                                    Unix-like system.
498 @end menu
499
500 @node Hierarchy Conventions
501 @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy
502
503 A GNU configuration name has three parts: the CPU type, the
504 manufacturer's name, and the operating system.  @file{configure} uses
505 these to pick the list of system-dependent directories to look for.  If
506 the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
507 directory @file{@var{machine}/fpu} is also used.  The operating system
508 often has a @dfn{base operating system}; for example, if the operating
509 system is @samp{sunos4.1}, the base operating system is @samp{unix/bsd}.
510 The algorithm used to pick the list of directories is simple:
511 @file{configure} makes a list of the base operating system,
512 manufacturer, CPU type, and operating system, in that order.  It then
513 concatenates all these together with slashes in between, to produce a
514 directory name; for example, the configuration @w{@samp{sparc-sun-sunos4.1}}
515 results in @file{unix/bsd/sun/sparc/sunos4.1}.  @file{configure} then
516 tries removing each element of the list in turn, so
517 @file{unix/bsd/sparc} and @file{sun/sparc} are also tried, among others.
518 Since the precise version number of the operating system is often not
519 important, and it would be very inconvenient, for example, to have
520 identical @file{sunos4.1.1} and @file{sunos4.1.2} directories,
521 @file{configure} tries successively less specific operating system names
522 by removing trailing suffixes starting with a period.
523
524 As an example, here is the complete list of directories that would be
525 tried for the configuration @w{@samp{sparc-sun-sunos4.1}} (without the
526 @w{@samp{--nfp}} option):
527
528 @smallexample
529 sparc/fpu
530 unix/bsd/sun/sunos4.1/sparc
531 unix/bsd/sun/sunos4.1
532 unix/bsd/sun/sunos4/sparc
533 unix/bsd/sun/sunos4
534 unix/bsd/sun/sunos/sparc
535 unix/bsd/sun/sunos
536 unix/bsd/sun/sparc
537 unix/bsd/sun
538 unix/bsd/sunos4.1/sparc
539 unix/bsd/sunos4.1
540 unix/bsd/sunos4/sparc
541 unix/bsd/sunos4
542 unix/bsd/sunos/sparc
543 unix/bsd/sunos
544 unix/bsd/sparc
545 unix/bsd
546 unix/sun/sunos4.1/sparc
547 unix/sun/sunos4.1
548 unix/sun/sunos4/sparc
549 unix/sun/sunos4
550 unix/sun/sunos/sparc
551 unix/sun/sunos
552 unix/sun/sparc
553 unix/sun
554 unix/sunos4.1/sparc
555 unix/sunos4.1
556 unix/sunos4/sparc
557 unix/sunos4
558 unix/sunos/sparc
559 unix/sunos
560 unix/sparc
561 unix
562 sun/sunos4.1/sparc
563 sun/sunos4.1
564 sun/sunos4/sparc
565 sun/sunos4
566 sun/sunos/sparc
567 sun/sunos
568 sun/sparc
569 sun
570 sunos4.1/sparc
571 sunos4.1
572 sunos4/sparc
573 sunos4
574 sunos/sparc
575 sunos
576 sparc
577 @end smallexample
578
579 Different machine architectures are conventionally subdirectories at the
580 top level of the @file{sysdeps} directory tree.  For example,
581 @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}.  These contain
582 files specific to those machine architectures, but not specific to any
583 particular operating system.  There might be subdirectories for
584 specializations of those architectures, such as
585 @w{@file{sysdeps/m68k/68020}}. Code which is specific to the
586 floating-point coprocessor used with a particular machine should go in
587 @w{@file{sysdeps/@var{machine}/fpu}}.
588
589 There are a few directories at the top level of the @file{sysdeps}
590 hierarchy that are not for particular machine architectures.
591
592 @table @file
593 @item generic
594 @itemx stub
595 As described above (@pxref{Porting}), these are the two subdirectories
596 that every configuration implicitly uses after all others.
597
598 @item ieee754
599 This directory is for code using the IEEE 754 floating-point format,
600 where the C type @code{float} is IEEE 754 single-precision format, and
601 @code{double} is IEEE 754 double-precision format.  Usually this
602 directory is referred to in the @file{Implies} file in a machine
603 architecture-specific directory, such as @file{m68k/Implies}.
604
605 @item posix
606 This directory contains implementations of things in the library in
607 terms of @sc{POSIX.1} functions.  This includes some of the @sc{POSIX.1}
608 functions themselves.  Of course, @sc{POSIX.1} cannot be completely
609 implemented in terms of itself, so a configuration using just
610 @file{posix} cannot be complete.
611
612 @item unix
613 This is the directory for Unix-like things.  @xref{Porting to Unix}.
614 @file{unix} implies @file{posix}.  There are some special-purpose
615 subdirectories of @file{unix}:
616
617 @table @file
618 @item unix/common
619 This directory is for things common to both BSD and System V release 4.
620 Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
621
622 @item unix/inet
623 This directory is for @code{socket} and related functions on Unix systems.
624 The @file{inet} top-level subdirectory is enabled by @file{unix/inet/Subdirs}.
625 @file{unix/common} implies @file{unix/inet}.
626 @end table
627
628 @item mach
629 This is the directory for things based on the Mach microkernel from CMU
630 (including the GNU operating system).  Other basic operating systems
631 (VMS, for example) would have their own directories at the top level of
632 the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
633 @end table
634
635 @node Porting to Unix
636 @appendixsubsec Porting the GNU C Library to Unix Systems
637
638 Most Unix systems are fundamentally very similar.  There are variations
639 between different machines, and variations in what facilities are
640 provided by the kernel.  But the interface to the operating system
641 facilities is, for the most part, pretty uniform and simple.
642
643 The code for Unix systems is in the directory @file{unix}, at the top
644 level of the @file{sysdeps} hierarchy.  This directory contains
645 subdirectories (and subdirectory trees) for various Unix variants.
646
647 The functions which are system calls in most Unix systems are
648 implemented in assembly code in files in @file{sysdeps/unix}.  These
649 files are named with a suffix of @samp{.S}; for example,
650 @file{__open.S}.  Files ending in @samp{.S} are run through the C
651 preprocessor before being fed to the assembler.
652
653 These files all use a set of macros that should be defined in
654 @file{sysdep.h}.  The @file{sysdep.h} file in @file{sysdeps/unix}
655 partially defines them; a @file{sysdep.h} file in another directory must
656 finish defining them for the particular machine and operating system
657 variant.  See @file{sysdeps/unix/sysdep.h} and the machine-specific
658 @file{sysdep.h} implementations to see what these macros are and what
659 they should do.@refill
660
661 The system-specific makefile for the @file{unix} directory (that is, the
662 file @file{sysdeps/unix/Makefile}) gives rules to generate several files
663 from the Unix system you are building the library on (which is assumed
664 to be the target system you are building the library @emph{for}).  All
665 the generated files are put in the directory where the object files are
666 kept; they should not affect the source tree itself.  The files
667 generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
668 @file{errlist.c} (for the @file{stdio} section of the library).
669
670 @ignore
671 @c This section might be a good idea if it is finished,
672 @c but there's no point including it as it stands. --rms
673 @c @appendixsec Compatibility with Traditional C
674
675 @c ??? This section is really short now.  Want to keep it? --roland
676
677 Although the GNU C library implements the ANSI C library facilities, you
678 @emph{can} use the GNU C library with traditional, ``pre-ANSI'' C
679 compilers.  However, you need to be careful because the content and
680 organization of the GNU C library header files differs from that of
681 traditional C implementations.  This means you may need to make changes
682 to your program in order to get it to compile.
683 @end ignore
684
685 @node Contributors
686 @appendixsec Contributors to the GNU C Library
687
688 The GNU C library was written almost entirely by Roland McGrath, who now
689 maintains it.  Some parts of the library were contributed or worked on
690 by other people.
691
692 @itemize @bullet
693 @item
694 The @code{getopt} function and related code were written by
695 Richard Stallman, @w{David J. MacKenzie}, and @w{Roland McGrath}.
696
697 @item
698 Most of the math functions are taken from 4.4 BSD; they have been
699 modified only slightly to work with the GNU C library.  The
700 Internet-related code (most of the @file{inet} subdirectory) and several
701 other miscellaneous functions and header files have been included with
702 little or no modification.
703
704 All code incorporated from 4.4 BSD is under the following copyright:
705
706 @quotation
707 @display
708 Copyright @copyright{} 1991 Regents of the University of California.
709 All rights reserved.
710 @end display
711
712 Redistribution and use in source and binary forms, with or without
713 modification, are permitted provided that the following conditions
714 are met:
715
716 @enumerate
717 @item
718 Redistributions of source code must retain the above copyright
719 notice, this list of conditions and the following disclaimer.
720 @item
721 Redistributions in binary form must reproduce the above copyright
722 notice, this list of conditions and the following disclaimer in the
723 documentation and/or other materials provided with the distribution.
724 @item
725 All advertising materials mentioning features or use of this software
726 must display the following acknowledgement:
727 @quotation
728         This product includes software developed by the University of
729         California, Berkeley and its contributors.
730 @end quotation
731 @item
732 Neither the name of the University nor the names of its contributors
733 may be used to endorse or promote products derived from this software
734 without specific prior written permission.
735 @end enumerate
736
737 @sc{this software is provided by the regents and contributors ``as is'' and
738 any express or implied warranties, including, but not limited to, the
739 implied warranties of merchantability and fitness for a particular purpose
740 are disclaimed.  in no event shall the regents or contributors be liable
741 for any direct, indirect, incidental, special, exemplary, or consequential
742 damages (including, but not limited to, procurement of substitute goods
743 or services; loss of use, data, or profits; or business interruption)
744 however caused and on any theory of liability, whether in contract, strict
745 liability, or tort (including negligence or otherwise) arising in any way
746 out of the use of this software, even if advised of the possibility of
747 such damage.}
748 @end quotation
749
750 @item
751 The random number generation functions @code{random}, @code{srandom},
752 @code{setstate} and @code{initstate}, which are also the basis for the
753 @code{rand} and @code{srand} functions, were written by Earl T. Cohen
754 for the University of California at Berkeley and are copyrighted by the
755 Regents of the University of California.  They have undergone minor
756 changes to fit into the GNU C library and to fit the ANSI C standard,
757 but the functional code is Berkeley's.@refill
758
759 @item
760 The merge sort function @code{qsort} was written by Michael J. Haertel.
761
762 @item
763 The quick sort function used as a fallback by @code{qsort} was written
764 by Douglas C. Schmidt.
765
766 @item
767 The memory allocation functions @code{malloc}, @code{realloc} and
768 @code{free} and related code were written by Michael J. Haertel.
769
770 @item
771 Fast implementations of many of the string functions (@code{memcpy},
772 @code{strlen}, etc.) were written by
773 @tex
774 Torbj\"orn
775 @end tex
776 @ifinfo
777 Torbjorn
778 @end ifinfo
779 Granlund.@refill
780
781 @item
782 Some of the support code for Mach is taken from Mach 3.0 by CMU,
783 and is under the following copyright terms:
784
785 @quotation
786 @display
787 Mach Operating System
788 Copyright @copyright{} 1991,1990,1989 Carnegie Mellon University
789 All Rights Reserved.
790 @end display
791
792 Permission to use, copy, modify and distribute this software and its
793 documentation is hereby granted, provided that both the copyright
794 notice and this permission notice appear in all copies of the
795 software, derivative works or modified versions, and any portions
796 thereof, and that both notices appear in supporting documentation.
797
798 @sc{carnegie mellon allows free use of this software in its ``as is''
799 condition.  carnegie mellon disclaims any liability of any kind for
800 any damages whatsoever resulting from the use of this software.}
801
802 Carnegie Mellon requests users of this software to return to
803
804 @display
805  Software Distribution Coordinator
806  School of Computer Science
807  Carnegie Mellon University
808  Pittsburgh PA 15213-3890
809 @end display
810
811 @noindent
812 or @samp{Software.Distribution@@CS.CMU.EDU} any improvements or
813 extensions that they make and grant Carnegie Mellon the rights to
814 redistribute these changes.
815 @end quotation
816
817 @item
818 The @file{tar.h} header file was written by David J. MacKenzie.
819
820 @item
821 The port to the MIPS DECStation running Ultrix 4
822 (@code{mips-dec-ultrix4})
823 was contributed by Brendan Kehoe and Ian Lance Taylor.
824
825 @item
826 The DES encryption function @code{crypt} and related functions were
827 contributed by Michael Glad.
828
829 @item
830 The @code{ftw} function was contributed by Ian Lance Taylor.
831
832 @item
833 The code to support SunOS shared libraries was contributed by Tom Quinn.
834
835 @item
836 The @code{mktime} function was contributed by Noel Cragg.
837
838 @item
839 The port to the Sequent Symmetry running Dynix version 3
840 (@code{i386-sequent-bsd}) was contributed by Jason Merrill.
841
842 @item
843 The timezone support code is derived from the public-domain timezone
844 package by Arthur David Olsen.
845
846 @item
847 The Internet resolver code is taken directly from BIND 4.9.1, which is
848 under both the Berkeley copyright above and also:
849
850 @quotation
851 Portions Copyright @copyright{} 1993 by Digital Equipment Corporation.
852
853 Permission to use, copy, modify, and distribute this software for any
854 purpose with or without fee is hereby granted, provided that the above
855 copyright notice and this permission notice appear in all copies, and
856 that the name of Digital Equipment Corporation not be used in
857 advertising or publicity pertaining to distribution of the document or
858 software without specific, written prior permission.
859
860 @sc{the software is provided ``as is'' and digital equipment corp.
861 disclaims all warranties with regard to this software, including all
862 implied warranties of merchantability and fitness.  in no event shall
863 digital equipment corporation be liable for any special, direct,
864 indirect, or consequential damages or any damages whatsoever resulting
865 from loss of use, data or profits, whether in an action of contract,
866 negligence or other tortious action, arising out of or in connection
867 with the use or performance of this software.}
868 @end quotation
869 @end itemize
870
871 @c @bye