.\" (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de) .\" .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies. .\" .\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one .\" .\" Since the Linux kernel and libraries are constantly changing, this .\" manual page may be incorrect or out-of-date. The author(s) assume no .\" responsibility for errors or omissions, or for damages resulting from .\" the use of the information contained herein. The author(s) may not .\" have taken the same level of care in the production of this manual, .\" which is licensed free of charge, as they might when working .\" professionally. .\" .\" Formatted or processed versions of this manual, if unaccompanied by .\" the source, must acknowledge the copyright and authors of this work. .\" License. .\" Modified Sat Jul 24 19:27:50 1993 by Rik Faith (faith@cs.unc.edu) .\" Modified Mon Aug 30 22:02:34 1995 by Jim Van Zandt .\" longindex is a pointer, has_arg can take 3 values, using consistent .\" names for optstring and longindex, "\n" in formats fixed. Documenting .\" opterr and getopt_long_only. Clarified explanations (borrowing heavily .\" from the source code). .\" .\" Modified Mon May 27 21:37:47 1996 by Martin Schulze .\" Translated to German Fri Jan 03 1997 by Patrick Rother .\" .TH GETOPT 3 "31. Dezember 1996" "GNU" "Bibliotheksfunktionen" .SH BEZEICHNUNG getopt \- werte Kommandozeilenoptionen aus .SH ÜBERSICHT .nf .B #include .sp .BI "int getopt(int " argc ", char * const " argv[] "," .BI " const char *" optstring ");" .sp .BI "extern char *" optarg ; .BI "extern int " optind ", " opterr ", " optopt ; .sp .B #define _GNU_SOURCE .B #include .sp .BI "int getopt_long(int " argc ", char * const " argv[] ", .BI " const char *" optstring , .BI " const struct option *" longopts ", int *" longindex ");" .sp .BI "int getopt_long_only(int " argc ", char * const " argv[] ", .BI " const char *" optstring , .BI " const struct option *" longopts ", int *" longindex ");" .fi .SH BESCHREIBUNG Die Funktion .B getopt() wertet die Kommandozeilenoptionen aus. Ihre Argumente .I argc und .I argv sind die Argumentanzahl und das Argumentenfeld wie zur Funktion .B main() bei Programmaufruf übergeben. Ein Element von \fIargv\fP , dass mit `-' beginnt (und nicht exact "-" or "--") ist, ist ein Optionselement. Die Zeichen dieses Elementes (ohne das einleitende `-') sind Optionszeichen. Wenn \fBgetopt()\fP wiederholt aufgerufen wird, gibt sie aufeinanderfolgend jedes der Optionszeichen von jedem Optionselement zurück. .PP Wenn \fBgetopt()\fP ein weiteres Optionszeichen findet, gibt sie dieses Zeichen zurück, wobei die externe Variable \fIoptind\fP und eine statische Variable \fInextchar\fP auf neuen Stand gesetzt werden, so dass der nächste Aufruf von \fBgetopt()\fP die Suche mit dem folgenden Optionszeichen oder \fIargv\fP-Element fortsetzen kann. .PP Wenn es keine weiteren Optionszeichen gibt, gibt \fBgetopt()\fP -1 zurück. Dann ist \fIoptind\fP der Index in \fIargv\fP des ersten \fIargv\fP-Elementes, das keine Option ist. .PP .I 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 \fBgetopt\fP einen Zeiger auf den folgenden Text in dem selben \fIargv\fP-Element oder den Text des folgenden \fIargv\fP-Elementes in .IR optarg platziert. Zwei Doppelpunkte bedeuten, dass diese Option ein optionales Argument nimmt; wenn es Text im aktuellen \fIargv\fP-Element, wird er in \fIoptarg\fP zurückgegeben, anderenfalls wird \fIoptarg\fP auf Null gesetzt. Dieses ist eine GNU-Erweiterung. Wenn .I optstring .B W gefolgt von einem Semikolon enthält, wird .B \-W foo wie .B \-\-foo interpretiert. (Die Option .B \-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 \fBgetopt()\fP den Inhalt von \fIargv\fP beim Durchsuchen, so dass eventuell alle Nichtoptionen am Ende stehen. Zwei andere Modi sind ebenfalls implementiert. Wenn das erste Zeichen von \fIoptstring\fP 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 \fIoptstring\fP ein `-' ist, dann wird jedes Argument von \fIargv\fP, 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 \fIargv\fP-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. .PP Wenn \fBgetopt()\fP ein Optionszeichen nicht erkennt, wird eine Fehlernachricht nach stderr ausgegeben, das Zeichen in \fIoptopt\fP gespeichert und `?' zurückgegeben. Das aufrufende Programm kann die Fehlernachricht verhindern durch setzen von \fIopterr\fP auf 0. .PP Die Funktion .B getopt_long() arbeitet wie .BR getopt() , bis auf dass 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 .B --arg=param oder .BR "--arg param" nehmen. .PP .I longopts ist ein Zeiger auf das ersten Element eines Feldes der Struktur .BR "struct option" , die in .B deklariert ist als .nf .sp .in 10 struct option { .in 14 const char *name; int has_arg; int *flag; int val; .in 10 }; .fi .PP Die Bedeutungen der einzelnen Felder sind: .TP .I name ist der Name der langen Option. .TP .I has_arg ist: \fBno_argument\fP (or 0) wenn die Option kein Argument nimmt, \fBrequired_argument\fP (or 1) wenn die Option ein Argument braucht, oder \fBoptional_argument\fP (or 2) wenn die Option ein optionales Argument nimmt. .TP .I flag gibt an wie Ergebnisse zurückgegeben werden für eine lange Option. Wenn \fIflag\fP \fBNULL\fP ist, dann gibt \fBgetopt_long()\fP \fIval\fP zurück. (Zum Beispiel kann das aufrufende Programm \fIval\fP auf das Zeichen der äquivalenten Kurzoption setzen.) Anderenfalls gibt \fBgetopt_long()\fP 0 zurück, und \fIflag\fP zeigt auf eine Variable, die auf \fIval\fP gesetzt wird, wenn die Option gefunden wird, und die unverändert gelassen wird, wenn die Option nicht gefunden wird. .TP \fIval\fP ist der Wert, der zurückzugeben oder in die Variable zu laden ist, auf die \fIflag\fP zeigt. .PP Das letzte Element des Feldes muss mit Nullen gefüllt werden. .PP Wenn \fIlongindex\fP nicht \fBNULL\fP ist, zeigt er auf eine Variable, welche auf den Index der langen Option relativ zu .IR longopts gesetzt wird. .PP \fBgetopt_long_only()\fP ist wie \fBgetopt_long()\fP, 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. .SH RÜCKGABEWERT Die Funktion .B 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. .PP \fBgetopt_long()\fP und \fBgetopt_long_only()\fP geben auch das Optionszeichen zurück wenn eine kurze Option gefunden wurde. Für eine lange Option geben sie \fIval\fP zurück wenn \fIflag\fP \fBNULL\fP ist, anderenfalls 0. Fehler- und EOF-Rückgaben sind wie bei \fBgetopt()\fP, zusätzlich jedoch `?' für eine unzureichende Übereinstimmung oder einen überzähligen Parameter. .SH UMGEBUNGSVARIABLEN .TP .SM .B POSIXLY_CORRECT Wenn dies gesetzt ist, dann stoppt die Optionsbearbeitung sobald eine Argument auftritt, das keine Option ist. .TP .B __GNU_nonoption_argv_flags_ Diese Variable wurde in .B 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 .B bash 2.01 wieder gelöscht, der Support dafür bleibt jedoch in der GNU libc enthalten. .SH BEISPIEL Das folgende Beispielprogramm veranschaulicht die Benutzung von .BR getopt_long() mit der meisten ihrer Eigenschaften. .nf .sp #include 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 ("\\n"); break; case '0': case '1': case '2': if (digit_optind != 0 && digit_optind != this_option_optind) printf ("digits occur in two different argv-elements.\\n"); digit_optind = this_option_optind; printf ("Option %c\\n", c); break; case 'a': printf ("Option a\\n"); break; case 'b': printf ("Option b\\n"); break; case 'c': printf ("Option c mit Wert `%s'\\n", optarg); break; case 'd': printf ("Option d mit Wert `%s'\\n", optarg); break; case '?': break; default: printf ("?? getopt lieferte Zeichcode 0%o zurück ??\\n", c); } } if (optind < argc) { printf ("Nichtoptionselemente von ARGV: "); while (optind < argc) printf ("%s ", argv[optind++]); printf ("\\n"); } exit (0); } .fi .SH "FEHLER" Die POSIX.2-Spezifikation von .B 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. .SH "KONFORM ZU" .TP \fBgetopt()\fP: POSIX.2, vorausgesetzt, die Umgebungsvariable POSIXLY_CORRECT ist gesetzt. Anderenfalls sind die Elemente von \fIargv\fP nicht wirklich konstant, da wir sie vertauschen. Wir geben im Prototypen vor, sie seien konstant, um kompatibel zu anderen Systemen zu sein.