.\" Automatically generated by Pandoc 3.10.2
.\"
.TH "JDB" "1" "2026" "JDK 25.0.4.1" "JDK Commands"
.SH "نام (NAME)"
jdb \- یافتن و رفع باگ‌ها در برنامه‌های پلتفرم جاوا
.SH "خلاصه دستور (SYNOPSIS)"
\f[CR]jdb\f[R] [\f[I]options\f[R]] [\f[I]classname\f[R]]
[\f[I]arguments\f[R]]
.TP
\f[I]options\f[R]
نشان‌دهنده گزینه‌های خط فرمان \f[CR]jdb\f[R] است.
بخش \f[B]گزینه‌های دستور JDB\f[R] را ببینید.
.TP
\f[I]classname\f[R]
نشان‌دهنده نام کلاس اصلی برای اشکال‌زدایی است.
.TP
\f[I]arguments\f[R]
نشان‌دهنده آرگومان‌هایی است که به متد \f[CR]main()\f[R] کلاس ارسال می‌شوند.
.SH "توضیحات (DESCRIPTION)"
اشکال‌زدای جاوا (JDB) یک اشکال‌زدای خط فرمانی ساده برای کلاس‌های جاوا است.
دستور \f[CR]jdb\f[R] و گزینه‌های آن، ابزار JDB را فراخوانی می‌کنند.
دستور \f[CR]jdb\f[R] معماری اشکال‌زدایی پلتفرم جاوا (Java Platform Debugger Architecture) را به نمایش می‌گذارد و امکان بازرسی و اشکال‌زدایی یک JVM محلی یا راه‌دور را فراهم می‌آورد.
.SH "شروع یک نشست JDB (START A JDB SESSION)"
روش‌های متعددی برای شروع یک نشست JDB وجود دارد.
رایج‌ترین روش این است که JDB یک JVM جدید را به همراه کلاس اصلی برنامه‌ای که باید اشکال‌زدایی شود راه‌اندازی کند.
این کار با جایگزین کردن دستور \f[CR]jdb\f[R] به جای دستور \f[CR]java\f[R] در خط فرمان انجام می‌شود.
برای نمونه، اگر کلاس اصلی برنامه شما \f[CR]MyClass\f[R] است، از دستور زیر برای اشکال‌زدایی آن تحت JDB استفاده کنید:
.RS
.PP
\f[CR]jdb MyClass\f[R]
.RE
.PP
هنگامی که به این صورت راه‌اندازی می‌شود، دستور \f[CR]jdb\f[R] یک JVM ثانویه را با پارامترهای مشخص‌شده فراخوانی کرده، کلاس تعیین‌شده را بارگذاری می‌کند و JVM را پیش از اجرای نخستین دستورالعمل آن کلاس متوقف می‌سازد.
.PP
روش دیگر برای استفاده از دستور \f[CR]jdb\f[R] پیوست کردن (attach) آن به یک JVM است که از پیش در حال اجرا است.
نحو راه‌اندازی یک JVM که دستور \f[CR]jdb\f[R] هنگام اجرا به آن متصل می‌شود به صورت زیر است.
این عمل کتابخانه‌های اشکال‌زدایی درون‌فرآیندی را بارگذاری کرده و نوع اتصالی که باید برقرار شود را مشخص می‌سازد.
.RS
.PP
\f[CR]java \-agentlib:jdwp=transport=dt_socket,server=y,suspend=n MyClass\f[R]
.RE
.PP
سپس می‌توانید دستور \f[CR]jdb\f[R] را با دستور زیر به JVM متصل کنید:
.RS
.PP
\f[CR]jdb \-attach 8000\f[R]
.RE
.PP
عدد 8000 نشانی JVM در حال اجرا است.
.PP
در این حالت آرگومان \f[CR]MyClass\f[R] در خط فرمان \f[CR]jdb\f[R] مشخص نمی‌شود، زیرا دستور \f[CR]jdb\f[R] به جای راه‌اندازی یک JVM جدید، به یک JVM موجود متصل می‌شود.
.PP
روش‌های بسیار دیگری برای اتصال اشکال‌زدا به یک JVM وجود دارد و همه آن‌ها توسط دستور \f[CR]jdb\f[R] پشتیبانی می‌شوند.
مستندات معماری اشکال‌زدایی پلتفرم جاوا (Java Platform Debugger Architecture) شامل اطلاعات تکمیلی درباره این گزینه‌های اتصال است.
.SH "نقاط توقف (BREAKPOINTS)"
نقاط توقف (Breakpoints) را می‌توان در JDB بر اساس شماره خطوط یا در نخستین دستورالعمل یک متد تعیین کرد، برای نمونه:
.IP \(bu 2
دستور \f[CR]stop at MyClass:22\f[R] یک نقطه توقف در نخستین دستورالعمل خط ۲۲ از فایل منبع حاوی \f[CR]MyClass\f[R] تنظیم می‌کند.
.IP \(bu 2
دستور \f[CR]stop in java.lang.String.length\f[R] یک نقطه توقف در آغاز متد \f[CR]java.lang.String.length\f[R] تعیین می‌کند.
.IP \(bu 2
دستور \f[CR]stop in MyClass.<clinit>\f[R] از \f[CR]<clinit>\f[R] برای شناسایی کد مقداردهی اولیه ایستای \f[CR]MyClass\f[R] استفاده می‌کند.
.PP
هنگامی که یک متد سربارگذاری (overload) شده باشد، باید نوع آرگومان‌های آن را نیز مشخص کنید تا متد مناسب برای نقطه توقف انتخاب شود.
برای نمونه، \f[CR]MyClass.myMethod(int,java.lang.String)\f[R] یا \f[CR]MyClass.myMethod()\f[R].
.PP
دستور \f[CR]clear\f[R] با استفاده از نحو روبرو نقاط توقف را حذف می‌کند: \f[CR]clear MyClass:45\f[R].
استفاده از دستور \f[CR]clear\f[R] یا \f[CR]stop\f[R] بدون هیچ آرگومانی، فهرستی از تمام نقاط توقف تنظیم‌شده فعلی را نمایش می‌دهد.
دستور \f[CR]cont\f[R] اجرای برنامه را ادامه می‌دهد.
.SH "گام‌زنی (STEPPING)"
دستور \f[CR]step\f[R] اجرا را به خط بعدی پیش می‌برد، چه در قاب پشته (stack frame) فعلی باشد و چه درون یک متد فراخوانی‌شده.
دستور \f[CR]next\f[R] اجرا را به خط بعدی در قاب پشته فعلی پیش می‌برد.
.SH "استثناها (EXCEPTIONS)"
هنگامی که استثنایی رخ می‌دهد و هیچ عبارت \f[CR]catch\f[R] برای آن در پشته فراخوانیِ رشته پرتاب‌کننده وجود ندارد، JVM معمولاً ردگیری استثنا (trace) را چاپ کرده و خارج می‌شود.
اما هنگام اجرا تحت JDB، کنترل در محل پرتاب خطا به JDB بازمی‌گردد.
سپس می‌توانید از دستور \f[CR]jdb\f[R] برای عیب‌یابی علت استثنا استفاده کنید.
.PP
از دستور \f[CR]catch\f[R] استفاده کنید تا برنامه تحت اشکال‌زدایی در سایر استثناهای پرتاب‌شده متوقف شود، برای نمونه:
\f[CR]catch java.io.FileNotFoundException\f[R] یا \f[CR]catch\f[R]
\f[CR]mypackage.BigTroubleException\f[R].
هر استثنایی که نمونه‌ای از کلاس مشخص‌شده یا زیرکلاس‌های آن باشد، برنامه را در نقطه‌ای که استثنا پرتاب می‌شود متوقف می‌سازد.
.PP
دستور \f[CR]ignore\f[R] اثر دستور \f[CR]catch\f[R] پیشین را باطل می‌کند.
دستور \f[CR]ignore\f[R] باعث نادیده گرفتن استثناهای خاص توسط JVM تحت اشکال‌زدایی نمی‌شود، بلکه تنها باعث می‌شود که اشکال‌زدا آن‌ها را نادیده بگیرد.
.SH "گزینه‌های دستور JDB (OPTIONS FOR THE JDB COMMAND)"
هنگامی که از دستور \f[CR]jdb\f[R] به جای دستور \f[CR]java\f[R] در خط فرمان استفاده می‌کنید، دستور \f[CR]jdb\f[R] بسیاری از گزینه‌های مشابه دستور \f[CR]java\f[R] را می‌پذیرد.
.PP
گزینه‌های زیر توسط دستور \f[CR]jdb\f[R] پشتیبانی می‌شوند:
.TP
\f[CR]\-help\f[R]
یک پیام راهنما نمایش می‌دهد.
.TP
\f[CR]\-sourcepath\f[R] \f[I]dir1\f[R]\f[CR]:\f[R]\f[I]dir2\f[R]\f[CR]:\f[R]...
از مسیر مشخص‌شده برای جستجوی فایل‌های منبع استفاده می‌کند.
اگر این گزینه مشخص نشود، از مسیر پیش‌فرض نقطه (\f[CR].\f[R]) استفاده خواهد شد.
.TP
\f[CR]\-attach\f[R] \f[I]address\f[R]
اشکال‌زدا را با سازوکار اتصال پیش‌فرض به یک JVM در حال اجرا متصل می‌کند.
.TP
\f[CR]\-listen\f[R] \f[I]address\f[R]
منتظر می‌ماند تا یک JVM در حال اجرا با استفاده از یک رابط اتصال استاندارد به نشانی مشخص‌شده متصل شود.
.TP
\f[CR]\-listenany\f[R]
منتظر می‌ماند تا یک JVM در حال اجرا با استفاده از یک رابط استاندارد به هر نشانیِ در دسترسی متصل گردد.
.TP
\f[CR]\-launch\f[R]
برنامه تحت اشکال‌زدایی را بلافاصله پس از راه‌اندازی دستور \f[CR]jdb\f[R] اجرا می‌کند.
گزینه \f[CR]\-launch\f[R] نیاز به استفاده از دستور \f[CR]run\f[R] را برطرف می‌سازد.
برنامه تحت اشکال‌زدایی راه‌اندازی شده و سپس دقیقاً پیش از بارگذاری کلاس اولیه برنامه متوقف می‌شود.
در این نقطه، می‌توانید هر نقطه توقف لازم را تنظیم کرده و از دستور \f[CR]cont\f[R] برای ادامه اجرا استفاده کنید.
.TP
\f[CR]\-listconnectors\f[R]
رابط‌های اتصال (connectors) موجود در این JVM را فهرست می‌کند.
.TP
\f[CR]\-connect\f[R] \f[I]connector\-name\f[R]\f[CR]:\f[R]\f[I]name1\f[R]\f[CR]=\f[R]\f[I]value1\f[R]....
با استفاده از رابط اتصال مشخص‌شده و مقادیر آرگومان‌های فهرست‌شده، به JVM هدف متصل می‌شود.
.TP
\f[CR]\-dbgtrace\f[R] [\f[I]flags\f[R]]
اطلاعاتی را برای اشکال‌زدایی خودِ دستور \f[CR]jdb\f[R] چاپ می‌کند.
.TP
\f[CR]\-tclient\f[R]
برنامه را در Java HotSpot VM client اجرا می‌کند.
.TP
\f[CR]\-trackallthreads\f[R]
همه رشته‌ها، از جمله رشته‌های مجازی (virtual threads) را به محض ایجاد شدن ردیابی می‌کند.
بخش \f[B]کار با رشته‌های مجازی\f[R] را در زیر ببینید.
.TP
\f[CR]\-tserver\f[R]
برنامه را در Java HotSpot VM server اجرا می‌کند.
.TP
\f[CR]\-J\f[R]\f[I]option\f[R]
گزینه \f[I]option\f[R] را به JVM مربوط به JDB ارسال می‌کند؛ که در آن option یکی از گزینه‌های شرح داده‌شده در صفحه راهنمای اجراکننده برنامه‌های جاوا است.
برای نمونه، \f[CR]\-J\-Xms48m\f[R] حافظه راه‌اندازی را روی ۴۸ مگابایت تنظیم می‌کند.
بخش \f[I]Overview of Java Options\f[R] در \f[B]java\f[R] را ببینید.
.PP
گزینه‌های زیر به فرآیند تحت اشکال‌زدایی (debuggee) هدایت می‌شوند:
.TP
\f[CR]\-R\f[R]\f[I]option\f[R]
گزینه \f[I]option\f[R] را به JVM تحت اشکال‌زدایی ارسال می‌کند؛ که در آن option یکی از گزینه‌های شرح داده‌شده در صفحه راهنمای اجراکننده برنامه‌های جاوا است.
برای نمونه، \f[CR]\-R\-Xms48m\f[R] حافظه راه‌اندازی را روی ۴۸ مگابایت تنظیم می‌کند.
بخش \f[I]Overview of Java Options\f[R] در \f[B]java\f[R] را ببینید.
.TP
\f[CR]\-v\f[R] یا \f[CR]\-verbose\f[R][\f[CR]:\f[R]\f[I]class\f[R]|\f[CR]gc\f[R]|\f[CR]jni\f[R]]
حالت پرگو (verbose) را فعال می‌کند.
.TP
\f[CR]\-D\f[R]\f[I]name\f[R]\f[CR]=\f[R]\f[I]value\f[R]
یک ویژگی سیستمی (system property) را تنظیم می‌کند.
.TP
\f[CR]\-classpath\f[R] \f[I]dir\f[R]
دایرکتوری‌های جداشده با دونقطه را که باید در آن‌ها به دنبال کلاس‌ها گشت، فهرست می‌کند.
.TP
\f[CR]\-X\f[R] \f[I]option\f[R]
یک گزینه غیراستاندارد مربوط به JVM هدف.
.PP
گزینه‌های دیگری نیز برای ارائه سازوکارهای جایگزین جهت اتصال اشکال‌زدا به JVM مورد نظر پشتیبانی می‌شوند.
.SH "کار با رشته‌های مجازی (WORKING WITH VIRTUAL THREADS)"
اغلب رشته‌های مجازی در تعداد و بسامدی چنان بالا ایجاد می‌شوند که ممکن است بار زیادی به اشکال‌زدا تحمیل کرده و کارایی آن را مختل کنند.
به همین دلیل، JDB به طور پیش‌فرض رشته‌های مجازی را به محض ایجاد شدن ردیابی نمی‌کند.
این ابزار تنها رشته‌های مجازی‌ای را ردیابی خواهد کرد که رویدادی برای آن‌ها رخ داده باشد، مانند رویداد یک نقطه توقف.
می‌توان از گزینه \f[CR]\-trackallthreads\f[R] استفاده کرد تا JDB تمام رشته‌های مجازی را به محض ایجاد شدن ردیابی نماید.
.PP
هنگامی که JDB برای نخستین بار متصل می‌شود، فهرستی از تمام رشته‌های شناخته‌شده را از عامل اشکال‌زدایی (Debug Agent) درخواست می‌کند.
به طور پیش‌فرض، عامل اشکال‌زدایی هیچ رشته مجازی‌ای را در این فهرست بازنمی‌گرداند، باز هم به این دلیل که حجم فهرست ممکن است بسیار بزرگ بوده و بر عملکرد اشکال‌زدا اثر منفی بگذارد.
عامل اشکال‌زدایی گزینه‌ای به نام \f[CR]includevirtualthreads\f[R] دارد که می‌توان آن را فعال ساخت تا این رفتار تغییر کند و همه رشته‌های مجازی شناخته‌شده در فهرست گنجانده شوند.
گزینه \f[CR]\-trackallthreads\f[R] در JDB باعث می‌شود هنگام راه‌اندازی یک برنامه برای اشکال‌زدایی، JDB به طور خودکار گزینه \f[CR]includevirtualthreads\f[R] عامل اشکال‌زدایی را فعال کند.
با این حال، به خاطر داشته باشید که عامل اشکال‌زدایی ممکن است از رشته‌های مجازی که پیش از اتصال JDB به برنامه تحت اشکال‌زدایی ایجاد شده‌اند، اطلاعی نداشته باشد.