GAGetArgs

Section: C Library Functions (3)
Updated: IRIT Version 6.0
Index Return to Main Contents
 

NAME

GAGetArgs()  

SYNOPSIS

misc_lib/getarg.c:198

int GAGetArgs(int va_alist, ...)
 

DESCRIPTION

Routine to access command line arguments and interpret them, by getting access to the main routine's argc/argv interface and a control string that prescribes the expected options. Returns ARG_OK (0) is case of succesfull parsing, error code else...

Format of CtrlStr format: The control string passed to GAGetArgs controls the way argv (argc) are parsed. Each entry in this string must have no spaces in it. The First Entry is the name of the program which is usually ignored except when GAPrintHowTo is called. All the other entries (except the last one which will be discussed shortly) must have the following format:
 1. One letter which sets the option letter (i.e. 'x' for option '-x').
 2. '!' or '%' to determines if this option is really optional ('%') or it must be provided by the user ('!').
 3. '-' always.
 4. Alpha numeric string, usually ignored, but used by GAPrintHowTo to describe the meaning of this option.
 5. Sequences that start with either '!' or '%'. Again if '!' then this sequence must exists (only if its option flag is given), and if '%' it is optional. Each sequence will be followed by one or two characters which defines the kind of the input:
    5.1. d, x, o, u - integer is expected (decimal, hex, octal base or unsigned).
    5.2. D, X, O, U - long integer is expected (same as above).
    5.3. f          - float number is expected.
    5.4. F          - double number is expected.
    5.5. s          - string is expected.
    5.6. *?    - any number of '?' kind (d, x, o, u, D, X, O, U, f, F, s) will match this one. If '?' is numeric, it scans until none numeric input is given. If '?' is 's' then it scans up to the next option or end of argv.

If the last parameter given in the CtrlStr, is not an option (i.e. the second char is not in ['!', '%'] and the third one is not '-'), all what remained from argv is hooked to it.

The variables passed to GAGetArgs (starting from 4th parameter) MUST match the order of options in the CtrlStr. For each option, an address of an integer must be passed. This integer must initialized by 0. If that option is given in the command line, it will be set to one. Otherwise, this integer will not be affected. In addition, the sequences that might follow an option require the following parameter(s) to be passed
 1. d, x, o, u - pointer to an integer (int *).
 2. D, X, O, U - pointer to a long (long *).
 3. f       - pointer to a float (float *).
 4. F       - pointer to a double (double *).
 5. s       - pointer to a char * (char **). NO pre-allocation is required.
 6. *?      - TWO variables are passed for each such wild character request. The first variable is an address of an integer, and it will return the number of parameters actually hooked to this sequence. The second variable is a pointer to a pointer to type ? (? **). It will return an address of a vector of pointers of type ?, terminated with a NULL pointer. NO pre-allocation is required. These two variables behaves very much like the argv/argc pair and are used the "trap" unused command line options.

Examples:


    "Example1  i%-OneInteger!d  s%-Strings!*s  j%-  k!-Float!f  Files!*s"
 Will match: Example1 -i 77 -s String1 String2 String3 -k 88.2 File1 File2
   or match: Example1 -s String1 -k 88.3 -i 999 -j
    but not: Example1 -i 77 78 (i expects one integer, k must be specified). The option k must exists in the above example and if '-i' is prescribed one integer argument must follow it. In the first example, File1 & File2, will match Files in the control string. The order of the options in the command line is irrelevant. A call to GAPrintHowTo with this CtrlStr will print to stderr:


 Example1 [-i OneIngeter] [-s Strings...] [-j] -k Float Files...

The parameters below are stdarg style and in fact are expecting the following:


   GAGetArgs(argc, argv, CtrlStr, ...);


 1. argc, argv: The usual C interface from the main routine of the program.
 2. CtrlStr:    Defining the types/options to expect in the command line.
 3.  ...:       list of addreses of variables to initialize according to parsed command line.  

PARAMETERS:

va_alist: Do "man stdarg".

 

FUNCTION RETURN VALUE

int: TRUE if command line was valid, FALSE otherwise.

 

ORIGIN

(C) Copyright 1989/90-95 Gershon Elber, Technion, IIT


 

Index

NAME
SYNOPSIS
DESCRIPTION
PARAMETERS:
FUNCTION RETURN VALUE
ORIGIN

This document was created by man2html, using the manual pages.
Time: 07:27:45 GMT, July 20, 2024