Attachment #55684 for bug #84101

View | Details | Raw Unified | Return to bug 84101
Collapse All | Expand All




.Op Fl f Ar tapename
.Ar command
.Op Ar count
.Nm
.Op Fl f Ar tapename
.Ar command
.Ar argument
.Sh DESCRIPTION
The
.Nm
utility is used to command a magnetic tape drive for operations
other than reading or writing data.
.Pp
The
.Fl f
option's
.Ar tapename
overrides the TAPE environment variable described below.
.Pp
The available commands are listed below.
Only as many
characters as are required to uniquely identify a command
need be specified.
.Pp
The following commands optionally take a
.Ar count ,
which defaults to 1.
.Bl -tag -width "erase"
.It Cm weof
Write
.Ar count
end-of-file (EOF) marks at the current position.
.It Cm smk
Write
.Ar count
setmarks at the current position.
.It Cm fsf
Forward space
.Ar count

Backward space
.Ar count
setmarks.
.It Cm erase
Erase the tape using a long (often very long) method.
With a
.Ar count
of 0, it will erase the tape using a quick method.
Operation is not guaranteed if the tape is not at its beginning.
The tape will be at its beginning upon completion.
.El
.Pp
The following commands ignore
.Ar count .
.Bl -tag -width "geteotmodel"
.It Cm rdhpos
Read the hardware block position.
Some drives do not support this.
The block
number reported is specific for that hardware only.
With drive data compression especially,
this position may have more to do with the amount of data
sent to the drive than the amount of data written to tape.
Read SCSI logical block position.
Some drives do not support this.
.It Cm rdspos
Read the SCSI logical block position.
This typically is greater than the hardware position
by the number of end-of-file marks.
Some drives do not support this.
The count
argument is interpreted as a hardware block to which to position the tape.
.It Cm setspos
Set SCSI logical block position.
Some drives do not support this.
The count
argument is interpreted as a SCSI logical block to which to position the tape.
.It Cm rewind
Rewind the tape.
(Count is ignored).
.It Cm offline , rewoffl
Rewind the tape and place the drive off line.
Some drives are never off line.
.It Cm erase
Erase the tape.
A count of 0 disables long erase, which is on by default.
.It Cm retension
Re-tension the tape.
This winds the tape from the current position to the end
and then to the beginning.
This sometimes improves subsequent reading and writing,
particularly for streaming drives.
Some drives do not support this.
.It Cm status
Output status information about the drive.
For SCSI magnetic tape devices,
the current operating modes of density, blocksize, and whether compression
is enabled is reported.
The current state of the driver (what it thinks that
it is doing with the device) is reported.
If the driver knows the relative
position from BOT (in terms of filemarks and records), it outputs that.
Note
that this information is not definitive (only BOT, End of Recorded Media, and
hardware or SCSI logical block position (if the drive supports such) are
considered definitive tape positions).
.It Cm errstat
Output (and clear) error status information about this device.
For every normal
operation (e.g., a read or a write) and every control operation (e.g,, a
rewind), the driver stores up the last command executed and it is associated
status and any residual counts (if any).
This command retrieves and outputs this
information.
If possible, this also clears any latched error information.
.It Cm blocksize
Set the block size for the tape unit.
Zero means variable-length
blocks.
.It Cm density
Set the density for the tape unit.
For the density codes, see below.
The density value could be given either numerically, or as a string,
corresponding to the
.Dq Reference
field.
If the string is abbreviated, it will be resolved in the order
shown in the table, and the first matching entry will be used.
If the
given string and the resulting canonical density name do not match
exactly, an informational message is printed about what the given
string has been taken for.
.It Cm geteotmodel
Output the current EOT filemark model.
The model states how
many filemarks will be written at close if a tape was being written.
.It Cm eod , eom
Wind the tape to the end of the recorded data,
typically after an EOF mark where another file may be written.
.El
.Pp
The following commands require an
.Ar argument .
.Bl -tag -width "seteotmodel"
.It Cm sethpos
Set the hardware block position.
The
.Ar argument
is a hardware block number to which to position the tape.
Some drives do not support this.
.It Cm setspos
Set the SCSI logical block position.
The
.Ar argument
is a SCSI logical block number to which to position the tape.
Some drives do not support this.
.It Cm blocksize
Set the block size for the drive.
The
.Ar argument
is the number of bytes per block,
except 0 commands the drive to use variable-length blocks.
.It Cm seteotmodel
Set the EOT filemark model to
.Ar argument
and output the old and new models.
Typically this will be 2
Typically this will be
.Ar 2
filemarks, but some devices (typically QIC cartridge drives) can
only write 1 filemark.
You may only choose a value of
filemark.
Currently you can only choose a value of
.Ar 1
or
.Ar 2 .
.It Cm eom
Forward space to end of recorded medium
(Count is ignored).
.It Cm eod
Forward space to end of data, identical to
.Cm eom .
.It Cm comp
Set the drive's compression mode.
The non-numeric values of
.Ar argument
are:
.Pp
.Bl -tag -width 9n -compact
.It off

