READCD(1)             Schily's USER COMMANDS            READCD(1)



NNAAMMEE
       readcd - read or write data Compact Discs

SSYYNNOOPPSSIISS
       rreeaaddccdd ddeevv==_d_e_v_i_c_e [ _o_p_t_i_o_n_s ]


DDEESSCCRRIIPPTTIIOONN
       RReeaaddccdd is used to read or write Compact Discs.

       The _d_e_v_i_c_e refers to _s_c_s_i_b_u_s/_t_a_r_g_e_t/_l_u_n of the drive. Com-
       munication on _S_u_n_O_S is done with the SCSI  general  driver
       ssccgg..   Other operating systems are using a library simula-
       tion of this  driver.   Possible  syntax  is:  ddeevv==  _s_c_s_i_-
       _b_u_s,_t_a_r_g_e_t,_l_u_n  or  ddeevv==  _t_a_r_g_e_t,_l_u_n.  In the latter case,
       the drive has to be connected to the default SCSI  bus  of
       the machine.  _S_c_s_i_b_u_s, _t_a_r_g_e_t and _l_u_n are integer numbers.
       Some operating systems or SCSI  transport  implementations
       may  require  to  specify a filename in addition.  In this
       case the correct syntax for the device  is:  ddeevv==  _d_e_v_i_c_e_-
       _n_a_m_e:_s_c_s_i_b_u_s,_t_a_r_g_e_t,_l_u_n or ddeevv== _d_e_v_i_c_e_n_a_m_e:_t_a_r_g_e_t,_l_u_n.  If
       the name of the device node that  has  been  specified  on
       such  a system refers to exactly one SCSI device, a short-
       hand  in  the  form  ddeevv==  _d_e_v_i_c_e_n_a_m_e:_@  or  ddeevv==  _d_e_v_i_c_e_-
       _n_a_m_e:_@,_l_u_n  may  be  used instead of ddeevv== _d_e_v_i_c_e_n_a_m_e:_s_c_s_i_-
       _b_u_s,_t_a_r_g_e_t,_l_u_n.


       To access remote SCSI devices, you  need  to  prepend  the
       SCSI  device name by a remote device indicator. The remote
       device  indicator  is   either   RREEMMOOTTEE::_u_s_e_r_@_h_o_s_t_:   or
       RREEMMOOTTEE::_h_o_s_t_:
       A  valid remote SCSI device name may be: RREEMMOOTTEE::_u_s_e_r_@_h_o_s_t_:
       to    allow    remote     SCSI     bus     scanning     or
       RREEMMOOTTEE::_u_s_e_r_@_h_o_s_t_:_1_,_0_,_0  to  access the SCSI device at _h_o_s_t
       connected to SCSI bus # 1,target 0 lun 0.


       To access SCSI devices via alternate transport layers, you
       need  to prepend the SCSI device name by a transport layer
       indicator.  The transport layer indicator may be something
       like  UUSSCCSSII:: or AATTAAPPII::.  To get a list of supported trans-
       port layers for your platform, use ddeevv== _H_E_L_P:


       To make rreeaaddccdd portable to all UNIX platforms, the  syntax
       ddeevv==  _d_e_v_i_c_e_n_a_m_e:_s_c_s_i_b_u_s,_t_a_r_g_e_t,_l_u_n  is  preferred  as  is
       hides OS specific knowledge about device  names  from  the
       user.  A specific OS must not necessarily support a way to
       specify a real device file name nor a way to specify _s_c_s_i_-
       _b_u_s,_t_a_r_g_e_t,_l_u_n.


       _S_c_s_i_b_u_s  0  is  the default SCSI bus on the machine. Watch
       the boot  messages  for  more  information  or  look  into
       //vvaarr//aaddmm//mmeessssaaggeess for more information about the SCSI con-
       figuration of your machine.  If you have problems to  fig-
       ure out what values for _s_c_s_i_b_u_s,_t_a_r_g_e_t,_l_u_n should be used,
       try the --ssccaannbbuuss option of ccddrreeccoorrdd.


