# OS_GetOpt*

## C Specification

      #include <nitro/os.h>
      int         OS_GetOpt( const char* optstring );
      int         OS_GetOptInd( void );
      const char *OS_GetOptArg( void );
      int         OS_GetOptOpt( void );

## Arguments

optstring | Character string that represents the option string being accepted.

## Return Values

This function returns the command line option data. (See next section.)

## Description

This function analyzes the command line argument data retrieved by `OS_GetArgc()` and/or `OS_GetArgv()` and retrieves any data related to options.

`OS_GetOpt()` views characters included in optstring as option identifiers. Each time this function is called, it reads command line arguments one at a time, reads them in order, and if the corresponding option is present, an option identifier character is used as the return value.

The index value of command line arguments currently read by `OS_GetOpt()` can be retrieved using `OS_GetOptInd()`.

If ":" or "::" are included after the character in optstring, it indicates that option is an argument. Option argument data can be retrieved using `OS_GetOptArg()`.":"indicates that the option argument is mandatory. Also, `"::"` indicates that the option argument may be omitted. If the optional argument is omitted, `OS_GetOptArg()` returns a NULL.

When the command line argument contains an option that is not included in optstring, or when a mandatory option argument indicated by `":"` is not included, `OS_GetOpt()` will return the character code `"?"`. The identifying characters for the options can be retrieved using `OS_GetOptOpt()`.

`OS_GetOpt()` can be set to act one of two ways when it discovers a regular command line argument that is not an option. This behavior switches depending on whether the lead character of optstring is a `"-"` (hyphen) or another character.

If the lead character of optstring is not a hyphen (default), `OS_GetOpt()` returns `-1` when it finds a regular command line argument or no more command line arguments. Argument evaluation ends at this point and arguments are no longer read. `OS_GetOptInd()` returns the index value of the regular argument that appeared first. `OS_GetOptArg()` returns `NULL`. Specify a value between the value returned from `OS_GetOptInd()` and `OS_GetArgc()`-1 to use as an index for `OS_GetArgv()` to enable the application to access command line arguments with the exception of options.

Sample code is shown below.

            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':// An option that requires an argument
    opt_s = OS_GetOptArg();
    break;

    case 's':// An option with which the argument can be omitted
    opt_t = OS_GetOptArg();
    break;

    case '?':// Error operation
    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, `OS_GetOpt()` returns `+1` when a regular command line argument is found. To retrieve this argument value using `OS_GetOptArg()`, applications can handle regular arguments such as the character code `1` option string of `OS_GetOpt()`. Unlike the default operation, investigation of arguments continue, and the return value of `OS_GetOptInd()` varies with the index value of the next argument every time `OS_GetOpt()` is called. If there are no more arguments, reading the arguments progresses and `OS_GetOpt() returns -1`.

Sample code is shown below.

            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':// An option that requires an argument
    opt_s = OS_GetOptArg();
    break;

    case 's':// An option with which the argument can be omitted
    opt_t = OS_GetOptArg();
    break;

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

## See Also

`OS_GetArgc, OS_GetArgv, buryarg tool
`

## Revision History

09/06/2005 Added a description of how to switch behavior of function when evaluating arguments.

08/30/2005 Initial version.