Provided by: manpages-es_1.55-10_all bug

NOMBRE

       getopt - Analiza las opciones de la línea de órdenes

SINOPSIS

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

DESCRIPCIÓN

       La  función  getopt() analiza los argumentos de la línea de órdenes. Sus argumentos argc y
       argv son el número y el vector de argumentos como los pasados a la función  main()  cuando
       se  ejecuta  el  programa.   Un  elemento  de  argv  que  comience  con  '-' (y que no sea
       exactamente "-" ni "--") es un elemento de opción. Los caracteres de este elemento (aparte
       del  '-'  inicial)  son caracteres de opción. Si getopt() se llama repetidamente, devuelve
       sucesivamente cada uno de los caracteres de opción de cada uno de los elementos de opción.

       Si getopt() encuentra otro carácter de  opción,  lo  devuelve,  actualizando  la  variable
       externa  optind  y  una  variable  estática  nextchar  de forma que la siguiente llamada a
       getopt() pueda seguir la búsqueda en el siguiente carácter de opción o elemento de argv.

       Si no hay más caracteres de opción, getopt() devuelve -1.  Entonces optind es el índice en
       argv del primer elemento de argv que no es una opción.

       optstring es una cadena que contiene los caracteres de opción legítimos. Si un carácter de
       éstos es seguido por el carácter de dos puntos, la opción necesita un argumento, de  forma
       que  getopt coloca un puntero al texto siguiente en el mismo elemento de  argv, o el texto
       del siguiente elemento de argv, en optarg.  Dos caracteres de dos  puntos  significan  que
       una  opción toma un arg. opcional; si hay texto en el elemento de argv actual, se devuelve
       en optarg; si no, optarg se pone a cero.   Lo  siguiente  es  una  extensión  de  GNU.  Si
       optstring  contiene W seguido por un punto y coma, entonces -W foo se trata como la opción
       larga --foo.  (La opción -W está reservada en POSIX.2 para extensiones de implementación).
       Este  comportamiento es una extensión de GNU, no disponible en bibliotecas anteriores a la
       versión 2 de GNU libc.

       Por omisión, getopt() permuta los contenidos de argv cuando lo escudriña, de modo que todo
       lo  que no sea una opción vaya al final. Están implementados otros dos modos de operación.
       Si el primer carácter de optstring  es  '+'  o  está  definida  la  variable  de  ambiente
       POSIXLY_CORRECT, entonces el procesamiento de la opción se para tan pronto se encuentra un
       argumento que no es una opción.  Si el primer carácter de optstring es '-', entonces  cada
       elemento  de argv que no sea una opción se maneja como si fuera el argumento de una opción
       con código de carácter 1. (Esto se usa en  programas  que  fueron  escritos  para  esperar
       opciones  y  otros elementos de argv en cualquier orden y donde importa el ordenamiento de
       ambos).  El argumento especial '--' fuerza que se acabe el rastreo  de  las  opciones  sin
       tenerse en cuenta el modo.

       Si  getopt()  no  reconoce  un  carácter de opción, muestra un mensaje de error en stderr,
       guarda el carácter en optopt, y devuelve '?'. El programa que llama  a  la  función  puede
       evitar el mensaje de error poniendo opterr a 0.

       Si getopt() encuentra un carácter de opción en argv que no estaba incluido en optstring, o
       si detecta que falta un argumento de opción, devuelve `?' y pone en  la  variable  externa
       optopt  el  carácter  de opción real. Si el primer carácter de optstring es un carácter de
       dos puntos (`:'), getopt() devuelve `:' en  lugar  de  `?'   para  indicar  que  falta  un
       argumento  de  opción. Si se detecta un error, y el primer carácter de  optstring no es un
       carácter de dos puntos, y la variable externa opterr es distinta de cero (que es el  valor
       por defecto), getopt() muestra un mensaje de error.

       La  función  getopt_long()  trabaja  como  getopt()  salvo  en que también acepta opciones
       largas, que empiezan por dos guiones.  Los nombres de opción largos pueden  abreviarse  si
       la  abreviatura  es única o si es una concordancia exacta para alguna opción definida. Una
       opción larga puede tomar un parámetro, de la forma --arg=param o --arg param.

       longopts es un puntero al primer elemento de un  vector  de  struct  option  declarado  en
       <getopt.h> como

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

       Los significados de los diferentes campos son:

       name   es el nombre de la opción larga.

       has_arg
              es: no_argument (ó 0) si la opción no toma un argumento, required_argument (ó 1) si
              la opción requiere un argumento, u optional_argument (ó 2) si  la  opción  toma  un
              argumento opcional.

       flag   especifica cómo se devuelven los resultados para una opción larga. Si flag es NULL,
              entonces getopt_long() devuelve val. (Por ejemplo, el programa puede poner val como
              el carácter de opción corta equivalente.) De otro modo, getopt_long() devuelve 0, y
              flag apunta a una variable que se pone a val si la opción se encuentra, pero que se
              deja intacta si la opción no se encuentra.

       val    es el valor a devolver, o a cargar en la variable apuntada por flag.

       El último elemento del vector tiene que ser llenado con ceros.

       Si  longindex  no es NULL, apunta a una variable que toma el valor del índice de la opción
       larga relativa a longopts.

       getopt_long_only() es como getopt_long(), pero tanto `-'  como  `--'  pueden  indicar  una
       opción  larga.  Si  una  opción que empiece por `-' (no `--') no concordara con una opción
       larga, pero sí con una corta, se consideraría como tal.

VALOR DEVUELTO

       La función getopt() devuelve el carácter de la opción si ésta se  ha  encontrado,  ':'  si
       faltaba  un  parámetro  de  alguna  de  las  opciones,  '?'  para  un  carácter  de opción
       desconocida, o -1 si se ha llegado al final de la lista de opciones.

       getopt_long() y getopt_long_only() también devuelven el carácter de la  opción  cuendo  se
       reconoce  una  corta.  Para  una opción larga, devuelven val  si flag es NULL, y 0 en otra
       circunstancia. Las devoluciones de error y -1 son las mismas que para  getopt(),  más  '?'
       indicando una concordancia ambigua o un parámetro extraño.

VARIABLES DE AMBIENTE

       POSIXLY_CORRECT
              Si está definida, entonces el procesamiento de las opciones se para tan pronto como
              se encuentre un argumento que no sea una opción.

       _<PID>_GNU_nonoption_argv_flags_
              Esta variable era utilizada por bash 2.0 para comunicar a GNU libc  qué  argumentos
              eran el resultado de la expansión de comodines y, por tanto, no debían considerarse
              como opciones.  Este comportamiento se eliminó en la versión 2.01 de bash  pero  el
              soporte permanece en GNU libc.

EJEMPLO

       El  siguiente programa de ejemplo ilustra el empleo de getopt_long() con la mayoría de sus
       características.

       #include <stdio.h>     /* para printf */
       #include <stdlib.h>    /* para 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 (0);
       }

FALLOS

       La especificación POSIX.2 de getopt() tiene un error técnico descrito en la Interpretación
       150  de  POSIX.2.  La  implementación  GNU  (y probablemente el resto de implementaciones)
       implementa el comportamiento correcto en lugar del indicado.

CONFORME A

       getopt():
              POSIX.2, supuesto que tengamos definida la variable de entorno POSIXLY_CORRECT.  Si
              no,  los  elementos  de argv no son realmente const, puesto que los permutamos. Los
              ponemos como const en el prototipo para compatibilidad con otros sistemas.