GETOPT(1)

NUME
getopt - analizează opțiunile de comandă (îmbunătățit)

REZUMAT

getopt optstring parameters

getopt [options] [--] optstring parameters

getopt [options] -o|--options optstring [options] [--] parameters

DESCRIERE

getopt is used to break up (parse) options in command lines for easy parsing by shell procedures, and to check for valid options. It uses the GNU getopt(3) routines to do this.

Parametrii cu care este apelat getopt pot fi împărțiți în două părți: opțiunile care modifică modul în care getopt va efectua analiza ( opțiuni și șir-opțiuni din REZUMAT) și parametrii care trebuie analizați ( parametri din REZUMAT). A doua parte va începe de la primul parametru care nu este un argument de opțiune sau după prima apariție a lui „--”. În cazul în care în prima parte nu se găsește nicio opțiune „-o” sau „--opțiuni”, primul parametru din a doua parte este utilizat ca șir scurt de opțiuni.

Dacă este definită variabila de mediu GETOPT_COMPATIBLE sau dacă primul parametru nu este o opțiune (nu începe cu un „-”, primul format din REZUMAT), getopt va genera o ieșire compatibilă cu cea a altor versiuni ale getopt(1). Acesta va efectua în continuare amestecarea parametrilor și va recunoaște argumentele opționale (a se vedea secțiunea COMPATIBILITATE pentru mai multe informații).

Implementările tradiționale ale getopt(1) nu sunt capabile să facă față spațiilor albe și altor caractere speciale (specifice shell-ului) în argumente și în parametrii non-opțiune. Pentru a rezolva această problemă, această implementare poate genera o ieșire închisă între ghilimele care trebuie din nou interpretată de shell (de obicei prin utilizarea comenzii eval). Acest lucru are ca efect păstrarea acelor caractere, dar trebuie să apelați getopt într-un mod care nu mai este compatibil cu alte versiuni (al doilea sau al treilea format din REZUMAT). Pentru a determina dacă această versiune îmbunătățită a getopt(1) este instalată, se poate utiliza o opțiune specială de testare (-T).

OPȚIUNI

-a, --alternative
    Permite ca opțiunile lungi să înceapă cu o singură „-”.

-l, --longoptions opțiuni-lungi
    Opțiunile lungi (cu mai multe caractere) care trebuie recunoscute. Se pot specifica mai multe nume de opțiuni în același timp, separând numele cu virgule. Această opțiune poate fi dată de mai multe ori, opțiuni-lungi sunt cumulative. Fiecare nume de opțiune lungă din opțiuni-lungi poate fi urmat de două puncte „:” pentru a indica că are un argument obligatoriu și de două puncte duble „::” pentru a indica că are un argument opțional.

-n, --name nume-program
    Numele care va fi utilizat de rutinele getopt(3) atunci când raportează erori. Rețineți că erorile din getopt(1) sunt în continuare raportate ca provenind de la getopt.

-o, --options opțiuni-scurte
    Opțiunile scurte (un caracter) care trebuie recunoscute. Dacă această opțiune nu este găsită, primul parametru din getopt care nu începe cu „-” (și nu este un argument de opțiune) este utilizat ca șir scurt de opțiuni. Fiecare caracter de opțiune scurtă din opțiuni-scurte poate fi urmat de un caracter de două puncte „:” pentru a indica că are un argument obligatoriu și de două puncte duble „::” pentru a indica că are un argument opțional. Primul caracter din opțiunile scurte poate fi „+” sau „-” pentru a influența modul în care sunt analizate opțiunile și în care este generată ieșirea (a se vedea secțiunea MODURI DE SCANARE pentru detalii).

-q, --quiet
    Dezactivează raportarea erorilor de către getopt(3).

-Q, --quiet-output
    Nu generează o ieșire normală. Erorile sunt în continuare raportate de getopt(3), cu excepția cazului în care utilizați și -q.

-s, --shell shell
    Stabilește convențiile de folosire a ghilimelelor la cele din shell. Dacă opțiunea -s nu este furnizată, se utilizează convențiile BASH. Argumentele valide sunt în prezent "sh", "bash", "csh" și "tcsh".

-T, --test
    Testează dacă getopt(1) este această versiune îmbunătățită sau o versiune veche. Acest lucru nu generează niciun rezultat și stabilește starea de eroare la 4. Alte implementări ale getopt(1), precum și această versiune, dacă variabila de mediu GETOPT_COMPATIBLE este definită, vor returna „--” și starea de eroare 0.

-u, --unquoted
    Nu pune rezultatul între ghilimele. Rețineți că spațiile albe și caracterele speciale (care depind de shell) pot provoca haos în acest mod (la fel ca în cazul altor implementări getopt(1)).

-h, --help
    Afișează acest mesaj de ajutor și iese.

-V, --version
    Afișează informațiile despre versiune și iese.

ANALIZAREA

Această secțiune specifică formatul celei de-a doua părți a parametrilor din getopt (parametrii parametrii din REZUMAT). Următoarea secțiune (IEȘIRE) descrie rezultatul generat. Acești parametri erau, de obicei, parametrii cu care a fost apelată o funcție shell. Trebuie avut grijă ca fiecare parametru cu care a fost apelată funcția shell să corespundă exact unui parametru din lista de parametri din getopt (a se vedea EXEMPLE). Toate analizele sunt efectuate de rutinele GNU getopt(3).

