SG_WRITE_X(8) SG3_UTILS SG_WRITE_X(8)

sg_write_x - دستورات SCSI WRITE عادی/ATOMIC/SAME/SCATTERED/STREAM و ORWRITE

sg_write_x [--16] [--32] [--app-tag=AT] [--atomic=AB] [--bmop=OP,PGP] [--bs=BS] [--combined=DOF] [--dld=DLD] [--dpo] [--dry-run] [--fua] [--generation=EOG,NOG] [--grpnum=GN] [--help] --in=IF [--lba=LBA[,LBA...]] [--normal] [--num=NUM[,NUM...]] [--offset=OFF[,DLEN]] [--or] [--quiet] [--ref-tag=RT] [--same=NDOB] [--scat-file=SF] [--scat-raw] [--scattered=RD] [--stream=ID] [--strict] [--tag-mask=TM] [--timeout=TO] [--unmap=U_A] [--verbose] [--version] [--wrprotect=WPR] DEVICE

خلاصه دستور به تفکیک هر دستور پشتیبانی‌شده:

sg_write_x --normal --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dld=DLD] [--dpo] [--fua] [--grpnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict] [--tag-mask=TM] [--timeout=TO] [--wrprotect=WPR] DEVICE

sg_write_x --or --in=IF [--16] [--32] [--bmop=OP,PGP] [--bs=BS] [--dpo] [--fua] [--generation=EOG,NOG] [--grpnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--strict] [--timeout=TO] [--wrprotect=OPR] DEVICE

sg_write_x --atomic=AB --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dpo] [--fua] [--grpnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict] [--timeout=TO] [--wrprotect=WPR] DEVICE

sg_write_x --same=NDOB [--16] [--32] [--app-tag=AT] [--bs=BS] [--dpo] [--fua] [--grpnum=GN] [--in=IF] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict] [--timeout=TO] [--unmap=U_A] [--wrprotect=WPR] DEVICE

sg_write_x --scattered=RD --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dld=DLD] [--dpo] [--fua] [--grpnum=GN] [--lba=LBA[,LBA...]] [--num=NUM[,NUM...]] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--scat-file=SF] [--scat-raw] [--strict] [--tag-mask=TM] [--timeout=TO] [--wrprotect=WPR] DEVICE

sg_write_x --stream=ID --in=IF [--16] [--32] [--app-tag=AT] [--bs=BS] [--dpo] [--fua] [--grpnum=GN] [--lba=LBA] [--num=NUM] [--offset=OFF[,DLEN]] [--ref-tag=RT] [--strict] [--tag-mask=TM] [--timeout=TO] [--wrprotect=WPR] DEVICE

این ابزار یکی از شش دستور SCSI را که همگی مربوط به نوشتن داده روی DEVICE مشخص‌شده هستند، ارسال می‌کند. این دستورات عبارتند از WRITE "عادی"، ORWRITE، WRITE ATOMIC، WRITE SAME، WRITE SCATTERED یا WRITE STREAM. این ابزار از گونه‌های ۱۶ و ۳۲ بایتی هر شش دستور پشتیبانی می‌کند. به همین دلیل برخی دستورات بسیار مرتبط (مانند WRITE(10)) پشتیبانی نمی‌شوند. تمام گونه‌های ۳۲ بایتی، به‌جز ORWRITE(32)، نیازمند آن هستند که DEVICE با اطلاعات حفاظت (PI) نوع ۱، ۲ یا ۳ فرمت شده باشد، که باعث می‌شود تمام بلوک‌های منطقی روی رسانه ۸ بایت (یا مضربی از ۸ بایت) طولانی‌تر شوند.

رابط خط فرمان با بیش از سی گزینه کمی شلوغ است. از این رو، بخش خلاصه دستور پس از فهرست کردن تمام گزینه‌های (طولانی)، گزینه‌های مربوط به هر دستور پشتیبانی‌شده را فهرست می‌کند. برای خلاصه دستور هر یک، گزینه‌ای که دستور SCSI را انتخاب می‌کند در ابتدا نشان داده شده و پس از آن گزینه‌های الزامی می‌آیند. اگر هیچ گزینه دستوری داده نشود، دستور WRITE "عادی" فرض می‌شود. گرچه گزینه --scat-file=SF می‌تواند برای هر دستوری داده شود، تنها برای WRITE SCATTERED که بیشترین کاربرد را دارد نمایش داده شده است. اگر گزینه --scat-file=SF داده شود، نباید هیچ‌یک از گزینه‌های --lba=LBA[,LBA...] یا --num=NUM[,NUM...] مشخص شوند. تنها اولین مورد از گزینه‌های --lba=LBA[,LBA...] و --num=NUM[,NUM...] (یا اولین جفت (یا پنج‌تایی) از گزینه --scat-file=SF) برای تمام دستورات به‌جز WRITE SCATTERED استفاده می‌شود. تمام دستورات می‌توانند علاوه بر موارد نشان‌داده‌شده در خلاصه دستور، گزینه‌های --dry-run و --verbose را نیز بپذیرند.

اندازه بلوک منطقی به بایت را می‌توان به‌طور صریح با گزینه --bs=BS مشخص کرد، به شرطی که BS بزرگ‌تر از صفر باشد. این مقدار معمولاً توانی از دو، ۵۱۲ یا بیشتر است. اگر گزینه --bs=BS داده نشود یا BS صفر باشد، از دستور SCSI READ CAPACITY برای یافتن اندازه بلوک منطقی استفاده می‌شود. ابتدا دستور READ CAPACITY(16) امتحان می‌شود و در صورت موفقیت، اندازه بلوک منطقی در پاسخ معمولاً به‌عنوان اندازه بلوک واقعی برای این ابزار استفاده می‌شود. استثنا زمانی است که PROT_EN در پاسخ تنظیم شده باشد و گزینه --wrprotect=WPR داده شده و غیرصفر باشد؛ در این حالت ۸ (بایت) به اندازه بلوک منطقی اضافه می‌شود تا اندازه بلوک واقعی مورد استفاده این ابزار به دست آید. اگر READ CAPACITY(16) شکست بخورد، READ CAPACITY(10) امتحان می‌شود و در صورت موفقیت، اندازه بلوک منطقی موجود در پاسخ به‌عنوان اندازه بلوک واقعی استفاده می‌شود.

