~ubuntu-branches/ubuntu/hardy/sg3-utils/hardy : revision 6

1

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">

2

<html>

3

<head>

4

<title>Linux sg3_utils package</title>

5

6

content="text/html; charset=iso-8859-1">

7

8

9

content="Mozilla/4.79 [en] (X11; U; Linux 2.5.31 i686) [Netscape]">

10

</head>

11

<body alink="#ff0000" background="paper.jpg" bgcolor="#ffffff"

12

link="#0000ff" text="#000000" vlink="#000080">

13

14

<h1><a class="mozTocH1" name="mozTocId697451"></a> The  Linux

15

sg3_utils package</h1>

16

</center>

17

18

19

<li><a href="#mozTocId697451">

20

The  Linux

21

sg3_utils package</a>

22

<ol>

23

<li><a href="#mozTocId746876"> Introduction</a></li>

24

<li><a href="#mozTocId832900"> Contents of sg3_utils</a></li>

25

<li><a href="#mozTocId143590">Changing mode page

26

settings</a></li>

27

<li><a href="#mozTocId301018">Examples</a></li>

28

<li><a href="#mozTocId585558"> Notes</a></li>

29

<li><a href="#mozTocId479511"> Download</a></li>

30

</ol>

31

</li>

32

</ol>

33

<h2><a class="mozTocH2" name="mozTocId746876"></a> Introduction</h2>

34

The sg3_utils package contains

35

utilities

36

that send SCSI commands to "SCSI" devices. As well as devices on

37

transports associated with SCSI (e.g. Fibre Channel (FCP) and the SCSI

38

Parallel Interface(SPI)) many

39

other devices use SCSI command sets. ATAPI cd/dvd drives

40

and SATA disks that use a translation layer or bridge device are

41

examples of devices that use SCSI command sets.

42

43

SCSI command sets are divided into a common set and several device

44

class specific sets. The common set of commands is referred to as the

45

SCSI Primary Commands (SPC) with SPC-3 being the most recent standard.

46

The mandatory SCSI INQUIRY command is defined in SPC-3. The SCSI Block

47

Commands (SBC)

48

cover direct access devices such as disks. The MultiMedia Commands

49

(MMC) cover CD and DVD drives and the media within them. SCSI

50

command sets and transport

51

definitions can be found at the <a href="http://www.t10.org">www.t10.org</a>

52

site with this page giving a good diagrammatic overview: <a

53

href="http://www.t10.org/scsi-3.htm">www.t10.org/scsi-3.htm</a> .

54

55

The

56

sg3_utils package targets the

57

linux kernel 2.4 and 2.6 series and is

58

still being enhanced. An earlier package called sg_utils

59

targeted the linux kernel 2.2 series with some support for the

60

2.0 series. See an earlier version of this web <a href="uu_index.html">page</a>

61

for further information about sg_utils.  This

62

document describes

63

version 1.21 of <span

64

style="font-weight: bold;">sg3_utils .  A subset of these

65

utilities have been ported to the FreeBSD and Tru64 operating systems.

66

67

In the linux kernel 2.4 series most of these utilities must be

68

used with a SCSI generic (sg) driver device name (e.g. <span

69

style="font-family: monospace;">/dev/sg0). In

70

the lk 2.6 series almost all of these utilities can be used with the

71

primary device names as well (e.g. <span

72

style="font-family: monospace;">/dev/sda, /dev/scd0, /dev/st0

73

and

74

/dev/hdd (if it is an

75

ATAPI device)). The SCSI generic (sg) interface

76

still represents a cleaner interface than the primary device names

77

since the drivers behind primary device names have their

78

own policies, may interfere with error processing and, in some cases,

79

run their own

80

state machines.

81

A list of SCSI and storage utility programs that was at the bottom

82

of this page has been moved to the <a href="tools.html">tools</a> page.<span

83

style="font-weight: bold;">

84

85

<h2><a class="mozTocH2" name="mozTocId832900"></a> Contents of sg3_utils</h2>

86

Here is a listing in alphabetical order of the utilities in the

87

sg3_utils package:

88

89

<table style="width: 100%; text-align: left;" border="1" cellpadding="2"

90

cellspacing="2">

91

<tbody>

92

<tr>

93

<td style="vertical-align: top;">Utility

94

</td>

95

<td style="vertical-align: top;">Main

96

SCSI commands

97

</td>

98

<td style="vertical-align: top;">subdirectory

99

</td>

100

<td style="vertical-align: top;">Ported

101

</td>

102

<td style="vertical-align: top;">Notes

103

</td>

104

</tr>

105

<tr>

106

<td style="vertical-align: top;">hxascdmp

107

</td>

108

<td style="vertical-align: top;">-

109

</td>

110

<td style="vertical-align: top;">utils

111

</td>

112

113

</td>

114

<td style="vertical-align: top;">converts stdin (assumed binary)

115

to ASCII hex and ASCII, sending its output to stdout (like Unix <span

116

style="font-weight: bold;">od command)

117

</td>

118

</tr>

119

<tr>

120

<td style="vertical-align: top;">isosize

121

</td>

122

<td style="vertical-align: top;">-

123

</td>

124

<td style="vertical-align: top;">archive

125

</td>

126

127

</td>

128

<td style="vertical-align: top;">size of an ISO 9660 file system,

129

now in the util-linux package

130

</td>

