(_hurd_sig_post): __sig_post renamed to __msg_sig_post.
[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 Most of the math functions are taken from 4.4 BSD; they have been
737 modified only slightly to work with the GNU C library.  The
738 Internet-related code (most of the @file{inet} subdirectory) and several
739 other miscellaneous functions and header files have been included with
740 little or no modification.
741
742 All code incorporated from 4.4 BSD is under the following copyright:
743
744 @quotation
745 @display
746 Copyright @copyright{} 1991 Regents of the University of California.
747 All rights reserved.
748 @end display
749
750 Redistribution and use in source and binary forms, with or without
751 modification, are permitted provided that the following conditions
752 are met:
753
754 @enumerate
755 @item
756 Redistributions of source code must retain the above copyright
757 notice, this list of conditions and the following disclaimer.
758 @item
759 Redistributions in binary form must reproduce the above copyright
760 notice, this list of conditions and the following disclaimer in the
761 documentation and/or other materials provided with the distribution.
762 @item
763 All advertising materials mentioning features or use of this software
764 must display the following acknowledgement:
765 @quotation
766 This product includes software developed by the University of
767 California, Berkeley and its contributors.
768 @end quotation
769 @item
770 Neither the name of the University nor the names of its contributors
771 may be used to endorse or promote products derived from this software
772 without specific prior written permission.
773 @end enumerate
774
775 @sc{this software is provided by the regents and contributors ``as is'' and
776 any express or implied warranties, including, but not limited to, the
777 implied warranties of merchantability and fitness for a particular purpose
778 are disclaimed.  in no event shall the regents or contributors be liable
779 for any direct, indirect, incidental, special, exemplary, or consequential
780 damages (including, but not limited to, procurement of substitute goods
781 or services; loss of use, data, or profits; or business interruption)
782 however caused and on any theory of liability, whether in contract, strict
783 liability, or tort (including negligence or otherwise) arising in any way
784 out of the use of this software, even if advised of the possibility of
785 such damage.}
786 @end quotation
787
788 @item
789 The random number generation functions @code{random}, @code{srandom},
790 @code{setstate} and @code{initstate}, which are also the basis for the
791 @code{rand} and @code{srand} functions, were written by Earl T. Cohen
792 for the University of California at Berkeley and are copyrighted by the
793 Regents of the University of California.  They have undergone minor
794 changes to fit into the GNU C library and to fit the ANSI C standard,
795 but the functional code is Berkeley's.@refill
796
797 @item
798 The merge sort function @code{qsort} was written by Michael J. Haertel.
799
800 @item
801 The quick sort function used as a fallback by @code{qsort} was written
802 by Douglas C. Schmidt.
803
804 @item
805 The memory allocation functions @code{malloc}, @code{realloc} and
806 @code{free} and related code were written by Michael J. Haertel.
807
808 @comment tege's name has an umlaut.
809 @tex
810 \xdef\SETtege{Torbj\"orn Granlund}
811 @end tex
812 @ifinfo
813 @set tege Torbjorn Granlund
814 @end ifinfo
815 @item
816 Fast implementations of many of the string functions (@code{memcpy},
817 @code{strlen}, etc.) were written by @value{tege}.
818
819 @item
820 Some of the support code for Mach is taken from Mach 3.0 by CMU,
821 and is under the following copyright terms:
822
823 @quotation
824 @display
825 Mach Operating System
826 Copyright @copyright{} 1991,1990,1989 Carnegie Mellon University
827 All Rights Reserved.
828 @end display
829
830 Permission to use, copy, modify and distribute this software and its
831 documentation is hereby granted, provided that both the copyright
832 notice and this permission notice appear in all copies of the
833 software, derivative works or modified versions, and any portions
834 thereof, and that both notices appear in supporting documentation.
835
836 @sc{carnegie mellon allows free use of this software in its ``as is''
837 condition.  carnegie mellon disclaims any liability of any kind for
838 any damages whatsoever resulting from the use of this software.}
839
840 Carnegie Mellon requests users of this software to return to
841
842 @display
843  Software Distribution Coordinator
844  School of Computer Science
845  Carnegie Mellon University
846  Pittsburgh PA 15213-3890
847 @end display
848
849 @noindent
850 or @samp{Software.Distribution@@CS.CMU.EDU} any improvements or
851 extensions that they make and grant Carnegie Mellon the rights to
852 redistribute these changes.
853 @end quotation
854
855 @item
856 The @file{tar.h} header file was written by David J. MacKenzie.
857
858 @item
859 The port to the MIPS DECStation running Ultrix 4
860 (@code{mips-dec-ultrix4})
861 was contributed by Brendan Kehoe and Ian Lance Taylor.
862
863 @item
864 The DES encryption function @code{crypt} and related functions were
865 contributed by Michael Glad.
866
867 @item
868 The @code{ftw} function was contributed by Ian Lance Taylor.
869
870 @item
871 The code to support SunOS shared libraries was contributed by Tom Quinn.
872
873 @item
874 The @code{mktime} function was contributed by Noel Cragg.
875
876 @item
877 The port to the Sequent Symmetry running Dynix version 3
878 (@code{i386-sequent-bsd}) was contributed by Jason Merrill.
879
880 @item
881 The timezone support code is derived from the public-domain timezone
882 package by Arthur David Olson.
883
884 @item
885 The Internet resolver code is taken directly from BIND 4.9.1, which is
886 under both the Berkeley copyright above and also:
887
888 @quotation
889 Portions Copyright @copyright{} 1993 by Digital Equipment Corporation.
890
891 Permission to use, copy, modify, and distribute this software for any
892 purpose with or without fee is hereby granted, provided that the above
893 copyright notice and this permission notice appear in all copies, and
894 that the name of Digital Equipment Corporation not be used in
895 advertising or publicity pertaining to distribution of the document or
896 software without specific, written prior permission.
897
898 @sc{the software is provided ``as is'' and digital equipment corp.
899 disclaims all warranties with regard to this software, including all
900 implied warranties of merchantability and fitness.  in no event shall
901 digital equipment corporation be liable for any special, direct,
902 indirect, or consequential damages or any damages whatsoever resulting
903 from loss of use, data or profits, whether in an action of contract,
904 negligence or other tortious action, arising out of or in connection
905 with the use or performance of this software.}
906 @end quotation
907
908 @item
909 The port to the DEC Alpha running OSF/1 (@code{alpha-dec-osf1}) was
910 contributed by Brendan Kehoe, using some code written by Roland McGrath.
911
912 @item
913 The floating-point printing function used by @code{printf} and friends
914 was written by Roland McGrath and @value{tege}.  The multi-precision
915 integer functions used in that function are taken from GNU MP, which was
916 contributed by @value{tege}.
917
918 @item
919 The code to support Sun RPC is taken verbatim from Sun's
920 @w{@sc{rpcsrc-4.0}} distribution, and is covered by this copyright:
921
922 @quotation
923 @display
924 Copyright @copyright{} 1984, Sun Microsystems, Inc.
925 @end display
926
927 Sun RPC is a product of Sun Microsystems, Inc. and is provided for
928 unrestricted use provided that this legend is included on all tape media
929 and as a part of the software program in whole or part.  Users may copy
930 or modify Sun RPC without charge, but are not authorized to license or
931 distribute it to anyone else except as part of a product or program
932 developed by the user.
933
934 @sc{sun rpc is provided as is with no warranties of any kind including the
935 warranties of design, merchantibility and fitness for a particular
936 purpose, or arising from a course of dealing, usage or trade practice.}
937
938 Sun RPC is provided with no support and without any obligation on the
939 part of Sun Microsystems, Inc. to assist in its use, correction,
940 modification or enhancement.
941
942 @sc{sun microsystems, inc. shall have no liability with respect to the
943 infringement of copyrights, trade secrets or any patents by sun rpc
944 or any part thereof.}
945
946 In no event will Sun Microsystems, Inc. be liable for any lost revenue
947 or profits or other special, indirect and consequential damages, even if
948 Sun has been advised of the possibility of such damages.
949
950 @display
951 Sun Microsystems, Inc.
952 2550 Garcia Avenue
953 Mountain View, California  94043
954 @end display
955 @end quotation
956
957 @item
958 The port to SGI machines running Irix 4 (@code{mips-sgi-irix4}) was
959 contributed by Tom Quinn.
960
961 @item
962 The port of the Mach and Hurd code to the MIPS architecture
963 (@code{mips-@var{anything}-gnu}) was contribued by Kazumoto Kojima.
964 @end itemize
965
966 @c @bye