تعداد بایت‌هایی که این ابزار تلاش می‌کند از فایل مشخص‌شده توسط IF بخواند، حاصل‌ضرب اندازه بلوک واقعی در تعداد بلوک‌ها (یعنی NUM یا مجموع آرگومان‌های NUM) است. اگر بایت‌های کمتری از فایل IF خوانده شود و گزینه --strict داده شده باشد، این ابزار با وضعیت خروج SG_LIB_FILE_ERROR خارج می‌شود. اگر بایت‌های کمتری از فایل IF خوانده شود و گزینه --strict داده نشده باشد، بایت‌های صفر جایگزین بایت‌های "از دست رفته" می‌شوند و ابزار به کار خود ادامه می‌دهد.

تلاش برای نوشتن داده‌های چند مگابایتی با یک دستور منفرد احتمالاً به یکی از چندین دلیل با شکست مواجه می‌شود. نخست ممکن است سیستم‌عامل با تخصیص چنین بافر بزرگی مخالفت کند. سپس، لایه گذرگاه مستقیم SCSI معمولاً بلوک‌های داده را به چند مگابایت یا کمتر محدود می‌کند. در نهایت، دستگاه ذخیره‌سازی ممکن است حافظه RAM محدودی برای پشتیبانی از عملیات نوشتن مانند atomic داشته باشد (زیرا ممکن است نیاز به بازگردانی یا rollback داشته باشد). دستگاه ذخیره‌سازی می‌تواند محدودیت‌های خود را از طریق صفحه VPD محدودیت‌های بلوک (0xb0)، از جمله با فیلد حداکثر طول انتقال اتمی، به کلاینت برنامه اطلاع دهد.

یک توصیف‌گر بازه LBA (آدرس بلوک منطقی) تباهیده بدون PI، مقادیر LBA و NUM برابر با صفر دارد. یک توصیف‌گر بازه LBA تباهیده همراه با PI به‌علاوه فیلدهای RT، AT و TM خود را روی صفر تنظیم دارد (توجه: این مقادیر پیش‌فرض برای RT، AT و TM نیستند). آن‌ها از این نظر تباهیده هستند که از بایت‌های لایه پرکننده صفر که پس از لیست پراکنده در بافر خروجی داده قرار می‌گیرند، قابل تمایز نیستند. استاندارد SBC-4 مشخص می‌کند که یک توصیف‌گر بازه LBA تباهیده معتبر است. این امر ممکن است زمانی که RD داده‌شده در گزینه --scattered=RD مقدار ۰ دارد به یک مسئله تبدیل شود. در این حالت منطق برنامه ممکن است نیاز داشته باشد داده‌های ارائه‌شده توسط کاربر را برای محاسبه تعداد توصیف‌گرهای بازه LBA که توسط cdb دستور WRITE SCATTERED الزامی است پیمایش کند. در غیاب اطلاعات دیگر، منطق برنامه یک توصیف‌گر بازه LBA تباهیده را به‌عنوان پایان‌دهنده لیست پراکنده در نظر خواهد گرفت.

مرجع این دستورات استاندارد SBC-4 (T10/BSR INCITS 506-2021) و پیش‌نویس SBC-5 INCITS 571 بازنگری ۱ مورخ ۲۱ مه ۲۰۲۱ است. هر شش دستور SCSI در آن اسناد شرح داده شده‌اند. دستور WRITE ATOMIC در بازنگری ۳ از SBC-4 اضافه شد؛ WRITE STREAM در بازنگری ۷ از SBC-4 افزوده شد؛ WRITE SCATTERED در بازنگری ۱۱ از SBC-4 اضافه شد، در حالی که سایر دستورات در استاندارد قبلی یعنی SBC-3 موجود هستند.

آرگومان‌های گزینه‌های طولانی برای گزینه‌های کوتاه نیز الزامی هستند. گزینه‌ها بر اساس نام گزینه طولانی به ترتیب الفبایی مرتب شده‌اند.