131

</tr>

132

<tr>

133

<td style="vertical-align: top;">rescan-scsi-bus.sh

134

</td>

135

<td style="vertical-align: top;">-

136

</td>

137

<td style="vertical-align: top;">archive

138

</td>

139

140

</td>

141

<td style="vertical-align: top;">copy of Kurt Garloff's useful

142

script

143

</td>

144

</tr>

145

<tr>

146

<td style="vertical-align: top;">scsi_devfs_scan

147

</td>

148

<td style="vertical-align: top;">INQUIRY

149

</td>

150

<td style="vertical-align: top;">archive

151

</td>

152

153

</td>

154

<td style="vertical-align: top;">more relevant to lk 2.4 (in lk

155

2.6 sysfs replaces devfs; see <a href="../scsi/lsscsi.html">lsscsi</a>

156

)

157

</td>

158

</tr>

159

<tr>

160

<td style="vertical-align: top;">scsi_inquiry

161

</td>

162

<td style="vertical-align: top;">INQUIRY

163

</td>

164

<td style="vertical-align: top;">examples

165

</td>

166

167

</td>

168

<td style="vertical-align: top;">uses deprecated

169

SCSI_IOCTL_SEND_COMMAND ioctl

170

</td>

171

</tr>

172

<tr>

173

<td style="vertical-align: top;">sdparm

174

</td>

175

<td style="vertical-align: top;">MODE SENSE/SELECT, INQUIRY

176

</td>

177

<td style="vertical-align: top;">****

178

</td>

179

180

</td>

181

<td style="vertical-align: top;">was in sg3_utils for a short

182

time; now in own package, see <a href="sdparm.html">sdparm</a> .

183

sdparm manipulates mode pages, reads VPD pages and sends simple

184

commands.

185

</td>

186

</tr>

187

<tr>

188

<td style="vertical-align: top;">sg_chk_asc

189

</td>

190

<td style="vertical-align: top;">-

191

</td>

192

<td style="vertical-align: top;">utils

193

</td>

194

195

</td>

196

<td style="vertical-align: top;">check asc/ascq codes from

197

www.t10.org page against sg3_utils table

198

</td>

199

</tr>

200

<tr>

201

<td style="vertical-align: top;">sginfo

202

</td>

203

<td style="vertical-align: top;">MODE SENSE/SELECT, READ DEFECT

204

</td>

205

206

</td>

207

208

</td>

209

<td style="vertical-align: top;">symbolic decoding (optional

210

changing) of mode pages. Can also output (disk) defect lists. In lk 2.4

211

can be given primary device nodes (e.g. /dev/sda) as well as sg device

212

nodes. See scsiinfo package

213

notes below.

214

</td>

215

</tr>

216

<tr>

217

<td style="vertical-align: top;">sgm_dd

218

</td>

219

<td style="vertical-align: top;">READ, WRITE

220

</td>

221

222

</td>

223

224

</td>

225

<td style="vertical-align: top;">sg_dd variant that uses memory

226

mapped IO (only on sg devices)

227

</td>

228

</tr>

229

<tr>

230

<td style="vertical-align: top;">sgp_dd

231

</td>

232

<td style="vertical-align: top;">READ, WRITE

233

</td>

234

235

</td>

236

237

</td>

238

<td style="vertical-align: top;">sg_dd variant that uses POSIX

239

threads

240

</td>

241

</tr>

242

<tr>

243

<td style="vertical-align: top;">sgq_dd

244

</td>

245

<td style="vertical-align: top;">READ, WRITE

246

</td>

247

<td style="vertical-align: top;">archive

248

</td>

249

250

</td>

251

<td style="vertical-align: top;">sg_dd variant that uses

252

asynchronous sg IO calls

253

</td>

254

</tr>

255

<tr>

256

<td style="vertical-align: top;">sg_dd

257

</td>

258

<td style="vertical-align: top;">READ, WRITE

259

</td>

260

261

</td>

262

263

</td>

264

<td style="vertical-align: top;">Unix <span

265

style="font-weight: bold;">dd command variant, uses

266

SG_IO ioctl to send SCSI commands to copy data. See the <a

267

href="sg_dd.html">sg_dd</a> page. </td>

268

</tr>

269

<tr>

270

<td style="vertical-align: top;">sg_emc_trepass

271

</td>

272

<td style="vertical-align: top;">MODE SELECT

273

</td>

274

275

</td>

276

277

</td>

278

<td style="vertical-align: top;">utility specialized for EMC

279

Clariion series

280

</td>

281

</tr>

282

<tr>

283

<td style="vertical-align: top;">sg_format

284

</td>

285

<td style="vertical-align: top;">FORMAT

286

</td>

287

288

</td>

289

<td style="vertical-align: top;">fb,t64

290

</td>

291

<td style="vertical-align: top;">format or resize a SCSI disk

292

</td>

293

</tr>

294

<tr>

295

<td style="vertical-align: top;">sg_get_config

296

</td>

297

<td style="vertical-align: top;">GET CONFIGURATION

298

</td>

299

300

</td>

301

302

<td style="vertical-align: top;">fetch features and profiles of a

303

cd/dvd drive and/or its current media

304

</td>

305

</tr>

306

<tr>

307

<td style="vertical-align: top;">sg_ident

308

</td>

309

<td style="vertical-align: top;">REPORT/SET DEVICE IDENTIFIER

