GDBSERVER(1) GNU Development Tools GDBSERVER(1)

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

gdbserver comm prog [args...]

gdbserver --attach comm pid

gdbserver --multi comm

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

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

ابتدا باید یک نسخه از برنامه‌ای را که می‌خواهید اشکال‌زدایی کنید روی سیستم هدف (target) قرار دهید. در صورت نیاز برای صرفه‌جویی در فضا، می‌توان نمادهای برنامه را حذف (strip) کرد، چرا که gdbserver نیازی به نمادها ندارد. تمام مدیریت نمادها بر عهدهٔ 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" به پورت محلی TCP شمارهٔ 2345 را داریم. (در حال حاضر، بخش "host" نادیده گرفته می‌شود.) تا زمانی که شماره پورت با پورت‌های فعال دیگر TCP در سیستم هدف تداخل نداشته باشد، می‌توانید هر شماره‌ای را که می‌خواهید انتخاب کنید. همین شماره پورت باید در دستور "target remote" برنامهٔ GDB میزبان (که به زودی شرح داده خواهد شد) استفاده شود. توجه داشته باشید که اگر شماره پورتی را انتخاب کنید که با سرویس دیگری تداخل دارد، gdbserver پیامی خطا چاپ کرده و خارج خواهد شد.

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

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

pid شناسهٔ فرایند یک فرایند در حال اجرا است. نیازی به مشخص کردن مسیر فایل باینری فرایند در حال اجرا برای 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 می‌تواند چندین برنامهٔ تحت‌نظارت (inferior) را به‌طور هم‌زمان اشکال‌زدایی کند؛ این موضوع در دفترچه راهنمای 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 اختیاری است.

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

مستندات کامل 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" و "Free Software Needs Free Documentation"، با متون روی جلد شامل "A GNU Manual،" و متون پشت جلد به‌صورت بند (الف) در زیر.

(الف) متن پشت جلد 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