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-09-22                                          GETOPT(1)