310

</td>

311

312

</td>

313

314

<td style="vertical-align: top;">default is to report (fetch) the

315

device identifier. With the '--set' option a new identifier is sent

316

to the device.

317

</td>

318

</tr>

319

<tr>

320

<td style="vertical-align: top;">sg_inq

321

</td>

322

<td style="vertical-align: top;">INQUIRY

323

</td>

324

325

</td>

326

327

<td style="vertical-align: top;">fetch standard response, VPD

328

pages (including device identification) or version descriptors. Also

329

can perform IDENTIFY (PACKET) DEVICE ATA command. VPD page decoding now

330

also performed by sg_vpd .

331

</td>

332

</tr>

333

<tr>

334

<td style="vertical-align: top;">sg_logs

335

</td>

336

<td style="vertical-align: top;">LOG SENSE

337

</td>

338

339

</td>

340

341

<td style="vertical-align: top;">fetch log sense pages, decode

342

standard pages

343

</td>

344

</tr>

345

<tr>

346

<td style="vertical-align: top;">sg_luns

347

</td>

348

<td style="vertical-align: top;">REPORT LUNS

349

</td>

350

351

</td>

352

353

<td style="vertical-align: top;">fetch luns reported by a device

354

(lun 0 or "well known lu")

355

</td>

356

</tr>

357

<tr>

358

<td style="vertical-align: top;">sg_map

359

</td>

360

<td style="vertical-align: top;">INQUIRY

361

</td>

362

363

</td>

364

365

</td>

366

<td style="vertical-align: top;">shows mapping between sg devices

367

and primary device node (if any). In lk 2.6 see <a

368

href="../scsi/lsscsi.html">lsscsi</a> .

369

</td>

370

</tr>

371

<tr>

372

<td style="vertical-align: top;">sg_map26

373

</td>

374

375

</td>

376

377

</td>

378

379

</td>

380

<td style="vertical-align: top;">maps between single sg device

381

and primary device node (and vice versa). Also does mapping in to, and

382

out of, sysfs. For the linux 2.6 series.

383

</td>

384

</tr>

385

<tr>

386

<td style="vertical-align: top;">sg_modes

387

</td>

388

<td style="vertical-align: top;">MODE SENSE

389

</td>

390

391

</td>

392

393

<td style="vertical-align: top;">dump mode pages (mainly in hex)

394

</td>

395

</tr>

396

<tr>

397

<td style="vertical-align: top;">sg_opcodes

398

</td>

399

<td style="vertical-align: top;">REPORT SUPPORTED OPERATION CODES

400

</td>

401

402

</td>

403

404

</td>

405

<td style="vertical-align: top;">fetch supported SCSI commands or

406

supported task management functions

407

</td>

408

</tr>

409

<tr>

410

<td style="vertical-align: top;">sg_persist

411

</td>

412

<td style="vertical-align: top;">PERSISTENT RESERVE IN/OUT

413

</td>

414

415

</td>

416

417

<td style="vertical-align: top;">control persistent reservations

418

and report

419

reservation status

420

</td>

421

</tr>

422

<tr>

423

<td style="vertical-align: top;">sg_prevent

424

</td>

425

<td style="vertical-align: top;">PREVENT ALLOW MEDIUM REMOVAL

426

</td>

427

428

</td>

429

430

<td style="vertical-align: top;">control media removal, mainly

431

for those SCSI devices which have removable media (e.g. CD/DVD and tape

432

drives)

433

</td>

434

</tr>

435

<tr>

436

<td style="vertical-align: top;">sg_rbuf

437

</td>

438

<td style="vertical-align: top;">READ BUFFER

439

</td>

440

441

</td>

442

443

</td>

444

<td style="vertical-align: top;">read from SCSI device cache.

445

Typically for testing the SCSI transport (for throughput or errors)

446

</td>

447

</tr>

448

<tr>

449

<td style="vertical-align: top;">sg_rdac

450

</td>

451

<td style="vertical-align: top;">MODE SENSE/SELECT

452

</td>

453

454

</td>

455

456

<td style="vertical-align: top;">display or modify RDAC redundant

457

controller mode page

458

</td>

459

</tr>

460

<tr>

461

<td style="vertical-align: top;">sg_read

462

</td>

463

<td style="vertical-align: top;">READ

464

</td>

465

466

</td>

467

468

</td>

469

<td style="vertical-align: top;">read continually from same

470

offset. Syntax similar to sg_dd (without write side). Can test SCSI

471

device cache and transport performance (like sg_rbuf).

472

</td>

473

</tr>

474

<tr>

475

<td style="vertical-align: top;">sg_readcap

476

</td>

477

<td style="vertical-align: top;">READ CAPACITY

478

</td>

479

480

</td>

481

482

<td style="vertical-align: top;">fetch the number of blocks and

483

the individual block size for disks and CD/DVD media

484

</td>

485

</tr>

486

<tr>

487

<td style="vertical-align: top;">sg_read_long

488

</td>

489

<td style="vertical-align: top;">READ LONG

490

</td>

491

492

</td>

493

494

<td style="vertical-align: top;">read data from given lba which

495

includes the block and ECC data.

496

</td>

497

</tr>

498

<tr>

499

<td style="vertical-align: top;">sg_reassign

500

</td>

501

<td style="vertical-align: top;">REASSIGN BLOCKS

