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]

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

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

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

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

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

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

ابزار گنو ar می‌تواند به‌صورت اختیاری یک آرشیو نازک (thin archive) ایجاد کند که حاوی نمایه نماد و ارجاعاتی به نسخه‌های اصلی فایل‌های عضو آرشیو است. این ویژگی برای ساخت کتابخانه‌ها جهت استفاده درون درخت ساخت محلی (local build tree) مفید است، جایی که انتظار می‌رود اشیای جابه‌جاشونده در دسترس باقی بمانند و کپی کردن محتوای هر شیء صرفاً باعث هدر رفتن زمان و فضا می‌شود.

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

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

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

ابزار گنو ar طوری طراحی شده است که با دو شیوه مختلف سازگار باشد. می‌توانید فعالیت آن را با استفاده از گزینه‌های خط فرمان کنترل کنید، مانند انواع مختلف ar در سیستم‌های یونیکس؛ یا اگر گزینه تک خط فرمانی -M را مشخص کنید، می‌توانید آن را با یک اسکریپت که از طریق ورودی استاندارد ارائه می‌شود کنترل کنید، مانند برنامه کتابخانه‌دار (librarian) در MRI.

ابزار گنو ar به شما اجازه می‌دهد که کد عملیات p و پرچم‌های اصلاح‌کننده mod را به هر ترتیبی درون اولین آرگومان خط فرمان ترکیب کنید.

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

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

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

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

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

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

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

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

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

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

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

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

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

نکته - ابزار گنو 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 را مشخص نکنید، تمام فایل‌های موجود در آرشیو استخراج می‌شوند.

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

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

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

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

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

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

نوشتن نمایه فایل‌های شیء درون آرشیو یا به‌روزرسانی نمایه موجود، حتی اگر هیچ تغییر دیگری در آرشیو ایجاد نشود. می‌توانید این پرچم اصلاح‌کننده را همراه با هر عملیاتی یا به‌تنهایی استفاده کنید. اجرای ar s روی یک آرشیو معادل اجرای ranlib روی آن است.
تولید نکردن جدول نمادهای آرشیو. این کار می‌تواند ساخت یک کتابخانه بزرگ در چندین مرحله را سرعت بخشد، اما در صورتی که آرشیو حاصل با پیونددهنده استفاده شود تأثیر منفی بر کارایی خواهد گذاشت. برای ساخت جدول نماد، باید اصلاح‌کننده S را در آخرین اجرای ar حذف کنید، یا اینکه ranlib را روی آرشیو اجرا نمایید.
نام مستعار منسوخ‌شده برای --thin. استفاده از T توصیه نمی‌شود، زیرا در بسیاری از پیاده‌سازی‌های ar، همان‌طور که توسط رابط سیستم X/Open مشخص شده، 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 نادیده می‌گیرد. رفتاری که توسط این گزینه ایجاد می‌شود، حالت پیش‌فرض در گنو ar است. ابزار ar از هیچ‌یک از گزینه‌های دیگر -X پشتیبانی نمی‌کند؛ به‌ویژه، از -X32 که پیش‌فرض ar در AIX است پشتیبانی نمی‌کند.
سوییچ خط فرمان اختیاری --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 همواره با نسخه‌های قبلی سازگار به عقب (backwards compatible) است، بنابراین کپی کردن جدیدترین نسخه آن کافی است.

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

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

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

گزینه‌ها در file با نویسه‌های فاصله خالی از یکدیگر جدا می‌شوند. یک نویسه فاصله خالی می‌تواند با قرار دادن کل گزینه درون علامت نقل‌قول تکی یا دوتایی، در گزینه گنجانده شود. هر نویسه‌ای (از جمله بک‌اسلش) را می‌توان با قرار دادن یک بک‌اسلش پیش از آن درج کرد. خود file ممکن است شامل گزینه‌های اضافی @file باشد؛ چنین گزینه‌هایی به‌صورت بازگشتی پردازش خواهند شد.

nm(1)، ranlib(1)، و مدخل‌های Info برای binutils.

کپی‌رایت © 1991-2026 بنیاد نرم‌افزار آزاد (Free Software Foundation, Inc.)

اجازه کپی، توزیع و/یا تغییر این سند تحت شرایط «مجوز مستندات آزاد گنو» (GNU Free Documentation License)، نسخه ۱.۳ یا هر نسخه بعدی منتشرشده توسط بنیاد نرم‌افزار آزاد اعطا می‌شود؛ بدون بخش‌های تغییرناپذیر، بدون متون روی جلد، و بدون متون پشت جلد. یک نسخه از این مجوز در بخشی با عنوان «GNU Free Documentation License» گنجانده شده است.

2026-08-11 binutils-2.47