OOPPTTIIOONNSS
       If no options except the _d_e_v_= option have been  specified,
       rreeaaddccdd goes into interactive mode.  Select a primary func-
       tion and then follow the instructions.


       --vveerrssiioonn
              Print version information and exit.

       ddeevv==_t_a_r_g_e_t
              Sets the SCSI  target  for  the  drive,  see  notes
              above.  A typical device specification is ddeevv==_6_,_0 .
              If a filename must be provided  together  with  the
              numerical  target  specification,  the  filename is
              implementation specific.  The correct  filename  in
              this case can be found in the system specific manu-
              als of the target operating system.  On  a  _F_r_e_e_B_S_D
              system  without  _C_A_M  support,  you need to use the
              control device (e.g.   _/_d_e_v_/_r_c_d_0_._c_t_l).   A  correct
              device   specification   in   this   case   may  be
              ddeevv==_/_d_e_v_/_r_c_d_0_._c_t_l_:_@ .

              On Linux,  drives  connected  to  a  parallel  port
              adapter are mapped to a virtual SCSI bus. Different
              adapters are mapped to different  targets  on  this
              virtual SCSI bus.

              If  no  _d_e_v option is present, ccddrreeccoorrdd will try to
              get the device from the CCDDRR__DDEEVVIICCEE environment.

              If the argument to the ddeevv== option does not contain
              the  characters  ',', '/', '@' or ':', it is inter-
              preted as an label name that may be  found  in  the
              file /etc/default/cdrecord (see FILES section).

       ttiimmeeoouutt==_#
              Set  the  default  SCSI  command timeout value to _#
              seconds.  The default SCSI command timeout  is  the
              minimum timeout used for sending SCSI commands.  If
              a SCSI command fails due to a timeout, you may  try
              to raise the default SCSI command timeout above the
              timeout value of the failed command.  If  the  com-
              mand  runs correctly with a raised command timeout,
              please report the better timeout value and the cor-
              responding  command  to  the author of the program.
              If no _t_i_m_e_o_u_t option is present, a default  timeout
              of 40 seconds is used.

       ddeebbuugg==_#_, --dd
              Set  the  misc  debug  value to # (with debug=#) or
              increment the misc debug level by one (with -d). If
              you  specify _-_d_d_, this equals to ddeebbuugg==_2_.  This may
              help to find problems while opening  a  driver  for
              libscg.   as  well  as with sector sizes and sector
              types.  Using --ddeebbuugg slows down the process and may
              be the reason for a buffer underrun.

       kkddeebbuugg==#, kkdd==#
              Tell  the  ssccgg-driver  to  modify  the kernel debug
              value while SCSI commands are running.

       --ssiilleenntt, --ss
              Do not print out a status report  for  failed  SCSI
              commands.

       --vv     Increment  the  level  of general verbosity by one.
              This is used e.g. to display the  progress  of  the
              process.

       --VV     Increment  the  verbose  level with respect of SCSI
              command transport by  one.   This  helps  to  debug
              problems  during the process, that occur in the CD-
              Recorder.  If you get incomprehensible  error  mes-
              sages you should use this flag to get more detailed
              output.  --VVVV will show data buffer content in addi-
              tion.  Using --VV or --VVVV slows down the process.

       ff==_f_i_l_e Specify  the  filename  where  the output should be
              written or the inout should be  taken  from.  Using
              '-'  as  filename  will  cause rreeaaddccdd to use ssttddoouutt
              resp. ssttddiinn.

       --ww     Switch to write mode. If this option  is  not  pre-
              sent, rreeaaddccdd reads from the specified device.

       --cc22ssccaann
              Scans  the  whole  CD or the range specified by the
              sseeccttoorrss==_r_a_n_g_e for C2 errors. C2 errors  are  errors
              that  are  uncorrectable  after the second stage of
              the 24/28 + 28/32 Reed Solomon correction system at
              audio  level  (2352 bytes sector size). If an audio
              CD has C2 errors, interpolation is needed  to  hide
              the  errors.  If  a  data  CD  has C2 errors, these
              errors are in most cases corrected by  the  ECC/EDC
              code  that makes 2352 bytes out of 2048 data bytes.
              The ECC/EDC code should be able  to  correct  about
              100 C2 error bytes per sector.

              If  you  find  C2 errors you may want to reduce the
              speed using the ssppeeeedd== option as C2 errors may be a
              result of dynamic unbalance on the medium.

       sseeccttoorrss==_r_a_n_g_e
              Specify  a  sector  range that should be read.  The
              range is specified by the starting sector number, a
              minus  sign  and the ending sector number.  The end
              sector is not included in the list, so  sseeccttoorrss==0-0
              will not read anything and may be used to check for
              a CD in the drive.

       ssppeeeedd==#
              Set the speed factor of the read or  write  process
              to  #.  # is an integer, representing a multiple of
              the audio speed.  This is about 150 KB/s for CD-ROM
              and  about  172  KB/s  for  CD-Audio.   If no _s_p_e_e_d
              option is present, rreeaaddccdd will use  maximum  speed.
              Only  MMC  compliant  drives will benefit from this
              option.   The  speed  of  non  MMC  drives  is  not
              changed.

              Using a lower speed may increase the readability of
              a CD or DVD.

       --nnoottrruunncc
              Do not truncate the outputfile when opening it.

       --ffuullllttoocc
              Retrieve a full TOC from the current disk and print
              it in hex.

       --cclloonnee Do  a  clone read. Read the CD with all sub-channel
              data and a full TOC.  The full TOC data will be but
              into a file with similar name as with the ff== option
              but the suffix ..ttoocc added.

       --nnooeerrrroorr
              Do not abort if the high level  error  checking  in
              rreeaaddccdd  found  an  uncorrectable  error in the data
              stream.

       --nnooccoorrrr
              Switch the drive into a mode where it ignores  read
              errors  in data sectors that are a result of uncor-
              rectable ECC/EDC errors before reading.  If  rreeaaddccdd
              completes,  the error recovery mode of the drive is
              switched back to the remembered old mode.

       rreettrriieess==_#
              Set the retry  count  for  high  level  retries  in
              rreeaaddccdd  to  _#.   The  default  is to do 128 retries
              which may be too much if you like to read a CD with
              many unreadable sectors.

       --oovveerrhheeaadd
              Meter the SCSI command overhead time.  This is done
              by executing several commands 1000 times and print-
              ing  the  total  time  used. If you divide the dis-
              played times by 1000, you get the average  overhead
              time for a single command.

