1 ============================
2 Summary of CDROM ioctl calls
3 ============================
5 - Edward A. Falk <efalk@google.com>
9 This document attempts to describe the ioctl(2) calls supported by
10 the CDROM layer. These are by-and-large implemented (as of Linux 2.6)
11 in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c
13 ioctl values are listed in <linux/cdrom.h>. As of this writing, they
16 ======================== ===============================================
17 CDROMPAUSE Pause Audio Operation
18 CDROMRESUME Resume paused Audio Operation
19 CDROMPLAYMSF Play Audio MSF (struct cdrom_msf)
20 CDROMPLAYTRKIND Play Audio Track/index (struct cdrom_ti)
21 CDROMREADTOCHDR Read TOC header (struct cdrom_tochdr)
22 CDROMREADTOCENTRY Read TOC entry (struct cdrom_tocentry)
23 CDROMSTOP Stop the cdrom drive
24 CDROMSTART Start the cdrom drive
25 CDROMEJECT Ejects the cdrom media
26 CDROMVOLCTRL Control output volume (struct cdrom_volctrl)
27 CDROMSUBCHNL Read subchannel data (struct cdrom_subchnl)
28 CDROMREADMODE2 Read CDROM mode 2 data (2336 Bytes)
30 CDROMREADMODE1 Read CDROM mode 1 data (2048 Bytes)
32 CDROMREADAUDIO (struct cdrom_read_audio)
33 CDROMEJECT_SW enable(1)/disable(0) auto-ejecting
34 CDROMMULTISESSION Obtain the start-of-last-session
35 address of multi session disks
36 (struct cdrom_multisession)
37 CDROM_GET_MCN Obtain the "Universal Product Code"
38 if available (struct cdrom_mcn)
39 CDROM_GET_UPC Deprecated, use CDROM_GET_MCN instead.
40 CDROMRESET hard-reset the drive
41 CDROMVOLREAD Get the drive's volume setting
42 (struct cdrom_volctrl)
43 CDROMREADRAW read data in raw mode (2352 Bytes)
45 CDROMREADCOOKED read data in cooked mode
46 CDROMSEEK seek msf address
47 CDROMPLAYBLK scsi-cd only, (struct cdrom_blk)
48 CDROMREADALL read all 2646 bytes
49 CDROMGETSPINDOWN return 4-bit spindown value
50 CDROMSETSPINDOWN set 4-bit spindown value
51 CDROMCLOSETRAY pendant of CDROMEJECT
52 CDROM_SET_OPTIONS Set behavior options
53 CDROM_CLEAR_OPTIONS Clear behavior options
54 CDROM_SELECT_SPEED Set the CD-ROM speed
55 CDROM_SELECT_DISC Select disc (for juke-boxes)
56 CDROM_MEDIA_CHANGED Check is media changed
57 CDROM_TIMED_MEDIA_CHANGE Check if media changed
59 (struct cdrom_timed_media_change_info)
60 CDROM_DRIVE_STATUS Get tray position, etc.
61 CDROM_DISC_STATUS Get disc type, etc.
62 CDROM_CHANGER_NSLOTS Get number of slots
63 CDROM_LOCKDOOR lock or unlock door
64 CDROM_DEBUG Turn debug messages on/off
65 CDROM_GET_CAPABILITY get capabilities
66 CDROMAUDIOBUFSIZ set the audio buffer size
67 DVD_READ_STRUCT Read structure
68 DVD_WRITE_STRUCT Write structure
69 DVD_AUTH Authentication
70 CDROM_SEND_PACKET send a packet to the drive
71 CDROM_NEXT_WRITABLE get next writable block
72 CDROM_LAST_WRITTEN get last block written on disc
73 ======================== ===============================================
76 The information that follows was determined from reading kernel source
77 code. It is likely that some corrections will be made over time.
79 ------------------------------------------------------------------------------
83 Unless otherwise specified, all ioctl calls return 0 on success
84 and -1 with errno set to an appropriate value on error. (Some
85 ioctls return non-negative data values.)
87 Unless otherwise specified, all ioctl calls return -1 and set
88 errno to EFAULT on a failed attempt to copy data to or from user
91 Individual drivers may return error codes not listed here.
93 Unless otherwise specified, all data structures and constants
94 are defined in <linux/cdrom.h>
96 ------------------------------------------------------------------------------
100 Pause Audio Operation
105 ioctl(fd, CDROMPAUSE, 0);
117 - ENOSYS cd drive not audio-capable.
121 Resume paused Audio Operation
126 ioctl(fd, CDROMRESUME, 0);
138 - ENOSYS cd drive not audio-capable.
149 struct cdrom_msf msf;
151 ioctl(fd, CDROMPLAYMSF, &msf);
154 cdrom_msf structure, describing a segment of music to play
162 - ENOSYS cd drive not audio-capable.
165 - MSF stands for minutes-seconds-frames
166 - LBA stands for logical block address
167 - Segment is described as start and end times, where each time
168 is described as minutes:seconds:frames.
169 A frame is 1/75 of a second.
173 Play Audio Track/index
182 ioctl(fd, CDROMPLAYTRKIND, &ti);
185 cdrom_ti structure, describing a segment of music to play
193 - ENOSYS cd drive not audio-capable.
196 - Segment is described as start and end times, where each time
197 is described as a track and an index.
204 (struct cdrom_tochdr)
211 ioctl(fd, CDROMREADTOCHDR, &header);
214 cdrom_tochdr structure
218 cdrom_tochdr structure
222 - ENOSYS cd drive not audio-capable.
229 (struct cdrom_tocentry)
234 struct cdrom_tocentry entry;
236 ioctl(fd, CDROMREADTOCENTRY, &entry);
239 cdrom_tocentry structure
243 cdrom_tocentry structure
247 - ENOSYS cd drive not audio-capable.
248 - EINVAL entry.cdte_format not CDROM_MSF or CDROM_LBA
249 - EINVAL requested track out of bounds
250 - EIO I/O error reading TOC
253 - TOC stands for Table Of Contents
254 - MSF stands for minutes-seconds-frames
255 - LBA stands for logical block address
265 ioctl(fd, CDROMSTOP, 0);
277 - ENOSYS cd drive not audio-capable.
280 - Exact interpretation of this ioctl depends on the device,
281 but most seem to spin the drive down.
285 Start the cdrom drive
290 ioctl(fd, CDROMSTART, 0);
302 - ENOSYS cd drive not audio-capable.
305 - Exact interpretation of this ioctl depends on the device,
306 but most seem to spin the drive up and/or close the tray.
307 Other devices ignore the ioctl completely.
311 - Ejects the cdrom media
316 ioctl(fd, CDROMEJECT, 0);
328 - ENOSYS cd drive not capable of ejecting
329 - EBUSY other processes are accessing drive, or door is locked
332 - See CDROM_LOCKDOOR, below.
338 pendant of CDROMEJECT
343 ioctl(fd, CDROMCLOSETRAY, 0);
355 - ENOSYS cd drive not capable of closing the tray
356 - EBUSY other processes are accessing drive, or door is locked
359 - See CDROM_LOCKDOOR, below.
365 Control output volume (struct cdrom_volctrl)
370 struct cdrom_volctrl volume;
372 ioctl(fd, CDROMVOLCTRL, &volume);
375 cdrom_volctrl structure containing volumes for up to 4
383 - ENOSYS cd drive not audio-capable.
388 Get the drive's volume setting
390 (struct cdrom_volctrl)
395 struct cdrom_volctrl volume;
397 ioctl(fd, CDROMVOLREAD, &volume);
404 The current volume settings.
408 - ENOSYS cd drive not audio-capable.
415 (struct cdrom_subchnl)
420 struct cdrom_subchnl q;
422 ioctl(fd, CDROMSUBCHNL, &q);
425 cdrom_subchnl structure
429 cdrom_subchnl structure
433 - ENOSYS cd drive not audio-capable.
434 - EINVAL format not CDROM_MSF or CDROM_LBA
437 - Format is converted to CDROM_MSF or CDROM_LBA
438 as per user request on return
443 read data in raw mode (2352 Bytes)
451 struct cdrom_msf msf; /* input */
452 char buffer[CD_FRAMESIZE_RAW]; /* return */
454 ioctl(fd, CDROMREADRAW, &arg);
457 cdrom_msf structure indicating an address to read.
459 Only the start values are significant.
462 Data written to address provided by user.
466 - EINVAL address less than 0, or msf less than 0:2:0
467 - ENOMEM out of memory
470 - As of 2.6.8.1, comments in <linux/cdrom.h> indicate that this
471 ioctl accepts a cdrom_read structure, but actual source code
472 reads a cdrom_msf structure and writes a buffer of data to
475 - MSF values are converted to LBA values via this formula::
477 lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET;
483 Read CDROM mode 1 data (2048 Bytes)
488 Identical to CDROMREADRAW except that block size is
489 CD_FRAMESIZE (2048) bytes
494 Read CDROM mode 2 data (2336 Bytes)
499 Identical to CDROMREADRAW except that block size is
500 CD_FRAMESIZE_RAW0 (2336) bytes
505 (struct cdrom_read_audio)
509 struct cdrom_read_audio ra;
511 ioctl(fd, CDROMREADAUDIO, &ra);
514 cdrom_read_audio structure containing read start
518 audio data, returned to buffer indicated by ra
522 - EINVAL format not CDROM_MSF or CDROM_LBA
523 - EINVAL nframes not in range [1 75]
524 - ENXIO drive has no queue (probably means invalid fd)
525 - ENOMEM out of memory
529 enable(1)/disable(0) auto-ejecting
536 ioctl(fd, CDROMEJECT_SW, val);
539 Flag specifying auto-eject flag.
547 - ENOSYS Drive is not capable of ejecting.
548 - EBUSY Door is locked
554 Obtain the start-of-last-session address of multi session disks
556 (struct cdrom_multisession)
560 struct cdrom_multisession ms_info;
562 ioctl(fd, CDROMMULTISESSION, &ms_info);
565 cdrom_multisession structure containing desired
570 cdrom_multisession structure is filled with last_session
574 - EINVAL format not CDROM_MSF or CDROM_LBA
578 Obtain the "Universal Product Code"
586 struct cdrom_mcn mcn;
588 ioctl(fd, CDROM_GET_MCN, &mcn);
595 Universal Product Code
599 - ENOSYS Drive is not capable of reading MCN data.
602 - Source code comments state::
604 The following function is implemented, although very few
605 audio discs give Universal Product Code information, which
606 should just be the Medium Catalog Number on the box. Note,
607 that the way the code is written on the CD is /not/ uniform
614 CDROM_GET_MCN (deprecated)
617 Not implemented, as of 2.6.8.1
627 ioctl(fd, CDROMRESET, 0);
639 - EACCES Access denied: requires CAP_SYS_ADMIN
640 - ENOSYS Drive is not capable of resetting.
646 read data in cooked mode
651 u8 buffer[CD_FRAMESIZE]
653 ioctl(fd, CDROMREADCOOKED, buffer);
660 2048 bytes of data, "cooked" mode.
664 Not implemented on all drives.
674 Same as CDROMREADCOOKED, but reads 2646 bytes.
684 struct cdrom_msf msf;
686 ioctl(fd, CDROMSEEK, &msf);
689 MSF address to seek to.
706 struct cdrom_blk blk;
708 ioctl(fd, CDROMPLAYBLK, &blk);
721 Obsolete, was ide-cd only
728 ioctl(fd, CDROMGETSPINDOWN, &spindown);
735 The value of the current 4-bit spindown value.
742 Obsolete, was ide-cd only
749 ioctl(fd, CDROMSETSPINDOWN, &spindown);
752 4-bit value used to control spindown (TODO: more detail here)
771 ioctl(fd, CDROM_SET_OPTIONS, options);
774 New values for drive options. The logical 'or' of:
776 ============== ==================================
777 CDO_AUTO_CLOSE close tray on first open(2)
778 CDO_AUTO_EJECT open tray on last release
779 CDO_USE_FFLAGS use O_NONBLOCK information on open
780 CDO_LOCK lock tray on open files
781 CDO_CHECK_TYPE check type on open for data
782 ============== ==================================
785 Returns the resulting options settings in the
786 ioctl return value. Returns -1 on error.
789 - ENOSYS selected option(s) not supported by drive.
795 Clear behavior options
798 Same as CDROM_SET_OPTIONS, except that selected options are
811 ioctl(fd, CDROM_SELECT_SPEED, speed);
822 - ENOSYS speed selection not supported by drive.
827 Select disc (for juke-boxes)
834 ioctl(fd, CDROM_SELECT_DISC, disk);
837 Disk to load into drive.
845 - EINVAL Disk number beyond capacity of drive
850 Check is media changed
857 ioctl(fd, CDROM_MEDIA_CHANGED, slot);
860 Slot number to be tested, always zero except for jukeboxes.
862 May also be special values CDSL_NONE or CDSL_CURRENT
865 Ioctl return value is 0 or 1 depending on whether the media
867 has been changed, or -1 on error.
870 - ENOSYS Drive can't detect media change
871 - EINVAL Slot number beyond capacity of drive
872 - ENOMEM Out of memory
877 Get tray position, etc.
884 ioctl(fd, CDROM_DRIVE_STATUS, slot);
887 Slot number to be tested, always zero except for jukeboxes.
889 May also be special values CDSL_NONE or CDSL_CURRENT
892 Ioctl return value will be one of the following values
894 from <linux/cdrom.h>:
896 =================== ==========================
897 CDS_NO_INFO Information not available.
903 =================== ==========================
906 - ENOSYS Drive can't detect drive status
907 - EINVAL Slot number beyond capacity of drive
908 - ENOMEM Out of memory
919 ioctl(fd, CDROM_DISC_STATUS, 0);
927 Ioctl return value will be one of the following values
929 from <linux/cdrom.h>:
942 - Source code comments state::
945 Ok, this is where problems start. The current interface for
946 the CDROM_DISC_STATUS ioctl is flawed. It makes the false
947 assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc.
948 Unfortunately, while this is often the case, it is also
949 very common for CDs to have some tracks with data, and some
950 tracks with audio. Just because I feel like it, I declare
951 the following to be the best way to cope. If the CD has
952 ANY data tracks on it, it will be returned as a data CD.
953 If it has any XA tracks, I will return it as that. Now I
954 could simplify this interface by combining these returns with
955 the above, but this more clearly demonstrates the problem
956 with the current interface. Too bad this wasn't designed
957 to use bitmasks... -Erik
959 Well, now we have the option CDS_MIXED: a mixed-type CD.
960 User level programmers might feel the ioctl is not very
973 ioctl(fd, CDROM_CHANGER_NSLOTS, 0);
981 The ioctl return value will be the number of slots in a
982 CD changer. Typically 1 for non-multi-disk devices.
997 ioctl(fd, CDROM_LOCKDOOR, lock);
1000 Door lock flag, 1=lock, 0=unlock
1008 - EDRIVE_CANT_DO_THIS
1010 Door lock function not supported.
1013 Attempt to unlock when multiple users
1014 have the drive open and not CAP_SYS_ADMIN
1017 As of 2.6.8.1, the lock flag is a global lock, meaning that
1018 all CD drives will be locked or unlocked together. This is
1021 The EDRIVE_CANT_DO_THIS value is defined in <linux/cdrom.h>
1022 and is currently (2.6.8.1) the same as EOPNOTSUPP
1027 Turn debug messages on/off
1034 ioctl(fd, CDROM_DEBUG, debug);
1037 Cdrom debug flag, 0=disable, 1=enable
1041 The ioctl return value will be the new debug flag.
1045 - EACCES Access denied: requires CAP_SYS_ADMIN
1049 CDROM_GET_CAPABILITY
1055 ioctl(fd, CDROM_GET_CAPABILITY, 0);
1063 The ioctl return value is the current device capability
1064 flags. See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc.
1069 set the audio buffer size
1076 ioctl(fd, CDROMAUDIOBUFSIZ, val);
1079 New audio buffer size
1083 The ioctl return value is the new audio buffer size, or -1
1087 - ENOSYS Not supported by this driver.
1090 Not supported by all drivers.
1095 DVD_READ_STRUCT Read structure
1101 ioctl(fd, DVD_READ_STRUCT, &s);
1104 dvd_struct structure, containing:
1106 =================== ==========================================
1107 type specifies the information desired, one of
1108 DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT,
1109 DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA,
1111 physical.layer_num desired layer, indexed from 0
1112 copyright.layer_num desired layer, indexed from 0
1114 =================== ==========================================
1117 dvd_struct structure, containing:
1119 =================== ================================
1120 physical for type == DVD_STRUCT_PHYSICAL
1121 copyright for type == DVD_STRUCT_COPYRIGHT
1122 disckey.value for type == DVD_STRUCT_DISCKEY
1123 bca.{len,value} for type == DVD_STRUCT_BCA
1124 manufact.{len,valu} for type == DVD_STRUCT_MANUFACT
1125 =================== ================================
1128 - EINVAL physical.layer_num exceeds number of layers
1129 - EIO Received invalid response from drive
1133 DVD_WRITE_STRUCT Write structure
1135 Not implemented, as of 2.6.8.1
1139 DVD_AUTH Authentication
1145 ioctl(fd, DVD_AUTH, &ai);
1148 dvd_authinfo structure. See <linux/cdrom.h>
1152 dvd_authinfo structure.
1156 - ENOTTY ai.type not recognized.
1161 send a packet to the drive
1166 struct cdrom_generic_command cgc;
1168 ioctl(fd, CDROM_SEND_PACKET, &cgc);
1171 cdrom_generic_command structure containing the packet to send.
1177 cdrom_generic_command structure containing results.
1185 Operation not permitted, either because a
1186 write command was attempted on a drive which
1187 is opened read-only, or because the command
1188 requires CAP_SYS_RAWIO
1191 cgc.data_direction not set
1196 get next writable block
1203 ioctl(fd, CDROM_NEXT_WRITABLE, &next);
1210 The next writable block.
1214 If the device does not support this ioctl directly, the
1216 ioctl will return CDROM_LAST_WRITTEN + 7.
1221 get last block written on disc
1228 ioctl(fd, CDROM_LAST_WRITTEN, &last);
1235 The last block written on disc
1239 If the device does not support this ioctl directly, the
1240 result is derived from the disc's table of contents. If the
1241 table of contents can't be read, this ioctl returns an