1st(4)                      Kernel Interfaces 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 us‐
29       ing  the “no-rewind” device number will not.  (Note that using an auto-
30       rewind device for positioning the tape with, for instance, mt does  not
31       lead  to  the  desired result: the tape is rewound after the mt command
32       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.  Before Linux 2.1.121, the buffer is allocated
59       as one contiguous block.  This limits the block  size  to  the  largest
60       contiguous block of memory the kernel allocator can provide.  The limit
61       is currently 128 kB for 32-bit architectures and 256 kB for 64-bit  ar‐
62       chitectures.   In newer kernels the driver allocates the buffer in sev‐
63       eral parts if necessary.  By default, the maximum number  of  parts  is
64       16.   This means that the maximum block size is very large (2 MB if al‐
65       location 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 before Linux 2.1.121 (this applies also to
73       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  de‐
102       fault tape device on the system.
103
104       Starting  from  Linux  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.   Before Linux 2.1.121 allow writes with arbitrary byte count if
128       buffering is enabled.  In all other cases (before  Linux  2.1.121  with
129       buffering disabled or newer kernel) the write byte count must be a mul‐
130       tiple of the tape block size.
131
132       In Linux 2.6, the driver tries to use direct transfers between the user
133       buffer  and the device.  If this is not possible, the driver's internal
134       buffer is used.  The reasons for not using direct transfers include im‐
135       proper  alignment of the user buffer (default is 512 bytes but this can
136       be changed by the HBA driver), one or more pages of the user buffer not
137       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 tape to
170              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
177              Enable compression of tape data within the drive if mt_count  is
178              nonzero  and disable compression if mt_count is zero.  This com‐
179              mand uses the MODE page 15 supported by most DATs.
180
181       MTEOM  Go to the end of the recorded media (for appending files).
182
183       MTERASE
184              Erase tape.  With Linux 2.6, short erase (mark  tape  empty)  is
185              performed if the argument is zero.  Otherwise, long erase (erase
186              all) is done.
187
188       MTFSF  Forward space over mt_count filemarks.
189
190       MTFSFM Forward space over mt_count filemarks.  Reposition the  tape  to
191              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 available for
198              some   HP   autoloaders.    If   mt_count   is   the    constant
199              MT_ST_HPLOADER_OFFSET  plus  a number, the number is sent to the
200              drive to control the autoloader.
201
202       MTLOCK Lock the tape drive door.
203
204       MTMKPART
205              Format the tape into one or two partitions.  If mt_count is pos‐
206              itive, it gives the size of partition 1 and partition 0 contains
207              the rest of the tape.  If mt_count is zero, the tape is  format‐
208              ted  into  one  partition.   From Linux 4.6, a negative mt_count
209              specifies the size of partition 0 and the rest of the tape  con‐
210              tains  partition 1.  The physical ordering of partitions depends
211              on the drive.  This command is not allowed for  a  drive  unless
212              the   partition   support   is   enabled   for  the  drive  (see
213              MT_ST_CAN_PARTITIONS below).
214
215       MTNOP  No op—flushes the driver's buffer as a side effect.   Should  be
216              used before reading status with MTIOCGET.
217
218       MTOFFL Rewind and put the drive off line.
219
220       MTRESET
221              Reset drive.
222
223       MTRETEN
224              Re-tension tape.
225
226       MTREW  Rewind.
227
228       MTSEEK Seek to the tape block number specified in mt_count.  This oper‐
229              ation requires either a SCSI-2 drive that  supports  the  LOCATE
230              command   (device-specific  address)  or  a  Tandberg-compatible
231              SCSI-1 drive (Tandberg, Archive Viper, Wangtek, ...).  The block
232              number should be one that was previously returned by MTIOCPOS if
233              device-specific addresses are used.
234
235       MTSETBLK
236              Set the drive's block length to the value specified in mt_count.
237              A  block  length  of  zero sets the drive to variable block size
238              mode.
239
240       MTSETDENSITY
241              Set the tape density to the code in mt_count.  The density codes
242              supported by a drive can be found from the drive documentation.
243
244       MTSETPART
245              The  active  partition  is switched to mt_count.  The partitions
246              are numbered from zero.  This command is not allowed for a drive
247              unless  the  partition  support  is  enabled  for the drive (see
248              MT_ST_CAN_PARTITIONS below).
249
250       MTUNLOAD
251              Execute the SCSI unload command (does not eject the tape).
252
253       MTUNLOCK
254              Unlock the tape drive door.
255
256       MTWEOF Write mt_count filemarks.
257
258       MTWSM  Write mt_count setmarks.
259
260       Magnetic tape operations for setting of device options  (by  the  supe‐
261       ruser):
262
263       MTSETDRVBUFFER
264              Set  various  drive and driver options according to bits encoded
265              in mt_count.  These consist of the drive's buffering mode, a set
266              of  Boolean driver options, the buffer write threshold, defaults
267              for the block size and density, and timeouts (only  since  Linux
268              2.1).   A  single operation can affect only one item in the list
269              below (the Booleans counted as one item.)
270
271              A value having zeros in the high-order 4 bits will  be  used  to
272              set the drive's buffering mode.  The buffering modes are:
273
274              0      The  drive  will not report GOOD status on write commands
275                     until the data blocks are actually written to the medium.
276
277              1      The drive may report GOOD status  on  write  commands  as
278                     soon  as all the data has been transferred to the drive's
279                     internal buffer.
280
281              2      The drive may report GOOD status  on  write  commands  as
282                     soon  as  (a)  all  the  data has been transferred to the
283                     drive's internal buffer, and (b) all buffered  data  from
284                     different initiators has been successfully written to the
285                     medium.
286
287              To control the write threshold the value in  mt_count  must  in‐
288              clude  the  constant  MT_ST_WRITE_THRESHOLD  bitwise ORed with a
289              block count in the low 28  bits.   The  block  count  refers  to
290              1024-byte  blocks, not the physical block size on the tape.  The
291              threshold cannot exceed the driver's internal buffer  size  (see
292              DESCRIPTION, above).
293
294              To  set and clear the Boolean options the value in mt_count must
295              include one of the constants MT_ST_BOOLEANS,  MT_ST_SETBOOLEANS,
296              MT_ST_CLEARBOOLEANS,  or  MT_ST_DEFBOOLEANS  bitwise  ORed  with
297              whatever combination of the following options is desired.  Using
298              MT_ST_BOOLEANS  the  options can be set to the values defined in
299              the corresponding bits.  With MT_ST_SETBOOLEANS the options  can
300              be   selectively  set  and  with  MT_ST_DEFBOOLEANS  selectively
301              cleared.
302
303              The default options for a tape device are  set  with  MT_ST_DEF‐
304              BOOLEANS.   A  nonactive tape device (e.g., device with minor 32
305              or 160) is activated when the default options for it are defined
306              the  first  time.   An activated device inherits from the device
307              activated at start-up the options not set explicitly.
308
309              The Boolean options are:
310
311              MT_ST_BUFFER_WRITES (Default: true)
312                     Buffer all write operations in fixed-block mode.  If this
313                     option  is  false  and the drive uses a fixed block size,
314                     then all write operations must be for a multiple  of  the
315                     block size.  This option must be set false to write reli‐
316                     able multivolume archives.
317
318              MT_ST_ASYNC_WRITES (Default: true)
319                     When this option is true, write operations return immedi‐
320                     ately  without  waiting for the data to be transferred to
321                     the drive if the data fits into the driver's buffer.  The
322                     write  threshold  determines  how full the buffer must be
323                     before a new SCSI write command is  issued.   Any  errors
324                     reported  by the drive will be held until the next opera‐
325                     tion.  This option must be set false  to  write  reliable
326                     multivolume archives.
327
328              MT_ST_READ_AHEAD (Default: true)
329                     This  option  causes the driver to provide read buffering
330                     and read-ahead in fixed-block mode.  If  this  option  is
331                     false  and  the  drive  uses a fixed block size, then all
332                     read operations must be for a multiple of the block size.
333
334              MT_ST_TWO_FM (Default: false)
335                     This option modifies the driver behavior when a  file  is
336                     closed.  The normal action is to write a single filemark.
337                     If the option is true, the driver will  write  two  file‐
338                     marks and backspace over the second one.
339
340                     Note:  This  option  should  not be set true for QIC tape
341                     drives since they are unable  to  overwrite  a  filemark.
342                     These  drives  detect the end of recorded data by testing
343                     for blank tape rather  than  two  consecutive  filemarks.
344                     Most other current drives also detect the end of recorded
345                     data and using two filemarks is  usually  necessary  only
346                     when interchanging tapes with some other systems.
347
348              MT_ST_DEBUGGING (Default: false)
349                     This  option turns on various debugging messages from the
350                     driver (effective only if the driver  was  compiled  with
351                     DEBUG defined nonzero).
352
353              MT_ST_FAST_EOM (Default: false)
354                     This  option  causes  the  MTEOM operation to be sent di‐
355                     rectly to the drive, potentially speeding up  the  opera‐
356                     tion  but causing the driver to lose track of the current
357                     file number normally returned by  the  MTIOCGET  request.
358                     If MT_ST_FAST_EOM is false, the driver will respond to an
359                     MTEOM request by forward spacing over files.
360
361              MT_ST_AUTO_LOCK (Default: false)
362                     When this option is true, the drive door is  locked  when
363                     the device file 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 Linux 2.6, the  de‐
391                     fault 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 before
397                     sending commands if the selected block size is acceptable
398                     to the drive.
399
400              MT_ST_CAN_PARTITIONS (Default: false)
401                     This option enables support for several partitions within
402                     a tape.  The option applies to all devices  linked  to  a
403                     drive.
404
405              MT_ST_SCSI2LOGICAL (Default: false)
406                     This option instructs the driver to use the logical block
407                     addresses defined in the SCSI-2 standard when  performing
408                     the seek and tell operations (both with MTSEEK and MTIOC‐
409                     POS commands and when changing tape  partition).   Other‐
410                     wise,  the  device-specific  addresses  are  used.  It is
411                     highly advisable to set this option if the drive supports
412                     the  logical addresses because they count also filemarks.
413                     There are some drives that support only the logical block
414                     addresses.
415
416              MT_ST_SYSV (Default: false)
417                     When  this  option  is  enabled, the tape devices use the
418                     System V 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 us‐
423                     ing  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 Linux 2.1.x and later, the timeout values can be  set  with
444              the  subcommand  MT_ST_SET_TIMEOUT ORed with the timeout in sec‐
445              onds.  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 suc‐
448              cessful  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 Linux 2.4.19 and Linux 2.5.43, the driver supports
455              a status bit which indicates whether the drive  requests  clean‐
456              ing.   The  method used by the drive to return cleaning informa‐
457              tion is set using the MT_ST_SEL_CLN subcommand.  If the value is
458              zero, 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.  The
462              bits  9–16  specify a mask to select the bits to look at and the
463              bits 17–23 specify the bit pattern to look for.  If the bit pat‐
464              tern  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
485              The header file defines many values for mt_type, but the current
486              driver reports only the generic types MT_ISSCSI1 (Generic SCSI-1
487              tape) and MT_ISSCSI2 (Generic SCSI-2 tape).
488
489       mt_resid
490              contains the current tape partition number.
491
492       mt_dsreg
493              reports  the drive's current settings for block size (in the low
494              24 bits) and density (in the high 8 bits).  These fields are de‐
495              fined  by  MT_ST_BLKSIZE_SHIFT,  MT_ST_BLKSIZE_MASK,  MT_ST_DEN‐
496              SITY_SHIFT, and MT_ST_DENSITY_MASK.
497
498       mt_gstat
499              reports generic (device independent)  status  information.   The
500              header file defines macros for testing these status bits:
501
502              GMT_EOF(x)
503                     The  tape  is  positioned  just  after a filemark (always
504                     false after an MTSEEK operation).
505
506              GMT_BOT(x)
507                     The tape is positioned at the beginning of the first file
508                     (always false after an MTSEEK operation).
509
510              GMT_EOT(x)
511                     A tape operation has reached the physical End Of Tape.
512
513              GMT_SM(x)
514                     The  tape  is  currently  positioned at a setmark (always
515                     false after an MTSEEK operation).
516
517              GMT_EOD(x)
518                     The tape is positioned at the end of recorded data.
519
520              GMT_WR_PROT(x)
521                     The drive is write-protected.  For some drives  this  can
522                     also  mean that the drive does not support writing on the
523                     current medium type.
524
525              GMT_ONLINE(x)
526                     The last open(2) found the drive with a tape in place and
527                     ready for operation.
528
529              GMT_D_6250(x)
530              GMT_D_1600(x)
531              GMT_D_800(x)
532                     This  “generic”  status  information  reports the current
533                     density setting for 9-track ½" tape drives only.
534
535              GMT_DR_OPEN(x)
536                     The drive does not have a tape in place.
537
538              GMT_IM_REP_EN(x)
539                     Immediate report mode.  This bit is set if there  are  no
540                     guarantees  that  the data has been physically written to
541                     the tape when the write call returns.   It  is  set  zero
542                     only  when  the driver does not buffer data and the drive
543                     is set not to buffer data.
544
545              GMT_CLN(x)
546                     The drive  has  requested  cleaning.   Implemented  since
547                     Linux 2.4.19 and Linux 2.5.43.
548
549       mt_erreg
550              The  only field defined in mt_erreg is the recovered error count
551              in the low  16  bits  (as  defined  by  MT_ST_SOFTERR_SHIFT  and
552              MT_ST_SOFTERR_MASK).   Due  to inconsistencies in the way drives
553              report recovered errors, this  count  is  often  not  maintained
554              (most  drives  do not by default report soft errors but this can
555              be changed with a SCSI MODE SELECT command).
556
557       mt_fileno
558              reports the current file number (zero-based).  This value is set
559              to  -1 when the file number is unknown (e.g., after MTBSS or MT‐
560              SEEK).
561
562       mt_blkno
563              reports the block number (zero-based) within the  current  file.
564              This  value is set to -1 when the block number is unknown (e.g.,
565              after MTBSF, MTBSS, or MTSEEK).
566
567   MTIOCPOS — get tape position
568       This request takes an argument of type (struct mtpos *) and reports the
569       drive's  notion of the current tape block number, which is not the same
570       as mt_blkno returned by MTIOCGET.  This drive must be  a  SCSI-2  drive
571       that  supports the READ POSITION command (device-specific address) or a
572       Tandberg-compatible SCSI-1 drive (Tandberg, Archive Viper, Wangtek, ...
573       ).
574
575           /* structure for MTIOCPOS - mag tape get position command */
576           struct mtpos {
577               long mt_blkno;    /* current block number */
578           };
579

RETURN VALUE

581       EACCES An  attempt  was  made to write or erase a write-protected tape.
582              (This error is not detected during open(2).)
583
584       EBUSY  The device is already in use or the driver was unable  to  allo‐
585              cate a buffer.
586
587       EFAULT The  command  parameters  point  to  memory not belonging to the
588              calling process.
589
590       EINVAL An ioctl(2) had an invalid argument, or a requested  block  size
591              was invalid.
592
593       EIO    The requested operation could not be completed.
594
595       ENOMEM The  byte  count  in  read(2)  is smaller than the next physical
596              block on the tape.  (Before Linux 2.2.18 and Linux 2.4.0 the ex‐
597              tra bytes have been silently ignored.)
598
599       ENOSPC A  write  operation  could  not  be  completed  because the tape
600              reached end-of-medium.
601
602       ENOSYS Unknown ioctl(2).
603
604       ENXIO  During opening, the tape device does not exist.
605
606       EOVERFLOW
607              An attempt was made to read or  write  a  variable-length  block
608              that is larger than the driver's internal buffer.
609
610       EROFS  Open  is  attempted with O_WRONLY or O_RDWR when the tape in the
611              drive is write-protected.
612

FILES

614       /dev/st*
615              the auto-rewind SCSI tape devices
616
617       /dev/nst*
618              the nonrewind SCSI tape devices
619

NOTES

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

SEE ALSO

655       mt(1)
656
657       The file drivers/scsi/README.st or Documentation/scsi/st.txt (kernel >=
658       2.6) in the Linux kernel source tree contains the most recent  informa‐
659       tion about the driver and its configuration possibilities
660
661
662
663Linux man-pages 6.05              2023-02-05                             st(4)
Impressum