AR(1) GNU Development Tools AR(1)

ar - ساخت، ویرایش و استخراج از بایگانی‌ها

ar [-X32_64] [-]p[mod] [--plugin name] [--target bfdname] [--output dirname] [--record-libdeps libdeps] [--thin] [relpos] [count] archive [member...]

برنامهٔ GNU ar بایگانی‌ها را می‌سازد، ویرایش می‌کند، و محتوای آن‌ها را استخراج می‌نماید. یک بایگانی (archive) فایلی یکتاست که مجموعه‌ای از فایل‌های دیگر را درون ساختاری نگه می‌دارد که بازیابی مجدد تک‌تک فایل‌های اولیه (که عضوهای بایگانی یا members نامیده می‌شوند) را ممکن می‌سازد.

محتوای فایل‌های اصلی، حالت (مجوزها)، برچسب زمان، مالک، و گروه آن‌ها درون بایگانی حفظ می‌شوند و در هنگام استخراج قابل بازیابی هستند.

ابزار GNU ar می‌تواند بایگانی‌هایی را مدیریت کند که اعضای آن نام‌هایی با هر طولی داشته باشند؛ با این حال، بسته به نحوهٔ پیکربندی ar بر روی سیستم شما، ممکن است برای سازگاری با قالب‌های بایگانیِ مدیریت‌شده توسط ابزارهای دیگر، محدودیتی روی طول نام عضو اعمال شود. در صورت وجود، این محدودیت معمولاً ۱۵ نویسه (رایج در قالب‌های مرتبط با a.out) یا ۱۶ نویسه (رایج در قالب‌های مرتبط با coff) است.

ابزار ar یک ابزار باینری به شمار می‌رود، زیرا بایگانی‌هایی از این نوع اغلب به عنوان کتابخانه‌هایی حاوی زیرروال‌های پرکاربرد استفاده می‌شوند. از آنجا که کتابخانه‌ها معمولاً به کتابخانه‌های دیگری وابسته هستند، ar همچنین می‌تواند در صورت تعیین گزینهٔ --record-libdeps، وابستگی‌های یک کتابخانه را ثبت کند.

هنگامی که تغییردهندهٔ s را تعیین می‌کنید، ar یک نمایه (index) از نمادهای تعریف‌شده در پودمان‌های شیء بازآدرس‌پذیر (relocatable object modules) در بایگانی ایجاد می‌کند. پس از ایجاد، این نمایه هر بار که ar تغییری در محتویات آن ایجاد کند (به‌جز عملیات به‌روزرسانی q)، در بایگانی به‌روزرسانی می‌شود. بایگانیِ دارای چنین نمایه‌ای، سرعت پیوند دادن به کتابخانه را افزایش می‌دهد و به روال‌های درون کتابخانه اجازه می‌دهد بدون توجه به جایگاهشان در بایگانی، یکدیگر را فراخوانی کنند.

می‌توانید برای فهرست کردن این جدول نمایه از nm -s یا nm --print-armap استفاده کنید. اگر یک بایگانی فاقد این جدول باشد، می‌توان از شکل دیگری از ar به نام ranlib برای افزودن این جدول استفاده کرد.

ابزار GNU ar می‌تواند به‌صورت اختیاری یک بایگانی نازک (thin) بسازد که شامل نمایهٔ نمادها و ارجاع‌هایی به نسخه‌های اصلی فایل‌های عضو بایگانی است. این قابلیت برای ساخت کتابخانه‌هایی جهت استفاده در درخت ساخت (build tree) محلی کاربردی است؛ جایی که انتظار می‌رود اشیای بازآدرس‌پذیر همچنان در دسترس باقی بمانند و رونویسی محتوای هر شیء تنها موجب هدر رفتن زمان و فضا می‌شود.

یک بایگانی یا می‌تواند نازک باشد یا عادی؛ نمی‌تواند هر دو حالت را به طور هم‌زمان داشته باشد. پس از ایجاد یک بایگانی، قالب آن بدون حذف اولیه و سپس ساخت بایگانی جدید در جای آن، قابل تغییر نیست.

