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

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

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

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

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

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

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

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

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

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

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

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

حرف کلیدی 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 استخراج کرد، و همچنین محدودیت‌هایی در استخراج از آرشیوهای ایجادشده با 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).
مشخص کردن وابستگی‌های این کتابخانه. وابستگی‌ها باید بلافاصله پس از این نویسهٔ گزینه بیایند، باید از ساختار نحوی مشابه خط فرمان linker استفاده کنند، و باید درون یک آرگومان واحد مشخص شوند؛ به این معنی که اگر چندین مورد نیاز است، باید نقل‌قول شوند تا یک آرگومان خط فرمان واحد را تشکیل دهند. برای مثال 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 مانع از این جایگزینی خواهد شد.

یک نمایهٔ فایل شیء (object-file index) را درون آرشیو می‌نویسد، یا نمایهٔ موجود را به‌روزرسانی می‌کند، حتی اگر هیچ تغییر دیگری در آرشیو ایجاد نشده باشد. می‌توانید از این پرچمِ تغییردهنده همراه با هر عملیاتی، یا به‌تنهایی استفاده کنید. اجرای ar s روی یک آرشیو معادل اجرای ranlib روی آن است.
جدول نمادهای آرشیو را ایجاد نمی‌کند. این کار می‌تواند ساخت یک کتابخانهٔ بزرگ را در چندین مرحله سرعت ببخشد. آرشیو حاصل را نمی‌توان با پیونددهنده (linker) استفاده کرد. برای ساخت جدول نمادها، باید تغییردهندهٔ S را در آخرین اجرای ar حذف کنید، یا باید 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 برای سازگاری با AIX، گزینهٔ ابتدایی با نام -X32_64 را نادیده می‌گیرد. رفتاری که این گزینه ایجاد می‌کند، برای 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 همیشه با نسخه‌های پیشین سازگار به عقب (backwards compatible) است، بنابراین کپی کردن جدیدترین نسخه کافی خواهد بود.

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

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

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

گزینه‌ها در 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