function.gml

开放源码的编译器open watcom 1.6.0版的源代码

.kw int
and a return value is required, the behavior is undefined.
.pp
The prototype for a function must match the function definition.
Each parameter type and the type of the return value must be the same,
otherwise the behavior is undefined.
.pp
All library functions have prototypes in one of several
.ix 'header'
header files. That header file should be included whenever a function
described therein is used.
Refer to the &libref for details.
.beglevel
.*
.section Variable Argument Lists
.*
.ix 'variable argument list'
.pp
If the prototype (and definition)
for a function has a parameter list that ends with
.mono ,...
then the function has a
.us variable argument list
or
.us variable parameter list
meaning that the number of arguments to the function can vary.
(The
library function
.libfn printf
is an example.)
At least one argument must be provided before the variable portion.
This argument usually describes, in some fashion, how many other
arguments to expect.
It may be a simple count, or may involve (as with
.libfn printf
..ct )
an encoding of the number and types of arguments.
.pp
All arguments that correspond to a variable argument list have the
default argument promotions performed on them, since it is not possible
to determine, at compilation time, what types will be required by
the function.
.pp
Since the parameters represented by the
.mono ,...
don't have names, special handling is required.
The C language provides a special type and three macros for
handling variable argument lists.
To be able to use these, the header
.hdr <stdarg.h>
must be included.
.pp
The type
.ix type va_list
.ix 'va_list type'
.kw va_list
is an
implementation-specific
type used to store information about the variable list.
Within the function, an object must be declared with type
.kw va_list
..ct ..li .
This object is used by the macros and functions for processing the list.
.* .pp
.* In the following examples, it is assumed that the declaration
.* .millust begin
.* va_list parminfo;
.* .millust end
.* .pc
.* has been made in the function processing its variable parameter list.
.pp
The macro
.ix macro 'variable argument' 'va_start'
.ix va_start
.mkw va_start
has the form,
.millust begin
void va_start( va_list :ITAL.parminfo:eITAL., :ITAL.lastparm:eITAL. );
.millust end
.pc
The
object
:ITAL.parminfo:eITAL.
is set up by the macro with information describing the variable
list. The argument
:ITAL.lastparm:eITAL.
is the name (identifier) of the last parameter before the
.mono ,...
and must not have been declared with the storage class
.ix 'storage class' register
.ix register
.kw register
..ct ..li .
.pp
The macro
.mkw va_start
must be executed before any processing of the variable portion of the
parameter list is performed.
.pp
.mkw va_start
may be executed more than once, but only if an intervening
.mkw va_end
is executed.
.pp
The macro
.ix macro 'variable argument' va_arg
.ix va_arg
.mkw va_arg
has the form,
.millust begin
:ITAL.type:eITAL. va_arg( va_list :ITAL.parminfo:eITAL., :ITAL.type:eITAL. );
.millust end
.pp
.us parminfo
is the same object named in the call to
.mkw va_start
..ct ..li .
.us type
is the type of argument expected.
The types expected should only be those that result from the default
argument promotions (
..ct .kw int
..ct ,
.kw long int
and
.kw long long int
and their unsigned varieties,
.kw double
and
.kw long double
..ct ),
and those that are not subject to promotion
(pointers, structures and unions).
The type must be determined
by the program.
The
.mkw va_arg
macro expands to an expression that has the type and value of the
next parameter in the variable list.
.pp
In the case of
.libfn printf
..ct ,
the parameter type expected is determined by the "conversion
specifications" such as
.mono %s
..ct ,
.mono %d
and so on.
.pp
The first invocation of the
.mkw va_arg
macro (after executing a
.mkw va_start
..ct ) returns the value of the parameter following
.us lastparm
(as specified in
.mkw va_start
..ct ). Each subsequent invocation of
.mkw va_arg
returns the next parameter in the list.
At each invocation, the value of
.us parminfo
is modified (in some implementation-specific manner)
to reflect the processing of the parameter list.
.pp
If the type of the next parameter does not match
.us type
..ct ,
or if no parameter was specified, the behavior is undefined.
.pp
The macro
.ix va_end
.ix macro 'variable argument' 'va_end'
.mkw va_end
has the form,
.millust begin
void va_end( va_list :ITAL.parminfo:eITAL. );
.millust end
.pp
.us parminfo
is the same object named in the corresponding call to
.mkw va_start
..ct ..li .
The function
.mkw va_end
closes off processing of the variable argument list, which must be
done prior to returning from the function. If
.mkw va_end
is not called before returning, the behavior is undefined.
.pp
If
.mkw va_end
is called without a corresponding call to
.mkw va_start
having been done, the behavior is undefined.
.pp
After calling
.mkw va_end
and prior to returning, it is possible to call
.mkw va_start
again and reprocess the variable list. It will be necessary to
call
.mkw va_end
again before returning.
.pp
The following function takes an arbitrary number of floating-point
numbers as parameters along with a count, and returns the
average of the numbers:
.millust begin
#include <stdarg.h>

