Subversion Repositories test_project

                Summary of CDROM ioctl calls.

                ============================

                Edward A. Falk 

                November, 2004

This document attempts to describe the ioctl(2) calls supported by

the CDROM layer.  These are by-and-large implemented (as of Linux 2.6)

in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c

ioctl values are listed in .  As of this writing, they

are as follows:

        CDROMPAUSE              Pause Audio Operation

        CDROMRESUME             Resume paused Audio Operation

        CDROMPLAYMSF            Play Audio MSF (struct cdrom_msf)

        CDROMPLAYTRKIND         Play Audio Track/index (struct cdrom_ti)

        CDROMREADTOCHDR         Read TOC header (struct cdrom_tochdr)

        CDROMREADTOCENTRY       Read TOC entry (struct cdrom_tocentry)

        CDROMSTOP               Stop the cdrom drive

        CDROMSTART              Start the cdrom drive

        CDROMEJECT              Ejects the cdrom media

        CDROMVOLCTRL            Control output volume (struct cdrom_volctrl)

        CDROMSUBCHNL            Read subchannel data (struct cdrom_subchnl)

        CDROMREADMODE2          Read CDROM mode 2 data (2336 Bytes)

                                           (struct cdrom_read)

        CDROMREADMODE1          Read CDROM mode 1 data (2048 Bytes)

                                           (struct cdrom_read)

        CDROMREADAUDIO          (struct cdrom_read_audio)

        CDROMEJECT_SW           enable(1)/disable(0) auto-ejecting

        CDROMMULTISESSION       Obtain the start-of-last-session

                                  address of multi session disks

                                  (struct cdrom_multisession)

        CDROM_GET_MCN           Obtain the "Universal Product Code"

                                   if available (struct cdrom_mcn)

        CDROM_GET_UPC           Deprecated, use CDROM_GET_MCN instead.

        CDROMRESET              hard-reset the drive

        CDROMVOLREAD            Get the drive's volume setting

                                          (struct cdrom_volctrl)

        CDROMREADRAW            read data in raw mode (2352 Bytes)

                                           (struct cdrom_read)

        CDROMREADCOOKED         read data in cooked mode

        CDROMSEEK               seek msf address

        CDROMPLAYBLK            scsi-cd only, (struct cdrom_blk)

        CDROMREADALL            read all 2646 bytes

        CDROMGETSPINDOWN        return 4-bit spindown value

        CDROMSETSPINDOWN        set 4-bit spindown value

        CDROMCLOSETRAY          pendant of CDROMEJECT

        CDROM_SET_OPTIONS       Set behavior options

        CDROM_CLEAR_OPTIONS     Clear behavior options

        CDROM_SELECT_SPEED      Set the CD-ROM speed

        CDROM_SELECT_DISC       Select disc (for juke-boxes)

        CDROM_MEDIA_CHANGED     Check is media changed

        CDROM_DRIVE_STATUS      Get tray position, etc.

        CDROM_DISC_STATUS       Get disc type, etc.

        CDROM_CHANGER_NSLOTS    Get number of slots

        CDROM_LOCKDOOR          lock or unlock door

        CDROM_DEBUG             Turn debug messages on/off

        CDROM_GET_CAPABILITY    get capabilities

        CDROMAUDIOBUFSIZ        set the audio buffer size

        DVD_READ_STRUCT         Read structure

        DVD_WRITE_STRUCT        Write structure

        DVD_AUTH                Authentication

        CDROM_SEND_PACKET       send a packet to the drive

        CDROM_NEXT_WRITABLE     get next writable block

        CDROM_LAST_WRITTEN      get last block written on disc

The information that follows was determined from reading kernel source

code.  It is likely that some corrections will be made over time.

General:

        Unless otherwise specified, all ioctl calls return 0 on success

        and -1 with errno set to an appropriate value on error.  (Some

        ioctls return non-negative data values.)

        Unless otherwise specified, all ioctl calls return -1 and set

        errno to EFAULT on a failed attempt to copy data to or from user

        address space.

        Individual drivers may return error codes not listed here.

        Unless otherwise specified, all data structures and constants

        are defined in 

CDROMPAUSE                      Pause Audio Operation

        usage:

          ioctl(fd, CDROMPAUSE, 0);

        inputs:         none

        outputs:        none

        error return:

          ENOSYS        cd drive not audio-capable.

