1.\" $NetBSD: chio.1,v 1.4 1997/10/02 00:41:25 hubertf Exp $ 2.\" 3.\" Copyright (c) 1996 Jason R. Thorpe <thorpej@and.com> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. All advertising materials mentioning features or use of this software 15.\" must display the following acknowledgements: 16.\" This product includes software developed by Jason R. Thorpe 17.\" for And Communications, http://www.and.com/ 18.\" 4. The name of the author may not be used to endorse or promote products 19.\" derived from this software without specific prior written permission. 20.\" 21.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 22.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 23.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 24.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 25.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 26.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 27.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 28.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 29.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 30.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 31.\" SUCH DAMAGE. 32.\" 33.\" $FreeBSD$ 34.\" 35.Dd May 14, 1998 36.Dt CHIO 1 37.Os 38.Sh NAME 39.Nm chio 40.Nd medium changer control utility 41.Sh SYNOPSIS 42.Nm 43.Op Fl f Ar changer 44.Ar command 45.Op Fl <flags> 46.Ar arg1 47.Ar arg2 48.Oo 49.Ar arg3 Oo ... 50.Oc 51.Oc 52.Sh DESCRIPTION 53.Nm 54is used to control the operation of medium changers, such as those found 55in tape and optical disk jukeboxes. 56.Pp 57The options are as follows: 58.Bl -tag -width indent 59.It Fl f Ar changer 60Use the device 61.Pa changer 62rather than the default device 63.Pa /dev/ch0 . 64.El 65.Pp 66The default changer may be overridden by setting the environment variable 67.Ev CHANGER 68to the desired changer device. 69.Pp 70A medium changer apparatus is made up of 71.Em elements . 72There are four element types: 73.Em picker 74(medium transport), 75.Em slot 76(storage), 77.Em portal 78(import/export), and 79.Em drive 80(data transfer). In this command description, the shorthand 81.Em ET 82will be used to represent an element type, and 83.Em EU 84will be used to represent an element unit. For example, to represent 85the first robotic arm in the changer, the 86.Em ET 87would be 88.Dq picker 89and the 90.Em EU 91would be 92.Dq 0 . 93.Pp 94.Sh SUPPORTED COMMANDS 95.Bl -tag -width indent 96.It Xo Nm move 97.Ar <from ET> <from EU> <to ET> <to EU> 98.Op Ar inv 99.Xc 100Move the media unit from 101.Pa <from ET/EU> 102to 103.Pa <to ET/EU> . 104If the optional modifier 105.Pa inv 106is specified, the media unit will be inverted before insertion. 107.It Xo Nm exchange 108.Ar <src ET> <src EU> <dst1 ET> <dst1 EU> 109.Op Ar <dst2 ET> <dst2 ET> 110.Op Ar inv1 111.Op Ar inv2 112.Xc 113Perform a media unit exchange operation. The media unit in 114.Pa <src ET/EU> 115is moved to 116.Pa <dst1 ET/EU> 117and the media unit previously in 118.Pa <dst1 ET/EU> 119is moved to 120.Pa <dst2 ET/EU> . 121In the case of a simple exchange, 122.Pa <dst2 ET/EU> 123is omitted and the values 124.Pa <src ET/EU> 125are used in their place. 126The optional modifiers 127.Pa inv1 128and 129.Pa inv2 130specify whether the media units are to be inverted before insertion into 131.Pa <dst1 ET/EU> 132and 133.Pa <dst2 ET/EU> 134respectively. 135.Pp 136Note that not all medium changers support the 137.Ic exchange 138operation; the changer must have multiple free pickers or emulate 139multiple free pickers with transient storage. 140.It Xo Nm position 141.Ar <to ET> <to EU> 142.Op Ar inv 143.Xc 144Position the picker in front of the element described by 145.Pa <to ET/EU> . 146If the optional modifier 147.Pa inv 148is specified, the media unit will be inverted before insertion. 149.Pp 150Note that not all changers behave as expected when issued this command. 151.It Nm params 152Report the number of slots, drives, pickers, and portals in the changer, 153and which picker unit the changer is currently configured to use. 154.It Nm getpicker 155Report which picker unit the changer is currently configured to use. 156.It Xo Nm setpicker 157.Ar <unit> 158.Xc 159Configure the changer to use picker 160.Pa <unit> . 161.Pp 162.It Xo Nm ielem 163.Op Pa <timeout> 164.Xc 165Perform an \fBINITIALIZE ELEMENT STATUS\fR 166operation on the changer. The optional 167.Pa <timeout> 168parameter may be given to specify a timeout in seconds for the 169operations. This may be used if the operation takes unusually long 170because of buggy firmware or the like. 171.It Xo Nm voltag 172.Op Fl fca 173.Ar <ET> 174.Ar <EU> 175.Op Ar <label> 176.Op Ar <serial> 177.Xc 178Change volume tag for an element in the media changer. This command 179is only supported by few media changers. If it is not supported by a 180device, using this command will usually result in a "Invalid Field in 181CDB" error message on the console. 182.Pp 183If the 184.Fl c 185flag is specified, the volume tag of the specified element is 186cleared. If the 187.Fl f 188flag is specified, the volume tag is superseded with the specified 189volume tag even if a volume tag is already defined for the element. 190It is an error to not specify the 191.Fl f 192flag when trying to set a label for an element which already has 193volume tag information defined. 194.Pp 195The command works with the primary volume tag or, if the 196.Fl a 197flag is given, with the alternate volume tag. 198.It Xo Nm status 199.Op Fl vVsSbIa 200.Op Ar <type> 201.Xc 202Report the status of all elements in the changer. If 203.Pa <type> 204is specified, report the status of all elements of type 205.Pa <type> . 206.It Fl v 207Print the primary volume tag for each loaded medium, if any. The volume 208tag is printed as \fB<LABEL:SERIAL>\fR. 209.It Fl V 210Print the alternate volume tag for each loaded medium, if any. 211.It Fl s 212Print the additional sense code and additional sense code qualifier for 213each element. 214.It Fl S 215Print the element source address for each element. 216.It Fl b 217Print SCSI bus information for each element. Note that this information 218is valid only for drives. 219.It Fl I 220Print the internal element addresses for each element. The internal 221element address is not normally used with this driver. It is reported 222for diagnostic purposes only. 223.It Fl a 224Print all additional information (as in 225.Fl vVsSba 226). 227.El 228.Pp 229The status bits are defined as follows: 230.Bl -tag -width indent 231.It FULL 232Element contains a media unit. 233.It IMPEXP 234Media was deposited into element by an outside human operator. 235.It EXCEPT 236Element is in an abnormal state. 237.It ACCESS 238Media in this element is accessible by a picker. 239.It EXENAB 240Element supports passing media (exporting) to an outside human operator. 241.It INENAB 242Element supports receiving media (importing) from an outside human operator. 243.El 244.Pp 245.Sh EXAMPLES 246.Bl -tag -width indent 247.It Nm chio move slot 3 drive 0 248Move the media in slot 3 (fourth slot) to drive 0 (first drive). 249.It Nm chio setpicker 2 250Configure the changer to use picker 2 (third picker) for operations. 251.El 252.Sh FILES 253.Bl -tag -width /dev/ch0 -compact 254.It Pa /dev/ch0 255default changer device 256.El 257.Sh SEE ALSO 258.Xr mt 1 , 259.Xr mount 8 . 260.Sh AUTHORS 261The 262.Nm 263program and SCSI changer driver were written by 264.An Jason R. Thorpe Aq thorpej@and.com 265for And Communications, http://www.and.com/. 266.br 267Additional work by 268.An Hans Huebner Aq hans@artcom.de 269