OS_GetOpt*

Syntax

#include <nitro/os.h>

int         OS_GetOpt( const char* optstring );
int         OS_GetOptInd( void );
const char *OS_GetOptArg( void );
int         OS_GetOptOpt( void );

Arguments

Return Values

This function returns any discovered command-line option data. (See next section.)

Description

Analyzes the command-line argument data obtained by the OS_GetArgc and/or OS_GetArgv functions and extracts any data related to options.

The OS_GetOpt function assumes the characters in the optstring string are option identifiers. Each time this function is called, it reads and evaluates command-line arguments one at a time in order, and if the corresponding option is present, it returns that option's identifier character.

Use the OS_GetOptInd function to retrieve the index value of the command-line argument currently being read by the OS_GetOpt function.

In addition, if one or two colons (: or ::) are appended to the end of the string within optstring, it indicates that the option takes an argument. Option argument data can be obtained using the OS_GetOptArg function.":"indicates that the option argument is mandatory. A double colon (::) indicates that the option argument can be omitted. If the option's argument is omitted, OS_GetOptArg() returns NULL.

If there is an option in command line arguments not included in optstring, and if an option argument required due to the use of a single colon (:) is not present, the OS_GetOpt function returns the question mark (?) character code. In this situation, use the OS_GetOptOpt function to get the original command-line option identifier in question.

The OS_GetOpt function can be set to act in either of two ways when it discovers a regular command-line argument that is not an option. This behavior changes depending on whether the lead character of optstring is a hyphen (-) or some other character.

By default, the lead character of optstring is not a hyphen. In this case, the OS_GetOpt function returns -1 when it finds a regular command-line argument or no more command-line arguments. Argument evaluation ends at this position, and no further arguments are read. The OS_GetOptInd function returns the index value of this first-encountered regular argument. The OS_GetOptArg function returns NULL. By specifying the values in the range between the value returned from OS_GetOptInd and OS_GetArgc()-1 as indices to the OS_GetArgv function, the application can access the set of command-line arguments with options removed.

The following code shows how to do this.

BOOL        opt_b = FALSE;
const char*  opt_s = NULL;
const char*  opt_t = NULL;
int          argc  = OS_GetArgc();
int          c, i;

while ((c = OS_GetOpt("bs:t::")) > 0)
{
        switch (c)
        {
        case 'b': // Switch-type option
                opt_b = TRUE;
                break;

        case 's': // The option requires an argument
                opt_s = OS_GetOptArg();
                break;

        case 't': // The option does not require an argument
                opt_t = OS_GetOptArg();
                break;

        case '?': // Error processing
        default:
                OS_Printf("Error --- option '%c'\n", OS_GetOptOpt());
                break;
        }
}

// Normal command-line argument
for (i = OS_GetOptInd(); i < argc; i ++)
{ 
        OS_Printf("ARG[%d]=%s\n", i, OS_GetArgv(i));
}

If the lead character of optstring is a hyphen (-), the OS_GetOpt function returns +1 when a regular command-line argument is found. Because applications can retrieve this argument value using the OS_GetOptArg function, applications can handle regular arguments as if the OS_GetOpt function had returned the character code 1 option character. Unlike this function's default behavior, the function will continue evaluating arguments after this point, and each time the OS_GetOpt function is called, the OS_GetOptInd function's return value will change to to the index of the next argument. Evaluation will continue until there are no more arguments, at which point the OS_GetOpt function will return -1.

The following code shows how to do this.

BOOL        opt_b = FALSE;
const char*  opt_s = NULL;
const char*  opt_t = NULL;
int          c;

while ((c = OS_GetOpt("-bs:t::")) > 0)
{
        switch (c)
        {
        case 1: // Normal command-line argument
                OS_Printf("ARG=%s\n", OS_GetOptArg());
                break;

        case 'b': // Switch-type option
                opt_b = TRUE;
                break;

        case 's':// The option requires an argument
                opt_s = OS_GetOptArg();
                break;

        case 't':// The option allows the argument to be omitted
                opt_t = OS_GetOptArg();
                break;

        case '?': // Error processing
        default:
                OS_Printf("Error --- option '%c'\n", OS_GetOptOpt());
                break;
        }
}

See Also

OS_GetArgc
OS_GetArgv
buryarg Tool

Revision History

2005/09/06 Added a description of how to switch behavior of the function when evaluating arguments.
2005/08/30 Initial version.

CONFIDENTIAL