CDROMRESUME                     Resume paused Audio Operation

        usage:

          ioctl(fd, CDROMRESUME, 0);

        inputs:         none

        outputs:        none

        error return:

          ENOSYS        cd drive not audio-capable.

CDROMPLAYMSF                    Play Audio MSF (struct cdrom_msf)

        usage:

          struct cdrom_msf msf;

          ioctl(fd, CDROMPLAYMSF, &msf);

        inputs:

          cdrom_msf structure, describing a segment of music to play

        outputs:        none

        error return:

          ENOSYS        cd drive not audio-capable.

        notes:

          MSF stands for minutes-seconds-frames

          LBA stands for logical block address

          Segment is described as start and end times, where each time

          is described as minutes:seconds:frames.  A frame is 1/75 of

          a second.

CDROMPLAYTRKIND                 Play Audio Track/index (struct cdrom_ti)

        usage:

          struct cdrom_ti ti;

          ioctl(fd, CDROMPLAYTRKIND, &ti);

        inputs:

          cdrom_ti structure, describing a segment of music to play

        outputs:        none

        error return:

          ENOSYS        cd drive not audio-capable.

        notes:

          Segment is described as start and end times, where each time

          is described as a track and an index.

CDROMREADTOCHDR                 Read TOC header (struct cdrom_tochdr)

        usage:

          cdrom_tochdr header;

          ioctl(fd, CDROMREADTOCHDR, &header);

        inputs:

          cdrom_tochdr structure

        outputs:

          cdrom_tochdr structure

        error return:

          ENOSYS        cd drive not audio-capable.

CDROMREADTOCENTRY               Read TOC entry (struct cdrom_tocentry)

        usage:

          struct cdrom_tocentry entry;

          ioctl(fd, CDROMREADTOCENTRY, &entry);

        inputs:

          cdrom_tocentry structure

        outputs:

          cdrom_tocentry structure

        error return:

          ENOSYS        cd drive not audio-capable.

          EINVAL        entry.cdte_format not CDROM_MSF or CDROM_LBA

          EINVAL        requested track out of bounds

          EIO           I/O error reading TOC

        notes:

          TOC stands for Table Of Contents

          MSF stands for minutes-seconds-frames

          LBA stands for logical block address

CDROMSTOP                       Stop the cdrom drive

        usage:

          ioctl(fd, CDROMSTOP, 0);

        inputs:         none

        outputs:        none

        error return:

          ENOSYS        cd drive not audio-capable.

        notes:

          Exact interpretation of this ioctl depends on the device,

          but most seem to spin the drive down.

CDROMSTART                      Start the cdrom drive

        usage:

          ioctl(fd, CDROMSTART, 0);

        inputs:         none

        outputs:        none

        error return:

          ENOSYS        cd drive not audio-capable.

        notes:

          Exact interpretation of this ioctl depends on the device,

          but most seem to spin the drive up and/or close the tray.

          Other devices ignore the ioctl completely.

CDROMEJECT                      Ejects the cdrom media

        usage:

          ioctl(fd, CDROMEJECT, 0);

        inputs:         none

        outputs:        none

        error returns:

          ENOSYS        cd drive not capable of ejecting

          EBUSY         other processes are accessing drive, or door is locked

        notes:

          See CDROM_LOCKDOOR, below.

CDROMCLOSETRAY                  pendant of CDROMEJECT

        usage:

          ioctl(fd, CDROMEJECT, 0);

        inputs:         none

        outputs:        none

        error returns:

          ENOSYS        cd drive not capable of ejecting

          EBUSY         other processes are accessing drive, or door is locked

        notes:

          See CDROM_LOCKDOOR, below.

CDROMVOLCTRL                    Control output volume (struct cdrom_volctrl)

        usage:

          struct cdrom_volctrl volume;

          ioctl(fd, CDROMVOLCTRL, &volume);

        inputs:

          cdrom_volctrl structure containing volumes for up to 4

          channels.

        outputs:        none

        error return:

          ENOSYS        cd drive not audio-capable.

CDROMVOLREAD                    Get the drive's volume setting

                                          (struct cdrom_volctrl)

        usage:

          struct cdrom_volctrl volume;

          ioctl(fd, CDROMVOLREAD, &volume);

        inputs:         none

        outputs:

          The current volume settings.

        error return:

          ENOSYS        cd drive not audio-capable.

