Provided by: setcd_1.5-6.1_amd64 bug

NAME

       setcd - set various flags to control the behaviour of your cdrom device.

SYNOPSIS

       setcd [-hirs] [-ceflot 0|1] [-dx arg] [device ...]

DESCRIPTION

       Setcd  is  a  program that allows you to control the behaviour of your Linux cdrom device.
       There are a number of ways you can control the behaviour of your cdrom  drive:  should  it
       try to close the tray upon mounting a cdrom when your happened to have left the tray open,
       or should it eject the tray (or caddy) upon unmounting the cdrom? Should it lock the  door
       when  some  process  uses  the  cdrom  or  not? Should the kernel try to ensure that there
       actually is a cd in the drive, and that it is of the right type (i.e., a data cd  in  case
       of a mount, or an audio cd in case of a play operation)?

       Setcd  can  also  inform  you  on  the  current  configuration  of the drive, and can give
       information on the status of the drive; whether or not a cd is loaded, what  the  type  is
       (audio/data),  and  some  basic  information  of  the disc (total playing time for audio /
       volume name for data).  Setcd can list/probe/configure  several  cdrom  devices  at  once,
       independent  of  their  low-level  implementation.  Finally,  setcd can select a disc in a
       multi-disc cdrom player (juke-box), and set the operating speed of the player.

OPTIONS

       Options come in three flavours: without arguments, with one boolean type argument and with
       a  numeric  argument. For boolean type arguments, 0 means `clear option,' and 1 means `set
       option.' Several options may be given at the same time. Following the options, a  list  of
       cdrom device names can be given, for which the operations will take place. If no device is
       given, the default value /dev/cdrom will be used.

       -c 0|1 Clear/set auto-close flag. If the cdrom device is opened  for  data  access  (e.g.,
              using  mount(1) ) and the tray is found open, an attempt is made to close the tray.
              This is considered `desired' behaviour but people with old cd player  programs  may
              disagree.  A  cd  player  that  opens  the  device  at regular intervals would have
              problems leaving the tray ejected, if there were no special arrangements  taken  to
              support  cd player programs. In the new interface they can specify in their open(2)
              call that they wish to open the device just for issuing ioctl(2) calls. Instead  of
              clearing this option, consider upgrading your cd player program.

       -d drive
              Selects the cd in slot number drive in case the cdrom player is a juke-box model.

       -e 0|1 Clear/set  EJECT_SW flag. This is basically identical to controlling the auto-close
              and auto-open flags simultaneously. The EJECT_SW flag enables closing the tray upon
              mounting  a  cdrom,  and  opening  the tray upon unmounting it again. The option is
              included to support the old-style  cdrom  behaviour  (many  low-level  driver  have
              implemented the ioctl-command connected to this flag).

       -f 0|1 Clear/set   use-fflags   flag.   The   new  cdrom  interface  specifies  a  special
              interpretation of the O_NONBLOCK option in the open(2) call for cdrom devices. When
              this  option  is  used, and the use-fflags option is set, the cdrom driver will not
              attempt to do anything to make the open() call more successful;  the  tray  is  not
              closed upon opening, no cd type checking is performed, in fact the open() call will
              always  succeed.  This  allows  user-level  programs  to  issue  ioctl()   commands
              regardless of the state in which the drive is. Setting this option is the preferred
              state.  Users may wish to clear this option in case they  have  an  old  cd  player
              program  that  does  not  support the O_NONBLOCK option, but have a new style cdrom
              driver (i.e., IDE, SCSI or cm206).

       -h     Print copyright information and terse help.

       -i     Give information on the cdrom drive. The status of the drive is  checked,  possible
              outcome is (a) no disc inserted, (b) tray is open, (c) drive is not ready, (d) disc
              is found. In the last case, an attempt is made to determine the type of disc (audio
              or one of 4 types of data disc), and for both "audio" and "data disc type 1|2" some
              additional information is given. Currently for data discs this is the volume  name,
              publisher  and  data preparer. For audio discs the extra information is very terse,
              you may enjoy a full-fledged audio cd player program better.

       -l 0|1 Clear/set locking flag. When this flag is set, the drive door is locked  while  the
              cdrom  devices  is  opened,  e.g., when a cdrom is mounted. Not locking the door is
              undesired behaviour, because this may lead to file system corruption if a cdrom  is
              removed while being mounted.

       -o 0|1 Clear/set auto-open flag. When this flag is set, and the last process that uses the
              cdrom device closes the device, an attempt is made  to  eject  the  tray.  Care  is
              taken,  that  processes that used the O_NONBLOCK option in opening the device, will
              not cause such an auto-eject. Yet, we consider this auto-eject behaviour undesired.
              In  most  cases, this behaviour is combined with the auto-close behaviour, in which
              case the option "-e" is the preferred usage.

       -r     Resets all options to a default behaviour. Using this option is equivalent to  "-c1
              -f1  -l1  -o0  -t1",  i.e., all options set in a way we consider `desired.' For the
              current development kernel, this is identical to the default  settings  apart  from
              the  type-checking flag, because this flag relies on a very modern kernel, libc and
              cdrom players.

       -s     Gives the current status of the option flags. Information  on  the  following  flag
              settings is giver, one per line: (a) auto-close, (b) auto-open, (c) use-fflags, (d)
              tray-locking, (e) type-checking.

       -t 0|1 Clear/set cd type checking flag. When this option is set, the kernel will check the
              type  of cd upon various operations. A system error "Wrong medium type" is given if
              the generic cdrom driver receives an open-for-data call while an audio cd is inside
              the drive, or a playing command is received while a data disc is in the drive. This
              behaviour is considered superior over kernel time-outs  and  other  implementation-
              dependent  behaviour  found on the old-style cdrom interface. However, this feature
              is relatively new, and requires kernel version 2.1.27 or later, and libc-5.4.24  or
              later.  Moreover, if you use an audio cd player program, it must use the O_NONBLOCK
              open flag (see option "-f"). These stringent constraints made the  current  kernels
              to  have this option turned off, while people using setcd are considered modern and
              progressive enough to have this option selected by default using the "-r" option.

       -x speed
              Sets the head-rate of the cdrom player to speed times 150 KB/sec,  or  speed  times
              real-time  audio  playback.  The  special value 0 is interpreted as auto-selection:
              data cd's are read at maximum head-rate, while audio  cd's  are  played  at  normal
              speed.   There  are  a  few  reasons  for having the speed to be selectable.  Badly
              pressed cdroms may benefit from less-than-maximum head rate.  Modern  cdrom  drives
              can  obtain  very high head rates, but these drives tend to make an annoyingly loud
              noise. A lower speed may reduce this.

