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...] ar -M [< mri-script]

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

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

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

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

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

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

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

یک آرشیو می‌تواند یا thin (کم‌حجم) باشد یا عادی. نمی‌تواند همزمان هر دو باشد. پس از ایجاد آرشیو، قالب آن بدون حذف اولیه و سپس ایجاد آرشیو جدیدی به جای آن، قابل تغییر نیست.

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

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

ابزار GNU ar به گونه‌ای طراحی شده است که با دو شیوهٔ کارکرد مختلف سازگار باشد. شما می‌توانید فعالیت آن را با استفاده از گزینه‌های خط فرمان، مانند انواع مختلف ar در سیستم‌های Unix کنترل کنید؛ یا چنانچه گزینهٔ تک‌حرفی خط فرمان -M را مشخص نمایید، می‌توانید آن را با اسکریپتی که از طریق ورودی استاندارد ارائه می‌شود، مانند برنامهٔ MRI "librarian" هدایت کنید..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). هنگام افزودن فایل‌ها و نمایهٔ آرشیو، برای UIDs، GIDs و برچسب‌های زمانی از صفر استفاده کنید و برای همهٔ فایل‌ها حالت‌های فایل سازگار به کار ببرید. وقتی از این گزینه استفاده شود، اگر 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 ممکن است هنگام افزودن فایل‌ها به یک آرشیو نازک مفید باشد، زیرا r بدون P مسیر را هنگام انتخاب عضوی که باید جایگزین شود نادیده می‌گیرد. بنابراین 
ar rcST archive.a subdir/file1 subdir/file2 file1

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

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

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

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

این حالت پیش‌فرض است مگر اینکه 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 را بارگیری کند که پشتیبانی از قالب‌های فایل بیشتری را اضافه می‌کند، از جمله فایل‌های شیء با اطلاعات بهینه‌سازی زمان پیوند (link-time optimization).

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

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

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

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

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

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

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

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

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

2026-08-31 binutils-2.47