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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

از این عملیات برای جابه‌جایی (move) اعضا در بایگانی استفاده کنید.

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

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

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

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

الحاق سریع (Quick append)؛ از نظر تاریخی، افزودن فایل‌های ...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.

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

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

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

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

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

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

کوتاه کردن (truncate) نام‌ها در بایگانی. ابزار 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 باشد. توجه داشته باشید که P ممکن است هنگام افزودن فایل‌ها به یک آرشیو thin مفید باشد، زیرا r بدون P هنگام انتخاب عنصری که باید جایگزین شود، مسیر را نادیده می‌گیرد. بنابراین 
ar rcST archive.a subdir/file1 subdir/file2 file1

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

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

این حالت پیش‌فرض است مگر اینکه 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).

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

اگر --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 با نویسه‌های فاصله از یکدیگر جدا می‌شوند. یک نویسه فاصله را می‌توان با قرار دادن کل گزینه درون علامت نقل‌قول تکی یا جفتی در گزینه گنجاند. هر نویسه‌ای (از جمله بک‌اسلش) را می‌توان با افزودن یک بک‌اسلش به عنوان پیشوند به آن نویسه، درج کرد. خود file می‌تواند شامل گزینه‌های @file بیشتری باشد؛ هر یک از این گزینه‌ها به‌طور بازگشتی پردازش خواهند شد..SH "همچنین ببینید (SEE ALSO)" nm(1)، ranlib(1) و مدخل‌های Info برای binutils.

کپی‌رایت (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