502

</td>

503

504

</td>

505

506

<td style="vertical-align: top;">reassign a lba from one sector

507

on a disk (typically damaged) to a new (spare) sector. User data copied

508

if it is recoverable.

509

</td>

510

</tr>

511

<tr>

512

<td style="vertical-align: top;">sg_requests

513

</td>

514

<td style="vertical-align: top;">REQUEST SENSE

515

</td>

516

517

</td>

518

519

<td style="vertical-align: top;">fetch sense data from the given

520

SCSI device. Useful if no autosense , to get progress indication (e.g.

521

during a format) or find the power condition state.

522

</td>

523

</tr>

524

<tr>

525

<td style="vertical-align: top;">sg_reset

526

</td>

527

<td style="vertical-align: top;">-

528

</td>

529

530

</td>

531

532

</td>

533

<td style="vertical-align: top;">Issue a driver, (SCSI) bus or

534

device (target or lun?) reset.

535

</td>

536

</tr>

537

<tr>

538

<td style="vertical-align: top;">sg_rmsn

539

</td>

540

<td style="vertical-align: top;">READ MEDIA SERIAL NUMBER

541

</td>

542

543

</td>

544

545

<td style="vertical-align: top;">Relatively new command

546

added to SPC-3. Format of response is vendor specific so this utility

547

outputs it in hex (default) or binary.

548

</td>

549

</tr>

550

<tr>

551

<td style="vertical-align: top;">sg_rtpg

552

</td>

553

<td style="vertical-align: top;">REPORT TARGET PORT GROUPS

554

</td>

555

556

</td>

557

558

<td style="vertical-align: top;">Specialized for multi-ported

559

SCSI devices where one port (or a group of them) is preferred for IO

560

over another (or others).

561

</td>

562

</tr>

563

<tr>

564

<td style="vertical-align: top;">sg_sat_identify

565

</td>

566

<td style="vertical-align: top;">ATA PASS THROUGH

567

</td>

568

<td style="vertical-align: top;">examples

569

</td>

570

571

</td>

572

<td style="vertical-align: top;">Sends IDENTIFY (PACKET) DEVICE

573

ATA command via the SAT ATA PASS THROUGH SCSI command. Also

574

sg_sat_chk_power and sg_sat_smart_rd_data .

575

</td>

576

</tr>

577

<tr>

578

<td style="vertical-align: top;">sg_scan

579

</td>

580

<td style="vertical-align: top;">[INQUIRY]

581

</td>

582

583

</td>

584

585

</td>

586

<td style="vertical-align: top;">maps each sg device name to

587

the corresponding numeric <host, channel, target', lun> tuple. In

588

lk 2.6 series the "<a href="scsi/lsscsi.html">lsscsi</a> -g" command is

589

similar.

590

</td>

591

</tr>

592

<tr>

593

<td style="vertical-align: top;">sg_senddiag

594

</td>

595

<td style="vertical-align: top;">SEND DIAGNOSTIC

596

</td>

597

598

</td>

599

600

<td style="vertical-align: top;">Issues either a default self

601

test or a short/extended foreground/background self test. With no

602

arguments it uses RECEIVE DIAGNOSTIC to list all supported diagnostic

603

pages.

604

</td>

605

</tr>

606

<tr>

607

<td style="vertical-align: top;">sg_ses

608

</td>

609

<td style="vertical-align: top;">SEND/RECEIVE DIAGNOSTIC

610

</td>

611

612

</td>

613

614

<td style="vertical-align: top;">Fetches status diagnostic

615

pages from, and sends some control pages to, a SCSI Enclosure Services

616

(SES) device.

617

</td>

618

</tr>

619

<tr>

620

<td style="vertical-align: top;">sg_simple1,2,3,4,5

621

</td>

622

<td style="vertical-align: top;">INQUIRY, TEST UNIT READY

623

</td>

624

<td style="vertical-align: top;">examples

625

</td>

626

627

</td>

628

<td style="vertical-align: top;">Simple code examples of using

629

the scsi generic (sg) driver interface

630

</td>

631

</tr>

632

<tr>

633

<td style="vertical-align: top;">sg_simple16

634

</td>

635

<td style="vertical-align: top;">READ

636

</td>

637

<td style="vertical-align: top;">examples

638

</td>

639

640

</td>

641

<td style="vertical-align: top;">Simple code example of sending a

642

16 byte cdb SCSI READ command

643

</td>

644

</tr>

645

<tr>

646

<td style="vertical-align: top;">sg_start

647

</td>

648

<td style="vertical-align: top;">START STOP UNIT

649

</td>

650

651

</td>

652

653

<td style="vertical-align: top;">Controls the power condition

654

state of a SCSI device. Primary use is to spin up and down SCSI disks.

655

</td>

656

</tr>

657

<tr>

658

<td style="vertical-align: top;">sg_sync

659

</td>

660

<td style="vertical-align: top;">SYNCHRONIZE CACHE

661

</td>

662

663

</td>

664

665

<td style="vertical-align: top;">Causes disk caches to be flushed

666

to media

667

</td>

668

</tr>

669

<tr>

670

<td style="vertical-align: top;">sg_test_rwbuf

671

</td>

672

<td style="vertical-align: top;">READ/WRITE BUFFER

673

</td>

674

675

</td>

676

677

</td>

678

