JDB(1) دستورهای JDK JDB(1)

jdb-openjdk21 - دیباگر تعاملی برنامه‌های جاوا در OpenJDK 21

jdb [گزینه‌ها] [نام‌کلاس] [آرگومان‌ها]

گزینه‌ها
این بخش نشان‌دهنده گزینه‌های خط فرمان jdb است. بخش گزینه‌های دستور JDB (OPTIONS FOR THE JDB COMMAND) را ببینید.
نام‌کلاس
این بخش نشان‌دهنده نام کلاس اصلی برای اشکال‌زدایی (دیباگ) است.
آرگومان‌ها
این بخش نشان‌دهنده آرگومان‌هایی است که به متد main() کلاس پاس داده می‌شوند.

اشکال‌زدای جاوا (JDB) یک ابزار خط فرمانی ساده برای اشکال‌زدایی کلاس‌های جاوا است. دستور jdb و گزینه‌های آن، JDB را فراخوانی می‌کنند. دستور jdb معماری اشکال‌زدایی پلتفرم جاوا (Java Platform Debugger Architecture) را به نمایش می‌گذارد و امکان بررسی و اشکال‌زدایی یک JVM محلی یا راه‌دور را فراهم می‌کند.

راه‌های متعددی برای شروع یک نشست JDB وجود دارد. متداول‌ترین روش این است که JDB یک JVM جدید را همراه با کلاس اصلی برنامه‌ای که قرار است اشکال‌زدایی شود راه‌اندازی کند. این کار با جایگزین کردن دستور jdb به جای دستور java در خط فرمان انجام می‌شود. برای مثال، اگر کلاس اصلی برنامه شما MyClass است، از دستور زیر برای اشکال‌زدایی آن تحت JDB استفاده کنید:

jdb MyClass

هنگامی که JDB به این صورت شروع می‌شود، دستور jdb یک JVM ثانویه را با پارامترهای مشخص‌شده فراخوانی می‌کند، کلاس تعیین‌شده را بارگذاری می‌نماید و پیش از اجرای نخستین دستورالعمل آن کلاس، JVM را متوقف می‌کند.

روش دیگر برای استفاده از دستور jdb، متصل کردن (attach) آن به یک JVM در حال اجرا است. سینتکس راه‌اندازی یک JVM که دستور jdb در زمان اجرا به آن متصل می‌شود، به شرح زیر است. این کار کتابخانه‌های اشکال‌زدایی درون‌فرآیندی را بارگذاری کرده و نوع اتصال مورد نظر را مشخص می‌سازد:

java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n MyClass

سپس می‌توانید دستور jdb را با دستور زیر به JVM متصل کنید:

jdb -attach 8000

عدد 8000 نشانی JVM در حال اجرا است.

در این حالت، آرگومان MyClass در خط فرمان jdb مشخص نمی‌شود زیرا دستور jdb به جای راه‌اندازی یک JVM جدید، به یک JVM موجود متصل می‌شود.

راه‌های بسیار دیگری نیز برای اتصال اشکال‌زدا به یک JVM وجود دارد که همگی توسط دستور jdb پشتیبانی می‌شوند. مستندات معماری اشکال‌زدایی پلتفرم جاوا شامل توضیحات تکمیلی درباره این گزینه‌های اتصال است.

نقاط توقف (Breakpoints) را می‌توان در JDB روی شماره خطوط یا روی اولین دستورالعمل یک متد تنظیم کرد؛ برای مثال:

•
دستور stop at MyClass:22 یک نقطه توقف در نخستین دستورالعمل برای خط ۲۲ از فایل منبع حاوی MyClass تنظیم می‌کند.
•
دستور stop in java.lang.String.length یک نقطه توقف در ابتدای متد java.lang.String.length تنظیم می‌کند.
•
دستور stop in MyClass.<clinit> از <clinit> برای مشخص کردن کد مقداردهی اولیه ایستا (static initialization) برای MyClass استفاده می‌کند.

هنگامی که یک متد دارای سربارگذاری (overload) است، باید انواع آرگومان‌های آن را نیز مشخص کنید تا متد مناسب برای نقطه توقف انتخاب شود؛ برای مثال، MyClass.myMethod(int,java.lang.String) یا MyClass.myMethod().

