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