بایگانی‌های نازک همچنین به‌صورت هم‌سطح (flattened) هستند، به طوری که افزودن یک بایگانی نازک به یک بایگانی نازک دیگر باعث تو در تو شدن آن نمی‌شود؛ بر خلاف آنچه در یک بایگانی عادی رخ می‌دهد. در عوض، عناصر بایگانی اول به‌صورت مجزا به بایگانی دوم اضافه می‌شوند.

مسیرهای منتهی به عناصر بایگانی به‌صورت نسبی نسبت به خود فایل بایگانی ذخیره می‌شوند.

ابزار GNU ar به گونه‌ای طراحی شده است که با دو شیوهٔ کاری متفاوت سازگار باشد. شما می‌توانید عملکرد آن را با استفاده از گزینه‌های خط فرمان، مانند انواع گوناگون ar در سیستم‌های Unix کنترل کنید؛ یا اگر گزینهٔ خط فرمان تکی -M را تعیین کنید، می‌توانید آن را با یک اسکریپت که از طریق ورودی استاندارد فراهم می‌شود، همانند برنامهٔ "librarian" متعلق به MRI کنترل نمایید..SH "گزینه‌ها (OPTIONS)" ابزار GNU ar به شما امکان می‌دهد کد عملیات p و پرچم‌های تغییردهندهٔ mod را به هر ترتیبی درون نخستین آرگومان خط فرمان ترکیب کنید.

در صورت تمایل، می‌توانید نخستین آرگومان خط فرمان را با یک خط تیره (-) آغاز کنید.

حرف کلیدی p مشخص می‌کند چه عملیاتی اجرا شود؛ این حرف می‌تواند هر یک از موارد زیر باشد، اما تنها باید یکی از آن‌ها را مشخص کنید:

حذف پودمان‌ها از آرشیو. نام پودمان‌های حذفی را به‌صورت member... مشخص کنید؛ در صورتی که فایلی را برای حذف مشخص نکنید، آرشیو دست‌نخورده باقی می‌ماند.

اگر تغییردهندهٔ v را مشخص کنید، ar هر پودمان را هنگام حذف فهرست می‌کند.

از این عملیات برای جابه‌جایی اعضا در یک آرشیو استفاده کنید.

در صورتی که یک نماد در بیش از یک عضو تعریف شده باشد، ترتیب اعضا در آرشیو می‌تواند در نحوهٔ پیوند خوردن برنامه‌ها با استفاده از کتابخانه تفاوت ایجاد کند.

اگر هیچ تغییردهنده‌ای همراه با "m" به کار نرود، هر عضوی که در آرگومان‌های member نام ببرید به انتهای آرشیو منتقل می‌شود؛ می‌توانید به‌جای آن از تغییردهنده‌های a، b یا i برای انتقال آن‌ها به مکانی مشخص استفاده کنید.

چاپ اعضای مشخص‌شدهٔ آرشیو در فایل خروجی استاندارد. اگر تغییردهندهٔ v مشخص شده باشد، پیش از رونوشت محتوا به خروجی استاندارد، نام عضو نمایش داده می‌شود.

اگر هیچ آرگومان member مشخص نکنید، تمام فایل‌های موجود در آرشیو چاپ می‌شوند.

الحاق سریع؛ از نظر تاریخی، افزودن فایل‌های member... به انتهای archive بدون بررسی برای جایگزینی.

تغییردهنده‌های a، b و i بر این عملیات تاثیری ندارند؛ اعضای جدید همواره در انتهای آرشیو قرار می‌گیرند.

تغییردهندهٔ v باعث می‌شود ar هر فایل را هنگام الحاق‌شدن فهرست کند.

از آن‌جا که هدف این عملیات سرعت است، پیاده‌سازی‌های ar این امکان را دارند که جدول نمادهای آرشیو را (در صورت وجود) به‌روزرسانی نکنند. با این حال، سیستم‌های بسیار متعددی فرض می‌کنند که جدول‌های نماد همیشه به‌روز هستند، بنابراین GNU ar حتی با یک الحاق سریع نیز جدول را بازسازی خواهد کرد.

نکته - GNU ar با دستور qs به‌عنوان مترادفی برای r رفتار می‌کند - جایگزین کردن فایل‌های از پیش موجود در آرشیو و الحاق فایل‌های جدید به انتها.

