# 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

`optstring` | String that represents the option characters being accepted.

## 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