-6, --16
ارسال گونه ۱۶ بایتی cdb از دستور SCSI انتخاب‌شده. اگر هیچ دستوری انتخاب نشده باشد، دستور (عادی) SCSI WRITE(16) ارسال می‌شود. اگر نه این گزینه و نه گزینه --32 داده نشده باشند، این گزینه پیش‌فرض فرض می‌شود.
-3, --32
ارسال گونه ۳۲ بایتی cdb از دستور SCSI انتخاب‌شده. اگر هیچ دستوری انتخاب نشده باشد، دستور (عادی) SCSI WRITE(32) ارسال می‌شود. اگر نه این گزینه و نه گزینه --16 داده نشده باشند، گزینه --16 پیش‌فرض در نظر گرفته می‌شود. اگر هم این گزینه و هم گزینه --16 داده شوند، این گزینه اولویت دارد. توجه داشته باشید که به‌جز ORWRITE(32)، تمام گونه‌های دیگر cdb با طول ۳۲ بایت نیازمند یک DEVICE فرمت‌شده با اطلاعات حفاظت نوع ۱، ۲ یا ۳ هستند.
که در آن AT فیلد "برچسب برنامه کاربردی بلوک منطقی مورد انتظار" موجود در بیشتر گونه‌های ۳۲ بایتی cdb است (به‌استثنای ORWRITE(32)). AT یک فیلد ۱۶ بیتی است که یعنی حداکثر مقدار آن 0xffff است. مقدار پیش‌فرض 0xffff است.
دستور WRITE ATOMIC را انتخاب می‌کند و AB در فیلد مرز اتمی (Atomic Boundary) از cdb آن قرار می‌گیرد. این یک فیلد ۱۶ بیتی است، بنابراین حداکثر مقدار آن 0xffff است. اگر در مورد مقدار مطمئن نیستید، مقدار ۰ را امتحان کنید که تلاش می‌کند کل بافر خروجی داده را در یک عملیات اتمی منفرد بنویسد.
که در آن OP و PGP مقادیری هستند که به ترتیب در فیلدهای BMOP و 'پردازش نسل قبلی' (Previous Generation Processing) در دستور ORWRITE(32) قرار می‌گیرند. BMOP یک فیلد ۳ بیتی است (از ۰ تا ۷) و PGP یک فیلد ۴ بیتی است (از ۰ تا ۱۵). مقدار پیش‌فرض هر دو فیلد ۰ است.
که در آن BS اندازه بلوک منطقی یا اندازه بلوک واقعی است که کمی بزرگ‌تر خواهد بود. مقدار پیش‌فرض صفر است. اگر این گزینه داده نشود یا با مقدار BS برابر با صفر داده شود، دستور SCSI READ CAPACITY(16) به DEVICE ارسال می‌شود. اگر آن شکست بخورد، دستور READ CAPACITY(10) ارسال می‌شود. اندازه بلوک منطقی و واقعی از پاسخ دستور READ CAPACITY استخراج خواهد شد.
این بخش فرض می‌کند BS بزرگ‌تر از صفر است. اگر BS کمتر از ۵۱۲ (بایت) یا غیرمضرب ۸ باشد، هشداری صادر شده و ابزار به کار خود ادامه می‌دهد مگر اینکه گزینه --strict نیز داده شده باشد. اگر BS توانی از دو باشد (مثلاً ۵۱۲)، اندازه بلوک منطقی و واقعی روی BS تنظیم می‌شود (مثلاً ۵۱۲). اگر BS توانی از دو نباشد (مثلاً ۵۲۰)، اندازه بلوک منطقی روی نزدیک‌ترین توان دو کمتر از BS (مثلاً ۵۱۲) تنظیم شده و اندازه بلوک واقعی روی BS (مثلاً ۵۲۰) تنظیم می‌شود.
اگر اندازه بلوک منطقی و واقعی متفاوت باشند، بررسی بعدی اندازه بلوک واقعی را به اندازه بلوک منطقی کاهش می‌دهد، مگر اینکه --wrprotect=WPR بزرگ‌تر از صفر باشد.
این گزینه فقط برای WRITE SCATTERED اعمال می‌شود و فرض می‌کند کل بافر خروجی داده را می‌توان از IF مشخص‌شده توسط گزینه --in=IF خواند. کل بافر خروجی داده عبارت است از سرآیند لیست پارامترها، به دنبال آن صفر یا چند توصیف‌گر بازه LBA، به صورت اختیاری چند بایت لایه پرکننده و سپس داده‌هایی که باید روی رسانه نوشته شوند. اگر گزینه‌های --lba=LBA[,LBA...]، --num=NUM[,NUM...] یا --scat-file=SF نیز داده شوند، خطایی ایجاد می‌شود. آرگومان DOF باید مقداری مناسب برای فیلد 'افست داده‌های بلوک منطقی' در cdb دستور WRITE SCATTERED باشد. این مقدار، افست در بافر خروجی داده است که از آنجا داده‌های قابل نوشتن روی رسانه آغاز می‌شوند. واحد این فیلد اندازه بلوک واقعی است که در صورت ارسال اطلاعات حفاظت (PI)، برابر با اندازه بلوک منطقی به علاوه مضربی از ۸ خواهد بود. هنگامی که WPR (از --wrprotect=WPR) بزرگ‌تر از صفر باشد، وجود PI انتظار می‌رود. استاندارد SBC-4 بازنگری ۱۵ این موضوع را بیان نکرده اما به نظر می‌رسد مقدار ۰ برای DOF نامعتبر است. پیشنهاد می‌شود هنگام آزمایش از این گزینه همراه با گزینه --strict استفاده شود، زیرا داده‌های تصادفی یا نادرست واردشده از طریق گزینه --in=IF می‌تواند داده‌های "عجیبی" را در سراسر DEVICE بنویسد. اگر DOF برابر با ۰ داده شود، این ابزار داده‌ها را در IF پیمایش می‌کند تا زمانی که RD توصیف‌گر بازه LBA پیدا شود؛ یا اگر RD نیز ۰ باشد، تا زمانی که یک توصیف‌گر بازه LBA تباهیده پیدا شود.
که در آن DLD توصیف‌گر محدودیت‌های مدت زمان است که در ۳ بیت از cdbهای SCSI WRITE(16) و WRITE SCATTERED(16) پخش شده است. DLD بین ۰ تا ۷ با مقدار پیش‌فرض صفر است. فیلد DLD0 در WRITE(16) و WRITE SCATTERED(16) در صورتی که (0x1 & DLD) غیرصفر باشد تنظیم می‌شود. فیلد DLD1 در هر دو cdb در صورتی که (0x2 & DLD) غیرصفر باشد تنظیم می‌شود. فیلد DLD2 در هر دو cdb در صورتی که (0x4 & DLD) غیرصفر باشد تنظیم می‌شود.
اگر این گزینه داده شود، فیلد بیتی DPO (غیرفعال کردن تخلیه به حافظه موقت یا disable page out) در cdb تنظیم می‌شود. حالت پیش‌فرض پاک کردن این فیلد بیتی است. برای تمام دستورات پشتیبانی‌شده توسط این ابزار به‌جز WRITE SAME اعمال می‌شود.
این گزینه درست قبل از ارسال دستور نوشتن SCSI انتخاب‌شده، با وضعیت ۰ خارج می‌شود. با این حال ممکن است همچنان یک دستور SCSI READ CAPACITY (گونه ۱۶ بایتی و شاید گونه ۱۰ بایتی) ارسال کند، بنابراین DEVICE همچنان مورد نیاز است. اگر گزینه‌های --in=IF و/یا --scat-file=SF داده شده باشند، داده‌ها را خوانده و پردازش می‌کند. تمام پردازش‌های خط فرمان و بررسی‌های صحت (مثلاً در صورت داده شدن گزینه --strict) انجام خواهد شد و در صورت بروز خطا، وضعیت خروج غیرصفر خواهد بود.
اگر این گزینه دو بار داده شود (مثلاً -xx)، به جای اجرای دستور نوشتن SCSI انتخاب‌شده، بافر خروجی داده در فایلی به نام sg_write_x.bin نوشته می‌شود. اگر وجود نداشته باشد، آن فایل در دایرکتوری جاری ایجاد می‌شود و اگر از قبل با محتوای طولانی‌تر وجود داشته باشد، کوتاه (truncate) می‌شود. بافر خروجی داده به صورت باینری نوشته شده و برخی اطلاعات مربوط به آن در خروجی استاندارد چاپ می‌شود. برای دستورات نوشتن غیر از پراکنده، نام فایل و طول آن به بایت در خروجی استاندارد چاپ می‌شود. برای نوشتن پراکنده، علاوه بر آن، تعداد توصیف‌گرهای بازه LBA و افست داده‌های بلوک منطقی آن نیز در خروجی استاندارد نوشته می‌شود.
اگر این گزینه داده شود، فیلد بیتی FUA (دسترسی اجباری به واحد ذخیره‌سازی یا force unit access) در cdb تنظیم می‌شود. حالت پیش‌فرض پاک کردن این فیلد بیتی است. برای تمام دستورات پشتیبانی‌شده توسط این ابزار به‌جز WRITE SAME اعمال می‌شود.
آرگومان‌های این گزینه تنها توسط دستور ORWRITE(32) استفاده می‌شوند. EOG در فیلد "Expected ORWgeneration" قرار می‌گیرد در حالی که NOG در فیلد "New ORWgeneration" قرار داده می‌شود. هر دو ۳۲ بیت طول دارند و مقدار پیش‌فرض آن‌ها صفر است.
فیلد 'شماره گروه' (Group number) را روی GN تنظیم می‌کند. مقدار پیش‌فرض صفر است. GN باید مقداری بین ۰ تا ۶۳ باشد.
چاپ پیام راهنمای نحوه استفاده و خروج. برای راهنمایی بیشتر چند بار استفاده کنید. در حال حاضر گزینه‌های '-h' تا '-hhhh' خروجی‌های متفاوتی ارائه می‌دهند.
خواندن داده‌ها (به صورت باینری) از فایلی به نام IF در یک فراخوانی سیستمی منفرد سیستم‌عامل (در یونیکس: read(2)). این داده‌ها در یک بافر پیوسته قرار گرفته و سپس به‌عنوان بافر خروجی داده برای تمام دستورات نوشتن SCSI استفاده می‌شوند، به‌جز WRITE SCATTERED(16 یا 32) که ممکن است شامل داده‌های دیگری در بافر خروجی داده باشد. برای WRITE SCATTERED (16 یا 32) بافر خروجی داده از ۳ یا ۴ جزء به این ترتیب تشکیل شده است: یک سرآیند لیست پارامترها (۳۲ بایت صفر)؛ صفر یا چند توصیف‌گر بازه LBA، به صورت اختیاری چند بایت لایه پرکننده (صفرها) و سپس داده‌هایی که باید روی رسانه نوشته شوند. برای WRITE SCATTERED، فایل IF فقط داده‌های قابل نوشتن روی رسانه را فراهم می‌کند مگر اینکه --combined=DOF داده شده باشد. هنگامی که گزینه --combined=DOF مشخص شود، IF شامل تمام اجزای بافر خروجی داده WRITE SCATTERED به صورت باینری خواهد بود. داده‌های خوانده‌شده از IF از افست بایتی OFF (که پیش‌فرض آن صفر است) آغاز می‌شوند و حداکثر DLEN بایت از آن نقطه خوانده می‌شود (یعنی از افست بایتی فایل OFF). اگر DLEN صفر باشد یا داده نشود، بقیه فایل IF خوانده می‌شود. این گزینه الزامی است، مگر زمانی که --same=1 داده شود (که بیت NDOB مخفف "No Data Out Buffer" را تنظیم می‌کند). در سیستم‌عامل‌های مبتنی بر یونیکس، هر تعداد بایت صفر را می‌توان با استفاده از فایل دستگاه /dev/zero تولید کرد.
مقدار IF می‌تواند "-" باشد که به عنوان ورودی استاندارد (stdin) در نظر گرفته می‌شود. در این حالت گزینه --offset=OFF,DLEN می‌تواند با OFF تنظیم‌شده روی ۰ و LEN تنظیم‌شده روی یک مقدار غیرصفر (ترجیحاً مضربی از اندازه بلوک واقعی) داده شود. ابزار همچنین می‌تواند طول مورد نیاز IF را از NUM (یا مجموع آن‌ها در صورت وجود لیست پراکنده) استنباط کند.
که در آن آرگومان، یک آدرس بلوک منطقی (LBA) منفرد یا فهرستی از LBAها جداشده با کاما است که هر یک از آن‌ها آدرس اولین بلوک نوشته‌شده توسط دستور نوشتن انتخاب‌شده است. تنها دستور WRITE SCATTERED می‌تواند به طور مفید بیش از یک LBA بپذیرد. به هر تعداد که LBA داده شود، باید به همان تعداد NUM به گزینه --num=NUM[,NUM...] داده شود. اولین LBA داده‌شده به همراه اولین NUM داده‌شده، اولین توصیف‌گر بازه LBA را تشکیل می‌دهند (که T10 در SBC-4 شماره‌گذاری آن‌ها را از صفر آغاز می‌کند). دومین LBA با دومین NUM می‌آمیزد تا دومین توصیف‌گر بازه LBA را تشکیل دهد، و الی آخر. یک روش راحت‌تر برای تعریف تعداد زیادی توصیف‌گر بازه LBA استفاده از گزینه --scat-file=SF است. مقدار پیش‌فرض بلوک منطقی ۰ است (که می‌تواند خطرناک باشد) در حالی که NUM به طور پیش‌فرض ۰ است که این ترکیب را بی‌خطر می‌سازد. LBA فرض می‌شود در مبنای دهدهی است مگر اینکه دارای پیشوند '0x' یا پسوند 'h' باشد.
انتخاب دستور WRITE "عادی" (۱۶ یا ۳۲) می‌تواند به طور صریح با این گزینه انجام شود. در صورت عدم انتخاب هر دستور دیگر (مانند --atomic=AB)، انتخاب WRITE "عادی" حالت پیش‌فرض است.
که در آن آرگومان، یک تعداد بلوک (NUM) منفرد یا فهرستی از NUMها جداشده با کاما است که با ورودی‌های متناظر در گزینه --lba=LBA[,LBA...] جفت می‌شوند. اگر یک NUM داده شود و با روش دیگری (مثلاً با استفاده از گزینه --scat-file=SF) فراهم نشده باشد، به طور پیش‌فرض روی تعداد بلوک‌های حاصل از اندازه فایل نام‌برده‌شده توسط IF (از افست بایتی OFF تا انتهای فایل یا DLEN) قرار می‌گیرد. به جز در گزینه --combined=DOF، یک LBA باید به طور صریح داده شود (یا با --lba=LBA یا از طریق --scat-file=SF)، در غیر این صورت NUM به عنوان یک تدبیر ایمنی به طور پیش‌فرض روی ۰ قرار می‌گیرد.
که در آن OFF افست بایتی درون فایل نام‌برده‌شده توسط IF برای شروع خواندن است. مقدار پیش‌فرض OFF صفر است که همان ابتدای فایل IF می‌باشد. DLEN حداکثر تعداد بایت‌هایی است که با شروع از افست بایتی OFF از فایل IF خوانده می‌شود. اگر پایان فایل پیش از اتمام DLEN رخ دهد، بایت‌های کمتری خوانده خواهد شد. اگر DLEN صفر باشد یا داده نشود، خواندن از افست بایتی OFF تا پایان فایل IF فرض می‌شود.
دستور ORWRITE را انتخاب می‌کند. ORWRITE(16) دارای فیلدهای مشابه با WRITE(16) است، به جز اینکه فیلد WRPROTECT به ORPROTECT تغییر نام یافته و معنای کمی متفاوت دارد، و همچنین فاقد ۳ فیلد بیتی DLD است. ORWRITE(32) دارای چهار فیلد اضافی است که با گزینه‌های --bmop=OP,PGP و --generation=EOG,NOG تنظیم می‌شوند. دستور ORWRITE(32) تنها دستور cdb با طول ۳۲ بایت در این ابزار است که نیازی به DEVICE فرمت‌شده با PI نوع ۱، ۲ یا ۳ ندارد (اگرچه در صورت فرمت بودن با PI نیز کار خواهد کرد).
فرونشاندن برخی پیام‌های اطلاعاتی مانند پیام‌های مربوط به خطاهای شناسایی‌شده هنگام خروج این ابزار. مقدار وضعیت خروج هنگام خروج ابزار همچنان به سیستم‌عامل بازگردانده می‌شود.
که در آن RT فیلد "برچسب مرجع اولیه بلوک منطقی مورد انتظار" موجود در گونه‌های ۳۲ بایتی cdb دستورات WRITE، WRITE ATOMIC، WRITE SAME و WRITE STREAM است. این فیلد همچنین در توصیف‌گرهای بازه LBA در WRITE SCATTERED(32) یافت می‌شود. این یک فیلد ۳۲ بیتی است، به این معنی که حداکثر مقدار آن 0xffffffff است. مقدار پیش‌فرض 0xffffffff است.
دستور WRITE SAME را انتخاب می‌کند و فیلد NDOB آن را روی NDOB تنظیم می‌نماید که مخفف No Data-Out Buffer است. NDOB می‌تواند مقادیر ۰ یا ۱ را بگیرد (یعنی یک فیلد تک‌بیتی است). هنگامی که --same=1 باشد، تمام گزینه‌های مرتبط با بافر خروجی داده نادیده گرفته می‌شوند.
که در آن SF نام یک فایل کمکی حاوی لیست پراکنده برای دستور WRITE SCATTERED است. اگر گزینه --scat-raw نیز داده شود، فرض می‌شود که SF شامل سرآیند لیست پارامترها (۳۲ بایت صفر) و به دنبال آن صفر یا چند توصیف‌گر بازه LBA است که هر کدام ۳۲ بایت طول دارند. این اجزا مطابق با تعریف SBC-4 هستند (یعنی به صورت باینری با اعداد صحیح در فرمت big-endian). اگر گزینه --scat-raw داده نشود، یک فایل هگزادسیمال اسکی طبق توضیحات بخش «قالب اسکی فایل پراکنده» در زیر انتظار می‌رود.
اگر این گزینه همراه با گزینه --combined=DOF داده شود، این ابزار با خطای نحوی خارج می‌شود. SF نباید "-" باشد، که روشی برای جلوگیری از تلاش کاربر برای تغییر مسیر ورودی استاندارد است.
این گزینه فقط بر نحوه تفسیر فایل نام‌برده‌شده SF از گزینه --scat-file=SF برای WRITE SCATTERED تأثیر می‌گذارد. به طور پیش‌فرض (یعنی بدون این گزینه)، SF به عنوان هگزادسیمال اسکی تجزیه می‌شود و خطوط خالی و محتویات خط از نویسه '#' تا انتهای خط نادیده گرفته می‌شوند. بنابراین می‌تواند شامل توضیحات و نشانه‌های دیگر باشد. هنگامی که این گزینه داده شود، فایل نام‌برده‌شده SF به عنوان باینری تفسیر می‌شود. به عنوان باینری، فرض می‌شود که شامل ۳۲ بایت صفر (سرآیند لیست پارامترهای WRITE SCATTERED) و به دنبال آن صفر یا چند توصیف‌گر بازه LBA (هر کدام ۳۲ بایت) است. اگر گزینه --strict داده شده باشد، فیلدهای رزروشده در این دو مورد بررسی می‌شوند و هر بایت غیرصفر باعث بروز خطا خواهد شد.
دستور WRITE SCATTERED را انتخاب می‌کند که در آن RD تعداد توصیف‌گرهای بازه LBA است که در بافر خروجی داده قرار می‌گیرند. اگر RD صفر باشد، منطق برنامه تلاش می‌کند تعداد توصیف‌گرهای بازه را از روش‌های دیگر (مثلاً با تجزیه فایل نام‌برده‌شده توسط SF، در صورت وجود) تعیین کند. توصیف‌گرهای بازه LBA بین گونه‌های ۱۶ و ۳۲ بایتی cdb دستور WRITE SCATTERED تفاوت دارند. در گونه ۱۶ بایتی cdb، توصیف‌گر بازه LBA ۳۲ بایتی از یک LBA ۸ بایتی، به دنبال آن یک number_of_blocks ۴ بایتی و سپس ۲۰ بایت صفر تشکیل شده است. در گونه ۳۲ بایتی، پس از LBA و number_of_blocks، مقادیر RT (۴ بایت)، AT (۲ بایت) و TM (۲ بایت) و سپس ۱۲ بایت صفر قرار می‌گیرند.
این پاراگراف زمانی اعمال می‌شود که RD بزرگ‌تر از صفر باشد. اگر RD کمتر از تعداد توصیف‌گرهای بازه LBA ساخته‌شده از گزینه‌های خط فرمان، از گزینه --scat-file=SF یا رمزگشایی‌شده از IF (هنگام استفاده از گزینه --combined=DOF) باشد، در این صورت RD اولویت دارد؛ بنابراین RD در فیلد "تعداد توصیف‌گرهای بازه LBA" در cdb قرار می‌گیرد. اگر RD بزرگ‌تر از تعداد توصیف‌گرهای بازه LBA یافت‌شده از داده‌ها و گزینه‌های ارائه‌شده باشد، خطایی صادر می‌شود.
دستور WRITE STREAM را انتخاب می‌کند و فیلد STR_ID را روی ID تنظیم می‌نماید. ID می‌تواند مقادیری از ۰ تا 0xffff را بگیرد (یعنی یک فیلد ۱۶ بیتی است).
هنگامی که این گزینه وجود داشته باشد، موارد بیشتری (مثلاً اینکه فیلدهای رزروشده حاوی صفر باشند) بررسی شده و هرگونه ناهماهنگی باعث خاتمه ابزار با پیامی در خطای استاندارد و یک وضعیت خروج معین می‌شود. هنگام آزمایش با این دستورات، به ویژه WRITE SCATTERED، استفاده از این گزینه توصیه می‌شود.
که در آن TM فیلد "ماسک برچسب برنامه کاربردی بلوک منطقی" موجود در گونه‌های ۳۲ بایتی cdb دستورات WRITE، WRITE ATOMIC، WRITE SAME و WRITE STREAM است. این فیلد همچنین در توصیف‌گرهای بازه LBA در WRITE SCATTERED(32) یافت می‌شود. این یک فیلد ۱۶ بیتی است که یعنی حداکثر مقدار آن 0xffff است. مقدار پیش‌فرض 0xffff است.
که در آن TO مقدار مهلت زمانی دستور بر حسب ثانیه است. مقدار پیش‌فرض ۱۲۰ ثانیه است. اگر NUM روی رسانه‌های کُند بزرگ باشد، ممکن است این دستورات WRITE به زمان بسیار بیشتری از ۱۲۰ ثانیه برای تکمیل نیاز داشته باشند. شکل بلند جایگزین این گزینه --tmo=TO است.
که در آن U_A مقادیر بیتی OR شده است که برای تنظیم فیلدهای بیتی UNMAP و ANCHOR در cdb دستور WRITE SAME (16 یا 32) استفاده می‌شود. اگر U_A برابر با ۱ باشد، فیلد بیتی UNMAP تنظیم می‌شود؛ اگر U_A برابر با ۲ باشد، فیلد بیتی ANCHOR تنظیم می‌شود؛ اگر U_A برابر با ۳ باشد، هر دو فیلد بیتی UNMAP و ANCHOR تنظیم می‌شوند. مقدار پیش‌فرض برای هر دو فیلد بیتی پاک‌شده (۰) است؛ تنظیم U_A روی ۰ نیز هر دو فیلد بیتی را پاک می‌کند.
افزایش سطح پرگویی (پیام‌های اشکال‌زدایی). این پیام‌ها معمولاً در خطای استاندارد نوشته می‌شوند.
چاپ رشته نسخه و خروج.
فیلد WRPROTECT (۳ بیت) را در تمام دستورات sg_write_x به‌جز ORWRITE که فیلد ۳ بیتی ORPROTECT دارد (و در خلاصه دستور برای برجسته کردن تفاوت به صورت OPR نشان داده شده است) تنظیم می‌کند. در همه موارد WPR در آن فیلد ۳ بیتی قرار می‌گیرد. مقدار پیش‌فرض صفر است که هیچ PI را در بافر خروجی داده ارسال نمی‌کند. WPR باید مقداری بین ۰ تا ۷ باشد.

