sys/man/2/scsi

   1 .TH SCSI 2
   2 .SH NAME
   3 openscsi, closescsi, 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 .ft L
  31 int   scsi(Scsi *s, uchar *cmd, int ncmd,
  32 .br
  33                     void *data, int ndata, int dir)
  34 .PP
  35 .ft L
  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
  48 .IR sd (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
  56 .I inquire
  57 in the returned
  58 .B Scsi
  59 structure.
  60 .I Closescsi
  61 closes the connection and frees the
  62 .B Scsi
  63 structure.
  64 .PP
  65 .I Scsiready
  66 sends the ``unit ready'' command up to three times,
  67 returning zero if the unit responds that it is ready,
  68 or \-1 on error.
  69 .PP
  70 .I Scsierror
  71 returns a textual description of the SCSI status
  72 denoted by the ASC and ASCQ sense codes.
  73 The description is found by consulting
  74 .BR /sys/lib/scsicodes .
  75 The returned string will be overwritten by
  76 the next call to
  77 .IR scsierror .
  78 .PP
  79 .I Scsi
  80 and
  81 .I scsicmd
  82 execute a single SCSI command on the named device.
  83 There should be
  84 .I ncmd
  85 bytes of
  86 command data in
  87 .IR cmd ;
  88 if
  89 .I dir
  90 is
  91 .BR Sread ,
  92 a successful operation
  93 will store up to
  94 .I ndata
  95 bytes into
  96 .IR data ,
  97 returning the number of bytes stored.
  98 If
  99 .I dir
 100 is
 101 .BR Swrite ,
 102 the
 103 .I ndata
 104 bytes beginning at
 105 .I data
 106 are transmitted as the data argument to
 107 the command, and the
 108 number of bytes written is returned.
 109 If
 110 .I dir
 111 is
 112 .BR Snone ,
 113 .I data
 114 and
 115 .I ndata
 116 are ignored.
 117 On error,
 118 .I scsi
 119 and
 120 .I scsicmd
 121 return \-1.
 122 .I Scsicmd
 123 simply issues the command and
 124 returns the result;
 125 .I scsi
 126 works a bit harder and
 127 is the more commonly used routine.
 128 .I Scsi
 129 attempts to send the command;
 130 if it is successful,
 131 .I scsi
 132 returns what
 133 .I scsicmd
 134 returned.
 135 Otherwise,
 136 .I scsi
 137 sends a request sense command to
 138 obtain the reason for the failure,
 139 sends a unit ready command in
 140 an attempt to bring the unit out of any
 141 inconsistent states, and tries again.
 142 If the second try fails,
 143 .I scsi
 144 sends the request
 145 sense and unit ready commands
 146 again
 147 and then uses
 148 .I scsierror
 149 to set
 150 .I errstr
 151 with a reason for failure.
 152 .PP
 153 The
 154 .B nchange
 155 and
 156 .B changetime
 157 fields
 158 in the
 159 .B Scsi
 160 structure
 161 record the number of times a media
 162 change has been detected, and the
 163 time when the current media was
 164 inserted into the drive (really the
 165 first time a SCSI command was issued
 166 after it was inserted).
 167 They are maintained by
 168 .IR scsi .
 169 .PP
 170 If
 171 .I scsiverbose
 172 is set,
 173 these commands will produce a fair
 174 amount of debugging output on file descriptor 2
 175 when SCSI commands fail.
 176 .SH FILES
 177 .TP
 178 .B /sys/lib/scsicodes
 179 List of textual messages corresponding to SCSI error codes;
 180 consulted by
 181 .BR scsierror .
 182 .SH SOURCE
 183 .B /sys/src/libdisk/scsi.c
 184 .SH SEE ALSO
 185 .IR sd (3),
 186 .IR scuzz (8)