.\"
.\" Translated 13 Jul 1998 by Juan José López Mellado (laveneno@hotmail.com)
.\"
.TH GETOPT 1 "31 Mayo 1997" Linux ""
.SH NOMBRE
getopt \- analiza una línea de comandos (mejorado)
.SH SINOPSIS
.BR getopt " optstring parameters"

.BR getopt " [options] [" -- "] optstring parameters"

.BR getopt " [options] " -o | --options " optstring [options] [" -- "] parameters"
.SH DESCRIPCIÓN
.B getopt
se usa para partir
.RI ( analizar )
las opciones de las líneas de comandos para un fácil análisis
por parte de los procedimientos del shell, y para 
identificar las opciones legales.
Usa las rutinas
.BR getopt (3) 
de
.SM GNU
para hacerlo.

Los parámetros con los que se llama a
.B getopt
se pueden dividir en dos partes: opciones
que modifican la manera en la que getopt analizará
.RI ( options
y
.I -o|--options optstring
en la 
.BR SINOPSIS), 
y los parámetros que deben ser analizados
.RI ( parameters
en la
.BR SINOPSIS).

La segunda parte comenzará en el primer parámetro que no sea
una opción, o después de la primera aparición de
.RB ` -- '.
Si las opciones
.RB ` -o ' 
o
.RB ` --options ' 
no se encuentran en la primera parte, el primer parámetro
de la segunda parte se interpreta como la cadena de opciones cortas.

Si la variable de entorno
.B GETOPT_COMPATIBLE
está definida, o si su primer parámetro no es una opción
(no comienza por un
.RB ` - ',
entonces se toma el primer formato descrito en la
.BR SINOPSIS),
.B getopt
generará una salida compatible con esta u otras versiones de
.BR getopt (1).
Todavía se realizará el reordenamiento de parámetros y el reconocimiento
de argumentos opcionales
(ver la sección
.B COMPATIBILIDADES
para más información).

