نام (NAME)

ar - ایجاد، ویرایش و استخراج از آرشیوها

خلاصه دستور (SYNOPSIS)

ar [-X32_64] [-]p[mod] [--plugin name] [--target bfdname] [--output dirname] [--record-libdeps libdeps] [--thin] [relpos] [count] archive [member...]

توضیحات (DESCRIPTION)

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

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

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

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

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

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

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

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

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

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

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

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

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

d

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

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

m

از این عملیات برای انتقال (move) اعضا درون یک آرشیو استفاده کنید.

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

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

p

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

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

q

الحاق سریع (Quick append)؛ از لحاظ تاریخی، فایل‌های member... را بدون بررسی برای جایگزینی، به انتهای archive اضافه می‌کند.

تغییردهنده‌های a، b و i بر این عملیات تاثیری not (ندارند)؛ اعضای جدید همواره در انتهای آرشیو قرار می‌گیرند.

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

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

نکته - GNU ar دستور qs را به‌عنوان مترادفی برای r در نظر می‌گیرد - جایگزین کردن فایل‌های از پیش موجود در آرشیو و الحاق فایل‌های جدید به انتها.

r

درج فایل‌های member... درون archive (همراه با جایگزینی یا replacement). این عملیات با q از این نظر تفاوت دارد که اگر نام اعضای از پیش موجود با نام فایل‌های در حال اضافه شدن یکسان باشد، آن اعضا حذف می‌شوند.

اگر یکی از فایل‌های نام‌برده در member... وجود نداشته باشد، ar یک پیام خطا نمایش می‌دهد و هیچ‌یک از اعضای موجود در آرشیو را که با آن نام همخوانی دارند تغییر نمی‌دهد.

به‌طور پیش‌فرض، اعضای جدید در انتهای فایل اضافه می‌شوند؛ اما می‌توانید از یکی از تغییردهنده‌های a، b یا i برای درخواست جای‌گذاری نسبت به عضوی موجود استفاده کنید.

استفاده از تغییردهندهٔ v با این عملیات، یک خط خروجی به ازای هر فایل درج‌شده به همراه یکی از حروف a یا r تولید می‌کند تا مشخص شود فایل الحاق شده است (عضو قدیمی حذف نشده) یا جایگزین گشته است.

s

افزودن نمایه‌ای به آرشیو، یا به‌روزرسانی آن در صورت وجود. توجه داشته باشید که این دستور استثنایی بر این قاعده است که تنها می‌تواند یک حرف دستور وجود داشته باشد، زیرا می‌توان آن را چه به‌صورت دستور و چه به‌صورت یک تغییردهنده به کار برد. در هر دو حالت، عمل یکسانی انجام می‌دهد.

t

نمایش جدولی (table) از فهرست محتویات archive، یا فایل‌های فهرست‌شده در member... که در آرشیو حاضر هستند. معمولاً فقط نام عضو نمایش داده می‌شود، اما اگر تغییردهندهٔ O مشخص شود، آفست متناظر با عضو نیز نمایش داده خواهد شد. در نهایت، برای مشاهدهٔ حالت‌ها (مجوزها)، برچسب زمانی، مالک، گروه، و اندازه، تغییردهندهٔ v باید قید شود.

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

اگر بیش از یک فایل با نام یکسان (مثلاً fie) در آرشیو (مثلاً b.a) وجود داشته باشد، دستور ar t b.a fie تنها اولین مورد را فهرست می‌کند؛ برای مشاهدهٔ همهٔ آن‌ها، باید یک فهرست‌بندی کامل درخواست کنید---در مثال ما، ar t b.a.

x

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

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

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

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

a

افزودن فایل‌های جدید پس از (after) یک عضو موجود در آرشیو. اگر از تغییردهندهٔ a استفاده کنید، نام یک عضو موجود در آرشیو باید به‌عنوان آرگومان relpos، پیش از مشخصهٔ archive ارائه شود.

b

افزودن فایل‌های جدید پیش از (before) یک عضو موجود در آرشیو. اگر از تغییردهندهٔ b استفاده کنید، نام یک عضو موجود در آرشیو باید به‌عنوان آرگومان relpos، پیش از مشخصهٔ archive ارائه شود (همانند i).

c

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

D

عملکرد در حالت قطعی (deterministic). هنگام افزودن فایل‌ها و نمایهٔ آرشیو، برای UIDها، GIDها و برچسب‌های زمانی از صفر استفاده می‌کند، و حالت‌های فایل یکسانی را برای تمام فایل‌ها به کار می‌گیرد. هنگامی که این گزینه استفاده می‌شود، اگر ar با گزینه‌های یکسان و فایل‌های ورودی یکسان اجرا شود، اجراهای چندگانه بدون در نظر گرفتن مالکان، گروه‌ها، حالت‌های فایل یا زمان‌های ویرایش فایل‌های ورودی، خروجی‌های کاملاً یکسانی ایجاد خواهند کرد.

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

f

