Loading

NOM

       getopt, getopt_long, getopt_long_only, optarg, optind, opterr, optopt -
       Analyser les options de la ligne de commande

SYNOPSIS

       #include <unistd.h>

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

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

       #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);

   Exigences de  macros  de  test  de  fonctionnalités  pour  la  glibc  (voir
   feature_test_macros(7)) :

       getopt() : _POSIX_C_SOURCE >= 2 || _XOPEN_SOURCE || _POSIX_SOURCE
       getopt_long(), getopt_long_only() : _GNU_SOURCE

       La fonction getopt() analyse les arguments de la ligne de commande. Ses
       éléments  argc  et  argv  correspondent  aux  nombres  et  à  la  table
       d’arguments qui sont transmis à la fonction main() lors du lancement du
       programme. Un élément de argv qui commence par « - » (et  qui  ne  soit
       pas  uniquement  « -- »  ou  « - ») est considéré comme une option. Les
       caractères à la suite du « - » initial sont les caractères de l’option.
       Si   getopt()   est   appelée   à  plusieurs  reprises,  elle  renverra
       successivement chaque caractère de chaque option.

       La variable optind est l’indice de l’élément suivant  à  analyser  dans
       argv.  Le  système  initialise  cette  valeur  à  1. L’appelant peut le
       remettre à 1 pour recommencer l’analyse du même argv ou  pour  analyser
       un nouveau tableau de paramètre.

       Si  getopt()  trouve  un  autre  caractère  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 caractère suivant ou l’élément argv.

       S’il n’y a plus de caractères d’option,  getopt()  renvoie  -1.  Alors,
       optind  devient  l’index du premier élément de argv qui ne soit pas une
       option.

       optstring est une chaîne contenant l’ensemble des  caractères  d’option
       autorisés.  Si  un  de  ces  caractères  est  suivi  par un deux-points
       (« : »), l’option nécessite  un  argument,  donc  getopt()  placera  un
       pointeur  sur  le  texte  suivant dans le même argv, ou sur le texte de
       l’élément argv suivant dans optarg.  Un  double  deux  points  (« :: »)
       signifie  qu’une  option  prend  un  argument optionnel. S’il existe un
       texte dans le même élément de argv (c’est à dire dans le même  mot  que
       l’option  elle-même  comme « -oarg ») alors il est renvoyé dans optarg,
       sinon optarg est défini à zéro.  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 réservée par POSIX.2  pour
       des   extensions   spécifique  à  l’implémentation).  Ce  comportement,
       spécifique à la version GNU, n’est pas disponible avant la bibliothèque
       glibc 2.

       Par défaut, getopt() permute les éléments 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
       implémentés: Si le premier caractère de optstring vaut « + », ou si  la
       variable  d’environnement  POSIXLY_CORRECT  est valide, alors l’analyse
       s’arrête aussitôt qu’un argument ne  constituant  pas  une  option  est
       rencontré.  Si  le premier caractère de optstring vaut « - », alors les
       arguments ne correspondant pas à une option sont manipulés comme  s’ils
       étaient  des  arguments d’une option dont le caractère est le caractère
       de code 1 (ceci est utilisé par les programmes  qui  sont  conçus  pour
       recevoir  des  options et d’autres éléments de argv dans n’importe quel
       ordre  mais  qui  prennent  en  compte  l’ordre  de  ces  deux  types).
       L’argument spécial « -- » arrête l’analyse des options, quelque soit le
       mode en cours.

       Si getopt() ne reconnaît pas  un  caractère  d’option,  il  affiche  un
       message  d’erreur  sur  la  sortie standard stderr, stocke le caractère
       dans optopt, et renvoie « ? ».  Le  programme  appelant  peut  empêcher
       l’affichage du message d’erreur en positionnant opterr à 0.

       Si  getopt()  trouve  dans  argv  un caractère d’option non inclus dans
       optstring, ou s’il manque un argument  d’option,  la  fonction  renvoie
       « ?»  et  affecte  à  la  variable externe optopt le caractère d’option
       courant. Si le premier caractère de optstring (suivi par « + » ou « -»)
       est  un  deux  points  (« : »), alors getopt() renvoie « : » plutôt que
       « ? » pour indiquer un argument d’option manquant. Si  une  erreur  est
       détectée,  si  le premier caractère de optstring n’est pas deux points,
       et si la variable externe opterr est non nulle, (non nulle par défaut),
       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, commençant par  deux  tirets
       (si le programme accepte seulement les options longues, alors optstring
       devrait être spécifiée avec une chaîne vide « "" » et non  avec  NULL).
       Les  noms  longs  d’option  peuvent  être abrégés, si l’abréviation est
       unique, ou si elle correspond exactement  à  une  option  définie.  Une
       option  longue  peut  prendre  un  argument, de la forme --arg=param ou
       --arg param.

       longopts est un  pointeur  sur  le  premier  élément  d’un  tableau  de
       structures struct option déclarées dans <getopt.h> ainsi :

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

       La signification des différents 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
              optionnel.

       flag   spécifie la manière de renvoyer les résultats  pour  une  option
              longue.  Si flag vaut NULL, alors getopt_long() renvoie val (par
              exemple,  le  programme  appelant  peut  remplir  val  avec   le
              caractère    de    l’option   courte   correspondante).   Sinon,
              getopt_long() renvoie 0, et flag pointe sur une variable définie
              à  val  si l’option est trouvée, mais reste inchangé si l’option
              est absente.

       val    est la valeur à renvoyer, ou à charger dans la variable  pointée
              par flag.

       Le dernier élément de la table doit être rempli avec des zéros.

       Si longindex n’est pas NULL, il pointe sur une variable qui est définie
       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 commençant
       par « - » (et non « -- ») ne correspond pas à une option  longue,  mais
       correspond  à  une  option  courte, elle est analysée en tant qu’option
       courte.

