GETOPT(1) Polecenia uzytkownika GETOPT(1) NAZWA getopt - analizuje opcje wiersza polecen (rozszerzone) SKLADNIA getopt lancuch-opcji parametry getopt [opcje] [--] lancuch-opcji parametry getopt [opcje] -o|--options lancuch-opcji [opcje] [--] parametry OPIS getopt sluzy do rozdzielenia (analizy) opcji w wierszu polecen, w celu latwego analizowania przez funkcje powloki oraz sprawdzenia poprawnosci opcji. Program wykorzystuje do tego celu funkcje GNU getopt(3). Parametry, z ktorymi wywolywany jest getopt, mozna podzielic na dwie czesci: opcje modyfikujace sposob analizy getopt (opcje i lancuch-opcji w SKLADNI) oraz parametry do przeanalizowania (parametry w SKLADNI). Druga czesc rozpoczyna sie od pierwszego parametru nieopcyjnego, ktory nie jest argumentem opcji lub po pierwszym wystapieniu "--". Jesli w pierwszej czesci nie wystapi "-o" ani "--options", to pierwszy parametr drugiej czesci jest intepretowany jako lancuch krotkich opcji. Jesli ustawiona jest zmienna srodowiskowa GETOPT_COMPATIBLE lub gdy pierwszy parametr nie jest opcja (nie rozpoczyna sie od "-", pierwszy format w SKLADNI), getopt utworzy wyjscie kompatybilne z innymi wersjami getopt(1). Mimo to, zmieniona zostanie kolejnosc parametrow oraz zostana rozpoznane argumenty opcjonalne (wiecej informacji w rozdziale KOMPATYBILNOSC). Tradycyjne implementacje getopt(1) nie radza sobie z bialymi znakami i innymi (zaleznymi od powloki) znakami specjalnymi w argumentach i parametrach niebedacymi opcjami. Aby rozwiazac ten problem, niniejsza implementacja potrafi utworzyc wyjscie cytowane, ktore musi byc ponownie zinterpretowane przez powloke (zwykle poleceniem eval). Dzieki temu wspomniane znaki zostana zachowane, ale konieczne jest wywolanie getopt w sposob, ktory nie bedzie kompatybilny z innymi wersjami (drugi lub trzeci format w SKLADNI). Aby okreslic, czy zainstalowano rozszerzona wersje getopt(1), mozna skorzystac ze specjalnej opcji testowania (-T). OPCJE -a, --alternative Pozwala na rozpoczynanie dlugich opcji pojedynczym "-". -l, --longoptions dlugie-opcje Dlugie (wieloznakowe) opcje do rozpoznania. Mozna podac jednoczesnie wiele nazw opcji, rozdzielajac je przecinkami. Opcji tej mozna uzyc wiecej niz raz, dlugie-opcje lacza sie. Po kazdej nazwie opcji w dlugich-opcjach mozna dopisac jeden dwukropek - aby wskazac ze jest to argument wymagany albo dwa dwukropki - oznaczajace argument opcjonalny. -n, --name nazwa-programu Nazwa, ktora posluzy funkcjom getopt(3) do zglaszania bledow. Prosze zauwazyc, ze bledy samego getopt(1) sa wciaz zglaszane jako pochodzace z getopt. -o, --options krotkie-opcje Krotkie (jednoznakowe) opcje do rozpoznania. Jesli nie poda sie tej opcji, pierwszy parametr getopt niezaczynajacy sie od "-" (i niebedacym argumentem opcji) sluzy jako lancuch krotkich opcji. Po kazdym znaku ktotkich opcji w krotkich-opcjach mozna dopisac jeden dwukropek - aby wskazac ze jest to argument wymagany albo dwa dwukropki - oznaczajace argument opcjonalny. Pierwszy znak w krotkich-opcjach rowny "+" lub "-" wplywa na sposob analizy i tworzenia wyjscia (wiecej szczegolow w rozdziale TRYBY SKANOWANIA). -q, --quiet Wylacza zglaszanie bledow przez getopt(3). -Q, --quiet-output Nie tworzy normalnego wyjscia. Bledy sa wciaz zglaszane przez getopt(3), chyba ze podano tez opcje -q. -s, --shell powloka Ustawia konwencje cytowania na uzywana przez powloke. Jesli nie podano opcji -s stosowane sa konwencje powloki BASH. Prawidlowymi argumentami sa obecnie: "sh", "bash", "csh" i "tcsh". -T, --test Sprawdza, czy uzywany program getopt(1) jest opisywana tu wersja rozszerzona, czy stara wersja. Niniejsza wersja nie tworzy wyjscia i ustawia status bledu na 4. Inne implementacje getopt(1) oraz ta wersja, jesli ustawiono zmienna srodowiskowa GETOPT_COMPATIBLE, zwroci "--" i status bledu 0. -u, --unquoted Nie uzywa cytowania w wyjsciu. Prosze zauwazyc, ze biale znaki i znaki specjalne (zalezne od powloki) moga spowodowac w tym trybie rozgardiasz (podobnie jak dzieje sie w innych implementacjach getopt(1)). -h, --help Wyswietla ten tekst i wychodzi. -V, --version Wyswietla wersje i wychodzi. ANALIZOWANIE Niniejszy rozdzial okresla format drugiej czesci parametrow getopt (parametry w SKLADNI). Kolejny rozdzial (WYJSCIE) opisuje tworzone wyjscie. Parametry te byly zwykle parametrami, z ktorymi wywolano funkcje powloki. Nalezy uwazac, aby kazdy parametr, z ktorym wywolano funkcje powloki, odpowiadal dokladnie jednemu parametrowi w liscie parametrow getopt (zob. PRZYKLADY). Cala analiza jest dokonywana przez funkcje getopt(3) GNU. Parametry sa analizowane od lewej do prawej strony. Kazdy parametr jest klasyfikowany jako: krotka opcja, dluga opcja, argument do opcji albo parametr niebedacy opcja. Prosta krotka opcja jest "-" po ktorym nastepuje znak krotkiej opcji. Jesli opcja ma wymagany argument, moze byc on zapisany bezposrednio po znaku opcji lub jako nastepny parametr (tj. rozdzielony bialym znakiem w wierszu polecenia). Jesli opcja ma argument opcjonalny, jesli jest obecny, musi byc podany bezposrednio po znaku opcji (bez odstepu). Po jednym "-" mozna podac wiele krotkich opcji, o ile tylko nie maja one argumentow wymaganych lub opcjonalnych (to ograniczenie nie dotyczy ostatniej opcji). Dlugie opcje zaczynaja sie zwykle od "--", po ktorym nastepuje nazwa dlugiej opcji. Jesli opcja ma argument wymagany, moze byc: zapisany bezposrednio po nazwie dlugiej opcji, rozdzielony znakiem '=' albo byc nastepnym argumentem (tj. rozdzielony bialym znakiem w wierszu polecenia). Jesli opcja ma argument opcjonalny, jesli jest obecny, musi byc podany tuz po nazwie dlugiej opcji, rozdzielony od niej znakiem "=" (jesli poda sie sam znak "=" jest to interpretowane jak gdyby argument nie byl obecny; jest to niewielki blad, zob. USTERKI). Nazwy dlugich opcji mozna skracac, o ile tylko tak skrocona nazwa nie bedzie niejednoznaczna. Kazdy parametr niezaczynajacy sie od "-" oraz niebedacy wymaganym argumentem poprzedniej opcji jest parametrem nieopcyjnym. Kazdy parametr po "--" jest zawsze interpretowany jako parametr nieopcyjny. Jesli ustawiona jest zmienna srodowiskowa POSIXLY_CORRECT lub gdy lancuch krotkiej opcji zaczyna sie znakiem "+", wszystkie pozostale parametry sa interpretowane jako parametry nieopcyjne po tym, jak zostanie odnaleziony pierwszy parametr nieopcyjny. WYJSCIE Wyjscie tworzone jest dla kazdego elementu opisanego w poprzednim rozdziale. Wyjscie jest tworzone w tej samej kolejnosci jak elementy podane w wejsciu, z wyjatkiem parametrow nieopcyjnych. Wyjscie moze byc tworzone w trybie kompatybilnosci (niecytowanym) lub w taki sposob, ze zachowywane sa biale znaki i inne specjalne znaki wewnetrz argumentow i parametrow nieopcyjnych (zob. CYTOWANIE). Gdy wyjscie jest analizowane w skrypcie powloki, bedzie wygladalo na utworzone z wyraznie oddzielnych elementow, ktore moga byc przetwarzane pojedynczo (w wiekszosci jezykow powloki za pomoca polecenia shift). Jest to niedoskonale w trybie niecytowanym, poniewaz elementy moga byc przelamane w nieoczekiwanych miejscach, jesli zawieraja biale znaki lub znaki specjalne. Jesli przy analizie parametrow wystapia problemy np. z powodu braku wymaganego argumentu lub nierozpoznania opcji, na standardowe wyjscie bledo zostanie zgloszony blad, dla problematycznego elementu nie zostanie utworzone wyjscie, a program zwroci niezerowy status bledu. W przypadku krotkiej opcji, jako jeden parametr zostanie utworzony pojedynczy "-" wraz ze znakiem opcji. Jesli opcja przyjmuje argument opcjonalny, lecz nie zostanie on odnaleziony, w trybie cytowania zostanie utworzony nastepny, pusty parametr, natomiast w trybie niecytowanym (kompatybilnosci) drugi parametr nie bedzie tworzony. Prosze zauwazyc, ze wiele innych implementacji getopt(1) nie obsluguje argumentow opcjonalnych. Jesli po pojedynczym "-" podano wiele krotkich opcji, kazda bedzie obecna w wyjsciu jako oddzielny parametr. W przypadku dlugiej opcji, jako jeden parametr zostanie utworzone "--" wraz z pelna nazwa opcji. Tak dzieje sie niezaleznie od tego, czy uzyto skroconej nazwy opcji, albo opcje podano w wejsciu z pojedynczym "-". Argumenty sa obslugiwane w taki sam sposob jak w przypadku krotkich opcji. Zwykle wyjscie parametrow nieopcyjnych nie jest tworzone az do momentu wygenerowania wszystkich opcji i ich argumentow. Nastepnie tworzone jest "--"' jako pojedynczy parametr, a po nim nastepuja parametry nieopcyjne, w kolejnosci ich odnalezienia, kazdy jako oddzielny parametr. Tylko gdy pierwszym znakiem lancucha krotkich opcji byl "-", wyjscie parametrow nieopcyjnych jest tworzone w miejscu jego odnalezienia na werjsciu (nie jest to obslugiwane w pierwszym formacie SKLADNI; w takim przypadku wszystkie poprzedzajace wystapienia "-" i "+" sa ignorowane). CYTOWANIE W trybie kompatybilnosci, biale znaki oraz znaki "specjalne" w argumentach lub parametrach nieopcyjnych nie sa poprawnie obslugiwane. W miare wysylania wyjscia do skryptu powloki, skrypt nie wie w jaki sposob ma rozdzielic wyjscie na poszczegolne parametry. Aby naprawic ten problem, niniejsza implementacja oferuje cytowanie. Dzieki temu tworzone wyjscie posiada znaki cytowania wokol kazdego parametru. Gdy to wyjscie jest nastepnie ponownie przesylane do powloki (zwykle poleceniem eval powloki), jest poprawnie dzielone na poszczegolne parametry. Cytowanie nie jest wlaczane, gdy ustawiona jest zmienna srodowiskowa GETOPT_COMPATIBLE, korzysta sie z pierwszej postaci SKLADNI lub gdy poda sie opcje "-u". Rozne powloki korzystaja z roznych konwencji cytowania. Opcja "-s" sluzy do wyboru uzywanej powloki. Obecnie obslugiwane sa nastepujace powloki: "sh", "bash", "csh" i "tcsh". W praktyce rozrozniane sa jedynie dwie odmiany: konwencje cytowania w stylu sh i w stylu csh. Nawet jesli korzysta sie z innego jezyka skryptowego powloki, prawdopodobnie jedna z tych dwoch konwencji bedzie prawidlowa. TRYBY SKANOWANIA Pierwszym znakiem lancucha krotkich opcji moze byc "-" lub "+" wskazujac specjalny tryb skanowania. Jesli uzyta zostanie pierwsza postac SKLADNI, znaki te sa ignorowane, ale wciaz sprawdzana jest zmienna srodowiskowa POSIXLY_CORRECT. Jesli pierwszym znakiem jest "+" lub ustawiona jest zmienna srodowiskowa POSIXLY_CORRECT, analiza zatrzymuje sie po napotkaniu pierwszego parametru nieopcyjnego (tj. parametru niezaczynajacego sie od "-"), ktory nie jest argumentem opcji. Pozostale parametry sa interpretowane jako parametry nieopcyjne. Jesli pierwszym znakiem jest "-", parametry nieopcyjne sa wypisywane w miejscu ich odnalezienia; w zwyklym trybie dzialania sa zbierane na koncu wyjscia, po wygenerowaniu parametru "--". Prosze zauwazyc, ze parametr "--" tez jest generowany, ale w opisywanym trybie specjalnym bedzie zawsze ostatnim parametrem. ZGODNOSC Niniejsza wersje getopt(1) napisano w sposob zachowujacy maksymalna kompatybilnosc z innymi wersjami programu. Zwykle mozna je zastapic ta wersje bez koniecznosci dokonywania jakichkolwiek modyfikacji, a otrzymujac pewne korzysci. Jesli pierwszym znakiem pierwszego parametru getopt nie jest "-", getopt wejdzie w tryb kompatybilnosci. Zinterpretuje swoj pierwszy parametr jako lancuch krotkich opcji, a wszystkie pozostale argumenty zostana przeanalizowane. Wciaz dokona zmiany kolejnosci parametrow (tj. wszystkie parametry nieopcyjne sa wypisywane na koncu), chyba ze ustawiona jest zmienna srodowiskowa POSIXLY_CORRECT - wowczas getopt automatycznie poprzedzi krotkie opcje znakiem "+". Zmienna srodowiskowa GETOPT_COMPATIBLE zmusza getopt do wejscia w tryb kompatybilnosci. Jej lacze ustawienie ze zmienna srodowiskowa POSIXLY_CORRECT gwarantuje 100% kompatybilnosc dla "trudnych" programow. Zwykle zadna z nich nie jest jednak konieczna. W trybie kompatybilnosci, poczatkowe znaki "-" i "+" w lancuchu krotkich opcji sa ignorowane. KODY ZAKONCZENIA getopt zwraca kod bledu 0 w przypadku pomyslnej analizy; 1 jesli getopt(3) zwroci bledy; 2 jesli nie rozpoznaje swoich wlasnych parametrow; 3 jesli wystapi blad wewnetrzny, taki jak brak pamieci oraz 4 gdy zostanie wywolany z opcja -T. PRZYKLADY Przykladowe skrypty dla powlok (ba)sh i (t)csh sa dostarczane razem z programem getopt(1) i instalowane w katalogu /usr/share/doc/util-linux. SRODOWISKO POSIXLY_CORRECT Zmienna sprawdzane przez funkcje getopt(3). Jesli jest ustawiona, analiza zatrzymuje sie po napotkaniu parametru niebedacego opcja ani argumentem opcji. Wszystkie pozostale parametry sa rowniez interpretowane jako parametry nieopcyjne, niezaleznie od tego, czy zaczynaja sie od znaku "-". GETOPT_COMPATIBLE Zmusza getopt do uzycie pierwszego formatu wywolania opisanego w SKLADNI. USTERKI getopt(3) potrafi analizowac dlugie opcje z argumentami opcjonalnymi, ktore sa podane jako pusty argumenty opcjonalne (lecz nie moze tego czynic wobec krotkich opcji). Ten program getopt(1) traktuje puste argumenty tak, jakby byly nieobecne. Skladnia nie jest zbyt intuicyjna, gdy nie sa potrzebne zmienne z krotkimi opcjami (trzeba je ustawic jawnie na pusty lancuch). AUTOR Frodo Looijaard ZOBACZ TAKZE bash(1), tcsh(1), getopt(3) ZGLASZANIE BLEDOW Problemy nalezy zglaszac w systemie sledzenia bledow . DOSTEPNOSC Polecenie getopt jest czescia pakietu util-linux, ktory mozna pobrac ze strony Archiwum jadra Linux . util-linux 2.41 2025-03-29 GETOPT(1)