Ubuntu Manpage: getopt - analizuje opcje wiersza poleceń (rozszerzone)

Provided by: util-linux-locales_2.41-4ubuntu3_all

NAZWA

       getopt - analizuje opcje wiersza poleceń (rozszerzone)

SKŁADNIA

       getopt łańcuch-opcji parametry

       getopt [opcje] [--] łańcuch-opcji parametry

       getopt [opcje] -o|--options łańcuch-opcji [opcje] [--] parametry

OPIS

getopt służy do rozdzielenia (analizy) opcji w wierszu poleceń, w celu łatwego analizowania przez funkcje
powłoki oraz sprawdzenia poprawności opcji. Program wykorzystuje do tego celu funkcje GNU getopt(3).

Parametry, z którymi wywoływany jest getopt, można podzielić na dwie części: opcje modyfikujące sposób
analizy getopt (opcje i łańcuch-opcji w SKŁADNI) oraz parametry do przeanalizowania (parametry w
SKŁADNI). Druga część rozpoczyna się od pierwszego parametru nieopcyjnego, który nie jest argumentem
opcji lub po pierwszym wystąpieniu "--". Jeśli w pierwszej części nie wystąpi "-o" ani "--options", to
pierwszy parametr drugiej części jest intepretowany jako łańcuch krótkich opcji.

Jeśli ustawiona jest zmienna środowiskowa GETOPT_COMPATIBLE lub gdy pierwszy parametr nie jest opcją (nie
rozpoczyna się od "-", pierwszy format w SKŁADNI), getopt utworzy wyjście kompatybilne z innymi wersjami
getopt(1). Mimo to, zmieniona zostanie kolejność parametrów oraz zostaną rozpoznane argumenty opcjonalne
(więcej informacji w rozdziale KOMPATYBILNOŚĆ).

Tradycyjne implementacje getopt(1) nie radzą sobie z białymi znakami i innymi (zależnymi od powłoki)
znakami specjalnymi w argumentach i parametrach niebędącymi opcjami. Aby rozwiązać ten problem, niniejsza
implementacja potrafi utworzyć wyjście cytowane, które musi być ponownie zinterpretowane przez powłokę
(zwykle poleceniem eval). Dzięki temu wspomniane znaki zostaną zachowane, ale konieczne jest wywołanie
getopt w sposób, który nie będzie kompatybilny z innymi wersjami (drugi lub trzeci format w SKŁADNI). Aby
określić, czy zainstalowano rozszerzoną wersję getopt(1), można skorzystać ze specjalnej opcji testowania
(-T).

OPCJE

-a, --alternative
Pozwala na rozpoczynanie długich opcji pojedynczym "-".

-l, --longoptions długie-opcje
Długie (wieloznakowe) opcje do rozpoznania. Można podać jednocześnie wiele nazw opcji, rozdzielając
je przecinkami. Opcji tej można użyć więcej niż raz, długie-opcje łączą się. Po każdej nazwie opcji w
długich-opcjach można dopisać jeden dwukropek - aby wskazać że jest to argument wymagany albo dwa
dwukropki - oznaczające argument opcjonalny.

-n, --name nazwa-programu
Nazwa, która posłuży funkcjom getopt(3) do zgłaszania błędów. Proszę zauważyć, że błędy samego
getopt(1) są wciąż zgłaszane jako pochodzące z getopt.

-o, --options krótkie-opcje
Krótkie (jednoznakowe) opcje do rozpoznania. Jeśli nie poda się tej opcji, pierwszy parametr getopt
niezaczynający się od "-" (i niebędącym argumentem opcji) służy jako łańcuch krótkich opcji. Po
każdym znaku któtkich opcji w krótkich-opcjach można dopisać jeden dwukropek - aby wskazać że jest to
argument wymagany albo dwa dwukropki - oznaczające argument opcjonalny. Pierwszy znak w
krótkich-opcjach równy "+" lub "-" wpływa na sposób analizy i tworzenia wyjścia (więcej szczegółów w
rozdziale TRYBY SKANOWANIA).

-q, --quiet
Wyłącza zgłaszanie błędów przez getopt(3).

-Q, --quiet-output
Nie tworzy normalnego wyjścia. Błędy są wciąż zgłaszane przez getopt(3), chyba że podano też opcję
-q.

