NOM¶
getopt - Analyser des options de lignes de commandes (version
améliorée)
SYNOPSIS¶
getopt chaîne_options paramètres
getopt [
options] [
--]
chaîne_options
paramètres
getopt [
options]
-o|
--options
chaîne_options [
options] [
--]
paramètres
DESCRIPTION¶
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ètre est constitué des options qui
modifient la façon dont
getopt fera l'analyse (les
options et
chaîne_options dans le
SYNOPSIS) et les
paramètres à analyser (
paramètres dans le
SYNOPSIS). Le second type de paramètre commence dès le
premier paramètre qui n'est 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 d’options courtes.
Si la variable d'environnement
GETOPT_COMPATIBLE est positionnée,
ou si le premier
paramètre n'est pas une option
(c'est-à-dire ne commence 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 (consultez 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). Cela 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
- Permettre aux options longues de ne commencer que par un seul
« - ».
- -h, --help
- Afficher un texte d’aide puis quitter. Rien d'autre ne sera
affiché.
- -l, --longoptions options_longues
- Les options longues (plusieurs caractères) à
reconnaître. Plusieurs noms d'option 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
(consultez la section MODES D'ANALYSE pour plus de
précisions).
- -q, --quiet
- Désactiver le signalement des erreurs par getopt(3).
- -Q, --quiet-output
- Ne pas produire la sortie normale. Les erreurs sont toujours
remontées par getopt(3), sauf si l'option -q est
utilisée.
- -s, --shell shell
- Définir les règles de protection (avec des guillemets)
à celles des interpréteurs de commandes shell. En
absence d’indication de l’option -s, les conventions
de BASH sont utilisées. Les valeurs acceptées
sont « sh »,
« bash », «
csh » et «
tcsh ».
- -u, --unquoted
- Ne pas placer la sortie entre guillemets. Remarquez 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
- Vérifier si la 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
- Afficher le numéro de version puis quitter. Aucune autre sortie
n'est créée.
ANALYSE¶
Cette section indique le format de la seconde partie des paramètres de
getopt (
paramètres 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 (consultez
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 un 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 d'indiquer 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 espace). 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 ; c'est un bogue mineur, consultez 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 des options.
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 indiqués en entrée, à
l'exception des paramètres n'étant pas des options. La sortie
peut être faite dans un mode
compatible (
non
protégé : sans guillemet) ou de telle sorte que les
espaces ou autres caractères spéciaux des paramètres
soient préservés (consultez
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 protégé parce que
les éléments peuvent être coupés à des
endroits non prévus s'ils contiennent des espaces ou caractères
spéciaux.
En cas de problème lors de l'analyse des paramètres, par exemple
si un paramètre obligatoire n'est pas trouvé ou si une option
n'est pas reconnue, une erreur est renvoyée sur la sortie d'erreur
standard. Les éléments incriminés ne seront pas
affiché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 options 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 indiqué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 comme un paramètre
distinct. Si le premier caractère de la chaîne des options
courtes 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 encore généré, mais il sera
toujours 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 de 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 ». D'habitude,
cependant, aucune 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 réussite lors
de l'analyse des options,
1 si
getopt(3) signale des erreurs,
2 s'il ne comprend pas ses propres paramètres,
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 des paramètres n'étant pas
des options, qu'ils commencent par un «
- » ou non.
- GETOPT_COMPATIBLE
- Force getopt à utiliser le premier format d'appel, comme
indiqué 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
VOIR AUSSI¶
getopt(3),
bash(1),
tcsh(1).
DISPONIBILITɶ
La commande
getopt fait partie du paquet util-linux, elle est disponible
sur
l’archive
du noyau Linux
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.