VALEUR RENVOYÉE

       Si une option a été trouvée, alors getopt()  renvoie  le  caractère  de
       l’option.  Si  toutes les options de la ligne de commande ont été lues,
       alors getopt() renvoie -1. Si getopt() rencontre un caractère  d’option
       qui  n’est  pas  dans  optstring,  alors « ? » est renvoyé. Si getopt()
       rencontre une  option  avec  un  argument  manquant,  alors  la  valeur
       renvoyée  dépend  du  premier  caractère de optstring : si c’est « : »,
       alors ce caractère est renvoyé, sinon « ? » est renvoyé.

       getopt_long() et getopt_long_only() renvoient  également  le  caractère
       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 gérées comme avec getopt(), en renvoyant de surcroît « ? »
       pour une correspondance ambiguë, ou un paramètre en trop.

ENVIRONNEMENT

       POSIXLY_CORRECT
              Si cette variable est positionnée, l’analyse s’arrête dès  qu’un
              argument ne constituant pas une option est rencontré.

       _<PID>_GNU_nonoption_argv_flags_
              Cette  variable  est utilisée par bash(1) 2.0 pour communiquer à
              la glibc les arguments résultant de l’expansion  des  caractères
              génériques,  et  ils  ne  doivent  pas être considérés comme des
              options. Ce comportement a été supprimé de bash(1) version 2.01,
              mais il est toujours géré par la glibc.

CONFORMITÉ

       getopt() :
              POSIX.2   et   POSIX.1-2001,   à   condition   que  la  variable
              d’environnement POSIXLY_CORRECT  soit  positionnée.  Sinon,  les
              éléments  de  argv  ne  sont pas vraiment constants puisque l’on
              peut les permuter. On les déclare  «const »  dans  le  prototype
              pour être compatible avec d’autres systèmes.

              L’utilisation  de  '+'  et  '-' dans optstring est une extension
              GNU.

              Sur certaines anciennes implémentations, getopt() était déclarée
              dans  <stdio.h>.  SUSv1 permettait que la déclaration 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 déclaration soit dans <stdio.h>.

       getopt_long() et getopt_long_only() :
              Ces fonctions sont des extensions GNU.

NOTES

       Un programme qui analyse plusieurs tableaux de paramètres ou analyse de
       nouveau  le  même  tableau  plusieurs  fois,  et  qui veut utiliser les
       extension GNU telles que '+' et '-' au début de optstring,  ou  changer
       la  valeur  de  POSIXLY_CORRECT  entre les analyses, doit réinitialiser
       getopt() en remettant optind à 0, plutôt que la  valeur  traditionnelle
       de  1.  La  remise  à  0  force  l’appel d’une routine d’initialisation
       interne qui vérifie POSIXLY_CORRECT  et vérifie les extensions GNU dans
       optstring.

BOGUES

       Les spécifications POSIX.2 de getopt() contiennent une erreur technique
       décrite dans  POSIX.2  interprétation  150.  L’implémentation  GNU  (et
       probablement   toutes   les  autres)  adopte  un  comportement  correct
       différent de la spécification.

EXEMPLE

       Le  programme  d’exemple  trivial  suivant  utilise  getopt()  avec   2
       options:-n sans valeur associée et -t val qui nécessite 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 fonctionnalités.

       #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);
       }

VOIR AUSSI

       getsubopt(3), feature_test_macros(7)

COLOPHON

       Cette page fait partie de  la  publication  3.23  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      être       trouvées       à       l’adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION

       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 à
       disposition sur http://manpagesfr.free.fr/.

       Les mises à jour et corrections de la version présente dans Debian sont
       directement gérées par Florentin Duneau <fduneau@gmail.com> et l’équipe
       francophone de traduction de Debian.

       Veuillez  signaler  toute  erreur   de   traduction   en   écrivant   à
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous pouvez toujours avoir accès à la version anglaise de  ce  document
       en utilisant la commande « man -L C <section> <page_de_man> ».