تمام دستورات این ابزار می‌توانند گزینه --scat-file=SF را بپذیرند و این گزینه می‌تواند به عنوان جایگزینی برای گزینه‌های --lba=LBA[,LBA...] و --num=NUM[,NUM...] دیده شود. اگر هر دو گزینه --scat-file=SF و --scat-raw داده شوند، انتظار می‌رود فایلی به نام SF باینری باشد و شامل سرآیند لیست پارامترها (۳۲ بایت صفر برای هر دو گونه ۱۶ و ۳۲ بایتی) و به دنبال آن صفر یا چند توصیف‌گر بازه LBA (هر کدام ۳۲ بایت) باشد. این بخش آنچه در SF در صورت عدم ارائه گزینه --scat-raw انتظار می‌رود را شرح می‌دهد.

"فایل پراکنده" هگزادسیمال اسکی (نام‌گذاری‌شده با SF) می‌تواند شامل توضیحات، خطوط خالی و اعداد باشد. اگر چند عدد در یک خط ظاهر شوند، می‌توان آن‌ها را با فاصله، تب یا یک کاما جدا کرد. اعداد به عنوان ده‌دهی تجزیه می‌شوند مگر اینکه پیشوند "0x" (یا "0X") داشته باشند یا پسوند "h" داشته باشند. پیشوند 0x برای اعداد هگزادسیمال در زبان C است در حالی که T10 از پسوند "h" برای همین منظور استفاده می‌کند. هر چیزی از نویسه "#" تا انتهای خط نادیده گرفته می‌شود، بنابراین می‌توان توضیحات را در آنجا قرار داد.

