]>
Commit | Line | Data |
---|---|---|
d9dc34cd | 1 | @node Maintenance, Platform, Installation, Top |
7a68c94a | 2 | @c %MENU% How to enhance and port the GNU C Library |
28f540f4 RM |
3 | @appendix Library Maintenance |
4 | ||
5 | @menu | |
28f540f4 | 6 | * Source Layout:: How to add new functions or header files |
1f77f049 | 7 | to the GNU C Library. |
3d3a2911 | 8 | * Source Fortification:: Fortification of function calls. |
6e15f3e2 | 9 | * Symbol handling:: How to handle symbols in the GNU C Library. |
1f77f049 | 10 | * Porting:: How to port the GNU C Library to |
28f540f4 | 11 | a new machine or operating system. |
7da3079b | 12 | @end menu |
28f540f4 | 13 | |
28f540f4 RM |
14 | @node Source Layout |
15 | @appendixsec Adding New Functions | |
16 | ||
17 | The process of building the library is driven by the makefiles, which | |
18 | make heavy use of special features of GNU @code{make}. The makefiles | |
19 | are very complex, and you probably don't want to try to understand them. | |
20 | But what they do is fairly straightforward, and only requires that you | |
21 | define a few variables in the right places. | |
22 | ||
23 | The library sources are divided into subdirectories, grouped by topic. | |
41f27456 | 24 | |
28f540f4 | 25 | The @file{string} subdirectory has all the string-manipulation |
41f27456 | 26 | functions, @file{math} has all the mathematical functions, etc. |
28f540f4 RM |
27 | |
28 | Each subdirectory contains a simple makefile, called @file{Makefile}, | |
29 | which defines a few @code{make} variables and then includes the global | |
30 | makefile @file{Rules} with a line like: | |
31 | ||
32 | @smallexample | |
33 | include ../Rules | |
34 | @end smallexample | |
35 | ||
36 | @noindent | |
37 | The basic variables that a subdirectory makefile defines are: | |
38 | ||
39 | @table @code | |
40 | @item subdir | |
41 | The name of the subdirectory, for example @file{stdio}. | |
42 | This variable @strong{must} be defined. | |
43 | ||
44 | @item headers | |
45 | The names of the header files in this section of the library, | |
46 | such as @file{stdio.h}. | |
47 | ||
48 | @item routines | |
49 | @itemx aux | |
50 | The names of the modules (source files) in this section of the library. | |
51 | These should be simple names, such as @samp{strlen} (rather than | |
52 | complete file names, such as @file{strlen.c}). Use @code{routines} for | |
53 | modules that define functions in the library, and @code{aux} for | |
54 | auxiliary modules containing things like data definitions. But the | |
55 | values of @code{routines} and @code{aux} are just concatenated, so there | |
0005e54f | 56 | really is no practical difference. |
28f540f4 RM |
57 | |
58 | @item tests | |
59 | The names of test programs for this section of the library. These | |
60 | should be simple names, such as @samp{tester} (rather than complete file | |
61 | names, such as @file{tester.c}). @w{@samp{make tests}} will build and | |
62 | run all the test programs. If a test program needs input, put the test | |
63 | data in a file called @file{@var{test-program}.input}; it will be given to | |
64 | the test program on its standard input. If a test program wants to be | |
65 | run with arguments, put the arguments (all on a single line) in a file | |
41f27456 RM |
66 | called @file{@var{test-program}.args}. Test programs should exit with |
67 | zero status when the test passes, and nonzero status when the test | |
68 | indicates a bug in the library or error in building. | |
28f540f4 RM |
69 | |
70 | @item others | |
71 | The names of ``other'' programs associated with this section of the | |
72 | library. These are programs which are not tests per se, but are other | |
73 | small programs included with the library. They are built by | |
0005e54f | 74 | @w{@samp{make others}}. |
28f540f4 RM |
75 | |
76 | @item install-lib | |
77 | @itemx install-data | |
78 | @itemx install | |
79 | Files to be installed by @w{@samp{make install}}. Files listed in | |
80 | @samp{install-lib} are installed in the directory specified by | |
81 | @samp{libdir} in @file{configparms} or @file{Makeconfig} | |
82 | (@pxref{Installation}). Files listed in @code{install-data} are | |
83 | installed in the directory specified by @samp{datadir} in | |
84 | @file{configparms} or @file{Makeconfig}. Files listed in @code{install} | |
85 | are installed in the directory specified by @samp{bindir} in | |
0005e54f | 86 | @file{configparms} or @file{Makeconfig}. |
28f540f4 RM |
87 | |
88 | @item distribute | |
89 | Other files from this subdirectory which should be put into a | |
90 | distribution tar file. You need not list here the makefile itself or | |
91 | the source and header files listed in the other standard variables. | |
92 | Only define @code{distribute} if there are files used in an unusual way | |
93 | that should go into the distribution. | |
94 | ||
95 | @item generated | |
96 | Files which are generated by @file{Makefile} in this subdirectory. | |
97 | These files will be removed by @w{@samp{make clean}}, and they will | |
98 | never go into a distribution. | |
99 | ||
100 | @item extra-objs | |
101 | Extra object files which are built by @file{Makefile} in this | |
102 | subdirectory. This should be a list of file names like @file{foo.o}; | |
103 | the files will actually be found in whatever directory object files are | |
104 | being built in. These files will be removed by @w{@samp{make clean}}. | |
105 | This variable is used for secondary object files needed to build | |
106 | @code{others} or @code{tests}. | |
107 | @end table | |
108 | ||
d9dc34cd TMQMF |
109 | @menu |
110 | * Platform: Adding Platform-specific. Adding platform-specific | |
111 | features. | |
112 | @end menu | |
113 | ||
114 | @node Adding Platform-specific | |
115 | @appendixsubsec Platform-specific types, macros and functions | |
116 | ||
117 | It's sometimes necessary to provide nonstandard, platform-specific | |
118 | features to developers. The C library is traditionally the | |
119 | lowest library layer, so it makes sense for it to provide these | |
120 | low-level features. However, including these features in the C | |
121 | library may be a disadvantage if another package provides them | |
122 | as well as there will be two conflicting versions of them. Also, | |
123 | the features won't be available to projects that do not use | |
124 | @theglibc{} but use other GNU tools, like GCC. | |
125 | ||
126 | The current guidelines are: | |
127 | @itemize @bullet | |
128 | @item | |
129 | If the header file provides features that only make sense on a particular | |
130 | machine architecture and have nothing to do with an operating system, then | |
131 | the features should ultimately be provided as GCC built-in functions. Until | |
132 | then, @theglibc{} may provide them in the header file. When the GCC built-in | |
133 | functions become available, those provided in the header file should be made | |
134 | conditionally available prior to the GCC version in which the built-in | |
135 | function was made available. | |
136 | ||
137 | @item | |
138 | If the header file provides features that are specific to an operating system, | |
139 | both GCC and @theglibc{} could provide it, but @theglibc{} is preferred | |
140 | as it already has a lot of information about the operating system. | |
141 | ||
142 | @item | |
143 | If the header file provides features that are specific to an operating system | |
144 | but used by @theglibc{}, then @theglibc{} should provide them. | |
145 | @end itemize | |
146 | ||
147 | The general solution for providing low-level features is to export them as | |
148 | follows: | |
149 | ||
150 | @itemize @bullet | |
151 | @item | |
152 | A nonstandard, low-level header file that defines macros and inline | |
153 | functions should be called @file{sys/platform/@var{name}.h}. | |
154 | ||
155 | @item | |
156 | Each header file's name should include the platform name, to avoid | |
6d2857d3 | 157 | users thinking there is anything in common between the different |
d9dc34cd TMQMF |
158 | header files for different platforms. For example, a |
159 | @file{sys/platform/@var{arch}.h} name such as | |
160 | @file{sys/platform/ppc.h} is better than @file{sys/platform.h}. | |
161 | ||
162 | @item | |
163 | A platform-specific header file provided by @theglibc{} should coordinate | |
164 | with GCC such that compiler built-in versions of the functions and macros are | |
165 | preferred if available. This means that user programs will only ever need to | |
166 | include @file{sys/platform/@var{arch}.h}, keeping the same names of types, | |
167 | macros, and functions for convenience and portability. | |
168 | ||
169 | @item | |
170 | Each included symbol must have the prefix @code{__@var{arch}_}, such as | |
171 | @code{__ppc_get_timebase}. | |
172 | @end itemize | |
173 | ||
174 | ||
175 | The easiest way to provide a header file is to add it to the | |
176 | @code{sysdep_headers} variable. For example, the combination of | |
177 | Linux-specific header files on PowerPC could be provided like this: | |
178 | ||
179 | @smallexample | |
180 | sysdep_headers += sys/platform/ppc.h | |
181 | @end smallexample | |
182 | ||
183 | Then ensure that you have added a @file{sys/platform/ppc.h} | |
184 | header file in the machine-specific directory, e.g., | |
185 | @file{sysdeps/powerpc/sys/platform/ppc.h}. | |
186 | ||
187 | ||
3d3a2911 SP |
188 | @node Source Fortification |
189 | @appendixsec Fortification of function calls | |
190 | ||
191 | This section contains implementation details of @theglibc{} and may not | |
192 | remain stable across releases. | |
193 | ||
194 | The @code{_FORTIFY_SOURCE} macro may be defined by users to control | |
195 | hardening of calls into some functions in @theglibc{}. The definition | |
196 | should be at the top of the source file before any headers are included | |
197 | or at the pre-processor commandline using the @code{-D} switch. The | |
198 | hardening primarily focuses on accesses to buffers passed to the | |
199 | functions but may also include checks for validity of other inputs to | |
200 | the functions. | |
201 | ||
202 | When the @code{_FORTIFY_SOURCE} macro is defined, it enables code that | |
203 | validates inputs passed to some functions in @theglibc to determine if | |
204 | they are safe. If the compiler is unable to determine that the inputs | |
205 | to the function call are safe, the call may be replaced by a call to its | |
206 | hardened variant that does additional safety checks at runtime. Some | |
207 | hardened variants need the size of the buffer to perform access | |
208 | validation and this is provided by the @code{__builtin_object_size} or | |
209 | the @code{__builtin_dynamic_object_size} builtin functions. | |
ac2a1434 SP |
210 | @code{_FORTIFY_SOURCE} also enables additional compile time diagnostics, |
211 | such as unchecked return values from some functions, to encourage | |
212 | developers to add error checking for those functions. | |
3d3a2911 SP |
213 | |
214 | At runtime, if any of those safety checks fail, the program will | |
215 | terminate with a @code{SIGABRT} signal. @code{_FORTIFY_SOURCE} may be | |
216 | defined to one of the following values: | |
217 | ||
218 | @itemize @bullet | |
219 | @item @math{1}: This enables buffer bounds checking using the value | |
220 | returned by the @code{__builtin_object_size} compiler builtin function. | |
221 | If the function returns @code{(size_t) -1}, the function call is left | |
222 | untouched. Additionally, this level also enables validation of flags to | |
223 | the @code{open}, @code{open64}, @code{openat} and @code{openat64} | |
224 | functions. | |
225 | ||
226 | @item @math{2}: This behaves like @math{1}, with the addition of some | |
227 | checks that may trap code that is conforming but unsafe, e.g. accepting | |
228 | @code{%n} only in read-only format strings. | |
229 | ||
230 | @item @math{3}: This enables buffer bounds checking using the value | |
231 | returned by the @code{__builtin_dynamic_object_size} compiler builtin | |
232 | function. If the function returns @code{(size_t) -1}, the function call | |
233 | is left untouched. Fortification at this level may have a impact on | |
234 | program performance if the function call that is fortified is frequently | |
235 | encountered and the size expression returned by | |
236 | @code{__builtin_dynamic_object_size} is complex. | |
237 | @end itemize | |
238 | ||
239 | In general, the fortified variants of the function calls use the name of | |
240 | the function with a @code{__} prefix and a @code{_chk} suffix. There | |
241 | are some exceptions, e.g. the @code{printf} family of functions where, | |
242 | depending on the architecture, one may also see fortified variants have | |
243 | the @code{_chkieee128} suffix or the @code{__nldbl___} prefix to their | |
244 | names. | |
245 | ||
246 | Another exception is the @code{open} family of functions, where their | |
247 | fortified replacements have the @code{__} prefix and a @code{_2} suffix. | |
248 | The @code{FD_SET}, @code{FD_CLR} and @code{FD_ISSET} macros use the | |
249 | @code{__fdelt_chk} function on fortification. | |
250 | ||
251 | The following functions and macros are fortified in @theglibc{}: | |
252 | @c Generated using the following command: | |
253 | @c find . -name Versions | xargs grep -e "_chk;" -e "_2;" | | |
254 | @c cut -d ':' -f 2 | sed 's/;/\n/g' | sed 's/ *//g' | grep -v "^$" | | |
255 | @c sort -u | grep ^__ | | |
256 | @c grep -v -e ieee128 -e __nldbl -e align_cpy -e "fdelt_warn" | | |
257 | @c sed 's/__fdelt_chk/@item @code{FD_SET}\n\n@item @code{FD_CLR}\n\n@item @code{FD_ISSET}\n/' | | |
258 | @c sed 's/__\(.*\)_\(chk\|2\)/@item @code{\1}\n/' | |
259 | ||
260 | @itemize @bullet | |
261 | ||
262 | @item @code{asprintf} | |
263 | ||
264 | @item @code{confstr} | |
265 | ||
266 | @item @code{dprintf} | |
267 | ||
268 | @item @code{explicit_bzero} | |
269 | ||
270 | @item @code{FD_SET} | |
271 | ||
272 | @item @code{FD_CLR} | |
273 | ||
274 | @item @code{FD_ISSET} | |
275 | ||
276 | @item @code{fgets} | |
277 | ||
278 | @item @code{fgets_unlocked} | |
279 | ||
280 | @item @code{fgetws} | |
281 | ||
282 | @item @code{fgetws_unlocked} | |
283 | ||
284 | @item @code{fprintf} | |
285 | ||
286 | @item @code{fread} | |
287 | ||
288 | @item @code{fread_unlocked} | |
289 | ||
290 | @item @code{fwprintf} | |
291 | ||
292 | @item @code{getcwd} | |
293 | ||
294 | @item @code{getdomainname} | |
295 | ||
296 | @item @code{getgroups} | |
297 | ||
298 | @item @code{gethostname} | |
299 | ||
300 | @item @code{getlogin_r} | |
301 | ||
302 | @item @code{gets} | |
303 | ||
304 | @item @code{getwd} | |
305 | ||
306 | @item @code{longjmp} | |
307 | ||
308 | @item @code{mbsnrtowcs} | |
309 | ||
310 | @item @code{mbsrtowcs} | |
311 | ||
312 | @item @code{mbstowcs} | |
313 | ||
314 | @item @code{memcpy} | |
315 | ||
316 | @item @code{memmove} | |
317 | ||
318 | @item @code{mempcpy} | |
319 | ||
320 | @item @code{memset} | |
321 | ||
322 | @item @code{mq_open} | |
323 | ||
324 | @item @code{obstack_printf} | |
325 | ||
326 | @item @code{obstack_vprintf} | |
327 | ||
328 | @item @code{open} | |
329 | ||
330 | @item @code{open64} | |
331 | ||
332 | @item @code{openat} | |
333 | ||
334 | @item @code{openat64} | |
335 | ||
336 | @item @code{poll} | |
337 | ||
338 | @item @code{ppoll64} | |
339 | ||
340 | @item @code{ppoll} | |
341 | ||
342 | @item @code{pread64} | |
343 | ||
344 | @item @code{pread} | |
345 | ||
346 | @item @code{printf} | |
347 | ||
348 | @item @code{ptsname_r} | |
349 | ||
350 | @item @code{read} | |
351 | ||
352 | @item @code{readlinkat} | |
353 | ||
354 | @item @code{readlink} | |
355 | ||
356 | @item @code{realpath} | |
357 | ||
358 | @item @code{recv} | |
359 | ||
360 | @item @code{recvfrom} | |
361 | ||
362 | @item @code{snprintf} | |
363 | ||
364 | @item @code{sprintf} | |
365 | ||
366 | @item @code{stpcpy} | |
367 | ||
368 | @item @code{stpncpy} | |
369 | ||
370 | @item @code{strcat} | |
371 | ||
372 | @item @code{strcpy} | |
373 | ||
d2fda60e PE |
374 | @item @code{strlcat} |
375 | ||
376 | @item @code{strlcpy} | |
377 | ||
3d3a2911 SP |
378 | @item @code{strncat} |
379 | ||
380 | @item @code{strncpy} | |
381 | ||
382 | @item @code{swprintf} | |
383 | ||
384 | @item @code{syslog} | |
385 | ||
386 | @item @code{ttyname_r} | |
387 | ||
388 | @item @code{vasprintf} | |
389 | ||
390 | @item @code{vdprintf} | |
391 | ||
392 | @item @code{vfprintf} | |
393 | ||
394 | @item @code{vfwprintf} | |
395 | ||
396 | @item @code{vprintf} | |
397 | ||
398 | @item @code{vsnprintf} | |
399 | ||
400 | @item @code{vsprintf} | |
401 | ||
402 | @item @code{vswprintf} | |
403 | ||
404 | @item @code{vsyslog} | |
405 | ||
406 | @item @code{vwprintf} | |
407 | ||
408 | @item @code{wcpcpy} | |
409 | ||
410 | @item @code{wcpncpy} | |
411 | ||
412 | @item @code{wcrtomb} | |
413 | ||
414 | @item @code{wcscat} | |
415 | ||
416 | @item @code{wcscpy} | |
417 | ||
d2fda60e PE |
418 | @item @code{wcslcat} |
419 | ||
420 | @item @code{wcslcpy} | |
421 | ||
3d3a2911 SP |
422 | @item @code{wcsncat} |
423 | ||
424 | @item @code{wcsncpy} | |
425 | ||
426 | @item @code{wcsnrtombs} | |
427 | ||
428 | @item @code{wcsrtombs} | |
429 | ||
430 | @item @code{wcstombs} | |
431 | ||
432 | @item @code{wctomb} | |
433 | ||
434 | @item @code{wmemcpy} | |
435 | ||
436 | @item @code{wmemmove} | |
437 | ||
438 | @item @code{wmempcpy} | |
439 | ||
440 | @item @code{wmemset} | |
441 | ||
442 | @item @code{wprintf} | |
443 | ||
444 | @end itemize | |
445 | ||
446 | ||
6e15f3e2 AA |
447 | @node Symbol handling |
448 | @appendixsec Symbol handling in the GNU C Library | |
449 | ||
450 | @menu | |
451 | * 64-bit time symbol handling :: How to handle 64-bit time related | |
452 | symbols in the GNU C Library. | |
453 | @end menu | |
454 | ||
455 | @node 64-bit time symbol handling | |
456 | @appendixsubsec 64-bit time symbol handling in the GNU C Library | |
457 | ||
bfb79db4 | 458 | With respect to time handling, @glibcadj{} configurations fall in two |
6e15f3e2 AA |
459 | classes depending on the value of @code{__TIMESIZE}: |
460 | ||
461 | @table @code | |
462 | ||
463 | @item @code{__TIMESIZE == 32} | |
464 | ||
465 | These @dfn{dual-time} configurations have both 32-bit and 64-bit time | |
466 | support. 32-bit time support provides type @code{time_t} and cannot | |
467 | handle dates beyond @dfn{Y2038}. 64-bit time support provides type | |
468 | @code{__time64_t} and can handle dates beyond @dfn{Y2038}. | |
469 | ||
470 | In these configurations, time-related types have two declarations, | |
471 | a 64-bit one, and a 32-bit one; and time-related functions generally | |
472 | have two definitions: a 64-bit one, and a 32-bit one which is a wrapper | |
473 | around the former. Therefore, for every @code{time_t}-related symbol, | |
474 | there is a corresponding @code{__time64_t}-related symbol, the name of | |
475 | which is usually the 32-bit symbol's name with @code{__} (a double | |
476 | underscore) prepended and @code{64} appended. For instance, the | |
477 | 64-bit-time counterpart of @code{clock_gettime} is | |
478 | @code{__clock_gettime64}. | |
479 | ||
480 | @item @code{__TIMESIZE == 64} | |
481 | ||
482 | These @dfn{single-time} configurations only have a 64-bit @code{time_t} | |
483 | and related functions, which can handle dates beyond 2038-01-19 | |
484 | 03:14:07 (aka @dfn{Y2038}). | |
485 | ||
486 | In these configurations, time-related types only have a 64-bit | |
487 | declaration; and time-related functions only have one 64-bit definition. | |
488 | However, for every @code{time_t}-related symbol, there is a | |
489 | corresponding @code{__time64_t}-related macro, the name of which is | |
490 | derived as in the dual-time configuration case, and which expands to | |
491 | the symbol's name. For instance, the macro @code{__clock_gettime64} | |
492 | expands to @code{clock_gettime}. | |
493 | ||
a4ed0471 AZ |
494 | When @code{__TIMESIZE} is set to 64, @theglibc{} will also define |
495 | the@code{__USE_TIME_BITS64} macro. It is used by the Linux kernel ABI | |
496 | to set the expected @code{time_t} size used on some syscalls. | |
497 | ||
6e15f3e2 AA |
498 | These macros are purely internal to @theglibc{} and exist only so that |
499 | a single definition of the 64-bit time functions can be used on both | |
500 | single-time and dual-time configurations, and so that glibc code can | |
501 | freely call the 64-bit functions internally in all configurations. | |
502 | ||
503 | @end table | |
504 | ||
505 | @c The following paragraph should be removed once external interfaces | |
506 | @c get support for both time sizes. | |
507 | ||
508 | Note: at this point, 64-bit time support in dual-time configurations is | |
509 | work-in-progress, so for these configurations, the public API only makes | |
510 | the 32-bit time support available. In a later change, the public API | |
511 | will allow user code to choose the time size for a given compilation | |
512 | unit. | |
513 | ||
514 | 64-bit variants of time-related types or functions are defined for all | |
515 | configurations and use 64-bit-time symbol names (for dual-time | |
516 | configurations) or macros (for single-time configurations). | |
517 | ||
518 | 32-bit variants of time-related types or functions are defined only for | |
519 | dual-time configurations. | |
520 | ||
521 | Here is an example with @code{localtime}: | |
522 | ||
523 | Function @code{localtime} is declared in @file{time/time.h} as | |
524 | @smallexample | |
525 | extern struct tm *localtime (const time_t *__timer) __THROW; | |
526 | libc_hidden_proto (localtime) | |
527 | @end smallexample | |
528 | ||
529 | For single-time configurations, @code{__localtime64} is a macro which | |
530 | evaluates to @code{localtime}; for dual-time configurations, | |
531 | @code{__localtime64} is a function similar to @code{localtime} except | |
532 | it uses Y2038-proof types: | |
533 | @smallexample | |
534 | #if __TIMESIZE == 64 | |
535 | # define __localtime64 localtime | |
536 | #else | |
537 | extern struct tm *__localtime64 (const __time64_t *__timer) __THROW; | |
538 | libc_hidden_proto (__localtime64) | |
539 | #endif | |
540 | @end smallexample | |
541 | ||
542 | (note: type @code{time_t} is replaced with @code{__time64_t} because | |
543 | @code{time_t} is not Y2038-proof, but @code{struct tm} is not | |
544 | replaced because it is already Y2038-proof.) | |
545 | ||
546 | The 64-bit-time implementation of @code{localtime} is written as follows | |
547 | and is compiled for both dual-time and single-time configuration classes. | |
548 | ||
549 | @smallexample | |
550 | struct tm * | |
551 | __localtime64 (const __time64_t *t) | |
8b18d418 | 552 | @{ |
6e15f3e2 | 553 | return __tz_convert (*t, 1, &_tmbuf); |
8b18d418 | 554 | @} |
6e15f3e2 AA |
555 | libc_hidden_def (__localtime64) |
556 | @end smallexample | |
557 | ||
558 | The 32-bit-time implementation is a wrapper and is only compiled for | |
559 | dual-time configurations: | |
560 | ||
561 | @smallexample | |
562 | #if __TIMESIZE != 64 | |
563 | ||
564 | struct tm * | |
565 | localtime (const time_t *t) | |
8b18d418 | 566 | @{ |
6e15f3e2 AA |
567 | __time64_t t64 = *t; |
568 | return __localtime64 (&t64); | |
8b18d418 | 569 | @} |
6e15f3e2 AA |
570 | libc_hidden_def (localtime) |
571 | ||
572 | #endif | |
573 | @end smallexample | |
574 | ||
28f540f4 | 575 | @node Porting |
1f77f049 | 576 | @appendixsec Porting @theglibc{} |
28f540f4 | 577 | |
1f77f049 | 578 | @Theglibc{} is written to be easily portable to a variety of |
28f540f4 RM |
579 | machines and operating systems. Machine- and operating system-dependent |
580 | functions are well separated to make it easy to add implementations for | |
581 | new machines or operating systems. This section describes the layout of | |
582 | the library source tree and explains the mechanisms used to select | |
583 | machine-dependent code to use. | |
584 | ||
585 | All the machine-dependent and operating system-dependent files in the | |
586 | library are in the subdirectory @file{sysdeps} under the top-level | |
587 | library source directory. This directory contains a hierarchy of | |
588 | subdirectories (@pxref{Hierarchy Conventions}). | |
589 | ||
590 | Each subdirectory of @file{sysdeps} contains source files for a | |
591 | particular machine or operating system, or for a class of machine or | |
592 | operating system (for example, systems by a particular vendor, or all | |
593 | machines that use IEEE 754 floating-point format). A configuration | |
594 | specifies an ordered list of these subdirectories. Each subdirectory | |
595 | implicitly appends its parent directory to the list. For example, | |
596 | specifying the list @file{unix/bsd/vax} is equivalent to specifying the | |
597 | list @file{unix/bsd/vax unix/bsd unix}. A subdirectory can also specify | |
598 | that it implies other subdirectories which are not directly above it in | |
599 | the directory hierarchy. If the file @file{Implies} exists in a | |
600 | subdirectory, it lists other subdirectories of @file{sysdeps} which are | |
601 | appended to the list, appearing after the subdirectory containing the | |
602 | @file{Implies} file. Lines in an @file{Implies} file that begin with a | |
603 | @samp{#} character are ignored as comments. For example, | |
0005e54f | 604 | @file{unix/bsd/Implies} contains: |
28f540f4 RM |
605 | @smallexample |
606 | # BSD has Internet-related things. | |
607 | unix/inet | |
608 | @end smallexample | |
609 | @noindent | |
610 | and @file{unix/Implies} contains: | |
611 | @need 300 | |
612 | @smallexample | |
613 | posix | |
614 | @end smallexample | |
615 | ||
616 | @noindent | |
617 | So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}. | |
618 | ||
f2ea0f5b UD |
619 | @file{sysdeps} has a ``special'' subdirectory called @file{generic}. It |
620 | is always implicitly appended to the list of subdirectories, so you | |
621 | needn't put it in an @file{Implies} file, and you should not create any | |
622 | subdirectories under it intended to be new specific categories. | |
623 | @file{generic} serves two purposes. First, the makefiles do not bother | |
624 | to look for a system-dependent version of a file that's not in | |
625 | @file{generic}. This means that any system-dependent source file must | |
626 | have an analogue in @file{generic}, even if the routines defined by that | |
11bf311e | 627 | file are not implemented on other platforms. Second, the @file{generic} |
f2ea0f5b UD |
628 | version of a system-dependent file is used if the makefiles do not find |
629 | a version specific to the system you're compiling for. | |
630 | ||
631 | If it is possible to implement the routines in a @file{generic} file in | |
632 | machine-independent C, using only other machine-independent functions in | |
633 | the C library, then you should do so. Otherwise, make them stubs. A | |
634 | @dfn{stub} function is a function which cannot be implemented on a | |
635 | particular machine or operating system. Stub functions always return an | |
636 | error, and set @code{errno} to @code{ENOSYS} (Function not implemented). | |
637 | @xref{Error Reporting}. If you define a stub function, you must place | |
638 | the statement @code{stub_warning(@var{function})}, where @var{function} | |
b830319d | 639 | is the name of your function, after its definition. This causes the |
f2ea0f5b UD |
640 | function to be listed in the installed @code{<gnu/stubs.h>}, and |
641 | makes GNU ld warn when the function is used. | |
642 | ||
cc3fa755 UD |
643 | Some rare functions are only useful on specific systems and aren't |
644 | defined at all on others; these do not appear anywhere in the | |
645 | system-independent source code or makefiles (including the | |
646 | @file{generic} directory), only in the system-dependent @file{Makefile} | |
647 | in the specific system's subdirectory. | |
28f540f4 RM |
648 | |
649 | If you come across a file that is in one of the main source directories | |
650 | (@file{string}, @file{stdio}, etc.), and you want to write a machine- or | |
651 | operating system-dependent version of it, move the file into | |
652 | @file{sysdeps/generic} and write your new implementation in the | |
653 | appropriate system-specific subdirectory. Note that if a file is to be | |
654 | system-dependent, it @strong{must not} appear in one of the main source | |
0005e54f | 655 | directories. |
28f540f4 RM |
656 | |
657 | There are a few special files that may exist in each subdirectory of | |
658 | @file{sysdeps}: | |
659 | ||
660 | @comment Blank lines after items make the table look better. | |
661 | @table @file | |
662 | @item Makefile | |
663 | ||
664 | A makefile for this machine or operating system, or class of machine or | |
665 | operating system. This file is included by the library makefile | |
666 | @file{Makerules}, which is used by the top-level makefile and the | |
667 | subdirectory makefiles. It can change the variables set in the | |
668 | including makefile or add new rules. It can use GNU @code{make} | |
669 | conditional directives based on the variable @samp{subdir} (see above) to | |
670 | select different sets of variables and rules for different sections of | |
671 | the library. It can also set the @code{make} variable | |
672 | @samp{sysdep-routines}, to specify extra modules to be included in the | |
673 | library. You should use @samp{sysdep-routines} rather than adding | |
674 | modules to @samp{routines} because the latter is used in determining | |
0005e54f | 675 | what to distribute for each subdirectory of the main source tree. |
28f540f4 RM |
676 | |
677 | Each makefile in a subdirectory in the ordered list of subdirectories to | |
678 | be searched is included in order. Since several system-dependent | |
679 | makefiles may be included, each should append to @samp{sysdep-routines} | |
680 | rather than simply setting it: | |
681 | ||
682 | @smallexample | |
683 | sysdep-routines := $(sysdep-routines) foo bar | |
684 | @end smallexample | |
685 | ||
686 | @need 1000 | |
687 | @item Subdirs | |
688 | ||
689 | This file contains the names of new whole subdirectories under the | |
690 | top-level library source tree that should be included for this system. | |
691 | These subdirectories are treated just like the system-independent | |
692 | subdirectories in the library source tree, such as @file{stdio} and | |
693 | @file{math}. | |
694 | ||
695 | Use this when there are completely new sets of functions and header | |
696 | files that should go into the library for the system this subdirectory | |
697 | of @file{sysdeps} implements. For example, | |
698 | @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet} | |
699 | directory contains various network-oriented operations which only make | |
0005e54f | 700 | sense to put in the library on systems that support the Internet. |
28f540f4 | 701 | |
28f540f4 RM |
702 | @item configure |
703 | ||
704 | This file is a shell script fragment to be run at configuration time. | |
705 | The top-level @file{configure} script uses the shell @code{.} command to | |
706 | read the @file{configure} file in each system-dependent directory | |
707 | chosen, in order. The @file{configure} files are often generated from | |
cb8a6dbd | 708 | @file{configure.ac} files using Autoconf. |
28f540f4 RM |
709 | |
710 | A system-dependent @file{configure} script will usually add things to | |
711 | the shell variables @samp{DEFS} and @samp{config_vars}; see the | |
712 | top-level @file{configure} script for details. The script can check for | |
713 | @w{@samp{--with-@var{package}}} options that were passed to the | |
714 | top-level @file{configure}. For an option | |
715 | @w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the | |
716 | shell variable @w{@samp{with_@var{package}}} (with any dashes in | |
717 | @var{package} converted to underscores) to @var{value}; if the option is | |
718 | just @w{@samp{--with-@var{package}}} (no argument), then it sets | |
719 | @w{@samp{with_@var{package}}} to @samp{yes}. | |
720 | ||
cb8a6dbd | 721 | @item configure.ac |
28f540f4 RM |
722 | |
723 | This file is an Autoconf input fragment to be processed into the file | |
724 | @file{configure} in this subdirectory. @xref{Introduction,,, | |
725 | autoconf.info, Autoconf: Generating Automatic Configuration Scripts}, | |
726 | for a description of Autoconf. You should write either @file{configure} | |
cb8a6dbd MF |
727 | or @file{configure.ac}, but not both. The first line of |
728 | @file{configure.ac} should invoke the @code{m4} macro | |
28f540f4 RM |
729 | @samp{GLIBC_PROVIDES}. This macro does several @code{AC_PROVIDE} calls |
730 | for Autoconf macros which are used by the top-level @file{configure} | |
731 | script; without this, those macros might be invoked again unnecessarily | |
732 | by Autoconf. | |
733 | @end table | |
734 | ||
735 | That is the general system for how system-dependencies are isolated. | |
736 | @iftex | |
737 | The next section explains how to decide what directories in | |
738 | @file{sysdeps} to use. @ref{Porting to Unix}, has some tips on porting | |
739 | the library to Unix variants. | |
740 | @end iftex | |
741 | ||
742 | @menu | |
743 | * Hierarchy Conventions:: The layout of the @file{sysdeps} hierarchy. | |
744 | * Porting to Unix:: Porting the library to an average | |
745 | Unix-like system. | |
746 | @end menu | |
747 | ||
748 | @node Hierarchy Conventions | |
749 | @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy | |
750 | ||
751 | A GNU configuration name has three parts: the CPU type, the | |
752 | manufacturer's name, and the operating system. @file{configure} uses | |
753 | these to pick the list of system-dependent directories to look for. If | |
754 | the @samp{--nfp} option is @emph{not} passed to @file{configure}, the | |
755 | directory @file{@var{machine}/fpu} is also used. The operating system | |
756 | often has a @dfn{base operating system}; for example, if the operating | |
68b50604 | 757 | system is @samp{Linux}, the base operating system is @samp{unix/sysv}. |
28f540f4 RM |
758 | The algorithm used to pick the list of directories is simple: |
759 | @file{configure} makes a list of the base operating system, | |
760 | manufacturer, CPU type, and operating system, in that order. It then | |
761 | concatenates all these together with slashes in between, to produce a | |
68b50604 UD |
762 | directory name; for example, the configuration @w{@samp{i686-linux-gnu}} |
763 | results in @file{unix/sysv/linux/i386/i686}. @file{configure} then | |
28f540f4 | 764 | tries removing each element of the list in turn, so |
68b50604 | 765 | @file{unix/sysv/linux} and @file{unix/sysv} are also tried, among others. |
28f540f4 RM |
766 | Since the precise version number of the operating system is often not |
767 | important, and it would be very inconvenient, for example, to have | |
68b50604 | 768 | identical @file{irix6.2} and @file{irix6.3} directories, |
28f540f4 RM |
769 | @file{configure} tries successively less specific operating system names |
770 | by removing trailing suffixes starting with a period. | |
771 | ||
772 | As an example, here is the complete list of directories that would be | |
644d3857 | 773 | tried for the configuration @w{@samp{i686-linux-gnu}}: |
28f540f4 RM |
774 | |
775 | @smallexample | |
68b50604 | 776 | sysdeps/i386/elf |
68b50604 UD |
777 | sysdeps/unix/sysv/linux/i386 |
778 | sysdeps/unix/sysv/linux | |
779 | sysdeps/gnu | |
780 | sysdeps/unix/common | |
781 | sysdeps/unix/mman | |
782 | sysdeps/unix/inet | |
783 | sysdeps/unix/sysv/i386/i686 | |
784 | sysdeps/unix/sysv/i386 | |
785 | sysdeps/unix/sysv | |
786 | sysdeps/unix/i386 | |
787 | sysdeps/unix | |
788 | sysdeps/posix | |
789 | sysdeps/i386/i686 | |
790 | sysdeps/i386/i486 | |
791 | sysdeps/libm-i387/i686 | |
792 | sysdeps/i386/fpu | |
793 | sysdeps/libm-i387 | |
794 | sysdeps/i386 | |
795 | sysdeps/wordsize-32 | |
796 | sysdeps/ieee754 | |
797 | sysdeps/libm-ieee754 | |
798 | sysdeps/generic | |
28f540f4 RM |
799 | @end smallexample |
800 | ||
801 | Different machine architectures are conventionally subdirectories at the | |
802 | top level of the @file{sysdeps} directory tree. For example, | |
803 | @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}. These contain | |
804 | files specific to those machine architectures, but not specific to any | |
805 | particular operating system. There might be subdirectories for | |
806 | specializations of those architectures, such as | |
cf822e3c | 807 | @w{@file{sysdeps/m68k/68020}}. Code which is specific to the |
28f540f4 RM |
808 | floating-point coprocessor used with a particular machine should go in |
809 | @w{@file{sysdeps/@var{machine}/fpu}}. | |
810 | ||
811 | There are a few directories at the top level of the @file{sysdeps} | |
812 | hierarchy that are not for particular machine architectures. | |
813 | ||
814 | @table @file | |
815 | @item generic | |
f2ea0f5b | 816 | As described above (@pxref{Porting}), this is the subdirectory |
28f540f4 RM |
817 | that every configuration implicitly uses after all others. |
818 | ||
819 | @item ieee754 | |
820 | This directory is for code using the IEEE 754 floating-point format, | |
821 | where the C type @code{float} is IEEE 754 single-precision format, and | |
822 | @code{double} is IEEE 754 double-precision format. Usually this | |
823 | directory is referred to in the @file{Implies} file in a machine | |
824 | architecture-specific directory, such as @file{m68k/Implies}. | |
825 | ||
68b50604 UD |
826 | @item libm-ieee754 |
827 | This directory contains an implementation of a mathematical library | |
828 | usable on platforms which use @w{IEEE 754} conformant floating-point | |
829 | arithmetic. | |
830 | ||
831 | @item libm-i387 | |
832 | This is a special case. Ideally the code should be in | |
833 | @file{sysdeps/i386/fpu} but for various reasons it is kept aside. | |
834 | ||
28f540f4 RM |
835 | @item posix |
836 | This directory contains implementations of things in the library in | |
837 | terms of @sc{POSIX.1} functions. This includes some of the @sc{POSIX.1} | |
838 | functions themselves. Of course, @sc{POSIX.1} cannot be completely | |
839 | implemented in terms of itself, so a configuration using just | |
840 | @file{posix} cannot be complete. | |
841 | ||
842 | @item unix | |
843 | This is the directory for Unix-like things. @xref{Porting to Unix}. | |
844 | @file{unix} implies @file{posix}. There are some special-purpose | |
845 | subdirectories of @file{unix}: | |
846 | ||
847 | @table @file | |
848 | @item unix/common | |
849 | This directory is for things common to both BSD and System V release 4. | |
850 | Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}. | |
851 | ||
852 | @item unix/inet | |
853 | This directory is for @code{socket} and related functions on Unix systems. | |
3c20b9b6 | 854 | @file{unix/inet/Subdirs} enables the @file{inet} top-level subdirectory. |
28f540f4 RM |
855 | @file{unix/common} implies @file{unix/inet}. |
856 | @end table | |
857 | ||
858 | @item mach | |
859 | This is the directory for things based on the Mach microkernel from CMU | |
a7a93d50 | 860 | (including @gnuhurdsystems{}). Other basic operating systems |
28f540f4 RM |
861 | (VMS, for example) would have their own directories at the top level of |
862 | the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}. | |
863 | @end table | |
864 | ||
865 | @node Porting to Unix | |
1f77f049 | 866 | @appendixsubsec Porting @theglibc{} to Unix Systems |
28f540f4 RM |
867 | |
868 | Most Unix systems are fundamentally very similar. There are variations | |
869 | between different machines, and variations in what facilities are | |
870 | provided by the kernel. But the interface to the operating system | |
871 | facilities is, for the most part, pretty uniform and simple. | |
872 | ||
873 | The code for Unix systems is in the directory @file{unix}, at the top | |
874 | level of the @file{sysdeps} hierarchy. This directory contains | |
875 | subdirectories (and subdirectory trees) for various Unix variants. | |
876 | ||
877 | The functions which are system calls in most Unix systems are | |
26b4d766 | 878 | implemented in assembly code, which is generated automatically from |
3c20b9b6 UD |
879 | specifications in files named @file{syscalls.list}. There are several |
880 | such files, one in @file{sysdeps/unix} and others in its subdirectories. | |
881 | Some special system calls are implemented in files that are named with a | |
26b4d766 UD |
882 | suffix of @samp{.S}; for example, @file{_exit.S}. Files ending in |
883 | @samp{.S} are run through the C preprocessor before being fed to the | |
884 | assembler. | |
28f540f4 RM |
885 | |
886 | These files all use a set of macros that should be defined in | |
887 | @file{sysdep.h}. The @file{sysdep.h} file in @file{sysdeps/unix} | |
888 | partially defines them; a @file{sysdep.h} file in another directory must | |
889 | finish defining them for the particular machine and operating system | |
890 | variant. See @file{sysdeps/unix/sysdep.h} and the machine-specific | |
891 | @file{sysdep.h} implementations to see what these macros are and what | |
0005e54f | 892 | they should do. |
28f540f4 | 893 | |
3c20b9b6 UD |
894 | The system-specific makefile for the @file{unix} directory |
895 | (@file{sysdeps/unix/Makefile}) gives rules to generate several files | |
28f540f4 RM |
896 | from the Unix system you are building the library on (which is assumed |
897 | to be the target system you are building the library @emph{for}). All | |
898 | the generated files are put in the directory where the object files are | |
899 | kept; they should not affect the source tree itself. The files | |
900 | generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and | |
901 | @file{errlist.c} (for the @file{stdio} section of the library). | |
902 | ||
903 | @ignore | |
904 | @c This section might be a good idea if it is finished, | |
905 | @c but there's no point including it as it stands. --rms | |
906 | @c @appendixsec Compatibility with Traditional C | |
907 | ||
908 | @c ??? This section is really short now. Want to keep it? --roland | |
909 | ||
68b50604 UD |
910 | @c It's not anymore true. glibc 2.1 cannot be used with K&R compilers. |
911 | @c --drepper | |
912 | ||
1f77f049 JM |
913 | Although @theglibc{} implements the @w{ISO C} library facilities, you |
914 | @emph{can} use @theglibc{} with traditional, ``pre-ISO'' C | |
28f540f4 | 915 | compilers. However, you need to be careful because the content and |
1f77f049 | 916 | organization of the @glibcadj{} header files differs from that of |
28f540f4 RM |
917 | traditional C implementations. This means you may need to make changes |
918 | to your program in order to get it to compile. | |
919 | @end ignore |