EEXXAAMMPPLLEESS
       For  all examples below, it will be assumed that the drive
       is connected to the primary SCSI bus of the  machine.  The
       SCSI target id is set to 2.

       To  read the complete media from a CD-ROM writing the data
       to the file _c_d_i_m_a_g_e_._r_a_w:

           readcd dev=2,0 f=cdimage.raw

       To read sectors from range 150 ...  10000  from  a  CD-ROM
       writing the data to the file _c_d_i_m_a_g_e_._r_a_w:

           readcd dev=2,0 sectors=150-10000 f=cdimage.raw

       To  write  the  data  from  the  file  _c_d_i_m_a_g_e_._r_a_w (e.g. a
       filesystem image from mmkkiissooffss) to a DVD-RAM, call:

           readcd dev=2,0 -w f=cdimage.raw


EENNVVIIRROONNMMEENNTT
       RRSSHH    If the RRSSHH environment is present, the remote  con-
              nection  will  not  be  created  via rrccmmdd(3) but by
              calling the program pointed to by  RRSSHH.   Use  e.g.
              RRSSHH==/usr/bin/ssh  to  create a secure shell connec-
              tion.

              Note that this forces ccddrreeccoorrdd to create a pipe  to
              the   rrsshh((11))  program  and  disallows  ccddrreeccoorrdd  to
              directly access the network socket  to  the  remote
              server.  This makes it impossible to set up perfor-
              mance parameters and slows down the connection com-
              pared to a rroooott initiated rrccmmdd((33)) connection.

       RRSSCCSSII  If  the  RRSSCCSSII  environment  is present, the remote
              SCSI   server   will    not    be    the    program
              //oopptt//sscchhiillyy//ssbbiinn//rrssccssii  but  the program pointed to
              by RRSSCCSSII.  Note that the remote SCSI server program
              name will be ignored if you log in using an account
              that has been created with  a  remote  SCSI  server
              program as login shell.

FFIILLEESS
SSEEEE AALLSSOO
       ccddrreeccoorrdd(1),  mmkkiissooffss(1), ssccgg(7), ffbbkk(7), rrccmmdd(3), sssshh(1).


NNOOTTEESS
       If you don't want to allow users to become  root  on  your
       system,  rreeaaddccdd  may  safely  be installed suid root. This
       allows all users or a group of users with no  root  privi-
       leges  to use rreeaaddccdd..  RReeaaddccdd in this case will only allow
       access to CD-ROM type drives- To give all user  access  to
       use rreeaaddccdd,, enter:

            chown root /usr/local/bin/readcd
            chmod 4711 /usr/local/bin/readcd

       To  give  a  restricted  group  of  users access to rreeaaddccdd
       enter:

            chown root /usr/local/bin/readcd
            chgrp cdburners /usr/local/bin/readcd
            chmod 4710 /usr/local/bin/readcd

       and add a group _c_d_b_u_r_n_e_r_s on your system.

       Never give write permissions for non  root  users  to  the
       _/_d_e_v_/_s_c_g_?   devices  unless  you  would  allow  anybody to
       read/write/format all your disks.

       You should not connect old drives that do not support dis-
       connect/reconnect to either the SCSI bus that is connected
       to the CD-Recorder or the source disk.

       When using rreeaaddccdd  with  the  broken  LLiinnuuxx  SSCCSSII  ggeenneerriicc
       ddrriivveerr..   You  should  note  that rreeaaddccdd uses a hack, that
       tries to emulate the  functionality  of  the  scg  driver.
       Unfortunately,  the  sg driver on LLiinnuuxx has several severe
       bugs:

       +o      It cannot see if a SCSI command could not  be  sent
              at all.

       +o      It  cannot  get  the  SCSI status byte.  RReeaaddccdd for
              that reason cannot report failing SCSI commands  in
              some situations.

       +o      It  cannot  get real DMA count of transfer.  RReeaaddccdd
              cannot tell you if there is an DMA residual  count.

       +o      It  cannot  get number of bytes valid in auto sense
              data.  RReeaaddccdd cannot tell you if  device  transfers
              no sense data at all.

       +o      It  fetches  to  few  data  in  auto  request sense
              (CCS/SCSI-2/SCSI-3 needs >= 18).