برای دستور WRITE SCATTERED (16)، توصیف‌گرهای بازه LBA آن شامل دو مورد در هر توصیف‌گر هستند: یک LBA ۸ بایتی و به دنبال آن یک number_of_blocks ۴ بایتی. ۲۰ بایت باقی‌مانده توصیف‌گر صفر هستند. قالب پذیرفته‌شده نسبتاً انعطاف‌پذیر است و هر مقدار رمزگشایی‌شده به نوبت در یک LBA و سپس یک number_of_blocks قرار می‌گیرد تا پایان فایل فرا برسد. الگو با یک LBA شروع می‌شود و اگر با یک number_of_blocks پایان نیابد (یعنی تعداد فردی مقدار تجزیه شود)، خطایی رخ می‌دهد. بنابراین تعداد توصیف‌گرهای بازه LBA تولیدشده نصف تعداد مقادیر تجزیه‌شده در SF خواهد بود.

برای دستور WRITE SCATTERED (32)، توصیف‌گرهای بازه LBA آن شامل پنج مورد در هر توصیف‌گر هستند: یک LBA ۸ بایتی و به دنبال آن یک number_of_blocks ۴ بایتی، سپس یک RT ۴ بایتی، یک AT ۲ بایتی و یک TM ۲ بایتی. سه مورد آخر مربوط به اطلاعات حفاظت (PI) هستند. قالب پذیرفته‌شده در فایل SF محدودتر از گونه ۱۶ بایتی cdb است. موارد مربوط به هر توصیف‌گر بازه LBA باید در یک خط قرار گیرند و موارد مجاور با کاما از هم جدا شوند. دو مورد اول (LBA و number_of_blocks) باید مشخص شوند، و اگر مورد دیگری در خط نباشد، به RT، AT و TM مقادیر پیش‌فرض آن‌ها (تمام بایت‌های "ff") داده می‌شود. فاصله‌ها و تب‌ها می‌توانند بین موارد ظاهر شوند اما کاماها جداکننده هستند. دو کاما بدون هیچ مقداری بین آن‌ها باعث می‌شود که مورد "از قلم افتاده" مقدار پیش‌فرض خود را دریافت کند.

