NOM
getopt - Analyser des options de lignes de commandes (version
améliorée).
SYNOPSIS
getopt chane_options paramtres
getopt [options] [--] chane_options paramtres
getopt [options] -o|--options chane_options [options] [--] paramtres
getopt permet d’analyser les options d’une ligne de commande d’une
façon simple pour des scripts shell et de vérifier les options
autorisées. Les routines GNU getopt(3) sont utilisées pour cela.
Les paramètres fournis à getopt sont de deux types : le premier type de
paramètres est constitué des options qui modifient la façon dont getopt
fera l’analyse (options et -o|--options chane_options dans le
SYNOPSIS). Le second type de paramètres commence dès le premier
paramètre n’étant pas une option ou après la première apparition de
« -- ». Si aucune option « -o » ou « --options » n’est présente dans la
première partie, le premier paramètre de la seconde partie sera utilisé
comme chaîne de description des options courtes.
Si la variable d’environnement GETOPT_COMPATIBLE est positionnée, ou si
son premier paramètre n’est pas une option (c’est-à-dire ne commençant
pas par un « - », le premier format du SYNOPSIS), getopt produira une
sortie compatible avec d’autres versions de getopt(1). Il réorganisera
encore les paramètres et reconnaîtra les paramètres optionnels (voir la
section COMPATIBILITÉ pour plus d’informations).
Les implémentations traditionnelles de getopt(1) ne gèrent pas les
espaces ou autres caractères spéciaux (spécifiques à chaque
interpréteur de commandes) dans les paramètres (options ou non). Pour
résoudre ce problème, cette implémentation peut produire une sortie,
avec guillemets, qui doit être interprétée de nouveau par
l’interpréteur de commandes (en général avec la commande eval). Ceci
permet de préserver ces caractères, mais vous devez appeler getopt
d’une façon non compatible avec les autres versions (la deuxième ou
troisième forme dans le SYNOPSIS). Pour déterminer si cette version
améliorée de getopt(1) est installée, vous pouvez utiliser l’option
spéciale de test (-T).
OPTIONS
-a, --alternative
Permet aux options longues de ne commencer que par un seul
« - ».
-h, --help
Affiche un petit guide d’utilisation puis quitte sans erreur.
Rien d’autre ne sera affiché.
-l, --longoptions options longues
Les options longues (plusieurs caractères) à reconnaître.
Plusieurs noms d’options peuvent être fournis en une seule fois,
en séparant les noms par des virgules. Cette option peut être
fournie plusieurs fois, les options_longues se cumulent. Chaque
nom d’option dans options_longues peut être suivi d’un
deux-points pour indiquer que l’option attend un paramètre, et
par deux signes deux-points pour indiquer qu’elle a un paramètre
optionnel.
-n, --name nom-de-programme
Le nom qui sera utilisé par getopt(3) pour signaler les erreurs.
Notez que les erreurs de getopt(1) sont signalées comme
provenant de getopt.
-o, --options options courtes
Les options courtes (un seul caractère) à reconnaître. Si cette
option n’est pas trouvée, le premier paramètre de getopt qui ne
commence pas par un « - » (et qui n’est pas un paramètre d’une
option) est utilisé comme chaîne de description des options
courtes. Chaque caractère d’option courte de options_courtes
peut être suivi d’un signe deux-points pour indiquer que
l’option attend un paramètre ou de deux signes deux-points pour
indiquer qu’elle a un paramètre optionnel. Le premier caractère
de options_courtes peut être un « + » ou un « - » pour modifier
la façon dont les options sont analysées et dont la sortie est
produite (voir la section MODES D’ANALYSE pour plus de détails).
-q, --quiet
Désactive le signalement des erreurs par getopt(3).
-Q, --quiet-output
Ne génère pas la sortie normale. Les erreurs sont toujours
remontées par getopt(3), à moins que vous n’utilisiez l’option
-q.
-s, --shell shell
Fixe les règles de protection (avec des guillemets) à celles des
interpréteurs de commandes. En l’absence de paramètre pour -s,
les conventions de BASH sont utilisées. Les valeurs acceptées
sont « sh », « bash », « csh » et « tcsh ».
-u, --unquoted
Ne place pas la sortie entre guillemets. Notez que les espaces
et caractères spéciaux (pour l’interpréteur de commandes
utilisé) peuvent poser des problèmes dans ce mode (comme pour
les autres implémentations de getopt(1)).
-T, --test
Teste si votre version de getopt(1) correspond à cette version
améliorée ou à une version plus ancienne. Aucune sortie n’est
créée et la valeur de retour est 4. Les autres implémentations
de getopt(1) (ou celle-ci si la variable d’environnement
GETOPT_COMPATIBLE est positionnée) renverront « -- », avec une
valeur de retour de 0.
-V, --version
Affiche le numéro de version puis quitte. Aucune autre sortie
n’est créée.
ANALYSE
Cette section spécifie le format de la seconde partie des paramètres de
getopt (paramtres dans le SYNOPSIS). La section suivante (SORTIE)
décrit la sortie renvoyée. Ces paramètres sont généralement ceux
fournis à une fonction shell. Il faut faire attention à ce que chaque
paramètre fourni à la fonction corresponde bien à un paramètre de la
liste des paramètres de getopt (voir EXEMPLES). Toutes les analyses
sont faites en utilisant les routines getopt(3).
Les paramètres sont analysés de la gauche vers la droite. Chaque
paramètre est classé en option courte, option longue, argument d’une
option ou paramètre n’étant pas une option.
Une option courte est un « - » suivi par le caractère de l’option. Si
l’option a un paramètre obligatoire, il peut être indiqué juste après
le caractère de l’option ou comme paramètre suivant (c’est-à-dire en
les séparant par une espace). Si l’option a un paramètre optionnel, il
doit être écrit juste après le caractère de l’option (quand le
paramètre est présent).
Il est possible de spécifier plusieurs options courtes après un « - »,
tant que toutes les options (sauf peut-être la dernière) n’ont pas de
paramètre obligatoire ou optionnel.
Une option longue commence normalement par « -- », suivi par le nom de
l’option longue. Si l’option nécessite un paramètre, celui-ci peut être
indiqué juste après le nom de l’option, en insérant le caractère « = »
entre, ou il peut être indiqué dans le paramètre suivant (c’est-à-dire
en le séparant par un blanc). Si l’option a un paramètre optionnel, il
doit être indiqué juste après le nom de l’option, en insérant le
caractère « = » entre, si le paramètre est présent (quand vous ajoutez
le caractère « = » sans rien derrière, c’est comme si le paramètre
n’était pas présent ; ceci est un bogue mineur, voir la section
BOGUES). Les options longues peuvent être abrégées, tant que
l’abréviation n’est pas ambiguë.
Chaque paramètre ne commençant pas par un « - » et n’étant pas un
paramètre obligatoire est un « paramètre n’étant pas une option ».
Chaque paramètre situé après un « -- » est toujours interprété comme un
« paramètre n’étant pas une option ». Si la variable d’environnement
POSIXLY_CORRECT est positionnée, ou si la chaîne des options courtes
commence par un « + », tous les paramètres suivant le premier paramètre
n’étant pas une option sont interprétés comme des paramètres n’étant
pas une option.
SORTIE
La sortie est générée pour chaque élément décrit dans la section
précédente. Elle reprend l’ordre des éléments spécifiés en entrée, à
l’exception des paramètres n’étant pas une option. La sortie peut être
faite dans un mode compatible (non protg : sans guillemet) ou de
telle sorte que les espaces ou autres caractères spéciaux des
paramètres soient préservés (voir PROTECTION). Quand la sortie est
utilisée dans un script shell, elle paraîtra composée d’éléments
distincts qui peuvent être traités un par un (en utilisant la commande
shift de la plupart des langages de script). Ce n’est pas parfait dans
le mode non protg parce que les éléments peuvent être coupés à des
endroits non prévus s’ils contiennent des espaces ou caractères
spéciaux.
S’il y a des problèmes lors de l’analyse des paramètres, par exemple
parce qu’un paramètre obligatoire n’est pas trouvé ou qu’une option
n’est pas reconnue, une erreur est rapportée sur la sortie d’erreur. Il
n’y aura aucune sortie pour les éléments incriminés et un code d’erreur
non nul est renvoyé.
Pour une option courte, un seul « - » et le caractère de l’option sont
générés comme un paramètre. Si l’option est suivie de son paramètre, le
paramètre suivant de la sortie sera le paramètre de l’option. Si
l’option accepte un paramètre optionnel, mais qu’aucun n’a été trouvé,
un paramètre vide sera généré dans le mode protégé, mais aucun dans le
mode non protégé (ou mode compatible). Notez que beaucoup d’autres
implémentations de getopt(1) ne gèrent pas les paramètres optionnels.
Si plusieurs option courtes ont été précisées après un unique « - »,
chacune sera présente dans la sortie dans un paramètre distinct.
Pour une option longue, « -- » et le nom complet de l’option sont
générés en un seul paramètre. C’est le cas que l’option soit abrégée ou
qu’elle soit spécifiée avec un seul « - » dans l’entrée. Les paramètres
sont traités comme pour les options courtes.
Normalement, aucun paramètre n’étant pas une option n’est généré sur la
sortie tant que toutes les options et leurs paramètres n’ont pas été
traités. Ensuite, « -- » est généré séparément comme un paramètre, et
est suivi des paramètres n’étant pas des options, dans l’ordre où ils
ont été trouvés, chacun dans un paramètre distinct. Si le premier
caractère de la chaîne des options courte est un « - », et seulement
dans ce cas, les paramètres n’étant pas des options sont générés quand
ils sont trouvés dans l’entrée (ce n’est pas géré si la première forme
du SYNOPSIS est utilisée ; dans ce cas, les « - » et « + » de tête sont
ignorés).
PROTECTION
Dans le mode compatible, les espaces et caractères spéciaux dans les
paramètres des options ou les paramètres n’étant pas des options ne
sont pas gérés correctement. Comme la sortie est envoyée à un script
shell, le script ne sait pas comment il doit séparer les paramètres.
Pour éviter ce problème, cette implémentation propose un mode protégé.
L’idée est de générer la sortie avec des protections (à l’aide de
guillemets) autour des paramètres. Quand cette sortie est envoyée de
nouveau à un interpréteur de commandes (généralement en utilisant la
commande eval de l’interpréteur), le découpage en paramètres est
correct.
La protection n’est pas activée si la variable d’environnement
GETOPT_COMPATIBLE est positionnée, si la première forme du SYNOPSIS est
utilisée ou si l’option « -u » est trouvée.
Les conventions de protections diffèrent suivant les interpréteurs de
commandes. Vous pouvez préciser l’interpréteur de commandes que vous
utilisez avec l’option « -s ». Les interpréteurs de commandes suivants
sont gérés : « sh », « bash », « csh » et « tcsh ». En fait, seuls deux
types sont différenciés : ceux utilisant les conventions de sh et ceux
utilisant les conventions de csh. Il y a de grandes chances que si vous
utilisez un autre langage de script, il utilise une de ces conventions.
MODES D’ANALYSE
Le premier caractère de la chaîne de description des options courtes
peut être un « - » ou un « + » pour utiliser un mode spécial d’analyse.
Si la première forme du SYNOPSIS est appelée, ils sont ignorés ; mais
la variable d’environnement POSIXLY_CORRECT est toujours examinée.
Si le premier caractère est un « + », ou si la variable d’environnement
POSIXLY_CORRECT est positionnée, l’analyse s’arrête dès qu’un paramètre
n’étant pas une option est rencontré (c’est-à-dire un paramètre qui ne
commence pas par « - »). Aucun des paramètres suivants ne sera
considéré comme une option.
Si le premier caractère est un « - », les paramètres qui ne sont pas
des options sont placés dans la sortie à la position où ils ont été
trouvés ; normalement, ils sont tous placés à la fin de la sortie,
juste après le paramètre « -- » qui a été généré. Notez que dans ce
mode, le paramètre « -- » est toujours généré, mais il sera le dernier
paramètre.
COMPATIBILITÉ
Cette version de getopt(1) a été écrite pour être aussi compatible que
possible avec les autres versions. En général, vous pouvez vous
contenter des les remplacer par cette version sans aucune modification,
avec même certains avantages.
Si le premier caractère du premier paramètre de getopt n’est pas un
« - », getopt passe en mode compatible. Il interprète ce premier
paramètre comme une chaîne de description des options courtes, et tous
les autres paramètres seront analysés. Il réorganisera encore les
paramètres (c’est-à-dire que les paramètres n’étant pas des options
sont placés à la fin), à moins que la variable POSIXLY_CORRECT soit
positionnée.
La variable d’environnement GETOPT_COMPATIBLE force getopt dans un mode
de compatibilité. Avec à la fois cette variable d’environnement et
POSIXLY_CORRECT, il sera 100 % compatible pour les programmes
« difficiles ». Même si d’habitude aucun n’est nécessaire.
Dans ce mode, les « - » ou « + » de tête des options courtes sont
ignorés.
CODES DE RETOUR
Le code de retour de getopt est 0 en cas de succès lors de l’analyse
des options, 1 si getopt(3) signale des erreurs, 2 si ses propres
paramètres ne sont pas compris, 3 dans le cas d’une erreur interne
(comme un manque de mémoire) et 4 lorsque l’option -T est utilisée.
EXEMPLES
Des scripts d’exemple pour (ba)sh et (t)csh sont fournis avec getopt(1)
et installés sous /usr/share/doc/util-linux/examples.
ENVIRONNEMENT
POSIXLY_CORRECT
Cette variable d’environnement est utilisée par getopt(3).
Lorsqu’elle est positionnée, l’analyse s’arrête au premier
paramètre n’étant ni une option ni le paramètre d’une option.
Tous les paramètres restants sont également interprétés comme
paramètre n’étant pas une option, qu’ils commence par un « - »
ou non.
GETOPT_COMPATIBLE
Force getopt à utiliser le premier format d’appel, comme
spécifié dans le SYNOPSIS.
BOGUES
getopt(3) peut analyser des options longues avec des paramètres
optionnels vides (ce n’est pas possible pour les options courtes).
Cette version de getopt(1) traite les arguments optionnels vides comme
s’ils n’étaient pas présents.
La syntaxe n’est pas très intuitive si vous ne voulez pas d’option
courte : vous devez explicitement les définir comme des chaînes vides.
AUTEUR
Frodo Looijaard <frodo@frodo.looijaard.name>
VOIR AUSSI
getopt(3), bash(1), tcsh(1).
DISPONIBILITÉ
La commande getopt fait partie du paquet util-linux-ng, elle est
disponible sur ftp://ftp.kernel.org/pub/linux/utils/util-linux-ng/.
TRADUCTION
Cette traduction est maintenue par les membres de la liste
<debian-l10n-french AT lists DOT debian DOT org>. Veuillez signaler
toute erreur de traduction par un rapport de bogue sur le paquet
manpages-fr-extra.