Bug 202907

Summary: old matching brace constraint on stdarg macros va_start / va_copy and va_end
Product: Documentation Reporter: Vincent Lefevre (vincent)
Component: man-pagesAssignee: documentation_man-pages (documentation_man-pages)
Status: RESOLVED CODE_FIX    
Severity: normal CC: mtk.manpages
Priority: P1    
Hardware: All   
OS: Linux   
Kernel Version: Subsystem:
Regression: No Bisected commit-id:

Description Vincent Lefevre 2019-03-13 14:05:55 UTC 
The current stdarg(3) man page http://man7.org/linux/man-pages/man3/stdarg.3.html contains in NOTES:

       On some systems, va_end contains a closing '}' matching a '{' in
       va_start, so that both macros must occur in the same function, and in
       a way that allows this.

However, the constraint on the matching braces is not in the ISO C standard, which just requires:

  Each invocation of the va_start and va_copy macros shall be matched
  by a corresponding invocation of the va_end macro in the same
  function.

and

  If there is no corresponding invocation of the va_start or va_copy            
  macro, or if the va_end macro is not invoked before the return, the
  behavior is undefined.

(already present in the DESCRIPTION section of the man page).

According to https://stackoverflow.com/a/25652373/3782797 the matching brace constraint is just history, and it is often not followed in practice. Thus I suggest to remove this paragraph from the man page (or if someone knows an implementation that still has this additional requirement, it should be mentioned).
Comment 1 Michael Kerrisk 2019-05-05 16:57:17 UTC 
The h=whole NOTES section seems to be referring the ancient varargs implementation, and I suspect the paragraph you quite actually is describing va_start/va_end details for that implementation.

I'm actually inclined to remove the whole NOTES section, since it relates to details that were last relevant about 30 years ago.

What do you think about removing the whole NOTES section?
Comment 2 Michael Kerrisk 2019-05-05 17:11:47 UTC 
And furthermore, gcc no longer implements <varargs.h>, probably for at least 15 years. I'm going to remove the NOTES section.