GDBSERVER(1) GNU Development Tools GDBSERVER(1)

gdbserver - سرور راه‌دور برای اشکال‌زدای گنو (GNU Debugger)

gdbserver comm prog [args...]

gdbserver --attach comm pid

gdbserver --multi comm

برنامهٔ gdbserver به شما اجازه می‌دهد GDB را روی ماشینی متفاوت از ماشینی که برنامهٔ در حال اشکال‌زدایی را اجرا می‌کند، به کار ببرید.

کاربرد (سمت سرور (هدف)):

نخست، باید یک نسخه از برنامه‌ای را که می‌خواهید اشکال‌زدایی کنید روی سامانهٔ هدف قرار دهید. در صورت نیاز می‌توان نمادهای برنامه را حذف (strip) کرد تا فضا ذخیره شود، چرا که gdbserver نیازی به جدول نمادها ندارد. تمام پردازش نمادها توسط GDB در حال اجرا روی سامانهٔ میزبان انجام می‌شود.

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

target> gdbserver <comm> <program> [<args> ...]

برای نمونه، هنگام استفاده از درگاه سریال، می‌توانید دستور زیر را وارد کنید:

target> gdbserver /dev/com1 emacs foo.txt

این دستور به gdbserver اعلام می‌کند تا emacs را با آرگومان foo.txt اشکال‌زدایی کند و از طریق درگاه /dev/com1 با GDB ارتباط بگیرد. اکنون gdbserver منتظر برقراری ارتباط از سوی GDB در سامانهٔ میزبان می‌ماند.

برای استفاده از اتصال TCP، می‌توانید این دستور را به کار ببرید:

target> gdbserver host:2345 emacs foo.txt

این دستور تقریباً مشابه مثال پیشین عمل می‌کند، با این تفاوت که از طریق TCP با GDB در "host" ارتباط برقرار خواهد کرد. آرگومان "host:2345" بدین معناست که منتظر یک اتصال TCP از جانب "host" به درگاه محلی TCP با شمارهٔ 2345 هستیم. (در حال حاضر بخش "host" نادیده گرفته می‌شود.) می‌توانید هر شماره درگاهی را که می‌خواهید انتخاب کنید، به شرطی که با درگاه‌های TCP فعال در سامانهٔ هدف تداخلی نداشته باشد. همین شماره درگاه باید در دستور "target remote" در GDB میزبان (که در ادامه توضیح داده شده) استفاده شود. توجه داشته باشید که اگر شماره درگاه انتخابی با سرویس دیگری تداخل داشته باشد، gdbserver یک پیام خطا نمایش داده و خارج می‌شود.

همچنین gdbserver می‌تواند به برنامه‌های در حال اجرا متصل شود (attach کند). این کار از طریق آرگومان --attach انجام می‌شود. نحو دستور بدین صورت است:

target> gdbserver --attach <comm> <pid>

شناسهٔ pid همان شناسهٔ فرایند (Process ID) یک فرایندِ در حال اجرا است. نیازی نیست gdbserver را به فایل باینری فرایندِ در حال اجرا ارجاع دهید.

برای راه‌اندازی "gdbserver" بدون ارسال دستور اولیه برای اجرا یا شناسهٔ فرایند برای اتصال، از گزینهٔ خط فرمان --multi استفاده کنید. در این حالت باید از طریق "target extended-remote" متصل شوید تا برنامه‌ای را که می‌خواهید اشکال‌زدایی کنید اجرا نمایید.

target> gdbserver --multi <comm>

کاربرد (سمت میزبان):

