Hi Kaspars, Kaspars Bankovskis wrote on Sat, Dec 06, 2014 at 11:00:35PM +0200:
> I'm proposing the following changes to stdarg(3). > Moved description of return values to its own section + macro cleanup. Committed, thanks. Ingo > Index: stdarg.3 > =================================================================== > RCS file: /cvs/src/share/man/man3/stdarg.3,v > retrieving revision 1.18 > diff -u -p -r1.18 stdarg.3 > --- stdarg.3 30 Nov 2014 21:21:59 -0000 1.18 > +++ stdarg.3 6 Dec 2014 20:43:31 -0000 > @@ -57,15 +57,15 @@ > A function may be called with a varying number of arguments of varying > types. > The include file > -.Aq Pa stdarg.h > +.In stdarg.h > declares a type > -.Pq Li va_list > +.Vt va_list > and defines three macros for stepping > through a list of arguments whose number and types are not known to > the called function. > .Pp > The called function must declare an object of type > -.Li va_list > +.Vt va_list > which is used by the macros > .Fn va_start , > .Fn va_arg , > @@ -95,17 +95,13 @@ macro, it should not be declared as a re > function, nor an array type. > .Pp > The > -.Fn va_start > -macro returns no value. > -.Pp > -The > .Fn va_arg > macro expands to an expression that has the type and value of the next > argument in the call. > The parameter > .Fa ap > is the > -.Li va_list Fa ap > +.Va va_list ap > initialized by > .Fn va_start . > Each call to > @@ -134,33 +130,24 @@ promoted type should be used as the argu > The following describes which types should be promoted (and to what): > .Bl -dash -compact > .It > -.Va short > +.Vt short > is promoted to > -.Va int > +.Vt int > .It > -.Va float > +.Vt float > is promoted to > -.Va double > +.Vt double > .It > -.Va char > +.Vt char > is promoted to > -.Va int > +.Vt int > .El > .Pp > The same rules apply to unsigned versions of the above types, as well > as their bit-type equivalents (e.g.\& > -.Dv int8_t > +.Vt int8_t > and > -.Dv int16_t ) . > -.Pp > -The first use of the > -.Fn va_arg > -macro after that of the > -.Fn va_start > -macro returns the argument after > -.Fa last . > -Successive invocations return the values of the remaining > -arguments. > +.Vt int16_t ) . > .Pp > The > .Fn va_copy > @@ -176,20 +163,28 @@ macro as had previously been used to rea > .Fa src . > .Pp > The > -.Fn va_copy > -macro returns no value. > -.Pp > -The > .Fn va_end > macro handles a normal return from the function whose variable argument > list was initialized by > .Fn va_start > or > .Fn va_copy . > +.Sh RETURN VALUES > +The first use of the > +.Fn va_arg > +macro after that of the > +.Fn va_start > +macro returns the argument after > +.Fa last . > +Successive invocations return the values of the remaining > +arguments. > .Pp > The > +.Fn va_start , > +.Fn va_copy > +and > .Fn va_end > -macro returns no value. > +macros return no value. > .Sh EXAMPLES > The function > .Fn foo > @@ -232,7 +227,7 @@ These macros are > compatible with the historic macros they replace. > A backward compatible version can be found in the include > file > -.Aq Pa varargs.h . > +.In varargs.h . > .Pp > The > .Fn va_start , > @@ -248,7 +243,7 @@ The > and > .Fn va_end > macros were introduced in > -.St -ansiC-89 . > +.St -ansiC . > The > .Fn va_copy > macro was introduced in > @@ -267,7 +262,7 @@ code to > code, > but it also creates difficulties for variadic functions that > wish to pass all of their arguments on to a function > -that takes a > -.Li va_list > -argument, such as > +that takes an argument of type > +.Vt va_list , > +such as > .Xr vfprintf 3 .
