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

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

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

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

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

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

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

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

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

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

ابزار GNU ar طوری طراحی شده است که با دو شیوه مختلف سازگار باشد. شما می‌توانید فعالیت آن را با استفاده از گزینه‌های خط فرمان، مانند انواع مختلف ar در سیستم‌های یونیکس کنترل کنید؛ یا اگر گزینه خط فرمان منفرد -M را مشخص کنید، می‌توانید آن را با اسکریپتی از ورودی استاندارد، مانند برنامه کتابدار MRI ("librarian") کنترل نمایید.

ابزار 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 (همراه با جایگزینی یا replacement). این عملیات با q تفاوت دارد، زیرا هر عضو موجود قبلی در صورت تطابق نام با فایل‌های در حال افزودن، حذف می‌شود.

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

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

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

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

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

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

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

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

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

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

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

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

کوتاه کردن نام‌ها در آرشیو. ابزار GNU ar معمولاً نام فایل‌ها را با هر طولی مجاز می‌داند. این کار باعث ایجاد آرشیوهایی می‌شود که با برنامه بومی ar در برخی سیستم‌ها سازگار نیستند. در صورت نگرانی در این باره، می‌توان از اصلاح‌کننده f برای کوتاه کردن نام فایل‌ها هنگام قرار دادن آن‌ها در آرشیو استفاده کرد.
درج فایل‌های جدید قبل از (before) یک عضو موجود در آرشیو. اگر از اصلاح‌کننده i استفاده کنید، نام یک عضو موجود در آرشیو باید به عنوان آرگومان relpos قبل از نام archive آورده شود (همانند b).
مشخص کردن وابستگی‌های این کتابخانه. وابستگی‌ها باید بلافاصله پس از این نویسه گزینه بیایند، باید از همان نحو خط فرمان پیونددهنده استفاده کنند و باید درون یک آرگومان منفرد مشخص شوند؛ یعنی در صورت نیاز به چندین مورد، باید برای تشکیل یک آرگومان واحد خط فرمان داخل گیومه قرار داده شوند. برای مثال l "-L/usr/local/lib -lmydep1 -lmydep2".
استفاده از پارامتر count. این شناسه زمانی استفاده می‌شود که چندین ورودی با یک نام در آرشیو وجود داشته باشند. استخراج یا حذف نمونه شماره count از نام ارائه‌شده از آرشیو.
حفظ تاریخ‌های اصلی (original) اعضا هنگام استخراج آن‌ها. اگر این اصلاح‌کننده را تعیین نکنید، فایل‌های استخراج‌شده از آرشیو با زمان استخراج مهر زمانی می‌خورند.
نمایش آفست اعضا درون آرشیو. همراه با گزینه t استفاده شود.
استفاده از نام مسیر کامل هنگام تطبیق یا ذخیره نام‌ها در آرشیو. آرشیوهای ایجادشده با نام مسیر کامل با استاندارد POSIX سازگار نیستند و بنابراین ممکن است با ابزارهایی به غیر از ابزارهای به‌روز GNU کار نکنند. ویرایش چنین آرشیوهایی با GNU ar بدون استفاده از P نام‌های مسیر کامل را حذف می‌کند مگر اینکه آرشیو از نوع تنک (thin) باشد. توجه داشته باشید که P هنگام افزودن فایل‌ها به یک آرشیو تنک می‌تواند مفید باشد زیرا r بدون P مسیر را هنگام انتخاب عنصری که باید جایگزین شود نادیده می‌گیرد. بنابراین 
ar rcST archive.a subdir/file1 subdir/file2 file1

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

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

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

اگر --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) تبدیل کن. اگر از قبل وجود داشته باشد و یک آرشیو معمولی باشد، اعضای موجود باید در همان پوشه فایل archive حضور داشته باشند.
@file
خواندن گزینه‌های خط فرمان از file. گزینه‌های خوانده‌شده به جای گزینه اصلی @file درج می‌شوند. اگر file وجود نداشته باشد، یا نتوان آن را خواند، با گزینه به صورت لغوی رفتار شده و حذف نخواهد شد.

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

nm(1)، ranlib(1) و مدخل‌های Info برای binutils.

Copyright (c) 1991-2025 Free Software Foundation, Inc.

اجازه کپی، توزیع و/یا ویرایش این سند تحت شرایط «مجوز مستندات آزاد گنو»، نسخه ۱.۳ یا هر نسخه جدیدتر منتشرشده توسط بنیاد نرم‌افزارهای آزاد داده می‌شود؛ بدون بخش‌های تغییرناپذیر، بدون متن‌های روی جلد، و بدون متن‌های پشت جلد. نسخه‌ای از مجوز در بخشی با عنوان «GNU Free Documentation License» آورده شده است.

2026-01-23 binutils-2.45.1