'\" t
.\"     Title: getopt
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.23
.\"      Date: 2025-03-29
.\"    Manual: Polecenia użytkownika
.\"    Source: util-linux 2.41
.\"  Language: English
.\"
.TH "GETOPT" "1" "2025-03-29" "util\-linux 2.41" "Polecenia użytkownika"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAZWA"
getopt \- analizuje opcje wiersza poleceń (rozszerzone)
.SH "SKŁADNIA"
.sp
\fBgetopt\fP \fIłańcuch\-opcji\fP \fIparametry\fP
.sp
\fBgetopt\fP [opcje] [\fB\-\-\fP] \fIłańcuch\-opcji\fP \fIparametry\fP
.sp
\fBgetopt\fP [opcje] \fB\-o\fP|\fB\-\-options\fP \fIłańcuch\-opcji\fP [opcje] [\fB\-\-\fP] \fIparametry\fP
.SH "OPIS"
.sp
\fBgetopt\fP służy do rozdzielenia (\fIanalizy\fP) opcji w wierszu poleceń, w celu łatwego analizowania przez funkcje powłoki oraz sprawdzenia poprawności opcji. Program wykorzystuje do tego celu funkcje GNU \fBgetopt\fP(3).
.sp
Parametry, z którymi wywoływany jest \fBgetopt\fP, można podzielić na dwie części: opcje modyfikujące sposób analizy \fBgetopt\fP (\fIopcje\fP i \fIłańcuch\-opcji\fP w \fBSKŁADNI\fP) oraz parametry do przeanalizowania (\fIparametry\fP w \fBSKŁADNI\fP). Druga część rozpoczyna się od pierwszego parametru nieopcyjnego, który nie jest argumentem opcji lub po pierwszym wystąpieniu "\fB\-\-\fP". Jeśli w pierwszej części nie wystąpi "\fB\-o\fP" ani "\fB\-\-options\fP", to pierwszy parametr drugiej części jest intepretowany jako łańcuch krótkich opcji.
.sp
Jeśli ustawiona jest zmienna środowiskowa \fBGETOPT_COMPATIBLE\fP lub gdy pierwszy \fIparametr\fP nie jest opcją (nie rozpoczyna się od "\fB\-\fP", pierwszy format w \fBSKŁADNI\fP), \fBgetopt\fP utworzy wyjście kompatybilne z innymi wersjami \fBgetopt\fP(1). Mimo to, zmieniona zostanie kolejność parametrów oraz zostaną rozpoznane argumenty opcjonalne (więcej informacji w rozdziale \fBKOMPATYBILNOŚĆ\fP).
.sp
Tradycyjne implementacje \fBgetopt\fP(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 \fBeval\fP). Dzięki temu wspomniane znaki zostaną zachowane, ale konieczne jest wywołanie \fBgetopt\fP w sposób, który nie będzie kompatybilny z innymi wersjami (drugi lub trzeci format w \fBSKŁADNI\fP). Aby określić, czy zainstalowano rozszerzoną wersję \fBgetopt\fP(1), można skorzystać ze specjalnej opcji testowania (\fB\-T\fP).
.SH "OPCJE"
.sp
\fB\-a\fP, \fB\-\-alternative\fP
.RS 4
Pozwala na rozpoczynanie długich opcji pojedynczym "\fB\-\fP".
.RE
.sp
\fB\-l\fP, \fB\-\-longoptions\fP \fIdługie\-opcje\fP
.RS 4
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, \fIdługie\-opcje\fP łączą się. Po każdej nazwie opcji w \fIdługich\-opcjach\fP można dopisać jeden dwukropek \- aby wskazać że jest to argument wymagany albo dwa dwukropki \- oznaczające argument opcjonalny.
.RE
.sp
\fB\-n\fP, \fB\-\-name\fP \fInazwa\-programu\fP
.RS 4
Nazwa, która posłuży funkcjom \fBgetopt\fP(3) do zgłaszania błędów. Proszę zauważyć, że błędy samego \fBgetopt\fP(1) są wciąż zgłaszane jako pochodzące z getopt.
.RE
.sp
\fB\-o\fP, \fB\-\-options\fP \fIkrótkie\-opcje\fP
.RS 4
Krótkie (jednoznakowe) opcje do rozpoznania. Jeśli nie poda się tej opcji, pierwszy parametr \fBgetopt\fP niezaczynający się od "\fB\-\fP" (i niebędącym argumentem opcji) służy jako łańcuch krótkich opcji. Po każdym znaku któtkich opcji w \fIkrótkich\-opcjach\fP 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 "\fB+\fP" lub "\fB\-\fP" wpływa na sposób analizy i tworzenia wyjścia (więcej szczegółów w rozdziale \fBTRYBY SKANOWANIA\fP).
.RE
.sp
\fB\-q\fP, \fB\-\-quiet\fP
.RS 4
Wyłącza zgłaszanie błędów przez \fBgetopt\fP(3).
.RE
.sp
\fB\-Q\fP, \fB\-\-quiet\-output\fP
.RS 4
Nie tworzy normalnego wyjścia. Błędy są wciąż zgłaszane przez \fBgetopt\fP(3), chyba że podano też opcję \fB\-q\fP.
.RE
.sp
\fB\-s\fP, \fB\-\-shell\fP \fIpowłoka\fP
.RS 4
Ustawia konwencję cytowania na używaną przez \fIpowłokę\fP. Jeśli nie podano opcji \fB\-s\fP stosowane są konwencje powłoki \fBBASH\fP. Prawidłowymi argumentami są obecnie: "\fBsh\fP", "\fBbash\fP", "\fBcsh\fP" i "\fBtcsh\fP".
.RE
.sp
\fB\-T\fP, \fB\-\-test\fP
.RS 4
Sprawdza, czy używany program \fBgetopt\fP(1) jest opisywaną tu wersją rozszerzoną, czy starą wersją. Niniejsza wersja nie tworzy wyjścia i ustawia status błędu na 4. Inne implementacje \fBgetopt\fP(1) oraz ta wersja, jeśli ustawiono zmienną środowiskową \fBGETOPT_COMPATIBLE\fP, zwróci "\fB\-\-\fP" i status błędu 0.
.RE
.sp
\fB\-u\fP, \fB\-\-unquoted\fP
.RS 4
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 \fBgetopt\fP(1)).
.RE
.sp
\fB\-h\fP, \fB\-\-help\fP
.RS 4
Wyświetla ten tekst i wychodzi.
.RE
.sp
\fB\-V\fP, \fB\-\-version\fP
.RS 4
Wyświetla wersję i wychodzi.
.RE
.SH "ANALIZOWANIE"
.sp
Niniejszy rozdział określa format drugiej części parametrów \fBgetopt\fP (\fIparametry\fP w \fBSKŁADNI\fP). Kolejny rozdział (\fBWYJŚCIE\fP) 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 \fBgetopt\fP (zob. \fBPRZYKŁADY\fP). Cała analiza jest dokonywana przez funkcje \fBgetopt\fP(3) GNU.
.sp
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ą.
.sp
Prostą krótką opcją jest "\fB\-\fP" 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).
.sp
Po jednym "\fB\-\fP" można podać wiele krótkich opcji, o ile tylko nie mają one argumentów wymaganych lub opcjonalnych (to ograniczenie nie dotyczy ostatniej opcji).
.sp
Długie opcje zaczynają się zwykle od "\fB\-\-\fP", 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 \*(Aq\fB=\fP\*(Aq 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 "\fB=\fP" (jeśli poda się sam znak "\fB=\fP" jest to interpretowane jak gdyby argument nie był obecny; jest to niewielki błąd, zob. \fBUSTERKI\fP). Nazwy długich opcji można skracać, o ile tylko tak skrócona nazwa nie będzie niejednoznaczna.
.sp
Każdy parametr niezaczynający się od "\fB\-\fP" oraz niebędący wymaganym argumentem poprzedniej opcji jest parametrem nieopcyjnym. Każdy parametr po "\fB\-\-\fP" jest zawsze interpretowany jako parametr nieopcyjny. Jeśli ustawiona jest zmienna środowiskowa \fBPOSIXLY_CORRECT\fP lub gdy łańcuch krótkiej opcji zaczyna się znakiem "\fB+\fP", wszystkie pozostałe parametry są interpretowane jako parametry nieopcyjne po tym, jak zostanie odnaleziony pierwszy parametr nieopcyjny.
.SH "WYJŚCIE"
.sp
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 \fIkompatybilności\fP (\fIniecytowanym\fP) lub w taki sposób, że zachowywane są białe znaki i inne specjalne znaki wewnętrz argumentów i parametrów nieopcyjnych (zob. \fBCYTOWANIE\fP). 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.
.sp
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.
.sp
W przypadku krótkiej opcji, jako jeden parametr zostanie utworzony pojedynczy "\fB\-\fP" 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 \fBgetopt\fP(1) nie obśługuje argumentów opcjonalnych.
.sp
Jeśli po pojedynczym "\fB\-\fP" podano wiele krótkich opcji, każda będzie obecna w wyjściu jako oddzielny parametr.
.sp
W przypadku długiej opcji, jako jeden parametr zostanie utworzone "\fB\-\-\fP" 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 "\fB\-\fP". Argumenty są obsługiwane w taki sam sposób jak w przypadku krótkich opcji.
.sp
Zwykle wyjście parametrów nieopcyjnych nie jest tworzone aż do momentu wygenerowania wszystkich opcji i ich argumentów. Następnie tworzone jest "\fB\-\-\fP"\*(Aq 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ł "\fB\-\fP", wyjście parametrów nieopcyjnych jest tworzone w miejscu jego odnalezienia na werjściu (nie jest to obsługiwane w pierwszym formacie \fBSKŁADNI\fP; w takim przypadku wszystkie poprzedzające wystąpienia "\fB\-\fP" i "\fB+\fP" są ignorowane).
.SH "CYTOWANIE"
.sp
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 \fBeval\fP powłoki), jest poprawnie dzielone na poszczególne parametry.
.sp
Cytowanie nie jest włączane, gdy ustawiona jest zmienna środowiskowa \fBGETOPT_COMPATIBLE\fP, korzysta się z pierwszej postaci \fBSKŁADNI\fP lub gdy poda się opcję "\fB\-u\fP".
.sp
Różne powłoki korzystają z różnych konwencji cytowania. Opcja "\fB\-s\fP" służy do wyboru używanej powłoki. Obecnie obsługiwane są następujące powłoki: "\fBsh\fP", "\fBbash\fP", "\fBcsh\fP" i "\fBtcsh\fP". 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.
.SH "TRYBY SKANOWANIA"
.sp
Pierwszym znakiem łańcucha krótkich opcji może być "\fB\-\fP" lub "\fB+\fP" wskazując specjalny tryb skanowania. Jeśli użyta zostanie pierwsza postać \fBSKŁADNI\fP, znaki te są ignorowane, ale wciąż sprawdzana jest zmienna środowiskowa \fBPOSIXLY_CORRECT\fP.
.sp
Jeśli pierwszym znakiem jest "\fB+\fP" lub ustawiona jest zmienna środowiskowa \fBPOSIXLY_CORRECT\fP, analiza zatrzymuje się po napotkaniu pierwszego parametru nieopcyjnego (tj. parametru niezaczynającego się od "\fB\-\fP"), który nie jest argumentem opcji. Pozostałe parametry są interpretowane jako parametry nieopcyjne.
.sp
Jeśli pierwszym znakiem jest "\fB\-\fP", parametry nieopcyjne są wypisywane w miejscu ich odnalezienia; w zwykłym trybie działania są zbierane na końcu wyjścia, po wygenerowaniu parametru "\fB\-\-\fP". Proszę zauważyć, że parametr "\fB\-\-\fP" też jest generowany, ale w opisywanym trybie specjalnym będzie zawsze ostatnim parametrem.
.SH "ZGODNOŚĆ"
.sp
Niniejszą wersję \fBgetopt\fP(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.
.sp
Jeśli pierwszym znakiem pierwszego parametru getopt nie jest "\fB\-\fP", \fBgetopt\fP 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 \fBPOSIXLY_CORRECT\fP \- wówczas \fBgetopt\fP automatycznie poprzedzi krótkie opcje znakiem "\fB+\fP".
.sp
Zmienna środowiskowa \fBGETOPT_COMPATIBLE\fP zmusza \fBgetopt\fP do wejścia w tryb kompatybilności. Jej łącze ustawienie ze zmienną środowiskową \fBPOSIXLY_CORRECT\fP gwarantuje 100% kompatybilność dla "trudnych" programów. Zwykle żadna z nich nie jest jednak konieczna.
.sp
W trybie kompatybilności, początkowe znaki "\fB\-\fP" i "\fB+\fP" w łańcuchu krótkich opcji są ignorowane.
.SH "KODY ZAKOŃCZENIA"
.sp
\fBgetopt\fP zwraca kod błędu \fB0\fP w przypadku pomyślnej analizy; \fB1\fP jeśli \fBgetopt\fP(3) zwróci błędy; \fB2\fP jeśli nie rozpoznaje swoich własnych parametrów; \fB3\fP jeśli wystąpi błąd wewnętrzny, taki jak brak pamięci oraz \fB4\fP gdy zostanie wywołany z opcją \fB\-T\fP.
.SH "PRZYKŁADY"
.sp
Przykładowe skrypty dla powłok (ba)sh i (t)csh są dostarczane razem z programem \fBgetopt\fP(1) i instalowane w katalogu \fI/usr/share/doc/util\-linux\fP.
.SH "ŚRODOWISKO"
.sp
\fBPOSIXLY_CORRECT\fP
.RS 4
Zmienna sprawdzane przez funkcje \fBgetopt\fP(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 "\fB\-\fP".
.RE
.sp
\fBGETOPT_COMPATIBLE\fP
.RS 4
Zmusza \fBgetopt\fP do użycie pierwszego formatu wywołania opisanego w \fBSKŁADNI\fP.
.RE
.SH "USTERKI"
.sp
\fBgetopt\fP(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 \fBgetopt\fP(1) traktuje puste argumenty tak, jakby były nieobecne.
.sp
Składnia nie jest zbyt intuicyjna, gdy nie są potrzebne zmienne z krótkimi opcjami (trzeba je ustawić jawnie na pusty łańcuch).
.SH "AUTOR"
.sp
.MTO "frodo\(atfrodo.looijaard.name" "Frodo Looijaard" ""
.SH "ZOBACZ TAKŻE"
.sp
\fBbash\fP(1), \fBtcsh\fP(1), \fBgetopt\fP(3)
.SH "ZGŁASZANIE BŁĘDÓW"
.sp
Problemy należy zgłaszać w \c
.URL "https://github.com/util\-linux/util\-linux/issues" "systemie śledzenia błędów" "."
.SH "DOSTĘPNOŚĆ"
.sp
Polecenie \fBgetopt\fP jest częścią pakietu util\-linux, który można pobrać ze strony \c
.URL "https://www.kernel.org/pub/linux/utils/util\-linux/" "Archiwum jądra Linux" "."