CDROMSUBCHNL                    Read subchannel data (struct cdrom_subchnl)

        usage:

          struct cdrom_subchnl q;

          ioctl(fd, CDROMSUBCHNL, &q);

        inputs:

          cdrom_subchnl structure

        outputs:

          cdrom_subchnl structure

        error return:

          ENOSYS        cd drive not audio-capable.

          EINVAL        format not CDROM_MSF or CDROM_LBA

        notes:

          Format is converted to CDROM_MSF on return

CDROMREADRAW                    read data in raw mode (2352 Bytes)

                                           (struct cdrom_read)

        usage:

          union {

            struct cdrom_msf msf;               /* input */

            char buffer[CD_FRAMESIZE_RAW];      /* return */

          } arg;

          ioctl(fd, CDROMREADRAW, &arg);

        inputs:

          cdrom_msf structure indicating an address to read.

          Only the start values are significant.

        outputs:

          Data written to address provided by user.

        error return:

          EINVAL        address less than 0, or msf less than 0:2:0

          ENOMEM        out of memory

        notes:

          As of 2.6.8.1, comments in  indicate that this

          ioctl accepts a cdrom_read structure, but actual source code

          reads a cdrom_msf structure and writes a buffer of data to

          the same address.

          MSF values are converted to LBA values via this formula:

            lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET;

CDROMREADMODE1                  Read CDROM mode 1 data (2048 Bytes)

                                           (struct cdrom_read)

        notes:

          Identical to CDROMREADRAW except that block size is

          CD_FRAMESIZE (2048) bytes

CDROMREADMODE2                  Read CDROM mode 2 data (2336 Bytes)

                                           (struct cdrom_read)

        notes:

          Identical to CDROMREADRAW except that block size is

          CD_FRAMESIZE_RAW0 (2336) bytes

CDROMREADAUDIO                  (struct cdrom_read_audio)

        usage:

          struct cdrom_read_audio ra;

          ioctl(fd, CDROMREADAUDIO, &ra);

        inputs:

          cdrom_read_audio structure containing read start

          point and length

        outputs:

          audio data, returned to buffer indicated by ra

        error return:

          EINVAL        format not CDROM_MSF or CDROM_LBA

          EINVAL        nframes not in range [1 75]

          ENXIO         drive has no queue (probably means invalid fd)

          ENOMEM        out of memory

CDROMEJECT_SW                   enable(1)/disable(0) auto-ejecting

        usage:

          int val;

          ioctl(fd, CDROMEJECT_SW, val);

        inputs:

          Flag specifying auto-eject flag.

        outputs:        none

        error return:

          ENOSYS        Drive is not capable of ejecting.

          EBUSY         Door is locked

CDROMMULTISESSION               Obtain the start-of-last-session

                                  address of multi session disks

                                  (struct cdrom_multisession)

        usage:

          struct cdrom_multisession ms_info;

          ioctl(fd, CDROMMULTISESSION, &ms_info);

        inputs:

          cdrom_multisession structure containing desired

          format.

        outputs:

          cdrom_multisession structure is filled with last_session

          information.

        error return:

          EINVAL        format not CDROM_MSF or CDROM_LBA

CDROM_GET_MCN                   Obtain the "Universal Product Code"

                                   if available (struct cdrom_mcn)

        usage:

          struct cdrom_mcn mcn;

          ioctl(fd, CDROM_GET_MCN, &mcn);

        inputs:         none

        outputs:

          Universal Product Code

        error return:

          ENOSYS        Drive is not capable of reading MCN data.

        notes:

          Source code comments state:

            The following function is implemented, although very few

            audio discs give Universal Product Code information, which

            should just be the Medium Catalog Number on the box.  Note,

            that the way the code is written on the CD is /not/ uniform

            across all discs!

CDROM_GET_UPC                   CDROM_GET_MCN  (deprecated)

        Not implemented, as of 2.6.8.1

CDROMRESET                      hard-reset the drive

        usage:

          ioctl(fd, CDROMRESET, 0);

        inputs:         none

        outputs:        none

        error return:

          EACCES        Access denied:  requires CAP_SYS_ADMIN

          ENOSYS        Drive is not capable of resetting.

CDROMREADCOOKED                 read data in cooked mode

        usage:

          u8 buffer[CD_FRAMESIZE]

          ioctl(fd, CDROMREADCOOKED, buffer);

        inputs:         none

        outputs:

          2048 bytes of data, "cooked" mode.

        notes:

          Not implemented on all drives.

CDROMREADALL                    read all 2646 bytes

        Same as CDROMREADCOOKED, but reads 2646 bytes.

