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