کوتاه کردن نام‌ها در آرشیو. GNU ar معمولاً نام‌های فایل با هر طولی را می‌پذیرد. این امر موجب می‌شود آرشیوهایی ایجاد کند که با برنامهٔ بومی ar در برخی سیستم‌ها سازگار نیستند. اگر این مسئله نگران‌کننده است، می‌توان از تغییردهندهٔ f برای کوتاه کردن نام فایل‌ها هنگام قرار دادن آن‌ها در آرشیو استفاده کرد.

i

درج فایل‌های جدید پیش از (before) یک عضو موجود در آرشیو. اگر از تغییردهندهٔ i استفاده کنید، نام یک عضو موجود در آرشیو باید به‌عنوان آرگومان relpos، پیش از مشخصهٔ archive ارائه شود (همانند b).

l

مشخص کردن وابستگی‌های این کتابخانه. وابستگی‌ها باید بلافاصله پس از این نویسهٔ گزینه بیایند، باید از همان نحو خط فرمان پیونددهنده استفاده کنند، و باید درون یک آرگومان واحد مشخص شوند؛ یعنی در صورت نیاز به چند مورد، باید آن‌ها را داخل علامت نقل‌قول قرار داد تا یک آرگومان خط فرمان تکی تشکیل شود. برای نمونه l "-L/usr/local/lib -lmydep1 -lmydep2"

N

از پارامتر count استفاده می‌کند. این مورد زمانی استفاده می‌شود که چندین مدخل با نام یکسان در آرشیو وجود داشته باشد. مورد شمارهٔ count از نام ارائه‌شده را از آرشیو استخراج یا حذف می‌کند.

o

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

O

نمایش آفست اعضا درون آرشیو. همراه با گزینهٔ t استفاده می‌شود.

P

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

s

نوشتن نمایهٔ فایل هدف درون آرشیو، یا به‌روزرسانی نمونهٔ موجود، حتی اگر هیچ تغییر دیگری در آرشیو ایجاد نشود. می‌توانید از این پرچم تغییردهنده چه به همراه هر عملیاتی و چه به‌تنهایی استفاده کنید. اجرای ar s روی یک آرشیو معادل اجرای ranlib بر روی آن است..IP S 4 جدول نمادهای آرشیو را ایجاد نمی‌کند. این کار می‌تواند ساخت یک کتابخانهٔ بزرگ در چند مرحله را سرعت بخشد. آرشیو حاصل را نمی‌توان همراه با پیونددهنده استفاده کرد. برای ساخت جدول نمادها، باید در آخرین اجرای ar از اصلاح‌کنندهٔ S صرف‌نظر کنید، یا این‌که ranlib را روی آرشیو اجرا نمایید.

T

یک نام مستعار منسوخ‌شده برای --thin. استفاده از T توصیه نمی‌شود زیرا در بسیاری از پیاده‌سازی‌های ar، طبق آنچه توسط X/Open System Interface مشخص شده است، T معنی متفاوتی دارد.

u

به‌طور معمول، دستور ...ar r تمام فایل‌های فهرست‌شده را درون آرشیو قرار می‌دهد. اگر می‌خواهید تنها فایل‌هایی را درج کنید که از اعضای هم‌نامِ موجود جدیدتر هستند، از این اصلاح‌کننده استفاده کنید. اصلاح‌کنندهٔ u تنها برای عملیات r (جایگزینی) مجاز است. به‌طور خاص، ترکیب qu مجاز نیست، زیرا بررسی برچسب‌های زمانی، هرگونه مزیت سرعتی حاصل از عملیات q را از بین می‌برد.

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

U

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

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

v

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

V

این اصلاح‌کننده شماره نسخهٔ ar را نمایش می‌دهد.

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

--help

فهرست گزینه‌های خط فرمان پشتیبانی‌شده توسط ar را نمایش می‌دهد و سپس خارج می‌شود.

--version

اطلاعات نسخهٔ ar را نمایش می‌دهد و سپس خارج می‌شود.

-X32_64

دستور ar برای سازگاری با AIX، گزینهٔ ابتدایی به شکل -X32_64 را نادیده می‌گیرد. رفتار حاصل از این گزینه، حالت پیش‌فرض در GNU ar است. ar از هیچ‌یک از گزینه‌های دیگر -X پشتیبانی نمی‌کند؛ به‌ویژه، از -X32 که پیش‌فرض برای AIX ar است پشتیبانی نمی‌کند.

--plugin name

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

--target target

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

--output dirname

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

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

--record-libdeps libdeps

گزینهٔ --record-libdeps کاملاً همانند اصلاح‌کنندهٔ l است، و صرفاً در قالب بلند به کار می‌رود.

--thin

archive مشخص‌شده را به یک آرشیو thin تبدیل می‌کند. اگر آرشیو از قبل وجود داشته باشد و یک آرشیو معمولی باشد، اعضای موجود باید در همان دایرکتوریِ archive حضور داشته باشند.

@file

گزینه‌های خط فرمان را از file می‌خواند. گزینه‌های خوانده‌شده به جای گزینهٔ اصلی @file قرار می‌گیرند. اگر file وجود نداشته باشد یا قابل خواندن نباشد، با این گزینه به عنوان یک عبارت لفظی برخورد می‌شود و حذف نخواهد شد.

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

همچنین ببینید (SEE ALSO)

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” آمده است.