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

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

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

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

آرشیوهای thin همچنین به‌صورت مسطح هستند؛ به طوری که افزودن یک آرشیو 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).
تعیین وابستگی‌های این کتابخانه. وابستگی‌ها باید بلافاصله پس از نویسهٔ این گزینه بیایند، باید از همان قواعد نحوی خط فرمان پیونددهنده استفاده کنند و باید درون یک آرگومان واحد مشخص شوند. یعنی اگر به چندین مورد نیاز است، باید درون نقل‌قول قرار گیرند تا یک آرگومان خط فرمان منفرد را تشکیل دهند. برای نمونه: l "-L/usr/local/lib -lmydep1 -lmydep2"
استفاده از پارامتر count. این مورد زمانی استفاده می‌شود که چندین مدخل با نام یکسان در آرشیو وجود داشته باشند. نمونهٔ countام از نام داده‌شده را از آرشیو استخراج یا حذف می‌کند.
حفظ تاریخ‌های اصلی اعضا هنگام استخراج آن‌ها. اگر این تغییردهنده را مشخص نکنید، فایل‌های استخراج‌شده از آرشیو با زمان استخراج برچسب زمانی می‌خورند.
نمایش آفست‌های اعضا درون آرشیو. همراه با گزینهٔ t استفاده می‌شود.
استفاده از نام کامل مسیر هنگام تطبیق یا ذخیرهٔ نام‌ها در آرشیو. آرشیوهای ایجادشده با نام‌های کامل مسیر با استاندارد 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 جلوی این جایگزینی را خواهد گرفت.

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

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

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

این حالت پیش‌فرض است، مگر اینکه binutils با --enable-deterministic-archives پیکربندی شده باشد.

این تغییردهنده نسخهٔ همراه با جزئیات (verbose) یک عملیات را درخواست می‌کند. با افزودن تغییردهندهٔ v، بسیاری از عملیات‌ها اطلاعات اضافی مانند نام فایل‌های پردازش‌شده را نمایش می‌دهند.
این تغییردهنده شماره نسخهٔ ar را نمایش می‌دهد.

برنامهٔ ar همچنین از برخی گزینه‌های خط فرمان پشتیبانی می‌کند که نه تغییردهنده هستند و نه کنش (action)، اما رفتار آن را به شیوه‌های معینی تغییر می‌دهند:

فهرست گزینه‌های خط فرمان پشتیبانی‌شده توسط ar را نمایش می‌دهد و سپس خارج می‌شود.
اطلاعات نسخهٔ ar را نمایش می‌دهد و سپس خارج می‌شود.
برنامهٔ ar برای سازگاری با AIX، گزینهٔ ابتدایی با نگارش -X32_64 را نادیده می‌گیرد. رفتاری که با این گزینه ایجاد می‌شود، رفتار پیش‌فرض 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 همیشه با نسخه‌های پیشین سازگار به عقب است، بنابراین تنها کپی کردن جدیدترین نسخه کفایت می‌کند.

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

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

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

گزینه‌ها در 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)؛ بدون بخش‌های تغییرناپذیر، بدون متون روی جلد، و بدون متون پشت جلد، اعطا می‌شود. نسخه‌ای از این مجوز در بخشی با عنوان “GNU Free Documentation License” گنجانده شده است.

2026-01-23 binutils-2.45.1