extern double Average( int count, ... )
/*************************************/
{
    double  sum = 0;
    int     i;
    va_list parminfo;

    if( count == 0 ) {
        return( 0.0 );
    }
    va_start( parminfo, count );
    for( i = 0; i < count; i++ ) {
        sum += va_arg( parminfo, double );
    }
    va_end( parminfo );
    return( sum / count );
}
.millust end
.endlevel
.*
.section The Parameters to the Function main
.*
.pp
The function
.ix 'function' 'main'
.ix 'main'
.ix 'entry point'
.ix 'main' 'parameters to'
.mono main
has a special meaning in C.
It is the function that receives control
when a program is started.
The function
.mono main
has the following definition:
.millust begin
extern int main( int argc, char * argv[] )
/****************************************/
{
    :ITAL.statements:eITAL.
}
.millust end
.pc
The objects
.ix argc
.ix 'parameter' 'to main' 'argc'
.mono argc
and
.ix argv
.ix 'parameter' 'to main' 'argv'
.mono argv
have the following properties:
.begbull
.bull
.mono argc
is the "argument count", or the number of parameters
(including program name)
supplied to the program, and its value is greater than zero,
.bull
.mono argv
is an array of pointers to strings containing the parameters,
.bull
.mono argv[0]
is the program name, if available, otherwise it is a pointer to
a string containing only the null character,
.bull
.mono argv[argc]
is a null pointer,
representing the end of the argument list,
.bull
.mono argv[1]
through
.mono argv[argc-1]
are pointers to strings representing the arguments to the program.
These strings are modifiable by the program, and exist throughout
the execution of the program.
The strings will generally be in mixed (upper and lower)
case, although a system that
cannot provide mixed case argument strings will provide them in
lower case.
.endbull
.pc
The translation of the arguments to the program, as
provided by the operating system (often from the command-line used
to invoke the program),
into the strings contained in
.mono argv
..ct ,
is implementation-defined.
.*
.************************************************************************
.*
..if '&target' eq 'PC' or '&target' eq 'PC 370' ..th ..do begin
.shade begin
With &wcboth.,
each unquoted, blank-separated token
on the command line is made into a string that is an element of
.mono argv.
Quoted strings are maintained as one element without the quotes.
.pp
For example, the command line,
.millust pgm 2+ 1 tokens "one token"
will result in
.mono argc
having the value 5, and the elements of
.mono argv
being the strings
.mono "pgm"
..ct ,
.mono "2+"
..ct ,
.mono "1"
..ct ,
.mono "tokens"
and
.mono "one token".
.shade end
..do end
..if '&target' eq 'PC 370' ..th ..do begin
.shade begin
With &wlooc., there are different ways in which command-line
parameters may be passed to the function
.mono main.
See the &userguide. for full details.
.shade end
..do end
.*
.************************************************************************
.*
.pp
The function
.mono main
may also be declared without any parameters, as,
.millust begin
extern int main( void )
/*********************/
{
    statements
}
.millust end
.pp
The return value of
.mono main
is an integer, usually representing a
.ix 'termination status'
.ix 'main' 'return value'
termination
status.
If no return value is specified (by using a
.kw return
statement with no expression or encountering the closing brace in the
function),
then the value returned is undefined.
.pp
The
.libfn exit
library function may be used to terminate the program at any point.
The value of the argument to
.libfn exit
is returned as if
.mono main
had returned the value.