Las implementaciones tradicionales de
.BR getopt (1)
son incapaces de soportar los espacios en blanco y otros caracteres
especiales (específicos del shell) en argumentos y
parámetros libres. Para resolver este problema, esta
implementación puede generar salida entrecomillada
(
.B N. del T. 
quoted ) que puede ser, a su vez, tratada por el shell 
(típicamente usando el comando
.B eval
). Esto tiene el efecto de preservar dichos caracteres, pero debe
llamarse a
.B getopt
de una manera no compatible con otras versiones (el segundo y tercer
formato en la
.BR SINOPSIS). 
Para determinar cuando esta versión mejorada de
.BR getopt (1)
está instalada, puede usarse la opción
.RB ( -T ) 
que realiza dicha prueba.
.SH OPCIONES
.IP "-a, --alternative"
Permitir que las opciones largas comiencen con un solo
.RB ` - '.
.IP "-h, --help"
Genera como salida una guia de uso y termina correctamente. No se genera
ninguna otra salida.
.IP "-l, --longoptions longopts"
Las opciones largas (más de un carácter) para ser analizadas.
Pueden especificarse más de una opción al mismo tiempo, separándolas
con comas. Esta opción puede darse más de una vez, ya que
.I longopts 
es acumulativa.
Cada nombre de opción larga en
.I longopts 
puede ir secundado por dos puntos (:) para indicar que es un argumento
requerido, y por doble dos puntos (::) para indicar que es un argumento
opcional. 
.IP "-n, --name progname"
El nombre que será usado por las rutinas
.BR getopt (3)
cuando generen algún error. Nótese que los errores de
.BR getopt (1)
son todavía generados tal y como se obtienen de getopt.
.IP "-o, --options shortopts"
Las opciones cortas (un solo carácter) para ser analizadas. Si esta opción
no se encuentra, el primer parámetro de
.B getopt 
que no comience por un
.RB ` - ' 
(y no sea un argumento opcional) es usado como la cadena de opciones cortas.
Cada carácter de una opción corta en
.I shortopts 
puede ir secundada por dos puntos (:) para indicar que es un argumento
requerido, y por doble dos puntos (::) para indicar que es un argumento
opcional.
El primer carácter de shortopts puede ser
.RB ` + ' 
o
.RB ` - ' 
para influenciar sobre la manera en que las opciones son pasadas
y la salida es generada (ver la sección
.B "MODOS DE EXPLORACIÓN"
para más detalles).
.IP "-q, --quiet"
Deshabilita la salida de errores por parte de getopt(3).
.IP "-Q, --quiet-output"
No genera la salida normal. 
.BR getopt (3)
sigue generando errores a menos que no se use
.IR -q .
.IP "-s, --shell shell"
Establece las convenciones de entrecomillado para cada tipo de
shell. Si el argumento -s no se encuentra, se
utilizan las convenciones de
.SM BASH
. Actualmente los argumentos válidos son
.RB ` sh '
.RB ` bash ',
.RB ` csh ',
y
.RB ` tcsh '.
.IP "-u, --unquoted"
No produce salida entrecomillada. Nótese que los espacios en blanco y los
caracteres especiales (dependientes del shell) pueden
causar estragos en este modo (tal y como se producen en otras 
implementaciones de
.BR getopt (1)
).
.IP "-T --test"
Prueba si su
.BR getopt (1) 
es esta versión mejorada o una versión antigua. No genera ningún tipo de
salida y devuelve un código de error 4. Otras implementaciones de
.BR getopt (1),
y esta versión si la variable de entorno
.B GETOPT_COMPATIBLE
está definida,
retornan
.RB ` -- ' 
y un código de error 0.
.IP "-V, --version"
Genera información sobre la versión y finaliza satisfactoriamente. No se
genera ninguna otra salida.

.SH ANÁLISIS
Esta sección especifica el formato de la segunda parte de los parámetros de
.B getopt
(los
.I parameters
en la
.BR SINOPSIS ). 
La siguiente sección
.RB ( SALIDA ) 
describe la salida que se genera. Estos parámetros serán los que típicamente
se usen al llamar a un programa del shell.
Debe tenerse cuidado de que cada parámetro con el que se llamó
al fichero de comandos del shell
corresponda exactamente con un parámetro de la
lista de parámetros de
.B getopt 
(véase los
.BR EJEMPLOS ). 
Todo el análisis es llevado a cabo por las rutinas
.BR getopt (3) 
de GNU. 

Los parámetros son pasados de izquierda a derecha. Cada parámetro es
clasificado como una opción corta, una opción larga, un argumento de una
opción, o un parámetro libre.

Una opción corta es un
.RB ` - ' 
seguido por un carácter de una opción corta. Si la opción tiene un argumento
requerido, deberá aparecer justo después del carácter de la opción o como
el siguiente parámetro (por ejemplo, separados por espacios en blanco en la
línea de comandos). Si la opción tiene un argumento opcional, deberá aparecer
justo después del carácter de la opción si es que existe.

Es posible especificar varias opciones cortas después de un
.RB ` - ', 
siempre y cuando todas (exceptuando posiblemente la última) no necesite
argumentos requeridos o opcionales.

Una opción larga normalmente comienza por
.RB ` -- ' 
seguido por el nombre de la opción.Si la opción tiene un argumento requerido,
 deberá aparecer justo después del nombre de la opción, separado por un
