.\" Automatically generated by Pandoc 3.10.2
.\"
.TH "JDB" "1" "2026" "JDK 26.0.2.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
هنگامی که JDB به این روش راه‌اندازی می‌شود، یک JVM دوم را با پارامترهای
مشخص‌شده فراخوانی کرده، کلاس تعیین‌شده را بارگذاری می‌کند و پیش از اجرای
نخستین دستورالعمل آن کلاس، JVM را متوقف می‌سازد.
.PP
روش دیگر برای استفاده از دستور \f[CR]jdb\f[R]، پیوستن (attach) آن به یک
JVM است که هم‌اکنون در حال اجراست.
سینتکس راه‌اندازی یک JVM که دستور \f[CR]jdb\f[R] پس از اجرا به آن متصل
می‌شود، به شرح زیر است.
این عمل کتابخانه‌های اشکال‌زدایی درون‌فرآیندی (in\-process) را بارگذاری کرده
و نوع اتصال را مشخص می‌نماید.
.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] برای شناسایی
کد مقداردهی اولیه ایستا (static initialization) برای \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)"
هنگامی که استثنایی (exception) رخ دهد که در هیچ کجای پشته فراخوانیِ ریسه
پرتاب‌کننده، دستور \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]
تمام ریسه‌ها، از جمله ریسه‌های مجازی را هم‌زمان با ایجادشان ردگیری می‌کند.
بخش \f[B]کار با ریسه‌های مجازی (Working With Virtual Threads)\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
یکی از گزینه‌های شرح‌داده‌شده در صفحه راهنمای راه‌انداز برنامه جاوا
(Java application launcher) است.
برای نمونه، \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 به صورت پیش‌فرض ریسه‌های مجازی را در زمان ایجادشان ردگیری
نمی‌کند.
این ابزار تنها ریسه‌های مجازی‌ای را ردگیری خواهد کرد که رویدادی روی آن‌ها رخ
داده باشد، مانند رویداد نقطه توقف (breakpoint event).
گزینه \f[CR]\-trackallthreads\f[R] می‌تواند برای وادار کردن JDB به ردگیری همه
ریسه‌های مجازی در هنگام ایجاد آن‌ها به کار رود.
.PP
هنگامی که JDB برای نخستین بار متصل می‌شود، فهرستی از تمامی ریسه‌های شناخته‌شده
را از Debug Agent درخواست می‌کند.
به طور پیش‌فرض، عامل اشکال‌زدایی هیچ ریسه مجازی‌ای را در این فهرست بازنمی‌گرداند،
باز هم به این دلیل که این فهرست ممکن است چنان طولانی باشد که اشکال‌زدا را تحت
فشار قرار دهد.
Debug Agent گزینه‌ای با نام \f[CR]includevirtualthreads\f[R] دارد که می‌توان
آن را برای تغییر این رفتار فعال کرد تا تمام ریسه‌های مجازی شناخته‌شده در فهرست
قرار گیرند.
گزینه \f[CR]\-trackallthreads\f[R] در JDB موجب می‌شود هنگامی که JDB برنامه‌ای
را برای اشکال‌زدایی اجرا می‌کند، به طور خودکار گزینه
\f[CR]includevirtualthreads\f[R] مربوط به Debug Agent را فعال سازد.
با این حال، به یاد داشته باشید که Debug Agent ممکن است از ریسه‌های مجازی که
پیش از اتصال JDB به برنامه تحت اشکال‌زدایی ایجاد شده‌اند، آگاهی نداشته باشد.