درج فایل‌های member... در archive (همراه با جایگزینی). تفاوت این عملیات با q در این است که اگر نام اعضای قبلی با نام فایل‌های در حال افزوده‌شدن مطابقت داشته باشد، اعضای قبلی حذف می‌شوند.

اگر یکی از فایل‌های نام‌برده‌شده در member... وجود نداشته باشد، ar یک پیام خطا نمایش می‌دهد و اعضای موجود در آرشیو را که با آن نام مطابقت دارند دست‌نخورده باقی می‌گذارد.

به‌طور پیش‌فرض، اعضای جدید در انتهای فایل اضافه می‌شوند؛ اما می‌توانید از یکی از تغییردهنده‌های a، b یا i برای درخواست جای‌گذاری نسبت به یکی از اعضای موجود استفاده کنید.

تغییردهندهٔ v در صورت استفاده با این عملیات، یک خط خروجی برای هر فایل درج‌شده به همراه یکی از حروف a یا r تولید می‌کند تا مشخص شود فایل الحاق شده است (عضو قدیمی حذف نشده) یا جایگزین گشته است.

افزودن یک نمایه به آرشیو، یا به‌روزرسانی آن در صورت وجود داشتن. توجه داشته باشید این دستور استثنایی بر این قاعده است که تنها یک حرف دستور می‌تواند وجود داشته باشد، چرا که استفاده از آن هم به‌عنوان یک دستور و هم به‌عنوان یک تغییردهنده ممکن است. در هر دو حالت، عمل یکسانی انجام می‌دهد.
نمایش یک جدول از محتویات archive، یا فایل‌های فهرست‌شده در member... که در آرشیو وجود دارند. به‌طور معمول تنها نام عضو نشان داده می‌شود، اما اگر تغییردهندهٔ O مشخص شده باشد، آفست متناظر عضو نیز نمایش می‌یابد. در نهایت، برای دیدن حالت‌ها (مجوزها)، برچسب زمانی، مالک، گروه و اندازه، باید تغییردهندهٔ v گنجانده شود.

اگر هیچ member را مشخص نکنید، تمام فایل‌های موجود در آرشیو فهرست می‌شوند.

اگر بیش از یک فایل با نام یکسان (مثلاً fie) در یک آرشیو (مثلاً b.a) وجود داشته باشد، دستور ar t b.a fie تنها اولین مورد را فهرست می‌کند؛ برای دیدن همهٔ آن‌ها، باید فهرست‌گیری کامل را درخواست کنید---در مثال ما، ar t b.a.

استخراج اعضا (با نام member) از آرشیو. می‌توانید از تغییردهندهٔ v با این عملیات استفاده کنید تا از ar درخواست شود هر نام را هنگام استخراج فهرست کند.

اگر member مشخص نشود، تمام فایل‌های موجود در آرشیو استخراج می‌شوند.

فایل‌ها را نمی‌توان از یک آرشیو کم‌حجم (thin archive) استخراج کرد، و محدودیت‌هایی برای استخراج از آرشیوهای ایجادشده با P وجود دارد: مسیرها نباید مطلق باشند، نباید شامل ".." باشند، و هر زیردایرکتوری موجود در مسیرها باید وجود داشته باشد. در صورت تمایل به اجتناب از این محدودیت‌ها، از گزینهٔ --output برای تعیین دایرکتوری خروجی استفاده کنید.

تعدادی از تغییردهنده‌ها (mod) می‌توانند بلافاصله پس از حرف کلیدی p قرار گیرند تا تغییراتی را در رفتار عملیات مشخص کنند:

افزودن فایل‌های جدید بعد از یکی از اعضای موجود در آرشیو. اگر از تغییردهندهٔ a استفاده کنید، نام یکی از اعضای موجود آرشیو باید به‌عنوان آرگومان relpos، پیش از مشخصهٔ archive آورده شود.
افزودن فایل‌های جدید قبل از یکی از اعضای موجود در آرشیو. اگر از تغییردهندهٔ b استفاده کنید، نام یکی از اعضای موجود آرشیو باید به‌عنوان آرگومان relpos، پیش از مشخصهٔ archive آورده شود (مشابه i).
ایجاد آرشیو. هنگام درخواست به‌روزرسانی، اگر archive مشخص‌شده وجود نداشته باشد، همواره ایجاد می‌شود؛ اما یک هشدار صادر خواهد شد مگر اینکه با استفاده از این تغییردهنده از پیش مشخص کرده باشید که انتظار ایجاد آن را دارید.
کارکرد در حالت قطعیت‌پذیر (deterministic). هنگام افزودن فایل‌ها و نمایهٔ آرشیو، برای UIDها، GIDها و برچسب‌های زمانی از صفر استفاده می‌شود و حالت‌های فایلی یکنواخت برای تمام فایل‌ها به کار می‌رود. با استفاده از این گزینه، چنانچه ar با گزینه‌های یکسان و فایل‌های ورودی یکسان اجرا شود، دفعات مختلف اجرا بدون در نظر گرفتن مالکان، گروه‌ها، حالت‌های فایل یا زمان‌های تغییر فایل‌های ورودی، فایل‌های خروجی کاملاً یکسانی را تولید خواهند کرد.

اگر binutils با --enable-deterministic-archives پیکربندی شده باشد، این حالت به‌طور پیش‌فرض فعال است. این حالت را می‌توان با تغییردهندهٔ U در زیر غیرفعال کرد.

کوتاه کردن نام‌ها در آرشیو. ابزار GNU ar به‌طور معمول نام فایل‌ها را با هر طولی مجاز می‌داند. این کار سبب می‌شود آرشیوهایی ایجاد کند که با برنامهٔ بومی ar در برخی سیستم‌ها سازگار نیستند. اگر این مسئله موجب نگرانی است، می‌توان از تغییردهندهٔ f برای کوتاه کردن نام فایل‌ها هنگام قرار دادن آن‌ها در آرشیو استفاده کرد.
درج فایل‌های جدید قبل از یکی از اعضای موجود در آرشیو. اگر از تغییردهندهٔ i استفاده کنید، نام یکی از اعضای موجود آرشیو باید به‌عنوان آرگومان relpos، پیش از مشخصهٔ archive آورده شود (مشابه b).
مشخص کردن وابستگی‌های این کتابخانه. وابستگی‌ها باید بلافاصله پس از این نویسهٔ گزینه بیایند، باید از همان ساختار نحوی خط فرمان پیونددهنده استفاده کنند و باید درون یک آرگومان واحد مشخص شوند. یعنی اگر به چند مورد نیاز باشد، باید برای تشکیل یک آرگومان خط فرمان واحد در گیومه قرار گیرند. برای نمونه: l "-L/usr/local/lib -lmydep1 -lmydep2"
استفاده از پارامتر count. این تغییردهنده زمانی استفاده می‌شود که چندین مدخل با نام یکسان در آرشیو وجود داشته باشد. نمونهٔ شمارهٔ count از نام مشخص‌شده را از آرشیو استخراج یا حذف می‌کند.
حفظ تاریخ‌های اصلی اعضا هنگام استخراج آن‌ها. اگر این تغییردهنده را مشخص نکنید، فایل‌های استخراج‌شده از آرشیو با زمان استخراج برچسب زمانی می‌خورند.
نمایش آفست‌های عضو در داخل آرشیو. همراه با گزینهٔ t استفاده می‌شود..IP P 4 هنگام تطبیق یا ذخیره کردن نام‌ها در آرشیو، از نام کامل مسیر استفاده می‌کند. آرشیوهایی که با نام کامل مسیر ایجاد می‌شوند با POSIX سازگار نیستند، و بنابراین ممکن است با ابزارهایی غیر از ابزارهای به‌روز GNU کار نکنند. تغییر چنین آرشیوهایی با GNU ar بدون استفاده از P نام‌های کامل مسیر را حذف خواهد کرد، مگر اینکه آرشیو از نوع thin archive باشد. توجه داشته باشید که P ممکن است هنگام افزودن فایل‌ها به یک thin archive مفید باشد زیرا r بدون P مسیر را هنگام انتخاب این که کدام عنصر جایگزین شود نادیده می‌گیرد. بنابراین 
ar rcST archive.a subdir/file1 subdir/file2 file1

