Provided by: manpages-fr-dev_2.64.1-1_all bug

NOM

       getopt,  getopt_long,  getopt_long_only  -  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;

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

DESCRIPTION

       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.

       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
       GNU libc 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.

       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 libc GNU quels arguments  sont
              le  résultat  de  l’expansion  des  caractères génériques, et 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 libc GNU.

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.

              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>.

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[1]);
                   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)

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> ».