CDROMSEEK                       seek msf address

        usage:

          struct cdrom_msf msf;

          ioctl(fd, CDROMSEEK, &msf);

        inputs:

          MSF address to seek to.

        outputs:        none

CDROMPLAYBLK                    scsi-cd only, (struct cdrom_blk)

        usage:

          struct cdrom_blk blk;

          ioctl(fd, CDROMPLAYBLK, &blk);

        inputs:

          Region to play

        outputs:        none

CDROMGETSPINDOWN

        usage:

          char spindown;

          ioctl(fd, CDROMGETSPINDOWN, &spindown);

        inputs:         none

        outputs:

          The value of the current 4-bit spindown value.

CDROMSETSPINDOWN

        usage:

          char spindown

          ioctl(fd, CDROMSETSPINDOWN, &spindown);

        inputs:

          4-bit value used to control spindown (TODO: more detail here)

        outputs:        none

CDROM_SET_OPTIONS               Set behavior options

        usage:

          int options;

          ioctl(fd, CDROM_SET_OPTIONS, options);

        inputs:

          New values for drive options.  The logical 'or' of:

            CDO_AUTO_CLOSE      close tray on first open(2)

            CDO_AUTO_EJECT      open tray on last release

            CDO_USE_FFLAGS      use O_NONBLOCK information on open

            CDO_LOCK            lock tray on open files

            CDO_CHECK_TYPE      check type on open for data

        outputs:

          Returns the resulting options settings in the

          ioctl return value.  Returns -1 on error.

        error return:

          ENOSYS        selected option(s) not supported by drive.

CDROM_CLEAR_OPTIONS             Clear behavior options

        Same as CDROM_SET_OPTIONS, except that selected options are

        turned off.

CDROM_SELECT_SPEED              Set the CD-ROM speed

        usage:

          int speed;

          ioctl(fd, CDROM_SELECT_SPEED, speed);

        inputs:

          New drive speed.

        outputs:        none

        error return:

          ENOSYS        speed selection not supported by drive.

CDROM_SELECT_DISC               Select disc (for juke-boxes)

        usage:

          int disk;

          ioctl(fd, CDROM_SELECT_DISC, disk);

        inputs:

          Disk to load into drive.

        outputs:        none

        error return:

          EINVAL        Disk number beyond capacity of drive

CDROM_MEDIA_CHANGED             Check is media changed

        usage:

          int slot;

          ioctl(fd, CDROM_MEDIA_CHANGED, slot);

        inputs:

          Slot number to be tested, always zero except for jukeboxes.

          May also be special values CDSL_NONE or CDSL_CURRENT

        outputs:

          Ioctl return value is 0 or 1 depending on whether the media

          has been changed, or -1 on error.

        error returns:

          ENOSYS        Drive can't detect media change

          EINVAL        Slot number beyond capacity of drive

          ENOMEM        Out of memory

CDROM_DRIVE_STATUS              Get tray position, etc.

        usage:

          int slot;

          ioctl(fd, CDROM_DRIVE_STATUS, slot);

        inputs:

          Slot number to be tested, always zero except for jukeboxes.

          May also be special values CDSL_NONE or CDSL_CURRENT

        outputs:

          Ioctl return value will be one of the following values

          from :

            CDS_NO_INFO         Information not available.

            CDS_NO_DISC

            CDS_TRAY_OPEN

            CDS_DRIVE_NOT_READY

            CDS_DISC_OK

            -1                  error

        error returns:

          ENOSYS        Drive can't detect drive status

          EINVAL        Slot number beyond capacity of drive

          ENOMEM        Out of memory

CDROM_DISC_STATUS               Get disc type, etc.

        usage:

          ioctl(fd, CDROM_DISC_STATUS, 0);

        inputs:         none

        outputs:

          Ioctl return value will be one of the following values

          from :

            CDS_NO_INFO

            CDS_AUDIO

            CDS_MIXED

            CDS_XA_2_2

            CDS_XA_2_1

            CDS_DATA_1

        error returns:  none at present

        notes:

          Source code comments state:

            Ok, this is where problems start.  The current interface for

            the CDROM_DISC_STATUS ioctl is flawed.  It makes the false

            assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc.

            Unfortunately, while this is often the case, it is also

            very common for CDs to have some tracks with data, and some

            tracks with audio.  Just because I feel like it, I declare

            the following to be the best way to cope.  If the CD has

            ANY data tracks on it, it will be returned as a data CD.

            If it has any XA tracks, I will return it as that.  Now I

            could simplify this interface by combining these returns with

            the above, but this more clearly demonstrates the problem

            with the current interface.  Too bad this wasn't designed

            to use bitmasks...         -Erik

            Well, now we have the option CDS_MIXED: a mixed-type CD.

            User level programmers might feel the ioctl is not very

            useful.

                        ---david

