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