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

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

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

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

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

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

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

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

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

مسیرهای اجزای بایگانی به صورت نسبی با خود بایگانی ذخیره می‌شوند.

ابزار 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).
مشخص کردن وابستگی‌های این کتابخانه. وابستگی‌ها باید بلافاصله پس از این نویسه گزینه بیایند، باید از همان نحو خط فرمان پیونددهنده (linker) استفاده کنند، و باید در یک آرگومان واحد مشخص شوند. به این معنی که اگر چندین مورد نیاز باشد، باید درون علامت نقل‌قول قرار گیرند تا یک آرگومان واحد خط فرمان را تشکیل دهند. برای مثال l "-L/usr/local/lib -lmydep1 -lmydep2"
استفاده از پارامتر count. این زمانی استفاده می‌شود که چندین مدخل با نام یکسان در بایگانی وجود داشته باشد. مورد countام از نام داده‌شده را از بایگانی استخراج یا حذف می‌کند.
حفظ تاریخ‌های اصلی اعضا هنگام استخراج آن‌ها. اگر این اصلاح‌کننده را مشخص نکنید، فایل‌های استخراج‌شده از بایگانی با زمان استخراج نشانه‌گذاری می‌شوند.
نمایش آفست‌های اعضا درون بایگانی. همراه با گزینه t استفاده می‌شود.
استفاده از نام مسیر کامل هنگام تطبیق یا ذخیره نام‌ها در بایگانی. بایگانی‌های ایجادشده با نام مسیر کامل، سازگار با استاندارد POSIX نیستند و بنابراین ممکن است با ابزارهایی غیر از ابزارهای به‌روز GNU کار نکنند. ویرایش چنین بایگانی‌هایی با GNU ar بدون استفاده از P نام‌های مسیر کامل را حذف خواهد کرد، مگر اینکه بایگانی یک بایگانی نازک (thin archive) باشد. توجه داشته باشید که P ممکن است هنگام افزودن فایل‌ها به یک بایگانی نازک مفید باشد، زیرا r بدون P هنگام انتخاب عنصری که باید جایگزین شود، مسیر را نادیده می‌گیرد. بنابراین 
ar rcST archive.a subdir/file1 subdir/file2 file1

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

نوشتن یک نمایه فایل شیء (object-file) درون بایگانی، یا به‌روزرسانی نمایه موجود، حتی اگر هیچ تغییر دیگری در بایگانی ایجاد نشده باشد. می‌توانید از این پرچم اصلاح‌کننده همراه با هر عملیاتی یا به تنهایی استفاده کنید. اجرای ar s بر روی یک بایگانی معادل اجرای ranlib بر روی آن است..IP S 4 جدول نمادهای آرشیو را تولید نکن. این کار می‌تواند ساخت یک کتابخانهٔ بزرگ را در چند مرحله سرعت ببخشد. آرشیو حاصل را نمی‌توان به همراه پیونددهنده (linker) استفاده کرد. برای ساخت جدول نمادها، باید در آخرین اجرای ar از اصلاح‌کنندهٔ S صرف‌نظر کنید، یا اینکه ranlib را بر روی آرشیو اجرا نمایید.
نام مستعار منسوخ‌شده برای --thin. استفاده از T توصیه نمی‌شود چرا که در بسیاری از پیاده‌سازی‌های ar، طبق مشخصات X/Open System Interface، معنای متفاوتی دارد.
به‌طور معمول، 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 که پیش‌فرض ar در AIX است، پشتیبانی نمی‌کند.
سوئیچ اختیاری خط فرمان --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 همیشه با نسخه‌های قبلی سازگار با گذشته است، بنابراین کپی کردن جدیدترین نسخه کافی خواهد بود.

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

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

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

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

nm(1)، ranlib(1)، و مدخل‌های Info برای binutils..SH "کپی‌رایت و تکثیر (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