GDBSERVER(1) GNU Development Tools GDBSERVER(1)

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

gdbserver comm prog [args...]

gdbserver --attach comm pid

gdbserver --multi comm

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

شیوهٔ استفاده (سمت سرور (هدف)):

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

برای استفاده از سرور، به سیستم هدف وارد شده و برنامهٔ 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 موجود در "host" از طریق TCP ارتباط برقرار کنیم. آرگومان "host:2345" به این معنی است که ما منتظر یک اتصال TCP از جانب "host" به درگاه محلی 2345 پروتکل TCP هستیم. (در حال حاضر، بخش "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 را همانند همیشه با قرار دادن برنامهٔ هدف به عنوان آرگومان اول اجرا کنید. (اگر خط سریال با سرعتی غیر از 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، حتماً باید پیش از استفاده از دستور `target remote` برنامهٔ gdbserver را اجرا کرده باشید، در غیر این صورت ممکن است با خطایی شبیه به `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 ممکن است در چنین شرایطی استفاده شود یا نشود..SH "گزینه‌ها (OPTIONS)" سه حالت مختلف برای فراخوانی 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 به یک برنامه در حال اجرا متصل (attach) خواهد شد. نحو دستور چنین است: 
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، Richard M. Stallman و Roland H. Pesch، ژوئیه ۱۹۹۱.

کپی‌رایت (c) 1988-2025 Free Software Foundation, Inc.

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

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

2026-05-10 gdb-17.2