Re: __builtin_extend_pointer

[Jim Wilson <wilson at specifixinc dot com>]

On Mon, 2004-06-14 at 19:19, Benjamin Kosnik wrote:
> All this appears to be very fine indeed, with one small caveat: there
> was no documentation added for this builtin. Any chance you could add
> some?

That was deliberate.  The only current documentation for builtin
functions is user documentation in gcc/doc/extend.texi.  It isn't
appropriate to document gcc internal builtin functions in user docs, as
then users will incorrectly assume that they can use them.  There is
incidentally a paragraph about this in the extend.texi file.

  GCC provides a large number of built-in functions other than the ones
  mentioned above.  Some of these are for internal use in the processing
  of exceptions or variable-length argument lists and will not be
  documented here because they may change from time to time; we do not
  recommend general use of these functions.

I put __builtin_extend_pointers in the EH category, along with the other
related undocumented built in functions like __builtin_eh_return,
__builtin_eh_return_data_regno, __builtin_extract_return_addr,
__builtin_frob_return_addr, etc.

Of course, it would be nice to have internal documentation for them.  I
put some docs in the comments.  I could expand them if not clear.  I
could perhaps add a mention to the docs for the POINTERS_EXTEND_UNSIGNED
macro mentioning that it affects the __builtin_extend_pointers function
which might be helpful.  Do you have any specific suggestions?

I actually think we should have more builtin functions which are removed
from the user docs.  I think it was a historical mistake that we
documented some of them at all, as that just encouraged users to try
things that they never should have.  For instance, I think any user that
tries to use __builtin_apply is dangerously misinformed.
-- 
Jim Wilson, GNU Tools Support, http://www.SpecifixInc.com