DDIIAAGGNNOOSSTTIICCSS
       A typical error message for a SCSI command looks like:

              readcd: I/O error. test unit ready: scsi sendcmd: no error
              CDB:  00 20 00 00 00 00
              status: 0x2 (CHECK CONDITION)
              Sense Bytes: 70 00 05 00 00 00 00 0A 00 00 00 00 25 00 00 00 00 00
              Sense Key: 0x5 Illegal Request, Segment 0
              Sense Code: 0x25 Qual 0x00 (logical unit not supported) Fru 0x0
              Sense flags: Blk 0 (not valid)
              cmd finished after 0.002s timeout 40s

       The first line gives information about  the  transport  of
       the  command.   The  text  after the first colon gives the
       error text for the system call from the view of  the  ker-
       nel.  It  usually is: II//OO eerrrroorr unless other problems hap-
       pen. The next words contain a short  description  for  the
       SCSI command that fails. The rest of the line tells you if
       there were any problems for the transport of  the  command
       over the SCSI bus.  ffaattaall eerrrroorr means that it was not pos-
       sible to transport the command (i.e. no device present  at
       the requested SCSI address).

       The  second  line prints the SCSI command descriptor block
       for the failed command.

       The third line gives information on the SCSI  status  code
       returned  by  the command, if the transport of the command
       succeeds.  This is error information from the SCSI device.

       The  fourth  line  is a hex dump of the auto request sense
       information for the command.

       The fifth line is the error text  for  the  sense  key  if
       available,  followed  by  the  segment number that is only
       valid if the command was a _c_o_p_y command. If the error mes-
       sage  is  not directly related to the current command, the
       text _d_e_f_e_r_r_e_d _e_r_r_o_r is appended.

       The sixth line is the error text for the  sense  code  and
       the  sense  qualifier  if  available.   If the type of the
       device is known, the sense data is decoded from tables  in
       _s_c_s_i_e_r_r_s_._c  .  The text is followed by the error value for
       a field replaceable unit.

       The seventh line prints the block number that  is  related
       to  the  failed  command and text for several error flags.
       The block number may not be valid.

       The eight line reports the timeout set up for this command
       and the time that the command really needed to complete.


BBUUGGSS
CCRREEDDIITTSS
MMAAIILLIINNGG LLIISSTTSS
       If  you  want  to actively take part on the development of
       cdrecord, you may join the cdwriting mailing list by send-
       ing mail to:

            other-cdwrite-request@lists.debian.org

       and  include  the  word  _s_u_b_s_c_r_i_b_e  in the body.  The mail
       address of the list is:

            cdwrite@lists.debian.org


AAUUTTHHOORR
       Joerg Schilling
       Seestr. 110
       D-13353 Berlin
       Germany

       Additional information can be found on:
       http://www.fokus.fhg.de/usr/schilling/cdrecord.html

       If you have support questions, send them to:

       ccddrreeccoorrdd--ssuuppppoorrtt@@bbeerrlliiooss..ddee
       or ootthheerr--ccddwwrriittee@@lliissttss..ddeebbiiaann..oorrgg

       Of you have definitely found a bug, send a mail to:

       ccddrreeccoorrdd--ddeevveellooppeerrss@@bbeerrlliiooss..ddee
       or sscchhiilllliinngg@@ffookkuuss..ffhhgg..ddee

       To subscribe, use:

       hhttttpp::////lliissttss..bbeerrlliiooss..ddee//mmaaiillmmaann//lliissttiinnffoo//ccddrreeccoorrdd--ddeevveelloopp--
       eerrss
       or  hhttttpp::////lliissttss..bbeerrlliiooss..ddee//mmaaiillmmaann//lliissttiinnffoo//ccddrreeccoorrdd--ssuupp--
       ppoorrtt



Joerg Schilling            Version 2.0                  READCD(1)
