[Previous]
[Contents]
[Next]

getopt()

get options from a command line

Synopsis:

#include <unistd.h>
int getopt( int argc, const char *argv[],
            const char *optstring );

extern char *optarg;
extern int optind, opterr, optopt;

Description:

The getopt() function is a command-line parser that can be used by applications that follow guidelines 3,4,5,6,7,9 and 10 in Utility Syntax Guidelines 1003.2 2.10.2. The remaining guidelines are not addressed by getopt(), and are the responsibility of the application.

The parameters argc and argv are the argument count and argument array, respectively, as passed to main(). The argument optstring is a string of recognized option letters; if a letter is followed by a colon, the option takes an argument. All option letters allowed by Utility Syntax Guidelines 1003.2 2.10.2 guideline 3 are allowed in optstring (thus, letters include digits). This implementation of getopt() allows any characters to be used as options letters with the exception of the colon.

The QNX getopt() has a concept of "normal" options versus "extended" options. The presence of two consecutive asterisks (**) in optstring separates the "normal" from the "extended" options. The "**" is otherwise ignored (that is, "*" does not become an option when this is used). getopt() looks for the environment variable POSIX_STRICT. If found, the extended options are disabled.

The variable optind is the index of the next element of the argv[] vector to be processed. The system initializes optind to 0 when the program is loaded, and getopt() updates it when it finishes with each element of argv[] (reset optind to 0 if you want to use getopt() to process additional argument sets - this is a QNX extension).

The getopt() function returns the next option letter from argv that matches a letter in optstring. If the option takes an argument, getopt() sets the variable optarg to point to the option argument as follows:

  1. If the option is the last letter in the string pointed to by an element of argv, then optarg contains the next element of argv, and optind is incremented by 2.
  2. Otherwise, optarg points to the string following the option letter in that element of argv, and optind is incremented by 1.

If, when getopt() is called, argv[optind] is NULL, *argv[optind] is not the character '-', or argv[optind] points to the string "-", getopt() returns -1 without changing optind. If argv[optind] points to the string "--", getopt() returns -1 after incrementing optind.

If getopt() encounters an invalid option, or an option that expects an argument and no argument is found, it writes an error message to standard error, sets the variable optopt to the unknown option letter that caused the error, and returns a question-mark (?). The optind variable is still updated. An application can disable the error message by setting opterr to zero. The variable opterr is initially set to 1 by the system.

Returns:

The next option letter specified on the command line, or -1 when all command-line options have been parsed.

Examples:

#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>

void main( int argc, char *argv[] )
  {
    int c,
    errflag = 0;

    while( ( c = getopt( argc, argv, "abt:**k" ) )
      != -1 ) {
      switch( c ) {
        case 'a': printf( "apples\n" );
                  break;
        case 'b': printf( "bananas\n" );
                  break;
        case 't': printf( "tree = %s\n", optarg );
                  break;
        case 'k': printf( "extended kumquats" );
                  break;
        case '?': ++errflag;
                  break;
      }
    }
  }

Classification:

POSIX 1003.2

Safety:
Interrupt handler No
Signal handler No
Thread No

See also:

print_usage()


[Previous]
[Contents]
[Next]