NAME¶

getargs(), getlargs(), getvargs() - parse arguments until a non-flag is reached

SYNOPSIS¶

#include <schily/getargs.h>

int getargs(pac, pav, fmt, a1, ..., an)

	int *pac;       /* pointer to arg count */

	char *(*pav)[]; /* pointer to address of arg vector */

	char *fmt;      /* format string */

	type *a1;       /* pointer to result 1 (corresponding */

	                /* to the first descriptor in fmt) */

	type *an;       /* pointer to result n (corresponding */

	                /* to the nth descriptor in fmt) */


int getlargs(pac, pav, props, fmt, a1, ..., an)

	int *pac;       /* pointer to arg count */

	char *(*pav)[]; /* pointer to address of arg vector */

	struct ga_props *props; /* control properties */

	char *fmt;      /* format string */

	type *a1;       /* pointer to result 1 (corresponding */

	                /* to the first descriptor in fmt) */

	type *an;       /* pointer to result n (corresponding */

	                /* to the nth descriptor in fmt) */

int getvargs(pac, pav, props, vfmt)

	int *pac;       /* pointer to arg count */

	char *(*pav)[]; /* pointer to address of arg vector */

	struct ga_props *props; /* control properties */

	struct ga_flags *vfmt;  /* array of formats and args */

DESCRIPTION¶

getargs() is part of the advanced option parsing interface together with the getallargs() and getfiles() family.

getargs() looks at each argument that begins with '-', '+', or has an '=' in it and tries to find a matching description in fmt. If a match is found, the corresponding value pointed to by a1 to an is set to the value according to the conversion specification.

If a match is not found, getargs() returns the error code -1 (BADFLAG), with *pav[0] pointing to the bad argument. If an argument that does not begin with '-' or '+' or does not contain an '=' is found, getargs() returns +1 (NOTAFLAG), again with pav[0] pointing to the non-flag argument. If the argument "--" is found, getargs() returns +2 (FLAGDELIM) and pav[0] points to the argument after the argument "--".

getlargs() is similar to getargs() but implements an additional ga_props parameter that must be initialized with getarginit() before it is passed. Instead of using an explicit structure parameter, the special parameter GA_NO_PROPS may be used to enforce default behavior and the special parameter GA_POSIX_PROPS may be used to enforce POSIX compliant behavior.

getvargs() is similar to getlargs() but uses a structure ga_flags instead of a format string and a variable argument list with pointers. The array of structures ga_flags:

struct ga_flags {



   const char  *ga_format; /* Comma separated list for one flag */



   void        *ga_arg;    /* Ptr. to variable to fill for flag */



   getpargfun  ga_funcp;   /* Ptr. for function to call (&/~)   */

};

is terminated by an element with ga_format == NULL. For a ga_format that does not expect a function pointer, ga_funcp is NULL.

With getargs(), each normal format takes one address argument from a1 to an and each function type format takes two address arguments from a1 to an.

In the description, it is assumed that pac = &ac and pav = &av, where ac and av are the two arguments passed to main(). The pointers are necessary so that getargs() can update ac and av as it verifies each argument and reflects the current position back to the user.

The format string is a series of one or more option descriptors. Each option descriptor starts with the option-name which is composed of characters, numbers, the underscore character `-', minus or plus, which must match the option parameter on the command line. The plus sign (+) must be escaped via \\ in the format string to distinguish it from the + format character. Each option-name is followed by the optional format descriptor and an optional size modifier.

Legal conversions and their meanings are:

#

Integer

+

Increment sized integer

empty

BOOLean TRUE

%0 .. %9

Set sized integer to value in the range 0..9.

?

Character

*

String

&

Call function

~

Call function for BOOLean flag

The conversion types:

#

Integer conversion

+

Increment integer

%[0-9]

Integer assignment

may have a size modifier:

c or C

The assignment is made to an character sized object.

s or S

The assignment is made to a short int sized object.

empty

i or I

The assignment is made to an int sized object.

l or L

The assignment is made to a long int sized object.

ll or LL

The assignment is made to a long long int sized object.

Flag (option) descriptors are separated by a ',' (without whitespace) in the format string. They correspond in order to the resultant pointers, a1...an. Note that function type formats take two arguments from resultant pointers, a1...an.

It is an error to expect more than one conversion from a single match (e.g., "x#*" to attempt to get both the numerical value and the actual string for the x flag); a -2 (BADFMT) error will result if this is attempted.

Although flags must appear exactly as they do in the format string, the format string does not contain the leading '-'. If the flag should start with a '+', the '+' needs to be in the format string. If a long flag should start with a '--', and a long flag with a single dash should not be permitted, a single '-' needs to be in front of the flag name in the format string.

Flags, where conversion is to take place, may appear either as:

-fvalue

f=value

f= value

-f=value

-f= value

where f is the matching flag string. No additional effort is required to get these different ways of specifying values.

Long flags, where conversion is to take place, may appear either as:

-flagvalue

--flagvalue

flag=value

flag= value

-flag=value

--flag=value

-flag= value

--flag= value

where flag is the matching flag string. All the above variants are accepted by the function.

For flags of type *, ?, & and #, when the format character is immediately followed by a space or underscore character, the permitted option calling variants are limited:

-

The underscore character enforces that option-name and option-argument need to be written as a single argument. This allows implementing options with optional arguments.

-

The space character enforces that option-name and option-argument need to be written as separate arguments.

RETURNS¶

FLAGDELIM 2

The command line argument "--" stopped flag processing.

NOTAFLAG  1

The argument *pav does not appear to be a flag.

NOARGS    0

All arguments have been successfully examined.

BADFLAG  -1

A bad flag (option) argument was supplied to the program. The argument *pav contains the offending command line argument.

BADFMT  -2

A bad format descriptor string has been detected. This means an error in the calling program, not a user input data error.

General rules for the return code:

> 0

A file type argument was found.

  0

All arguments have been parsed.

< 0

An error occurred or not a file type argument.

Flag and file arg processing should be terminated after getting a return code <= 0.

SEE ALSO¶

getarginit(3), getallargs(3), getargerror(3), getfiles(3), getlallargs(3), getlargs(3), getlfiles(3), getvallargs(3), getvargs(3), getvfiles(3).

NOTES¶

Users might find it surprising that given a format string like "foo*,bar*" and called with the command line "foo= bar=baz" the getargs(3) family of functions will consider "bar=baz" as the argument to the "foo=" flag. Pay special attention to this in shell scripts where e.g. "foo=$bar" will consume the next argument if "$bar" is empty. To avoid this, write foo= "$bar" instead.

getargs() assumes the first argument is at av[0]. Commands are invoked by the system with the command name in av[0] and the first argument in av[1], so they must increment av and decrement ac before calling getargs().

getargs() should only be used when the position of the switches influences how an argument is processed, or when all switches must be before all file type arguments. In other cases, use getallargs().

BUGS¶

None currently known.

Mail bugs and suggestions to schilytools@mlists.in-berlin.de or open a ticket at https://codeberg.org/schilytools/schilytools/issues.

The mailing list archive may be found at:

https://mlists.in-berlin.de/mailman/listinfo/schilytools-mlists.in-berlin.de.

AUTHOR¶

Joerg Schilling and the schilytools project authors.