-s, --shell powłoka
Ustawia konwencję cytowania na używaną przez powłokę. Jeśli nie podano opcji -s stosowane są
konwencje powłoki BASH. Prawidłowymi argumentami są obecnie: "sh", "bash", "csh" i "tcsh".

-T, --test
Sprawdza, czy używany program getopt(1) jest opisywaną tu wersją rozszerzoną, czy starą wersją.
Niniejsza wersja nie tworzy wyjścia i ustawia status błędu na 4. Inne implementacje getopt(1) oraz ta
wersja, jeśli ustawiono zmienną środowiskową GETOPT_COMPATIBLE, zwróci "--" i status błędu 0.

-u, --unquoted
Nie używa cytowania w wyjściu. Proszę zauważyć, że białe znaki i znaki specjalne (zależne od powłoki)
mogą spowodować w tym trybie rozgardiasz (podobnie jak dzieje się w innych implementacjach
getopt(1)).

-h, --help
Wyświetla ten tekst i wychodzi.

-V, --version
Wyświetla wersję i wychodzi.

ANALIZOWANIE

Niniejszy rozdział określa format drugiej części parametrów getopt (parametry w SKŁADNI). Kolejny
rozdział (WYJŚCIE) opisuje tworzone wyjście. Parametry te były zwykle parametrami, z którymi wywołano
funkcję powłoki. Należy uważać, aby każdy parametr, z którym wywołano funkcję powłoki, odpowiadał
dokładnie jednemu parametrowi w liście parametrów getopt (zob. PRZYKŁADY). Cała analiza jest dokonywana
przez funkcje getopt(3) GNU.

Parametry są analizowane od lewej do prawej strony. Każdy parametr jest klasyfikowany jako: krótka opcja,
długa opcja, argument do opcji albo parametr niebędący opcją.

Prostą krótką opcją jest "-" po którym następuje znak krótkiej opcji. Jeśli opcja ma wymagany argument,
może być on zapisany bezpośrednio po znaku opcji lub jako następny parametr (tj. rozdzielony białym
znakiem w wierszu polecenia). Jeśli opcja ma argument opcjonalny, jeśli jest obecny, musi być podany
bezpośrednio po znaku opcji (bez odstępu).

Po jednym "-" można podać wiele krótkich opcji, o ile tylko nie mają one argumentów wymaganych lub
opcjonalnych (to ograniczenie nie dotyczy ostatniej opcji).

Długie opcje zaczynają się zwykle od "--", po którym następuje nazwa długiej opcji. Jeśli opcja ma
argument wymagany, może być: zapisany bezpośrednio po nazwie długiej opcji, rozdzielony znakiem '=' albo
być następnym argumentem (tj. rozdzielony białym znakiem w wierszu polecenia). Jeśli opcja ma argument
opcjonalny, jeśli jest obecny, musi być podany tuż po nazwie długiej opcji, rozdzielony od niej znakiem
"=" (jeśli poda się sam znak "=" jest to interpretowane jak gdyby argument nie był obecny; jest to
niewielki błąd, zob. USTERKI). Nazwy długich opcji można skracać, o ile tylko tak skrócona nazwa nie
będzie niejednoznaczna.

Każdy parametr niezaczynający się od "-" oraz niebędący wymaganym argumentem poprzedniej opcji jest
parametrem nieopcyjnym. Każdy parametr po "--" jest zawsze interpretowany jako parametr nieopcyjny. Jeśli
ustawiona jest zmienna środowiskowa POSIXLY_CORRECT lub gdy łańcuch krótkiej opcji zaczyna się znakiem
"+", wszystkie pozostałe parametry są interpretowane jako parametry nieopcyjne po tym, jak zostanie
odnaleziony pierwszy parametr nieopcyjny.

WYJŚCIE

Wyjście tworzone jest dla każdego elementu opisanego w poprzednim rozdziale. Wyjście jest tworzone w tej
samej kolejności jak elementy podane w wejściu, z wyjątkiem parametrów nieopcyjnych. Wyjście może być
tworzone w trybie kompatybilności (niecytowanym) lub w taki sposób, że zachowywane są białe znaki i inne
specjalne znaki wewnętrz argumentów i parametrów nieopcyjnych (zob. CYTOWANIE). Gdy wyjście jest
analizowane w skrypcie powłoki, będzie wyglądało na utworzone z wyraźnie oddzielnych elementów, które
mogą być przetwarzane pojedynczo (w większości języków powłoki za pomocą polecenia shift). Jest to
niedoskonałe w trybie niecytowanym, ponieważ elementy mogą być przełamane w nieoczekiwanych miejscach,
jeśli zawierają białe znaki lub znaki specjalne.

