.TH SG_DECODE_SENSE "8" "مه 2023" "sg3_utils\-1.48" SG3_UTILS
.SH "نام (NAME)"
sg_decode_sense \- رمزگشایی داده‌های حسگر SCSI و داده‌های مرتبط
.SH "خلاصه دستور (SYNOPSIS)"
.B sg_decode_sense
[\fI\-\-binary=BFN\fR] [\fI\-\-cdb\fR] [\fI\-\-err=ES\fR] [\fI\-\-file=HFN\fR]
[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-inhex=HFN\fR]
[\fI\-\-ignore\-first\fR] [\fI\-\-json[=JO]\fR] [\fI\-\-js\-file=JFN\fR]
[\fI\-\-nodecode\fR] [\fI\-\-nospace\fR] [\fI\-\-status=SS\fR]
[\fI\-\-verbose\fR] [\fI\-\-version\fR] [\fI\-\-write=WFN\fR] [H1 H2 H3 ...]
.SH "توضیحات (DESCRIPTION)"
.\" Add any additional description here
این ابزار، داده‌های حسگر (sense data) در SCSI را به صورت باینری یا به عنوان دنباله‌ای از بایت‌های هگزادسیمال اسکی (ASCII hexadecimal) دریافت کرده و آن‌ها را رمزگشایی می‌کند. مرجع اصلی این رمزگشایی استانداردهای SPC\-5 ANSI INCITS 502\-2020 و جدیدترین پیش‌نویس SPC\-6 ویرایش ۶ است که می‌تواند در نشانی https://www.t10.org و دیگر بخش‌های اینترنت یافت شود.
.PP
داده‌های حسگر SCSI اغلب در فایل‌های لاگ هسته (kernel log) در نتیجه بروز خطا یا به عنوان یک هشدار اطلاعاتی یافت می‌شوند. این داده‌ها معمولاً به صورت دنباله‌ای از بایت‌های هگزادسیمال نمایش داده می‌شوند که با 70، 71، 72، 73، f0 یا f1 آغاز می‌شوند. داده‌های حسگر می‌توانند تا ۲۵۲ بایت طول داشته باشند اما به طور معمول بسیار کوتاه‌تر از آن هستند؛ طول ۱۸ بایت معمولاً مشاهده می‌شود و غالباً با قالب قدیمی‌تر داده‌های حسگر «ثابت» (fixed) مرتبط است.
.PP
داده‌های حسگر را می‌توان در خط فرمان یا درون یک فایل مشخص کرد. اگر در خط فرمان ارائه شوند، داده‌های حسگر باید دنباله‌ای از بایت‌های هگزادسیمال باشند که با فاصله (space) از هم جدا شده‌اند. همچنین می‌توان فایلی را مشخص کرد که محتوای آن بایت‌های باینری یا هگزادسیمال اسکی باشد. در حالت دوم، فایل می‌تواند شامل چندین خط باشد که هر خط شامل هیچ، یک یا چند بایت هگزادسیمال اسکی است که با فاصله (کاما یا تب) جدا شده‌اند. نماد هشتگ (#) نیز ممکن است در خط وجود داشته باشد که در این صورت، خود نماد و ادامه آن خط نادیده گرفته می‌شوند؛ این ویژگی برای درج توضیحات (کامنت) مفید است.
.PP
اگر گزینه
.I \-\-cdb
داده شود، به‌جای در نظر گرفتن آرگومان‌های هگز به عنوان داده‌های حسگر، به عنوان یک بلوک توصیف‌گر دستور SCSI (یا همان CDB) در نظر گرفته می‌شوند. در این حالت، نام دستور در خروجی چاپ می‌شود. این نام بر پایه نخستین بایت هگز داده‌شده (معروف به opcode یا کد عملیات) و به صورت اختیاری بر اساس فیلد دیگری به نام «service action» (اقدام سرویس) تعیین می‌شود.
.PP
عملکرد جایگزین دیگر زمانی است که گزینه
.I \-\-err=ES
داده شود. در این حالت، فرض می‌شود
.I ES
مقدار «وضعیت خروج» بین ۰ و ۲۵۵ از یکی از ابزارهای موجود در این بسته است. سپس یک رشته توصیفی چاپ می‌شود. سایر گزینه‌ها، به جز
.IR \-\-verbose ،
نادیده گرفته می‌شوند.
.PP
هنگامی که گزینه
.I \-\-nodecode
داده شود، می‌توان از این ابزار برای تبدیل یک فایل باینری به هگزادسیمال یا برعکس استفاده کرد. داده‌های تبدیل‌شده نیازی ندارند به داده‌های حسگر SCSI یا CDBها مربوط باشند.
.SH "گزینه‌ها (OPTIONS)"
آرگومان‌های گزینه‌های طولانی برای گزینه‌های کوتاه نیز الزامی هستند.
.TP
\fB\-b\fR, \fB\-\-binary\fR=\fIBFN\fR
داده‌ها به صورت باینری از فایلی به نام \fIBFN\fR خوانده می‌شوند. این گزینه را نمی‌توان همراه با \fI\-\-file=HFN\fR یا \fI\-\-inhex=HFN\fR استفاده کرد چرا که با یکدیگر در تضاد هستند. فرض می‌شود که داده‌ها از نوع داده‌های حسگر هستند، مگر اینکه گزینه \fI\-\-nodecode\fR مشخص شده باشد.
.TP
\fB\-c\fR, \fB\-\-cdb\fR
رشته آرگومان‌های هگز ارائه‌شده را به عنوان بایت‌های یک CDB در SCSI در نظر می‌گیرد و نام دستور را رمزگشایی می‌کند.
.TP
\fB\-e\fR, \fB\-\-err\fR=\fIES\fR
مقدار \fIES\fR باید یک مقدار «وضعیت خروج» بین ۰ و ۲۵۵ باشد که پس از پایان کار ابزار از طریق پوسته (یعنی محیط اجرای ابزار) در دسترس است. به صورت پیش‌فرض، یک پیام خطای توصیفی در خروجی استاندارد (stdout) چاپ می‌شود؛ و اگر گزینه \fI\-\-verbose\fR یک بار (یا تعداد فردی از دفعات) داده شود، پیام به جای آن در خطای استاندارد (stderr) چاپ می‌گردد. اگر \fI\-\-verbose\fR دو بار یا بیشتر داده شود، قالب طولانی‌تری از پیام در خروجی نمایش داده می‌شود. در تمام موارد، طول پیام کمتر از ۱۲۸ کاراکتر است و یک نویسه سرخط (line feed) در انتهای آن قرار دارد. تمام گزینه‌ها و آرگومان‌های دیگر خط فرمان نادیده گرفته می‌شوند.
.TP
\fB\-f\fR, \fB\-\-file\fR=\fIHFN\fR
داده‌های حسگر به صورت هگزادسیمال اسکی از فایلی به نام \fIHFN\fR خوانده می‌شوند. داده‌های حسگر باید به صورت دنباله‌ای از بایت‌ها باشند که با فاصله، کاما، تب، خط تیره یا خط جدید از هم جدا شده‌اند. هر چیزی از نماد هشتگ (#) تا انتهای آن خط نادیده گرفته می‌شود. اگر گزینه \fI\-\-nospace\fR تنظیم شده باشد، نیازی به جداکننده میان ارقام هگزادسیمال اسکی در \fIHFN\fR نیست و بایت‌ها از جفت‌رقم‌های هگزادسیمال اسکی رمزگشایی می‌شوند.
.TP
\fB\-h\fR, \fB\-\-help\fR
پیام راهنمای استفاده را نمایش داده و خارج می‌شود.
.TP
\fB\-H\fR, \fB\-\-hex\fR
این گزینه یک بار در ترکیب با \fI\-\-write=WFN\fR استفاده می‌شود تا خروجی نوشته‌شده در \fIWFN\fR را به خطوطی از بایت‌های هگز اسکی مناسب برای کامپایلر زبان C تغییر دهد. هر خط شامل حداکثر ۱۶ بایت است (برای نمونه خطی که با "0x3b,0x07,0x00,0xff" شروع می‌شود).
.br
در سایر موارد (یعنی هنگامی که \fI\-\-write=WFN\fR داده نشده باشد، یا این گزینه بیش از یک بار داده شود) خروجی مطابق توضیحات صفحه راهنمای sg3_utils(8) خواهد بود.
.br
ترکیب \fI\-\-inhex=HFN\fR و سه بار استفاده از این گزینه می‌تواند برای تبدیل بایت‌های هگزادسیمال (مثلاً جداشده با خط تیره) به قالبی منظم‌تر مفید باشد. شکل کوتاه این گزینه برای سه بار فراخوانی آن مناسب‌تر است (مانند '\-HHH').
.TP
\fB\-i\fR, \fB\-\-inhex\fR=\fIHFN\fR
عملکردی مشابه با \fI\-\-file=HFN\fR دارد. این گزینه برای سازگاری با سایر ابزارهای این بسته که دارای گزینه \fI\-\-inhex=\fR هستند اضافه شده است.
.TP
\fB\-I\fR, \fB\-\-ignore\-first\fR
بسیاری از برنامه‌هایی که بایت‌های هگز را در خروجی نمایش می‌دهند (مانند 'hexdump \-C')، یک شمارنده پیوسته (یا نمایه/شاخص) در ستون نخست هر خط دارند. این گزینه نخستین مقدار هگزادسیمال در هر خط را نادیده می‌گیرد. این گزینه در صورتی که گزینه‌های \fI\-\-binary=BFN\fR یا \fI\-\-nospace\fR داده شده باشند هیچ تاثیری ندارد. خطوط خالی و هر کاراکتری از نویسه "#" به بعد در یک خط نادیده گرفته می‌شوند. استفاده از این گزینه همراه با گزینه‌های \fI\-\-file=HFN\fR و \fI\-\-nodecode\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 فرستاده می‌شود. اگر آن فایل از قبل وجود داشته باشد، محتوای آن پاک (کوتاه/truncate) می‌شود. به صورت پیش‌فرض، خروجی JSON به stdout فرستاده می‌شود.
.br
هنگامی که این گزینه داده شود، گزینه \fI\-\-json[=JO]\fR به صورت ضمنی فعال تلقی شده و نیازی به ذکر آن نیست. ممکن است همچنان به گزینه \fI\-\-json[=JO]\fR برای تنظیم پارامتر \fIJO\fR روی مقادیری غیر از پیش‌فرض نیاز باشد.
.TP
\fB\-N\fR, \fB\-\-nodecode\fR
داده‌های داده‌شده را به عنوان داده‌های حسگر یا cdb رمزگشایی نمی‌کند. زمانی که داده‌های دلخواه ارائه شده باشند (مانند هنگام تبدیل هگز به باینری یا برعکس) کاربردی است.
.TP
\fB\-n\fR, \fB\-\-nospace\fR
انتظار دارد هگزادسیمال اسکی، رشته‌ای از ارقام هگزادسیمال بدون هیچ فاصله‌ای میان آن‌ها باشد. بایت‌ها با در نظر گرفتن هم‌زمان دو رقم هگزادسیمال رمزگشایی می‌شوند، بنابراین تعداد زوجی از ارقام مورد انتظار است. رشته ارقام هگزادسیمال می‌تواند در خط فرمان باشد (به جای "H1 H2 H3") یا در چندین خط در فایل \fIHFN\fR ارائه‌شده به \fI\-\-file=\fR پخش شده باشد. در خط فرمان، فاصله‌ها (یا سایر نویسه‌های فاصله خالی) میان دنباله‌های ارقام هگزادسیمال نادیده گرفته می‌شوند؛ حداکثر طول رشته هگز خط فرمان ۱۰۲۳ کاراکتر است.
.TP
\fB\-s\fR, \fB\-\-status\fR=\fISS\fR
که در آن \fISS\fR مقدار بایت وضعیت SCSI است که به صورت هگزادسیمال داده می‌شود. بایت وضعیت SCSI با داده‌های حسگر مرتبط است، اما از آن متمایز می‌باشد.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
افزایش سطح پرگویی (پیام‌های اشکال‌زدایی).
.TP
\fB\-V\fR, \fB\-\-version\fR
نمایش رشته نگارش و خروج.
.TP
\fB\-w\fR, \fB\-\-write\fR=\fIWFN\fR
داده‌های حسگر را در فایلی به نام \fIWFN\fR می‌نویسد. در صورت لزوم، \fIWFN\fR ایجاد می‌شود. اگر \fIWFN\fR از قبل وجود داشته باشد، پیش از نوشتن داده‌های حسگر، محتوای آن پاک (کوتاه/truncate) می‌شود. اگر گزینه \fI\-\-hex\fR نیز داده شده باشد، هگز اسکی در \fIWFN\fR نوشته می‌شود (توضیحات گزینه \fI\-\-hex\fR را ببینید)؛ در غیر این صورت داده‌های باینری در \fIWFN\fR نوشته می‌شوند. این گزینه تسهیل‌کننده است و می‌تواند در تبدیل نمایش هگزادسیمال اسکیِ داده‌های حسگر (یا هر چیز دیگر) به داده‌های باینری معادل یا قالبی از هگز اسکی قابل‌کامپایل مفید باشد.
.SH "نکات (NOTES)"
برخلاف بیشتر ابزارهای موجود در این بسته، این ابزار به دستگاه SCSI (واحد منطقی یا LUN) دسترسی پیدا نمی‌کند. این ابزار به کتابخانه‌ای مرتبط با این بسته دسترسی دارد. در میان وظایف دیگر، این کتابخانه داده‌های حسگر SCSI را رمزگشایی می‌کند.
.PP
ابزار sg_raw دنباله‌ای از هگزادسیمال اسکی را دریافت می‌کند که نشان‌دهنده یک CDB در SCSI است. هنگامی که گزینه '\-vvv' به sg_raw داده شود، تلاش خواهد کرد نام CDB را رمزگشایی کند.
.PP
استفاده از ترکیب گزینه‌های "\fI\-\-inhex=HFN \-\-nodecode \-\-write=WFN\fR" می‌تواند برای تبدیل هگزادسیمال (تولیدشده توسط این ابزار و سایر ابزارهای این بسته) به باینری به کار رود، به گونه‌ای که فایل خروجی \fIWFN\fR خواهد بود.
.PP
برخلاف بسیاری از ابزارهای دیگر، هیچ گزینه \fI\-\-raw\fR وجود ندارد. با این حال داده‌های باینری را می‌توان با استفاده از گزینه \fI\-\-binary=BFN\fR وارد کرد، و داده‌های باینری را می‌توان با گزینه \fI\-\-write=WFN\fR (در نبود گزینه \fI\-\-hex\fR) در خروجی نوشت.
.SH "مثال‌ها (EXAMPLES)"
داده‌های حسگر اغلب در لاگ‌های هسته و گاهی در صورت استفاده از فلگ‌های پرگویی (verbose) یا اشکال‌زدایی در خط فرمان چاپ می‌شوند. طول آن‌ها دست‌کم ۸ بایت و غالباً ۱۸ بایت خواهد بود، اما ممکن است بیشتر باشد. یک رشته داده‌های حسگر ممکن است شبیه این باشد:
.PP
.nf
f0 00 03 00 00 12 34 0a  00 00 00 00 11 00 00 00
00 00
.fi
.PP
آن را پس از دستور sg_decode_sense جای‌گذاری (paste) کنید:
.PP
.nf
  sg_decode_sense f0 00 03 00 00 12 34 0a 00 00 00 00 11 00 00 00 00 00
.fi
.PP
و برای این داده‌های حسگر، خروجی باید به این شکل باشد:
.PP
.nf
 Fixed format, current;  Sense key: Medium Error
 Additional sense: Unrecovered read error
  Info fld=0x1234 [4660]
.fi
.PP
برای خطای Medium Error، فیلد Info همان نشانی بلوک منطقی (LBA) از کم‌شماره‌ترین بلوکی است که دستور SCSI مربوطه قادر به خواندن (بررسی یا نوشتن) آن نبوده است.
.PP
برای تبدیل داده‌های باینری دلخواه به هگز، به طوری که برای تجزیه توسط سایر ابزارهای sg3_utils مناسب باشد. در این حالت از گزینه \fI\-\-nodecode\fR استفاده می‌شود:
.PP
.nf
  sg_decode_sense \-N \-i vpd_zbdc.hex \-w vpd_zbdc.bin
.fi
.PP
گزینه '\-HHH' داده‌های هگز را به شکلی مناسب برای سایر ابزارهای این بسته در کنسول (stdout) چاپ می‌کند تا به عنوان ورودی تجزیه شوند. همچنین از sg_decode_sense می‌توان برای تبدیل هگز دلخواه به باینری با این دستور استفاده کرد:
.PP
.nf
  sg_decode_sense \-N \-b vpd_zbdc.raw \-HHH
.fi
.PP
توجه داشته باشید که ابزارهایی مانند hexdump و od یک شمارنده (یعنی نمایه‌ای که از 0 آغاز می‌شود) در ابتدای هر خط قرار می‌دهند که هنگام تجزیه هگز دردسرساز است. گزینه(های) '\-HHH' این شمارنده آغازین را در هر خط نمایش نمی‌دهد.
.SH "وضعیت خروج (EXIT STATUS)"
وضعیت خروج sg_decode_sense در صورت موفقیت‌آمیز بودن برابر 0 است. در غیر این صورت به صفحه راهنمای sg3_utils(8) مراجعه کنید.
.SH "نویسندگان (AUTHORS)"
نوشته‌شده توسط Douglas Gilbert.
.SH "گزارش باگ‌ها (REPORTING BUGS)"
گزارش باگ‌ها به <dgilbert at interlog dot com>.
.SH "حق نشر (COPYRIGHT)"
حق نشر \(co 2010\-2022 Douglas Gilbert
.br
این نرم‌افزار تحت مجوز BSD\-2\-Clause توزیع شده است. هیچ ضمانتی وجود ندارد؛ حتی برای قابلیت تجاری یا مناسب بودن برای یک هدف خاص.
.SH "همچنین ببینید (SEE ALSO)"
.B sg_requests,sg_raw(sg3_utils)