ISO/ IEC JTC1/SC22/WG14 N671

                    Document Number:  WG14 N671/X3J11 97-034


                        C9X Revision Proposal
                        =====================

Title: va_copy proposal
Author: Clive D.W. Feather
Author Affiliation: Demon Internet Ltd
Postal Address: 322 Regents Park Road, London N3 2QQ, UK
E-mail Address: clive@demon.net
Telephone Number: +44 181 371 1138
Fax Number: +44 181 371 1037
Date: 1997-02-28
Proposal Category:
   __ Editorial change/non-normative contribution
   __ Correction
   XX New feature
   __ Addition to obsolescent feature list
   __ Addition to Future Directions
   __ Other (please specify)  ______________________________
Area of Standard Affected:
   __ Environment
   __ Language
   __ Preprocessor
   XX Library
      XX Macro/typedef/tag name
      XX Function
      __ Header
   __ Other (please specify)  ______________________________
Prior Art: n/a
Target Audience: all users of <stdargs.h>

Related Documents (if any): none

Proposal Attached: Yes

Abstract:
This proposal provides an additional facility to make variable arguments
easier to use: a va_list copier.

Notes:
This proposal was prepared with the assistance of Mark Brader, Jutta Degener,
Ron Guilmette, and a person whose employment conditions require anonymity.


Summary
-------
This proposal provides an additional facility to make variable arguments
easier to use: a va_list copier.


Conformance
-----------
This proposal includes a new identifier. The present proposal uses names
in the reserved namespace in order to avoid affecting strictly conforming
programs. If a more attractive name not in the reserved namespace is used
instead, some strictly conforming programs will be affected.

No other aspect of the proposal affects any strictly conforming program.


Discussion
----------
Sometimes processing variable arguments would be easier if the state of
processing could be copied, and then reverted to at a later point. However,
there is currently no way to do this. This proposal adds such a copying
mechanism.


Detailed proposal
-----------------
[Changes are relative to draft 9-pre-3.]

In subclause 7.11, replace:

  The header <stdarg.h> declares a type and defines three macros,

with:

  The header <stdarg.h> declares a type and defines four macros,

replace:

      va_list

  which is a type suitable for holding information  needed  by
  the  macros  va_start, va_arg, and va_end.

with:

      va_list

  which is a type suitable for holding information  needed  by
  the  macros  va_start, va_arg, va_end, and __va_copy.

Replace subclause 7.11.1 paragraph 1 by:

  The va_start, va_arg, and __va_copy macros described in this subclause
  shall be implemented as macros, not functions. It is unspecified
  whether va_end is a macro or an identifier declared with external
  linkage. If a macro definition is suppressed in order to access an
  actual function, or a program defines an external identifier with the
  name va_end, the behavior is undefined. Each invocation of the va_start
  or __va_copy macros shall be matched by a corresponding invocation of
  the va_end macro in the function accepting a varying number of
  arguments.

Add a new subclause 7.11.1.4:

  7.11.1.4  The __va_copy macro

  Synopsis

    #include <stdarg.h>
    void __va_copy (va_list dest, va_list src);

  Description

  The __va_copy function or macro makes the va_list dest be a copy of
  the va_list src, as if the va_start macro had been applied to it
  followed by the same sequence of uses of the va_arg macro as
  had previously been used to reach the present state of src.

  Returns

    The __va_copy function or macro returns no value.

Add a second example:

  Example

  The function f3 is similar, but saves the status of the variable argument
  list after the indicated number of arguments; after f2 has been called
  once with the whole list, the trailing part of the list is gathered
  again and passed to function f4.

    #include <stdarg.h>
    #define MAXARGS 31

    void f3(int n_ptrs, int f4_after, ...)
    {
        va_list ap, ap_save;
        char *array[MAXARGS];
        int ptr_no = 0;
        if (n_ptrs > MAXARGS)
            n_ptrs = MAXARGS;
        va_start(ap, n_ptrs);
        while (ptr_no < n_ptrs)
                {
            array[ptr_no++] = va_arg(ap, char *);
                        if (ptr_no == f4_after)
                            __va_copy(ap_save, ap);
        }
        va_end(ap);
        f2(n_ptrs, array);

        /* Now process the saved copy */

                n_ptrs -= f4_after;
                ptr_no = 0;
        while (ptr_no < n_ptrs)
            array[ptr_no++] = va_arg(ap_save, char *);
        va_end(ap_save);
        f4(n_ptrs, array);
    }

-- 
Clive D.W. Feather    | Associate Director  | Director
Tel: +44 181 371 1138 | Demon Internet Ltd. | CityScape Internet Services Ltd.
Fax: +44 181 371 1150 | <clive@demon.net>   | <cdwf@cityscape.co.uk>
Written on my laptop - please reply to the Reply-To address <clive@demon.net>