xref: /netbsd-src/bin/chio/chio.1 (revision 75f6d617e282811cb173c2ccfbf5df0dd71f7045)
1.\"	$NetBSD: chio.1,v 1.16 2012/03/17 11:09:29 wiz Exp $
2.\"
3.\" Copyright (c) 1996, 1998, 1999 The NetBSD Foundation, Inc.
4.\" All rights reserved.
5.\"
6.\" This code is derived from software contributed to The NetBSD Foundation
7.\" by Jason R. Thorpe of the Numerical Aerospace Simulation Facility,
8.\" NASA Ames Research Center.
9.\"
10.\" Redistribution and use in source and binary forms, with or without
11.\" modification, are permitted provided that the following conditions
12.\" are met:
13.\" 1. Redistributions of source code must retain the above copyright
14.\"    notice, this list of conditions and the following disclaimer.
15.\" 2. Redistributions in binary form must reproduce the above copyright
16.\"    notice, this list of conditions and the following disclaimer in the
17.\"    documentation and/or other materials provided with the distribution.
18.\"
19.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
20.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
21.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
22.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
23.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
24.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
25.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
26.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
27.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29.\" POSSIBILITY OF SUCH DAMAGE.
30.\"
31.Dd September 8, 1999
32.Dt CHIO 1
33.Os
34.Sh NAME
35.Nm chio
36.Nd medium changer control utility
37.Sh SYNOPSIS
38.Nm
39.Op Fl f Ar changer
40.Ar command
41.Ar arg1
42.Ar arg2
43.Oo
44.Ar arg3 Oo ...
45.Oc
46.Oc
47.Sh DESCRIPTION
48.Nm
49is used to control the operation of medium changers, such as those found
50in tape and optical disk jukeboxes.
51.Pp
52The options are as follows:
53.Bl -tag -width indent
54.It Fl f Ar changer
55Use the device
56.Pa changer
57rather than the default device
58.Pa /dev/ch0 .
59.El
60.Pp
61The default changer may be overridden by setting the environment variable
62.Ev CHANGER
63to the desired changer device.
64.Pp
65A medium changer apparatus is made up of
66.Pa elements .
67There are four element types:
68.Pa picker
69(medium transport),
70.Pa slot
71(storage),
72.Pa portal
73(import/export), and
74.Pa drive
75(data transfer).
76In this command description, the shorthand
77.Ic ET
78will be used to represent an element type, and
79.Ic EU
80will be used to represent an element unit.
81For example, to represent
82the first robotic arm in the changer, the ET would be
83.Dq picker
84and the EU would be
85.Dq 0 .
86.Sh SUPPORTED COMMANDS
87.Nm
88.Ic move
89.Ar \*[Lt]from ET\*[Gt] \*[Lt]from EU\*[Gt] \*[Lt]to ET\*[Gt] \*[Lt]to EU\*[Gt]
90.Op Ar inv
91.Pp
92Moves the media unit from
93.Pa \*[Lt]from ET/EU\*[Gt]
94to
95.Pa \*[Lt]to ET/EU\*[Gt] .
96If the optional modifier
97.Pa inv
98is specified, the media unit will be inverted before insertion.
99.Pp
100.Nm
101.Ic exchange
102.Ar \*[Lt]src ET\*[Gt] \*[Lt]src EU\*[Gt] \*[Lt]dst1 ET\*[Gt] \*[Lt]dst1 EU\*[Gt]
103.Op Ar \*[Lt]dst2 ET\*[Gt] \*[Lt]dst2 ET\*[Gt]
104.Op Ar inv1
105.Op Ar inv2
106.Pp
107Performs a media unit exchange operation.
108The media unit in
109.Pa \*[Lt]src ET/EU\*[Gt]
110is moved to
111.Pa \*[Lt]dst1 ET/EU\*[Gt]
112and the media unit previously in
113.Pa \*[Lt]dst1 ET/EU\*[Gt]
114is moved to
115.Pa \*[Lt]dst2 ET/EU\*[Gt] .
116In the case of a simple exchange,
117.Pa \*[Lt]dst2 ET/EU\*[Gt]
118is omitted and the values
119.Pa \*[Lt]src ET/EU\*[Gt]
120are used in their place.
121The optional modifiers
122.Pa inv1
123and
124.Pa inv2
125specify whether the media units are to be inverted before insertion into
126.Pa \*[Lt]dst1 ET/EU\*[Gt]
127and
128.Pa \*[Lt]dst2 ET/EU\*[Gt]
129respectively.
130.Pp
131Note that not all medium changers support the
132.Ic exchange
133operation; The changer must have multiple free pickers or emulate
134multiple free pickers with transient storage.
135.Pp
136.Nm
137.Ic position
138.Ar \*[Lt]to ET\*[Gt] \*[Lt]to EU\*[Gt]
139.Op Ar inv
140.Pp
141Position the picker in front of the element described by
142.Pa \*[Lt]to ET/EU\*[Gt] .
143If the optional modifier
144.Pa inv
145is specified, the media unit will be inverted before insertion.
146.Pp
147Note that not all changers behave as expected when issued this command.
148.Pp
149.Nm
150.Ic params
151.Pp
152Report the number of slots, drives, pickers, and portals in the changer,
153and which picker unit the changer is currently configured to use.
154.Pp
155.Nm
156.Ic getpicker
157.Pp
158Report which picker unit the changer is currently configured to use.
159.Pp
160.Nm
161.Ic setpicker
162.Ar \*[Lt]unit\*[Gt]
163.Pp
164Configure the changer to use picker
165.Pa \*[Lt]unit\*[Gt] .
166.Pp
167.Nm
168.Ic status
169.Oo Ar \*[Lt]type\*[Gt] Oo unit Oo count Oc Oc Oc
170.Op Ar voltags
171.Pp
172Report the status of all elements in the changer.
173If
174.Pa \*[Lt]type\*[Gt]
175is specified, report the status of all elements of type
176.Pa \*[Lt]type\*[Gt] .
177.Pp
178The status bits are defined as follows:
179.Bl -tag -width indent
180.It Nm FULL
181Element contains a media unit.
182.It Nm IMPEXP
183Media was deposited into element by an outside human operator.
184.It Nm EXCEPT
185Element is in an abnormal state.
186.It Nm ACCESS
187Media in this element is accessible by a picker.
188.It Nm EXENAB
189Element supports passing media (exporting) to an outside human operator.
190.It Nm INENAB
191Element supports receiving media (importing) from an outside human operator.
192.El
193.Pp
194If the element is a drive, the device name of the drive will be reported
195if it is available.
196.Pp
197If the
198.Op Ar voltags
199option is specified, primary and alternate volume tag information will
200be reported, if available.
201.Pp
202If the previous location of the media is available, it will also be reported.
203.Pp
204.Nm
205.Ic ielem
206.Pp
207Perform an
208.Em INITIALIZE ELEMENT STATUS
209operation on the changer.
210.Pp
211.Nm
212.Ic cdlu
213.Ar \*[Lt]sub-command\*[Gt]
214.Ar \*[Lt]slot\*[Gt]
215.Pp
216This command is provided for controlling CD-ROM changer mechanisms which
217cannot use the standard changer control interface.
218ATAPI CD-ROM changers fall into this category.
219There are 3 sub-commands:
220.Bl -tag -width indent
221.It Nm load
222Loads the media from the specified slot into the CD-ROM drive.
223.It Nm unload
224Unloads the media from the CD-ROM drive and returns it to the specified slot.
225.It Nm abort
226Aborts any pending load or unload operation.
227.El
228.Sh FILES
229/dev/ch0 - default changer device
230.Sh EXAMPLES
231.Dl chio -f /dev/ch0 move slot 3 drive 0
232.Pp
233Moves the media in slot 3 (fourth slot) to drive 0 (first drive).
234.Pp
235.Dl chio setpicker 2
236.Pp
237Configures the changer to use picker 2 (third picker) for operations.
238.Pp
239.Dl chio -f /dev/cd0a cdlu load 1
240.Pp
241Loads the media from slot (second slot) into the CD-ROM drive.
242.Pp
243.Dl chio -f /dev/ch1 status
244.Pp
245Returns status of all elements in the second changer.
246.Sh SEE ALSO
247.Xr mt 1 ,
248.Xr mount 8
249.Sh AUTHORS
250The
251.Nm
252program and SCSI changer driver were originally written by Jason R. Thorpe
253for
254.Lk http://www.and.com/ And Communications .
255Additional development was
256done by Jason R. Thorpe for the Numerical Aerospace Simulation Facility,
257NASA Ames Research Center.
258