     START-INFO-DIR-ENTRY
     * libc::                        The ANSI C library.
     END-INFO-DIR-ENTRY

This file documents the ANSI C library.

Copyright (C) 1992, 1993 Cygnus Support

libc includes software developed by the University of California, Berkeley and its contributors.

libc includes software developed by Martin Jackson, Graham Haley and Steve Chamberlain of Tadpole Technology and released to Cygnus.

libc uses floating point converstion software developed at AT&T, which includes this copyright information:

The author of this software is David M. Gay.

Copyright (c) 1991 by AT&T.

Permission to use, copy, modify, and distribute this software for any purpose without fee is hereby granted, provided that this entire notice is included in all copies of any software which is or includes a copy or modification of this software and in all copies of the supporting documentation for such software.

THIS SOFTWARE IS BEING PROVIDED "AS IS", WITHOUT ANY EXPRESS OR IMPLIED WARRANTY.  IN PARTICULAR, NEITHER THE AUTHOR NOR AT&T MAKES ANY REPRESENTATION OR WARRANTY OF ANY KIND CONCERNING THE MERCHANTABILITY OF THIS SOFTWARE OR ITS FITNESS FOR ANY PARTICULAR PURPOSE.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, subject to the terms of the GNU General Public License, which includes the provision that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions.

The Cygnus C Support Library
****************************

     [file sigset.texi not included]

     [file targetdep.tex not included]

Variable Argument Lists
***********************

The printf family of functions is defined to accept a variable number of arguments, rather than a fixed argument list.  You can define your own functions with a variable argument list, by using macro definitions from either stdarg.h (for compatibility with ANSI C) or from varargs.h (for compatibility with a popular convention prior to ANSI C).

ANSI-standard macros, stdarg.h
==============================

In ANSI C, a function has a variable number of arguments when its parameter list ends in an ellipsis (...).  The parameter list must also include at least one explicitly named argument; that argument is used to initialize the variable list data structure.

ANSI C defines three macros (va_start, va_arg, and va_end) to operate on variable argument lists.  stdarg.h also defines a special type to represent variable argument lists: this type is called va_list.

Initialize variable argument list
---------------------------------

Synopsis

     #include <stdarg.h>
     void va_start(va_list AP, RIGHTMOST);

Description

Use va_start to initialize the variable argument list AP, so that va_arg can extract values from it.  RIGHTMOST is the name of the last explicit argument in the parameter list (the argument immediately preceding the ellipsis ... that flags variable arguments in an ANSI C function header).  You can only use va_start in a function declared using this ellipsis notation (not, for example, in one of its subfunctions).

Returns

va_start does not return a result.

Portability

ANSI C requires va_start.

Extract a value from argument list
----------------------------------

Synopsis

     #include <stdarg.h>
     TYPE va_arg(va_list AP, TYPE);

Description

va_arg returns the next unprocessed value from a variable argument list AP (which you must previously create with VA_START).  Specify the type for the value as the second parameter to the macro, TYPE.

You may pass a va_list object AP to a subfunction, and use va_arg from the subfunction rather than from the function actually declared with an ellipsis in the header; however, in that case you may only use va_arg from the subfunction.  ANSI C does not permit extracting successive values from a single variable-argument list from different levels of the calling stack.

There is no mechanism for testing whether there is actually a next argument available; you might instead pass an argument count (or some other data that implies an argument count) as one of the fixed arguments in your function call.

Returns

va_arg returns the next argument, an object of type TYPE.

Portability

ANSI C requires va_arg.

Abandon a variable argument list
--------------------------------

Synopsis

     #include <stdarg.h>
     void va_end(va_list AP);

Description

Use va_end to declare that your program will not use the variable argument list AP any further.

Returns

va_end does not return a result.

Portability

ANSI C requires va_end.

Traditional macros, varargs.h
=============================

If your C compiler predates ANSI C, you may still be able to use variable argument lists using the macros from the varargs.h header file.  These macros resemble their ANSI counterparts, but have important differences in usage.   In particular, since traditional C has no declaration mechanism for variable argument lists, two additional macros are provided simply for the purpose of defining functions with variable argument lists.

As with stdarg.h, the type va_list is used to hold a data structure representing a variable argument list.

Declare variable arguments
--------------------------

Synopsis

     #include <varargs.h>
     FUNCTION(va_alist)
     va_dcl

Description

To use the varargs.h version of variable argument lists, you must declare your function with a call to the macro va_alist as its argument list, and use va_dcl as the declaration.  Do not use a semicolon after va_dcl.

Returns

These macros cannot be used in a context where a return is syntactically possible.

Portability

VA_ALIST and VA_DCL were the most widespread method of declaring variable argument lists prior to ANSI C.

Initialize variable argument list
---------------------------------

Synopsis

     #include <varargs.h>
     va_list AP;
     va_start(AP);

Description

With the varargs.h macros, use va_start to initialize a data structure AP to permit manipulating a variable argument list. AP must have the type VA_ALIST.

Returns

va_start does not return a result.

Portability

va_start is also defined as a macro in ANSI C, but the definitions are incompatible; the ANSI version has another parameter besides AP.

Extract a value from argument list
----------------------------------

Synopsis

     #include <varargs.h>
     TYPE va_arg(va_list AP, TYPE);

Description

va_arg returns the next unprocessed value from a variable argument list AP (which you must previously create with VA_START).  Specify the type for the value as the second parameter to the macro, TYPE.

Returns

va_arg returns the next argument, an object of type TYPE.

Portability

The va_arg defined in varargs.h has the same syntax and usage as the ANSI C version from stdarg.h.

Abandon a variable argument list
--------------------------------

Synopsis

     #include <varargs.h>
     va_end(va_list AP);

Description

Use va_end to declare that your program will not use the variable argument list AP any further.

Returns

va_end does not return a result.

Portability

The va_end defined in varargs.h has the same syntax and usage as the ANSI C version from stdarg.h.