1.\" $OpenBSD: chio.1,v 1.36 2022/02/18 02:07:15 jsg Exp $ 2.\" $NetBSD: chio.1,v 1.1.1.1 1996/04/03 00:34:38 thorpej Exp $ 3.\" 4.\" Copyright (c) 1996 Jason R. Thorpe <thorpej@and.com> 5.\" All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. All advertising materials mentioning features or use of this software 16.\" must display the following acknowledgments: 17.\" This product includes software developed by Jason R. Thorpe 18.\" for And Communications, http://www.and.com/ 19.\" 4. The name of the author may not be used to endorse or promote products 20.\" derived from this software without specific prior written permission. 21.\" 22.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 23.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 24.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 25.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 26.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 27.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 28.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 29.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 30.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 32.\" SUCH DAMAGE. 33.\" 34.Dd $Mdocdate: February 18 2022 $ 35.Dt CHIO 1 36.Os 37.Sh NAME 38.Nm chio 39.Nd medium changer control utility 40.Sh SYNOPSIS 41.Nm chio 42.Op Fl f Ar changer 43.Ar command 44.Op Ar arg ... 45.Sh DESCRIPTION 46The 47.Nm 48utility is used to control the operation of medium changers, such as those 49found in tape and optical disk jukeboxes. 50.Pp 51The options are as follows: 52.Bl -tag -width 10n 53.It Fl f Ar changer 54Use the device 55.Ar changer 56rather than the default device 57.Pa /dev/ch0 . 58.El 59.Pp 60A medium changer apparatus is made up of 61.Em elements . 62There are five element types: 63.Em picker 64(medium transport), 65.Em slot 66(storage), 67.Em portal 68(import/export), 69.Em drive 70(data transfer), and 71.Em voltag 72(select by volume identifier). 73The 74.Em voltag 75pseudo-element type allows the selection of tapes by their volume code, 76which is typically a barcode on the tape. 77In this command description, the shorthand 78.Sq ET 79will be used to represent an element type, and 80.Sq EU 81will be used to represent an element unit. 82For example, to represent 83the first robotic arm in the changer, the ET would be 84.Dq picker 85and the EU would be 86.Dq 0 . 87.Pp 88The following commands are supported: 89.Bl -tag -width Ds 90.It Xo 91.Cm exchange 92.Ar src-ET src-EU dst1-ET dst1-EU 93.Op Ar dst2-ET dst2-EU 94.Op Cm inv1 95.Op Cm inv2 96.Xc 97Performs a media unit exchange operation. 98The media unit in 99.Ar src-ET Ns / Ns Ar src-EU 100is moved to 101.Ar dst1-ET Ns / Ns Ar dst1-EU 102and the media unit previously in 103.Ar dst1-ET Ns / Ns Ar dst1-EU 104is moved to 105.Ar dst2-ET Ns / Ns Ar dst2-EU . 106In the case of a simple exchange, 107.Ar dst2-ET Ns / Ns Ar dst2-EU 108is omitted and the values 109.Ar src-ET Ns / Ns Ar src-EU 110are used in their place. 111The optional modifiers 112.Cm inv1 113and 114.Cm inv2 115specify whether the media units are to be inverted before insertion into 116.Ar dst1-ET Ns / Ns Ar dst2-EU 117and 118.Ar dst2-ET Ns / Ns Ar dst2-EU 119respectively. 120.Pp 121Note that not all medium changers support the 122.Cm exchange 123operation; the changer must have multiple free pickers or emulate 124multiple free pickers with transient storage. 125.It Cm getpicker 126Report which picker unit the changer is currently configured to use. 127.It Xo 128.Cm move 129.Ar from-ET from-EU to-ET to-EU 130.Op Cm inv 131.Xc 132Moves the media unit from 133.Ar from-ET Ns / Ns Ar from-EU 134to 135.Ar to-ET Ns / Ns Ar to-EU . 136If the optional modifier 137.Cm inv 138is specified, the media unit will be inverted before insertion. 139If 140.Ar from-ET 141is a drive, 142.Nm 143will first attempt to open and perform an 144.Dv MTOFFL 145operation on the 146.Xr st 4 147device corresponding to 148.Ar from-EU . 149By default, the 150.Xr st 4 151device 152.No /dev/rst Ns Ar X 153is used, where 154.Ar X 155is the 156.Ar from-EU . 157This mapping can be changed by using the 158.Xr chio.conf 5 159file. 160.It Cm params 161Report the number of slots, drives, pickers, and portals in the changer, 162and which picker unit the changer is currently configured to use. 163.It Cm position Ar to-ET to-EU Op Cm inv 164Position the picker in front of the element described by 165.Ar to-ET Ns / Ns Ar to-EU . 166If the optional modifier 167.Cm inv 168is specified, the media unit will be inverted before insertion. 169.Pp 170Note that not all changers behave as expected in response to this command. 171.It Cm setpicker Ar unit 172Configure the changer to use picker 173.Ar unit . 174.It Cm status 175.Op Fl vVa 176.Op Ar ET 177Report the status of all elements in the changer. 178If 179.Ar ET 180is specified, report the status of all elements of type 181.Ar ET . 182.Bl -tag -width Ds 183.It Fl v 184Print the primary volume tag for each loaded medium, if any. 185The volume 186tag is printed as 187.Dq \*(LtLABEL:SERIAL\*(Gt . 188.It Fl V 189Print the alternate volume tag for each loaded medium, if any. 190.It Fl a 191Print all additional information (as in 192.Fl vV ) . 193.El 194.Pp 195The status bits output are defined as follows: 196.Bl -tag -width indent 197.It Dv FULL 198Element contains a media unit. 199.It Dv IMPEXP 200Media was deposited into element by an outside human operator. 201.It Dv EXCEPT 202Element is in an abnormal state. 203.It Dv ACCESS 204Media in this element is accessible by a picker. 205.It Dv EXENAB 206Element supports passing media (exporting) to an outside human operator. 207.It Dv INENAB 208Element supports receiving media (importing) from an outside human operator. 209.El 210.El 211.Sh ENVIRONMENT 212.Bl -tag -width CHANGER 213.It Ev CHANGER 214The default changer may be overridden by setting this environmental 215variable to the desired changer device. 216.El 217.Sh FILES 218.Bl -tag -width "/etc/chio.confXX" 219.It Pa /dev/ch0 220Default changer device. 221.It Pa /etc/chio.conf 222Optional configuration file to set up a non-default mapping between 223.Xr st 4 224devices and changer drives. 225.El 226.Sh EXAMPLES 227Move the media in slot 3 (fourth slot) to drive 0 (first drive): 228.Pp 229.Dl # chio move slot 3 drive 0 230.Pp 231Move the media with volume tag 000007L2 to drive 1 (second drive): 232.Pp 233.Dl # chio move voltag 00007L2 drive 1 234.Pp 235Configure the changer to use picker 2 (third picker) for operations: 236.Pp 237.Dl # chio setpicker 2 238.Sh SEE ALSO 239.Xr mt 1 , 240.Xr ch 4 , 241.Xr st 4 , 242.Xr chio.conf 5 243.Sh HISTORY 244A 245.Nm 246utility appeared in 247.Nx 1.3 . 248.Sh AUTHORS 249The 250.Nm 251program and SCSI changer driver were written by 252.An Jason R. Thorpe 253for And Communications. 254