.\" Copyright (c) 1995, 2023, Oracle and/or its affiliates. All rights reserved.
.\" DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
.\"
.\" This code is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License version 2 only, as
.\" published by the Free Software Foundation.
.\"
.\" This code is distributed in the hope that it will be useful, but WITHOUT
.\" ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
.\" FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" version 2 for more details (a copy is included in the LICENSE file that
.\" accompanied this code).
.\"
.\" You should have received a copy of the GNU General Public License version
.\" 2 along with this work; if not, write to the Free Software Foundation,
.\" Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
.\"
.\" Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
.\" or visit www.oracle.com if you need additional information or have any
.\" questions.
.\"
.\" Automatically generated by Pandoc 2.19.2
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[R]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "JDB" "1" "2023" "JDK 21" "دستورهای JDK"
.hy
.SH "نام (NAME)"
.PP
jdb-openjdk21 \- دیباگر تعاملی برنامه‌های جاوا در OpenJDK 21
.SH "خلاصه دستور (SYNOPSIS)"
.PP
\f[V]jdb\f[R] [\f[I]گزینه‌ها\f[R]] [\f[I]نام‌کلاس\f[R]]
[\f[I]آرگومان‌ها\f[R]]
.TP
\f[I]گزینه‌ها\f[R]
این بخش نشان‌دهنده گزینه‌های خط فرمان \f[V]jdb\f[R] است.
بخش \f[B]گزینه‌های دستور JDB (OPTIONS FOR THE JDB COMMAND)\f[R] را ببینید.
.TP
\f[I]نام‌کلاس\f[R]
این بخش نشان‌دهنده نام کلاس اصلی برای اشکال‌زدایی (دیباگ) است.
.TP
\f[I]آرگومان‌ها\f[R]
این بخش نشان‌دهنده آرگومان‌هایی است که به متد \f[V]main()\f[R]
کلاس پاس داده می‌شوند.
.SH "توضیحات (DESCRIPTION)"
.PP
اشکال‌زدای جاوا (JDB) یک ابزار خط فرمانی ساده برای اشکال‌زدایی کلاس‌های جاوا است.
دستور \f[V]jdb\f[R] و گزینه‌های آن، JDB را فراخوانی می‌کنند.
دستور \f[V]jdb\f[R] معماری اشکال‌زدایی پلتفرم جاوا (Java Platform Debugger Architecture)
را به نمایش می‌گذارد و امکان بررسی و اشکال‌زدایی یک JVM محلی یا راه‌دور را فراهم می‌کند.
.SH "شروع یک نشست JDB (START A JDB SESSION)"
.PP
راه‌های متعددی برای شروع یک نشست JDB وجود دارد.
متداول‌ترین روش این است که JDB یک JVM جدید را همراه با کلاس اصلی برنامه‌ای که قرار است اشکال‌زدایی شود راه‌اندازی کند.
این کار با جایگزین کردن دستور \f[V]jdb\f[R] به جای دستور \f[V]java\f[R] در خط فرمان انجام می‌شود.
برای مثال، اگر کلاس اصلی برنامه شما \f[V]MyClass\f[R] است، از دستور زیر برای اشکال‌زدایی آن تحت JDB استفاده کنید:
.RS
.PP
\f[V]jdb MyClass\f[R]
.RE
.PP
هنگامی که JDB به این صورت شروع می‌شود، دستور \f[V]jdb\f[R] یک JVM ثانویه را با پارامترهای مشخص‌شده فراخوانی می‌کند،
کلاس تعیین‌شده را بارگذاری می‌نماید و پیش از اجرای نخستین دستورالعمل آن کلاس، JVM را متوقف می‌کند.
.PP
روش دیگر برای استفاده از دستور \f[V]jdb\f[R]، متصل کردن (attach) آن به یک JVM در حال اجرا است.
سینتکس راه‌اندازی یک JVM که دستور \f[V]jdb\f[R] در زمان اجرا به آن متصل می‌شود، به شرح زیر است.
این کار کتابخانه‌های اشکال‌زدایی درون‌فرآیندی را بارگذاری کرده و نوع اتصال مورد نظر را مشخص می‌سازد:
.RS
.PP
\f[V]java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n MyClass\f[R]
.RE
.PP
سپس می‌توانید دستور \f[V]jdb\f[R] را با دستور زیر به JVM متصل کنید:
.RS
.PP
\f[V]jdb -attach 8000\f[R]
.RE
.PP
عدد 8000 نشانی JVM در حال اجرا است.
.PP
در این حالت، آرگومان \f[V]MyClass\f[R] در خط فرمان \f[V]jdb\f[R] مشخص نمی‌شود زیرا دستور \f[V]jdb\f[R]
به جای راه‌اندازی یک JVM جدید، به یک JVM موجود متصل می‌شود.
.PP
راه‌های بسیار دیگری نیز برای اتصال اشکال‌زدا به یک JVM وجود دارد که همگی توسط دستور \f[V]jdb\f[R] پشتیبانی می‌شوند.
مستندات معماری اشکال‌زدایی پلتفرم جاوا شامل توضیحات تکمیلی درباره این گزینه‌های اتصال است.
.SH "نقاط توقف (BREAKPOINTS)"
.PP
نقاط توقف (Breakpoints) را می‌توان در JDB روی شماره خطوط یا روی اولین دستورالعمل یک متد تنظیم کرد؛ برای مثال:
.IP \[bu] 2
دستور \f[V]stop at MyClass:22\f[R] یک نقطه توقف در نخستین دستورالعمل برای خط ۲۲ از فایل منبع حاوی \f[V]MyClass\f[R] تنظیم می‌کند.
.IP \[bu] 2
دستور \f[V]stop in java.lang.String.length\f[R] یک نقطه توقف در ابتدای متد \f[V]java.lang.String.length\f[R] تنظیم می‌کند.
.IP \[bu] 2
دستور \f[V]stop in MyClass.<clinit>\f[R] از \f[V]<clinit>\f[R] برای مشخص کردن کد مقداردهی اولیه ایستا (static initialization) برای \f[V]MyClass\f[R] استفاده می‌کند.
.PP
هنگامی که یک متد دارای سربارگذاری (overload) است، باید انواع آرگومان‌های آن را نیز مشخص کنید تا متد مناسب برای نقطه توقف انتخاب شود؛
برای مثال، \f[V]MyClass.myMethod(int,java.lang.String)\f[R] یا \f[V]MyClass.myMethod()\f[R].
.PP
دستور \f[V]clear\f[R] نقاط توقف را با سینتکس زیر حذف می‌کند: \f[V]clear MyClass:45\f[R].
استفاده از دستور \f[V]clear\f[R] یا \f[V]stop\f[R] بدون هیچ آرگومانی، فهرستی از تمام نقاط توقف فعلی را نمایش می‌دهد.
دستور \f[V]cont\f[R] اجرای برنامه را ادامه می‌دهد.
.SH "گام‌به‌گام پیش رفتن (STEPPING)"
.PP
دستور \f[V]step\f[R] اجرای برنامه را به خط بعدی منتقل می‌کند، چه در فریم پشته فعلی باشد و چه در یک متد فراخوانی‌شده.
دستور \f[V]next\f[R] اجرای برنامه را به خط بعدی در فریم پشته فعلی منتقل می‌کند.
.SH "استثناها (EXCEPTIONS)"
.PP
هنگامی که استثنایی (exception) رخ می‌دهد که هیچ عبارت \f[V]catch\f[R] برای آن در هیچ‌کجای پشته فراخوانی ریسمان پرتاب‌کننده وجود ندارد،
JVM به طور معمول ردگیری استثنا (trace) را چاپ کرده و خارج می‌شود.
اما هنگام اجرا تحت JDB، کنترل در همان نقطه پرتاب خطا به JDB بازمی‌گردد.
سپس می‌توانید از دستور \f[V]jdb\f[R] برای تشخیص علت استثنا استفاده کنید.
.PP
از دستور \f[V]catch\f[R] استفاده کنید تا برنامه تحت اشکال‌زدایی در زمان پرتاب سایر استثناها متوقف شود؛ برای مثال:
\f[V]catch java.io.FileNotFoundException\f[R] یا \f[V]catch\f[R] \f[V]mypackage.BigTroubleException\f[R].
هر استثنایی که نمونه‌ای از کلاس مشخص‌شده یا زیرکلاس‌های آن باشد، برنامه را در نقطه‌ای که استثنا پرتاب می‌شود متوقف می‌کند.
.PP
دستور \f[V]ignore\f[R] اثر یک دستور قبلی \f[V]catch\f[R] را خنثی می‌کند.
دستور \f[V]ignore\f[R] باعث نمی‌شود که JVM در حال اشکال‌زدایی استثناهای مشخص را نادیده بگیرد، بلکه فقط باعث می‌شود که اشکال‌زدا آن‌ها را نادیده بگیرد.
.SH "گزینه‌های دستور JDB (OPTIONS FOR THE JDB COMMAND)"
.PP
هنگامی که از دستور \f[V]jdb\f[R] به جای دستور \f[V]java\f[R] در خط فرمان استفاده می‌کنید،
دستور \f[V]jdb\f[R] بسیاری از همان گزینه‌های دستور \f[V]java\f[R] را می‌پذیرد.
.PP
گزینه‌های زیر توسط دستور \f[V]jdb\f[R] پشتیبانی می‌شوند:
.TP
\f[V]-help\f[R]
پیام راهنما را نمایش می‌دهد.
.TP
\f[V]-sourcepath\f[R] \f[I]dir1\f[R]\f[V]:\f[R]\f[I]dir2\f[R]\f[V]:\f[R]...
از مسیر مشخص‌شده برای جستجوی فایل‌های منبع استفاده می‌کند.
اگر این گزینه مشخص نشود، از مسیر پیش‌فرض نقطه (\f[V].\f[R]) استفاده می‌شود.
.TP
\f[V]-attach\f[R] \f[I]address\f[R]
اشکال‌زدا را با سازوکار اتصال پیش‌فرض به یک JVM در حال اجرا متصل می‌کند.
.TP
\f[V]-listen\f[R] \f[I]address\f[R]
منتظر می‌ماند تا یک JVM در حال اجرا با استفاده از یک اتصال‌دهنده استاندارد به نشانی مشخص‌شده متصل شود.
.TP
\f[V]-listenany\f[R]
منتظر می‌ماند تا یک JVM در حال اجرا با استفاده از یک اتصال‌دهنده استاندارد به هر نشانی در دسترسی متصل شود.
.TP
\f[V]-launch\f[R]
برنامه تحت اشکال‌زدایی را بلافاصله پس از راه‌اندازی دستور \f[V]jdb\f[R] شروع می‌کند.
گزینه \f[V]-launch\f[R] نیاز به استفاده از دستور \f[V]run\f[R] را برطرف می‌سازد.
برنامه تحت اشکال‌زدایی راه‌اندازی شده و سپس درست قبل از بارگذاری کلاس اولیه برنامه متوقف می‌شود.
در آن نقطه می‌توانید هر نقطه توقف لازم را تنظیم کنید و با دستور \f[V]cont\f[R] به اجرای برنامه ادامه دهید.
.TP
\f[V]-listconnectors\f[R]
اتصال‌دهنده‌های (connectors) موجود در این JVM را فهرست می‌کند.
.TP
\f[V]-connect\f[R] \f[I]connector-name\f[R]\f[V]:\f[R]\f[I]name1\f[R]\f[V]=\f[R]\f[I]value1\f[R]....
با استفاده از اتصال‌دهنده نام‌گذاری‌شده و مقادیر آرگومان‌های ارائه‌شده، به JVM هدف متصل می‌شود.
.TP
\f[V]-dbgtrace\f[R] [\f[I]flags\f[R]]
اطلاعاتی را برای اشکال‌زدایی خود دستور \f[V]jdb\f[R] چاپ می‌کند.
.TP
\f[V]-tclient\f[R]
برنامه را در محیط کلاینت Java HotSpot VM اجرا می‌کند.
.TP
\f[V]-trackallthreads\f[R]
تمام ریسمان‌ها را به محض ایجاد شدن، شامل ریسمان‌های مجازی، ردگیری می‌کند.
بخش \f[B]کار با ریسمان‌های مجازی (WORKING WITH VIRTUAL THREADS)\f[R] در ادامه را ببینید.
.TP
\f[V]-tserver\f[R]
برنامه را در محیط سرور Java HotSpot VM اجرا می‌کند.
.TP
\f[V]-J\f[R]\f[I]option\f[R]
گزینه \f[I]option\f[R] را به JVM مربوط به JDB منتقل می‌کند، که در آن option یکی از گزینه‌های شرح‌داده‌شده در صفحه مرجع راه‌انداز برنامه جاوا است.
برای مثال، \f[V]-J-Xms48m\f[R] مقدار حافظه زمان راه‌اندازی را روی ۴۸ مگابایت تنظیم می‌کند.
بخش \f[I]Overview of Java Options\f[R] در صفحه راهنمای \f[B]java\f[R] را ببینید.
.PP
گزینه‌های زیر به فرآیند تحت اشکال‌زدایی (debuggee) هدایت می‌شوند:
.TP
\f[V]-R\f[R]\f[I]option\f[R]
گزینه \f[I]option\f[R] را به JVM تحت اشکال‌زدایی منتقل می‌کند، که در آن option یکی از گزینه‌های شرح‌داده‌شده در صفحه مرجع راه‌انداز برنامه جاوا است.
برای مثال، \f[V]-R-Xms48m\f[R] مقدار حافظه زمان راه‌اندازی را روی ۴۸ مگابایت تنظیم می‌کند.
بخش \f[I]Overview of Java Options\f[R] در صفحه راهنمای \f[B]java\f[R] را ببینید.
.TP
\f[V]-v\f[R] یا \f[V]-verbose\f[R][\f[V]:\f[R]\f[I]class\f[R]|\f[V]gc\f[R]|\f[V]jni\f[R]]
حالت پرگویی (verbose) را فعال می‌کند.
.TP
\f[V]-D\f[R]\f[I]name\f[R]\f[V]=\f[R]\f[I]value\f[R]
یک ویژگی سیستمی (system property) را تنظیم می‌کند.
.TP
\f[V]-classpath\f[R] \f[I]dir\f[R]
فهرستی از دایرکتوری‌های جداشده با دو‌نقطه (:) را برای جستجوی کلاس‌ها مشخص می‌کند.
.TP
\f[V]-X\f[R] \f[I]option\f[R]
یک گزینه غیر استاندارد برای JVM هدف.
.PP
گزینه‌های دیگری نیز برای ارائه سازوکارهای جایگزین جهت اتصال اشکال‌زدا به JVM تحت اشکال‌زدایی پشتیبانی می‌شوند.
.SH "کار با ریسمان‌های مجازی (WORKING WITH VIRTUAL THREADS)"
.PP
اغلب ریسمان‌های مجازی (Virtual Threads) با چنان تعداد و فرکانس بالایی ایجاد می‌شوند که می‌توانند بار بسیار سنگینی را به اشکال‌زدا تحمیل کنند.
به همین دلیل، JDB به طور پیش‌فرض ریسمان‌های مجازی را به محض ایجاد شدن ردگیری نمی‌کند.
این ابزار تنها ریسمان‌های مجازی را ردگیری می‌کند که رویدادی (مانند رویداد نقطه توقف) روی آن‌ها رخ داده باشد.
از گزینه \f[V]-trackallthreads\f[R] می‌توان برای وادار کردن JDB به ردگیری تمامی ریسمان‌های مجازی به محض ایجاد آن‌ها استفاده کرد.
.PP
هنگامی که JDB برای اولین بار متصل می‌شود، فهرستی از تمام ریسمان‌های شناخته‌شده را از عامل اشکال‌زدایی (Debug Agent) درخواست می‌کند.
به طور پیش‌فرض، عامل اشکال‌زدایی هیچ ریسمان مجازی را در این فهرست بازنمی‌گرداند؛ باز هم به این دلیل که فهرست ممکن است چنان بزرگ باشد که باعث تحمیل بار بیش از حد به اشکال‌زدا شود.
عامل اشکال‌زدایی دارای یک گزینه \f[V]includevirtualthreads\f[R] است که با فعال کردن آن می‌توان این رفتار را تغییر داد تا تمام ریسمان‌های مجازی شناخته‌شده در فهرست گنجانده شوند.
گزینه \f[V]-trackallthreads\f[R] در JDB باعث می‌شود که JDB هنگام راه‌اندازی یک برنامه برای اشکال‌زدایی،
گزینه \f[V]includevirtualthreads\f[R] عامل اشکال‌زدایی را به صورت خودکار فعال کند.
با این حال به یاد داشته باشید که ممکن است عامل اشکال‌زدایی از ریسمان‌های مجازی که قبل از اتصال JDB به برنامه ایجاد شده‌اند اطلاعی نداشته باشد.