.TH SG_PERSIST "8" "March 2023" "sg3_utils\-1.48" SG3_UTILS .SH "نام (NAME)" sg_persist \- استفاده از دستور SCSI PERSISTENT RESERVE برای دسترسی به ثبت‌ها و رزروها .SH "خلاصه دستور (SYNOPSIS)" .B sg_persist [\fIگزینه‌ها\fR] \fIDEVICE\fR .PP .B sg_persist [\fIگزینه‌ها\fR] \fI\-\-device=DEVICE\fR .PP .B sg_persist \fI\-\-help\fR | \fI\-\-version\fR .SH "توضیحات (DESCRIPTION)" .\" Add any additional description here این ابزار امکان پرس‌وجو و تغییر رزروها و ثبت‌های پایدار (Persistent Reservations and Registrations) را فراهم می‌کند. رزروها و ثبت‌های پایدار از طریق زیردستورها (که در SPC\-4 «کنش‌های سرویس» یا "service actions" نامیده می‌شوند) مربوط به دستور SCSI PERSISTENT RESERVE IN (PRIN) پرس‌وجو می‌شوند. رزروها و ثبت‌های پایدار توسط زیردستورهای دستور SCSI PERSISTENT RESERVE OUT (PROUT) تغییر می‌یابند. .PP برای دستیابی به یک رزرو پایدار، فرآیندی دو مرحله‌ای وجود دارد. نخست، یک برنامه کاربردی (که در اصطلاح استاندارد به آن یک I_T nexus گفته می‌شود) باید یک کلید رزرو (reservation key) را ثبت کند. در صورتی که این کلید پذیرفته شود (و باید پذیرفته شود مگر اینکه I_T nexus دیگری آن کلید را ثبت کرده باشد)، آنگاه برنامه می‌تواند برای رزرو دستگاه اقدام کند. عملیات رزرو باید کلید رزرو و یک «نوع» را مشخص کند (گزینه .I \-\-prout\-type=TYPE را ببینید). .PP پرس‌وجوی وضعیت رزروها و ثبت‌های پایدار نسبتاً بی‌خطر است. در صورت عدم تعیین هیچ گزینه‌ای، این ابزار به‌طور پیش‌فرض زیردستور READ KEYS از دستور PRIN را اجرا می‌کند. سایر زیردستورهای PRIN عبارتند از: READ RESERVATION، REPORT CAPABILITIES و READ FULL STATUS. .PP کاربران پیش از اقدام به تغییر رزروها و ثبت‌های پایدار باید کاملاً نسبت به کاری که انجام می‌دهند آگاه باشند. بخش‌های مربوطه در سند دستورات اولیه اسکازی (یعنی SPC\-5 ANSI INCITS 502\-2020) بخش‌های ۸.۱۴ (با عنوان «Reservations»)، ۹.۱۶ (برای دستور PRIN) و ۹.۱۷ (برای دستور PROUT) هستند. برای جلوگیری از استفاده تصادفی، در هنگام استفاده از یک زیردستور PROUT (مانند .IR \-\-register ) باید حتماً گزینه .I \-\-out مشخص شود. .PP دستورات قدیمی‌تر SCSI RESERVE و RELEASE (هر دو نگارش ۶ و ۱۰ بایتی) توسط این ابزار پشتیبانی نمی‌شوند. در SPC\-3 دستورات RESERVE و RELEASE منسوخ شده و رزروهای پایدار جایگزین آن‌ها شدند. RESERVE و RELEASE در SPC\-4 کاملاً حذف شده‌اند و پیوست B نحوه تبدیل آن‌ها به دستورات رزرو پایدار را نشان می‌دهد. برای پشتیبانی از دستورات SCSI RESERVE و RELEASE به ابزاری به نام «scsires» مراجعه کنید. .PP برای تمامی حالت‌های این ابزار به جز .I \-\-help و .IR \-\-version ، مشخص کردن .I DEVICE الزامی است. .I DEVICE را می‌توان هم به‌عنوان یک آرگومان (معمولاً اما نه لزوماً پس از گزینه‌ها) یا از طریق گزینه .I \-\-device=DEVICE مشخص کرد. .PP استاندارد SPC\-4 از اصطلاح «زیردستور» (sub\-command) استفاده نمی‌کند. این استاندارد اصطلاح «کنش سرویس» (service action) را برای این مورد و همچنین برای بخشی از نام یک فیلد در بلوک پارامتر مرتبط با دستور PROUT (یعنی "service action reservation key") به کار می‌برد. برای کاهش ابهام و سردرگمی احتمالی، در این ابزار اصطلاح «زیردستور» معرفی شده است. .SH "گزینه‌ها (OPTIONS)" آرگومان‌های گزینه‌های طولانی برای گزینه‌های کوتاه نیز اجباری هستند. گزینه‌های زیر بر اساس نام گزینه طولانی خود به ترتیب الفبایی مرتب شده‌اند. .TP \fB\-l\fR, \fB\-\-alloc\-length\fR=\fILEN\fR طول تخصیص (allocation length) دستور PRIN را مشخص می‌کند. .I LEN یک مقدار هگزادسیمال است. به‌طور پیش‌فرض این مقدار برابر با اندازه بافر داده ورودی (۸۱۹۲) تنظیم شده است. این پارامتر برای اعتبارسنجی اینکه پاسخ به دستورات PRIN با طول‌های تخصیص گوناگون مطابق با بخش ۴.۳.۵.۶ از بازنگری ۱۸ استاندارد SPC\-4 است، کاربرد دارد. مقادیر معتبر برای .I LEN بین ۰ تا ۸۱۹۲ هستند. .TP \fB\-C\fR, \fB\-\-clear\fR زیردستور Clear یکی از زیردستورهای دستور PROUT است. این گزینه رزرو پایدار (در صورت وجود) را آزاد کرده و تمامی ثبت‌ها را از روی دستگاه پاک می‌کند. ارائه یک کلید رزرو که برای این I_T_L nexus ثبت شده باشد (مشخص‌شده با .IR \-\-param\-rk=RK ) الزامی است. .br این گزینه دستور PERSISTENT RESERVE OUT اسکازی را در حالی که فیلد کنش سرویس (service action) آن روی CLEAR [0x3] تنظیم شده، صادر می‌کند. .TP \fB\-d\fR, \fB\-\-device\fR=\fIDEVICE\fR مشخص‌کننده .I DEVICE برای ارسال دستورات SCSI به آن. .I DEVICE را می‌توان از طریق این گزینه یا به‌صورت یک آرگومان مستقل مشخص کرد. برای نمونه، این دو دستور با یکدیگر معادل هستند: 'sg_persist \-\-device=/dev/sg2' و 'sg_persist /dev/sg2'. .TP \fB\-h\fR, \fB\-\-help\fR نمایش پیام راهنمای نحوه استفاده و گزینه‌های اصلی. استفاده دو بار از آن (مانند '\-hh') گزینه‌های دیگر و راهنمای بیشتری را نشان می‌دهد. .TP \fB\-H\fR, \fB\-\-hex\fR پاسخ به یک زیردستور معتبر PRIN را در قالب هگزادسیمال نمایش می‌دهد. به‌طور پیش‌فرض (یعنی بدون این گزینه)، اگر زیردستور PRIN شناخته‌شده باشد، پاسخ مطابق با SPC\-4 رمزگشایی و تفسیر خواهد شد. استفاده بیش از یک بار از این گزینه، خروجی هگزادسیمال بیشتر و متن کمتری تولید می‌کند. .TP \fB\-i\fR, \fB\-\-in\fR مشخص می‌کند که دستور SCSI PERSISTENT RESERVE IN مورد نیاز است. این حالت پیش‌فرض است. .TP \fB\-m\fR, \fB\-\-maxlen\fR=\fILEN\fR مقدار .I LEN به عنوان فیلد ALLOCATION LENGTH در دستور PRIN استفاده می‌شود. .I LEN به‌طور پیش‌فرض یک مقدار ده‌دهی (decimal) است. برای ارائه مقدار هگزادسیمال از پیشوند '0x' یا '0X'، یا پسوند 'h' (یا 'H') استفاده کنید. همچنین می‌تواند ضرایب ضرب‌کننده را بپذیرد؛ گزینه .I \-\-maxlen=LEN در صفحه راهنمای sg3_utils را ببینید. .br این گزینه به‌جز نحوه نمایش .IR LEN ، مشابه با گزینه .I \-\-alloc\-length=LEN است. این گزینه به‌طور پیش‌فرض ده‌دهی است، در حالی که .I \-\-alloc\-length=LEN فقط مقادیر هگزادسیمال را می‌پذیرد. .TP \fB\-n\fR, \fB\-\-no\-inquiry\fR عملکرد پیش‌فرض این است که پیش از اجرای یک دستور PRIN یا PROUT، یک دستور استاندارد SCSI INQUIRY انجام شده و رشته‌های سازنده، محصول و بازنگری به همراه نوع دستگاه جانبی چاپ شود. با این گزینه، اجرای دستور INQUIRY نادیده گرفته می‌شود. .TP \fB\-o\fR, \fB\-\-out\fR مشخص می‌کند که اجرای دستور SCSI PERSISTENT RESERVE OUT مورد نیاز است. .TP \fB\-Y\fR, \fB\-\-param\-alltgpt\fR فلگ «همه درگاه‌های مقصد» (ALL_TG_PT) را در بلوک پارامتر دستور PROUT تنظیم می‌کند. این گزینه فقط برای زیردستورهای 'register' و 'register and ignore existing key' کاربرد دارد. .TP \fB\-Z\fR, \fB\-\-param\-aptpl\fR فلگ «فعال‌سازی ماندگاری پس از قطع برق» (APTPL) را در بلوک پارامتر دستور PROUT تنظیم می‌کند. برای زیردستورهای 'register' ،'register and ignore existing key' و 'register and move' کاربرد دارد. .TP \fB\-K\fR, \fB\-\-param\-rk\fR=\fIRK\fR کلید رزرو موجود در بلوک پارامتر دستور PROUT را مشخص می‌کند. فرض می‌شود که .I RK یک مقدار هگزادسیمال (تا حداکثر ۸ بایت) است. مقدار پیش‌فرض ۰ است. این گزینه برای بیشتر زیردستورهای PROUT لازم است. .TP \fB\-S\fR, \fB\-\-param\-sark\fR=\fISARK\fR کلید رزرو کنش سرویس (service action reservation key) موجود در بلوک پارامتر دستور PROUT را مشخص می‌کند. فرض می‌شود که .I SARK یک مقدار هگزادسیمال (تا حداکثر ۸ بایت) است. مقدار پیش‌فرض ۰ است. این گزینه برای برخی از زیردستورهای PROUT لازم است. .TP \fB\-P\fR, \fB\-\-preempt\fR زیردستور Preempt یکی از زیردستورهای دستور PROUT است. این گزینه رزرو پایدار موجود (مشخص‌شده با .IR \-\-param\-sark=SARK ) را با کلید ثبتی که برای این I_T_L nexus ثبت شده است (مشخص‌شده با .IR \-\-param\-rk=RK ) غصب (preempt) می‌کند. اگر در نتیجه این غصب، رزرو جدیدی برقرار شود، مقدار ارائه‌شده با .I \-\-prout\-type=TYPE به‌عنوان نوع این رزرو جدید استفاده می‌شود. .br این گزینه دستور PERSISTENT RESERVE OUT اسکازی را در حالی که فیلد کنش سرویس آن روی PREEMPT [0x4] تنظیم شده، صادر می‌کند. .TP \fB\-A\fR, \fB\-\-preempt\-abort\fR زیردستور Preempt and Abort یکی از زیردستورهای دستور PROUT است. رزرو پایدار موجود (مشخص‌شده با .IR \-\-param\-sark=SARK ) را با کلید ثبتی که برای این I_T_L nexus ثبت شده است (مشخص‌شده با .IR \-\-param\-rk=RK ) غصب می‌کند. اگر در نتیجه این غصب، رزرو جدیدی برقرار شود، مقدار ارائه‌شده با .I \-\-prout\-type=TYPE به‌عنوان نوع این رزرو جدید استفاده می‌شود. همچنین وظایف ACA و سایر وظایف معلق لغو (abort) می‌شوند. .br این گزینه دستور PERSISTENT RESERVE OUT اسکازی را در حالی که فیلد کنش سرویس آن روی PREEMPT AND ABORT [0x5] تنظیم شده، صادر می‌کند. .TP \fB\-T\fR, \fB\-\-prout\-type\fR=\fITYPE\fR آرگومان 'type' دستور PROUT را مشخص می‌کند. برای زیردستورهای 'register\-move' ،'reserve' ،'release' و 'preempt (and abort)' الزامی است. مقادیر معتبر برای .IR TYPE : مقدار 1\-> دسترسی انحصاری نوشتن (write exclusive)، مقدار 3\-> دسترسی انحصاری (exclusive access)، مقدار 5\-> انحصاری نوشتن \- فقط ثبت‌نام‌شدگان (write exclusive \- registrants only)، مقدار 6\-> دسترسی انحصاری \- فقط ثبت‌نام‌شدگان (exclusive access \- registrants only)، مقدار 7\-> انحصاری نوشتن \- همه ثبت‌نام‌شدگان (write exclusive \- all registrants)، مقدار 8\-> دسترسی انحصاری \- همه ثبت‌نام‌شدگان (exclusive access \- all registrants). مقدار پیش‌فرض ۰ است (که یک نوع نامعتبر محسوب می‌شود). هر یک از انواع رزرو پایدار ("persistent reservation type") با جزئیات بیشتر در زیربخشی به همین نام در بخش read reservation از دستور PRIN (بخش ۶.۱۵.۳.۳ بازنگری ۳۷ استاندارد SPC\-4) توضیح داده شده است. .TP \fB\-s\fR, \fB\-\-read\-full\-status\fR زیردستور Read Full Status یکی از زیردستورهای دستور PRIN است. برای هر ثبت انجام‌شده در دستگاه SCSI مشخص‌شده، کلید رزرو و اطلاعات مرتبط با آن را فهرست می‌کند. شناسه‌های انتقال (TransportIDs) در صورت ارائه در پاسخ، رمزگشایی می‌شوند. .br این گزینه دستور PERSISTENT RESERVE IN اسکازی را با فیلد کنش سرویس تنظیم‌شده روی READ FULL STATUS [0x3] صادر می‌کند. .TP \fB\-k\fR, \fB\-\-read\-keys\fR زیردستور Read Keys یکی از زیردستورهای دستور PRIN است. تمام کلیدهای رزرو ثبت‌شده (یعنی ثبت‌ها) در دستگاه SCSI داده‌شده را فهرست می‌کند. این زیردستور پیش‌فرض برای دستور SCSI PRIN است. .br این گزینه دستور PERSISTENT RESERVE IN اسکازی را با فیلد کنش سرویس تنظیم‌شده روی READ KEYS [0x0] صادر می‌کند. .TP \fB\-y\fR, \fB\-\-readonly\fR دستگاه .I DEVICE را به‌صورت فقط‌خواندنی باز می‌کند. در دستورات PRIN در صورتی که باز کردن پیش‌فرض به‌صورت خواندن/نوشتن اثرات ناخواسته داشته باشد، می‌تواند مفید باشد. اگر دو بار داده شود، به عنوان اجبار به باز کردن به‌صورت خواندن/نوشتن تفسیر شده و بنابراین متغیر محیطی SG_PERSIST_IN_RDONLY (در صورت وجود) را نادیده می‌گیرد. برای اطلاعات بیشتر بخش متغیرهای محیطی را ببینید. .TP \fB\-r\fR, \fB\-\-read\-reservation\fR زیردستور Read Reservation یکی از زیردستورهای دستور PRIN است. اطلاعات مربوط به دارنده فعلی رزرو روی .I DEVICE را فهرست می‌کند. اگر رزرو فعلی وجود نداشته باشد، اعلام خواهد شد. اطلاعات مربوط به دارنده فعلی رزرو شامل کلید رزرو، محدوده (scope) و نوع (type) آن است. .br این گزینه دستور PERSISTENT RESERVE IN اسکازی را با فیلد کنش سرویس تنظیم‌شده روی READ RESERVATION [0x1] صادر می‌کند. .TP \fB\-s\fR, \fB\-\-read\-status\fR مشابه با .IR \-\-read\-full\-status . .TP \fB\-G\fR, \fB\-\-register\fR زیردستور Register یکی از زیردستورهای دستور PROUT است. بسته به پارامترهای مرتبط دارای ۳ عملکرد مختلف است: الف) افزودن یک ثبت جدید با '\-\-param\-rk=0' و '\-\-param\-sark='؛ ب) تغییر یک ثبت موجود با '\-\-param\-rk=' و '\-\-param\-sark='؛ یا ج) حذف یک ثبت موجود با '\-\-param\-rk=' و '\-\-param\-sark=0'. .br این گزینه دستور PERSISTENT RESERVE OUT اسکازی را با فیلد کنش سرویس تنظیم‌شده روی REGISTER [0x0] صادر می‌کند. .TP \fB\-I\fR, \fB\-\-register\-ignore\fR زیردستور Register and Ignore Existing Key یکی از زیردستورهای دستور PROUT است. مشابه با .I \-\-register است با این تفاوت که هنگام تغییر یک کلید رزرو، کلید قدیمی مشخص نمی‌شود. گزینه '\-\-param\-sark=' نیز باید ارائه گردد. .br این گزینه دستور PERSISTENT RESERVE OUT اسکازی را با فیلد کنش سرویس تنظیم‌شده روی REGISTER AND IGNORE EXISTING KEY [0x6] صادر می‌کند. .TP \fB\-M\fR, \fB\-\-register\-move\fR زیردستور ثبت (یک آغازگر دیگر) و انتقال (رزرو نگه‌داشته‌شده توسط آغازگر فعلی به آن آغازگر دیگر) یکی از زیردستورهای دستور PROUT است. این عملیات به شناسه انتقال (transportID) آغازگر دیگر نیاز دارد. [استاندارد از اصطلاح I_T nexus استفاده می‌کند اما نکته قابل تأکید این است که دو آغازگر وجود دارند (آغازگری که این دستور را می‌فرستد و دیگری)، اما تنها یک واحد منطقی (logical unit) وجود دارد.] گزینه‌های .I \-\-prout\-type=TYPE و .I \-\-param\-rk=RK باید با مشخصات رزرو موجود مطابقت داشته باشند در حالی که گزینه .I \-\-param\-sark=SARK کلید رزرو ثبت جدید (یعنی مقصد) را تعیین می‌کند. .br این گزینه دستور PERSISTENT RESERVE OUT اسکازی را با فیلد کنش سرویس تنظیم‌شده روی REGISTER AND MOVE [0x7] صادر می‌کند. .TP \fB\-Q\fR, \fB\-\-relative\-target\-port\fR=\fIRTPI\fR شناسه درگاه نسبی مقصد (relative target port identifier) که قرار است رزرو توسط زیردستور 'register and move' دستور PROUT به آن منتقل شود. فرض می‌شود که .I RTPI یک مقدار هگزادسیمال در محدوده ۰ تا ffff (شامل هر دو) باشد. پیش‌فرض ۰ است. .TP \fB\-L\fR, \fB\-\-release\fR زیردستور Release یکی از زیردستورهای دستور PROUT است. این گزینه رزرو پایدار فعلی را آزاد می‌کند. گزینه‌های .I \-\-prout\-type=TYPE و .IR \-\-param\-rk=RK ، منطبق با رزرو موجود، نیز باید مشخص شوند. .br این گزینه دستور PERSISTENT RESERVE OUT اسکازی را با فیلد کنش سرویس تنظیم‌شده روی RELEASE [0x2] صادر می‌کند. .TP \fB\-z\fR, \fB\-\-replace\-lost\fR زیردستور Replace Lost Reservation یکی از زیردستورهای دستور PROUT است. این زیردستور «یک فرآیند بازیابی را برای رزرو پایدار گم‌شده که توسط کلاینت‌های برنامه مدیریت می‌شود آغاز می‌کند». همچنین از لغو دستورات توسط کارگزار دستگاه به دلیل از دست رفتن رزرو پایدار جلوگیری به عمل می‌آورد. گزینه‌ها باید به‌صورت '\-\-param\-rk=0' (یا ارائه نشده)، '\-\-param\-sark=' و .I \-\-prout\-type=TYPE باشند. .br این گزینه دستور PERSISTENT RESERVE OUT اسکازی را با فیلد کنش سرویس تنظیم‌شده روی REPLACE LOST RESERVATION [0x8] صادر می‌کند. .TP \fB\-c\fR, \fB\-\-report\-capabilities\fR زیردستور Report Capabilities یکی از زیردستورهای دستور PRIN است. اطلاعات مربوط به ویژگی‌ها و جنبه‌هایی از رزروهای پایدار که توسط .I DEVICE پشتیبانی می‌شود را فهرست می‌کند. .br این گزینه دستور PERSISTENT RESERVE IN اسکازی را با فیلد کنش سرویس تنظیم‌شده روی REPORT CAPABILITIES [0x2] صادر می‌کند. .TP \fB\-R\fR, \fB\-\-reserve\fR زیردستور Reserve یکی از زیردستورهای دستور PROUT است. این زیردستور یک رزرو پایدار جدید ایجاد می‌کند (در صورت مجاز بودن). گزینه‌های .I \-\-prout\-type=TYPE و .I \-\-param\-rk=RK نیز باید مشخص شوند. .br این گزینه دستور PERSISTENT RESERVE OUT اسکازی را با فیلد کنش سرویس تنظیم‌شده روی RESERVE [0x1] صادر می‌کند. .TP \fB\-X\fR, \fB\-\-transport\-id\fR=\fITIDS\fR آرگومان .I TIDS می‌تواند یکی از چندین قالب را داشته باشد. می‌تواند فهرستی جداشده با کاما (یا یک فاصله) از بایت‌های هگزادسیمال اسکی باشد که نشان‌دهنده یک شناسه انتقال (TransportID) منفرد مطابق با تعریف SPC\-5 است. آن‌ها معمولاً به‌جز در iSCSI، طولی معادل ۲۴ بایت دارند. آرگومان .I TIDS می‌تواند قالبی مخصوص به پروتکل انتقال داشته باشد (برای نمونه، "sas,5000c50005b32001" بسیار واضح‌تر از معادل بایت‌های هگزادسیمال آن یعنی "6,0,0,0,5,0,c5,0,5,b3,20,1" است). آرگومان .I TIDS می‌تواند "\-" باشد که در این صورت یک یا چند TransportID از ورودی استاندارد (stdin) خوانده می‌شوند. آرگومان .I TIDS می‌تواند به شکل "file=" باشد که در این صورت یک یا چند TransportID از فایلی به نام خوانده می‌شوند. برای اطلاعات بیشتر بخش «شناسه‌های انتقال (TRANSPORT IDs)» در زیر را ببینید. .TP \fB\-U\fR, \fB\-\-unreg\fR اختیاری هنگام فراخوانی زیردستور register and move از دستور PROUT. در صورت ارائه، پس از ثبت آغازگر دیگر و انتقال رزرو به آن، آغازگر فعلی (I_T nexus) را از حالت ثبت خارج (unregister) می‌کند. در صورت عدم ارائه، آغازگری (I_T nexus) که دستور PROUT را ارسال کرده است در حالت ثبت‌شده باقی می‌ماند. .br این گزینه دستور PERSISTENT RESERVE OUT اسکازی را با فیلد کنش سرویس تنظیم‌شده روی REGISTER AND MOVE [0x7] صادر می‌کند. بیت UNREG در لیست پارامترهای مرتبط تنظیم می‌شود. .TP \fB\-v\fR, \fB\-\-verbose\fR چاپ cdb دستورات صادرشده پیش از اجرا. در صورت دو بار استفاده، بلوک پارامتر مرتبط با دستور PROUT را نیز پیش از اجرای آن چاپ می‌کند. در صورت سه بار استفاده، شناسه(های) انتقال ارائه‌شده را نیز رمزگشایی و نمایش می‌دهد. برای مشاهده پاسخ دستور PRIN به صورت سطح پایین، از گزینه .I \-\-hex استفاده کنید. .TP \fB\-V\fR, \fB\-\-version\fR رشته نگارش را چاپ می‌کند. تمام پارامترهای دیگر نادیده گرفته می‌شوند. .TP \fB\-?\fR پیام نحوه استفاده را چاپ می‌کند. تمام پارامترهای دیگر نادیده گرفته می‌شوند. .SH "شناسه‌های انتقال (TRANSPORT IDs)" از شناسه‌های انتقال (TransportIDs) در رزروهای پایدار برای شناسایی آغازگرها (initiators) استفاده می‌شود. قالب یک شناسه انتقال بسته به نوع انتقال مورد استفاده متفاوت است. ساختار و قالب آن‌ها در SPC\-4 تشریح شده است (در پیش‌نویس بازنگری ۳۷ بخش ۷.۶.۴ را ببینید). .PP ارائه یک TransportID برای زیردستور 'register and move' دستور PROUT الزامی است و زیردستور 'register' دستور PROUT می‌تواند صفر، یک یا چند TransportID داشته باشد. .PP هنگامی که گزینه .I \-\-transport\-id=TIDS داده شود، آرگومان .I TIDS می‌تواند فهرستی جداشده با کاما (یا یک فاصله) از بایت‌های هگزادسیمال اسکی باشد که نشان‌دهنده یک TransportID منفرد طبق تعریف SPC\-4 است. در غیر این صورت، آرگومان .I TIDS می‌تواند رشته‌ای خاص پروتکل انتقال باشد که با یکی از پیشوندهای "fcp," ،"spi," ،"sbp," ،"srp," ،"iqn" ،"sas," یا "sop," آغاز می‌شود. قالب "iqn" یک نام واجد شرایط iSCSI (نام iSCSI qualified) است. به جز "iqn"، سایر رشته‌های پیشوند مختص به پروتکل انتقال را می‌توان با حروف بزرگ نیز نوشت (مانند "FCP,"). .PP قالب "fcp," باید با ۱۶ رقم هگزادسیمال اسکی که نشان‌دهنده N_PORT_NAME آغازگر است دنبال شود (مانند "fcp,10000000C9F3A571"). قالب "spi," باید با "," (هر دو به‌صورت اعداد ده‌دهی) دنبال شود. قالب "sbp," باید با ۱۶ رقم هگزادسیمال اسکی که بیانگر نام EUI\-64 آغازگر است دنبال شود. قالب "srp," باید با ۳۲ رقم هگزادسیمال اسکی که نشان‌دهنده شناسه درگاه آغازگر است دنبال شود. قالب "sas," باید با ۱۶ رقم هگزادسیمال اسکی که بیانگر آدرس SAS درگاه آغازگر است دنبال شود (مانند "sas,5000c50005b32001"). قالب "sop," یک عدد هگزادسیمال می‌گیرد که نشان‌دهنده شناسه مسیریابی (routing id) است. .PP برای نام واجد شرایط iSCSI دو قالب وجود دارد. قالب کوتاه‌تر شامل نام iSCSI درگاه آغازگر است (مانند "iqn.5886.com.acme.diskarrays\-sn\-a8675309"). قالب طولانی‌تر شناسه نشست آغازگر (ISID به هگزادسیمال) را که با ",i,0x" جدا شده است اضافه می‌کند؛ برای نمونه: "iqn.5886.com.acme.diskarrays\-sn\-a8675309,i,0x1234567890ab". در خط فرمان برای جلوگیری از تفسیر اشتباه علائم نگارشی موجود در نام iSCSI توسط پوسته (شل)، توصیه می‌شود آرگومان گزینه شامل نام iSCSI درون گیومه دوتایی (کوتیشن) قرار گیرد. نام‌های iSCSI به صورت UTF\-8 کدگذاری می‌شوند، بنابراین اگر کاراکترهای غیر اسکی (۷ بیتی) در نام iSCSI در خط فرمان وجود داشته باشد و با UTF\-8 کدگذاری نشده باشند، مشکلاتی ایجاد خواهد شد. برای نمونه می‌توان با قرار دادن "LANG=en_US.utf\-8" قبل از اجرای sg_persist در خط فرمان، متغیر محلی (locale) را موقتاً تغییر داد. .PP همچنین آرگومان .I TIDS می‌تواند یک فایل (یا لوله/پایپ) را مشخص کند که یک یا چند TransportID از آن خوانده شوند. اگر آرگومان .I TIDS برابر با "\-" باشد، ورودی استاندارد (stdin) خوانده می‌شود. اگر آرگومان .I TIDS به صورت "file=" باشد، فایلی به نام خوانده خواهد شد. یک TransportID معتبر SPC\-4 از روی رشته اختصاصی پروتکل انتقال که در پاراگراف‌های پیشین شرح داده شد ساخته می‌شود. تجزیه داده‌های خوانده‌شده نسبتاً ساده است: خطوط خالی نادیده گرفته می‌شوند؛ همه چیز از کاراکتر "#" در یک خط به بعد نادیده گرفته می‌شود؛ فاصله‌ها و تب‌های ابتدای خط نادیده گرفته می‌شوند؛ در هر خط می‌تواند یک TransportID قرار گیرد؛ شناسه انتقال می‌تواند فهرستی جداشده با کاما، فاصله یا تب از بایت‌های هگزادسیمال اسکی باشد که نشان‌دهنده یک TransportID طبق تعریف SPC\-4 است. در صورت نیاز، افزودن بایت‌های صفر (padding) تا رسیدن به حداقل طول ۲۴ بایت انجام می‌شود. شناسه انتقال همچنین می‌تواند رشته اختصاصی پروتکل انتقال باشد که بالاتر بحث شد. .PP در SPC\-3 تنظیم بیت SPEC_I_PT روی یک و استفاده از شناسه‌های انتقال برای زیردستور register and ignore existing key از دستور PROUT مجاز بود. در SPC\-4 این کار غیرمجاز شده و وضعیت CHECK CONDITION به همراه کد حس ILLEGAL REQUEST و کد حس اضافی INVALID FIELD IN PARAMETER LIST برمی‌گرداند. .SH "نکات (NOTES)" در سری‌های ۲.۴ کرنل لینوکس، .I DEVICE باید یک دستگاه SCSI عمومی (sg) باشد. در سری‌های ۲.۶ هر نام دستگاه SCSI (مانند /dev/sdc، /dev/st1m یا /dev/sg3) را می‌توان مشخص کرد. برای نمونه، دستور "sg_persist \-\-read\-keys /dev/sdb" در کرنل‌های سری ۲.۶ به خوبی کار خواهد کرد. .PP تنها محدوده (scope) برای دستورات PROUT که در پیش‌نویس فعلی SPC\-4 پشتیبانی می‌شود "LU_SCOPE" است. از این رو، ارائه‌ی گزینه‌ای برای تنظیم scope به مقداری دیگر بی‌فایده به نظر می‌رسد. .PP بیشتر خطاها در زیردستورهای PROUT (مانند نبودن یا عدم تطابق .IR \-\-prout\-type=TYPE ) به وضعیت خطای RESERVATION CONFLICT منجر می‌شوند. این موضوع ممکن است زمانی که می‌دانید تنها یک آغازگر (فعال) وجود دارد کمی گیج‌کننده باشد: در واقع این «تداخل»، تداخل با استاندارد SPC است و نه با آغازگری دیگر. .PP برخی دیسک‌های جدیدتر هنگام متوقف بودن رسانه (مدیا)، برخی از زیردستورهای PRIN و PROUT را می‌پذیرند. یک استثنا تنظیم پرچم APTPL (با گزینه .IR \-\-param\-aptpl ) هنگام عملیات ثبت کلید بود؛ که اگر دیسک متوقف بود خطا می‌داد. پیام خطا نشان می‌داد که دیسک باید بچرخد (spin up شود) و هنگامی که این کار انجام شد، ثبت کلید با موفقیت پایان یافت. .SH "مثال‌ها (EXAMPLES)" این مثال‌ها از نام‌های دستگاه لینوکس استفاده می‌کنند. برای نام‌های مناسب دستگاه در سایر سیستم‌عامل‌های پشتیبانی‌شده به صفحه راهنمای sg3_utils(8) مراجعه کنید. .PP با توجه به مقادیر پیش‌فرض گزینه‌های مختلف، ساده‌ترین مثال زیردستور 'read keys' از دستور PRIN را اجرا می‌کند: .PP sg_persist /dev/sdb .PP این دستور معادل دستور (طولانی) زیر است: .PP sg_persist \-\-in \-\-read\-keys \-\-device=/dev/sdb .PP برای خواندن رزرو فعلی، می‌توان از شکل '\-\-read\-reservation' یا شکل کوتاه‌تر '\-r' استفاده کرد: .PP sg_persist \-r /dev/sdb .PP برای .B ثبت (register) کلید رزرو جدید 0x123abc می‌توان دستور زیر را به کار برد: .PP sg_persist \-\-out \-\-register \-\-param\-sark=123abc /dev/sdb .PP به فرض موفقیت ثبت بالا، برای .B رزرو کردن (reserve) دستگاه .I DEVICE (با نوع 'write exclusive') می‌توان دستور زیر را استفاده کرد: .PP sg_persist \-\-out \-\-reserve \-\-param\-rk=123abc \-\-prout\-type=1 /dev/sdb .PP برای .B آزادسازی (release) رزرو می‌توان دستور زیر را وارد کرد (توجه داشته باشید که آرگومان‌های \-\-param\-rk و \-\-prout\-type باید با مشخصات رزرو مطابقت داشته باشند): .PP sg_persist \-\-out \-\-release \-\-param\-rk=123abc \-\-prout\-type=1 /dev/sdb .PP در نهایت برای .B لغو ثبت (unregister) یک کلید رزرو (بدون تأثیر بر سایر ثبت‌ها، که کاری است که '\-\-clear' انجام می‌دهد) دستور کمی غافلگیرکننده است: .PP sg_persist \-\-out \-\-register \-\-param\-rk=123abc /dev/sdb .PP اکنون تفاوت بین مثال‌های ثبت (register) و لغو ثبت (unregister) در بالا را به دقت بررسی کنید. .PP یک فایل نمونه با فرمت‌بندی مناسب برای ارسال شناسه‌های انتقال از طریق گزینه '\-\-transport\-id=file=transport_ids.txt' را می‌توان در زیرپوشه examples از بسته sg3_utils یافت. همچنین یک اسکریپت آزمایشی ساده به نام sg_persist_tst.sh در همان دایرکتوری قرار دارد. .PP دنباله دستورات بالا با موفقیت روی یک دیسک Seagate Savvio 10K.3 و یک درایو 1200 SSD که هر دو دارای رابط SAS هستند، آزمایش شده است. .SH "وضعیت خروج (EXIT STATUS)" وضعیت خروج sg_persist در صورت موفقیت برابر با ۰ است. در غیر این صورت صفحه راهنمای sg3_utils(8) را ببینید. .SH "متغیرهای محیطی (ENVIRONMENT VARIABLES)" در حال حاضر یک متغیر محیطی شناخته‌شده وجود دارد: SG_PERSIST_IN_RDONLY. در صورت وجود و تنها زمانی که یک دستور PRIN انتخاب شده باشد، دستگاه داده‌شده .I DEVICE به‌صورت فقط‌خواندنی باز می‌شود (مثلاً در یونیکس با پرچم O_RDONLY). گزینه .I \-\-readonly را ببینید. .SH "نویسنده (AUTHOR)" نوشته‌شده توسط Douglas Gilbert .SH "گزارش باگ‌ها (REPORTING BUGS)" گزارش باگ‌ها را به بفرستید. .SH "حق نشر (COPYRIGHT)" کپی‌رایت \(co 2004\-2023 Douglas Gilbert .br این نرم‌افزار تحت مجوز GPL نسخه ۲ توزیع می‌شود. هیچ ضمانتی وجود ندارد؛ حتی برای قابلیت فروش یا تناسب برای یک هدف خاص. .SH "همچنین ببینید (SEE ALSO)" .B sg3_utils(sg3_utils), scsires(internet)