GETOPT(3) Manuel du programmeur Linux GETOPT(3)
getopt, getopt_long, getopt_long_only, optarg, optind, opterr, optopt -
Analyser les options de la ligne de commande
#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);
La fonction getopt() analyse les arguments de la ligne de commande. Ses
lments argc et argv correspondent aux nombres et la table d'arguments
qui sont transmis la fonction main() lors du lancement du programme.
Un lment de argv qui commence par - (et qui ne soit pas uniquement
-- ou - ) est considr comme une option. Les caractres la suite du
- initial sont les caractres de l'option. Si getopt() est appele
plusieurs reprises, elle renverra successivement chaque caractre de
chaque option.
La variable optind est l'indice de l'lment suivant analyser dans argv.
Le systme initialise cette valeur 1. L'appelant peut le remettre
1 pour recommencer l'analyse du mme argv ou pour analyser un nouveau
tableau de paramtre.
Si getopt() trouve un autre caractre d'option, elle le renvoie, mettant
jour la variable externe optind et la variable statique nextchar,
ainsi l'appel suivant getopt() peut continuer l'analyse avec le carac-
tre suivant ou l'lment argv.
S'il n'y a plus de caractres d'option, getopt() renvoie -1. Alors,
optind devient l'index du premier lment de argv qui ne soit pas une
option.
optstring est une chane contenant l'ensemble des caractres d'option
autoriss. Si un de ces caractres est suivi par un deux-points ( : ),
l'option ncessite un argument, donc getopt() placera un pointeur sur le
texte suivant dans le mme argv, ou sur le texte de l'lment argv suivant
dans optarg. Un double deux points ( :: ) signifie qu'une option prend
un argument optionnel. S'il existe un texte dans le mme lment de argv
(c'est dire dans le mme mot que l'option elle-mme comme -oarg ) alors
il est renvoy dans optarg, sinon optarg est dfini zro. Il s'agit d'une
extension GNU. Si optstring contient W suivi d'un point-virgule, alors
-W foo est trait comme l'option longue --foo (l'option -W est rserve
par POSIX.2 pour des extensions spcifique l'implmentation). Ce com-
portement, spcifique la version GNU, n'est pas disponible avant la
bibliothque glibc 2.
Par dfaut, getopt() permute les lments de argv au fur et mesure de son
analyse, ainsi tous les arguments ventuels ne constituant pas des
options se trouvent la fin. Deux autres modes sont galement implments:
Si le premier caractre de optstring vaut + , ou si la variable d'envi-
ronnement POSIXLY_CORRECT est valide, alors l'analyse s'arrte aussitt
qu'un argument ne constituant pas une option est rencontr. Si le pre-
mier caractre de optstring vaut - , alors les arguments ne correspon-
dant pas une option sont manipuls comme s'ils taient des arguments
d'une option dont le caractre est le caractre de code 1 (ceci est
utilis par les programmes qui sont conus pour recevoir des options et
d'autres lments de argv dans n'importe quel ordre mais qui prennent en
compte l'ordre de ces deux types). L'argument spcial -- arrte l'anal-
yse des options, quelque soit le mode en cours.
Si getopt() ne reconnat pas un caractre d'option, il affiche un message
d'erreur sur la sortie standard stderr, stocke le caractre dans optopt,
et renvoie ? . Le programme appelant peut empcher l'affichage du mes-
sage d'erreur en positionnant opterr 0.
Si getopt() trouve dans argv un caractre d'option non inclus dans opt-
string, ou s'il manque un argument d'option, la fonction renvoie ? et
affecte la variable externe optopt le caractre d'option courant. Si le
premier caractre de optstring (suivi par + ou -) est un deux points
( : ), alors getopt() renvoie : plutt que ? pour indiquer un argu-
ment d'option manquant. Si une erreur est dtecte, si le premier carac-
tre de optstring n'est pas deux points, et si la variable externe
opterr est non nulle, (non nulle par dfaut), alors getopt() affiche un
message d'erreur.
getopt_long() et getopt_long_only()
La fonction getopt_long() fonctionne comme getopt() sauf qu'elle
accepte galement des noms longs d'option, commenant par deux tirets (si
le programme accepte seulement les options longues, alors optstring
devrait tre spcifie avec une chane vide "" et non avec NULL). Les
noms longs d'option peuvent tre abrgs, si l'abrviation est unique, ou
si elle correspond exactement une option dfinie. Une option longue
peut prendre un argument, de la forme --arg=param ou --arg param.
longopts est un pointeur sur le premier lment d'un tableau de struc-
tures struct option dclares dans <getopt.h> ainsi :
struct option {
const char *name;
int has_arg;
int *flag;
int val;
};
La signification des diffrents champs est la suivante :
name est le nom de l'option longue.
has_arg
vaut : no_argument (ou 0), si l'option ne prend pas d'argument,
required_argument (ou 1) si l'option prend un argument, ou
optional_argument (ou 2) si l'option prend un argument option-
nel.
flag spcifie la manire de renvoyer les rsultats pour une option
longue. Si flag vaut NULL, alors getopt_long() renvoie val (par
exemple, le programme appelant peut remplir val avec le caractre
de l'option courte correspondante). Sinon, getopt_long() renvoie
0, et flag pointe sur une variable dfinie val si l'option est
trouve, mais reste inchang si l'option est absente.
val est la valeur renvoyer, ou charger dans la variable pointe par
flag.
Le dernier lment de la table doit tre rempli avec des zros.
Si longindex n'est pas NULL, il pointe sur une variable qui est dfinie
avec l'index de l'option longue correspondant longopts.
getopt_long_only() fonctionne comme getopt_long(), mais - tout comme
-- peut indiquer une option longue. Si une option commenant par -
(et non -- ) ne correspond pas une option longue, mais correspond
une option courte, elle est analyse en tant qu'option courte.
Si une option a t trouve, alors getopt() renvoie le caractre de
l'option. Si toutes les options de la ligne de commande ont t lues,
alors getopt() renvoie -1. Si getopt() rencontre un caractre d'option
qui n'est pas dans optstring, alors ? est renvoy. Si getopt() rencon-
tre une option avec un argument manquant, alors la valeur renvoye dpend
du premier caractre de optstring : si c'est : , alors ce caractre est
renvoy, sinon ? est renvoy.
getopt_long() et getopt_long_only() renvoient galement le caractre
d'option courte s'ils en trouvent une. Pour les options longues, ils
renvoient val si flag vaut NULL, et 0 sinon. Les erreurs et la fin des
options sont gres comme avec getopt(), en renvoyant de surcrot ? pour
une correspondance ambigu, ou un paramtre en trop.
POSIXLY_CORRECT
Si cette variable est positionne, l'analyse s'arrte ds qu'un
argument ne constituant pas une option est rencontr.
_<PID>_GNU_nonoption_argv_flags_
Cette variable est utilise par bash(1) 2.0 pour communiquer la
glibc les arguments rsultant de l'expansion des caractres
gnriques, et ils ne doivent pas tre considrs comme des options.
Ce comportement a t supprim de bash(1) version 2.01, mais il est
toujours gr par la glibc.
getopt() :
POSIX.2 et POSIX.1-2001, condition que la variable d'environ-
nement POSIXLY_CORRECT soit positionne. Sinon, les lments de
argv ne sont pas vraiment constants puisque l'on peut les per-
muter. On les dclare const dans le prototype pour tre compati-
ble avec d'autres systmes.
L'utilisation de '+' et '-' dans optstring est une extension
GNU.
Sur certaines anciennes implmentations, getopt() tait dclare
dans <stdio.h>. SUSv1 permettait que la dclaration apparaisse
soit dans <unistd.h> ou soit dans <stdio.h>. POSIX.1-2001 marque
l'utilisation de <stdio.h> comme LEGACY. POSIX.1-2001 ne permet
pas que la dclaration soit dans <stdio.h>.
getopt_long() et getopt_long_only() :
Ces fonctions sont des extensions GNU.
Un programme qui analyse plusieurs tableaux de paramtres ou analyse de
nouveau le mme tableau plusieurs fois, et qui veut utiliser les exten-
sion GNU telles que '+' et '-' au dbut de optstring, ou changer la
valeur de POSIXLY_CORRECT entre les analyses, doit rinitialiser
getopt() en remettant optind 0, plutt que la valeur traditionnelle de
1. La remise 0 force l'appel d'une routine d'initialisation interne
qui vrifie POSIXLY_CORRECT et vrifie les extensions GNU dans opt-
string.
Les spcifications POSIX.2 de getopt() contiennent une erreur technique
dcrite dans POSIX.2 interprtation 150. L'implmentation GNU (et proba-
blement toutes les autres) adopte un comportement correct diffrent de
la spcification.
Le programme d'exemple trivial suivant utilise getopt() avec 2
options:-n sans valeur associe et -t val qui ncessite une valeur.
#include <unistd.h>
#include <stdlib.h>
#include <stdio.h>
int
main(int argc, char *argv[])
{
int flags, opt;
int nsecs, tfnd;
nsecs = 0;
tfnd = 0;
flags = 0;
while ((opt = getopt(argc, argv, "nt:")) != -1) {
switch (opt) {
case 'n':
flags = 1;
break;
case 't':
nsecs = atoi(optarg);
tfnd = 1;
break;
default: /* '?' */
fprintf(stderr, "Usage: %s [-t nsecs] [-n] name\n",
argv[0]);
exit(EXIT_FAILURE);
}
}
printf("flags=%d; tfnd=%d; optind=%d\n", flags, tfnd, optind);
if (optind >= argc) {
fprintf(stderr, "Expected argument after options\n");
exit(EXIT_FAILURE);
}
printf("name argument = %s\n", argv[optind]);
/* Other code omitted */
exit(EXIT_SUCCESS);
}
Le programme suivant illustre l'utilisation de getopt_long() avec la
plupart de ses fonctionnalits.
#include <stdio.h> /* for printf */
#include <stdlib.h> /* for exit */
#include <getopt.h>
int
main(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(" with arg %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 with value '%s'\n", optarg);
break;
case 'd':
printf("option d with value '%s'\n", optarg);
break;
case '?':
break;
default:
printf("?? getopt returned character code 0%o ??\n", c);
}
}
if (optind < argc) {
printf("non-option ARGV-elements: ");
while (optind < argc)
printf("%s ", argv[optind++]);
printf("\n");
}
exit(EXIT_SUCCESS);
}
getsubopt(3), feature_test_macros(7)
Cette page fait partie de la publication 3.07 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent tre trouves l'adresse http://www.ker-
nel.org/doc/man-pages/.
Cette page de manuel a t traduite et mise jour par Christophe Blaess
<http://www.blaess.fr/christophe/>; entre 1996 et 2003, puis par Alain
Portal <aportal AT univ-montp2 DOT fr> jusqu'en 2006, et mise disposi-
tion sur http://manpagesfr.free.fr/.
Les mises jour et corrections de la version prsente dans Debian sont
directement gres par Florentin Duneau <fduneau [AT] gmail.com> et l'quipe
francophone de traduction de Debian.
Veuillez signaler toute erreur de traduction en crivant
<debian-l10n-french [AT] lists.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir accs la version anglaise de ce document en
utilisant la commande man -L C <section> <page_de_man> .
GNU 10 juillet 2008 GETOPT(3)