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ètres est constitué des options qui modifient
la façon dont
getopt fera l'analyse (
options et
-o|
--options chaîne_options dans le
SYNOPSIS)
et les paramètres à analyser (
paramètres 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 (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 petit guide d'utilisation puis quitter 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 (consultez
la section MODES D'ANALYSE pour plus de détails).
- -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. 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 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 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 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 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 ; 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 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 indiqués en entrée, à l'exception des
paramètres n'étant pas une option. 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 dans 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 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 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 ». Même si d'habitude 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 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 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 <
frodo@frodo.looijaard.name>
VOIR AUSSI¶
getopt(3),
bash(1),
tcsh(1).
DISPONIBILITɶ
La commande
getopt fait partie du paquet util-linux, elle est disponible
sur <URL:
ftp://ftp.kernel.org/pub/linux/utils/util-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.