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.2 2003/06/17 04:30:04 dillon 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 DIAGNOSTICS
 138 Error codes for the underlying
 139 .Xr ioctl 2
 140 commands are printed by the
 141 .Xr err 3
 142 facility.
 143 .Sh EXAMPLES
 144 The typical sequence of burning a data CD-R looks like:
 145 .Bd -literal
 146 # wormcontrol prepdisk double
 147 # wormcontrol track data
 148 # rtprio 5 team -v 1m 5 < cdrom.image | rtprio 5 dd of=/dev/rworm0 obs=20k
 149 # wormcontrol fixate 1
 150 .Ed
 151 .Pp
 152 Note that the
 153 .Xr dd 1
 154 command above is mainly used in order to
 155 .Dq slice
 156 the data stream.  It's particularly useful when recording audio data
 157 with their rather unusual blocksize.  Since the underlying device is a
 158 .Em raw
 159 device, the blocksize used in that command must be an integral multiple
 160 of the CD-R blocksize.
 161 .Pp
 162 The mentioned command
 163 .Xr team 1
 164 is not part of the base system, but comes extremely handy in order to
 165 pipe a constant data stream into the CD recorder.
 166 .Sh FILES
 167 .Bl -tag -width /usr/share/examples/worm/* -compact
 168 .It Pa /usr/share/examples/worm/*
 169 .El
 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.