منجر به این خواهد شد که اولین "subdir/file1" با "file1" از دایرکتوری جاری جایگزین شود. افزودن P از این جایگزینی جلوگیری خواهد کرد.

یک نمایه از فایل‌های شیء را در آرشیو می‌نویسد، یا نمایه موجود را به‌روزرسانی می‌کند، حتی اگر هیچ تغییر دیگری در آرشیو ایجاد نشده باشد. می‌توانید از این پرچم اصلاح‌گر با هر عملیاتی، یا به‌تنهایی استفاده کنید. اجرای ar s روی یک آرشیو معادل اجرای ranlib روی آن است.
جدول نمادهای آرشیو را ایجاد نمی‌کند. این کار می‌تواند ساخت یک کتابخانه بزرگ را در چندین مرحله تسریع کند. آرشیو حاصل را نمی‌توان با پیونددهنده (linker) استفاده کرد. برای ایجاد جدول نمادها، باید در آخرین اجرای ar اصلاح‌گر S را حذف کنید، یا باید ranlib را روی آرشیو اجرا نمایید.
نام مستعار منسوخ‌شده برای --thin. استفاده از T توصیه نمی‌شود زیرا در بسیاری از پیاده‌سازی‌های ar، طبق مشخصات X/Open System Interface، T معنای متفاوتی دارد.
به‌طور معمول، ...ar r تمام فایل‌های فهرست‌شده را در آرشیو درج می‌کند. اگر می‌خواهید تنها آن دسته از فایل‌های فهرست‌شده که از اعضای موجود با همان نام جدیدتر هستند درج شوند، از این اصلاح‌گر استفاده کنید. اصلاح‌گر u فقط برای عملیات r (جایگزینی) مجاز است. به‌ویژه، ترکیب qu مجاز نیست، زیرا بررسی برچسب‌های زمانی، هرگونه مزیت سرعتی ناشی از عملیات q را از بین می‌برد.

توجه - اگر آرشیو به روش قطعی (deterministic) ایجاد شده باشد، مثلاً با استفاده از اصلاح‌گر D، جایگزینی همیشه انجام خواهد شد و اصلاح‌گر u بی‌اثر خواهد بود.

در حالت قطعی (deterministic) عمل نمی‌کند. این برعکس اصلاح‌گر D در بالا است: فایل‌های اضافه‌شده و نمایه آرشیو مقادیر واقعی UID، GID، برچسب زمانی و حالت فایل (file mode) خود را دریافت می‌کنند.

این حالت پیش‌فرض است مگر اینکه binutils با --enable-deterministic-archives پیکربندی شده باشد.

این اصلاح‌گر نسخه پُرگو (verbose) یک عملیات را درخواست می‌کند. با افزودن اصلاح‌گر v، بسیاری از عملیات‌ها اطلاعات اضافی، مانند نام فایل‌های پردازش‌شده را نمایش می‌دهند.
این اصلاح‌گر شماره نسخه ar را نمایش می‌دهد.

برنامه ar همچنین از برخی گزینه‌های خط فرمان پشتیبانی می‌کند که نه اصلاح‌گر هستند و نه عمل، اما رفتار آن را به روش‌های خاصی تغییر می‌دهند:

فهرست گزینه‌های خط فرمان پشتیبانی‌شده توسط ar را نمایش می‌دهد و سپس خارج می‌شود.
اطلاعات نسخه ar را نمایش می‌دهد و سپس خارج می‌شود.
دستور ar گزینه اولیه‌ای با نام -X32_64 را جهت سازگاری با AIX نادیده می‌گیرد. رفتاری که توسط این گزینه حاصل می‌شود، برای GNU ar پیش‌فرض است. ar از هیچ‌یک از سایر گزینه‌های -X پشتیبانی نمی‌کند؛ به‌ویژه، از -X32 که پیش‌فرض AIX ar است پشتیبانی نمی‌کند.
سوئیچ اختیاری خط فرمان --plugin name باعث می‌شود ar افزونه‌ای به نام name را بارگیری کند که پشتیبانی از فرمت‌های فایل بیشتری را اضافه می‌کند، از جمله فایل‌های شیء حاوی اطلاعات بهینه‌سازی زمان پیوند (LTO).

