Manpage  — GETOPT

getopt - werte Kommandozeilenoptionen aus

ÜBERSICHT BESCHREIBUNG RÜCKGABEWERT UMGEBUNGSVARIABLEN BEISPIEL FEHLER KONFORM ZU

#include <unistd.h> 

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

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

#define _GNU_SOURCE 
#include <getopt.h> 

int getopt_long(int argc, char * const argv[]", 
           const char *optstring, 
           const struct option *longopts, int *longindex); 

int getopt_long_only(int argc, char * const argv[]", 
           const char *optstring, 
           const struct option *longopts, int *longindex); 

Die Funktion getopt() wertet die Kommandozeilenoptionen aus. Ihre Argumente argc und argv sind die Argumentanzahl und das Argumentenfeld wie zur Funktion main() bei Programmaufruf übergeben. Ein Element von argv , dass mit `-' beginnt (und nicht exact "-" or "--") ist, ist ein Optionselement. Die Zeichen dieses Elementes (ohne das einleitende `-') sind Optionszeichen. Wenn getopt() wiederholt aufgerufen wird, gibt sie gibt sie aufeinanderfolgend jedes der Optionszeichen von jedem Optionselement zurück.

Wenn getopt() ein weiteres Optionszeichen findet, gibt sie dieses Zeichen zurück, wobei die externe Variable optind und eine statische Variable nextchar auf neuen Stand gesetzt werden, so daß der nächste Aufruf von getopt() die Suche mit dem folgenden Optionszeichen oder argv-Element fortsetzen kann.

Wenn es keine weiteren Optionszeichen gibt, gibt getopt() -1 zurück. Dann ist optind der Index in argv des ersten argv-Elementes, das keine Option ist.

optstring ist ein String, der die gültigen Optionszeichen enthält. Wenn solche ein Zeichen von einem Doppelpunkt gefolgt wird, benötigt diese Option ein Argument, weswegen getopt einen Zeiger auf den folgenden Text in dem selben argv-Element oder den Text des folgenden argv-Elementes in optarg plaziert. Zwei Doppelpunkte bedeuten, daß diese Option ein optionales Argument nimmt; wenn es Text im aktuellen argv-Element, wird er in optarg zurückgegeben, anderenfalls wird optarg auf Null gesetzt. Dieses ist eine GNU-Erweiterung. Wenn optstring W gefolgt von einem Semikolon enthält, wird -W foo wie --foo interpretiert. (Die Option -W ist reserviert von POSIX.2 für die Implementierung von Erweiterungen.) Dieses Verhalten ist eine GNU-Erweiterung, die nicht verfügbar war in Bibliotheken vor GNU libc 2.

Per Vorgabe vertauscht getopt() den Inhalt von argv beim Durchsuchen, so daß eventuell alle Nichtoptionen am Ende stehen. Zwei andere Modi sind ebenfalls implementiert. Wenn das erste Zeichen von optstring ein `+' ist, oder die Umgebungsvariable POSIXLY_CORRECT gesetzt ist, dann stoppt die Optionsbearbeitung sobald ein Argument auftritt, dass keine Option ist. Wenn das erste Zeichen von optstring ein `-' ist, dann wird jedes Argument von argv, dass keine Option ist, behandelt als wenn es Argument einer Option mit dem Zeichencode 1 waere. (Dies wird benutzt von Programmen, die Optionen und andere argv-Elemente in einer Reihenfolge erwarten, und die Wert auf die Reihenfolge der beiden legen.) Das spezielle Argument `--' erzwingt die Beendigung der Suche nach Optionen unabhängig von der Suchmethode.

Wenn getopt() ein Optionszeichen nicht erkennt, wird eine Fehlernachricht nach stderr ausgegeben, das Zeichen in optopt gespeichert und `?' zurückgegeben. Das aufrufende Programm kann die Fehlernachricht verhindern durch setzen von opterr auf 0.

Die Funktion getopt_long() arbeitet wie getopt(), bis auf daß sie auch lange Optionsnamen unterstützt, die mit zwei Minuszeichen beginnen. Lange Optionsnamen dürfen abgekürzt werden, wenn die Abkürzung eindeutig ist, oder exact einer definierten Option entspricht. Eine lange Option darf einen Parameter der Form --arg=param oder --arg param nehmen.

longopts ist ein Zeiger auf das ersten Element eines Feldes der Struktur struct option, die in <getopt.h> deklariert ist als

struct option {
const char *name;
int has_arg;
int *flag;
int val;
};

Die Bedeutungen der einzelnen Felder sind:

name	ist der Name der langen Option.
has_arg
	ist: no_argument (or 0) wenn die Option kein Argument nimmt, required_argument (or 1) wenn die Option ein Argument braucht, oder optional_argument (or 2) wenn die Option ein optionales Argument nimmt.
flag	gibt an wie Ergebnisse zurückgegeben werden für eine lange Option. Wenn flag NULL ist, dann gibt getopt_long() val zurück. (Zum Beispiel kann das aufrufende Programm val auf das Zeichen der äquivalenten Kurzoption setzen.) Anderenfalls gibt getopt_long() 0 zurück, und flag zeigt auf eine Variable, die auf val gesetzt wird, wenn die Option gefunden wird, und die unverändert gelassen wird, wenn die Option nicht gefunden wird.
val	ist der Wert, der zurückzugeben oder in die Variable zu laden ist, auf die flag zeigt.

Das letzte Element des Feldes muss mit Nullen gefüllt werden.

Wenn longindex nicht NULL ist, zeigt er auf eine Variable, welche auf den Index der langen Option relativ zu longopts gesetzt wird.

getopt_long_only() ist wie getopt_long(), jedoch kann `-' genau wie `--' eine lange Option anzeigen. Wenn eine Option, die mit `-' anfängt (,not `--'), zu keiner langen Option passt, jedoch zu einer kurzen Option, so wird sie wie eine kurze Option behandelt.