<td style="vertical-align: top;">Random pattern written to SCSI

679

device buffer then read back and checked. Used in testing for data

680

corruption.

681

</td>

682

</tr>

683

<tr>

684

<td style="vertical-align: top;">sg_turs

685

</td>

686

<td style="vertical-align: top;">TEST UNIT READY

687

</td>

688

689

</td>

690

691

<td style="vertical-align: top;">Issue one or more Test Unit

692

Ready commands. Can be used to time SCSI command overhead.

693

</td>

694

</tr>

695

<tr>

696

<td style="vertical-align: top;">sg_verify</td>

697

<td style="vertical-align: top;">VERIFY</td>

698

699

</td>

700

701

<td style="vertical-align: top;">reads indicated blocks on a SCSI

702

disks, stops on the first error found. Does not yield any data. Useful

703

for media scans.</td>

704

</tr>

705

<tr>

706

<td style="vertical-align: top;">sg_vpd

707

</td>

708

<td style="vertical-align: top;">INQUIRY

709

</td>

710

711

</td>

712

<td style="vertical-align: top;">fb,t64

713

</td>

714

<td style="vertical-align: top;">Decodes standard and some vendor

715

Vital Product Data (VPD) pages.

716

</td>

717

</tr>

718

<tr>

719

<td style="vertical-align: top;">sg_write_long

720

</td>

721

<td style="vertical-align: top;">WRITE LONG

722

</td>

723

724

</td>

725

726

<td style="vertical-align: top;">writes to a lba, data which

727

includes the block and ECC data. Suitable data typically fetched by

728

prior

729

sg_read_long utility.

730

</td>

731

</tr>

732

<tr>

733

<td style="vertical-align: top;">sg_wr_mode

734

</td>

735

<td style="vertical-align: top;">MODE SELECT

736

</td>

737

738

</td>

739

740

<td style="vertical-align: top;">writes mode pages supplied in

741

ASCII hex (e.g. from "sg_modes -r") to the given SCSI device. See <a

742

href="sdparm.html">sdparm</a> for another method of setting mode page

743

parameters.

744

</td>

745

</tr>

746

</tbody>

747

</table>

748

749

More SCSI commands may be issued than shown in the "main SCSI

750

commands" column. For example many utilities issue a SCSI INQUIRY

751

command to find out the peripheral device type of the given SCSI

752

device. Some SCSI commands listed above are only relevant to a specific

753

device type (e.g. FORMAT UNIT) and should not be sent to a device

754

belonging to other peripheral device types (and in some cases these

755

utilities will

756

block inappropriate attempts). See the COVERAGE file in the main

757

directory of the tarball for a more exhaustive list of SCSI (and ATA)

758

commands

759

issued by the sg3_utils utilities.

760

761

If the "subdirectory"

762

column is empty in the above table then that utility is in the main

763

directory and more

764

documentation can be found in its "man" page. All utilities in the main

765

directory have "man" pages and some in the subdirectories have "man"

766

pages.

767

768

If the "Ported" column is empty then the utility is only found in

769

Linux. At this time the other ports are to FreeBSD, indicated by "fb"

770

in the "Ported" column, and to Tru64, indicated by "t64" in the

771

"Ported" column. See the README.freebsd and the README.tru64 files

772

for more information.

773

774

In the above table all utilities in the main directory except sgp_dd

775

issue SG_IO ioctls when they want to send SCSI commands to the given

776

device. The sgp_dd utility issues SCSI commands using the sg

777

driver's asynchronous ( write()/read() ) interface to device nodes that

778

have the sg driver's major device number (i.e. "char" major 21). This

779

means that all utilities in the main directory are "safe" with any

780

given device node. If the device node does not support the SG_IO ioctl

781

then that is reported and the utility exits. [In version 1.14 sgm_dd

782

also use the sg

783

driver's asynchronous ( write()/read() ) interface but that has been

784

changed to the SG_IO ioctl in version 1.15 since the asynchronous

785

action is not needed. sgm_dd will only use mmapped IO on sg device

786

nodes.]

787

788

Irrespective of the Unix device node used to access a device, care

789

should be taken not to interfere with a device while it is "active".

790

For example invoking a "sg_format -F" utility on a disk with mounted

791

file

792

systems on it is going to cause damage.

793

794

Each process containing one of these command line utilities completes

795

with an exit status 0 when

796

successful. Prior to version 1.21 all errors yielded an exit status of

797

1. From version 1.21 the exit status is one of:

798

<ul>

799

<li>1   syntax

800

error in command line options or their arguments, or an illegal

801

combination of options.</li>

802

<li>2   the device

803

reports that it is not ready for the operation requested. The device

804

may be in the process of becoming ready (e.g. spinning up but not at

805

speed) so the utility may work a little while later.</li>

806

<li>3   the device

807

reports a medium or hardware error (or a blank check). For example an

808

attempt to read a corrupted block on a disk will yield this value.

809

</li>

810

<li>5   the device

811

reports an "illegal request" with an additional sense code other than

812

"invalid operation code". This is often a supported command with a

813

field set requesting an unsupported capability. For commands that

814

require a "service action" field (e.g. READ CAPACITY(16) ) this value

815

can indicate that the

816

command is not supported.</li>

817

<li>6   the device

818

reports a "unit attention" condition. This usually indicates that

819

something unrelated to the requested command has occurred (e.g. a

820

device reset) potentially before the current SCSI command was sent. The

