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 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, getopt() returns:

and 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:

See also 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.

Returns:

One of the following:

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 Read the Caveats
Interrupt handler No
Signal handler No
Thread No

Caveats:

A cancellation point may occur when a thread is executing getopt() if the opterr argument is nonzero.