diff options
Diffstat (limited to 'manual/maint.texi')
| -rw-r--r-- | manual/maint.texi | 51 |
1 files changed, 30 insertions, 21 deletions
diff --git a/manual/maint.texi b/manual/maint.texi index e6fc47f8e1..7698549bf3 100644 --- a/manual/maint.texi +++ b/manual/maint.texi @@ -513,25 +513,35 @@ posix @noindent So the final list is @file{unix/bsd/vax unix/bsd unix/inet unix posix}. -@file{sysdeps} has two ``special'' subdirectories, called @file{generic} -and @file{stub}. These two are always implicitly appended to the list -of subdirectories (in that order), so you needn't put them in an -@file{Implies} file, and you should not create any subdirectories under -them intended to be new specific categories. @file{generic} is for -things that can be implemented in machine-independent C, using only -other machine-independent functions in the C library. @file{stub} is -for @dfn{stub} versions of functions which cannot be implemented on a -particular machine or operating system. The stub functions always -return an error, and set @code{errno} to @code{ENOSYS} (Function not -implemented). @xref{Error Reporting}. - -A source file is known to be system-dependent by its having a version in -@file{generic} or @file{stub}; every generally-available function whose -implementation is system-dependent in should have either a generic or -stub implementation (there is no point in having both). Some rare functions -are only useful on specific systems and aren't defined at all on others; -these do not appear anywhere in the system-independent source code or makefiles -(including the @file{generic} and @file{stub} directories), only in the +@file{sysdeps} has a ``special'' subdirectory called @file{generic}. It +is always implicitly appended to the list of subdirectories, so you +needn't put it in an @file{Implies} file, and you should not create any +subdirectories under it intended to be new specific categories. +@file{generic} serves two purposes. First, the makefiles do not bother +to look for a system-dependent version of a file that's not in +@file{generic}. This means that any system-dependent source file must +have an analogue in @file{generic}, even if the routines defined by that +file are not implemented on other platforms. Second. the @file{generic} +version of a system-dependent file is used if the makefiles do not find +a version specific to the system you're compiling for. + +If it is possible to implement the routines in a @file{generic} file in +machine-independent C, using only other machine-independent functions in +the C library, then you should do so. Otherwise, make them stubs. A +@dfn{stub} function is a function which cannot be implemented on a +particular machine or operating system. Stub functions always return an +error, and set @code{errno} to @code{ENOSYS} (Function not implemented). +@xref{Error Reporting}. If you define a stub function, you must place +the statement @code{stub_warning(@var{function})}, where @var{function} +is the name of your function, after its definition; also, you must +include the file @code{<stub-tag.h>} into your file. This causes the +function to be listed in the installed @code{<gnu/stubs.h>}, and +makes GNU ld warn when the function is used. + +Some rare functions are only useful on specific systems and aren't +defined at all on others; these do not appear anywhere in the +system-independent source code or makefiles (including the +@file{generic} and @file{stub} directories), only in the system-dependent @file{Makefile} in the specific system's subdirectory. If you come across a file that is in one of the main source directories @@ -737,8 +747,7 @@ hierarchy that are not for particular machine architectures. @table @file @item generic -@itemx stub -As described above (@pxref{Porting}), these are the two subdirectories +As described above (@pxref{Porting}), this is the subdirectory that every configuration implicitly uses after all others. @item ieee754 |