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