.RB ` = ', 
o como el siguiente argumento (por ejemplo separado por espacios en blanco
en la línea de comandos).Si la opción tiene un argumento opcional, deberá 
aparecer justo después del nombre de la opción, separado por
.RB ` = ', 
si es que existe, (si se añade el
.RB ` = ' 
pero nada detrás de el, se interpretará como si no existiera ningún
argumento; este es un ligero fallo, véase la sección
.BR FALLOS ).
Las opciones largas pueden ser abreviadas, siempre y cuando la abreviación
no sea ambigua.

Cualquier parámetro que no comience por un
.RB ` - ', 
y no sea un argumento requerido de una opción previa, será interpretado como un
parámetro libre. Cualquier parámetro después de un
.RB ` -- ' 
aislado será interpretado como un parámetro libre.

Si la variable de entorno
.B POSIXLY_CORRECT 
está definida, o si el carácter de una opción corta comienza por un
.RB ` + ', 
los restantes parámetros son interpretados como parámetros libres tan pronto
como sea encontrado el primero de los parámetros libres.

.SH SALIDA
Se genera una salida por cada elemento descrito en la sección anterior.
Se realiza en el mismo orden en el que los elementos son especificados en
la entrada, exceptuando los parámetros libres.
La salida puede generarse en modo
.I compatible 
.RI "( sin entrecomillado )"
, o en un modo en el que los espacios en blanco y otros caracteres especiales
entre argumentos y parámetros libres son preservados (véase
.BR ENTRECOMILLADO ).
Cuando la salida es procesada en un fichero de comandos del shell ,
aparecerá compuesta por distintos elementos que pueden ser tratados
uno a uno (usando el comando shift existente el la mayoría de los lenguajes
de shell). Esto no funciona completamente en el modo
sin entrecomillado, ya que los elementos pueden ser divididos por lugares
inesperados si contienen espacios en blanco o caracteres especiales.

Si hay problemas durante el análisis de los parámetros, por ejemplo como
consecuencia de no encontrar un argumento requerido o de una opción no
reconocida, se generará un error en stderr, no aparecerá en la salida
el elemento en discordia, y se devolverá un código de error diferente de cero.

Para una opción corta, la salida consta de un simple
.RB ` - ' 
y el carácter de la opción. Si la opción tiene un argumento, el siguiente
parámetro se tomará como el argumento. Si la  opción necesita de un argumento
opcional, pero no se ha encontrado ninguno, el siguiente parámetro se generará
pero se encontrará vacío en el formato entrecomillado, y no se generará ese
segundo parámetro en el formato no entrecomillado (compatible).
Nótese que la mayoría de las otras implementaciones de
.BR getopt (1) 
no soportan argumentos opcionales.

Si se especificaran más de una opción después de un 
.RB ` - ', 
cada una se presentaría en la salida como un parámetro independiente.

Para una opción larga, se generará el
.RB ` -- ' 
y el nombre completo de la opción como un único parámetro. Esto se hace
indistintamente de que la opción estuviera abreviada o fuera especificada
con un
.RB ` - ' 
en la entrada. Los argumentos se manejan como con las opciones cortas.

Normalmente, la salida de los parámetros libres no se generará hasta que todas
las opciones y sus argumentos hayan sido generadas. Entonces se generará un
.RB ` -- ' 
como si fuera un solo parámetro , y después los parámetros libres en el orden
en que se encontraron, cada uno como un parámetro independiente.
Solo si el primer carácter de la cadena de opciones cortas fuera un solo
.RB ` - ',
la salida de los parámetros libres se generaría en el lugar en que fueron
encontrados en la entrada (esto no está soportado si se usa el primer formato
que aparece en la
.B SINOPSIS
; en este caso todas las ocurrencias anteriores de
.RB ` - '
y 
.RB ` + '
son ignoradas).

.SH "ENTRECOMILLADO (QUOTING)"
En el modo compatible, los espacios en blanco o caracteres `especiales' en los
argumentos o parámetros libres no son tratados correctamente. Dado que la
salida alimenta al fichero de comandos del shell, este programa no
sabe como se supone que la entrada es troceada en los diferentes parámetros.
Para solventar el problema, esta implementación ofrece el entrecomillado. La
idea es que la salida es generada con comillas encerrando a cada parámetro.
Cuando esta salida alimenta al shell (típicamente por el
comando
.B eval 
del intérprete), se particiona correctamente en los diferentes parámetros.

El entrecomillado no se encontrará activado si la variable de entorno
.B GETOPT_COMPATIBLE
está definida, si se usa la primera forma de la
.B SINOPSIS
, o si la opción
.RB ` -u '
es encontrada.

Cada tipo de shell usa convenciones de entrecomillado diferentes.
Pero puede usarse la opción
.RB ` -s '
para seleccionar el shell que esté usando. Actualmente son soportados
los siguientes:
.RB ` sh ',
.RB ` bash ',
.RB ` csh ' 
y
.RB ` tcsh '.
Actualmente, solo se distinguen dos `tipos': las convenciones de
entrecomillado del tipo sh y las del tipo csh. Probablemente si
usa algún otro lenguaje de shell, uno de estos dos
tipos pueda servirle.

.SH "MODOS DE EXPLORACIÓN"
El primer carácter de la cadena de opciones cortas debe ser un
.RB ` - '
o un
.RB ` + '
para indicar el modo de exploración especial. Si se una la primera
forma que aparece en la
.B SINOPSIS 
son ignoradas; aun así, la variable de entorno
.B POSIXLY_CORRECT
es examinada, téngase en cuenta.

Si el primer carácter es
.RB ` + ',
o si la variable de entorno
.B POSIXLY_CORRECT
está definida, el análisis finaliza tan pronto como en primer parámetro
libre (por ejemplo un parámetro que no comience por un
.RB ` - ')
es encontrado y no es un argumento de alguna opción. Los restantes parámetros
son interpretados como parámetros libres.

Si el primer carácter es un 
.RB ` - ',
la salida de los parámetros libres se realiza en el orden en que son
encontrados; en el modo normal, se agrupan al final de la salida
después de generar un parámetro consistente en un único
.RB ` -- '. 
Nótese que este parámetro 
.RB ` -- '
se genera igualmente, pero siempre será
el último parámetro en este modo de exploración.

.SH COMPATIBILIDADES
Esta versión de
.BR getopt (1)
ha sido escrita para ser tan compatible como sea posible con otras
versiones. Normalmente solo debe reemplazar aquellas por esta nueva
versión sin ningún otro cambio, y con algunas ventajas.

Si el primer carácter del primer parámetro de getopt no es un
.RB ` - ', 
getopt entra en el modo compatible. Entonces su primer parámetro será
interpretado como la cadena de opciones cortas, y los restantes
argumentos serán analizados. Sigue manteniéndose el reordenamiento
de parámetros (por ejemplo los parámetros libres aparecen al final
de la salida), a menos que la variable
.B POSIXLY_CORRECT 
esté definida.

La variable de entorno
.B GETOPT_COMPATIBLE 
fuerza a
.B getopt
a entrar en el modo compatible. Definiendo al mismo tiempo esta variable
de entorno y
.B POSIXLY_CORRECT
se ofrece una compatibilidad al 100% para programas `problemáticos'.
Aunque normalmente no es necesario.

En el modo compatible, los primeros caracteres
.RB ` - '
y
.RB ` + '
en la cadena de opciones cortas son ignorados.

.SH VALOR DEVUELTO
.B getopt
devuelve un código de error
.B 0 
si el análisis ha sido satisfactorio,
.B 1
si
.BR getopt (3)
retorna errores,
.B 2 
si no es capaz de entender sus propios parámetros,
.B 3
si un error interno ha ocurrido (como falta de memoria), y
.B 4
si es llamado con
.BR -T .

.SH EJEMPLOS
Se ofrecen programas de ejemplo para (ba)sh y (t)csh con la
distribución de
.BR getopt (1)
, y se encontrarán instalados opcionalmente en
.B /usr/local/lib/getopt 
o 
.BR /usr/lib/getopt .

.SH ENTORNO
.IP POSIXLY_CORRECT
Esta variable de entorno es examinada por las rutinas de
.BR getopt (3)
.Si está definida, el análisis finaliza tan pronto como se encuentre
un parámetro que no es una opción o un argumento de una opción. Los
restantes parámetros son interpretados como parámetros libres,
aunque comiencen por un
.RB ` - '.
.IP GETOPT_COMPATIBLE
Fuerza a
.B getopt
a usar el primer formato de llamada tal y como se especifica en la
.BR SINOPSIS .

.SH FALLOS
.BR getopt (3)
puede analizar opciones largas con argumentos opcionales dados como un
argumento opcional vacío (pero no puede hacerlo con opciones cortas).
Este
.BR getopt (1)
trata a los argumentos opcionales vacíos como si no estuvieran presentes.

.SH AUTOR
Frodo Looijaard <frodol@dds.nl>
.SH "VÉASE TAMBIÉN"
.BR getopt (3),
.BR bash (1),
.BR tcsh (1).