شما به یک نسخهٔ حذف‌نشده (unstripped) از برنامهٔ هدف روی سامانهٔ میزبان خود نیاز دارید، چرا که GDB نیازمند بررسی جدول‌های نماد و موارد مرتبط با آن است. GDB را به شکل معمول اجرا کنید و برنامهٔ هدف را به عنوان نخستین آرگومان به آن بدهید. (اگر خط سریال با سرعتی غیر از ۹۶۰۰ باود کار می‌کند، ممکن است نیاز به استفاده از گزینهٔ --baud داشته باشید.) یعنی دستور "gdb TARGET-PROG" یا "gdb --baud BAUD TARGET-PROG". پس از آن، تنها دستور جدیدی که باید بدانید "target remote" (یا "target extended-remote") است. آرگومان آن یا نام یک دستگاه است (معمولاً یک دستگاه سریال مانند /dev/ttyb)، یا یک توصیف‌کنندهٔ "HOST:PORT". برای نمونه:

(gdb) target remote /dev/ttyb

ارتباط با سرور را از طریق خط سریال /dev/ttyb برقرار می‌کند، و:

(gdb) target remote the-target:2345

از طریق یک اتصال TCP به درگاه 2345 روی میزبان «the-target» ارتباط برقرار می‌کند؛ همان جایی که پیش‌تر gdbserver را با همان شماره درگاه اجرا کرده بودید. توجه داشته باشید که در اتصالات TCP، حتماً باید gdbserver را پیش از اجرای دستور «target remote» راه‌اندازی کنید، در غیر این صورت با خطایی شبیه به «Connection refused» مواجه خواهید شد.

همچنین gdbserver قادر است چندین فرودست (inferiors) را به طور همزمان اشکال‌زدایی کند؛ این مورد در راهنمای GDB ذیل گرهٔ "Inferiors Connections and Programs" -- دستور پوستهٔ "info -f gdb -n 'Inferiors Connections and Programs'" شرح داده شده است. در چنین شرایطی از گونهٔ دیگر دستور GDB یعنی "extended-remote" استفاده کنید:

(gdb) target extended-remote the-target:2345

گزینهٔ --multi در gdbserver ممکن است در چنین شرایطی استفاده بشود یا نشود.

سه حالت مختلف برای فراخوانی gdbserver وجود دارد:

  • اشکال‌زدایی یک برنامهٔ مشخص با نام برنامه: 
    gdbserver <comm> <prog> [<args>...]

    پارامتر comm شیوهٔ ارتباط سرور با GDB را مشخص می‌کند؛ این پارامتر می‌تواند نام یک دستگاه (برای استفاده از خط سریال)، یک شماره درگاه TCP (":1234")، یا "-" یا "stdio" برای استفاده از ورودی/خروجی استاندارد (stdin/stdout) برنامهٔ "gdbserver" باشد. نام برنامه‌ای را که قصد اشکال‌زدایی آن را دارید در prog مشخص کنید. هر آرگومان باقی‌مانده عیناً به برنامه تحویل داده می‌شود. پس از خروج برنامه، GDB اتصال را قطع کرده و "gdbserver" بسته خواهد شد.

  • اشکال‌زدایی یک برنامهٔ مشخص با تعیین شناسهٔ فرایند (PID) یک برنامهٔ در حال اجرا: 
    gdbserver --attach <comm> <pid>

    پارامتر comm مطابق توضیحات بالا عمل می‌کند. شناسهٔ فرایند در حال اجرا را در pid وارد کنید؛ GDB سایر کارها را انجام خواهد داد. همانند حالت قبل، با خروج فرایند pid، برنامهٔ GDB اتصال را بسته و "gdbserver" خارج می‌شود.

  • حالت چندفرایندی -- اشکال‌زدایی بیش از یک برنامه/فرایند: 
    gdbserver --multi <comm>

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

در هر یک از این حالت‌ها می‌توانید گزینه‌های زیر را مشخص نمایید:

نمایش تمامی گزینه‌ها به همراه توضیحات کوتاه.
نمایش شماره نسخهٔ gdbserver و خروج از برنامه.
متصل شدن gdbserver به یک برنامهٔ در حال اجرا. نحو دستور: 
target> gdbserver --attach <comm> <pid>