دستور clear نقاط توقف را با سینتکس زیر حذف می‌کند: clear MyClass:45. استفاده از دستور clear یا stop بدون هیچ آرگومانی، فهرستی از تمام نقاط توقف فعلی را نمایش می‌دهد. دستور cont اجرای برنامه را ادامه می‌دهد.

دستور step اجرای برنامه را به خط بعدی منتقل می‌کند، چه در فریم پشته فعلی باشد و چه در یک متد فراخوانی‌شده. دستور next اجرای برنامه را به خط بعدی در فریم پشته فعلی منتقل می‌کند.

هنگامی که استثنایی (exception) رخ می‌دهد که هیچ عبارت catch برای آن در هیچ‌کجای پشته فراخوانی ریسمان پرتاب‌کننده وجود ندارد، JVM به طور معمول ردگیری استثنا (trace) را چاپ کرده و خارج می‌شود. اما هنگام اجرا تحت JDB، کنترل در همان نقطه پرتاب خطا به JDB بازمی‌گردد. سپس می‌توانید از دستور jdb برای تشخیص علت استثنا استفاده کنید.

از دستور catch استفاده کنید تا برنامه تحت اشکال‌زدایی در زمان پرتاب سایر استثناها متوقف شود؛ برای مثال: catch java.io.FileNotFoundException یا catch mypackage.BigTroubleException. هر استثنایی که نمونه‌ای از کلاس مشخص‌شده یا زیرکلاس‌های آن باشد، برنامه را در نقطه‌ای که استثنا پرتاب می‌شود متوقف می‌کند.

دستور ignore اثر یک دستور قبلی catch را خنثی می‌کند. دستور ignore باعث نمی‌شود که JVM در حال اشکال‌زدایی استثناهای مشخص را نادیده بگیرد، بلکه فقط باعث می‌شود که اشکال‌زدا آن‌ها را نادیده بگیرد.

هنگامی که از دستور jdb به جای دستور java در خط فرمان استفاده می‌کنید، دستور jdb بسیاری از همان گزینه‌های دستور java را می‌پذیرد.

گزینه‌های زیر توسط دستور jdb پشتیبانی می‌شوند:

-help
پیام راهنما را نمایش می‌دهد.
-sourcepath dir1:dir2:...
از مسیر مشخص‌شده برای جستجوی فایل‌های منبع استفاده می‌کند. اگر این گزینه مشخص نشود، از مسیر پیش‌فرض نقطه (.) استفاده می‌شود.
-attach address
اشکال‌زدا را با سازوکار اتصال پیش‌فرض به یک JVM در حال اجرا متصل می‌کند.
-listen address
منتظر می‌ماند تا یک JVM در حال اجرا با استفاده از یک اتصال‌دهنده استاندارد به نشانی مشخص‌شده متصل شود.
-listenany
منتظر می‌ماند تا یک JVM در حال اجرا با استفاده از یک اتصال‌دهنده استاندارد به هر نشانی در دسترسی متصل شود.
-launch
برنامه تحت اشکال‌زدایی را بلافاصله پس از راه‌اندازی دستور jdb شروع می‌کند. گزینه -launch نیاز به استفاده از دستور run را برطرف می‌سازد. برنامه تحت اشکال‌زدایی راه‌اندازی شده و سپس درست قبل از بارگذاری کلاس اولیه برنامه متوقف می‌شود. در آن نقطه می‌توانید هر نقطه توقف لازم را تنظیم کنید و با دستور cont به اجرای برنامه ادامه دهید.
-listconnectors
اتصال‌دهنده‌های (connectors) موجود در این JVM را فهرست می‌کند.
-connect connector-name:name1=value1....
با استفاده از اتصال‌دهنده نام‌گذاری‌شده و مقادیر آرگومان‌های ارائه‌شده، به JVM هدف متصل می‌شود.
-dbgtrace [flags]
اطلاعاتی را برای اشکال‌زدایی خود دستور jdb چاپ می‌کند.
-tclient
برنامه را در محیط کلاینت Java HotSpot VM اجرا می‌کند.
-trackallthreads
تمام ریسمان‌ها را به محض ایجاد شدن، شامل ریسمان‌های مجازی، ردگیری می‌کند. بخش کار با ریسمان‌های مجازی (WORKING WITH VIRTUAL THREADS) در ادامه را ببینید.
-tserver
برنامه را در محیط سرور Java HotSpot VM اجرا می‌کند.
-Joption
گزینه option را به JVM مربوط به JDB منتقل می‌کند، که در آن option یکی از گزینه‌های شرح‌داده‌شده در صفحه مرجع راه‌انداز برنامه جاوا است. برای مثال، -J-Xms48m مقدار حافظه زمان راه‌اندازی را روی ۴۸ مگابایت تنظیم می‌کند. بخش Overview of Java Options در صفحه راهنمای java را ببینید.