این گزینه تنها زمانی در دسترس است که زنجیره ابزار (toolchain) همراه با پشتیبانی از افزونه ساخته شده باشد.

اگر --plugin ارائه نشود، اما پشتیبانی از افزونه فعال باشد، ar روی فایل‌های موجود در ${libdir}/bfd-plugins به ترتیب الفبایی پیمایش کرده و اولین افزونه‌ای که مسئولیت شیء مربوطه را بپذیرد استفاده می‌شود.

لطفاً توجه داشته باشید که این دایرکتوری جستجوی افزونه، با دایرکتوری مورد استفاده توسط گزینه -plugin در ld یکسان نیست. برای این که ar بتواند از افزونه پیونددهنده استفاده کند، باید در دایرکتوری ${libdir}/bfd-plugins کپی شود. برای کامپایل‌های مبتنی بر GCC افزونه پیونددهنده liblto_plugin.so.0.0.0 نام دارد. برای کامپایل‌های مبتنی بر Clang نام آن LLVMgold.so است. افزونه GCC همیشه با نسخه‌های پیشین سازگار است، بنابراین فقط کپی کردن جدیدترین نسخه کافی خواهد بود.

سوئیچ اختیاری خط فرمان --target bfdname مشخص می‌کند که اعضای آرشیو در فرمت کد شیئی متفاوتی از فرمت پیش‌فرض سیستم شما هستند. ببینید
از گزینه --output می‌توان برای مشخص کردن مسیری به یک دایرکتوری استفاده کرد که اعضای آرشیو باید در آن استخراج شوند. اگر این گزینه مشخص نشود، از دایرکتوری جاری استفاده خواهد شد.

توجه - هرچند وجود این گزینه به‌طور ضمنی بیانگر عملیات استخراج x است، اما آن گزینه همچنان باید در خط فرمان گنجانده شود.

گزینه --record-libdeps دقیقاً مشابه اصلاح‌گر l است، تنها به شکل طولانی به کار می‌رود.
آرشیو مشخص‌شده با archive را به یک آرشیو thin تبدیل می‌کند. اگر این فایل از قبل وجود داشته باشد و یک آرشیو معمولی باشد، اعضای موجود باید در همان دایرکتوری archive حضور داشته باشند.
@file
گزینه‌های خط فرمان را از file می‌خواند. گزینه‌های خوانده‌شده به‌جای گزینه اصلی @file جایگزین می‌شوند. اگر file وجود نداشته باشد، یا نتوان آن را خواند، با گزینه به‌صورت تحت‌اللفظی برخورد می‌شود و حذف نخواهد شد.

گزینه‌ها در file با نویسه فاصله (whitespace) از یکدیگر جدا می‌شوند. می‌توان یک نویسه فاصله را با محصور کردن کل گزینه در نقل‌قول تکی یا دوتایی درون آن قرار داد. هر نویسه‌ای (از جمله بک‌اسلش) را می‌توان با افزودن پیشوند بک‌اسلش به نویسه مورد نظر، درج کرد. خود file ممکن است شامل گزینه‌های اضافی @file باشد؛ چنین گزینه‌هایی به‌صورت بازگشتی پردازش خواهند شد..SH "همچنین ببینید (SEE ALSO)" nm(1)، ranlib(1) و مدخل‌های Info برای binutils.

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

اجازهٔ نسخه‌برداری، توزیع و/یا تغییر این سند تحت شرایط «مجوز مستندات آزاد گنو» (GNU Free Documentation License)، نسخهٔ 1.3 یا هر نسخهٔ متأخر دیگری که توسط بنیاد نرم‌افزارهای آزاد (Free Software Foundation) منتشر شده است، با رعایت این شرط که سند فاقد هرگونه بخشِ تغییرناپذیر (Invariant Sections)، فاقد متن روی جلد (Front-Cover Texts)، و فاقد متن پشت جلد (Back-Cover Texts) باشد، اعطا می‌شود. یک نسخه از این مجوز در بخشی با عنوان «GNU Free Documentation License» گنجانده شده است.

2026-01-23 binutils-2.45.1