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