GDBSERVER(1) GNU Development Tools GDBSERVER(1)

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

gdbserver comm prog [args...]

gdbserver --attach comm pid

gdbserver --multi comm

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

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

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

این دستور تقریباً مشابه مثال قبل است، با این تفاوت که ارتباط با GDB موجود روی "host" از طریق TCP صورت می‌گیرد. آرگومان "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، باید 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 ممکن است استفاده شود یا نشود..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 به یک برنامهٔ در حال اجرا متصل خواهد شد. ساختار به‌صورت زیر است: 
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)، ژوئیه ۱۹۹۱.

کپی‌رایت © ۱۹۸۸-۲۰۲۵ متعلق به 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