821

requested command has not been executed by the device. Note that unit

822

attention conditions are usually only reported once by a device.</li>

823

<li>9   the device

824

reports an illegal request with an additional sense code of "invalid

825

operation code" which means that it doesn't support the requested

826

command.</li>

827

<li>10   the

828

<scsi_device> reports it has a check condition but "no sense".

829

Some polling commands (e.g. REQUEST SENSE) can react this way. It is

830

unlikely that this value will occur as an exit status.</li>

831

<li>11   the device

832

reports a "recovered error". The requested command was successful. Most

833

likely a utility will report a recovered error to stderr and continue,

834

probably leaving the utility with an exit status of 0 .</li>

835

<li>15   the utility is

836

unable to open, close or use the given device. The given file name

837

could be incorrect or there may be permission problems. Adding the '-v'

838

option may give more information.</li>

839

<li>33   the

840

command sent to the device has timed out.</li>

841

<li>97   the

842

response to a SCSI command failed sanity checks.</li>

843

<li>98   the device

844

reports it has a check condition but the error doesn't fit into any of

845

the above categories.</li>

846

<li>99   any errors

847

that can't be categorized into values 1 to 98 may yield this value.

848

This includes transport and operating system errors.

849

</li>

850

</ul>

851

Many of the above exit statuses will be repeatable so executing the

852

utility again with one or more '-v' options may yield more information.

853

Unit attentions (exit status 6) are only reported once per condition.

854

Notice that some of the lower exit status values correspond to the SCSI

855

sense key values that they correspond to.

856

<h2><a class="mozTocH2" name="mozTocId143590"></a>Changing mode page

857

settings</h2>

858

SCSI devices store settings (metadata) that could possibly be changed

859

by the user (called the "application client" in SCSI jargon) in mode

860

pages. It is a common requirement to find mode page settings and in

861

some cases change them. An example is the Writeback Cache Enable (WCE)

862

bit

863

in the Caching mode page of SCSI disks. Usually the manufacturer's

864

default setting for WCE is set (on) however in some RAID configurations

865

it may be cleared (off).

866

867

Generic command line tools to change mode page settings tend to be

868

difficult to use (which in some small part is due to the SCSI rules for

869

manipulating mode pages). Here is a list of some linux utilities for

870

changing

871

mode pages followed by some notes:

872

<ul>

873

<li>scsiinfo (old utility):

874

awkward command line interface with double invocation (first to get,

875

second to set). Only mode page fields that the utility knows about can

876

be changed.

877

</li>

878

<li>sginfo (sg3_utils version

879

of scsiinfo): same awkward interface as scsiinfo but the mode pages are

880

more up to date. Supports other modern features such as mode subpages.

881

</li>

882

<li>sg_wr_mode (sg3_utils):

883

low level mode page settings based on ASCII hex representation. Used

884

with sg_modes to get a mode page in raw form and assumes ACSII hex will

885

be edited. Low level but general.</li>

886

<li>sdparm (sdparm): uses

887

acronyms (e.g. WCE) or numeric addressing to fetch and/or change mode

888

page settings.

889

Allows device to be reset to default settings for a specific mode page.

890

The user can choose whether changes are also made to the "saved" mode

891

page values. The

892

numeric addressing allows arbitrary fields to be changed (i.e. sdparm

893

doesn't need to know about them in advance).

894

</li>

895

<li>sgmode (scsirastools):

896

interactive utility for setting mode pages with data held in preset

897

".mdf" files. Useful to setting a large number of disks to preset mode

898

page values but awkward for manipulating a specific mode page field.</li>

899

<li>hdparm (hdparm):

900

abstracts over ATA (mainly) and SCSI (where convenient) disks. Write

901

caching can be turned on and off but that is one of the few mode fields

902

that can be changed on a SCSI device.

903

</li>

904

<li>blktool (blktool): much

905

newer and cleaner version of hdparm which targets the linux kernel 2.6

906

series.

907

For SCSI devices only a relatively small (but important) number of mode

908

page fields can be changed.</li>

909

<li>vendor specific (e.g. seatools from Seagate): several vendors

910

have utilities like this. Worth investigating and often useful with

911

disks from other manufacturers. Vendor extensions can be controlled

912

(e.g. Seagate's desktop/server mode (also see sdparm's man page about

913

this particular feature)).

914

</li>

915

</ul>

916

The author's recommendation is to use <a href="sdparm.html">sdparm</a>

917

unless the features of

918

another utility better suit your needs.

919

<h2><a class="mozTocH2" name="mozTocId301018"></a>Examples</h2>

920

The fundamental SCSI command whose support is mandatory for all SCSI

921

devices is INQUIRY. All devices should respond to a "standard" (i.e.

922

when no Vital Product Pages are requested) INQUIRY.

923

924

$ sg_inq /dev/sda<br

925

style="font-family: monospace;">

926

standard INQUIRY:<br

927

style="font-family: monospace;">

928

PQual=0

929

Device_type=0  RMB=0  version=0x03  [SPC]<br

930

style="font-family: monospace;">

931

[AERC=0]

932

[TrmTsk=0]  NormACA=0  HiSUP=1  Resp_data_format=2<br

933

style="font-family: monospace;">

934

SCCS=0  ACC=0

935

TGPS=0  3PC=0  Protect=0<br

