]>
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. | |
210 | ||
211 | At runtime, if any of those safety checks fail, the program will | |
212 | terminate with a @code{SIGABRT} signal. @code{_FORTIFY_SOURCE} may be | |
213 | defined to one of the following values: | |
214 | ||
215 | @itemize @bullet | |
216 | @item @math{1}: This enables buffer bounds checking using the value | |
217 | returned by the @code{__builtin_object_size} compiler builtin function. | |
218 | If the function returns @code{(size_t) -1}, the function call is left | |
219 | untouched. Additionally, this level also enables validation of flags to | |
220 | the @code{open}, @code{open64}, @code{openat} and @code{openat64} | |
221 | functions. | |
222 | ||
223 | @item @math{2}: This behaves like @math{1}, with the addition of some | |
224 | checks that may trap code that is conforming but unsafe, e.g. accepting | |
225 | @code{%n} only in read-only format strings. | |
226 | ||
227 | @item @math{3}: This enables buffer bounds checking using the value | |
228 | returned by the @code{__builtin_dynamic_object_size} compiler builtin | |
229 | function. If the function returns @code{(size_t) -1}, the function call | |
230 | is left untouched. Fortification at this level may have a impact on | |
231 | program performance if the function call that is fortified is frequently | |
232 | encountered and the size expression returned by | |
233 | @code{__builtin_dynamic_object_size} is complex. | |
234 | @end itemize | |
235 | ||
236 | In general, the fortified variants of the function calls use the name of | |
237 | the function with a @code{__} prefix and a @code{_chk} suffix. There | |
238 | are some exceptions, e.g. the @code{printf} family of functions where, | |
239 | depending on the architecture, one may also see fortified variants have | |
240 | the @code{_chkieee128} suffix or the @code{__nldbl___} prefix to their | |
241 | names. | |
242 | ||
243 | Another exception is the @code{open} family of functions, where their | |
244 | fortified replacements have the @code{__} prefix and a @code{_2} suffix. | |
245 | The @code{FD_SET}, @code{FD_CLR} and @code{FD_ISSET} macros use the | |
246 | @code{__fdelt_chk} function on fortification. | |
247 | ||
248 | The following functions and macros are fortified in @theglibc{}: | |
249 | @c Generated using the following command: | |
250 | @c find . -name Versions | xargs grep -e "_chk;" -e "_2;" | | |
251 | @c cut -d ':' -f 2 | sed 's/;/\n/g' | sed 's/ *//g' | grep -v "^$" | | |
252 | @c sort -u | grep ^__ | | |
253 | @c grep -v -e ieee128 -e __nldbl -e align_cpy -e "fdelt_warn" | | |
254 | @c sed 's/__fdelt_chk/@item @code{FD_SET}\n\n@item @code{FD_CLR}\n\n@item @code{FD_ISSET}\n/' | | |
255 | @c sed 's/__\(.*\)_\(chk\|2\)/@item @code{\1}\n/' | |
256 | ||
257 | @itemize @bullet | |
258 | ||
259 | @item @code{asprintf} | |
260 | ||
261 | @item @code{confstr} | |
262 | ||
263 | @item @code{dprintf} | |
264 | ||
265 | @item @code{explicit_bzero} | |
266 | ||
267 | @item @code{FD_SET} | |
268 | ||
269 | @item @code{FD_CLR} | |
270 | ||
271 | @item @code{FD_ISSET} | |
272 | ||
273 | @item @code{fgets} | |
274 | ||
275 | @item @code{fgets_unlocked} | |
276 | ||
277 | @item @code{fgetws} | |
278 | ||
279 | @item @code{fgetws_unlocked} | |
280 | ||
281 | @item @code{fprintf} | |
282 | ||
283 | @item @code{fread} | |
284 | ||
285 | @item @code{fread_unlocked} | |
286 | ||
287 | @item @code{fwprintf} | |
288 | ||
289 | @item @code{getcwd} | |
290 | ||
291 | @item @code{getdomainname} | |
292 | ||
293 | @item @code{getgroups} | |
294 | ||
295 | @item @code{gethostname} | |
296 | ||
297 | @item @code{getlogin_r} | |
298 | ||
299 | @item @code{gets} | |
300 | ||
301 | @item @code{getwd} | |
302 | ||
303 | @item @code{longjmp} | |
304 | ||
305 | @item @code{mbsnrtowcs} | |
306 | ||
307 | @item @code{mbsrtowcs} | |
308 | ||
309 | @item @code{mbstowcs} | |
310 | ||
311 | @item @code{memcpy} | |
312 | ||
313 | @item @code{memmove} | |
314 | ||
315 | @item @code{mempcpy} | |
316 | ||
317 | @item @code{memset} | |
318 | ||
319 | @item @code{mq_open} | |
320 | ||
321 | @item @code{obstack_printf} | |
322 | ||
323 | @item @code{obstack_vprintf} | |
324 | ||
325 | @item @code{open} | |
326 | ||
327 | @item @code{open64} | |
328 | ||
329 | @item @code{openat} | |
330 | ||
331 | @item @code{openat64} | |
332 | ||
333 | @item @code{poll} | |
334 | ||
335 | @item @code{ppoll64} | |
336 | ||
337 | @item @code{ppoll} | |
338 | ||
339 | @item @code{pread64} | |
340 | ||
341 | @item @code{pread} | |
342 | ||
343 | @item @code{printf} | |
344 | ||
345 | @item @code{ptsname_r} | |
346 | ||
347 | @item @code{read} | |
348 | ||
349 | @item @code{readlinkat} | |
350 | ||
351 | @item @code{readlink} | |
352 | ||
353 | @item @code{realpath} | |
354 | ||
355 | @item @code{recv} | |
356 | ||
357 | @item @code{recvfrom} | |
358 | ||
359 | @item @code{snprintf} | |
360 | ||
361 | @item @code{sprintf} | |
362 | ||
363 | @item @code{stpcpy} | |
364 | ||
365 | @item @code{stpncpy} | |
366 | ||
367 | @item @code{strcat} | |
368 | ||
369 | @item @code{strcpy} | |
370 | ||
371 | @item @code{strncat} | |
372 | ||
373 | @item @code{strncpy} | |
374 | ||
375 | @item @code{swprintf} | |
376 | ||
377 | @item @code{syslog} | |
378 | ||
379 | @item @code{ttyname_r} | |
380 | ||
381 | @item @code{vasprintf} | |
382 | ||
383 | @item @code{vdprintf} | |
384 | ||
385 | @item @code{vfprintf} | |
386 | ||
387 | @item @code{vfwprintf} | |
388 | ||
389 | @item @code{vprintf} | |
390 | ||
391 | @item @code{vsnprintf} | |
392 | ||
393 | @item @code{vsprintf} | |
394 | ||
395 | @item @code{vswprintf} | |
396 | ||
397 | @item @code{vsyslog} | |
398 | ||
399 | @item @code{vwprintf} | |
400 | ||
401 | @item @code{wcpcpy} | |
402 | ||
403 | @item @code{wcpncpy} | |
404 | ||
405 | @item @code{wcrtomb} | |
406 | ||
407 | @item @code{wcscat} | |
408 | ||
409 | @item @code{wcscpy} | |
410 | ||
411 | @item @code{wcsncat} | |
412 | ||
413 | @item @code{wcsncpy} | |
414 | ||
415 | @item @code{wcsnrtombs} | |
416 | ||
417 | @item @code{wcsrtombs} | |
418 | ||
419 | @item @code{wcstombs} | |
420 | ||
421 | @item @code{wctomb} | |
422 | ||
423 | @item @code{wmemcpy} | |
424 | ||
425 | @item @code{wmemmove} | |
426 | ||
427 | @item @code{wmempcpy} | |
428 | ||
429 | @item @code{wmemset} | |
430 | ||
431 | @item @code{wprintf} | |
432 | ||
433 | @end itemize | |
434 | ||
435 | ||
6e15f3e2 AA |
436 | @node Symbol handling |
437 | @appendixsec Symbol handling in the GNU C Library | |
438 | ||
439 | @menu | |
440 | * 64-bit time symbol handling :: How to handle 64-bit time related | |
441 | symbols in the GNU C Library. | |
442 | @end menu | |
443 | ||
444 | @node 64-bit time symbol handling | |
445 | @appendixsubsec 64-bit time symbol handling in the GNU C Library | |
446 | ||
bfb79db4 | 447 | With respect to time handling, @glibcadj{} configurations fall in two |
6e15f3e2 AA |
448 | classes depending on the value of @code{__TIMESIZE}: |
449 | ||
450 | @table @code | |
451 | ||
452 | @item @code{__TIMESIZE == 32} | |
453 | ||
454 | These @dfn{dual-time} configurations have both 32-bit and 64-bit time | |
455 | support. 32-bit time support provides type @code{time_t} and cannot | |
456 | handle dates beyond @dfn{Y2038}. 64-bit time support provides type | |
457 | @code{__time64_t} and can handle dates beyond @dfn{Y2038}. | |
458 | ||
459 | In these configurations, time-related types have two declarations, | |
460 | a 64-bit one, and a 32-bit one; and time-related functions generally | |
461 | have two definitions: a 64-bit one, and a 32-bit one which is a wrapper | |
462 | around the former. Therefore, for every @code{time_t}-related symbol, | |
463 | there is a corresponding @code{__time64_t}-related symbol, the name of | |
464 | which is usually the 32-bit symbol's name with @code{__} (a double | |
465 | underscore) prepended and @code{64} appended. For instance, the | |
466 | 64-bit-time counterpart of @code{clock_gettime} is | |
467 | @code{__clock_gettime64}. | |
468 | ||
469 | @item @code{__TIMESIZE == 64} | |
470 | ||
471 | These @dfn{single-time} configurations only have a 64-bit @code{time_t} | |
472 | and related functions, which can handle dates beyond 2038-01-19 | |
473 | 03:14:07 (aka @dfn{Y2038}). | |
474 | ||
475 | In these configurations, time-related types only have a 64-bit | |
476 | declaration; and time-related functions only have one 64-bit definition. | |
477 | However, for every @code{time_t}-related symbol, there is a | |
478 | corresponding @code{__time64_t}-related macro, the name of which is | |
479 | derived as in the dual-time configuration case, and which expands to | |
480 | the symbol's name. For instance, the macro @code{__clock_gettime64} | |
481 | expands to @code{clock_gettime}. | |
482 | ||
483 | These macros are purely internal to @theglibc{} and exist only so that | |
484 | a single definition of the 64-bit time functions can be used on both | |
485 | single-time and dual-time configurations, and so that glibc code can | |
486 | freely call the 64-bit functions internally in all configurations. | |
487 | ||
488 | @end table | |
489 | ||
490 | @c The following paragraph should be removed once external interfaces | |
491 | @c get support for both time sizes. | |
492 | ||
493 | Note: at this point, 64-bit time support in dual-time configurations is | |
494 | work-in-progress, so for these configurations, the public API only makes | |
495 | the 32-bit time support available. In a later change, the public API | |
496 | will allow user code to choose the time size for a given compilation | |
497 | unit. | |
498 | ||
499 | 64-bit variants of time-related types or functions are defined for all | |
500 | configurations and use 64-bit-time symbol names (for dual-time | |
501 | configurations) or macros (for single-time configurations). | |
502 | ||
503 | 32-bit variants of time-related types or functions are defined only for | |
504 | dual-time configurations. | |
505 | ||
506 | Here is an example with @code{localtime}: | |
507 | ||
508 | Function @code{localtime} is declared in @file{time/time.h} as | |
509 | @smallexample | |
510 | extern struct tm *localtime (const time_t *__timer) __THROW; | |
511 | libc_hidden_proto (localtime) | |
512 | @end smallexample | |
513 | ||
514 | For single-time configurations, @code{__localtime64} is a macro which | |
515 | evaluates to @code{localtime}; for dual-time configurations, | |
516 | @code{__localtime64} is a function similar to @code{localtime} except | |
517 | it uses Y2038-proof types: | |
518 | @smallexample | |
519 | #if __TIMESIZE == 64 | |
520 | # define __localtime64 localtime | |
521 | #else | |
522 | extern struct tm *__localtime64 (const __time64_t *__timer) __THROW; | |
523 | libc_hidden_proto (__localtime64) | |
524 | #endif | |
525 | @end smallexample | |
526 | ||
527 | (note: type @code{time_t} is replaced with @code{__time64_t} because | |
528 | @code{time_t} is not Y2038-proof, but @code{struct tm} is not | |
529 | replaced because it is already Y2038-proof.) | |
530 | ||
531 | The 64-bit-time implementation of @code{localtime} is written as follows | |
532 | and is compiled for both dual-time and single-time configuration classes. | |
533 | ||
534 | @smallexample | |
535 | struct tm * | |
536 | __localtime64 (const __time64_t *t) | |
8b18d418 | 537 | @{ |
6e15f3e2 | 538 | return __tz_convert (*t, 1, &_tmbuf); |
8b18d418 | 539 | @} |
6e15f3e2 AA |
540 | libc_hidden_def (__localtime64) |
541 | @end smallexample | |
542 | ||
543 | The 32-bit-time implementation is a wrapper and is only compiled for | |
544 | dual-time configurations: | |
545 | ||
546 | @smallexample | |
547 | #if __TIMESIZE != 64 | |
548 | ||
549 | struct tm * | |
550 | localtime (const time_t *t) | |
8b18d418 | 551 | @{ |
6e15f3e2 AA |
552 | __time64_t t64 = *t; |
553 | return __localtime64 (&t64); | |
8b18d418 | 554 | @} |
6e15f3e2 AA |
555 | libc_hidden_def (localtime) |
556 | ||
557 | #endif | |
558 | @end smallexample | |
559 | ||
28f540f4 | 560 | @node Porting |
1f77f049 | 561 | @appendixsec Porting @theglibc{} |
28f540f4 | 562 | |
1f77f049 | 563 | @Theglibc{} is written to be easily portable to a variety of |
28f540f4 RM |
564 | machines and operating systems. Machine- and operating system-dependent |
565 | functions are well separated to make it easy to add implementations for | |
566 | new machines or operating systems. This section describes the layout of | |
567 | the library source tree and explains the mechanisms used to select | |
568 | machine-dependent code to use. | |
569 | ||
570 | All the machine-dependent and operating system-dependent files in the | |
571 | library are in the subdirectory @file{sysdeps} under the top-level | |
572 | library source directory. This directory contains a hierarchy of | |
573 | subdirectories (@pxref{Hierarchy Conventions}). | |
574 | ||
575 | Each subdirectory of @file{sysdeps} contains source files for a | |
576 | particular machine or operating system, or for a class of machine or | |
577 | operating system (for example, systems by a particular vendor, or all | |
578 | machines that use IEEE 754 floating-point format). A configuration | |
579 | specifies an ordered list of these subdirectories. Each subdirectory | |
580 | implicitly appends its parent directory to the list. For example, | |
581 | specifying the list @file{unix/bsd/vax} is equivalent to specifying the | |
582 | list @file{unix/bsd/vax unix/bsd unix}. A subdirectory can also specify | |
583 | that it implies other subdirectories which are not directly above it in | |
584 | the directory hierarchy. If the file @file{Implies} exists in a | |
585 | subdirectory, it lists other subdirectories of @file{sysdeps} which are | |
586 | appended to the list, appearing after the subdirectory containing the | |
587 | @file{Implies} file. Lines in an @file{Implies} file that begin with a | |
588 | @samp{#} character are ignored as comments. For example, | |
0005e54f | 589 | @file{unix/bsd/Implies} contains: |
28f540f4 RM |
590 | @smallexample |
591 | # BSD has Internet-related things. | |
592 | unix/inet | |
593 | @end smallexample | |
594 | @noindent | |
595 | and @file{unix/Implies} contains: | |
596 | @need 300 | |
597 | @smallexample | |
598 | posix | |
599 | @end smallexample | |
600 | ||
601 | @noindent | |
602 | So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}. | |
603 | ||
f2ea0f5b UD |
604 | @file{sysdeps} has a ``special'' subdirectory called @file{generic}. It |
605 | is always implicitly appended to the list of subdirectories, so you | |
606 | needn't put it in an @file{Implies} file, and you should not create any | |
607 | subdirectories under it intended to be new specific categories. | |
608 | @file{generic} serves two purposes. First, the makefiles do not bother | |
609 | to look for a system-dependent version of a file that's not in | |
610 | @file{generic}. This means that any system-dependent source file must | |
611 | have an analogue in @file{generic}, even if the routines defined by that | |
11bf311e | 612 | file are not implemented on other platforms. Second, the @file{generic} |
f2ea0f5b UD |
613 | version of a system-dependent file is used if the makefiles do not find |
614 | a version specific to the system you're compiling for. | |
615 | ||
616 | If it is possible to implement the routines in a @file{generic} file in | |
617 | machine-independent C, using only other machine-independent functions in | |
618 | the C library, then you should do so. Otherwise, make them stubs. A | |
619 | @dfn{stub} function is a function which cannot be implemented on a | |
620 | particular machine or operating system. Stub functions always return an | |
621 | error, and set @code{errno} to @code{ENOSYS} (Function not implemented). | |
622 | @xref{Error Reporting}. If you define a stub function, you must place | |
623 | the statement @code{stub_warning(@var{function})}, where @var{function} | |
b830319d | 624 | is the name of your function, after its definition. This causes the |
f2ea0f5b UD |
625 | function to be listed in the installed @code{<gnu/stubs.h>}, and |
626 | makes GNU ld warn when the function is used. | |
627 | ||
cc3fa755 UD |
628 | Some rare functions are only useful on specific systems and aren't |
629 | defined at all on others; these do not appear anywhere in the | |
630 | system-independent source code or makefiles (including the | |
631 | @file{generic} directory), only in the system-dependent @file{Makefile} | |
632 | in the specific system's subdirectory. | |
28f540f4 RM |
633 | |
634 | If you come across a file that is in one of the main source directories | |
635 | (@file{string}, @file{stdio}, etc.), and you want to write a machine- or | |
636 | operating system-dependent version of it, move the file into | |
637 | @file{sysdeps/generic} and write your new implementation in the | |
638 | appropriate system-specific subdirectory. Note that if a file is to be | |
639 | system-dependent, it @strong{must not} appear in one of the main source | |
0005e54f | 640 | directories. |
28f540f4 RM |
641 | |
642 | There are a few special files that may exist in each subdirectory of | |
643 | @file{sysdeps}: | |
644 | ||
645 | @comment Blank lines after items make the table look better. | |
646 | @table @file | |
647 | @item Makefile | |
648 | ||
649 | A makefile for this machine or operating system, or class of machine or | |
650 | operating system. This file is included by the library makefile | |
651 | @file{Makerules}, which is used by the top-level makefile and the | |
652 | subdirectory makefiles. It can change the variables set in the | |
653 | including makefile or add new rules. It can use GNU @code{make} | |
654 | conditional directives based on the variable @samp{subdir} (see above) to | |
655 | select different sets of variables and rules for different sections of | |
656 | the library. It can also set the @code{make} variable | |
657 | @samp{sysdep-routines}, to specify extra modules to be included in the | |
658 | library. You should use @samp{sysdep-routines} rather than adding | |
659 | modules to @samp{routines} because the latter is used in determining | |
0005e54f | 660 | what to distribute for each subdirectory of the main source tree. |
28f540f4 RM |
661 | |
662 | Each makefile in a subdirectory in the ordered list of subdirectories to | |
663 | be searched is included in order. Since several system-dependent | |
664 | makefiles may be included, each should append to @samp{sysdep-routines} | |
665 | rather than simply setting it: | |
666 | ||
667 | @smallexample | |
668 | sysdep-routines := $(sysdep-routines) foo bar | |
669 | @end smallexample | |
670 | ||
671 | @need 1000 | |
672 | @item Subdirs | |
673 | ||
674 | This file contains the names of new whole subdirectories under the | |
675 | top-level library source tree that should be included for this system. | |
676 | These subdirectories are treated just like the system-independent | |
677 | subdirectories in the library source tree, such as @file{stdio} and | |
678 | @file{math}. | |
679 | ||
680 | Use this when there are completely new sets of functions and header | |
681 | files that should go into the library for the system this subdirectory | |
682 | of @file{sysdeps} implements. For example, | |
683 | @file{sysdeps/unix/inet/Subdirs} contains @file{inet}; the @file{inet} | |
684 | directory contains various network-oriented operations which only make | |
0005e54f | 685 | sense to put in the library on systems that support the Internet. |
28f540f4 | 686 | |
28f540f4 RM |
687 | @item configure |
688 | ||
689 | This file is a shell script fragment to be run at configuration time. | |
690 | The top-level @file{configure} script uses the shell @code{.} command to | |
691 | read the @file{configure} file in each system-dependent directory | |
692 | chosen, in order. The @file{configure} files are often generated from | |
cb8a6dbd | 693 | @file{configure.ac} files using Autoconf. |
28f540f4 RM |
694 | |
695 | A system-dependent @file{configure} script will usually add things to | |
696 | the shell variables @samp{DEFS} and @samp{config_vars}; see the | |
697 | top-level @file{configure} script for details. The script can check for | |
698 | @w{@samp{--with-@var{package}}} options that were passed to the | |
699 | top-level @file{configure}. For an option | |
700 | @w{@samp{--with-@var{package}=@var{value}}} @file{configure} sets the | |
701 | shell variable @w{@samp{with_@var{package}}} (with any dashes in | |
702 | @var{package} converted to underscores) to @var{value}; if the option is | |
703 | just @w{@samp{--with-@var{package}}} (no argument), then it sets | |
704 | @w{@samp{with_@var{package}}} to @samp{yes}. | |
705 | ||
cb8a6dbd | 706 | @item configure.ac |
28f540f4 RM |
707 | |
708 | This file is an Autoconf input fragment to be processed into the file | |
709 | @file{configure} in this subdirectory. @xref{Introduction,,, | |
710 | autoconf.info, Autoconf: Generating Automatic Configuration Scripts}, | |
711 | for a description of Autoconf. You should write either @file{configure} | |
cb8a6dbd MF |
712 | or @file{configure.ac}, but not both. The first line of |
713 | @file{configure.ac} should invoke the @code{m4} macro | |
28f540f4 RM |
714 | @samp{GLIBC_PROVIDES}. This macro does several @code{AC_PROVIDE} calls |
715 | for Autoconf macros which are used by the top-level @file{configure} | |
716 | script; without this, those macros might be invoked again unnecessarily | |
717 | by Autoconf. | |
718 | @end table | |
719 | ||
720 | That is the general system for how system-dependencies are isolated. | |
721 | @iftex | |
722 | The next section explains how to decide what directories in | |
723 | @file{sysdeps} to use. @ref{Porting to Unix}, has some tips on porting | |
724 | the library to Unix variants. | |
725 | @end iftex | |
726 | ||
727 | @menu | |
728 | * Hierarchy Conventions:: The layout of the @file{sysdeps} hierarchy. | |
729 | * Porting to Unix:: Porting the library to an average | |
730 | Unix-like system. | |
731 | @end menu | |
732 | ||
733 | @node Hierarchy Conventions | |
734 | @appendixsubsec Layout of the @file{sysdeps} Directory Hierarchy | |
735 | ||
736 | A GNU configuration name has three parts: the CPU type, the | |
737 | manufacturer's name, and the operating system. @file{configure} uses | |
738 | these to pick the list of system-dependent directories to look for. If | |
739 | the @samp{--nfp} option is @emph{not} passed to @file{configure}, the | |
740 | directory @file{@var{machine}/fpu} is also used. The operating system | |
741 | often has a @dfn{base operating system}; for example, if the operating | |
68b50604 | 742 | system is @samp{Linux}, the base operating system is @samp{unix/sysv}. |
28f540f4 RM |
743 | The algorithm used to pick the list of directories is simple: |
744 | @file{configure} makes a list of the base operating system, | |
745 | manufacturer, CPU type, and operating system, in that order. It then | |
746 | concatenates all these together with slashes in between, to produce a | |
68b50604 UD |
747 | directory name; for example, the configuration @w{@samp{i686-linux-gnu}} |
748 | results in @file{unix/sysv/linux/i386/i686}. @file{configure} then | |
28f540f4 | 749 | tries removing each element of the list in turn, so |
68b50604 | 750 | @file{unix/sysv/linux} and @file{unix/sysv} are also tried, among others. |
28f540f4 RM |
751 | Since the precise version number of the operating system is often not |
752 | important, and it would be very inconvenient, for example, to have | |
68b50604 | 753 | identical @file{irix6.2} and @file{irix6.3} directories, |
28f540f4 RM |
754 | @file{configure} tries successively less specific operating system names |
755 | by removing trailing suffixes starting with a period. | |
756 | ||
757 | As an example, here is the complete list of directories that would be | |
644d3857 | 758 | tried for the configuration @w{@samp{i686-linux-gnu}}: |
28f540f4 RM |
759 | |
760 | @smallexample | |
68b50604 | 761 | sysdeps/i386/elf |
68b50604 UD |
762 | sysdeps/unix/sysv/linux/i386 |
763 | sysdeps/unix/sysv/linux | |
764 | sysdeps/gnu | |
765 | sysdeps/unix/common | |
766 | sysdeps/unix/mman | |
767 | sysdeps/unix/inet | |
768 | sysdeps/unix/sysv/i386/i686 | |
769 | sysdeps/unix/sysv/i386 | |
770 | sysdeps/unix/sysv | |
771 | sysdeps/unix/i386 | |
772 | sysdeps/unix | |
773 | sysdeps/posix | |
774 | sysdeps/i386/i686 | |
775 | sysdeps/i386/i486 | |
776 | sysdeps/libm-i387/i686 | |
777 | sysdeps/i386/fpu | |
778 | sysdeps/libm-i387 | |
779 | sysdeps/i386 | |
780 | sysdeps/wordsize-32 | |
781 | sysdeps/ieee754 | |
782 | sysdeps/libm-ieee754 | |
783 | sysdeps/generic | |
28f540f4 RM |
784 | @end smallexample |
785 | ||
786 | Different machine architectures are conventionally subdirectories at the | |
787 | top level of the @file{sysdeps} directory tree. For example, | |
788 | @w{@file{sysdeps/sparc}} and @w{@file{sysdeps/m68k}}. These contain | |
789 | files specific to those machine architectures, but not specific to any | |
790 | particular operating system. There might be subdirectories for | |
791 | specializations of those architectures, such as | |
cf822e3c | 792 | @w{@file{sysdeps/m68k/68020}}. Code which is specific to the |
28f540f4 RM |
793 | floating-point coprocessor used with a particular machine should go in |
794 | @w{@file{sysdeps/@var{machine}/fpu}}. | |
795 | ||
796 | There are a few directories at the top level of the @file{sysdeps} | |
797 | hierarchy that are not for particular machine architectures. | |
798 | ||
799 | @table @file | |
800 | @item generic | |
f2ea0f5b | 801 | As described above (@pxref{Porting}), this is the subdirectory |
28f540f4 RM |
802 | that every configuration implicitly uses after all others. |
803 | ||
804 | @item ieee754 | |
805 | This directory is for code using the IEEE 754 floating-point format, | |
806 | where the C type @code{float} is IEEE 754 single-precision format, and | |
807 | @code{double} is IEEE 754 double-precision format. Usually this | |
808 | directory is referred to in the @file{Implies} file in a machine | |
809 | architecture-specific directory, such as @file{m68k/Implies}. | |
810 | ||
68b50604 UD |
811 | @item libm-ieee754 |
812 | This directory contains an implementation of a mathematical library | |
813 | usable on platforms which use @w{IEEE 754} conformant floating-point | |
814 | arithmetic. | |
815 | ||
816 | @item libm-i387 | |
817 | This is a special case. Ideally the code should be in | |
818 | @file{sysdeps/i386/fpu} but for various reasons it is kept aside. | |
819 | ||
28f540f4 RM |
820 | @item posix |
821 | This directory contains implementations of things in the library in | |
822 | terms of @sc{POSIX.1} functions. This includes some of the @sc{POSIX.1} | |
823 | functions themselves. Of course, @sc{POSIX.1} cannot be completely | |
824 | implemented in terms of itself, so a configuration using just | |
825 | @file{posix} cannot be complete. | |
826 | ||
827 | @item unix | |
828 | This is the directory for Unix-like things. @xref{Porting to Unix}. | |
829 | @file{unix} implies @file{posix}. There are some special-purpose | |
830 | subdirectories of @file{unix}: | |
831 | ||
832 | @table @file | |
833 | @item unix/common | |
834 | This directory is for things common to both BSD and System V release 4. | |
835 | Both @file{unix/bsd} and @file{unix/sysv/sysv4} imply @file{unix/common}. | |
836 | ||
837 | @item unix/inet | |
838 | This directory is for @code{socket} and related functions on Unix systems. | |
3c20b9b6 | 839 | @file{unix/inet/Subdirs} enables the @file{inet} top-level subdirectory. |
28f540f4 RM |
840 | @file{unix/common} implies @file{unix/inet}. |
841 | @end table | |
842 | ||
843 | @item mach | |
844 | This is the directory for things based on the Mach microkernel from CMU | |
a7a93d50 | 845 | (including @gnuhurdsystems{}). Other basic operating systems |
28f540f4 RM |
846 | (VMS, for example) would have their own directories at the top level of |
847 | the @file{sysdeps} hierarchy, parallel to @file{unix} and @file{mach}. | |
848 | @end table | |
849 | ||
850 | @node Porting to Unix | |
1f77f049 | 851 | @appendixsubsec Porting @theglibc{} to Unix Systems |
28f540f4 RM |
852 | |
853 | Most Unix systems are fundamentally very similar. There are variations | |
854 | between different machines, and variations in what facilities are | |
855 | provided by the kernel. But the interface to the operating system | |
856 | facilities is, for the most part, pretty uniform and simple. | |
857 | ||
858 | The code for Unix systems is in the directory @file{unix}, at the top | |
859 | level of the @file{sysdeps} hierarchy. This directory contains | |
860 | subdirectories (and subdirectory trees) for various Unix variants. | |
861 | ||
862 | The functions which are system calls in most Unix systems are | |
26b4d766 | 863 | implemented in assembly code, which is generated automatically from |
3c20b9b6 UD |
864 | specifications in files named @file{syscalls.list}. There are several |
865 | such files, one in @file{sysdeps/unix} and others in its subdirectories. | |
866 | Some special system calls are implemented in files that are named with a | |
26b4d766 UD |
867 | suffix of @samp{.S}; for example, @file{_exit.S}. Files ending in |
868 | @samp{.S} are run through the C preprocessor before being fed to the | |
869 | assembler. | |
28f540f4 RM |
870 | |
871 | These files all use a set of macros that should be defined in | |
872 | @file{sysdep.h}. The @file{sysdep.h} file in @file{sysdeps/unix} | |
873 | partially defines them; a @file{sysdep.h} file in another directory must | |
874 | finish defining them for the particular machine and operating system | |
875 | variant. See @file{sysdeps/unix/sysdep.h} and the machine-specific | |
876 | @file{sysdep.h} implementations to see what these macros are and what | |
0005e54f | 877 | they should do. |
28f540f4 | 878 | |
3c20b9b6 UD |
879 | The system-specific makefile for the @file{unix} directory |
880 | (@file{sysdeps/unix/Makefile}) gives rules to generate several files | |
28f540f4 RM |
881 | from the Unix system you are building the library on (which is assumed |
882 | to be the target system you are building the library @emph{for}). All | |
883 | the generated files are put in the directory where the object files are | |
884 | kept; they should not affect the source tree itself. The files | |
885 | generated are @file{ioctls.h}, @file{errnos.h}, @file{sys/param.h}, and | |
886 | @file{errlist.c} (for the @file{stdio} section of the library). | |
887 | ||
888 | @ignore | |
889 | @c This section might be a good idea if it is finished, | |
890 | @c but there's no point including it as it stands. --rms | |
891 | @c @appendixsec Compatibility with Traditional C | |
892 | ||
893 | @c ??? This section is really short now. Want to keep it? --roland | |
894 | ||
68b50604 UD |
895 | @c It's not anymore true. glibc 2.1 cannot be used with K&R compilers. |
896 | @c --drepper | |
897 | ||
1f77f049 JM |
898 | Although @theglibc{} implements the @w{ISO C} library facilities, you |
899 | @emph{can} use @theglibc{} with traditional, ``pre-ISO'' C | |
28f540f4 | 900 | compilers. However, you need to be careful because the content and |
1f77f049 | 901 | organization of the @glibcadj{} header files differs from that of |
28f540f4 RM |
902 | traditional C implementations. This means you may need to make changes |
903 | to your program in order to get it to compile. | |
904 | @end ignore |