(argz_delete): Fix prototype.
[kopensolaris-gnu/glibc.git] / manual / maint.texi
1 @node Maintenance, Contributors, Installation, Top
2 @c %MENU% How to enhance and port the GNU C Library
3 @appendix Library Maintenance
4
5 @menu
6 * Source Layout::         How to add new functions or header files
7                              to the GNU C library.
8 * Porting::               How to port the GNU C library to
9                              a new machine or operating system.
10 @end menu
11
12 @node Source Layout
13 @appendixsec Adding New Functions
14
15 The process of building the library is driven by the makefiles, which
16 make heavy use of special features of GNU @code{make}.  The makefiles
17 are very complex, and you probably don't want to try to understand them.
18 But what they do is fairly straightforward, and only requires that you
19 define a few variables in the right places.
20
21 The library sources are divided into subdirectories, grouped by topic.
22
23 The @file{string} subdirectory has all the string-manipulation
24 functions, @file{math} has all the mathematical functions, etc.
25
26 Each subdirectory contains a simple makefile, called @file{Makefile},
27 which defines a few @code{make} variables and then includes the global
28 makefile @file{Rules} with a line like:
29
30 @smallexample
31 include ../Rules
32 @end smallexample
33
34 @noindent
35 The basic variables that a subdirectory makefile defines are:
36
37 @table @code
38 @item subdir
39 The name of the subdirectory, for example @file{stdio}.
40 This variable @strong{must} be defined.
41
42 @item headers
43 The names of the header files in this section of the library,
44 such as @file{stdio.h}.
45
46 @item routines
47 @itemx aux
48 The names of the modules (source files) in this section of the library.
49 These should be simple names, such as @samp{strlen} (rather than
50 complete file names, such as @file{strlen.c}).  Use @code{routines} for
51 modules that define functions in the library, and @code{aux} for
52 auxiliary modules containing things like data definitions.  But the
53 values of @code{routines} and @code{aux} are just concatenated, so there
54 really is no practical difference.@refill
55
56 @item tests
57 The names of test programs for this section of the library.  These
58 should be simple names, such as @samp{tester} (rather than complete file
59 names, such as @file{tester.c}).  @w{@samp{make tests}} will build and
60 run all the test programs.  If a test program needs input, put the test
61 data in a file called @file{@var{test-program}.input}; it will be given to
62 the test program on its standard input.  If a test program wants to be
63 run with arguments, put the arguments (all on a single line) in a file
64 called @file{@var{test-program}.args}.  Test programs should exit with
65 zero status when the test passes, and nonzero status when the test
66 indicates a bug in the library or error in building.
67
68 @item others
69 The names of ``other'' programs associated with this section of the
70 library.  These are programs which are not tests per se, but are other
71 small programs included with the library.  They are built by
72 @w{@samp{make others}}.@refill
73
74 @item install-lib
75 @itemx install-data
76 @itemx install
77 Files to be installed by @w{@samp{make install}}.  Files listed in
78 @samp{install-lib} are installed in the directory specified by
79 @samp{libdir} in @file{configparms} or @file{Makeconfig}
80 (@pxref{Installation}).  Files listed in @code{install-data} are
81 installed in the directory specified by @samp{datadir} in
82 @file{configparms} or @file{Makeconfig}.  Files listed in @code{install}
83 are installed in the directory specified by @samp{bindir} in
84 @file{configparms} or @file{Makeconfig}.@refill
85
86 @item distribute
87 Other files from this subdirectory which should be put into a
88 distribution tar file.  You need not list here the makefile itself or
89 the source and header files listed in the other standard variables.
90 Only define @code{distribute} if there are files used in an unusual way
91 that should go into the distribution.
92
93 @item generated
94 Files which are generated by @file{Makefile} in this subdirectory.
95 These files will be removed by @w{@samp{make clean}}, and they will
96 never go into a distribution.
97
98 @item extra-objs
99 Extra object files which are built by @file{Makefile} in this
100 subdirectory.  This should be a list of file names like @file{foo.o};
101 the files will actually be found in whatever directory object files are
102 being built in.  These files will be removed by @w{@samp{make clean}}.
103 This variable is used for secondary object files needed to build
104 @code{others} or @code{tests}.
105 @end table
106
107 @node Porting
108 @appendixsec Porting the GNU C Library
109
110 The GNU C library is written to be easily portable to a variety of
111 machines and operating systems.  Machine- and operating system-dependent
112 functions are well separated to make it easy to add implementations for
113 new machines or operating systems.  This section describes the layout of
114 the library source tree and explains the mechanisms used to select
115 machine-dependent code to use.
116
117 All the machine-dependent and operating system-dependent files in the
118 library are in the subdirectory @file{sysdeps} under the top-level
119 library source directory.  This directory contains a hierarchy of
120 subdirectories (@pxref{Hierarchy Conventions}).
121
122 Each subdirectory of @file{sysdeps} contains source files for a
123 particular machine or operating system, or for a class of machine or
124 operating system (for example, systems by a particular vendor, or all
125 machines that use IEEE 754 floating-point format).  A configuration
126 specifies an ordered list of these subdirectories.  Each subdirectory
127 implicitly appends its parent directory to the list.  For example,
128 specifying the list @file{unix/bsd/vax} is equivalent to specifying the
129 list @file{unix/bsd/vax unix/bsd unix}.  A subdirectory can also specify
130 that it implies other subdirectories which are not directly above it in
131 the directory hierarchy.  If the file @file{Implies} exists in a
132 subdirectory, it lists other subdirectories of @file{sysdeps} which are
133 appended to the list, appearing after the subdirectory containing the
134 @file{Implies} file.  Lines in an @file{Implies} file that begin with a
135 @samp{#} character are ignored as comments.  For example,
136 @file{unix/bsd/Implies} contains:@refill
137 @smallexample
138 # BSD has Internet-related things.
139 unix/inet
140 @end smallexample
141 @noindent
142 and @file{unix/Implies} contains:
143 @need 300
144 @smallexample
145 posix
146 @end smallexample
147
148 @noindent
149 So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}.
150
151 @file{sysdeps} has a ``special'' subdirectory called @file{generic}.  It
152 is always implicitly appended to the list of subdirectories, so you
153 needn't put it in an @file{Implies} file, and you should not create any
154 subdirectories under it intended to be new specific categories.
155 @file{generic} serves two purposes.  First, the makefiles do not bother
156 to look for a system-dependent version of a file that's not in
157 @file{generic}.  This means that any system-dependent source file must
158 have an analogue in @file{generic}, even if the routines defined by that
159 file are not implemented on other platforms.  Second. the @file{generic}
160 version of a system-dependent file is used if the makefiles do not find
161 a version specific to the system you're compiling for.
162
163 If it is possible to implement the routines in a @file{generic} file in
164 machine-independent C, using only other machine-independent functions in
165 the C library, then you should do so.  Otherwise, make them stubs.  A
166 @dfn{stub} function is a function which cannot be implemented on a
167 particular machine or operating system.  Stub functions always return an
168 error, and set @code{errno} to @code{ENOSYS} (Function not implemented).
169 @xref{Error Reporting}.  If you define a stub function, you must place
170 the statement @code{stub_warning(@var{function})}, where @var{function}
171 is the name of your function, after its definition; also, you must
172 include the file @code{<stub-tag.h>} into your file.  This causes the
173 function to be listed in the installed @code{<gnu/stubs.h>}, and
174 makes GNU ld warn when the function is used.
175
176 Some rare functions are only useful on specific systems and aren't
177 defined at all on others; these do not appear anywhere in the
178 system-independent source code or makefiles (including the
179 @file{generic} directory), only in the system-dependent @file{Makefile}
180 in the specific system's subdirectory.
181
182 If you come across a file that is in one of the main source directories
183 (@file{string}, @file{stdio}, etc.), and you want to write a machine- or
184 operating system-dependent version of it, move the file into
185 @file{sysdeps/generic} and write your new implementation in the
186 appropriate system-specific subdirectory.  Note that if a file is to be
187 system-dependent, it @strong{must not} appear in one of the main source
188 directories.@refill
189
190 There are a few special files that may exist in each subdirectory of
191 @file{sysdeps}:
192
193 @comment Blank lines after items make the table look better.
194 @table @file
195 @item Makefile
196
197 A makefile for this machine or operating system, or class of machine or
198 operating system.  This file is included by the library makefile
199 @file{Makerules}, which is used by the top-level makefile and the
200 subdirectory makefiles.  It can change the variables set in the
201 including makefile or add new rules.  It can use GNU @code{make}
202 conditional directives based on the variable @samp{subdir} (see above) to
203 select different sets of variables and rules for different sections of
204 the library.  It can also set the @code{make} variable
205 @samp{sysdep-routines}, to specify extra modules to be included in the
206 library.  You should use @samp{sysdep-routines} rather than adding
207 modules to @samp{routines} because the latter is used in determining
208 what to distribute for each subdirectory of the main source tree.@refill
209
210 Each makefile in a subdirectory in the ordered list of subdirectories to
211 be searched is included in order.  Since several system-dependent
212 makefiles may be included, each should append to @samp{sysdep-routines}
213 rather than simply setting it:
214
215 @smallexample
216 sysdep-routines := $(sysdep-routines) foo bar
217 @end smallexample
218
219 @need 1000
220 @item Subdirs
221
222 This file contains the names of new whole subdirectories under the
223 top-level library source tree that should be included for this system.
224 These subdirectories are treated just like the system-independent
225 subdirectories in the library source tree, such as @file{stdio} and
226 @file{math}.
227
228 Use this when there are completely new sets of functions and header
229 files that should go into the library for the system this subdirectory
230 of @file{sysdeps} implements.  For example,
231 @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet}
232 directory contains various network-oriented operations which only make
233 sense to put in the library on systems that support the Internet.@refill
234
235 @item configure
236
237 This file is a shell script fragment to be run at configuration time.
238 The top-level @file{configure} script uses the shell @code{.} command to
239 read the @file{configure} file in each system-dependent directory
240 chosen, in order.  The @file{configure} files are often generated from
241 @file{configure.in} files using Autoconf.
242
243 A system-dependent @file{configure} script will usually add things to
244 the shell variables @samp{DEFS} and @samp{config_vars}; see the
245 top-level @file{configure} script for details.  The script can check for
246 @w{@samp{--with-@var{package}}} options that were passed to the
247 top-level @file{configure}.  For an option
248 @w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the
249 shell variable @w{@samp{with_@var{package}}} (with any dashes in
250 @var{package} converted to underscores) to @var{value}; if the option is
251 just @w{@samp{--with-@var{package}}} (no argument), then it sets
252 @w{@samp{with_@var{package}}} to @samp{yes}.
253
254 @item configure.in
255
256 This file is an Autoconf input fragment to be processed into the file
257 @file{configure} in this subdirectory.  @xref{Introduction,,,
258 autoconf.info, Autoconf: Generating Automatic Configuration Scripts},
259 for a description of Autoconf.  You should write either @file{configure}
260 or @file{configure.in}, but not both.  The first line of
261 @file{configure.in} should invoke the @code{m4} macro
262 @samp{GLIBC_PROVIDES}.  This macro does several @code{AC_PROVIDE} calls
263 for Autoconf macros which are used by the top-level @file{configure}
264 script; without this, those macros might be invoked again unnecessarily
265 by Autoconf.
266 @end table
267
268 That is the general system for how system-dependencies are isolated.
269 @iftex
270 The next section explains how to decide what directories in
271 @file{sysdeps} to use.  @ref{Porting to Unix}, has some tips on porting
272 the library to Unix variants.
273 @end iftex
274
275 @menu
276 * Hierarchy Conventions::       The layout of the @file{sysdeps} hierarchy.
277 * Porting to Unix::             Porting the library to an average
278                                    Unix-like system.
279 @end menu
280
281 @node Hierarchy Conventions
282 @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy
283
284 A GNU configuration name has three parts: the CPU type, the
285 manufacturer's name, and the operating system.  @file{configure} uses
286 these to pick the list of system-dependent directories to look for.  If
287 the @samp{--nfp} option is @emph{not} passed to @file{configure}, the
288 directory @file{@var{machine}/fpu} is also used.  The operating system
289 often has a @dfn{base operating system}; for example, if the operating
290 system is @samp{Linux}, the base operating system is @samp{unix/sysv}.
291 The algorithm used to pick the list of directories is simple:
292 @file{configure} makes a list of the base operating system,
293 manufacturer, CPU type, and operating system, in that order.  It then
294 concatenates all these together with slashes in between, to produce a
295 directory name; for example, the configuration @w{@samp{i686-linux-gnu}}
296 results in @file{unix/sysv/linux/i386/i686}.  @file{configure} then
297 tries removing each element of the list in turn, so
298 @file{unix/sysv/linux} and @file{unix/sysv} are also tried, among others.
299 Since the precise version number of the operating system is often not
300 important, and it would be very inconvenient, for example, to have
301 identical @file{irix6.2} and @file{irix6.3} directories,
302 @file{configure} tries successively less specific operating system names
303 by removing trailing suffixes starting with a period.
304
305 As an example, here is the complete list of directories that would be
306 tried for the configuration @w{@samp{i686-linux-gnu}} (with the
307 @file{crypt} and @file{linuxthreads} add-on):
308
309 @smallexample
310 sysdeps/i386/elf
311 crypt/sysdeps/unix
312 linuxthreads/sysdeps/unix/sysv/linux
313 linuxthreads/sysdeps/pthread
314 linuxthreads/sysdeps/unix/sysv
315 linuxthreads/sysdeps/unix
316 linuxthreads/sysdeps/i386/i686
317 linuxthreads/sysdeps/i386
318 linuxthreads/sysdeps/pthread/no-cmpxchg
319 sysdeps/unix/sysv/linux/i386
320 sysdeps/unix/sysv/linux
321 sysdeps/gnu
322 sysdeps/unix/common
323 sysdeps/unix/mman
324 sysdeps/unix/inet
325 sysdeps/unix/sysv/i386/i686
326 sysdeps/unix/sysv/i386
327 sysdeps/unix/sysv
328 sysdeps/unix/i386
329 sysdeps/unix
330 sysdeps/posix
331 sysdeps/i386/i686
332 sysdeps/i386/i486
333 sysdeps/libm-i387/i686
334 sysdeps/i386/fpu
335 sysdeps/libm-i387
336 sysdeps/i386
337 sysdeps/wordsize-32
338 sysdeps/ieee754
339 sysdeps/libm-ieee754
340 sysdeps/generic
341 @end smallexample
342
343 Different machine architectures are conventionally subdirectories at the
344 top level of the @file{sysdeps} directory tree.  For example,
345 @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}.  These contain
346 files specific to those machine architectures, but not specific to any
347 particular operating system.  There might be subdirectories for
348 specializations of those architectures, such as
349 @w{@file{sysdeps/m68k/68020}}. Code which is specific to the
350 floating-point coprocessor used with a particular machine should go in
351 @w{@file{sysdeps/@var{machine}/fpu}}.
352
353 There are a few directories at the top level of the @file{sysdeps}
354 hierarchy that are not for particular machine architectures.
355
356 @table @file
357 @item generic
358 As described above (@pxref{Porting}), this is the subdirectory
359 that every configuration implicitly uses after all others.
360
361 @item ieee754
362 This directory is for code using the IEEE 754 floating-point format,
363 where the C type @code{float} is IEEE 754 single-precision format, and
364 @code{double} is IEEE 754 double-precision format.  Usually this
365 directory is referred to in the @file{Implies} file in a machine
366 architecture-specific directory, such as @file{m68k/Implies}.
367
368 @item libm-ieee754
369 This directory contains an implementation of a mathematical library
370 usable on platforms which use @w{IEEE 754} conformant floating-point
371 arithmetic.
372
373 @item libm-i387
374 This is a special case.  Ideally the code should be in
375 @file{sysdeps/i386/fpu} but for various reasons it is kept aside.
376
377 @item posix
378 This directory contains implementations of things in the library in
379 terms of @sc{POSIX.1} functions.  This includes some of the @sc{POSIX.1}
380 functions themselves.  Of course, @sc{POSIX.1} cannot be completely
381 implemented in terms of itself, so a configuration using just
382 @file{posix} cannot be complete.
383
384 @item unix
385 This is the directory for Unix-like things.  @xref{Porting to Unix}.
386 @file{unix} implies @file{posix}.  There are some special-purpose
387 subdirectories of @file{unix}:
388
389 @table @file
390 @item unix/common
391 This directory is for things common to both BSD and System V release 4.
392 Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}.
393
394 @item unix/inet
395 This directory is for @code{socket} and related functions on Unix systems.
396 @file{unix/inet/Subdirs} enables the @file{inet} top-level subdirectory.
397 @file{unix/common} implies @file{unix/inet}.
398 @end table
399
400 @item mach
401 This is the directory for things based on the Mach microkernel from CMU
402 (including the GNU operating system).  Other basic operating systems
403 (VMS, for example) would have their own directories at the top level of
404 the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}.
405 @end table
406
407 @node Porting to Unix
408 @appendixsubsec Porting the GNU C Library to Unix Systems
409
410 Most Unix systems are fundamentally very similar.  There are variations
411 between different machines, and variations in what facilities are
412 provided by the kernel.  But the interface to the operating system
413 facilities is, for the most part, pretty uniform and simple.
414
415 The code for Unix systems is in the directory @file{unix}, at the top
416 level of the @file{sysdeps} hierarchy.  This directory contains
417 subdirectories (and subdirectory trees) for various Unix variants.
418
419 The functions which are system calls in most Unix systems are
420 implemented in assembly code, which is generated automatically from
421 specifications in files named @file{syscalls.list}.  There are several
422 such files, one in @file{sysdeps/unix} and others in its subdirectories.
423 Some special system calls are implemented in files that are named with a
424 suffix of @samp{.S}; for example, @file{_exit.S}.  Files ending in
425 @samp{.S} are run through the C preprocessor before being fed to the
426 assembler.
427
428 These files all use a set of macros that should be defined in
429 @file{sysdep.h}.  The @file{sysdep.h} file in @file{sysdeps/unix}
430 partially defines them; a @file{sysdep.h} file in another directory must
431 finish defining them for the particular machine and operating system
432 variant.  See @file{sysdeps/unix/sysdep.h} and the machine-specific
433 @file{sysdep.h} implementations to see what these macros are and what
434 they should do.@refill
435
436 The system-specific makefile for the @file{unix} directory
437 (@file{sysdeps/unix/Makefile}) gives rules to generate several files
438 from the Unix system you are building the library on (which is assumed
439 to be the target system you are building the library @emph{for}).  All
440 the generated files are put in the directory where the object files are
441 kept; they should not affect the source tree itself.  The files
442 generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and
443 @file{errlist.c} (for the @file{stdio} section of the library).
444
445 @ignore
446 @c This section might be a good idea if it is finished,
447 @c but there's no point including it as it stands. --rms
448 @c @appendixsec Compatibility with Traditional C
449
450 @c ??? This section is really short now.  Want to keep it? --roland
451
452 @c It's not anymore true.  glibc 2.1 cannot be used with K&R compilers.
453 @c --drepper
454
455 Although the GNU C library implements the @w{ISO C} library facilities, you
456 @emph{can} use the GNU C library with traditional, ``pre-ISO'' C
457 compilers.  However, you need to be careful because the content and
458 organization of the GNU C library header files differs from that of
459 traditional C implementations.  This means you may need to make changes
460 to your program in order to get it to compile.
461 @end ignore