نام (NAME)

ar - ایجاد، تغییر و استخراج فایل‌ها از بایگانی‌ها

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

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

توضیحات (DESCRIPTION)

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

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

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

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

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

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

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

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

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

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

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

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

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

d

حذف کردن پودمان‌ها از بایگانی. نام پودمان‌هایی را که باید حذف شوند به صورت member... مشخص کنید؛ اگر فایلی را برای حذف مشخص نکنید، بایگانی دست‌نخورده باقی می‌ماند.

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

m

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

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

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

p

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

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

q

الحاق سریع؛ از لحاظ تاریخی، افزودن فایل‌های member... به انتهای archive، بدون بررسی برای جایگزینی.

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

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

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

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

r

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

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

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

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

s

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

t

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

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

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

x

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

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

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

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

a

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

b

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

c

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

D

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

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

f

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

i

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

l

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

N

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

o

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

O

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

P

استفاده از نام کامل مسیر هنگام تطبیق یا ذخیرهٔ نام‌ها در بایگانی. بایگانی‌های ایجادشده با نام مسیر کامل سازگار با POSIX نیستند، و بنابراین ممکن است با ابزارهایی به جز ابزارهای به‌روز GNU کار نکنند. تغییر چنین بایگانی‌هایی با GNU ar بدون استفاده از P نام‌های مسیر کامل را حذف خواهد کرد، مگر اینکه بایگانی یک بایگانی باریک باشد. توجه داشته باشید که P ممکن است هنگام افزودن فایل‌ها به یک بایگانی باریک مفید باشد، زیرا r بدون P هنگام انتخاب عنصری که باید جایگزین شود، مسیر را نادیده می‌گیرد. بدین ترتیب:

ar rcST archive.a subdir/file1 subdir/file2 file1

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

s

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

T

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

u

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

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

U

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

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

v

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

V

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

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

--help

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

--version

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

-X32_64

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

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

@file

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

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

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

nm(1)، ranlib(1) و مدخل‌های Info برای binutils..SH "کپی‌رایت و تکثیر (COPYRIGHT)" Copyright (c) 1991-2026 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” گنجانده شده است.