.TH SG_GET_ELEM_STATUS "8" "June 2023" "sg3_utils\-1.48" SG3_UTILS
.SH "نام (NAME)"
sg_get_elem_status \- ارسال دستور SCSI GET PHYSICAL ELEMENT STATUS
.SH "خلاصه دستور (SYNOPSIS)"
.B sg_get_elem_status
[\fI\-\-brief\fR] [\fI\-\-filter=FLT\fR] [\fI\-\-help\fR] [\fI\-\-hex\fR]
[\fI\-\-inhex=FN\fR] [\fI\-\-json[=JO\fR]] [\fI\-\-js\-file=JFN\fR]
[\fI\-\-maxlen=LEN\fR] [\fI\-\-raw\fR] [\fI\-\-readonly\fR]
[\fI\-\-report\-type=RT\fR] [\fI\-\-starting=ELEM\fR] [\fI\-\-verbose\fR]
[\fI\-\-version\fR] \fIDEVICE\fR
.SH "توضیحات (DESCRIPTION)"
.\" Add any additional description here
دستور SCSI GET PHYSICAL ELEMENT STATUS را به \fIDEVICE\fR ارسال کرده و پاسخ را در خروجی نمایش می‌دهد. این دستور در ویرایش ۱۶ پیش‌نویس استاندارد SBC\-4 معرفی شد.
.PP
پیش‌نویس‌های T10 اکنون هم از عنصرهای «فیزیکی» (physical) و هم «ذخیره‌سازی» (storage) صحبت می‌کنند. اصطلاح دوم خاص‌تر است (یعنی عنصرهای ذخیره‌سازی زیرمجموعه‌ای از عنصرهای فیزیکی هستند) و به منابع دیسکی که ذخیره‌سازی داده‌های کاربر را کنترل می‌کنند اشاره دارد. نمونه‌ای از یک عنصر ذخیره‌سازی، داده‌های کاربری مرتبط با یک هد در یک دیسک سخت چرخان است. هنگامی که یک عنصر ذخیره‌سازی «تخلیه» (depopulated) می‌شود، فضای ذخیره‌سازی پیشین آن که از طریق LBAها در دسترس بود دیگر در دسترس نیست. عنصرهای فیزیکی عام‌تر هستند و شامل عنصرهای ذخیره‌سازی شده و ممکن است علاوه بر موارد دیگر، منابع دیسک مورد استفاده برای تنظیمات «ذخیره‌شده» در صفحه حالت (mode page) را نیز در بر گیرند.
.PP
عملکرد پیش‌فرض این ابزار، رمزگشایی پاسخ به یک هدر و حداکثر ۳۲ توصیف‌گر وضعیت عنصر فیزیکی است. توصیف‌گرهای وضعیت در هر خط یکی چاپ می‌شوند. مقدار خروجی را می‌توان با گزینه
\fI\-\-brief\fR
کاهش داد.
.PP
به‌جای ارسال این دستور SCSI به \fIDEVICE\fR، اگر گزینه
\fI\-\-inhex=FN\fR
داده شود، محتویات پرونده‌ای با نام \fIFN\fR به‌صورت هگزادسیمال اسکی (یا در صورت تعیین
\fI\-\-raw\fR
به‌صورت باینری) رمزگشایی شده و سپس طوری پردازش می‌شود که گویی پاسخ دستور GET PHYSICAL ELEMENT STATUS بوده است.
.SH "گزینه‌ها (OPTIONS)"
آرگومان‌های گزینه‌های بلند برای گزینه‌های کوتاه نیز الزامی هستند.
.TP
\fB\-b\fR, \fB\-\-brief\fR
هنگامی که یک بار استفاده شود، خروجی هر توصیف‌گر وضعیت عنصر فیزیکی در مقایسه با حالتی که این گزینه داده نشده خلاصه می‌شود. همچنین عبارت "associated capacity: not specified;" به دلیل اینکه اطلاعات چندانی منتقل نمی‌کند حذف می‌گردد.
.br
هنگامی که دو بار استفاده شود، خروجی هر توصیف‌گر وضعیت عنصر فیزیکی به این شکل خلاصه می‌شود: <element_id>: <element_type>,<element_health> . هر سه مقدار به‌صورت اعداد صحیح در مبنای ۱۰ نمایش داده می‌شوند. در صورت استفاده دو بار، خط معرفی‌کننده توصیف‌گرهای وضعیت یعنی "Element descriptors:" چاپ نمی‌شود. در صورت استفاده سه بار یا بیشتر، تنها هدر پاسخ در خروجی نمایش داده می‌شود.
.TP
\fB\-f\fR, \fB\-\-filter\fR=\fIFLT\fR
که در آن \fIFLT\fR در یک فیلد دو بیتی به نام FILTER در دستور GET PHYSICAL ELEMENT STATUS قرار می‌گیرد. تنها دو مقدار برای این فیلد تعریف شده است: ۰ برای تمام توصیف‌گرهای عنصر؛ ۱ برای توصیف‌گرهایی که خارج از «مشخصات» (spec) هستند یا اطلاعات تخلیه (depopulation) برای گزارش دارند. در هر دو حالت، فیلدهای REPORT TYPE و STARTING ELEMENT ممکن است تعداد توصیف‌گرهای بازگردانده شده را بیشتر محدود (کمتر) کنند. مقدار پیش‌فرض صفر است.
.TP
\fB\-h\fR, \fB\-\-help\fR
نمایش پیام راهنمای نحوه استفاده و سپس خروج.
.TP
\fB\-H\fR, \fB\-\-hex\fR
نمایش پاسخ به این دستور به‌صورت هگزادسیمال اسکی. در ابتدای هر خطِ ۱۶ بایتی یک آدرس یا نمایه که از ۰ شروع می‌شود قرار می‌گیرد و آدرس نیز در مبنای ۱۶ است. اگر دو بار داده شود، نمایش اسکی هر بایت به انتهای خط خروجی اضافه می‌شود. اگر سه بار یا بیشتر داده شود، تنها هگزادسیمال اسکی هر بایت، به‌صورت ۱۶ بایت در هر خط نمایش داده می‌شود (یعنی بدون آدرس در ابتدا و بدون نمایش کاراکتری اسکی در انتها). این شکل اخیر برای ذخیره در یک پرونده و استفاده با گزینه
\fI\-\-inhex=FN\fR
در اجراهای بعدی مناسب است.
.TP
\fB\-i\fR, \fB\-\-inhex\fR=\fIFN\fR
که در آن \fIFN\fR نام پرونده‌ای است که فرض می‌شود محتوای آن هگزادسیمال اسکی است. اگر \fIDEVICE\fR نیز داده شود، \fIDEVICE\fR نادیده گرفته شده، یک هشدار صادر می‌شود و ابزار با رمزگشایی پرونده \fIFN\fR به کار خود ادامه می‌دهد. برای اطلاعات بیشتر بخش "HEX, BINARY AND JSON FORMATS" در صفحه راهنمای sg3_utils را ببینید. اگر گزینه
\fI\-\-raw\fR
نیز داده شده باشد، محتویات \fIFN\fR به‌صورت باینری در نظر گرفته می‌شود.
.TP
\fB\-j\fR[=\fIJO\fR], \fB\-\-json\fR[=\fIJO\fR]
خروجی به‌جای متن ساده در قالب JSON ارائه می‌شود. توجه داشته باشید که آرگومان‌های شکل‌های کوتاه و بلند خود اختیاری بوده و در صورت وجود با "=" شروع می‌شوند و هیچ فاصله‌ای در اطراف آن "=" مجاز نیست.
.br
برای اطلاعات بیشتر صفحه راهنمای sg3_utils_json را ببینید یا برای دریافت خلاصه، برای \fIJO\fR مقدار '?' قرار دهید.
.TP
\fB\-J\fR, \fB\-\-js\-file\fR=\fIJFN\fR
خروجی در قالب JSON بوده و به پرونده‌ای با نام \fIJFN\fR ارسال می‌شود. اگر آن پرونده وجود داشته باشد بازنویسی (کوتاه) می‌شود. به‌طور پیش‌فرض، خروجی JSON به خروجی استاندارد (stdout) فرستاده می‌شود.
.br
هنگامی که این گزینه داده شود، گزینه
\fI\-\-json[=JO]\fR
به‌طور ضمنی در نظر گرفته می‌شود و نیازی به ذکر آن نیست. ممکن است همچنان برای تنظیم پارامتر \fIJO\fR به مقادیر غیرپیش‌فرض، به گزینه
\fI\-\-json[=JO]\fR
نیاز باشد.
.TP
\fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
که در آن \fILEN\fR طول (حداکثر) پاسخ بر حسب بایت است. این مقدار در فیلد "allocation length" در cdb قرار می‌گیرد. در صورت مشخص نشدن، از ۱۰۵۶ استفاده می‌شود. مقدار ۱۰۵۶ فضای کافی برای هدر پاسخ به همراه ۳۲ توصیف‌گر وضعیت عنصر فیزیکی است. \fILEN\fR باید مضربی از ۳۲ باشد (برای نمونه ۳۲، ۶۴ و ۹۶ مناسب هستند).
.TP
\fB\-r\fR, \fB\-\-raw\fR
خروجی پاسخ را به‌صورت باینری (در stdout) ارسال می‌کند، مگر اینکه گزینه
\fI\-\-inhex=FN\fR
نیز داده شده باشد. در این حالت، نام پرونده ورودی (\fIFN\fR) به‌صورت باینری رمزگشایی می‌شود (و خروجی به‌صورت باینری نخواهد بود).
.TP
\fB\-R\fR, \fB\-\-readonly\fR
دستگاه \fIDEVICE\fR را فقط‌خواندنی باز می‌کند (مثلاً در یونیکس با پرچم O_RDONLY). حالت پیش‌فرض، باز کردن آن به‌صورت خواندنی\-نوشتنی است.
.TP
\fB\-t\fR, \fB\-\-report\-type\fR=\fIRT\fR
که در آن \fIRT\fR در فیلد REPORT TYPE دستور GET PHYSICAL ELEMENT STATUS قرار می‌گیرد. در حال حاضر تنها دو مقدار تعریف شده است: ۰ برای «عنصر فیزیکی» (physical element) و ۱ برای «عنصر ذخیره‌سازی» (storage element). مقدار پیش‌فرض ۰ است.
.TP
\fB\-s\fR, \fB\-\-starting\fR=\fIELEM\fR
که در آن \fIELEM\fR در فیلد STARTING ELEMENT دستور GET PHYSICAL ELEMENT STATUS قرار می‌گیرد. تنها عنصرهای فیزیکی با شناسه‌های بزرگ‌تر یا مساوی با \fIELEM\fR بازگردانده می‌شوند. مقدار پیش‌فرض صفر است که اگرچه یک شناسه عنصر معتبر نیست (چون باید غیرصفر باشند)، در یک مثال در پیوست L از SBC\-4 ویرایش ۱۷ آورده شده است. بنابراین مقدار صفر برای \fIELEM\fR در این زمینه معتبر در نظر گرفته می‌شود.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
افزایش سطح پرگویی (یعنی خروجی اشکال‌زدایی). خروجی‌های اضافی ناشی از این گزینه به خطای استاندارد (stderr) فرستاده می‌شوند.
.TP
\fB\-V\fR, \fB\-\-version\fR
چاپ نگارش برنامه و سپس خروج.
.SH "نکات (NOTES)"
کد حس اضافی "Warning \- physical element status change" مقدار [0xb, 0x14] خاص است و باید کلاینت برنامه را وادار به فراخوانی دستور GET PHYSICAL ELEMENT STATUS کند. نحوه فعال شدن این هشدار به تنظیمات موجود در صفحه حالت Informational Exceptions Control [0xc, 0x0] بستگی دارد.
.PP
پس از شناسایی یک یا چند عنصر ذخیره‌سازی خارج از مشخصات (out\-of\-spec)، دیسک مورد نظر باید از رده خارج شود یا دستور REMOVE ELEMENT AND TRUNCATE (یا ... AND MODIFY ZONES) برای تعمیر (و کاهش ظرفیت ذخیره‌سازی) دیسک روی آن فراخوانی شود.
.SH "وضعیت خروج (EXIT STATUS)"
وضعیت خروج sg_get_elem_status در صورت موفقیت ۰ است. در غیر این صورت صفحه راهنمای sg3_utils(8) را ببینید.
.SH "نویسندگان (AUTHORS)"
نوشته شده توسط Douglas Gilbert.
.SH "گزارش باگ‌ها (REPORTING BUGS)"
گزارش باگ‌ها به <dgilbert at interlog dot com>.
.SH "حق نشر (COPYRIGHT)"
حق نشر \(co 2019\-2022 Douglas Gilbert
.br
این نرم‌افزار تحت مجوز BSD\-2\-Clause توزیع می‌شود. هیچ ضمانتی وجود ندارد؛ حتی برای قابلیت فروش یا تناسب با یک هدف خاص.
.SH "همچنین ببینید (SEE ALSO)"
.B sg_get_lba_status,sg3_utils,sg3_utils_json(sg3_utils)