Unix/Linux Go Back    


Linux 2.6 - man page for stdarg.h (linux section 7posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


<stdarg.h>(P)			    POSIX Programmer's Manual			    <stdarg.h>(P)

NAME
       stdarg.h - handle variable argument list

SYNOPSIS
       #include <stdarg.h>

       void va_start(va_list ap, argN);
       void va_copy(va_list dest, va_list src);
       type va_arg(va_list ap, type);
       void va_end(va_list ap);

DESCRIPTION
       The  <stdarg.h>	header shall contain a set of macros which allows portable functions that
       accept variable argument lists to be written. Functions that have variable argument  lists
       (such  as  printf()) but do not use these macros are inherently non-portable, as different
       systems use different argument-passing conventions.

       The type va_list shall be defined for variables used to traverse the list.

       The va_start() macro is invoked to initialize ap to the beginning of the list  before  any
       calls to va_arg().

       The va_copy() macro initializes dest as a copy of src, as if the va_start() macro had been
       applied to dest followed by the same sequence of uses of the va_arg() macro as had  previ-
       ously  been  used  to reach the present state of src. Neither the va_copy() nor va_start()
       macro shall be invoked to reinitialize dest  without  an  intervening  invocation  of  the
       va_end() macro for the same dest.

       The  object  ap may be passed as an argument to another function; if that function invokes
       the va_arg() macro with parameter ap, the value of ap in the calling function is  unspeci-
       fied  and  shall be passed to the va_end() macro prior to any further reference to ap. The
       parameter argN is the identifier of the rightmost parameter in the variable parameter list
       in  the	function  definition  (the  one  just  before  the ...). If the parameter argN is
       declared with the register storage class, with a function type or array type,  or  with	a
       type  that  is  not compatible with the type that results after application of the default
       argument promotions, the behavior is undefined.

       The va_arg() macro shall return the next argument in the list pointed to by ap. Each invo-
       cation  of va_arg() modifies ap so that the values of successive arguments are returned in
       turn. The type parameter shall be a type name specified such that the type of a pointer to
       an  object that has the specified type can be obtained simply by postfixing a '*' to type.
       If there is no actual next argument, or if type is not compatible with  the  type  of  the
       actual  next  argument  (as  promoted  according  to the default argument promotions), the
       behavior is undefined, except for the following cases:

	* One type is a signed integer type, the other type is the corresponding unsigned integer
	  type, and the value is representable in both types.

	* One type is a pointer to void and the other is a pointer to a character type.

	* Both types are pointers.

       Different types can be mixed, but it is up to the routine to know what type of argument is
       expected.

       The va_end() macro is used to clean up; it invalidates ap for use  (unless  va_start()  or
       va_copy() is invoked again).

       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.

       Multiple traversals, each bracketed by va_start() ... va_end(), are possible.

EXAMPLES
       This example is a possible implementation of execl():

	      #include <stdarg.h>

	      #define  MAXARGS	   31

	      /*
	       * execl is called by
	       * execl(file, arg1, arg2, ..., (char *)(0));
	       */
	      int execl(const char *file, const char *args, ...)
	      {
		  va_list ap;
		  char *array[MAXARGS +1];
		  int argno = 0;

		  va_start(ap, args);
		  while (args != 0 && argno < MAXARGS)
		  {
		      array[argno++] = args;
		      args = va_arg(ap, const char *);
		  }
		  array[argno] = (char *) 0;
		  va_end(ap);
		  return execv(file, array);
	      }

       The following sections are informative.

APPLICATION USAGE
       It is up to the calling routine to communicate to the called routine  how  many	arguments
       there are, since it is not always possible for the called routine to determine this in any
       other way.  For example, execl() is passed a null pointer to signal the end of  the  list.
       The printf() function can tell how many arguments are there by the format argument.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       The System Interfaces volume of IEEE Std 1003.1-2001, exec, printf()

COPYRIGHT
       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003				    <stdarg.h>(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 11:31 PM.