Parametrii sunt analizați de la stânga la dreapta. Fiecare parametru este clasificat ca fiind o opțiune scurtă, o opțiune lungă, un argument pentru o opțiune sau un parametru neopțional.

O opțiune scurtă simplă este un caracter „-” urmat de un caracter scurt de opțiune. În cazul în care opțiunea are un argument obligatoriu, acesta poate fi scris direct după caracterul de opțiune sau ca următorul parametru (adică separat de spațiu alb în linia de comandă). În cazul în care opțiunea are un argument opțional, acesta trebuie scris direct după caracterul de opțiune, dacă este prezent.

Este posibil să se precizeze mai multe opțiuni scurte după un "-", atâta timp cât toate (cu excepția, eventual, a ultimei opțiuni) nu au argumente obligatorii sau opționale.

O opțiune lungă începe în mod normal cu „--” urmate de numele opțiunii lungi. În cazul în care opțiunea are un argument obligatoriu, acesta poate fi scris direct după numele lung al opțiunii, separat de „="” sau ca următorul argument (adică separat de spațiu alb în linia de comandă). Dacă opțiunea are un argument opțional, acesta trebuie scris direct după numele lung al opțiunii, separat de „=”, dacă este prezent (dacă adăugați „=”, dar nu adăugați nimic în spatele lui, este interpretat ca și cum nu ar fi prezent niciun argument; aceasta este o mică eroare, a se vedea ERORI). Opțiunile lungi pot fi prescurtate, atâta timp cât abrevierea nu este ambiguă.

Fiecare parametru care nu începe cu „-” și care nu este un argument obligatoriu al unei opțiuni anterioare este un parametru neopțional. Fiecare parametru care urmează după un parametru „--” este întotdeauna interpretat ca un parametru neopțional. În cazul în care este definită variabila de mediu POSIXLY_CORRECT sau în cazul în care șirul scurt de opțiuni a început cu „+”, toți parametrii rămași sunt interpretați ca fiind parametrii neopționalii imediat ce este găsit primul parametru neopțional.

IEȘIRE

Se generează o ieșire pentru fiecare element descris în secțiunea anterioară. Ieșirea se face în aceeași ordine în care sunt specificate elementele la intrare, cu excepția parametrilor neopționali. Ieșirea se poate face în modul compatibil (fără-ghilimele) sau în așa fel încât spațiile albe și alte caractere speciale din argumente și parametrii neopționali să fie păstrate (a se vedea PUNEREA ÎNTRE GHILIMELE). Atunci când ieșirea este procesată în scriptul shell, aceasta va părea compusă din elemente distincte care pot fi procesate una câte una (prin utilizarea comenzii shift în majoritatea limbajelor shell). Acest lucru este imperfect în modul „fără-ghilimele”, deoarece elementele pot fi divizate în locuri neașteptate dacă conțin spații albe sau caractere speciale.

În cazul în care există probleme de analiză a parametrilor, de exemplu, pentru că un argument necesar nu este găsit sau o opțiune nu este recunoscută, se va raporta o eroare la ieșirea de eroare standard, nu va exista nicio ieșire pentru elementul în neregulă și se va returna o stare de eroare diferită de zero.

Pentru o opțiune scurtă, un singur caracter „-” și caracterul opțiunii sunt generate ca un singur parametru. În cazul în care opțiunea are un argument, următorul parametru va fi argumentul. Dacă opțiunea are un argument opțional, dar nu a fost găsit niciunul, următorul parametru va fi generat, dar va fi gol în modul cu ghilimele, dar nu va fi generat un al doilea parametru în modul fără ghilimele (compatibil). Rețineți că multe alte implementări getopt(1) nu acceptă argumente opționale.

În cazul în care mai multe opțiuni scurte au fost specificate după un singur "-", fiecare dintre ele va fi prezentă la ieșire ca un parametru separat.

Pentru o opțiune lungă, "--" și numele complet al opțiunii sunt generate ca un singur parametru. Acest lucru se face indiferent dacă opțiunea a fost prescurtată sau a fost specificată cu un singur "-" la intrare. Argumentele sunt tratate ca în cazul opțiunilor scurte.

În mod normal, nu se generează nicio ieșire din parametrii fără opțiuni până când nu au fost generate toate opțiunile și argumentele acestora. Apoi se generează „--” ca un singur parametru, după care se generează parametrii neopționali în ordinea în care au fost găsiți, fiecare ca un parametru separat. Numai în cazul în care primul caracter al șirului scurt de opțiuni a fost un „-”, se generează ieșirea parametrilor neopționali în locul în care sunt găsiți în intrare (acest lucru nu este acceptat dacă se utilizează primul format al REZUMAT; în acest caz, toate aparițiile anterioare ale lui „-” și „+” sunt ignorate).

PUNEREA ÎNTRE GHILIMELE