.El
.Pp
In addition to the above recognized compression keywords, the user can
supply a numeric compression algorithm for the drive to use.
In most
cases, simply turning the compression
.Sq on

.Cm status
display to see which compression algorithm is currently in use), the user
can manually specify one of the supported compression keywords (above), or
supply a numeric compression value from the drive's specifications.
.It Cm density
Set the density for the drive.
For the density codes, see below.
The density value could be given either numerically, or as a string,
corresponding to the
.Dq Reference
field.
If the string is abbreviated, it will be resolved in the order
shown in the table, and the first matching entry will be used.
If the
given string and the resulting canonical density name do not match
exactly, an informational message is output about what the given
string has been taken for.
.El
.Pp
If a tape name is not specified, and the environment variable
.Ev TAPE
does not exist;
.Nm
uses the device
.Pa /dev/nsa0 .
.Pp
The
.Nm
utility returns a 0 exit status when the operation(s) were successful,
1 if the command was unrecognized, and 2 if an operation failed.
.Pp
The following density table was taken from the
.Sq Historical sequential access density codes
table (A-1) in Revision 11 of the SCSI-3 Stream Device Commands (SSC)
working draft, dated November 11, 1997.
.Pp
The density codes are:
.Pp
.Dl "0x0	default for device
.Dl "0xE	reserved for ECMA
.Bd -literal -offset 3n
0x0    default for device
0xE    reserved for ECMA
.Dl ""
Value  Width        Tracks    Density         Code Type Reference   Note
        mm    in              bpmm       bpi
0x01   12.7  (0.5)    9         32     (800)  NRZI  R   X3.22-1983   2

   8 physical tracks each.
