1 .TH SCSI 3
2 .SH NAME
3 openscsi, scsiready, scsi, scsicmd, scsierror \- SCSI device operations
4 .SH SYNOPSIS
5 .nf
6 .ft L
7 #include <u.h>
8 #include <libc.h>
9 #include <disk.h>
10 .ft
11 .PP
12 .ft L
13 typedef struct Scsi {
14 	char  *inquire;
15 	int   rawfd;
16 	int   nchange;
17 	ulong changetime;
18 };
19 .ft
20 .PP
21 .B
22 Scsi* openscsi(char *devdir)
23 .PP
24 .B 
25 void  closescsi(Scsi *s)
26 .PP
27 .B
28 int   scsiready(Scsi *s)
29 .PP
30 .B
31 int   scsi(Scsi *s, uchar *cmd, int ncmd,
32 .br
33                     void *data, int ndata, int dir)
34 .PP
35 .B
36 int   scsicmd(Scsi *s, uchar *cmd, int ncmd,
37 .br
38                     void *data, int ndata, int dir)
39 .PP
40 .B
41 char* scsierror(int asc, int ascq)
42 .PP
43 .B 
44 int   scsiverbose;
45 .SH DESCRIPTION
46 These routines provide an interface
47 to a SCSI or ATAPI device via Plan 9's
48 \fIsd\fR(3).
49 .PP
50 .I Openscsi
51 attempts to open the file
52 .IB devdir /raw
53 and use it to send raw SCSI commands.
54 On success, it reads the device's inquiry
55 string and stores it in in returned
56 .B Scsi
57 structure.
58 .I Closescsi
59 closes the connection and frees the
60 .B Scsi
61 structure.
62 .PP
63 .I Scsiready
64 sends the ``unit ready'' command up to three times,
65 returning zero if the unit responds that it is ready,
66 or \-1 on error.
67 .PP
68 .I Scsierror
69 returns a textual description of the SCSI status
70 denoted by the ASC and ASCQ sense codes.
71 The description is found by consulting
72 .BR /sys/lib/scsicodes .
73 The returned string will be overwritten by
74 the next call to
75 .IR scsierror .
76 .PP
77 .I Scsi
78 and
79 .I scsicmd
80 execute a single SCSI command on the named device.
81 There should be 
82 .I ncmd
83 bytes of
84 command data in 
85 .IR cmd ;
86 if
87 .I dir
88 is 
89 .BR Sread ,
90 a successful operation
91 will store up to
92 .I ndata
93 bytes into
94 .IR data ,
95 returning the number of bytes stored.
96 If
97 .I dir
98 is
99 .BR Swrite ,
100 the 
101 .I ndata
102 bytes beginning at
103 .I data
104 are transmitted as the data argument to
105 the command, and the
106 number of bytes written is returned.
107 If
108 .I dir
109 is
110 .BR Snone ,
111 .I data
112 and
113 .I ndata
114 are ignored.
115 On error, 
116 .I scsi
117 and
118 .I scsicmd
119 return \-1.
120 .I Scsicmd
121 simply issues the command and
122 returns the result;
123 .I scsi
124 works a bit harder and
125 is the more commonly used routine.
126 .I Scsi
127 attempts to send the command;
128 if it is successful, 
129 .I scsi
130 returns what
131 .I scsicmd
132 returned.
133 Otherwise, 
134 .I scsi
135 sends a request sense command to
136 obtain the reason for the failure,
137 sends a unit ready command in
138 an attempt to bring the unit out of any
139 inconsistent states, and tries again.
140 If the second try fails,
141 .I scsi 
142 sends the request
143 sense and unit ready commands
144 again
145 and then uses
146 .I scsierror
147 to set
148 .I errstr
149 with a reason for failure.
150 .PP
151 The 
152 .B nchange
153 and
154 .B changetime
155 fields
156 in the
157 .B Scsi
158 structure
159 record the number of times a media
160 change has been detected, and the
161 time when the current media was
162 inserted into the drive (really the
163 first time a SCSI command was issued
164 after it was inserted).
165 They are maintained by 
166 .IR scsi .
167 .PP
168 If
169 .I scsiverbose
170 is set,
171 these commands will produce a fair
172 amount of debugging output on file descriptor 2
173 when SCSI commands fail.
174 .SH FILES
175 .TP
176 .B /sys/lib/scsicodes
177 List of textual messages corresponding to SCSI error codes;
178 consulted by
179 .BR scsierror .
180 .SH SOURCE
181 .B /usr/local/plan9/src/libdisk/scsi.c
182 .SH SEE ALSO
183 Plan 9's
184 \fIsd\fR(3) and
185 \fIscuzz\fR(8)
186 .SH BUGS
187 SCSI devices on Unix do not present the interface expected by
188 these routines.