HISTORY

       Traditionally, up to the 2.0 Linux kernel line, the behaviour  of  the  cdrom  access  was
       determined  by  the low-level driver implementation, which varied between different brands
       of drives. Since kernel 1.3.late, an extra interface layer has been  defined  between  the
       kernel and user level programs, that makes the behaviour of the cdrom drive independent of
       the low-level driver. The first driver to respect the new interface was, surprisingly, the
       outdated  Philips/LMS  cm206 in kernel 2.0.  Nowadays, all new cdrom drives are either IDE
       or SCSI, and these drivers support the new cdrom interface in the kernel 2.1 line. We hope
       that  the  other `old' cdrom divers will eventually support the new interface, so that the
       behaviour of Linux cdrom drives is truly uniform.

       The new cdrom interface level was actually inspired after writing  a  volume  daemon  that
       automatically  mounts a cdrom at the location /cdrom/volume upon insertion of the disc.  I
       then found out that there was a need for finding out  the  status  of  the  drive  without
       trying  to  read  data,  and  that  the uniformity of cdrom drivers was a mess. The volume
       daemon has not been finished yet, but progress has been made in convincing the Linux cdrom
       driver community to comply to the proposed standard.

DIAGNOSTICS

       Setting  or  clearing an option will result in a message indicating the new status of that
       option. Operations not supported by the underlying hardware, e.g.,  disc  selection,  will
       result  in  an  error condition. Several other ioctls may result an error condition if the
       low-level drivers don't support that particular ioctl.

FILES

       /dev/cdrom
              The default cdrom device. In most installations, this is a  symbolic  link  to  the
              only  cdrom device on the system. In multi cdrom systems, the cdrom devices have to
              be explicitly named on the command line.
       /usr/include/linux/ucdrom.h
              The header file for the new cdrom interface. Please consult this file first if  you
              want  to use ioctl calls in your program to control the cdrom drives. Maybe you can
              get want you want by controlling the behaviour of the  cdrom,  instead  of  issuing
              direct  commands. At any rate, use the O_NONBLOCK option if you open the device for
              ioctl-commanding.
       /usr/include/fcntl.h
              Location where O_NONBLOCK is defined.
       /usr/src/linux/Documentation/cdrom/cdrom-standard.tex
              A piece of proza originally written for cdrom driver developers. However, cd player
              program  developers  may  benefit from the explanation of new ioctls defined in the
              new cdrom interface. You can view the documentation by issuing
                          latex cdrom-standard.tex
                          xdvi cdrom-standard
              I am sorry that you'll have to install TeX, latex and xdvi first, but you may  have
              success in reading the plain latex source; after all, it is ASCII.

BUGS

       Long-style options are not supported.

TO DO

       CD  medium  catalog number could be given for audio cd's. However, not many cd's bare that
       kind of information.

       Somehow convince the `old-style' cdrom driver developers to adapt their drivers to the new
       interface, it shouldn't be that much work.

       Write texinfo documentation.

AUTHOR

       Setcd  is  written  by David A. van Leeuwen <david@elseware.nl>, the author of the earlier
       mentioned new cdrom interface and the cm206 cdrom driver.

SEE ALSO

       mount(1), open(2), ioctl(2).