آرگومان‌های عددی گوناگون (مانند LBA) ممکن است شامل پسوندهای ضربی باشند یا در مبنای هگزادسیمال داده شوند. بخش "NUMERIC ARGUMENTS" در صفحه راهنمای sg3_utils(8) را ببینید.

در لینوکس، پیش از نسخه هسته 3.17، درایور sg از اندازه‌های cdb بزرگ‌تر از ۱۶ بایت پشتیبانی نمی‌کرد. بنابراین یک گره دستگاه مانند /dev/sg1 که با درایور sg مرتبط است در صورت مشخص شدن گزینه --32 (یا به طور ضمنی توسط گزینه‌های دیگر) در این ابزار با شکست مواجه می‌شد. درایور bsg با گره‌های دستگاه مانند /dev/bsg/6:0:0:1 از زمان معرفی‌اش در نسخه هسته 2.6.28 از اندازه‌های cdb بزرگ‌تر از ۱۶ بایت پشتیبانی می‌کند.

وضعیت خروج sg_write_x در صورت موفقیت ۰ است. در غیر این صورت صفحه راهنمای sg3_utils(8) را ببینید.

یک کاربرد ساده، نوشتن ۴ بلوک صفر با شروع از (و شامل) یک LBA معین بر اساس قوانین WRITE ATOMIC با مرز اتمی ۰ است. از آنجا که هیچ گزینه اندازه cdb داده نشده است، cdb با طول ۱۶ بایت فرض می‌شود (یعنی WRITE ATOMIC(16)):

