Sweep-fix man page section order to match mdoc(7), part 5/5.
[dragonfly.git] / usr.sbin / wormcontrol / wormcontrol.8
1 .\"
2 .\" Copyright (C) 1996
3 .\"   interface business GmbH
4 .\"   Tolkewitzer Strasse 49
5 .\"   D-01277 Dresden
6 .\"   F.R. Germany
7 .\"
8 .\" All rights reserved.
9 .\"
10 .\" Written by Joerg Wunsch <joerg_wunsch@interface-business.de>
11 .\"
12 .\"
13 .\" Redistribution and use in source and binary forms, with or without
14 .\" modification, are permitted provided that the following conditions
15 .\" are met:
16 .\" 1. Redistributions of source code must retain the above copyright
17 .\"    notice, this list of conditions and the following disclaimer.
18 .\" 2. Redistributions in binary form must reproduce the above copyright
19 .\"    notice, this list of conditions and the following disclaimer in the
20 .\"    documentation and/or other materials provided with the distribution.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR(S) ``AS IS'' AND ANY
23 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
25 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR(S) BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
27 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT
28 .\" OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
29 .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
30 .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
31 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
32 .\" USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
33 .\" DAMAGE.
34 .\"
35 .\" $FreeBSD: src/usr.sbin/wormcontrol/wormcontrol.8,v 1.14.2.1 2000/12/27 13:50:37 ru Exp $
36 .\" $DragonFly: src/usr.sbin/wormcontrol/Attic/wormcontrol.8,v 1.4 2006/02/17 19:40:30 swildner Exp $
37 .\"
38 .\" arrgh, hilit19 needs this" :-(
39 .Dd January 27, 1996
40 .Os
41 .Dt WORMCONTROL 8
42 .Sh NAME
43 .Nm wormcontrol
44 .Nd control the CD-R driver
45 .Sh SYNOPSIS
46 .Nm
47 .Op Fl f Ar device
48 .Ar command
49 .Op Ar params...
50 .Sh DESCRIPTION
51 The
52 .Nm
53 utility is used to control the behaviour of the
54 .Xr worm 4
55 driver in order to adjust various parameters of a recordable CD
56 .Pq CD-R .
57 .Pp
58 Unlike many other devices, CD-R's require a very strict handling order.
59 Prior to writing data, the speed of the drive must be selected, and
60 the drive can also be turned into a
61 .Ql dummy
62 mode, where every action is only performed with the laser turned off.
63 This way, it's possible to test whether the environment provides a
64 sufficiently high data flow rate in order to actually burn the CD-R,
65 without destroying the medium in case of a catastrophic failure.
66 .Pp
67 In order to write a new track, the drive must be told whether the new
68 track will become an audio or a data track.  Audio tracks are written
69 with a block size of 2352 bytes, while data tracks have 2048 bytes per
70 block.  For audio tracks, the driver does further need to know
71 whether the data are recorded with a preemphasis.
72 .Pp
73 Once all tracks of a session have been written, the disk must be
74 .Em fixated .
75 This writes the table of contents and leadout information to the disk.
76 The disk won't be usable without doing this.
77 .Pp
78 The following options are available:
79 .Bl -tag -width ident
80 .It Fl f Ar device
81 Use
82 .Ar device
83 instead of the default
84 .Pa /dev/rworm0 .
85 .It prepdisk Ar single \&| double Op Ar dummy
86 Prepare the disk for recording.  This must be done before any tracks
87 can be prepared, and remains in effect until the session has been
88 fixated.  Either single speed
89 .Pq for audio data
90 or double speed
91 .Pq for CD-ROM data
92 must be selected, and optionally, the argument
93 .Ar dummy
94 can be used to tell the drive to keep the laser turned off, for testing.
95 .It track Ar audio \&| data Op Ar preemp
96 Inform the driver about the format of the next track.  Either
97 .Ar audio
98 or
99 .Ar data
100 .Pq CD-ROM
101 must be selected, with an optional argument
102 .Ar preemp
103 that must be specified for an audio track where data records with
104 preemphasis are being used.  Once this command has been successfully
105 specified, the track is ready for being written.
106 .It fixate Ar toc-type Op Ar onp
107 Once all tracks have been written, this closes the current session.
108 The argument
109 .Ar toc-type
110 is a single digit between 0 and 4, with the following meaning:
111 .Bl -item
112 .It
113 0     CD audio
114 .It
115 1     CD-ROM
116 .It
117 2     CD-ROM with first track in mode 1
118 .It
119 3     CD-ROM with first track in mode 2
120 .It
121 4     CDI
122 .El
123 .Pp
124 The optional argument
125 .Ar onp
126 stands for
127 .Dq open next program area ,
128 which means that the next session on the CD-R will be opened and can
129 be recorded in the future.  Otherwise, the CD-R will be closed and
130 remains unchangeable.
131 .It blank
132 Blank a CD-RW disk.
133 .It nextwriteable
134 Sets the next writeable location on the drive, used when writing
135 more than one track ie CD-DA (audio) disks.
136 .El
137 .Sh FILES
138 .Bl -tag -width /usr/share/examples/worm/* -compact
139 .It Pa /usr/share/examples/worm/*
140 .El
141 .Sh EXAMPLES
142 The typical sequence of burning a data CD-R looks like:
143 .Bd -literal
144 # wormcontrol prepdisk double
145 # wormcontrol track data
146 # rtprio 5 team -v 1m 5 < cdrom.image | rtprio 5 dd of=/dev/rworm0 obs=20k
147 # wormcontrol fixate 1
148 .Ed
149 .Pp
150 Note that the
151 .Xr dd 1
152 command above is mainly used in order to
153 .Dq slice
154 the data stream.  It's particularly useful when recording audio data
155 with their rather unusual blocksize.  Since the underlying device is a
156 .Em raw
157 device, the blocksize used in that command must be an integral multiple
158 of the CD-R blocksize.
159 .Pp
160 The mentioned command
161 .Xr team 1
162 is not part of the base system, but comes extremely handy in order to
163 pipe a constant data stream into the CD recorder.
164 .Sh DIAGNOSTICS
165 Error codes for the underlying
166 .Xr ioctl 2
167 commands are printed by the
168 .Xr err 3
169 facility.
170 .Sh SEE ALSO
171 .Xr dd 1 ,
172 .Xr team 1 ,
173 .Xr ioctl 2 ,
174 .Xr err 3 ,
175 .Xr worm 4
176 .Sh HISTORY
177 .Nm Wormcontrol
178 is currently under development.
179 .Sh AUTHORS
180 The program has been contributed by
181 .An J\(:org Wunsch ,
182 Dresden.