În modul de compatibilitate, spațiile albe sau caracterele „speciale” din argumente sau parametrii neopționali nu sunt tratate corect. Pe măsură ce ieșirea este transmisă scriptului shell, scriptul nu știe cum ar trebui să împartă ieșirea în parametri separați. Pentru a ocoli această problemă, această implementare oferă posibilitatea punerii între ghilimele. Ideea este că ieșirea este generată cu ghilimele în jurul fiecărui parametru. Atunci când această ieșire este din nou transmisă către shell (de obicei printr-o comandă eval), ea este împărțită corect în parametri separați.

Punerea între ghilimele nu este activată dacă variabila de mediu GETOPT_COMPATIBLE este definită, dacă se utilizează prima formă a lui din REZUMAT sau dacă se întâlnește opțiunea „-u”.

Diferite shell-uri folosesc convenții de punere între ghilimele (folosire a ghilimelelor) diferite. Puteți utiliza opțiunea „-s” pentru a selecta shell-ul pe care îl utilizați. În prezent, sunt acceptate următoarele shell-uri: „sh”, „bash”, „csh” și „tcsh”. De fapt, se disting doar două „arome”: convenții de punere între ghilimele de tip «sh» și convenții de punere între ghilimele de tip «csh». Există șanse ca, dacă folosiți un alt limbaj de script shell, să puteți folosi în continuare una dintre aceste arome (variante).

MODURI DE SCANARE

Primul caracter al șirului scurt de opțiuni poate fi un „-” sau un „+” pentru a indica un mod special de scanare. În cazul în care se utilizează prima formă de apelare din REZUMAT, acestea sunt ignorate; totuși, variabila de mediu POSIXLY_CORRECT este în continuare examinată.

În cazul în care primul caracter este „+” sau dacă este definită variabila de mediu POSIXLY_CORRECT, analizarea se oprește imediat ce se găsește primul parametru neopțional (adică un parametru care nu începe cu „-”) care nu este un argument opțional. Parametrii rămași sunt interpretați toți ca fiind parametri neopționali.

În cazul în care primul caracter este un „-”, parametrii neopționali sunt lăsați în locul în care sunt găsiți; în mod normal, toți parametrii sunt colectați la sfârșitul ieșirii după ce a fost generat un parametru „--”. Rețineți că acest parametru „--” este în continuare generat, dar va fi întotdeauna ultimul parametru în acest mod.

COMPATIBILITATE

Această versiune a getopt(1) este scrisă pentru a fi cât mai compatibilă cu alte versiuni. De obicei, le puteți înlocui pur și simplu cu această versiune fără modificări și cu unele avantaje.

În cazul în care primul caracter al primului parametru din getopt nu este un „-”, getopt trece în modul de compatibilitate. Acesta va interpreta primul său parametru ca fiind șirul de opțiuni scurte, iar toate celelalte argumente vor fi analizate. Acesta va continua să amestece parametrii (adică toți parametrii care nu sunt opțiuni sunt afișați la sfârșit), cu excepția cazului în care variabila de mediu POSIXLY_CORRECT este definită, caz în care getopt va adăuga automat un „+” înaintea opțiunilor scurte.

Variabila de mediu GETOPT_COMPATIBLE forțează getopt în modul de compatibilitate. Definirea atât a acestei variabile de mediu, cât și a variabilei POSIXLY_CORRECT oferă compatibilitate 100% pentru programele „dificile”. De obicei, însă, niciuna dintre ele nu este necesară.

În modul de compatibilitate, caracterele „-” și „+” din șirul scurt de opțiuni sunt ignorate.

CODURI DE IEȘIRE

getopt returns error code 0 for successful parsing, 1 if getopt(3) returns errors, 2 if it does not understand its own parameters, 3 if an internal error occurs like out-of-memory, and 4 if it is called with -T.

EXEMPLE

Scripturile de exemplu pentru (ba)sh și (t)csh sunt furnizate împreună cu distribuția getopt(1) și sunt instalate în directorul /usr/share/doc/util-linux.

MEDIU

POSIXLY_CORRECT
    Această variabilă de mediu este examinată de rutinele getopt(3). Dacă este definită, analizarea se oprește imediat ce se găsește un parametru care nu este o opțiune sau un argument de opțiune. Toți parametrii rămași sunt, de asemenea, interpretați ca parametri care nu sunt opțiuni, indiferent dacă încep cu "-".

GETOPT_COMPATIBLE
    Forțează getopt să utilizeze primul format de apelare, așa cum este specificat în REZUMAT.

ERORI

getopt(3) can parse long options with optional arguments that are given an empty optional argument (but cannot do this for short options). This getopt(1) treats optional arguments that are empty as if they were not present.

Sintaxa, în cazul în care nu doriți nicio variabilă de opțiune scurtă nu este foarte intuitivă (trebuie să le definiți în mod explicit la șirul gol).

AUTOR

CONSULTAȚI ȘI

bash(1), tcsh(1), getopt(3)

RAPORTAREA ERORILOR

Pentru rapoarte de eroare, folosiți sistemul de urmărire al erorilor la

DISPONIBILITATE

Comanda getopt face parte din pachetul util-linux care poate fi descărcat de la