.TH SG_STREAM_CTL "8" "December 2023" "sg3_utils\-1.49" SG3_UTILS
.SH "نام (NAME)"
sg_stream_ctl \- ارسال دستور SCSI GET STREAM STATUS یا STREAM CONTROL
.SH "خلاصه دستور (SYNOPSIS)"
.B sg_stream_ctl
[\fI\-\-brief\fR] [\fI\-\-close\fR] [\fI\-\-ctl=CTL\fR] [\fI\-\-get\fR]
[\fI\-\-help\fR] [\fI\-\-hex\fR] [\fI\-\-id=SID\fR] [\fI\-\-inhex=FN\fR]
[\fI\-\-json[=JO\fR]] [\fI\-\-js\-file=JFN\fR] [\fI\-\-maxlen=LEN\fR]
[\fI\-\-open\fR] [\fI\-\-raw\fR] [\fI\-\-readonly\fR] [\fI\-\-verbose\fR]
[\fI\-\-version\fR] \fIDEVICE\fR
.SH "توضیحات (DESCRIPTION)"
.\" Add any additional description here
یک دستور SCSI GET STREAM STATUS یا STREAM CONTROL را به \fIDEVICE\fR ارسال می‌کند.
این دستورات، همراه با WRITE STREAM (۱۶ و ۳۲) و چندین فیلد در صفحه VPD توسعه محدودیت‌های بلوک (Block Limits Extension) [0xb7]، از مفهوم جریان‌ها (streams) پشتیبانی می‌کنند.
همچنین صفحه حالت گروه‌بندی نکات راهنمای ورودی/خروجی (IO advice hints grouping mode page) [0xa,0x4] وجود دارد. در میان موارد دیگر، آن صفحه حالت مشخص می‌کند که آیا یک شناسه جریان می‌تواند وظیفه مضاعفی به عنوان شماره گروه موجود در بیشتر دستورات دسترسی به رسانه SCSI (مانند READ، WRITE و VERIFY) داشته باشد یا خیر.
.PP
دستورات جریان در پیش‌نویس ۸ استاندارد SBC\-4 (سپتامبر ۲۰۱۵) اضافه شدند. این دستورات در پیش‌نویس ۵ استاندارد SBC\-5 (اکتبر ۲۰۲۳) گسترش یافتند.
.PP
هر دو دستور GET STREAM STATUS و STREAM CONTROL انتظار دریافت داده از \fIDEVICE\fR را دارند (که به عنوان 'data\-in' یا داده ورودی شناخته می‌شود). در مورد STREAM CONTROL، تنها حالت 'open' (STR_CTL<\-\-0x1) در عمل به data\-in نیاز دارد زیرا در صورت باز شدن موفقیت‌آمیز، حاوی "Assigned stream id" (شناسه جریان تخصیص‌یافته) است. شناسه جریان تخصیص‌یافته باید توسط دستورات بعدی WRITE STREAM و در نهایت توسط بستن STREAM CONTROL (STR_CTL<\-\-0x2) استفاده شود. شناسه‌های معتبر جریان بین ۱ تا ۶۵۵۳۵ (شامل هر دو) هستند.
.SH "گزینه‌ها (OPTIONS)"
آرگومان‌های گزینه‌های طولانی برای گزینه‌های کوتاه نیز اجباری هستند.
.TP
\fB\-b\fR, \fB\-\-brief\fR
این گزینه خروجی دستور GET STREAM STATUS را تنها به یک عدد (در مبنای ده‌دهی) در هر خط ارسالی به خروجی استاندارد (stdout) کاهش می‌دهد. این اعداد، شناسه‌های جریان‌هایی هستند که در حال حاضر باز می‌باشند. در صورت بروز خطا، مقدار \-1 به خروجی استاندارد ارسال شده و پیام‌های مربوط به خطا به خطای استاندارد (stderr) ارسال می‌شوند. حالت پیش‌فرض این است که کلمات (و فیلدهای) بیشتری از پاسخ GET STREAM STATUS چاپ شود.
.TP
\fB\-c\fR, \fB\-\-close\fR
دستور STREAM CONTROL را انتخاب کرده و STR_CTL<\-\-0x2 (یعنی 'close') را تنظیم می‌کند. گزینه \fI\-\-id=SID\fR نیز باید مشخص شود زیرا مقدار پیش‌فرض آن 0 است که یک شناسه جریان معتبر نیست.
.TP
\fB\-C\fR, \fB\-\-ctl\fR=\fICTL\fR
\fICTL\fR مقداری است که در فیلد STR_CTL از دستور STREAM CONTROL (cdb) قرار می‌گیرد. این یک فیلد دو بیتی است، بنابراین ۴ حالت مختلف دارد: ۰ و ۳ رزرو شده‌اند؛ ۱ یک جریان جدید را باز می‌کند و ۲ شناسه جریان داده‌شده را می‌بندد. '\-\-ctl=1' معادل '\-\-open' و '\-\-ctl=2' معادل '\-\-close' است.
.TP
\fB\-g\fR, \fB\-\-get\fR
دستور GET STREAM STATUS را انتخاب می‌کند. اگر گزینه \fI\-\-id=SID\fR نیز داده شده باشد، پاسخ با فهرست کردن شناسه‌های جریان باز از \fISID\fR و شامل آن آغاز می‌شود. اگر گزینه \fI\-\-id=SID\fR داده نشود (یا \fISID\fR برابر با 0 باشد)، تا زمانی که طول تخصیص (allocation length) به اندازه کافی بزرگ باشد، تمام شناسه‌های جریان باز در پاسخ (data\-in) بازگردانده خواهند شد. طول تخصیص به طور پیش‌فرض ۲۴۸ بایت است که می‌توان آن را با گزینه \fI\-\-maxlen=LEN\fR بازنویسی کرد.
.IP
معمولاً نیازی به مشخص کردن این گزینه نیست، زیرا فراخوانی دستور GET STREAM STATUS در صورت نبود هر گزینه "انتخاب‌کننده" دیگر، اقدام پیش‌فرض این ابزار است.
.TP
\fB\-h\fR, \fB\-\-help\fR
چاپ پیام راهنمای استفاده و سپس خروج.
.TP
\fB\-H\fR, \fB\-\-hex\fR
.TP
\fB\-H\fR, \fB\-\-hex\fR
خروجی پاسخ این دستور را به صورت هگزادسیمال اسکی (ASCII hex) چاپ می‌کند. هر خط ۱۶ بایتی با یک آدرس یا نمایه که از ۰ شروع می‌شود پیشوند می‌گیرد و این آدرس نیز در مبنای شانزده (hex) است. اگر دو بار داده شود، نمایش اسکی هر بایت به انتهای خروجی خط اضافه می‌شود. اگر سه بار یا بیشتر داده شود، تنها مقدار هگزادسیمال اسکی هر بایت، ۱۶ بایت در هر خط چاپ می‌شود (یعنی بدون آدرس ابتدایی یا نمایش اسکی انتهایی). این شکل اخیر برای قرار دادن در یک فایل و استفاده با گزینه \fI\-\-inhex=FN\fR در فراخوانی‌های بعدی مناسب است.
.TP
\fB\-i\fR, \fB\-\-id\fR=\fISID\fR
\fISID\fR یک شناسه جریان است، مقداری بین ۱ تا ۶۵۵۳۵. این مقدار توسط STREAM CONTROL (close) برای مشخص کردن جریانی که باید بسته شود استفاده می‌شود. همچنین توسط دستور GET STREAM STATUS به عنوان شناسه جریان شروع (از و شامل آن) به کار می‌رود؛ بنابراین شناسه‌های جریانی که کمتر از \fISID\fR باشند در پاسخ ظاهر نخواهند شد.
.TP
\fB\-I\fR, \fB\-\-inhex\fR=\fIFN\fR
که در آن \fIFN\fR نام فایلی است که فرض می‌شود محتویات آن هگزادسیمال اسکی (ASCII hex) است. اگر \fIDEVICE\fR نیز داده شده باشد، \fIDEVICE\fR نادیده گرفته می‌شود، یک هشدار صادر شده و ابزار به کار خود با رمزگشایی فایل نام‌برده‌شده با \fIFN\fR ادامه می‌دهد. برای اطلاعات بیشتر، بخش "HEX, BINARY AND JSON FORMATS" را در صفحه راهنمای sg3_utils ببینید. اگر گزینه \fI\-\-raw\fR نیز داده شود، با محتویات \fIFN\fR به عنوان باینری رفتار می‌شود.
.br
\fIFN\fR ممکن است حاوی داده‌هایی باشد که بیانگر پاسخ به یک دستور SCSI GET STREAM STATUS یا STREAM CONTROL هستند. پیش‌فرض این ابزار انتظار برای مورد اول است. هنگامی که \fIFN\fR شامل داده‌های پاسخ یک دستور STREAM CONTROL باشد، باید یک گزینه اضافی (به جز این گزینه) مشخص شود: یکی از گزینه‌های \fI\-\-close\fR، \fI\-\-ctl=CTL\fR یا \fI\-\-open\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\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR
\fILEN\fR حداکثر طولی است که پاسخ می‌تواند داشته باشد. این مقدار به فیلد ALLOCATION LENGTH (طول تخصیص) در هر دو دستور تبدیل می‌شود. مقدار پیش‌فرض (در صورت نبود این گزینه) برای STREAM CONTROL برابر با ۸ بایت و برای GET STREAM STATUS برابر با ۲۴۸ بایت است.
.TP
\fB\-o\fR, \fB\-\-open\fR
دستور STREAM CONTROL را انتخاب کرده و STR_CTL<\-\-0x1 (یعنی 'open') را تنظیم می‌کند. اگر گزینه \fI\-\-id=SID\fR داده شود، نادیده گرفته خواهد شد. کاربر باید پاسخ را مشاهده کند زیرا در صورت موفقیت‌آمیز بودن باز کردن، "Assigned stream id" روی stdout چاپ می‌شود؛ در غیر این صورت '\-1' به stdout فرستاده شده و پیام‌های خطا به stderr فرستاده می‌شوند. اگر گزینه \fI\-\-brief\fR نیز داده شود، تنها چیزی که به stdout فرستاده می‌شود عدد شناسه جریان تخصیص‌یافته (۱ تا ۶۵۵۳۵ شامل هر دو) یا '\-1' در صورت بروز خطا خواهد بود.
.TP
\fB\-r\fR, \fB\-\-readonly\fR
این گزینه هنگام باز کردن \fIDEVICE\fR داده‌شده توسط سیستم‌عامل زیربنایی، پرچم 'read\-only' (فقط‌خواندنی) را تنظیم می‌کند. این ممکن است کار نکند زیرا سیستم‌عامل‌ها نمی‌توانند به راحتی تشخیص دهند که آیا یک دستور عبوری (pass\-through)، یک عملیات خواندن منطقی است یا نوشتن بر روی رسانه (یا فرا‌داده‌های آن)، بنابراین رویکردی محتاطانه در پیش گرفته و بدون توجه به آنچه توسط دستور عبوری انجام می‌شود، هنگام باز کردن \fIDEVICE\fR به مجوزهای از نوع خواندن\-نوشتن نیاز دارند.
.TP
\fB\-R\fR, \fB\-\-raw\fR
پاسخ را به صورت باینری (به stdout) چاپ می‌کند، مگر اینکه گزینه \fI\-\-inhex=FN\fR نیز داده شده باشد. در آن صورت، نام فایل ورودی (\fIFN\fR) به صورت باینری رمزگشایی می‌شود (و خروجی به صورت باینری _نخواهد_ بود).
.br
برای تعدیل این محدودیت نهایی، این گزینه می‌تواند چندین بار داده شود. اگر این گزینه یک یا سه بار مشخص شود، \fIFN\fR باینری فرض می‌شود. اگر این گزینه دو یا سه بار مشخص شود، خروجی (رمزگشایی‌نشده) به صورت باینری خواهد بود. این اقدامات تنها زمانی اعمال می‌شوند که گزینه \fI\-\-inhex=FN\fR داده شده باشد.
.TP
\fB\-v\fR, \fB\-\-verbose\fR
افزایش سطح پرگویی (یعنی خروجی اشکال‌زدایی).
.TP
\fB\-V\fR, \fB\-\-version\fR
چاپ رشته نسخه و سپس خروج.
.SH "نکات (NOTES)"
هیچ دستور خواندن خاصی برای جریان‌ها وجود ندارد. این بدان معناست که می‌توان از خواندن‌های "عادی" (۶، ۱۰، ۱۲، ۱۶ یا ۳۲) استفاده کرد. توجه داشته باشید هنگامی که یک جریان بسته می‌شود، تمامی منابع مرتبط با آن شناسه جریان، به جز داده‌های موجود در LBAهای نوشته‌شده، آزاد (حذف) می‌شوند. برای اطمینان از اینکه بازخوانی داده‌ها به دلیل بازیابی خطا (در صورت بروز خطاهای رسانه) بیش از حد به تاخیر نیفتد، کاربر می‌تواند فیلد RECOVERY TIME LIMIT (محدودیت زمان بازیابی یا RTL، با واحد میلی‌ثانیه برای مقادیر غیرصفر) را در صفحه حالت 'Read\-write error recovery' تنظیم کند. این کار را می‌توان با ابزار sdparm انجام داد.
.PP
دستورات SCSI WRITE STREAM (۱۶ و ۳۲) را می‌توان در ابزار sg_write_x در همین بسته یافت.
.SH "وضعیت خروج (EXIT STATUS)"
وضعیت خروج sg_stream_ctl در صورت موفقیت ۰ است. در غیر این صورت صفحه راهنمای sg3_utils(8) را ببینید.
.SH "نویسندگان (AUTHORS)"
نوشته‌شده توسط Douglas Gilbert.
.SH "گزارش باگ‌ها (REPORTING BUGS)"
گزارش باگ‌ها به <dgilbert at interlog dot com>.
.SH "حق نشر (COPYRIGHT)"
حق نشر \(co 2018\-2023 Douglas Gilbert
.br
این نرم‌افزار تحت مجوز BSD\-2\-Clause توزیع می‌شود. هیچ ضمانتی وجود ندارد؛ حتی برای قابلیت فروش یا تناسب با یک هدف خاص.
.SH "همچنین ببینید (SEE ALSO)"
.B sg_vpd,sg_write_x(sg3_utils); sdparm(sdparm)