.\" (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 <jrv@vanzandt.mv.com>
.\"  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 8 May 1998 by Joseph S. Myers (jsm28@cam.ac.uk)
.\" Modified 990715, aeb: changed `EOF' into `-1' since that is what POSIX
.\"  says; moreover, EOF is not defined in <unistd.h>.
.\" Modified 2002-02-16, joey: added information about non-existing
.\"  option character and colon as first option character
.\" Translated into Spanish Wed Jan 28 1998 by Gerardo Aburruzaga
.\" García <gerardo.aburruzaga@uca.es>
.\" Translation revised Tue Aug 18 1998 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Sat Jun 26 1999 by Juan Piernas <piernas@ditec.um.es>
.\" Translation revised Tue Apr 18 2000 by Juan Piernas <piernas@ditec.um.es>
.\" Traducción revisada por Miguel Pérez Ibars <mpi79470@alu.um.es> el 19-marzo-2005
.\"
.TH GETOPT 3  "16 febrero 2002" "GNU" "Manual del Programador de Linux"
.SH NOMBRE
getopt \- Analiza las opciones de la línea de órdenes
.SH SINOPSIS
.nf
.B #include <unistd.h>
.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
.br
.B #include <getopt.h>
.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 DESCRIPCIÓN
La función
.B getopt()
analiza los argumentos de la línea de órdenes. Sus argumentos
.I argc
y
.I argv
son el número y el vector de argumentos como los pasados a la función
.B main()
cuando se ejecuta el programa.
Un elemento de \fIargv\fP 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
\fBgetopt()\fP se llama repetidamente, devuelve sucesivamente cada uno
de los caracteres de opción de cada uno de los elementos de opción.
.PP
Si \fBgetopt()\fP encuentra otro carácter de opción, lo devuelve,
actualizando la variable externa \fIoptind\fP y una variable estática
\fInextchar\fP de forma que la siguiente llamada a \fBgetopt()\fP
pueda seguir la búsqueda en el siguiente carácter de opción o elemento
de \fIargv\fP.
.PP
Si no hay más caracteres de opción, \fBgetopt()\fP devuelve \-1.
Entonces \fIoptind\fP es el índice en \fIargv\fP del primer
elemento de \fIargv\fP que no es una opción.
.PP
.I 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
\fBgetopt\fP coloca un puntero al texto siguiente en el mismo elemento
de  \fIargv\fP, o el texto del siguiente elemento de \fIargv\fP, en
.IR optarg .
Dos caracteres de dos puntos significan que una opción toma un
arg. opcional; si hay texto en el elemento de \fIargv\fP actual, se
devuelve en \fIoptarg\fP; si no, \fIoptarg\fP se pone a cero.
Lo siguiente es una extensión de GNU. Si
.I optstring
contiene
.B W
seguido por un punto y coma, entonces
.B -W foo
se trata como la opción larga
.BR --foo .
(La opción
.B -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.
.PP
Por omisión, \fBgetopt()\fP permuta los contenidos de \fIargv\fP
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 \fIoptstring\fP 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 \fIoptstring\fP es '-', entonces cada
elemento de \fIargv\fP 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 \fIargv\fP 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.
.PP
Si \fBgetopt()\fP no reconoce un carácter de opción, muestra un
mensaje de error en stderr, guarda el carácter en \fIoptopt\fP, y
devuelve '?'. El programa que llama a la función puede evitar el
mensaje de error poniendo \fIopterr\fP a 0.
.PP
Si \fBgetopt()\fP encuentra un carácter de opción en \fIargv\fP que no estaba
incluido en \fIoptstring\fP, o si detecta que falta un argumento de opción,
devuelve `?' y pone en la variable externa \fIoptopt\fP
el carácter de opción real. Si el primer carácter de \fIoptstring\fP
es un carácter de dos puntos (`:'), \fBgetopt()\fP devuelve `:' en lugar de `?'
para indicar que falta un argumento de opción. Si se detecta un error, y
el primer carácter de  \fIoptstring\fP no es un carácter de dos puntos, y
la variable externa \fIopterr\fP es distinta de cero (que es el valor por defecto),
\fBgetopt()\fP muestra un mensaje de error.
.PP
La función
.B getopt_long()
trabaja como
.B 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
.B --arg=param
o
.BR "--arg param" .
.PP
.I longopts
es un puntero al primer elemento de un vector de
.B struct option
declarado en
.B <getopt.h>
como
.nf
.sp
.in 10
struct option {
.in 14
const char *name;
int has_arg;
int *flag;
int val;
.in 10
};
.fi
.PP
Los significados de los diferentes campos son:
.TP
.I name
es el nombre de la opción larga.
.TP
.I has_arg
es:
\fBno_argument\fP (ó 0) si la opción no toma un argumento,
\fBrequired_argument\fP (ó 1) si la opción requiere un argumento, u
\fBoptional_argument\fP (ó 2) si la opción toma un argumento opcional.
.TP
.I flag
especifica cómo se devuelven los resultados para una opción larga. Si
\fIflag\fP es \fBNULL\fP, entonces \fBgetopt_long()\fP devuelve
\fIval\fP. (Por ejemplo, el programa puede poner \fIval\fP como el
carácter de opción corta equivalente.) De otro modo,
\fBgetopt_long()\fP devuelve 0, y \fIflag\fP apunta a una variable que
se pone a \fIval\fP si la opción se encuentra, pero que se deja
intacta si la opción no se encuentra.
.TP
\fIval\fP 
es el valor a devolver, o a cargar en la variable apuntada por \fIflag\fP.
.PP
El último elemento del vector tiene que ser llenado con ceros.
.PP
Si \fIlongindex\fP no es \fBNULL\fP, apunta a una variable que toma el
valor del índice de la opción larga relativa a
.IR longopts .
.PP
\fBgetopt_long_only()\fP es como \fBgetopt_long()\fP, 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.
.SH "VALOR DEVUELTO"
La función
.B 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.
.PP
\fBgetopt_long()\fP y \fBgetopt_long_only()\fP también devuelven el
carácter de la opción cuendo se reconoce una corta. Para una opción
larga, devuelven \fIval\fP  si \fIflag\fP es \fBNULL\fP, y 0 en otra
circunstancia. Las devoluciones de error y \-1 son las mismas que para
\fBgetopt()\fP, más '?' indicando una concordancia ambigua o un
parámetro extraño.
.SH "VARIABLES DE AMBIENTE"
.TP
.SM
.B 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.
.TP
.SM
.B _<PID>_GNU_nonoption_argv_flags_
Esta variable era utilizada por
.B 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
.B bash
pero el soporte permanece en GNU libc.
.SH "EJEMPLO"
El siguiente programa de ejemplo ilustra el empleo
de
.BR getopt_long()
con la mayoría de sus características.
.nf
.sp
#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);
}
.fi
.SH "FALLOS"
La especificación POSIX.2 de
.B 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.
.SH "CONFORME A"
.TP
\fBgetopt()\fP:
POSIX.2, supuesto que tengamos definida la variable de entorno
POSIXLY_CORRECT. Si no, los elementos de \fIargv\fP no son realmente
const, puesto que los permutamos. Los ponemos como const en el
prototipo para compatibilidad con otros sistemas.