X-Authentication-Warning: delorie.com: mailnull set sender to djgpp-workers-bounces using -f
Sender: rich AT phekda DOT freeserve DOT co DOT uk
Message-ID: <3C17F34D.6E3D1434@phekda.freeserve.co.uk>
Date: Thu, 13 Dec 2001 00:16:13 +0000
From: Richard Dawe <rich AT phekda DOT freeserve DOT co DOT uk>
X-Mailer: Mozilla 4.77 [en] (X11; U; Linux 2.2.19 i586)
X-Accept-Language: de,fr
MIME-Version: 1.0
To: djgpp-workers AT delorie DOT com
Subject: Re: Description of stubs in develop.txi
References: <3C08E523 DOT C844E69B AT phekda DOT freeserve DOT co DOT uk> <6436-Sat01Dec2001164030+0200-eliz AT is DOT elta DOT co DOT il>
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit
Reply-To: djgpp-workers AT delorie DOT com

Hello.

Below is a diff to update the description of stubs in develop.txi. To
whoever wrote the section in the first place (Martin?): I hope you don't
mind, but I've rewritten it.

If no-one has any objections I'll commit it sometime tomorrow evening, UK
time (GMT).

Thanks, bye, Rich =]

-- 
Richard Dawe
http://www.phekda.freeserve.co.uk/richdawe/

Index: develop.txi
===================================================================
RCS file: /cvs/djgpp/djgpp/src/docs/kb/develop.txi,v
retrieving revision 1.8
diff -p -c -3 -r1.8 develop.txi
*** develop.txi 2001/12/02 11:59:46     1.8
--- develop.txi 2001/12/13 00:13:23
*************** reformat your sources to comply with the
*** 54,71 ****
  -nfc1 -fca -hnl -i2 -ip2 -ci0 -lp -npcs -nprs -psl -nsc -nsob
  @end example
  
! @subsection libc/stubs.h
! @cindex libc/stubs.h
  
! The @strong{only} time you put something in @file{stubs.h} is if an
! ANSI/POSIX function in libc needs to call a non-ANSI/POSIX function
! in libc, in which case the non-ANSI/POSIX function needs to be listed
! in @file{stubs.h} (or, for ANSI functions calling POSIX-only functions).
  
! There is no other reason why a function would get listed in stubs.
  
! @cindex stubbed name
! The @dfn{stubbed name} (@samp{__foo}) is @strong{not} part of
  the published API.
  
  @subsection Far pointers usage
--- 54,92 ----
  -nfc1 -fca -hnl -i2 -ip2 -ci0 -lp -npcs -nprs -psl -nsc -nsob
  @end example
  
! @cindex stubs
! @subsection Stubs
  
! A C application's namespace should not be polluted with non-ANSI
! and non-POSIX functions from the C libraries, unless the application
! explicitly uses these symbols.  An example of a non-ANSI and
! non-POSIX function is @code{fsync} (@pxref{fsync, , fsync, libc}).
  
! But what happens if you wish to call a non-ANSI and/or
! non-POSIX function from C library code?  The actual implementation
! is placed in the C library's private namespace with a stub function
! that calls the implementation.  Consider @code{fsync} ---
! the library would use the @code{__fsync} function internally,
! but application code would use the stub @code{fsync}.
  
! @cindex @file{libc/stubs.h}
! Functions that are stubbed have an entry in the include file
! @file{libc/stubs.h}, e.g.:
! 
! @example
! #define fsync __fsync
! @end example
! 
! Any C library sources defining or calling the implementation
! should include @file{libc/stubs.h} as the first include file.
! This is so that we can refer to e.g. @code{fsync} as @code{fsync}
! in the library code, but the library code will actually define/call
! e.g. @code{__fsync} and will not pollute the application namespace.
! 
! The stub files are assembly language files generated automagically
! from @file{libc/stubs.h} as part of the C library build process.
! 
! NB: The name private name, e.g. @code{__fsync}, is @strong{not} part of
  the published API.
  
  @subsection Far pointers usage