Die Funktion getopt() gibt das Optionszeichen zurück wenn die Option gefunden wurde, `:' wenn ein Parameter fehlte für eine der Optionen, `?' für ein unbekanntes Optionszeichen, oder -1 für das Ende der Optionsliste.

getopt_long() und getopt_long_only() geben auch das Optionszeichen zurück wenn eine kurze Option gefunden wurde. Für eine lange Option geben sie sie val zurück wenn flag NULL ist, anderenfalls 0. Fehler- und EOF-Rückgaben sind wie bei getopt(), zusätzlich jedoch `?' für eine unzureichende Übereinstimmung oder einen überzähligen Parameter.

POSIXLY_CORRECT	Wenn dies gesetzt ist, dann stoppt die Optionsbearbeitung sobald eine Argument auftritt, das keine Option ist.
_<PID>_GNU_nonoption_argv_flags_
	Diese Variable wurde in bash 2.0 verwendet, um mit der GNU libc zu kommunizieren und ihr mitzuteilen, welche Argumente die Ergebnisse von Wildcard-Expandierungen sind und daher nicht als Optionen verstanden werden sollten. Dieses Verhalten wurde in bash 2.01 wieder gelöscht, der Support dafür bleibt jedoch in der GNU libc enthalten.

Das folgende Beispielprogramm veranschaulicht die Benutzung von getopt_long() mit der meisten ihrer Eigenschaften.

#include <stdio.h>

int
main (argc, argv)
     int argc;
     char **argv;
{
  int c;
  int digit_optind = 0;

  while (1)
    {
      int this_option_optind = optind ? optind : 1;
      int option_index = 0;
      static struct option long_options[] =
      {
        {"add", 1, 0, 0},
        {"append", 0, 0, 0},
        {"delete", 1, 0, 0},
        {"verbose", 0, 0, 0},
        {"create", 1, 0, 'c'},
        {"file", 1, 0, 0},
        {0, 0, 0, 0}
      };

      c = getopt_long (argc, argv, "abc:d:012",
                       long_options, &option_index);
      if (c == -1)
        break;

      switch (c)
        {
        case 0:
          printf ("Option %s", long_options[option_index].name);
          if (optarg)
            printf (" mit Argument %s", optarg);
          printf (" );
          break;

        case '0':
        case '1':
        case '2':
          if (digit_optind != 0 && digit_optind != this_option_optind)
            printf ("digits occur in two different argv-elements. );
          digit_optind = this_option_optind;
          printf ("Option %c , c);
          break;

        case 'a':
          printf ("Option a );
          break;

        case 'b':
          printf ("Option b );
          break;

        case 'c':
          printf ("Option c mit Wert `%s' , optarg);
          break;

        case 'd':
          printf ("Option d mit Wert `%s' , optarg);
          break;

        case '?':
          break;

        default:
          printf ("?? getopt lieferte Zeichcode 0%o zurück ?? , c);
        }
    }

  if (optind < argc)
    {
      printf ("Nichtoptionselemente von ARGV: ");
      while (optind < argc)
      printf ("%s ", argv[optind++]);
      printf (" );
    }

  exit (0);
}

Die POSIX.2-Spezifikation von getopt() enthält einen technischen Fehler, der in der POSIX.2-Interpretation 150 beschrieben wird. Die GNU-Implementierung (und wahrscheinlich auch alle anderen Implementierungen) unterstützen das korrekte Verhalten anstatt des spezifizierten.

getopt():
	POSIX.2, vorausgesetzt, die Umgebungsvariable POSIXLY_CORRECT ist gesetzt. Anderenfalls sind die Elemente von argv nicht wirklich konstant, da wir sie vertauschen. Wir geben im Prototypen vor, sie seien konstant, um kompatibel zu anderen Systemen zu sein.