Re: __builtin_extend_pointer

[Benjamin Kosnik <bkoz at redhat dot com>]

>  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.

Yes. I guess I'm having problems telling the difference between builtins
that are supposed to be used, and builtins that are not supposed to be
used.

I think what you're saying that if it's documented, and that
documentation is not extend.texi, I can use them? The situation isn't
super clear. It would be nice if the intention was made clear WRT all
builtins and usage.

>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'm having problems finding any documentation at all (extend.texi,
builtins.def, builtins.c) so perhaps you can direct me to what, exactly,
you mean by "put some docs in the comments." Please excuse me in advance
if I'm just being thick-headed about this.

I think what is in your original patch message is quite clear. I was
just surprised that I couldn't find that in the docs, and had to hunt
for it.

>I actually think we should have more builtin functions which are removed
>from the user docs. 

... if that is how you are distinguishing between builtins that are
intended to be used by the public, and builtins that are not, then I
heartily agree. 

However, my preference is to document all builtins, and note the ones
that are intended to be used by the general public explicitly.

best,
benjamin