.Ed
.Sh ENVIRONMENT
.Bl -tag -width TAPE
.Nm .
.Bl -tag -width Fl
.It Ev TAPE
This is the -pathname of the tape drive.
The default (if the variable is unset, but not if it is null) is
.Pa /dev/nsa0 .
It may be overridden with the
.Fl f
option.
.Ar tapename
is not given.
.El
.Sh FILES
.Bl -tag -width /dev/*sa[0-9]*xx -compact

.It Pa /dev/*sa[0-9]*
SCSI magnetic tape interface
.El
.Sh DIAGNOSTICS
.Pp
The exit status will be 0 when the drive operations were successful,
2 when the drive operations were unsuccessful, and 1 for other
problems like an unrecognized command or a missing drive device.
.Sh COMPATIBILITY
Some undocumented commands support old software.
.Sh SEE ALSO
.Xr dd 1 ,
.Xr ioctl 2 ,

since it was often confused with
.Cm eom ,
which is fairly dangerous.
.Sh BUGS
The utility cannot be interrupted or killed during a long erase
(which can be longer than an hour), and it is easy to forget
that the default erase is long.
.Pp
Hardware block numbers do not always correspond to blocks on the tape
when the drive uses internal compression.
.Pp
Erasure is not guaranteed if the tape is not at its beginning.
.Pp
Tape-related documentation is poor, here and elsewhere.

Return to bug 84101

Lines 44-73 Link Here

(-)mt.1 (-105 / +133 lines)
44	.Op Fl f Ar tapename	44	.Op Fl f Ar tapename
45	.Ar command	45	.Ar command
46	.Op Ar count	46	.Op Ar count
		47	.Nm
		48	.Op Fl f Ar tapename
		49	.Ar command
		50	.Ar argument
47	.Sh DESCRIPTION	51	.Sh DESCRIPTION
48	The	52	The
49	.Nm	53	.Nm
50	utility is used to give commands to a magnetic tape drive.	54	utility is used to command a magnetic tape drive for operations
51	By default	55	other than reading or writing data.
52	.Nm	56	.Pp
53	performs the requested operation once.	57	The
54	Operations	58	.Fl f
55	may be performed multiple times by specifying	59	option's
56	.Ar count .	60	.Ar tapename
		61	overrides the TAPE environment variable described below.
57	.Pp	62	.Pp
58	The available commands are listed below.	63	The available commands are listed below.
59	Only as many	64	Only as many
60	characters as are required to uniquely identify a command	65	characters as are required to uniquely identify a command
61	need be specified.	66	need be specified.
62	.Bl -tag -width "eof, weof"	67	.Pp
		68	The following commands optionally take a
		69	.Ar count ,
		70	which defaults to 1.
		71	.Bl -tag -width "erase"
63	.It Cm weof	72	.It Cm weof
64	Write	73	Write
65	.Ar count	74	.Ar count
66	end-of-file marks at the current position on the tape.	75	end-of-file (EOF) marks at the current position.
67	.It Cm smk	76	.It Cm smk
68	Write	77	Write
69	.Ar count	78	.Ar count
70	setmarks at the current position on the tape.	79	setmarks at the current position.
71	.It Cm fsf	80	.It Cm fsf
72	Forward space	81	Forward space
73	.Ar count	82	.Ar count
Lines 92-198 Link Here
92	Backward space	101	Backward space
93	.Ar count	102	.Ar count
94	setmarks.	103	setmarks.
		104	.It Cm erase
		105	Erase the tape using a long (often very long) method.
		106	With a
		107	.Ar count
		108	of 0, it will erase the tape using a quick method.
		109	Operation is not guaranteed if the tape is not at its beginning.
		110	The tape will be at its beginning upon completion.
		111	.El
		112	.Pp
		113	The following commands ignore
		114	.Ar count .
		115	.Bl -tag -width "geteotmodel"
95	.It Cm rdhpos	116	.It Cm rdhpos
96	Read Hardware block position.	117	Read the hardware block position.
97	Some drives do not support this.
98	The block	118	The block
99	number reported is specific for that hardware only.	119	number reported is specific for that hardware only.
100	The count argument is	120	With drive data compression especially,
101	ignored.	121	this position may have more to do with the amount of data
102	.It Cm rdspos	122	sent to the drive than the amount of data written to tape.
103	Read SCSI logical block position.
104	Some drives do not support this.	123	Some drives do not support this.
105	The	124	.It Cm rdspos
106	count argument is ignored.	125	Read the SCSI logical block position.
107	.It Cm sethpos	126	This typically is greater than the hardware position
108	Set Hardware block position.	127	by the number of end-of-file marks.
109	Some drives do not support this.
110	The count
111	argument is interpreted as a hardware block to which to position the tape.
112	.It Cm setspos
113	Set SCSI logical block position.
114	Some drives do not support this.	128	Some drives do not support this.
115	The count
116	argument is interpreted as a SCSI logical block to which to position the tape.
117	.It Cm rewind	129	.It Cm rewind
118	Rewind the tape	130	Rewind the tape.
119	(Count is ignored).
120	.It Cm offline , rewoffl	131	.It Cm offline , rewoffl
121	Rewind the tape and place the tape unit off-line	132	Rewind the tape and place the drive off line.
122	(Count is ignored).	133	Some drives are never off line.
123	.It Cm erase
124	Erase the tape.
125	A count of 0 disables long erase, which is on by default.
126	.It Cm retension	134	.It Cm retension
127	Re-tension the tape	135	Re-tension the tape.
128	(one full wind forth and back, Count is ignored).	136	This winds the tape from the current position to the end
		137	and then to the beginning.
		138	This sometimes improves subsequent reading and writing,
		139	particularly for streaming drives.
		140	Some drives do not support this.
129	.It Cm status	141	.It Cm status
130	Print status information about the tape unit.	142	Output status information about the drive.
131	For SCSI magnetic tape devices,	143	For SCSI magnetic tape devices,
132	the current operating modes of density, blocksize, and whether compression	144	the current operating modes of density, blocksize, and whether compression
133	is enabled is reported.	145	is enabled is reported.
134	The current state of the driver (what it thinks that	146	The current state of the driver (what it thinks that
135	it is doing with the device) is reported.	147	it is doing with the device) is reported.
136	If the driver knows the relative	148	If the driver knows the relative
137	position from BOT (in terms of filemarks and records), it prints that.	149	position from BOT (in terms of filemarks and records), it outputs that.
138	Note	150	Note
139	that this information is not definitive (only BOT, End of Recorded Media, and	151	that this information is not definitive (only BOT, End of Recorded Media, and
140	hardware or SCSI logical block position (if the drive supports such) are	152	hardware or SCSI logical block position (if the drive supports such) are
141	considered definitive tape positions).	153	considered definitive tape positions).
142	.It Cm errstat	154	.It Cm errstat
143	Print (and clear) error status information about this device.	155	Output (and clear) error status information about this device.
144	For every normal	156	For every normal
145	operation (e.g., a read or a write) and every control operation (e.g,, a	157	operation (e.g., a read or a write) and every control operation (e.g,, a
146	rewind), the driver stores up the last command executed and it is associated	158	rewind), the driver stores up the last command executed and it is associated
147	status and any residual counts (if any).	159	status and any residual counts (if any).
148	This command retrieves and prints this	160	This command retrieves and outputs this
149	information.	161	information.
150	If possible, this also clears any latched error information.	162	If possible, this also clears any latched error information.
151	.It Cm blocksize
152	Set the block size for the tape unit.
153	Zero means variable-length
154	blocks.
155	.It Cm density
156	Set the density for the tape unit.
157	For the density codes, see below.
158	The density value could be given either numerically, or as a string,
159	corresponding to the
160	.Dq Reference
161	field.
162	If the string is abbreviated, it will be resolved in the order
163	shown in the table, and the first matching entry will be used.
164	If the
165	given string and the resulting canonical density name do not match
166	exactly, an informational message is printed about what the given
167	string has been taken for.
168	.It Cm geteotmodel	163	.It Cm geteotmodel
169	Fetch and print out the current EOT filemark model.	164	Output the current EOT filemark model.
170	The model states how	165	The model states how
171	many filemarks will be written at close if a tape was being written.	166	many filemarks will be written at close if a tape was being written.
		167	.It Cm eod , eom
		168	Wind the tape to the end of the recorded data,
		169	typically after an EOF mark where another file may be written.
		170	.El
		171	.Pp
		172	The following commands require an
		173	.Ar argument .
		174	.Bl -tag -width "seteotmodel"
		175	.It Cm sethpos
		176	Set the hardware block position.
		177	The
		178	.Ar argument
		179	is a hardware block number to which to position the tape.
		180	Some drives do not support this.
		181	.It Cm setspos
		182	Set the SCSI logical block position.
		183	The
		184	.Ar argument
		185	is a SCSI logical block number to which to position the tape.
		186	Some drives do not support this.
		187	.It Cm blocksize
		188	Set the block size for the drive.
		189	The
		190	.Ar argument
		191	is the number of bytes per block,
		192	except 0 commands the drive to use variable-length blocks.
172	.It Cm seteotmodel	193	.It Cm seteotmodel
173	Set (from the	194	Set the EOT filemark model to
174	.Ar count	195	.Ar argument
175	argument)	196	and output the old and new models.
176	and print out the current and EOT filemark model.	197	Typically this will be 2
177	Typically this will be
178	.Ar 2
179	filemarks, but some devices (typically QIC cartridge drives) can	198	filemarks, but some devices (typically QIC cartridge drives) can
180	only write	199	only write 1 filemark.
181	.Ar 1	200	You may only choose a value of
182	filemark.
183	Currently you can only choose a value of
184	.Ar 1	201	.Ar 1
185	or	202	or
186	.Ar 2 .	203	.Ar 2 .
187	.It Cm eom
188	Forward space to end of recorded medium
189	(Count is ignored).
190	.It Cm eod
191	Forward space to end of data, identical to
192	.Cm eom .
193	.It Cm comp	204	.It Cm comp
194	Set compression mode.	205	Set the drive's compression mode.
195	There are currently several possible values for the compression mode:	206	The non-numeric values of
		207	.Ar argument
		208	are:
196	.Pp	209	.Pp
197	.Bl -tag -width 9n -compact	210	.Bl -tag -width 9n -compact
198	.It off	211	.It off
Lines 212-218 Link Here
212	.El	225	.El
213	.Pp	226	.Pp
214	In addition to the above recognized compression keywords, the user can	227	In addition to the above recognized compression keywords, the user can
215	supply a numeric compression algorithm for the tape drive to use.	228	supply a numeric compression algorithm for the drive to use.
216	In most	229	In most
217	cases, simply turning the compression	230	cases, simply turning the compression
218	.Sq on	231	.Sq on
Lines 222-252 Link Here
222	.Cm status	235	.Cm status
223	display to see which compression algorithm is currently in use), the user	236	display to see which compression algorithm is currently in use), the user
224	can manually specify one of the supported compression keywords (above), or	237	can manually specify one of the supported compression keywords (above), or
225	supply a numeric compression value.	238	supply a numeric compression value from the drive's specifications.
		239	.It Cm density
		240	Set the density for the drive.
		241	For the density codes, see below.
		242	The density value could be given either numerically, or as a string,
		243	corresponding to the
		244	.Dq Reference
		245	field.
		246	If the string is abbreviated, it will be resolved in the order
		247	shown in the table, and the first matching entry will be used.
		248	If the
		249	given string and the resulting canonical density name do not match
		250	exactly, an informational message is output about what the given
		251	string has been taken for.
226	.El	252	.El
227	.Pp	253	.Pp
228	If a tape name is not specified, and the environment variable
229	.Ev TAPE
230	does not exist;
231	.Nm
232	uses the device
233	.Pa /dev/nsa0 .
234	.Pp
235	The
236	.Nm
237	utility returns a 0 exit status when the operation(s) were successful,
238	1 if the command was unrecognized, and 2 if an operation failed.
239	.Pp
240	The following density table was taken from the	254	The following density table was taken from the
241	.Sq Historical sequential access density codes	255	.Sq Historical sequential access density codes
242	table (A-1) in Revision 11 of the SCSI-3 Stream Device Commands (SSC)	256	table (A-1) in Revision 11 of the SCSI-3 Stream Device Commands (SSC)
243	working draft, dated November 11, 1997.	257	working draft, dated November 11, 1997.
244	.Pp	258	.Pp
245	The different density codes are as follows:	259	The density codes are:
246	.Pp
247	.Dl "0x0 default for device
248	.Dl "0xE reserved for ECMA
249	.Bd -literal -offset 3n	260	.Bd -literal -offset 3n
		261	0x0 default for device
		262	0xE reserved for ECMA
		263	.Dl ""
250	Value Width Tracks Density Code Type Reference Note	264	Value Width Tracks Density Code Type Reference Note
251	mm in bpmm bpi	265	mm in bpmm bpi
252	0x01 12.7 (0.5) 9 32 (800) NRZI R X3.22-1983 2	266	0x01 12.7 (0.5) 9 32 (800) NRZI R X3.22-1983 2
Lines 320-337 Link Here
320	8 physical tracks each.	334	8 physical tracks each.
321	.Ed	335	.Ed
322	.Sh ENVIRONMENT	336	.Sh ENVIRONMENT
323	If the following environment variable exists, it is utilized by	337	.Bl -tag -width TAPE
324	.Nm .
325	.Bl -tag -width Fl
326	.It Ev TAPE	338	.It Ev TAPE
327	The	339	This is the -pathname of the tape drive.
328	.Nm	340	The default (if the variable is unset, but not if it is null) is
329	utility checks the	341	.Pa /dev/nsa0 .
330	.Ev TAPE	342	It may be overridden with the
331	environment variable if the	343	.Fl f
332	argument	344	option.
333	.Ar tapename
334	is not given.
335	.El	345	.El
336	.Sh FILES	346	.Sh FILES
337	.Bl -tag -width /dev/sa[0-9]xx -compact	347	.Bl -tag -width /dev/sa[0-9]xx -compact
Lines 340-345 Link Here
340	.It Pa /dev/sa[0-9]	350	.It Pa /dev/sa[0-9]
341	SCSI magnetic tape interface	351	SCSI magnetic tape interface
342	.El	352	.El
		353	.Sh DIAGNOSTICS
		354	.Pp
		355	The exit status will be 0 when the drive operations were successful,
		356	2 when the drive operations were unsuccessful, and 1 for other
		357	problems like an unrecognized command or a missing drive device.
		358	.Sh COMPATIBILITY
		359	Some undocumented commands support old software.
343	.Sh SEE ALSO	360	.Sh SEE ALSO
344	.Xr dd 1 ,	361	.Xr dd 1 ,
345	.Xr ioctl 2 ,	362	.Xr ioctl 2 ,
Lines 373-375 Link Here
373	since it was often confused with	390	since it was often confused with
374	.Cm eom ,	391	.Cm eom ,
375	which is fairly dangerous.	392	which is fairly dangerous.
		393	.Sh BUGS
		394	The utility cannot be interrupted or killed during a long erase
		395	(which can be longer than an hour), and it is easy to forget
		396	that the default erase is long.
		397	.Pp
		398	Hardware block numbers do not always correspond to blocks on the tape
		399	when the drive uses internal compression.
		400	.Pp
		401	Erasure is not guaranteed if the tape is not at its beginning.
		402	.Pp
		403	Tape-related documentation is poor, here and elsewhere.