Jeśli przy analizie parametrów wystąpią problemy np. z powodu braku wymaganego argumentu lub
nierozpoznania opcji, na standardowe wyjście błędó zostanie zgłoszony błąd, dla problematycznego elementu
nie zostanie utworzone wyjście, a program zwróci niezerowy status błędu.

W przypadku krótkiej opcji, jako jeden parametr zostanie utworzony pojedynczy "-" wraz ze znakiem opcji.
Jeśli opcja przyjmuje argument opcjonalny, lecz nie zostanie on odnaleziony, w trybie cytowania zostanie
utworzony następny, pusty parametr, natomiast w trybie niecytowanym (kompatybilności) drugi parametr nie
będzie tworzony. Proszę zauważyć, że wiele innych implementacji getopt(1) nie obśługuje argumentów
opcjonalnych.

Jeśli po pojedynczym "-" podano wiele krótkich opcji, każda będzie obecna w wyjściu jako oddzielny
parametr.

W przypadku długiej opcji, jako jeden parametr zostanie utworzone "--" wraz z pełną nazwą opcji. Tak
dzieje się niezależnie od tego, czy użyto skróconej nazwy opcji, albo opcję podano w wejściu z
pojedynczym "-". Argumenty są obsługiwane w taki sam sposób jak w przypadku krótkich opcji.

Zwykle wyjście parametrów nieopcyjnych nie jest tworzone aż do momentu wygenerowania wszystkich opcji i
ich argumentów. Następnie tworzone jest "--"' jako pojedynczy parametr, a po nim następują parametry
nieopcyjne, w kolejności ich odnalezienia, każdy jako oddzielny parametr. Tylko gdy pierwszym znakiem
łańcucha krótkich opcji był "-", wyjście parametrów nieopcyjnych jest tworzone w miejscu jego
odnalezienia na werjściu (nie jest to obsługiwane w pierwszym formacie SKŁADNI; w takim przypadku
wszystkie poprzedzające wystąpienia "-" i "+" są ignorowane).

CYTOWANIE

       W trybie kompatybilności, białe znaki oraz znaki "specjalne" w argumentach lub parametrach nieopcyjnych
       nie są poprawnie obsługiwane. W miarę wysyłania wyjścia do skryptu powłoki, skrypt nie wie w jaki sposób
       ma rozdzielić wyjście na poszczególne parametry. Aby naprawić ten problem, niniejsza implementacja
       oferuje cytowanie. Dzięki temu tworzone wyjście posiada znaki cytowania wokół każdego parametru. Gdy to
       wyjście jest następnie ponownie przesyłane do powłoki (zwykle poleceniem eval powłoki), jest poprawnie
       dzielone na poszczególne parametry.

       Cytowanie nie jest włączane, gdy ustawiona jest zmienna środowiskowa GETOPT_COMPATIBLE, korzysta się z
       pierwszej postaci SKŁADNI lub gdy poda się opcję "-u".

       Różne powłoki korzystają z różnych konwencji cytowania. Opcja "-s" służy do wyboru używanej powłoki.
       Obecnie obsługiwane są następujące powłoki: "sh", "bash", "csh" i "tcsh". W praktyce rozróżniane są
       jedynie dwie odmiany: konwencje cytowania w stylu sh i w stylu csh. Nawet jeśli korzysta się z innego
       języka skryptowego powłoki, prawdopodobnie jedna z tych dwóch konwencji będzie prawidłowa.

