Caution: This version of this document is no longer maintained. For the latest documentation, see http://www.qnx.com/developers/docs.

getopt()

Parse options from a command line

Synopsis:

#include <unistd.h>

int getopt( int argc,
            char * const argv[],
            const char * optstring );

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

Arguments:

argc
The argument count that was passed to main().
argv
The argument array that was passed to main().
optstring
A string of recognized option letters; if a letter is followed by a colon, the option takes an argument. Valid option characters for optstring consist of a single alphanumeric character (i.e. a letter or digit).

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

The getopt() function is a command-line parser that can be used by applications that follow the Utility Syntax Guidelines described below.

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

The getopt() function returns the next option character from argv that matches a letter in optstring, if there's one that matches. If the option takes an argument, getopt() sets the global 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.

The getopt() function returns -1 is returned and doesn't change optind if:

This function returns -1 after incrementing optind, if:

If getopt() encounters an option character that isn't contained in optstring, it returns the ? character. If it detects a missing option argument, it returns : if the first character of optstring is a colon, or ? otherwise. In both cases, getopt() sets optopt to the option character that caused the error.

The getopt() always prints a diagnostic message to stderr unless opterr is set to 0, or the first character of optstring is a : character.

Utility Syntax Guidelines

The getopt() function may be used by applications that follow these guidelines:

Returns:

The next option character specified on the command line; a colon if a missing argument is detected and the first character of optstring is a colon; a question mark if an option character is encountered that's not in optstring and the first character of optstring isn't a colon; otherwise, -1 when all command line options have been parsed.

Examples:

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

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

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

Classification:

POSIX 1003.1

Safety:
Cancellation point Yes
Interrupt handler No
Signal handler No
Thread No

See also:

getsubopt(), stderr

Guidelines 3,4,5,6,7,9 and 10 in the Base Definitions volume of the IEEE Std.1003.1-2001, Section 12.2, Utility Syntax Guidelines.