GDBSERVER(1) ابزارهای توسعه گنو GDBSERVER(1)

gdbserver - کارگزار از راه دور برای اشکال‌زدای گنو

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 انجام می‌گیرد. نحو دستور به این صورت است:

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

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

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

target> gdbserver --multi <comm>

نحوهٔ استفاده (سمت میزبان):

شما به یک نسخهٔ حذف‌نشده (دارای نشانه‌ها یا unstripped) از برنامهٔ هدف روی سامانهٔ میزبان خود نیاز دارید، چرا که GDB باید جدول نشانه‌ها و موارد مشابه را بررسی کند. همانند همیشه، GDB را با مشخص کردن برنامهٔ هدف به عنوان اولین آرگومان اجرا کنید. (اگر خط سریال با سرعتی غیر از 9600 باود کار می‌کند، ممکن است نیاز به استفاده از گزینهٔ --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'" شرح داده شده است. در چنین حالتی از دستور مشتق‌شدهٔ "extended-remote" در GDB استفاده کنید:

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

در این حالت، ممکن است از گزینهٔ --multi در gdbserver استفاده بشود یا نشود (اختیاری است)..SH "گزینه‌ها (OPTIONS)" سه حالت مختلف برای فراخوانی gdbserver وجود دارد:

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

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

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

    پارامتر comm همانند توضیحات بالا است. شناسه فرایند (ID) یک برنامه در حال اجرا را در 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، سپس هرگونه آرگومان خط فرمانی که باید به wrapper ارسال شود، و در ادامه "--" برای مشخص کردن پایان آرگومان‌های wrapper بیاید.
به‌طور پیش‌فرض، gdbserver درگاه شنود TCP را باز نگه می‌دارد تا اتصالات بعدی امکان‌پذیر باشد. با این حال، اگر "gdbserver" را با گزینه --once اجرا کنید، پس از اتصال به اولین نشست GDB، شنود برای هرگونه تلاش بعدی جهت اتصال را متوقف خواهد کرد..SH "محیط (ENVIRONMENT)"

مستندات کامل برای GDB به عنوان یک راهنمای Texinfo نگهداری می‌شود. اگر برنامه‌های "info" و "gdb" و مستندات Texinfo مربوط به GDB به‌درستی روی سیستم شما نصب شده باشند، دستور

info gdb

باید دسترسی به راهنمای کامل را برای شما فراهم کند.

Using GDB: A Guide to the GNU Source-Level Debugger، ریچارد ام. استالمن و رولند اچ. پش، ژوئیه ۱۹۹۱.

کپی‌رایت (c) ۱۹۸۸-۲۰۲۵ Free Software Foundation, Inc.

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

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

2025-12-20 gdb-17.1