شناسهٔ pid همان شناسهٔ یک فرایندِ در حال اجرا است. نیازی به تعیین مسیر باینری فرایندِ در حال اجرا برای gdbserver نیست.

برای راه‌اندازی "gdbserver" بدون مشخص کردن یک دستور اولیه برای اجرا یا شناسهٔ فرایند برای اتصال، از این گزینه در خط فرمان استفاده کنید. سپس می‌توانید با استفاده از "target extended-remote" متصل شده و برنامهٔ مورد نظر را اجرا کنید. نحو دستور: 
target> gdbserver --multi <comm>
دستور به "gdbserver" برای نمایش اطلاعات وضعیت بیشتر دربارهٔ فرایند اشکال‌زدایی. این گزینه برای توسعهٔ "gdbserver" و ارسال گزارش باگ به توسعه‌دهندگان طراحی شده است.

هر option نام مؤلفه‌ای است که اشکال‌زدایی باید برای آن فعال شود. فهرست گزینه‌های ممکن شامل all، threads، event-loop و remote است. گزینهٔ ویژهٔ all تمامی مؤلفه‌ها را فعال می‌کند. این فهرست از چپ به راست پردازش می‌شود و می‌توان پیشوند "-" را قبل از یک گزینه قرار داد تا خروجی اشکال‌زدایی آن مؤلفه غیرفعال شود؛ برای نمونه:

target> gdbserver --debug=all,-event-loop

تا خروجی اشکال‌زدایی برای تمامی مؤلفه‌ها به جز event-loop فعال شود. اگر هیچ گزینه‌ای برای --debug تعیین نشود، معادل با --debug=threads رفتار خواهد کرد. این رفتار ممکن است در نسخه‌های بعدی "gdbserver" تغییر کند.

دستور به "gdbserver" برای هدایت تمامی خروجی‌های اشکال‌زدایی به نام فایل تعیین‌شده در filename. این گزینه برای توسعهٔ "gdbserver" و گزارش باگ کاربرد دارد.
دستور به "gdbserver" برای درج اطلاعات اضافی در هر خط از خروجی‌های اشکال‌زدایی.
تعیین یک پوشش‌دهنده (wrapper) برای راه‌اندازی برنامه‌ها جهت اشکال‌زدایی. پس از این گزینه باید ابتدا نام پوشش‌دهنده، سپس آرگومان‌های خط فرمان ارسالی به آن، و در پایان "--" برای مشخص ساختن انتهای آرگومان‌های wrapper قرار گیرد.
به‌طور پیش‌فرض، gdbserver درگاه شنود TCP را باز نگه می‌دارد تا اتصالات بعدی نیز برقرار شوند. اما اگر "gdbserver" را با گزینهٔ --once اجرا کنید، پس از اتصال به نخستین نشست GDB، شنود برای اتصالات بعدی متوقف خواهد شد.

مستندات کامل GDB در قالب یک کتابچهٔ راهنمای Texinfo نگهداری می‌شود. چنانچه برنامه‌های "info" و "gdb" به همراه مستندات Texinfo مربوط به GDB روی سامانهٔ شما نصب باشند، اجرای دستور زیر:

info gdb

دسترسی شما به راهنمای جامع را فراهم می‌سازد.

Using GDB: A Guide to the GNU Source-Level Debugger, Richard M. Stallman and Roland H. Pesch, July 1991.

حق نشر (c) ۱۹۸۸-۲۰۲۵ بنیاد نرم‌افزار آزاد (Free Software Foundation, Inc.)

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

(a) متن پشت جلد بنیاد نرم‌افزار آزاد (FSF): «شما در کپی و تغییر این راهنمای گنو آزاد هستید. خرید نسخه‌ها از انتشارات گنو (GNU Press) از FSF در توسعهٔ گنو و پیشبرد آزادی نرم‌افزار پشتیبانی می‌کند.»

2026-05-10 gdb-17.2