TRYBY SKANOWANIA

       Pierwszym znakiem łańcucha krótkich opcji może być "-" lub "+" wskazując specjalny tryb skanowania. Jeśli
       użyta zostanie pierwsza postać SKŁADNI, znaki te są ignorowane, ale wciąż sprawdzana jest zmienna
       środowiskowa POSIXLY_CORRECT.

       Jeśli pierwszym znakiem jest "+" lub ustawiona jest zmienna środowiskowa POSIXLY_CORRECT, analiza
       zatrzymuje się po napotkaniu pierwszego parametru nieopcyjnego (tj. parametru niezaczynającego się od
       "-"), który nie jest argumentem opcji. Pozostałe parametry są interpretowane jako parametry nieopcyjne.

       Jeśli pierwszym znakiem jest "-", parametry nieopcyjne są wypisywane w miejscu ich odnalezienia; w
       zwykłym trybie działania są zbierane na końcu wyjścia, po wygenerowaniu parametru "--". Proszę zauważyć,
       że parametr "--" też jest generowany, ale w opisywanym trybie specjalnym będzie zawsze ostatnim
       parametrem.

ZGODNOŚĆ

       Niniejszą wersję getopt(1) napisano w sposób zachowujący maksymalną kompatybilność z innymi wersjami
       programu. Zwykle można je zastąpić tą wersję bez konieczności dokonywania jakichkolwiek modyfikacji, a
       otrzymując pewne korzyści.

       Jeśli pierwszym znakiem pierwszego parametru getopt nie jest "-", getopt wejdzie w tryb kompatybilności.
       Zinterpretuje swój pierwszy parametr jako łańcuch krótkich opcji, a wszystkie pozostałe argumenty zostaną
       przeanalizowane. Wciąż dokona zmiany kolejności parametrów (tj. wszystkie parametry nieopcyjne są
       wypisywane na końcu), chyba że ustawiona jest zmienna środowiskowa POSIXLY_CORRECT - wówczas getopt
       automatycznie poprzedzi krótkie opcje znakiem "+".

       Zmienna środowiskowa GETOPT_COMPATIBLE zmusza getopt do wejścia w tryb kompatybilności. Jej łącze
       ustawienie ze zmienną środowiskową POSIXLY_CORRECT gwarantuje 100% kompatybilność dla "trudnych"
       programów. Zwykle żadna z nich nie jest jednak konieczna.

       W trybie kompatybilności, początkowe znaki "-" i "+" w łańcuchu krótkich opcji są ignorowane.

KODY ZAKOŃCZENIA

       getopt zwraca kod błędu 0 w przypadku pomyślnej analizy; 1 jeśli getopt(3) zwróci błędy; 2 jeśli nie
       rozpoznaje swoich własnych parametrów; 3 jeśli wystąpi błąd wewnętrzny, taki jak brak pamięci oraz 4 gdy
       zostanie wywołany z opcją -T.

PRZYKŁADY

       Przykładowe skrypty dla powłok (ba)sh i (t)csh są dostarczane razem z programem getopt(1) i instalowane w
       katalogu /usr/share/doc/util-linux.

ŚRODOWISKO

       POSIXLY_CORRECT
           Zmienna sprawdzane przez funkcje getopt(3). Jeśli jest ustawiona, analiza zatrzymuje się po
           napotkaniu parametru niebędącego opcją ani argumentem opcji. Wszystkie pozostałe parametry są również
           interpretowane jako parametry nieopcyjne, niezależnie od tego, czy zaczynają się od znaku "-".

       GETOPT_COMPATIBLE
           Zmusza getopt do użycie pierwszego formatu wywołania opisanego w SKŁADNI.

USTERKI

       getopt(3) potrafi analizować długie opcje z argumentami opcjonalnymi, które są podane jako pusty
       argumenty opcjonalne (lecz nie może tego czynić wobec krótkich opcji). Ten program getopt(1) traktuje
       puste argumenty tak, jakby były nieobecne.

       Składnia nie jest zbyt intuicyjna, gdy nie są potrzebne zmienne z krótkimi opcjami (trzeba je ustawić
       jawnie na pusty łańcuch).

AUTOR

       Frodo Looijaard <frodo@frodo.looijaard.name>

ZOBACZ TAKŻE

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

ZGŁASZANIE BŁĘDÓW

       Problemy należy zgłaszać w systemie śledzenia błędów <https://github.com/util-linux/util-linux/issues>.

DOSTĘPNOŚĆ

       Polecenie getopt jest częścią pakietu util-linux, który można pobrać ze strony Archiwum jądra Linux
       <https://www.kernel.org/pub/linux/utils/util-linux/>.

util-linux 2.41                                    2025-07-02                                          GETOPT(1)