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

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

gdbserver comm prog [args...]

gdbserver --attach comm pid

gdbserver --multi comm

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

نحوهٔ استفاده (سمت سرور (هدف)):

ابتدا باید یک نسخه از برنامه‌ای که می‌خواهید اشکال‌زدایی کنید روی سیستم هدف قرار گیرد. در صورت نیاز می‌توان برنامه را برای صرفه‌جویی در فضا پیراست (strip کرد)، زیرا gdbserver نیازی به نمادها (symbols) ندارد. تمام مدیریت نمادها توسط 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

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

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

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

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

برای شروع "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 همان‌طور است که در بالا شرح داده شد. شناسه فرآیند یک برنامه در حال اجرا را در pid مشخص کنید؛ GDB باقی کارها را انجام خواهد داد. مانند حالت قبل، هنگامی که فرآیند pid پایان یابد، GDB اتصال را می‌بندد و "gdbserver" خارج خواهد شد.

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

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

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

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

pid شناسه فرآیند (ID) یک فرآیند در حال اجرا است. نیازی نیست که 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، Richard M. Stallman و Roland H. Pesch، ژوئیه 1991.

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

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

(a) متن پشت جلد FSF عبارت است از: "You are free to copy and modify this GNU Manual. Buying copies from GNU Press supports the FSF in developing GNU and promoting software freedom."

2025-12-20 gdb-17.1