GDBSERVER(1) GNU Development Tools GDBSERVER(1)

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

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

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

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

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

مقدار pid شناسه فرآیند در حال اجرا است. نیازی نیست 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 به درگاه ۲۳۴۵ روی میزبان `the-target'، جایی که قبلاً gdbserver را با همان شماره درگاه راه‌اندازی کرده‌اید، ارتباط برقرار می‌کند. توجه داشته باشید که برای اتصالات TCP، باید پیش از استفاده از دستور 'target remote'، کارساز gdbserver را راه‌اندازی کرده باشید، در غیر این صورت ممکن است با خطایی مانند `Connection refused' مواجه شوید.

برنامه gdbserver همچنین می‌تواند چندین فرآیند زیرین (inferiors) را به طور همزمان اشکال‌زدایی کند، که در راهنمای GDB در بخش "Inferiors Connections and Programs" توضیح داده شده است -- دستور پوسته "info -f gdb -n 'Inferiors Connections and Programs'". در این حالت از دستور دیگر یعنی "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" خارج خواهد شد.

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

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

info gdb

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

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

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

مجوز کپی، توزیع و/یا اصلاح این سند تحت شرایط مجوز اسناد آزاد گنو (GNU FDL)، نسخه ۱.۳ یا هر نسخه بعدی منتشر شده توسط بنیاد نرم‌افزار آزاد اعطا می‌شود.

2026-05-10 gdb-17.2