Scroll to navigation

AR(1) Narzędzia programistyczne GNU AR(1)

NAZWA

ar - tworzy, modyfikuje i wypakowuje z archiwów

SKŁADNIA

ar [-X32_64] [-]p[mod] [--plugin nazwa] [--target nazwa-bfd] [--output nazwa-katalogu] [--record-libdeps zal-bibl] [--thin] [poz-rel] [numer] archiwum [składowa...]

OPIS

Program GNU ar tworzy, modyfikuje i wypakowuje pliki z archiwów. Archiwum jest pojedynczym plikiem, zawierającym zbiór innych plików w strukturze, która umożliwia wypakowanie plików oryginalnych (zwanych składowymi archiwum.

Zawartość pierwotnych plików, tryb (uprawnienia), znaczniki czasu, właściciele i grupy są zachowywane w archiwum i mogą być przywrócone przy wypakowaniu.

GNU ar potrafi obsługiwać archiwa, których składowe mają nazwy dowolnej długości; zależnie jednak od konfiguracji ar, można ustawiać limit długości nazwy składowych, dla zachowania kompatybilności z formatami archiwów utrzymywanymi przez inne narzędzia. Jeśli limit istnieje, to jest często limitem 15 znaków (typowy dla formatów związanych z a.out) lub 16 (typowe dla formatów związanych z coff).

ar jest uważany za narzędzie binarne, ponieważ jego archiwa są najczęściej używane jako biblioteki (statyczne) zawierające najczęściej używane funkcje. Ponieważ biblioteki często zależą od innych bibliotek, ar może również zachować zależności biblioteki, jeśli poda się opcję --record-libdeps.

Jeśli poda się modyfikator s, ar będzie tworzył indeks do symboli zdefiniowanych w relokowalnych modułach obiektowych archiwum. Raz utworzony indeks jest odnawiany w archiwum w sytuacji, gdy ar zmieni jego zawartość (bezpieczne dla operacji odnawiania q). Archiwum z takim indeksem przyspiesza linkowanie biblioteki i umożliwia funkcjom z biblioteki wołanie siebie nawzajem bez względu na położenie w archiwum.

Aby wypisać ten indeks, można użyć nm -s lub nm --print-armap. Jeśli archiwum nie ma takiego indeksu, można go dodać przy użyciu innej formy ar, nazywającej się ranlib.

GNU ar może opcjonalnie utworzyć archiwum cienkie, które zawiera indeks symboli i odniesienia do pierwotnych kopii składowych archiwum. Przydaje się to przy budowaniu bibliotek do użycia w lokalnym drzewie budowania, gdzie zakłada się, że obiekty relokowalne pozostaną dostępne, a kopiowanie zawartości każdego z tych obiektów byłoby stratą czasu i miejsca.

Archiwum może być albo cienkie albo normalne. Nie może być obiema tymi postaciami jednocześnie. Po utworzeniu, nie da się zmienić formatu archiwum bez uprzedniego usunięcia go i utworzenia archiwum na nowo.

Archiwa cienkie są również spłaszczone, zatem archiwum cienkie dodane do innego archiwum cienkiego nie zagnieździ się, jak stałoby się to ze zwykłym archiwum. Elementy pierwszego archiwum zostaną w zamian dodane indywidualnie do drugiego archiwum.

Ścieżki do elementów archiwum są przechowywane względem samego archiwum.

GNU ar został zaprojektowany do użycia na dwa sposoby. Można kontrolować jego aktywność za pomocą opcji wiersza poleceń, podobnie jak w różnych odmianach ar na systemach uniksowych albo, jeśli poda się pojedynczą opcję wiersza polecenia -M, można kontrolować go za pomocą skryptu podanego na standardowe wejście, podobnie jak w programie MRI "librarian".

OPCJE

GNU ar umożliwia mieszanie kodu operacji p i flag modyfikacji mod w dowolnej kolejności, w obrębie pierwszego argumentu wiersza poleceń.

Można również rozpocząć pierwszy argument wiersza poleceń kreseczką.

Litera kluczowa p określa, jaką operację wykonać; może być dowolną z następujących, lecz tylko jedną naraz:

Kasuje moduły z archiwum. Nazwy modułów do usunięcia należy podać jako składowe...; archiwum pozostanie nietknięte, jeśli nie poda się plików do skasowania.

Jeśli poda się modyfikator v, to ar wyświetli każdy skasowany moduł.

Operacja służy do przemieszczenia składowych archiwum.

Kolejność składowych w archiwum może być istotna przy linkowaniu biblioteki z programami, kiedy symbol jest zdefiniowany więcej niż w jednej składowej.

Jeśli nie użyto żadnych modyfikatorów przy "m", wszystkie składowe nazwane w argumentach składowa są przenoszone na koniec archiwum; można również użyć modyfikatorów a, b lub i, aby przenieść je do określonego miejsca.

Wypisuje określone składowe archiwum na standardowe wyjście. Jeśli został podany modyfikator v, to przed skopiowaniem zawartości składowej na standardowym wyjściu, pokazuje jego nazwę.

Jeśli nie podano żadnych argumentów składowych, wypisane zostaną wszystkie pliki archiwum.

Szybkie dołączenie; historycznie dodawało składowe... do końca archiwum, bez sprawdzania podmieniania.

Modyfikatory a, b, i i nie wpływają na tę operację; nowe składowe zawsze są dodawane na końcu archiwum.

Modyfikator v powoduje, że ar wypisuje każdy plik, który doda.

Jako że celem tej operacji jest szybkość, implementacje ar nie aktualizowały tablicy symboli archiwum, jeśli taka istniała. Jednak zbyt wiele systemów zakłada, ze tablica symboli jest zawsze aktualna, dlatego GNU ar przebudowuje tablicę nawet przy operacji szybkiego dołączenia.

Uwaga - GNU ar traktuje polecenie qs jako synonim r - zastępuje istniejące pliki w archiwum i dodaje nowe na jego końcu.

Wstawia pliki składowe... do archiwum (z podmienianiem). Ta operacja różni się od q tym, że wszystkie istniejące składowe zostaną usunięte, jeśli ich nazwy odpowiadają nazwom dodawanym.

Jeśli któryś z plików nazwanych w argumencie składowa... nie istnieje, ar wyświetla komunikat o błędzie i pozostawia składowe archiwum, odpowiadające tej nazwie.

Domyślnie, nowe składowe są dodawane na koniec pliku; można jednak użyć jednego z modyfikatorów a, b lub i, aby zażądać wstawienia względem jakiejś istniejącej składowej.

W tej operacji można użyć modyfikatora v, który wyświetla po jednym wierszu komentarza dla każdego włączonego pliku, uzupełniając ją jedną z liter a lub r, wskazując tak odpowiednio, czy plik został dopisany na końcu (nie skasowano żadnej starej składowej) czy został podmieniony.

Dodaje indeks do archiwum lub aktualizuje go, jeśli już istnieje. To polecenie jest wyjątkiem od reguły, że można podać tylko jedną literę polecenia, ponieważ można go stosować jako polecenie lub modyfikator. W obu przypadkach działa tak samo.
Wypisuje w formie tabelarycznej zawartość archiwum lub tych z plików, wymienionych w argumencie składowe, które są obecne w archiwum. Normalnie wyświetlana jest tylko nazwa składowej, natomiast jeśli poda się modyfikator O, wyświetlane jest również odpowiednie przesunięcie (offset) składowej. Aby zapoznać się z trybami (uprawnieniami), znacznikiem czasowym, właścicielem, grupą i rozmiarem, należy podać modyfikator v.

Jeśli nie zostanie podany żaden argument składowa, to wypisane zostaną wszystkie pliki archiwum.

Jeśli pod daną nazwą w archiwum (powiedzmy b.a istnieje więcej niż jeden plik (powiedzmy fie), to ar t b.a fie wypisze tylko pierwszy z nich; aby zobaczyć wszystkie, należy zażądać pełnej listy — w naszym przypadku, ar t b.a.

Wypakowuje składowe (o nazwie składowa) z archiwum. Aby zażądać, by ar wypisał każdą nazwę podczas jej wypakowywania, można użyć modyfikatora v.

Jeśli nie poda się składowej, wypakowane zostaną wszystkie pliki archiwum.

Plików nie da się wypakować z archiwum cienkiego, istnieją również ograniczenia w stosunku do wypakowywania z archiwów utworzonych za pomocą P: Ścieżki nie mogą być absolutne, nie mogą zawierać "..", a wszystkie podkatalogi ścieżki muszą istnieć. Jeśli wskazane byłoby ominięcie tych ograniczeń, należy podać opcję --output, aby podać katalog wyjściowy.

Za literą kluczową p może znajdować się pewna liczba modyfikatorów (mod), która wtedy określa wariacje zachowania tej operacji:

Dodaje nowe pliki za istniejącą składową archiwum. Jeśli używa się tego modyfikatora, to przed podaniem archiwum, należy wskazać nazwę istniejącej składowej archiwum argumentem poz-rel
Dodaje nowe pliki przed istniejącą składową archiwum. Jeśli używa się tego modyfikatora, to przed podaniem archiwum, należy wskazać nazwę istniejącej składowej archiwum argumentem poz-rel. (Równoważne i)
Tworzy archiwum. Podane archiwum jest zawsze tworzone jeżeli nie istniało, a zażąda się odnowienia (update). Wypisywane jest jednak wtedy ostrzeżenie, chyba że poda się z góry, że chce się je utworzyć, używając tego modyfikatora.
Działa w trybie deterministycznym. Przy dodawaniu plików i indeksu archiwum używa zera jako identyfikatorów użytkowników, grup, znaczników czasowych oraz używa stałych trybów plików dla wszystkich plików. Przy korzystaniu z tej opcji, jeśli użyje się programu ar z identycznymi opcjami i identycznymi plikami wejściowymi, kolejne przebiegi utworzą identyczne pliki wyjściowe, niezależnie od właścicieli, grup, trybów plików i czasów modyfikacji plików wejściowych.

Jeśli binutils skonfigurowano z --enable-deterministic-archives, tryb ten jest domyślnie włączony. Można go wyłączyć modyfikatorem U, zob. niżej.

Skraca nazwy w archiwum. GNU ar normalnie pozwala plikom mieć dowolną długość. Powoduje to, że archiwa mogą być niekompatybilne z natywnymi programami ar niektórych innych systemów. Jeśli jest to istotne, można wykorzystać modyfikator f, który umożliwia skracanie nazw plików podczas wstawiania ich do archiwum.
Wstawia nowe pliki przed istniejącą składową archiwum. Jeśli używa się tego modyfikatora, to przed podaniem archiwum, należy wskazać nazwę istniejącej składowej archiwum argumentem poz-rel. (Równoważne b)
Określa zależności tej biblioteki. Zależności muszą wystąpić bezpośrednio po tym znaku opcji, muszą używać tej samej składni jak wiersz polecenia konsolidatora oraz muszą być podane jako jeden argument. Oznacza to, że jeśli konieczne jest podanie wielu elementów, należy je zacytować, aby utworzyły pojedynczy argument wiersza poleceń. Przykład: l "-L/usr/local/lib -lmojazaleznosc1 -lmojazaleznosc2"
Używa parametru numer. Jest on stosowany, gdy występuje wiele wpisów z tą samą nazwą w archiwum. Wówczas wypakowane lub usunięte zostanie wystąpienie podanej nazwy o zadanym numerze z archiwum.
Chroni oryginalne daty składowych przy wypakowywaniu. Jeśli nie poda się tego modyfikatora, pliki wypakowane z archiwum będą oznaczone czasem z chwili wypakowania.
Wypisuje przesunięcia (offsety) wewnątrz archiwum. Należy używać łącznie z opcją t.
Używa pełnej ścieżki przy dopasowywaniu lub przechowywaniu nazw w archiwum. Archiwa z pełnymi ścieżkami nie są zgodne z normą POSIX, zatem mogą nie działać z narzędziami innymi niż aktualne narzędzia GNU. Modyfikowanie takich archiwów programem GNU ar bez podania P spowoduje usunięcie pełnych ścieżek chyba, że jest to archiwum cienkie. Proszę zauważyć, że P może być przydatne przy dodawaniu plików do archiwum cienkiego, ponieważ r bez P ignoruje ścieżki, przy wyborze elementów do zastąpienia. Zatem 

 ar rcST archiwum.a podkat/plik1 podkat/plik2 plik1

spowoduje zastąpienie "podkat/plik1" przez "plik1" z katalogu bieżącego. Dodanie P pozwoli uniknąć tego zastąpienia.

Zapisuje indeks plików obiektowych do archiwum, lub odnawia istniejący, nawet jeśli w archiwum nic nie zmieniono. Tej flagi modyfikującej można użyć w połączeniu z dowolną operacją, lub samodzielnie. Uruchamianie ar s na archiwum jest równoważne uruchomieniu na nim ranlib.
Nie tworzy tablicy symboli archiwum. Może to przyspieszyć budowanie dużej biblioteki w wielu krokach. Wynikowe archiwum nie może być stosowane z konsolidatorem. Aby zbudować tablicę symboli konieczne jest pominięcie modyfikatora S przy ostatnim wykonaniu ar albo uruchomienie ranlib na archiwum.
Przestarzały alias --thin. T nie jest zalecane, ponieważ w wielu implementacjach ar, T ma inne znaczenie, określone w X/Open System Interface.
Normalnie, ar r... wstawia wszystkie wypisane pliki do archiwum. Jeśli chce się wstawić tylko te z wymienionych plików, które są nowsze od istniejących składowych o tych samych nazwach, należy użyć tego modyfikatora. Modyfikator u jest dozwolony tylko przy operacji r (podmienienia). W praktyce kombinacja qu nie jest dozwolona, ponieważ sprawdzanie znaczników czasowych spowodowałoby spowolnienie wszystkich ulepszeń operacji q.

Uwaga - jeśli archiwum utworzono w sposób deterministyczny np. z modyfikatorem D, to zastąpienia wystąpią zawsze, co uczyni modyfikator u nieefektywnym.

Nie działa w trybie deterministycznym. Jest to odwrotność modyfikatora D opisanej powyżej: podczas kopiowania składowych archiwum i zapisywania indeksu archiwum używa właściwych wartości pól identyfikatorów użytkownika, grupy, znacznika czasowego i praw dostępu do pliku.

Jest to zachowanie domyślne, o ile binutils nie został skonfigurowany z --enable-deterministic-archives.

Ten modyfikator żąda wersji operacji, która wypisuje komunikaty informacyjne. Po dodaniu modyfikatora v wiele operacji wyświetla dodatkowe informacje np. przetwarzane pliki.
Ten modyfikator pokazuje wersję programu ar.

Program ar obsługuje również pewne opcje wiersza poleceń, które nie są ani modyfikatorami, ani akcjami, lecz zmieniają jego zachowanie w pewien określony sposób:

Wyświetla listę opcji wiersza poleceń obsługiwanych przez ar i wychodzi.
Wyświetla informacje o wersji programu ar i wychodzi.
ar ignoruje początkową opcję -X32_64, ze względu na kompatybilność z AIX. Zachowanie określone tą opcją jest bowiem domyślne dla GNU ar. ar nie obsługuje żadnych innych opcji -X; w szczególności nie obsługuje -X32, która jest domyślna dla AIX ar.
Opcjonalny przełącznik wiersza poleceń --plugin nazwa powoduje, że ar załaduje wtyczkę o podanej nazwie, która dodaje obsługę większej liczby formatów plików, w tym plików obiektowych z informacjami o optymalizacji w momencie linkowania.

Opcja jest dostępna tylko, jeśli program zbudowano z włączoną obsługą wtyczek.

Jeśli nie podano --plugin, lecz obsługa wtyczek została włączona, to ar przechodzi przez pliki w ${libdir}/bfd-plugins w kolejności alfabetycznej i używa pierwszej wtyczki deklarującej dany obiekt.

Proszę zauważyć, że ten katalog przeszukiwania wtyczek nie jest taki, jak używany przez opcję -plugin programu ld. Aby ar używał wtyczki konsolidarora, musi być ona skopiowana do katalogu ${libdir}/bfd-plugins. W przypadku kompilacji powstałych w oparciu o GCC, wtyczka konsolidatora ma nazwę liblto_plugin.so.0.0.0. W przypadku Clanga jest to LLVMgold.so. Wtyczka GCC jest zawsze wstecznie kompatybilna z wcześniejszymi wersjami, więc wystarczy skopiować jej najnowszą wersję.

Opcjonalny przełącznik wiersza poleceń --target nazwa-bfd określa, że składowe archiwum są w formacie obiektowym kodu różnym od domyślnego formatu bieżącego systemu.
Opcja --output służy do określenia ścieżki do katalogu, do którego powinny być wypakowane składowe archiwum. Jeśli się jej nie poda, używany jest katalog bieżący.

Uwaga - choć obecność tej opcji wymusza wypakowanie za pomocą x, to wciąż trzeba podać tę opcję w wierszu polecenia.

Opcja --record-libdeps jest identyczna jak modyfikator l, stanowi jedynie odmianę w długiej postaci.
Czyni z podanego archiwum archiwum cienkie. Jeśli podane archiwum już istnieje i jest archiwum zwykłym, istniejące składowe muszą być obecne w tym samym katalogu, co archiwum.
@plik
Czyta opcje wiersza poleceń z podanego pliku. Przeczytane opcje są wstawiane w miejsce oryginalnej opcji @plik. Jeśli plik nie istnieje lub nie może być odczytany, ta opcja jest traktowana dosłownie i nie jest usuwana.

Opcje w pliku są rozdzielane białymi znakami. Biały znak może wystąpić w opcji, jeśli cała opcja zostanie ujęta w pojedyncze albo podwójne cudzysłowy. Można dodać dowolny znak (włączając w to znak odwrotnego ukośnika), poprzedzając go znakiem odwrotnego ukośnika. Plik może również zawierać dodatkowe opcje @plik - w takim przypadku każda z takich opcji będzie przetwarzana rekurencyjnie.

ZOBACZ TAKŻE

nm(1), ranlib(1) oraz wpisy Info zestawu binutils.

PRAWA AUTORSKIE

Copyright (c) 1991-2025 Free Software Foundation, Inc.

Zezwala się na kopiowanie, rozpowszechnianie i/lub modyfikowanie tego dokumentu na warunkach Licencji Wolnej Dokumentacji GNU (GNU Free Documentation License) w wersji 1.3 lub jakiejkolwiek nowszej wersji opublikowanej przez Fundację Wolnego Oprogramowania, przy czym Sekcjami niezmiennymi są „GNU General Public License” i „GNU Free Documentation License”, bez treści przedniej lub tylnej strony okładki. Egzemplarz licencji zamieszczono w sekcji zatytułowanej „GNU Free Documentation License”.

TŁUMACZENIE

Autorami polskiego tłumaczenia niniejszej strony podręcznika są: Przemek Borys <pborys@dione.ids.pl> i Michał Kułach <michal.kulach@gmail.com>

Niniejsze tłumaczenie jest wolną dokumentacją. Bliższe informacje o warunkach licencji można uzyskać zapoznając się z GNU General Public License w wersji 3 lub nowszej. Nie przyjmuje się ŻADNEJ ODPOWIEDZIALNOŚCI.

Błędy w tłumaczeniu strony podręcznika prosimy zgłaszać na adres listy dyskusyjnej manpages-pl-list@lists.sourceforge.net.

3 marca 2025 r. binutils-2.44