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: src/bin/chio/chio.1,v 1.10.2.8 2003/05/16 22:43:15 keramida Exp $ 34.\" $DragonFly: src/bin/chio/chio.1,v 1.4 2008/09/07 07:51:39 swildner Exp $ 35.\" 36.Dd May 14, 1998 37.Dt CHIO 1 38.Os 39.Sh NAME 40.Nm chio 41.Nd medium changer control utility 42.Sh SYNOPSIS 43.Nm 44.Op Fl f Ar changer 45.Ar command 46.Op Fl <flags> 47.Ar arg1 48.Ar arg2 49.Op Ar arg3 Op ... 50.Sh DESCRIPTION 51The 52.Nm 53utility is used to control the operation of medium changers, such as those 54found in tape and optical disk jukeboxes. 55.Pp 56The options are as follows: 57.Bl -tag -width indent 58.It Fl f Ar changer 59Use the device 60.Ar changer 61rather than the default device 62.Pa /dev/ch0 . 63.El 64.Pp 65The default changer may be overridden by setting the environment variable 66.Ev CHANGER 67to the desired changer device. 68.Pp 69A medium changer apparatus is made up of 70.Em elements . 71There are five element types: 72.Em picker 73(medium transport), 74.Em slot 75(storage), 76.Em portal 77(import/export), 78.Em drive 79(data transfer), and 80.Em voltag 81(select by volume identifier). The 82.Em voltag 83pseudo-element type allows the selection of tapes by their volume tag 84(typically a barcode on the tape). 85.Pp 86In this command description, the shorthand 87.Em ET 88will be used to represent an element type, and 89.Em EU 90will be used to represent an element unit. 91For example, to represent the first robotic arm in the changer, the 92.Em ET 93would be 94.Dq picker 95and the 96.Em EU 97would be 98.Dq 0 . 99.Sh SUPPORTED COMMANDS 100.Bl -tag -width indent 101.It Ic move Xo 102.Ar <from ET> <from EU> <to ET> <to EU> 103.Op Cm inv 104.Xc 105Move the media unit from 106.Ar <from ET/EU> 107to 108.Ar <to ET/EU> . 109If the optional modifier 110.Cm inv 111is specified, the media unit will be inverted before insertion. 112.It Ic exchange Xo 113.Ar <src ET> <src EU> <dst1 ET> <dst1 EU> 114.Op Ar <dst2 ET> <dst2 ET> 115.Op Cm inv1 116.Op Cm inv2 117.Xc 118Perform a media unit exchange operation. The media unit in 119.Ar <src ET/EU> 120is moved to 121.Ar <dst1 ET/EU> 122and the media unit previously in 123.Ar <dst1 ET/EU> 124is moved to 125.Ar <dst2 ET/EU> . 126In the case of a simple exchange, 127.Ar <dst2 ET/EU> 128is omitted and the values 129.Ar <src ET/EU> 130are used in their place. 131The optional modifiers 132.Cm inv1 133and 134.Cm inv2 135specify whether the media units are to be inverted before insertion into 136.Ar <dst1 ET/EU> 137and 138.Ar <dst2 ET/EU> 139respectively. 140.Pp 141Note that not all medium changers support the 142.Ic exchange 143operation; the changer must have multiple free pickers or emulate 144multiple free pickers with transient storage. 145.It Ic return Xo 146.Ar <from ET> <from EU> 147.Xc 148Return the media unit to its source element. 149This command will query the status of the specified media unit, and 150will move it to the element specified in its source attribute. 151This is a convenient way to return media from a drive or portal 152to its previous element in the changer. 153.Pp 154.It Ic position Xo 155.Ar <to ET> <to EU> 156.Op Cm inv 157.Xc 158Position the picker in front of the element described by 159.Ar <to ET/EU> . 160If the optional modifier 161.Cm inv 162is specified, the media unit will be inverted before insertion. 163.Pp 164Note that not all changers behave as expected when issued this command. 165.It Ic params 166Report the number of slots, drives, pickers, and portals in the changer, 167and which picker unit the changer is currently configured to use. 168.It Ic getpicker 169Report which picker unit the changer is currently configured to use. 170.It Ic setpicker Xo 171.Ar <unit> 172.Xc 173Configure the changer to use picker 174.Ar <unit> . 175.Pp 176.It Ic ielem Xo 177.Op Ar <timeout> 178.Xc 179Perform an 180.Em INITIALIZE ELEMENT STATUS 181operation on the changer. The optional 182.Ar <timeout> 183parameter may be given to specify a timeout in seconds for the 184operations. This may be used if the operation takes unusually long 185because of buggy firmware or the like. 186.It Ic voltag Xo 187.Op Fl fca 188.Ar <ET> 189.Ar <EU> 190.Op Ar <label> 191.Op Ar <serial> 192.Xc 193Change volume tag for an element in the media changer. This command 194is only supported by few media changers. If it is not supported by a 195device, using this command will usually result in an 196.Dq Invalid Field in CDB 197error message on the console. 198.Pp 199If the 200.Fl c 201flag is specified, the volume tag of the specified element is 202cleared. If the 203.Fl f 204flag is specified, the volume tag is superseded with the specified 205volume tag even if a volume tag is already defined for the element. 206It is an error to not specify the 207.Fl f 208flag when trying to set a label for an element which already has 209volume tag information defined. 210.Pp 211The command works with the primary volume tag or, if the 212.Fl a 213flag is given, with the alternate volume tag. 214.It Ic status Xo 215.Op Fl vVsSbIa 216.Op Ar <type> 217.Xc 218Report the status of all elements in the changer. If 219.Ar <type> 220is specified, report the status of all elements of type 221.Ar <type> . 222.It Fl v 223Print the primary volume tag for each loaded medium, if any. The volume 224tag is printed as 225.Dq <LABEL:SERIAL> . 226.It Fl V 227Print the alternate volume tag for each loaded medium, if any. 228.It Fl s 229Print the additional sense code and additional sense code qualifier for 230each element. 231.It Fl S 232Print the element source address for each element. 233.It Fl b 234Print SCSI bus information for each element. Note that this information 235is valid only for drives. 236.It Fl I 237Print the internal element addresses for each element. The internal 238element address is not normally used with this driver. It is reported 239for diagnostic purposes only. 240.It Fl a 241Print all additional information (as in 242.Fl vVsSba ) . 243.El 244.Pp 245The status bits are defined as follows: 246.Bl -tag -width indent 247.It FULL 248Element contains a media unit. 249.It IMPEXP 250Media was deposited into element by an outside human operator. 251.It EXCEPT 252Element is in an abnormal state. 253.It ACCESS 254Media in this element is accessible by a picker. 255.It EXENAB 256Element supports passing media (exporting) to an outside human operator. 257.It INENAB 258Element supports receiving media (importing) from an outside human operator. 259.El 260.Sh FILES 261.Bl -tag -width /dev/ch0 -compact 262.It Pa /dev/ch0 263default changer device 264.El 265.Sh EXAMPLES 266.Bl -tag -width indent 267.It Li chio move slot 3 drive 0 268Move the media in slot 3 (fourth slot) to drive 0 (first drive). 269.It Li chio move voltag VOLUME01 drive 0 270Move the media with the barcode VOLUME01 to drive 0 (first drive). 271.It Li chio return drive 0 272Remove the tape from drive 0 (first drive) and return it to its original 273location in the rack. 274.It Li chio setpicker 2 275Configure the changer to use picker 2 (third picker) for operations. 276.El 277.Sh SEE ALSO 278.Xr mt 1 , 279.Xr mount 8 280.Sh AUTHORS 281.An -nosplit 282The 283.Nm 284program and SCSI changer driver were written by 285.An Jason R. Thorpe Aq thorpej@and.com 286for And Communications, 287.Pa http://www.and.com/ . 288.Pp 289Additional work by 290.An Hans Huebner 291.Aq hans@artcom.de 292and 293.An Steve Gunn 294.Aq csg@waterspout.com . 295