sg_write_x --atomic=0 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc

از آنجا که --bs=BS داده نشده است، این ابزار دستور READ CAPACITY(16) را روی /dev/sdc فراخوانی می‌کند تا تعداد بایت‌های یک بلوک منطقی را تعیین کند. اگر دستور READ CAPACITY(16) شکست بخورد، دستور READ CAPACITY(10) امتحان می‌شود. فرض کنیم یکی از آن‌ها کار می‌کند و تعداد بایت‌ها در هر بلوک منطقی ۵۱۲ بایت است. بنابراین ۴ بلوک صفر (هر بلوک شامل ۵۱۲ بایت) از (و شامل) LBA 0x1234 نوشته خواهد شد. حال برای دور زدن نیاز به دستور(های) READ CAPACITY می‌توان از گزینه --bs=BS استفاده کرد:

sg_write_x --atomic=0 --bs=512 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc

از آنجا که =bs-- داده شده و مقدار آن (۵۱۲) توانی از ۲ است، اندازه بلوک واقعی نیز ۵۱۲ خواهد بود. اگر به جای آن ۵۲۰ داده می‌شد، اندازه بلوک منطقی ۵۱۲ (بالاترین توان ۲ کمتر از ۵۲۰) و اندازه بلوک واقعی ۵۲۰ بایت می‌بود. برای ارسال گونه ۳۲ بایتی، --32 را اضافه کنید مانند:

sg_write_x --atomic=0 --32 --bs=512 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc

برای مثال‌های استفاده از 'sg_write_x --same=NDOB' صفحه راهنمای sg_write_same(8) را ببینید. نحو کمی متفاوت است اما معانی یکسان هستند.

برای ارسال یک WRITE STREAM(32) با مقدار STR_ID برابر با ۱، از دستور زیر استفاده کنید:

sg_write_x --stream=1 --32 --bs=512 --in=/dev/zero --lba=0x1234 --num=4 /dev/sdc

دستور بعدی یک دستور WRITE SCATTERED(16) است با لیست پراکنده که در خط فرمان بین گزینه‌های =lba-- و =num-- تقسیم شده است:

sg_write_x  --scattered=2 --lba=2,0x33 --num=4,1 -i /dev/zero /dev/sg1

مثالی از دستور WRITE SCATTERED(16) با یک توصیف‌گر بازه LBA تباهیده (اولین عنصر به =lba-- و =num--):

sg_write_x  --scattered=2 --lba=0,0x33 --num=0,1 -i /dev/zero /dev/sg1

مثالی از دستور WRITE SCATTERED(16) با لیست پراکنده در scat_file.txt:

sg_write_x  --scattered=3 -q scat_file.txt -i /dev/zero /dev/sg1

دستور بعدی یک دستور WRITE SCATTERED(16) با لیست پراکنده و داده‌ها در یک فایل منفرد است. توجه داشته باشید که آرگومان =scattered-- برابر با ۰ است، بنابراین تعداد توصیف‌گرهای بازه LBA با تحلیل دو بلوک اول scat_data.bin محاسبه می‌شود (زیرا آرگومان =combined-- برابر با ۲ است):

sg_write_x  --scattered=0 --combined=2 -i scat_data.bin /dev/sg1

هنگامی که گزینه -xx استفاده می‌شود، دستور WRITE SCATTERED اجرا نمی‌شود بلکه محتویات بافر خروجی داده در فایلی به نام sg_write_x.bin نوشته می‌شود. در مورد WRITE SCATTERED آن فایل باینری برای ارائه به یک فراخوانی بعدی جهت انجام نوشتن واقعی روی رسانه مناسب است. برای مثال:

$ sg_write_x  --scattered=3 -q scat_file.txt -xx -i /dev/zero /dev/sg1
Wrote 8192 bytes to sg_write_x.bin, LB data offset: 1
Number of LBA range descriptors: 3
sg_write_x  --scattered=0 --combined=1 -i sg_write_x.bin /dev/sg1

توجه داشته باشید که وقتی sg_write_x.bin نوشته می‌شود (و چیزی روی رسانه نوشته نمی‌شود)، خلاصه‌ای از آنچه رخ داده به خروجی استاندارد ارسال می‌شود. مقدار نشان‌داده‌شده برای ":LB data offset" (1) باید هنگام نوشتن واقعی روی رسانه (یعنی فراخوانی دوم که مستقیماً در بالا نشان داده شده است) به گزینه =combined-- داده شود.

نوشته‌شده توسط Douglas Gilbert.

گزارش باگ‌ها به <dgilbert at interlog dot com>.

حق نشر © 2017-2023 Douglas Gilbert
این نرم‌افزار تحت مجوز BSD-2-Clause توزیع می‌شود. هیچ ضمانتی وجود ندارد؛ حتی برای قابلیت فروش یا تناسب با یک هدف خاص.

sg_readcap,sg_vpd,sg_write_same,sg_stream_ctl(sg3_utils)

May 2023 sg3_utils-1.48