936

style="font-family: monospace;">

937

BQue=0

938

EncServ=0  MultiP=0  MChngr=0  [ACKREQQ=0]  Addr16=1<br

939

style="font-family: monospace;">

940

[RelAdr=0]

941

WBus16=1  Sync=1  Linked=1  [TranDis=1]  CmdQue=1<br

942

style="font-family: monospace;">

943

Clocking=0x3

944

QAS=0  IUS=0

945

length=144

946

(0x90)   Peripheral device type: disk<br

947

style="font-family: monospace;">

948

Vendor identification:

949

SEAGATE

950

Product identification:

951

ST318451LW

952

Product revision level: 0003<br

953

style="font-family: monospace;">

954

Unit serial number:

955

xxxxxxxxx

956

957

Some SCSI devices have version descriptor information showing which

958

standards (and drafts) they support:

959

960

$ sg_inq -d /dev/sdb<br

961

style="font-family: monospace;">

962

standard INQUIRY:<br

963

style="font-family: monospace;">

964

PQual=0

965

Device_type=0  RMB=0  version=0x03  [SPC]<br

966

style="font-family: monospace;">

967

[AERC=0]

968

[TrmTsk=0]  NormACA=0  HiSUP=0  Resp_data_format=2<br

969

style="font-family: monospace;">

970

SCCS=0  ACC=0

971

TGPS=0  3PC=0  Protect=0<br

972

style="font-family: monospace;">

973

BQue=0

974

EncServ=0  MultiP=0  MChngr=0  [ACKREQQ=0]  Addr16=1<br

975

style="font-family: monospace;">

976

[RelAdr=0]

977

WBus16=1  Sync=1  Linked=1  [TranDis=1]  CmdQue=1<br

978

style="font-family: monospace;">

979

Clocking=0x0

980

QAS=0  IUS=0

981

length=96

982

(0x60)   Peripheral device type: disk<br

983

style="font-family: monospace;">

984

Vendor identification:

985

FUJITSU

986

Product identification:

987

MAM3184MP

988

Product revision level: 0106<br

989

style="font-family: monospace;">

990

Unit serial number:

991

xxxxxxxxx

992

993

Version descriptors:<br

994

style="font-family: monospace;">

995

SAM-2 (no

996

version claimed)

997

SPI-3

998

T10/1302-D revision 10

999

SPC ANSI

1000

X3.301:1997

1001

SBC T10/0996-D

1002

revision 08c

1003

1004

Many modern SCSI devices also support "Vital Product Data" (VPD) pages.

1005

Here is a request to list available VPD pages:

1006

1007

$ sg_inq -e /dev/sg1<br

1008

style="font-family: monospace;">

1009

VPD INQUIRY, page code=0x00:<br

1010

style="font-family: monospace;">

1011

[PQual=0

1012

Peripheral device type: disk]

1013

Supported VPD pages:<br

1014

style="font-family: monospace;">

1015

1016

0x0        Supported VPD pages<br

1017

style="font-family: monospace;">

1018

1019

0x80       Unit serial number<br

1020

style="font-family: monospace;">

1021

1022

0x83       Device identification

1023

1024

For displaying VPD pages, sg_vpd (or sdparm) may be a better choice

1025

than sg_inq as sg_vpd has a simpler, less cluttered command line

1026

interface and additional support for vendor specific VPD pages.

1027

1028

# sg_vpd /dev/sdh<br

1029

style="font-family: monospace;">

1030

Supported VPD pages VPD page:<br

1031

style="font-family: monospace;">

1032

Supported VPD pages [sv]<br

1033

style="font-family: monospace;">

1034

Unit serial number [sn]<br

1035

style="font-family: monospace;">

1036

Implemented operating

1037

definition (obs) [iod]

1038

Device identification [di]

1039

1040

The following displays a subset of the device identification VPD page,

1041

namely the designators for the target port:

1042

1043

# sg_vpd --page=di_port /dev/sdh<br

1044

style="font-family: monospace;">

1045

Device Identification VPD page:<br

1046

style="font-family: monospace;">

1047

Target port:<br

1048

style="font-family: monospace;">

1049

desig_type:

1050

NAA,  code_set: Binary

1051

1052

transport: Serial Attached SCSI (SAS)<br

1053

style="font-family: monospace;">

1054

1055

0x5000c500005208ee

1056

desig_type:

1057

Relative target port,  code_set: Binary<br

1058

style="font-family: monospace;">

1059

1060

transport: Serial Attached SCSI (SAS)<br

1061

style="font-family: monospace;">

1062

1063

Relative target port: 0x2

1064

1065

The sg_scan and sg_map utilities show the relationships between sg

1066

devices and their <bus, channel, target, lun> tuples and their

1067

primary device node names:

1068

Example: given these 3 SCSI devices:

1069

<tt style="font-family: monospace;">$ cat /proc/scsi/scsi</tt><span

1070

style="font-family: monospace;"> <br

1071

style="font-family: monospace;">

1072

<tt style="font-family: monospace;">Attached devices:</tt><span

1073

style="font-family: monospace;"> <br

1074

style="font-family: monospace;">

1075

<tt style="font-family: monospace;">Host: scsi1 Channel: 00 Id: 00 Lun:

1076

00</tt> <br

1077

style="font-family: monospace;">

1078

<tt style="font-family: monospace;">  Vendor: SEAGATE  Model:

1079

ST318451LW       Rev: 0003</tt><span

1080

style="font-family: monospace;"> <br

1081

style="font-family: monospace;">

1082

<tt style="font-family: monospace;">  Type:

1083

Direct-Access                   

1084

ANSI SCSI revision: 03</tt> <br

1085

style="font-family: monospace;">

1086

<tt style="font-family: monospace;">Host: scsi2 Channel: 00 Id: 04 Lun:

1087

00</tt> <br

1088

style="font-family: monospace;">

1089

<tt style="font-family: monospace;">  Vendor: PIONEER  Model:

1090

DVD-ROM DVD-303  Rev: 1.10</tt><span

1091

style="font-family: monospace;">

1092

1093

<tt style="font-family: monospace;">  Type:

1094

CD-ROM                          

1095

ANSI SCSI revision: 02</tt> <br

1096

style="font-family: monospace;">

1097

<tt style="font-family: monospace;">Host: scsi2 Channel: 00 Id: 06 Lun:

1098

00</tt> <br

1099

style="font-family: monospace;">

1100

<tt style="font-family: monospace;">  Vendor: YAMAHA

1101

Model:

1102

CRW4416S         Rev: 1.0g</tt><span

1103

style="font-family: monospace;">

1104

1105

<tt style="font-family: monospace;">  Type:

1106

CD-ROM                          

1107

ANSI SCSI revision: 02</tt>

1108

then the output from sg_scan is:

1109

<tt style="font-family: monospace;">$ sg_scan</tt><span

1110

style="font-family: monospace;"> <br

1111

style="font-family: monospace;">

1112

<tt style="font-family: monospace;">/dev/sg0: scsi1 channel=0 id=0

1113

lun=0  type=0</tt> <tt

1114

style="font-family: monospace;">

1115

/dev/sg1: scsi2 channel=0 id=4 lun=0  type=5</tt><span

1116

style="font-family: monospace;"> <br

1117

style="font-family: monospace;">

1118

<tt style="font-family: monospace;">/dev/sg2: scsi2 channel=0 id=6

1119

lun=0  type=5</tt>

1120

INQUIRY data can be added to that output with the "-i" option. The

1121

sg_map utility shows the mapping between scsi generic (sg) devices and

1122

the corresponding primary device node. For some peripheral device

1123

types, SCSI enclosures for example, there is no mapping and the

1124

enclosure device must be accessed via a sg device node.

1125

1126

$ sg_map

1127

/dev/sg0  /dev/sda

1128

/dev/sg1  /dev/scd0

1129

/dev/sg2  /dev/scd1

1130

In the lk 2.6 series of kernels sg_scan and sg_map are less important

1131

as most

1132

utilities in the sg3_utils package can be issued directly against the

1133

primary device node (e.g. /dev/sda).  However the sg driver is

1134

still needed to "talk" to devices such as enclosures which have no

1135

specialized driver in linux.

1136

<h2><a class="mozTocH2" name="mozTocId585558"></a> Notes</h2>

1137

Starting with sg3_utils-1.09 a library called libsgutils is built and

1138

is required by most utilities. The library is made up of two source

1139

files: sg_lib.c and sg_cmds.c; and their associated header files . The

1140

sg_lib.c file contains SCSI

1141

command,

1142

sense key and additional sense code strings and various related helper

1143

functions. The sg_cmds.c file contains low level wrapper functions for

1144

commonly used SCSI commands. The library is built both as a shared

1145

object and a static library. The binary rpm package only contains the

1146

shared library while the sg3_utils-devel rpm package contains the

1147

static library, sg_lib.h and sg_cmds.h . If users do not want libraries

1148

(shared or static) then they can refer to the "no_lib" subdirectory

1149

in the tarball which contains "no_lib" versions of the Makefile and the

1150

rpm "spec" file.

1151

1152

Many of the utilities in the sg3_utils package use the SG_IO ioctl

1153

(rather than the older write()/read() interface) in the sg driver. In

1154

the lk 2.6  series the SG_IO ioctl (or at least a stripped

1155

down version of it) has been implemented in the block subsystem. That

1156

means that commands that previously only worked on sg device names will

1157

now work on block device names as well (e.g. "sg_inq /dev/sda"). To use

1158

this facility safely version sg3_utils-1.02 or later should be used.

1159

Note that SCSI tape devices (both st and osst device drivers) are char

1160

devices and support the SG_IO ioctl from lk 2.6.6 onwards.

1161

See the notes about header file problems in the README file inside

1162

each package.

1163

<h2><a class="mozTocH2" name="mozTocId479511"></a> Download</h2>

1164

Various tarballs that include the source, a README, CHANGELOG, INSTALL

1165

and a Makefile can be found in the <a

1166

href="http://www.torque.net/sg/index.html#mozTocId566194"><span

1167

style="text-decoration: underline;">table 2</a> on the <a

1168

href="index.html">main</a>

1169

page. There are also source,

1170

i386 binary rpm and deb packages available. Both sg3_utils and the

1171

older sg_utils packages can

1172

be found on http://freshmeat.net .<a

1173

href="http://oss.metaparadigm.com/safte-monitor"></a>

1174

1175

Return to <a href="index.html">main</a> page.

1176

1177

Last updated: 6th July 2006

1178

1179

1180

</center>

1181

</body>

1182

</html>