getopt()

Updated: April 19, 2023

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.
argv
The argument array that you want to parse.
optstring
A string of recognized option characters, each of which must be alphanumeric (i.e., a letter or a digit). If a character is followed by a colon (:), the option takes an argument. The optstring can begin with a colon, which affects error handling as described below.

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 character 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 character 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 character 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() function 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.