/share/man/man4/mtio.4

  1.\" Copyright (c) 1996
  2.\"	Mike Pritchard <mpp@FreeBSD.org>.  All rights reserved.
  3.\"
  4.\" Copyright (c) 1983, 1991, 1993
  5.\"	The Regents of the University of California.  All rights reserved.
  6.\"
  7.\" Redistribution and use in source and binary forms, with or without
  8.\" modification, are permitted provided that the following conditions
  9.\" are met:
 10.\" 1. Redistributions of source code must retain the above copyright
 11.\"    notice, this list of conditions and the following disclaimer.
 12.\" 2. Redistributions in binary form must reproduce the above copyright
 13.\"    notice, this list of conditions and the following disclaimer in the
 14.\"    documentation and/or other materials provided with the distribution.
 15.\" 3. All advertising materials mentioning features or use of this software
 16.\"    must display the following acknowledgement:
 17.\"	This product includes software developed by the University of
 18.\"	California, Berkeley and its contributors.
 19.\" 4. Neither the name of the University nor the names of its contributors
 20.\"    may be used to endorse or promote products derived from this software
 21.\"    without specific prior written permission.
 22.\"
 23.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
 24.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 25.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 26.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
 27.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 28.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
 29.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 30.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
 31.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
 32.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 33.\" SUCH DAMAGE.
 34.\"
 35.\"     @(#)mtio.4	8.1 (Berkeley) 6/5/93
 36.\" $FreeBSD$
 37.\"
 38.Dd November 11, 2011
 39.Dt MTIO 4
 40.Os
 41.Sh NAME
 42.Nm mtio
 43.Nd FreeBSD magtape interface
 44.Sh DESCRIPTION
 45The special files
 46named
 47.Pa /dev/[n]sa*
 48refer to SCSI tape drives,
 49which may be attached to the system.
 50.Pa /dev/[n]sa*.ctl
 51are control devices that can be used to issue ioctls to the SCSI
 52tape driver to set parameters that are required to last beyond the
 53unmounting of a tape.
 54.Pp
 55The rewind devices automatically rewind
 56when the last requested read, write or seek has finished, or the end of the tape
 57has been reached.
 58The letter
 59.Ql n
 60is usually prepended to
 61the name of the no-rewind devices.
 62.Pp
 63Tapes can be written with either fixed length records or variable length
 64records.
 65See
 66.Xr sa 4
 67for more information.
 68Two end-of-file markers mark the end of a tape, and
 69one end-of-file marker marks the end of a tape file.
 70If the tape is not to be rewound it is positioned with the
 71head in between the two tape marks, where the next write
 72will over write the second end-of-file marker.
 73.Pp
 74All of the magtape devices may be manipulated with the
 75.Xr mt 1
 76command.
 77.Pp
 78A number of
 79.Xr ioctl 2
 80operations are available
 81on raw magnetic tape.
 82The following definitions are from
 83.In sys/mtio.h :
 84.Bd  -literal
 85#ifndef	_SYS_MTIO_H_
 86#define	_SYS_MTIO_H_
 87
 88#ifndef _KERNEL
 89#include <sys/types.h>
 90#endif
 91#include <sys/ioccom.h>
 92
 93/*
 94 * Structures and definitions for mag tape io control commands
 95 */
 96
 97/* structure for MTIOCTOP - mag tape op command */
 98struct mtop {
 99	short	mt_op;		/* operations defined below */
100	int32_t	mt_count;	/* how many of them */
101};
102
103/* operations */
104#define MTWEOF		0	/* write an end-of-file record */
105#define MTFSF		1	/* forward space file */
106#define MTBSF		2	/* backward space file */
107#define MTFSR		3	/* forward space record */
108#define MTBSR		4	/* backward space record */
109#define MTREW		5	/* rewind */
110#define MTOFFL		6	/* rewind and put the drive offline */
111#define MTNOP		7	/* no operation, sets status only */
112#define MTCACHE		8	/* enable controller cache */
113#define MTNOCACHE	9	/* disable controller cache */
114
115#if defined(__FreeBSD__)
116/* Set block size for device. If device is a variable size dev		*/
117/* a non zero parameter will change the device to a fixed block size	*/
118/* device with block size set to that of the parameter passed in.	*/
119/* Resetting the block size to 0 will restore the device to a variable	*/
120/* block size device. */
121
122#define MTSETBSIZ	10
123
124/* Set density values for device. Sets the value for the opened mode only. */
125
126#define MTSETDNSTY	11
127
128#define MTERASE		12	/* erase to EOM */
129#define MTEOD		13	/* Space to EOM */
130#define MTCOMP		14	/* select compression mode 0=off, 1=def */
131#define MTRETENS	15	/* re-tension tape */
132#define MTWSS		16	/* write setmark(s) */
133#define MTFSS		17	/* forward space setmark */
134#define MTBSS		18	/* backward space setmark */
135
136#define MT_COMP_ENABLE		0xffffffff
137#define MT_COMP_DISABLED	0xfffffffe
138#define MT_COMP_UNSUPP		0xfffffffd
139
140/*
141 * Values in mt_dsreg that say what the device is doing
142 */
143#define	MTIO_DSREG_NIL	0	/* Unknown */
144#define	MTIO_DSREG_REST	1	/* Doing Nothing */
145#define	MTIO_DSREG_RBSY	2	/* Communicating with tape (but no motion) */
146#define	MTIO_DSREG_WR	20	/* Writing */
147#define	MTIO_DSREG_FMK	21	/* Writing Filemarks */
148#define	MTIO_DSREG_ZER	22	/* Erasing */
149#define	MTIO_DSREG_RD	30	/* Reading */
150#define	MTIO_DSREG_FWD	40	/* Spacing Forward */
151#define	MTIO_DSREG_REV	41	/* Spacing Reverse */
152#define	MTIO_DSREG_POS	42	/* Hardware Positioning (direction unknown) */
153#define	MTIO_DSREG_REW	43	/* Rewinding */
154#define	MTIO_DSREG_TEN	44	/* Retensioning */
155#define	MTIO_DSREG_UNL	45	/* Unloading */
156#define	MTIO_DSREG_LD	46	/* Loading */
157
158#endif	/* __FreeBSD__ */
159
160/* structure for MTIOCGET - mag tape get status command */
161
162struct mtget {
163	short	mt_type;	/* type of magtape device */
164/* the following two registers are grossly device dependent */
165	short	mt_dsreg;	/* ``drive status'' register */
166	short	mt_erreg;	/* ``error'' register */
167/* end device-dependent registers */
168	/*
169	 * Note that the residual count, while maintained, may be
170	 * be nonsense because the size of the residual may (greatly)
171	 * exceed 32 K-bytes. Use the MTIOCERRSTAT ioctl to get a
172	 * more accurate count.
173	 */
174	short	mt_resid;	/* residual count */
175#if defined (__FreeBSD__)
176	int32_t mt_blksiz;	/* presently operating blocksize */
177	int32_t mt_density;	/* presently operating density */
178	uint32_t mt_comp;	/* presently operating compression */
179	int32_t mt_blksiz0;	/* blocksize for mode 0 */
180	int32_t mt_blksiz1;	/* blocksize for mode 1 */
181	int32_t mt_blksiz2;	/* blocksize for mode 2 */
182	int32_t mt_blksiz3;	/* blocksize for mode 3 */
183	int32_t mt_density0;	/* density for mode 0 */
184	int32_t mt_density1;	/* density for mode 1 */
185	int32_t mt_density2;	/* density for mode 2 */
186	int32_t mt_density3;	/* density for mode 3 */
187/* the following are not yet implemented */
188	uint32_t mt_comp0;	/* compression type for mode 0 */
189	uint32_t mt_comp1;	/* compression type for mode 1 */
190	uint32_t mt_comp2;	/* compression type for mode 2 */
191	uint32_t mt_comp3;	/* compression type for mode 3 */
192/* end not yet implemented */
193#endif
194	int32_t	mt_fileno;	/* relative file number of current position */
195	int32_t	mt_blkno;	/* relative block number of current position */
196};
197
198/* structure for MTIOCERRSTAT - tape get error status command */
199/* really only supported for SCSI tapes right now */
200struct scsi_tape_errors {
201	/*
202	 * These are latched from the last command that had a SCSI
203	 * Check Condition noted for these operations. The act
204	 * of issuing an MTIOCERRSTAT unlatches and clears them.
205	 */
206	uint8_t io_sense[32];	/* Last Sense Data For Data I/O */
207	int32_t io_resid;	/* residual count from last Data I/O */
208	uint8_t io_cdb[16];	/* Command that Caused the Last Data Sense */
209	uint8_t ctl_sense[32];	/* Last Sense Data For Control I/O */
210	int32_t ctl_resid;	/* residual count from last Control I/O */
211	uint8_t ctl_cdb[16];	/* Command that Caused the Last Control Sense */
212	/*
213	 * These are the read and write cumulative error counters.
214	 * (how to reset cumulative error counters is not yet defined).
215	 * (not implemented as yet but space is being reserved for them)
216	 */
217	struct {
218		uint32_t retries;	/* total # retries performed */
219		uint32_t corrected;	/* total # corrections performed */
220		uint32_t processed;	/* total # corrections successful */
221		uint32_t failures;	/* total # corrections/retries failed */
222		uint64_t nbytes;	/* total # bytes processed */
223	} wterr, rderr;
224};
225
226union mterrstat {
227	struct scsi_tape_errors scsi_errstat;
228	char _reserved_padding[256];
229};
230
231/*
232 * Constants for mt_type byte.  These are the same
233 * for controllers compatible with the types listed.
234 */
235#define	MT_ISTS		0x01		/* TS-11 */
236#define	MT_ISHT		0x02		/* TM03 Massbus: TE16, TU45, TU77 */
237#define	MT_ISTM		0x03		/* TM11/TE10 Unibus */
238#define	MT_ISMT		0x04		/* TM78/TU78 Massbus */
239#define	MT_ISUT		0x05		/* SI TU-45 emulation on Unibus */
240#define	MT_ISCPC	0x06		/* SUN */
241#define	MT_ISAR		0x07		/* SUN */
242#define	MT_ISTMSCP	0x08		/* DEC TMSCP protocol (TU81, TK50) */
243#define MT_ISCY		0x09		/* CCI Cipher */
244#define MT_ISCT		0x0a		/* HP 1/4 tape */
245#define MT_ISFHP	0x0b		/* HP 7980 1/2 tape */
246#define MT_ISEXABYTE	0x0c		/* Exabyte */
247#define MT_ISEXA8200	0x0c		/* Exabyte EXB-8200 */
248#define MT_ISEXA8500	0x0d		/* Exabyte EXB-8500 */
249#define MT_ISVIPER1	0x0e		/* Archive Viper-150 */
250#define MT_ISPYTHON	0x0f		/* Archive Python (DAT) */
251#define MT_ISHPDAT	0x10		/* HP 35450A DAT drive */
252#define MT_ISMFOUR	0x11		/* M4 Data 1/2 9track drive */
253#define MT_ISTK50	0x12		/* DEC SCSI TK50 */
254#define MT_ISMT02	0x13		/* Emulex MT02 SCSI tape controller */
255
256/* mag tape io control commands */
257#define	MTIOCTOP	_IOW('m', 1, struct mtop)	/* do a mag tape op */
258#define	MTIOCGET	_IOR('m', 2, struct mtget)	/* get tape status */
259/* these two do not appear to be used anywhere */
260#define MTIOCIEOT	_IO('m', 3)			/* ignore EOT error */
261#define MTIOCEEOT	_IO('m', 4)			/* enable EOT error */
262/*
263 * When more SCSI-3 SSC (streaming device) devices are out there
264 * that support the full 32 byte type 2 structure, we'll have to
265 * rethink these ioctls to support all the entities they haul into
266 * the picture (64 bit blocks, logical file record numbers, etc..).
267 */
268#define	MTIOCRDSPOS	_IOR('m', 5, uint32_t)	/* get logical blk addr */
269#define	MTIOCRDHPOS	_IOR('m', 6, uint32_t)	/* get hardware blk addr */
270#define	MTIOCSLOCATE	_IOW('m', 5, uint32_t)	/* seek to logical blk addr */
271#define	MTIOCHLOCATE	_IOW('m', 6, uint32_t)	/* seek to hardware blk addr */
272#define	MTIOCERRSTAT	_IOR('m', 7, union mterrstat)	/* get tape errors */
273/*
274 * Set EOT model- argument is number of filemarks to end a tape with.
275 * Note that not all possible values will be accepted.
276 */
277#define	MTIOCSETEOTMODEL	_IOW('m', 8, uint32_t)
278/* Get current EOT model */
279#define	MTIOCGETEOTMODEL	_IOR('m', 8, uint32_t)
280
281#ifndef _KERNEL
282#define	DEFTAPE	"/dev/nsa0"
283#endif
284
285#endif /* !_SYS_MTIO_H_ */
286.Ed
287.Sh FILES
288.Bl -tag -width /dev/[n]sa* -compact
289.It Pa /dev/[n]sa*
290.El
291.Sh SEE ALSO
292.Xr mt 1 ,
293.Xr tar 1 ,
294.Xr ast 4 ,
295.Xr sa 4
296.Sh HISTORY
297The
298.Nm
299manual appeared in
300.Bx 4.2 .
301An i386 version first appeared in
302.Fx 2.2 .
303.Sh BUGS
304The status should be returned in a device independent format.
305.Pp
306The special file naming should be redone in a more consistent and
307understandable manner.