گزینه‌های زیر به فرآیند تحت اشکال‌زدایی (debuggee) هدایت می‌شوند:

-Roption
گزینه option را به JVM تحت اشکال‌زدایی منتقل می‌کند، که در آن option یکی از گزینه‌های شرح‌داده‌شده در صفحه مرجع راه‌انداز برنامه جاوا است. برای مثال، -R-Xms48m مقدار حافظه زمان راه‌اندازی را روی ۴۸ مگابایت تنظیم می‌کند. بخش Overview of Java Options در صفحه راهنمای java را ببینید.
-v یا -verbose[:class|gc|jni]
حالت پرگویی (verbose) را فعال می‌کند.
-Dname=value
یک ویژگی سیستمی (system property) را تنظیم می‌کند.
-classpath dir
فهرستی از دایرکتوری‌های جداشده با دو‌نقطه (:) را برای جستجوی کلاس‌ها مشخص می‌کند.
-X option
یک گزینه غیر استاندارد برای JVM هدف.

گزینه‌های دیگری نیز برای ارائه سازوکارهای جایگزین جهت اتصال اشکال‌زدا به JVM تحت اشکال‌زدایی پشتیبانی می‌شوند.

اغلب ریسمان‌های مجازی (Virtual Threads) با چنان تعداد و فرکانس بالایی ایجاد می‌شوند که می‌توانند بار بسیار سنگینی را به اشکال‌زدا تحمیل کنند. به همین دلیل، JDB به طور پیش‌فرض ریسمان‌های مجازی را به محض ایجاد شدن ردگیری نمی‌کند. این ابزار تنها ریسمان‌های مجازی را ردگیری می‌کند که رویدادی (مانند رویداد نقطه توقف) روی آن‌ها رخ داده باشد. از گزینه -trackallthreads می‌توان برای وادار کردن JDB به ردگیری تمامی ریسمان‌های مجازی به محض ایجاد آن‌ها استفاده کرد.

هنگامی که JDB برای اولین بار متصل می‌شود، فهرستی از تمام ریسمان‌های شناخته‌شده را از عامل اشکال‌زدایی (Debug Agent) درخواست می‌کند. به طور پیش‌فرض، عامل اشکال‌زدایی هیچ ریسمان مجازی را در این فهرست بازنمی‌گرداند؛ باز هم به این دلیل که فهرست ممکن است چنان بزرگ باشد که باعث تحمیل بار بیش از حد به اشکال‌زدا شود. عامل اشکال‌زدایی دارای یک گزینه includevirtualthreads است که با فعال کردن آن می‌توان این رفتار را تغییر داد تا تمام ریسمان‌های مجازی شناخته‌شده در فهرست گنجانده شوند. گزینه -trackallthreads در JDB باعث می‌شود که JDB هنگام راه‌اندازی یک برنامه برای اشکال‌زدایی، گزینه includevirtualthreads عامل اشکال‌زدایی را به صورت خودکار فعال کند. با این حال به یاد داشته باشید که ممکن است عامل اشکال‌زدایی از ریسمان‌های مجازی که قبل از اتصال JDB به برنامه ایجاد شده‌اند اطلاعی نداشته باشد.

2023 JDK 21