StdLib/Include/stdarg.h

   1 /** @file
   2   The header <stdarg.h> declares a type and defines three macros, for advancing
   3   through a list of arguments whose number and types are not known to the
   4   called function when it is translated.
   5
   6   A function may be called with a variable number of arguments of varying types.
   7   Its parameter list contains one or more parameters.  The rightmost parameter
   8   plays a special role in the access mechanism, and will be designated paramN
   9   in this description.
  10
  11   The type va_list is a type suitable for holding information needed by the
  12   macros va_start, va_arg, and va_end.  If access to the varying arguments
  13   is desired, the called function shall declare an object (referred to as ap
  14   in these descriptions) having type va_list.  The object ap may be passed as
  15   an argument to another function; if that function invokes the va_arg macro
  16   with parameter ap, the value of ap in the calling function is indeterminate
  17   and shall be passed to the va_end macro prior to any further reference to ap.
  18
  19   The va_start and va_arg macros shall be implemented as macros, not as actual
  20   functions.  It is unspecified, by the C library standards, whether va_end
  21   is a macro or an identifier declared with external linkage.  If a macro
  22   definition is suppressed in order to access an actual function, or a
  23   program defines an external identifier with the name va_end, the behavior
  24   is undefined.  The va_start and va_end macros shall be invoked in the
  25   function accepting a varying number of arguments, if access to the varying
  26   arguments is desired.
  27
  28 Copyright (c) 2010, Intel Corporation. All rights reserved.<BR>
  29 This program and the accompanying materials are licensed and made available under
  30 the terms and conditions of the BSD License that accompanies this distribution.
  31 The full text of the license may be found at
  32 http://opensource.org/licenses/bsd-license.php.
  33
  34 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
  35 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
  36
  37 **/
  38 #ifndef _STDARG_H
  39 #define _STDARG_H
  40 #include  <sys/EfiCdefs.h>
  41
  42 /** The type va_list is a type suitable for holding information needed by the
  43     macros va_start, va_arg, and va_end.
  44 **/
  45 #if defined(__GNUC__)
  46 typedef __builtin_va_list   va_list;
  47 #else
  48 #define va_list   VA_LIST
  49 #endif
  50
  51 /** The va_start macro shall be invoked before any access to the unnamed arguments.
  52     The va_start macro initializes ap for subsequent use by va_arg and va_end.
  53
  54     Synopsys: void va_start(va_list ap, paramN);
  55
  56     @param  ap      An object of type va_list that is to be initialized such
  57                     that subsequent successive invocations of va_arg will
  58                     return the values of the parameters following paramN.
  59
  60     @param  paramN  The parameter paramN is the identifier of the rightmost
  61                     parameter in the variable parameter list in the function
  62                     definition (the one just before the ,...).  If the
  63                     parameter parmN is declared with the register storage
  64                     class, with a function of array type, or with a type that
  65                     is not compatible with the type that results after
  66                     application of the default argument promotions, the
  67                     behavior is undefined.
  68 **/
  69 #if defined(__GNUC__)
  70 #define va_start    __builtin_va_start
  71 #else
  72 #define va_start    VA_START
  73 #endif
  74
  75 /** The va_arg macro expands to an expression that has the type and value of
  76     the next argument in the call.  The parameter ap shall be the same as the
  77     va_list ap initialized by va_start.  Each invocation of va_arg modifies ap
  78     so that the values of successive arguments are returned in turn.  The
  79     parameter type is a type name specified such that the type of a pointer to
  80     an object that has the specified type can be obtained simply by postfixing
  81     a * to type.  If there is no actual next argument, or if type is not
  82     compatible with the type of the actual next argument (as promoted
  83     according to the default argument promotions), the behavior is undefined.
  84
  85     Synopsys: type va_arg(va_list ap, type);
  86
  87     @param  ap    An object of type va_list that was initialized by a prior
  88                   invocation of va_start.
  89
  90     @param  type  A type name specifying the type of the parameter to be retrieved.
  91
  92     @return       The first invocation of the va_arg macro after that of the
  93                   va_start macro returns the value of the argument after that
  94                   specified by paramN.  Successive invocations return the values
  95                   of the remaining arguments in succession.
  96 **/
  97 #if defined(__GNUC__)
  98 #define va_arg        __builtin_va_arg
  99 #else
 100 #define va_arg        VA_ARG
 101 #endif
 102
 103 /** The va_end macro facillitates a normal return from the function whose
 104     variable argument list was referred to by the expansion of va_start that
 105     initialized the va_list ap.
 106
 107     Synopsys: void va_end(va_list ap);
 108
 109     The va_end macro may modify ap so that it is no longer usable (without an
 110     intervening invocation of va_start).  If there is no corresponding
 111     invocation of the va_start macro, or if the va_end macro is not invoked
 112     before the return, the behavior is undefined.
 113
 114     @param  ap    An object of type va_list, initialized by a prior
 115                   invocation of va_start, that will no longer be referenced.
 116 **/
 117 #if defined(__GNUC__)
 118 #define va_end              __builtin_va_end
 119 #else
 120 #define va_end              VA_END
 121 #endif
 122
 123 /** For BSD compatibility. **/
 124 #if defined(__GNUC__)
 125 #define va_copy         __builtin_va_copy
 126 #else
 127 #define va_copy(s,d)      (s) = (d)
 128 #endif
 129
 130 #endif  /* _STDARG_H */