CDROM_CHANGER_NSLOTS            Get number of slots

        usage:

          ioctl(fd, CDROM_CHANGER_NSLOTS, 0);

        inputs:         none

        outputs:

          The ioctl return value will be the number of slots in a

          CD changer.  Typically 1 for non-multi-disk devices.

        error returns:  none

CDROM_LOCKDOOR                  lock or unlock door

        usage:

          int lock;

          ioctl(fd, CDROM_LOCKDOOR, lock);

        inputs:

          Door lock flag, 1=lock, 0=unlock

        outputs:        none

        error returns:

          EDRIVE_CANT_DO_THIS   Door lock function not supported.

          EBUSY                 Attempt to unlock when multiple users

                                have the drive open and not CAP_SYS_ADMIN

        notes:

          As of 2.6.8.1, the lock flag is a global lock, meaning that

          all CD drives will be locked or unlocked together.  This is

          probably a bug.

          The EDRIVE_CANT_DO_THIS value is defined in 

          and is currently (2.6.8.1) the same as EOPNOTSUPP

CDROM_DEBUG                     Turn debug messages on/off

        usage:

          int debug;

          ioctl(fd, CDROM_DEBUG, debug);

        inputs:

          Cdrom debug flag, 0=disable, 1=enable

        outputs:

          The ioctl return value will be the new debug flag.

        error return:

          EACCES        Access denied:  requires CAP_SYS_ADMIN

CDROM_GET_CAPABILITY            get capabilities

        usage:

          ioctl(fd, CDROM_GET_CAPABILITY, 0);

        inputs:         none

        outputs:

          The ioctl return value is the current device capability

          flags.  See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc.

CDROMAUDIOBUFSIZ                set the audio buffer size

        usage:

          int arg;

          ioctl(fd, CDROMAUDIOBUFSIZ, val);

        inputs:

          New audio buffer size

        outputs:

          The ioctl return value is the new audio buffer size, or -1

          on error.

        error return:

          ENOSYS        Not supported by this driver.

        notes:

          Not supported by all drivers.

DVD_READ_STRUCT                 Read structure

        usage:

          dvd_struct s;

          ioctl(fd, DVD_READ_STRUCT, &s);

        inputs:

          dvd_struct structure, containing:

            type                specifies the information desired, one of

                                DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT,

                                DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA,

                                DVD_STRUCT_MANUFACT

            physical.layer_num  desired layer, indexed from 0

            copyright.layer_num desired layer, indexed from 0

            disckey.agid

        outputs:

          dvd_struct structure, containing:

            physical            for type == DVD_STRUCT_PHYSICAL

            copyright           for type == DVD_STRUCT_COPYRIGHT

            disckey.value       for type == DVD_STRUCT_DISCKEY

            bca.{len,value}     for type == DVD_STRUCT_BCA

            manufact.{len,valu} for type == DVD_STRUCT_MANUFACT

        error returns:

          EINVAL        physical.layer_num exceeds number of layers

          EIO           Received invalid response from drive

DVD_WRITE_STRUCT                Write structure

        Not implemented, as of 2.6.8.1

DVD_AUTH                        Authentication

        usage:

          dvd_authinfo ai;

          ioctl(fd, DVD_AUTH, &ai);

        inputs:

          dvd_authinfo structure.  See 

        outputs:

          dvd_authinfo structure.

        error return:

          ENOTTY        ai.type not recognized.

CDROM_SEND_PACKET               send a packet to the drive

        usage:

          struct cdrom_generic_command cgc;

          ioctl(fd, CDROM_SEND_PACKET, &cgc);

        inputs:

          cdrom_generic_command structure containing the packet to send.

        outputs:        none

          cdrom_generic_command structure containing results.

        error return:

          EIO           command failed.

          EPERM         Operation not permitted, either because a

                        write command was attempted on a drive which

                        is opened read-only, or because the command

                        requires CAP_SYS_RAWIO

          EINVAL        cgc.data_direction not set

CDROM_NEXT_WRITABLE             get next writable block

        usage:

          long next;

          ioctl(fd, CDROM_NEXT_WRITABLE, &next);