1ST(4)                      Linux Programmer's Manual                     ST(4)
2
3
4

NAME

6       st - SCSI tape device
7

SYNOPSIS

9       #include <sys/mtio.h>
10
11       int ioctl(int fd, int request [, (void *)arg3]);
12       int ioctl(int fd, MTIOCTOP, (struct mtop *)mt_cmd);
13       int ioctl(int fd, MTIOCGET, (struct mtget *)mt_status);
14       int ioctl(int fd, MTIOCPOS, (struct mtpos *)mt_pos);
15

DESCRIPTION

17       The st driver provides the interface to a variety of SCSI tape devices.
18       Currently, the driver takes control of all  detected  devices  of  type
19       “sequential-access”.  The st driver uses major device number 9.
20
21       Each  device  uses eight minor device numbers.  The lowermost five bits
22       in the minor numbers are assigned sequentially in the order  of  detec‐
23       tion.   In  the 2.6 kernel, the bits above the eight lowermost bits are
24       concatenated to the five lowermost bits to form the tape  number.   The
25       minor numbers can be grouped into two sets of four numbers: the princi‐
26       pal (auto-rewind) minor device numbers, n, and the  “no-rewind”  device
27       numbers,  (n  + 128).  Devices opened using the principal device number
28       will be sent a REWIND command when they  are  closed.   Devices  opened
29       using  the  “no-rewind”  device  number  will not.  (Note that using an
30       auto-rewind device for positioning the tape with, for instance, mt does
31       not  lead  to the desired result: the tape is rewound after the mt com‐
32       mand and the next command starts from the beginning of the tape).
33
34       Within each group, four minor numbers are available to  define  devices
35       with different characteristics (block size, compression, density, etc.)
36       When the system starts up, only the first  device  is  available.   The
37       other  three are activated when the default characteristics are defined
38       (see below).  (By changing compile-time constants, it  is  possible  to
39       change  the  balance  between the maximum number of tape drives and the
40       number of minor numbers for each drive.  The default allocation  allows
41       control  of 32 tape drives.  For instance, it is possible to control up
42       to 64 tape drives with two minor numbers for different options.)
43
44       Devices are typically created by:
45
46           mknod -m 666 /dev/st0 c 9 0
47           mknod -m 666 /dev/st0l c 9 32
48           mknod -m 666 /dev/st0m c 9 64
49           mknod -m 666 /dev/st0a c 9 96
50           mknod -m 666 /dev/nst0 c 9 128
51           mknod -m 666 /dev/nst0l c 9 160
52           mknod -m 666 /dev/nst0m c 9 192
53           mknod -m 666 /dev/nst0a c 9 224
54
55       There is no corresponding block device.
56
57       The driver uses an internal buffer that has to be large enough to  hold
58       at  least  one  tape  block.   In kernels before 2.1.121, the buffer is
59       allocated as one contiguous block.  This limits the block size  to  the
60       largest  contiguous  block  of memory the kernel allocator can provide.
61       The limit is currently 128 kB for 32-bit architectures and  256 kB  for
62       64-bit architectures.  In newer kernels the driver allocates the buffer
63       in several parts if necessary.  By default, the maximum number of parts
64       is  16.   This means that the maximum block size is very large (2 MB if
65       allocation of 16 blocks of 128 kB succeeds).
66
67       The driver's internal buffer size is determined by a compile-time  con‐
68       stant  which  can be overridden with a kernel startup option.  In addi‐
69       tion to this, the driver tries to allocate a larger temporary buffer at
70       run  time if necessary.  However, run-time allocation of large contigu‐
71       ous blocks of memory may fail and it is advisable not to rely too  much
72       on  dynamic  buffer  allocation  with  kernels older than 2.1.121 (this
73       applies also to demand-loading the driver with kerneld or kmod).
74
75       The driver does not specifically support any tape drive brand or model.
76       After  system start-up the tape device options are defined by the drive
77       firmware.  For example, if the drive firmware selects fixed-block mode,
78       the tape device uses fixed-block mode.  The options can be changed with
79       explicit ioctl(2) calls and remain in effect when the device is  closed
80       and reopened.  Setting the options affects both the auto-rewind and the
81       nonrewind device.
82
83       Different options can be specified for the different devices within the
84       subgroup  of  four.  The options take effect when the device is opened.
85       For example, the system administrator can define one device that writes
86       in  fixed-block mode with a certain block size, and one which writes in
87       variable-block mode (if the drive supports both modes).
88
89       The driver supports tape partitions if they are supported by the drive.
90       (Note that the tape partitions have nothing to do with disk partitions.
91       A partitioned tape can be seen as  several  logical  tapes  within  one
92       medium.)   Partition  support  has to be enabled with an ioctl(2).  The
93       tape location is  preserved  within  each  partition  across  partition
94       changes.  The partition used for subsequent tape operations is selected
95       with an ioctl(2).  The partition switch is executed together  with  the
96       next  tape  operation in order to avoid unnecessary tape movement.  The
97       maximum number of partitions on a tape is  defined  by  a  compile-time
98       constant  (originally  four).  The driver contains an ioctl(2) that can
99       format a tape with either one or two partitions.
100
101       Device /dev/tape is usually created as a  hard  or  soft  link  to  the
102       default tape device on the system.
103
104       Starting  from  kernel 2.6.2, the driver exports in the sysfs directory
105       /sys/class/scsi_tape the attached devices and some parameters  assigned
106       to the devices.
107
108   Data transfer
109       The  driver  supports  operation in both fixed-block mode and variable-
110       block mode (if supported by the drive).  In fixed-block mode the  drive
111       writes blocks of the specified size and the block size is not dependent
112       on the byte counts of the write system calls.  In  variable-block  mode
113       one tape block is written for each write call and the byte count deter‐
114       mines the size of the corresponding tape block.  Note that  the  blocks
115       on  the tape don't contain any information about the writing mode: when
116       reading, the only important thing is to use commands  that  accept  the
117       block sizes on the tape.
118
119       In  variable-block  mode the read byte count does not have to match the
120       tape block size exactly.  If the byte count is  larger  than  the  next
121       block on tape, the driver returns the data and the function returns the
122       actual block size.  If the block size is larger than the byte count, an
123       error is returned.
124
125       In  fixed-block mode the read byte counts can be arbitrary if buffering
126       is enabled, or a multiple of the tape block size if buffering  is  dis‐
127       abled.   Kernels  before 2.1.121 allow writes with arbitrary byte count
128       if buffering is enabled.  In all other  cases  (kernel  before  2.1.121
129       with buffering disabled or newer kernel) the write byte count must be a
130       multiple of the tape block size.
131
132       In the 2.6 kernel, the driver tries to use direct transfers between the
133       user  buffer  and  the  device.   If this is not possible, the driver's
134       internal buffer is used.  The reasons for not  using  direct  transfers
135       include improper alignment of the user buffer (default is 512 bytes but
136       this can be changed by the HBA driver), one or more pages of  the  user
137       buffer not reachable by the SCSI adapter, and so on.
138
139       A  filemark is automatically written to tape if the last tape operation
140       before close was a write.
141
142       When a filemark is encountered while reading,  the  following  happens.
143       If  there  are data remaining in the buffer when the filemark is found,
144       the buffered data is returned.  The next read returns zero bytes.   The
145       following  read  returns  data from the next file.  The end of recorded
146       data is signaled by returning  zero  bytes  for  two  consecutive  read
147       calls.  The third read returns an error.
148
149   Ioctls
150       The  driver  supports three ioctl(2) requests.  Requests not recognized
151       by the st driver are passed to the SCSI driver.  The definitions  below
152       are from /usr/include/linux/mtio.h:
153
154   MTIOCTOP — perform a tape operation
155       This request takes an argument of type (struct mtop *).  Not all drives
156       support all operations.  The driver returns an EIO error if  the  drive
157       rejects an operation.
158
159           /* Structure for MTIOCTOP - mag tape op command: */
160           struct mtop {
161               short   mt_op;       /* operations defined below */
162               int     mt_count;    /* how many of them */
163           };
164
165       Magnetic Tape operations for normal tape use:
166
167       MTBSF         Backward space over mt_count filemarks.
168
169       MTBSFM        Backward  space  over mt_count filemarks.  Reposition the
170                     tape to the EOT side of the last filemark.
171
172       MTBSR         Backward space over mt_count records (tape blocks).
173
174       MTBSS         Backward space over mt_count setmarks.
175
176       MTCOMPRESSION Enable compression of  tape  data  within  the  drive  if
177                     mt_count  is  nonzero and disable compression if mt_count
178                     is zero.  This command uses the MODE page 15 supported by
179                     most DATs.
180
181       MTEOM         Go  to  the  end  of  the  recorded  media (for appending
182                     files).
183
184       MTERASE       Erase tape.  With 2.6  kernel,  short  erase  (mark  tape
185                     empty)  is performed if the argument is zero.  Otherwise,
186                     long erase (erase all) is done.
187
188       MTFSF         Forward space over mt_count filemarks.
189
190       MTFSFM        Forward space over mt_count  filemarks.   Reposition  the
191                     tape to the BOT side of the last filemark.
192
193       MTFSR         Forward space over mt_count records (tape blocks).
194
195       MTFSS         Forward space over mt_count setmarks.
196
197       MTLOAD        Execute  the SCSI load command.  A special case is avail‐
198                     able for some HP autoloaders.  If mt_count  is  the  con‐
199                     stant  MT_ST_HPLOADER_OFFSET plus a number, the number is
200                     sent to the drive to control the autoloader.
201
202       MTLOCK        Lock the tape drive door.
203
204       MTMKPART      Format the tape into one or two partitions.  If  mt_count
205                     is  positive, it gives the size of partition 1 and parti‐
206                     tion 0 contains the rest of the  tape.   If  mt_count  is
207                     zero,  the  tape  is  formatted into one partition.  From
208                     kernel version 4.6, a  negative  mt_count  specifies  the
209                     size  of  partition  0  and the rest of the tape contains
210                     partition 1.  The physical ordering of partitions depends
211                     on  the  drive.   This command is not allowed for a drive
212                     unless the partition support is  enabled  for  the  drive
213                     (see MT_ST_CAN_PARTITIONS below).
214
215       MTNOP         No  op—flushes  the  driver's  buffer  as  a side effect.
216                     Should be used before reading status with MTIOCGET.
217
218       MTOFFL        Rewind and put the drive off line.
219
220       MTRESET       Reset drive.
221
222       MTRETEN       Re-tension tape.
223
224       MTREW         Rewind.
225
226       MTSEEK        Seek to the tape  block  number  specified  in  mt_count.
227                     This  operation  requires either a SCSI-2 drive that sup‐
228                     ports the LOCATE command (device-specific address)  or  a
229                     Tandberg-compatible   SCSI-1   drive  (Tandberg,  Archive
230                     Viper, Wangtek, ...).  The block  number  should  be  one
231                     that  was  previously returned by MTIOCPOS if device-spe‐
232                     cific addresses are used.
233
234       MTSETBLK      Set the drive's block length to the  value  specified  in
235                     mt_count.  A block length of zero sets the drive to vari‐
236                     able block size mode.
237
238       MTSETDENSITY  Set the tape density to the code in mt_count.   The  den‐
239                     sity  codes  supported  by  a drive can be found from the
240                     drive documentation.
241
242       MTSETPART     The active partition is switched to mt_count.  The parti‐
243                     tions  are  numbered  from  zero.   This  command  is not
244                     allowed for a  drive  unless  the  partition  support  is
245                     enabled for the drive (see MT_ST_CAN_PARTITIONS below).
246
247       MTUNLOAD      Execute  the  SCSI  unload  command  (does  not eject the
248                     tape).
249
250       MTUNLOCK      Unlock the tape drive door.
251
252       MTWEOF        Write mt_count filemarks.
253
254       MTWSM         Write mt_count setmarks.
255
256       Magnetic Tape operations for setting of device options  (by  the  supe‐
257       ruser):
258
259       MTSETDRVBUFFER
260               Set  various drive and driver options according to bits encoded
261               in mt_count.  These consist of the drive's  buffering  mode,  a
262               set  of  Boolean  driver  options,  the buffer write threshold,
263               defaults for the block size and density, and timeouts (only  in
264               kernels 2.1 and later).  A single operation can affect only one
265               item in the list above (the Booleans counted as one item.)
266
267               A value having zeros in the high-order 4 bits will be  used  to
268               set the drive's buffering mode.  The buffering modes are:
269
270                   0   The drive will not report GOOD status on write commands
271                       until the data  blocks  are  actually  written  to  the
272                       medium.
273
274                   1   The  drive  may report GOOD status on write commands as
275                       soon as all  the  data  has  been  transferred  to  the
276                       drive's internal buffer.
277
278                   2   The  drive  may report GOOD status on write commands as
279                       soon as (a) all the data has been  transferred  to  the
280                       drive's internal buffer, and (b) all buffered data from
281                       different initiators has been successfully  written  to
282                       the medium.
283
284               To  control  the  write  threshold  the  value in mt_count must
285               include the constant MT_ST_WRITE_THRESHOLD bitwise ORed with  a
286               block  count  in  the  low  28 bits.  The block count refers to
287               1024-byte blocks, not the physical block size on the tape.  The
288               threshold  cannot exceed the driver's internal buffer size (see
289               DESCRIPTION, above).
290
291               To set and clear the Boolean options the value in mt_count must
292               include one of the constants MT_ST_BOOLEANS, MT_ST_SETBOOLEANS,
293               MT_ST_CLEARBOOLEANS, or  MT_ST_DEFBOOLEANS  bitwise  ORed  with
294               whatever  combination  of  the  following  options  is desired.
295               Using MT_ST_BOOLEANS the options  can  be  set  to  the  values
296               defined  in the corresponding bits.  With MT_ST_SETBOOLEANS the
297               options can  be  selectively  set  and  with  MT_ST_DEFBOOLEANS
298               selectively cleared.
299
300               The  default  options for a tape device are set with MT_ST_DEF‐
301               BOOLEANS.  A nonactive tape device (e.g., device with minor  32
302               or  160)  is  activated  when  the  default  options for it are
303               defined the first time.  An activated device inherits from  the
304               device activated at start-up the options not set explicitly.
305
306               The Boolean options are:
307
308               MT_ST_BUFFER_WRITES (Default: true)
309                      Buffer  all  write  operations  in fixed-block mode.  If
310                      this option is false and the drive uses  a  fixed  block
311                      size,  then  all write operations must be for a multiple
312                      of the block size.  This option must  be  set  false  to
313                      write reliable multivolume archives.
314
315               MT_ST_ASYNC_WRITES (Default: true)
316                      When  this option is true, write operations return imme‐
317                      diately without waiting for the data to  be  transferred
318                      to  the drive if the data fits into the driver's buffer.
319                      The write threshold determines how full the buffer  must
320                      be  before  a  new  SCSI  write  command is issued.  Any
321                      errors reported by the drive will be held until the next
322                      operation.  This option must be set false to write reli‐
323                      able multivolume archives.
324
325               MT_ST_READ_AHEAD (Default: true)
326                      This option causes the driver to provide read  buffering
327                      and  read-ahead  in fixed-block mode.  If this option is
328                      false and the drive uses a fixed block  size,  then  all
329                      read  operations  must  be  for  a multiple of the block
330                      size.
331
332               MT_ST_TWO_FM (Default: false)
333                      This option modifies the driver behavior when a file  is
334                      closed.   The  normal  action is to write a single file‐
335                      mark.  If the option is true, the driver will write  two
336                      filemarks and backspace over the second one.
337
338                      Note:  This  option  should not be set true for QIC tape
339                      drives since they are unable to  overwrite  a  filemark.
340                      These  drives detect the end of recorded data by testing
341                      for blank tape rather than  two  consecutive  filemarks.
342                      Most  other  current  drives  also  detect  the  end  of
343                      recorded data and using two filemarks is usually  neces‐
344                      sary  only when interchanging tapes with some other sys‐
345                      tems.
346
347               MT_ST_DEBUGGING (Default: false)
348                      This option turns on various debugging messages from the
349                      driver  (effective  only if the driver was compiled with
350                      DEBUG defined nonzero).
351
352               MT_ST_FAST_EOM (Default: false)
353                      This option  causes  the  MTEOM  operation  to  be  sent
354                      directly to the drive, potentially speeding up the oper‐
355                      ation but causing the driver to lose track of  the  cur‐
356                      rent  file  number  normally  returned  by  the MTIOCGET
357                      request.  If MT_ST_FAST_EOM is false,  the  driver  will
358                      respond  to  an  MTEOM  request  by forward spacing over
359                      files.
360
361               MT_ST_AUTO_LOCK (Default: false)
362                      When this option is true, the drive door is locked  when
363                      the device is opened and unlocked when it is closed.
364
365               MT_ST_DEF_WRITES (Default: false)
366                      The  tape  options (block size, mode, compression, etc.)
367                      may change when changing from one  device  linked  to  a
368                      drive to another device linked to the same drive depend‐
369                      ing on how the devices are defined.  This option defines
370                      when  the changes are enforced by the driver using SCSI-
371                      commands and when the drives auto-detection capabilities
372                      are  relied  upon.   If this option is false, the driver
373                      sends the SCSI-commands immediately when the  device  is
374                      changed.   If  the option is true, the SCSI-commands are
375                      not sent until a write is requested.  In this case,  the
376                      drive  firmware  is allowed to detect the tape structure
377                      when reading and the SCSI-commands are used only to make
378                      sure  that  a  tape  is written according to the correct
379                      specification.
380
381               MT_ST_CAN_BSR (Default: false)
382                      When read-ahead is used,  the  tape  must  sometimes  be
383                      spaced  backward to the correct position when the device
384                      is closed and the SCSI command to  space  backward  over
385                      records  is  used  for  this purpose.  Some older drives
386                      can't process this command reliably and this option  can
387                      be  used  to instruct the driver not to use the command.
388                      The end result is that, with read-ahead and  fixed-block
389                      mode,  the tape may not be correctly positioned within a
390                      file when the device is closed.  With  2.6  kernel,  the
391                      default is true for drives supporting SCSI-3.
392
393               MT_ST_NO_BLKLIMS (Default: false)
394                      Some drives don't accept the READ BLOCK LIMITS SCSI com‐
395                      mand.  If this is used, the driver does not use the com‐
396                      mand.   The  drawback  is  that  the  driver can't check
397                      before sending commands if the selected  block  size  is
398                      acceptable to the drive.
399
400               MT_ST_CAN_PARTITIONS (Default: false)
401                      This  option  enables  support  for  several  partitions
402                      within a tape.  The option applies to all devices linked
403                      to a drive.
404
405               MT_ST_SCSI2LOGICAL (Default: false)
406                      This  option  instructs  the  driver  to use the logical
407                      block addresses defined in the SCSI-2 standard when per‐
408                      forming  the  seek and tell operations (both with MTSEEK
409                      and MTIOCPOS commands and when changing tape partition).
410                      Otherwise,  the  device-specific addresses are used.  It
411                      is highly advisable to set this option if the drive sup‐
412                      ports  the  logical  addresses  because  they count also
413                      filemarks.  There are some drives that support only  the
414                      logical block addresses.
415
416               MT_ST_SYSV (Default: false)
417                      When  this  option  is enabled, the tape devices use the
418                      SystemV semantics.  Otherwise,  the  BSD  semantics  are
419                      used.   The most important difference between the seman‐
420                      tics is what happens when a device used for  reading  is
421                      closed: in System V semantics the tape is spaced forward
422                      past the next filemark if this has  not  happened  while
423                      using the device.  In BSD semantics the tape position is
424                      not changed.
425
426               MT_NO_WAIT (Default: false)
427                      Enables immediate mode (i.e., don't wait for the command
428                      to finish) for some commands (e.g., rewind).
429
430               An example:
431
432                   struct mtop mt_cmd;
433                   mt_cmd.mt_op = MTSETDRVBUFFER;
434                   mt_cmd.mt_count = MT_ST_BOOLEANS |
435                           MT_ST_BUFFER_WRITES | MT_ST_ASYNC_WRITES;
436                   ioctl(fd, MTIOCTOP, mt_cmd);
437
438               The   default   block  size  for  a  device  can  be  set  with
439               MT_ST_DEF_BLKSIZE and the default density code can be set  with
440               MT_ST_DEFDENSITY.  The values for the parameters are or'ed with
441               the operation code.
442
443               With kernels 2.1.x and later, the timeout  values  can  be  set
444               with  the subcommand MT_ST_SET_TIMEOUT ORed with the timeout in
445               seconds.  The long timeout (used for rewinds and other commands
446               that may take a long time) can be set with MT_ST_SET_LONG_TIME‐
447               OUT.  The kernel defaults are very long to  make  sure  that  a
448               successful command is not timed out with any drive.  Because of
449               this, the driver may seem stuck even if it is only waiting  for
450               the  timeout.  These commands can be used to set more practical
451               values for a specific drive.  The timeouts set for  one  device
452               apply for all devices linked to the same drive.
453
454               Starting  from kernels 2.4.19 and 2.5.43, the driver supports a
455               status bit which indicates whether the drive requests cleaning.
456               The  method used by the drive to return cleaning information is
457               set using the MT_ST_SEL_CLN subcommand.  If the value is  zero,
458               the  cleaning  bit  is  always  zero.  If the value is one, the
459               TapeAlert data defined in the SCSI-3 standard is used (not  yet
460               implemented).   Values  2–17 are reserved.  If the lowest eight
461               bits are >= 18, bits from the extended  sense  data  are  used.
462               The  bits 9–16 specify a mask to select the bits to look at and
463               the bits 17–23 specify the bit pattern to look for.  If the bit
464               pattern  is  zero, one or more bits under the mask indicate the
465               cleaning request.  If the pattern is nonzero, the pattern  must
466               match the masked sense data byte.
467
468   MTIOCGET — get status
469       This request takes an argument of type (struct mtget *).
470
471           /* structure for MTIOCGET - mag tape get status command */
472           struct mtget {
473               long     mt_type;
474               long     mt_resid;
475               /* the following registers are device dependent */
476               long     mt_dsreg;
477               long     mt_gstat;
478               long     mt_erreg;
479               /* The next two fields are not always used */
480               daddr_t  mt_fileno;
481               daddr_t  mt_blkno;
482           };
483
484       mt_type    The  header  file  defines  many values for mt_type, but the
485                  current driver reports only  the  generic  types  MT_ISSCSI1
486                  (Generic SCSI-1 tape) and MT_ISSCSI2 (Generic SCSI-2 tape).
487
488       mt_resid   contains the current tape partition number.
489
490       mt_dsreg   reports  the drive's current settings for block size (in the
491                  low 24 bits) and density (in the high 8 bits).  These fields
492                  are   defined  by  MT_ST_BLKSIZE_SHIFT,  MT_ST_BLKSIZE_MASK,
493                  MT_ST_DENSITY_SHIFT, and MT_ST_DENSITY_MASK.
494
495       mt_gstat   reports generic  (device  independent)  status  information.
496                  The  header  file  defines  macros  for testing these status
497                  bits:
498
499                  GMT_EOF(x): The tape is positioned  just  after  a  filemark
500                      (always false after an MTSEEK operation).
501
502                  GMT_BOT(x):  The  tape is positioned at the beginning of the
503                      first file (always false after an MTSEEK operation).
504
505                  GMT_EOT(x): A tape operation has reached the physical End Of
506                      Tape.
507
508                  GMT_SM(x):  The  tape  is  currently positioned at a setmark
509                      (always false after an MTSEEK operation).
510
511                  GMT_EOD(x): The tape is positioned at the  end  of  recorded
512                      data.
513
514                  GMT_WR_PROT(x):  The  drive  is  write-protected.   For some
515                      drives this can also mean that the drive does  not  sup‐
516                      port writing on the current medium type.
517
518                  GMT_ONLINE(x):  The last open(2) found the drive with a tape
519                      in place and ready for operation.
520
521                  GMT_D_6250(x), GMT_D_1600(x), GMT_D_800(x):  This  “generic”
522                      status  information  reports the current density setting
523                      for 9-track ½" tape drives only.
524
525                  GMT_DR_OPEN(x): The drive does not have a tape in place.
526
527                  GMT_IM_REP_EN(x): Immediate report mode.  This bit is set if
528                      there  are  no  guarantees that the data has been physi‐
529                      cally written to the tape when the write  call  returns.
530                      It is set zero only when the driver does not buffer data
531                      and the drive is set not to buffer data.
532
533                  GMT_CLN(x): The drive has requested  cleaning.   Implemented
534                      in kernels since 2.4.19 and 2.5.43.
535
536       mt_erreg   The  only  field  defined in mt_erreg is the recovered error
537                  count in the low 16 bits (as defined by  MT_ST_SOFTERR_SHIFT
538                  and  MT_ST_SOFTERR_MASK.   Due to inconsistencies in the way
539                  drives report recovered errors,  this  count  is  often  not
540                  maintained (most drives do not by default report soft errors
541                  but this can be changed with a SCSI MODE SELECT command).
542
543       mt_fileno  reports the current file number (zero-based).  This value is
544                  set to -1 when the file number is unknown (e.g., after MTBSS
545                  or MTSEEK).
546
547       mt_blkno   reports the block number  (zero-based)  within  the  current
548                  file.   This  value  is  set  to -1 when the block number is
549                  unknown (e.g., after MTBSF, MTBSS, or MTSEEK).
550
551   MTIOCPOS — get tape position
552       This request takes an argument of type (struct mtpos *) and reports the
553       drive's  notion of the current tape block number, which is not the same
554       as mt_blkno returned by MTIOCGET.  This drive must be  a  SCSI-2  drive
555       that  supports the READ POSITION command (device-specific address) or a
556       Tandberg-compatible SCSI-1 drive (Tandberg, Archive Viper, Wangtek, ...
557       ).
558
559           /* structure for MTIOCPOS - mag tape get position command */
560           struct mtpos {
561               long mt_blkno;    /* current block number */
562           };
563

RETURN VALUE

565       EACCES        An attempt was made to write or erase a write-pro‐
566                     tected tape.  (This error is not  detected  during
567                     open(2).)
568
569       EBUSY         The  device  is  already  in use or the driver was
570                     unable to allocate a buffer.
571
572       EFAULT        The command parameters point to memory not belong‐
573                     ing to the calling process.
574
575       EINVAL        An   ioctl(2)   had  an  invalid  argument,  or  a
576                     requested block size was invalid.
577
578       EIO           The requested operation could not be completed.
579
580       ENOMEM        The byte count in read(2) is smaller than the next
581                     physical  block  on  the tape.  (Before 2.2.18 and
582                     2.4.0-test6 the extra  bytes  have  been  silently
583                     ignored.)
584
585       ENOSPC        A  write  operation could not be completed because
586                     the tape reached end-of-medium.
587
588       ENOSYS        Unknown ioctl(2).
589
590       ENXIO         During opening, the tape device does not exist.
591
592       EOVERFLOW     An attempt was made to read or write  a  variable-
593                     length  block  that  is  larger  than the driver's
594                     internal buffer.
595
596       EROFS         Open is attempted with O_WRONLY or O_RDWR when the
597                     tape in the drive is write-protected.
598

FILES

600       /dev/st*
601              the auto-rewind SCSI tape devices
602
603       /dev/nst*
604              the nonrewind SCSI tape devices
605

NOTES

607       1.  When  exchanging  data between systems, both systems have to
608           agree on the physical tape block size.  The parameters of  a
609           drive  after  startup  are often not the ones most operating
610           systems use with these devices.  Most systems use drives  in
611           variable-block  mode  if the drive supports that mode.  This
612           applies to most modern drives, including DATs,  8mm  helical
613           scan  drives,  DLTs,  etc.  It may be advisable to use these
614           drives in variable-block  mode  also  in  Linux  (i.e.,  use
615           MTSETBLK  or MTSETDEFBLK at system startup to set the mode),
616           at least when exchanging data with a  foreign  system.   The
617           drawback  of this is that a fairly large tape block size has
618           to be used to get acceptable data transfer rates on the SCSI
619           bus.
620
621       2.  Many  programs  (e.g., tar(1)) allow the user to specify the
622           blocking factor on the command line.  Note that this  deter‐
623           mines the physical block size on tape only in variable-block
624           mode.
625
626       3.  In order to use SCSI tape drives, the basic SCSI  driver,  a
627           SCSI-adapter  driver and the SCSI tape driver must be either
628           configured into the kernel or loaded  as  modules.   If  the
629           SCSI-tape driver is not present, the drive is recognized but
630           the tape support described in this page is not available.
631
632       4.  The driver writes error messages to  the  console/log.   The
633           SENSE  codes  written  into  some messages are automatically
634           translated to text if verbose SCSI messages are  enabled  in
635           kernel configuration.
636
637       5.  The  driver's  internal  buffering allows good throughput in
638           fixed-block mode also with small read(2) and  write(2)  byte
639           counts.   With direct transfers this is not possible and may
640           cause a surprise when moving to the 2.6 kernel.   The  solu‐
641           tion  is to tell the software to use larger transfers (often
642           telling it to use larger blocks).  If this is not  possible,
643           direct transfers can be disabled.
644

SEE ALSO

646       mt(1)
647
648       The  file  drivers/scsi/README.st  or  Documentation/scsi/st.txt
649       (kernel >= 2.6) in the Linux kernel  source  tree  contains  the
650       most  recent  information about the driver and its configuration
651       possibilities
652

COLOPHON

654       This page is  part  of  release  4.16  of  the  Linux  man-pages
655       project.   A  description  of  the  project,  information  about
656       reporting bugs, and the latest version  of  this  page,  can  be
657       found at https://www.kernel.org/doc/man-pages/.
658
659
660
661Linux                             2017-09-15                             ST(4)
Impressum