1 ============================
2 Summary of CDROM ioctl calls
3 ============================
4
5 - Edward A. Falk <efalk@google.com>
6
7 November, 2004
8
9 This document attempts to describe the ioctl(2
10 the CDROM layer. These are by-and-large imple
11 in drivers/cdrom/cdrom.c and drivers/block/scs
12
13 ioctl values are listed in <linux/cdrom.h>. A
14 are as follows:
15
16 ======================== ============
17 CDROMPAUSE Pause Audio
18 CDROMRESUME Resume pause
19 CDROMPLAYMSF Play Audio M
20 CDROMPLAYTRKIND Play Audio T
21 CDROMREADTOCHDR Read TOC hea
22 CDROMREADTOCENTRY Read TOC ent
23 CDROMSTOP Stop the cdr
24 CDROMSTART Start the cd
25 CDROMEJECT Ejects the c
26 CDROMVOLCTRL Control outp
27 CDROMSUBCHNL Read subchan
28 CDROMREADMODE2 Read CDROM m
29 (struct cdro
30 CDROMREADMODE1 Read CDROM m
31 (struct cdro
32 CDROMREADAUDIO (struct cdro
33 CDROMEJECT_SW enable(1)/di
34 CDROMMULTISESSION Obtain the s
35 address of m
36 (struct cdro
37 CDROM_GET_MCN Obtain the "
38 if available
39 CDROM_GET_UPC Deprecated,
40 CDROMRESET hard-reset t
41 CDROMVOLREAD Get the driv
42 (struct cdro
43 CDROMREADRAW read data in
44 (struct cdro
45 CDROMREADCOOKED read data in
46 CDROMSEEK seek msf add
47 CDROMPLAYBLK scsi-cd only
48 CDROMREADALL read all 264
49 CDROMGETSPINDOWN return 4-bit
50 CDROMSETSPINDOWN set 4-bit sp
51 CDROMCLOSETRAY pendant of C
52 CDROM_SET_OPTIONS Set behavior
53 CDROM_CLEAR_OPTIONS Clear behavi
54 CDROM_SELECT_SPEED Set the CD-R
55 CDROM_SELECT_DISC Select disc
56 CDROM_MEDIA_CHANGED Check is med
57 CDROM_TIMED_MEDIA_CHANGE Check if med
58 since given
59 (struct cdro
60 CDROM_DRIVE_STATUS Get tray pos
61 CDROM_DISC_STATUS Get disc typ
62 CDROM_CHANGER_NSLOTS Get number o
63 CDROM_LOCKDOOR lock or unlo
64 CDROM_DEBUG Turn debug m
65 CDROM_GET_CAPABILITY get capabili
66 CDROMAUDIOBUFSIZ set the audi
67 DVD_READ_STRUCT Read structu
68 DVD_WRITE_STRUCT Write struct
69 DVD_AUTH Authenticati
70 CDROM_SEND_PACKET send a packe
71 CDROM_NEXT_WRITABLE get next wri
72 CDROM_LAST_WRITTEN get last blo
73 ======================== ============
74
75
76 The information that follows was determined fr
77 code. It is likely that some corrections will
78
79 ----------------------------------------------
80
81 General:
82
83 Unless otherwise specified, all ioctl
84 and -1 with errno set to an appropriat
85 ioctls return non-negative data values
86
87 Unless otherwise specified, all ioctl
88 errno to EFAULT on a failed attempt to
89 address space.
90
91 Individual drivers may return error co
92
93 Unless otherwise specified, all data s
94 are defined in <linux/cdrom.h>
95
96 ----------------------------------------------
97
98
99 CDROMPAUSE
100 Pause Audio Operation
101
102
103 usage::
104
105 ioctl(fd, CDROMPAUSE, 0);
106
107
108 inputs:
109 none
110
111
112 outputs:
113 none
114
115
116 error return:
117 - ENOSYS cd drive not audio-cap
118
119
120 CDROMRESUME
121 Resume paused Audio Operation
122
123
124 usage::
125
126 ioctl(fd, CDROMRESUME, 0);
127
128
129 inputs:
130 none
131
132
133 outputs:
134 none
135
136
137 error return:
138 - ENOSYS cd drive not audio-cap
139
140
141 CDROMPLAYMSF
142 Play Audio MSF
143
144 (struct cdrom_msf)
145
146
147 usage::
148
149 struct cdrom_msf msf;
150
151 ioctl(fd, CDROMPLAYMSF, &msf);
152
153 inputs:
154 cdrom_msf structure, describin
155
156
157 outputs:
158 none
159
160
161 error return:
162 - ENOSYS cd drive not audio-cap
163
164 notes:
165 - MSF stands for minutes-secon
166 - LBA stands for logical block
167 - Segment is described as star
168 is described as minutes:seco
169 A frame is 1/75 of a second.
170
171
172 CDROMPLAYTRKIND
173 Play Audio Track/index
174
175 (struct cdrom_ti)
176
177
178 usage::
179
180 struct cdrom_ti ti;
181
182 ioctl(fd, CDROMPLAYTRKIND, &ti);
183
184 inputs:
185 cdrom_ti structure, describing
186
187
188 outputs:
189 none
190
191
192 error return:
193 - ENOSYS cd drive not audio-cap
194
195 notes:
196 - Segment is described as star
197 is described as a track and
198
199
200
201 CDROMREADTOCHDR
202 Read TOC header
203
204 (struct cdrom_tochdr)
205
206
207 usage::
208
209 cdrom_tochdr header;
210
211 ioctl(fd, CDROMREADTOCHDR, &header);
212
213 inputs:
214 cdrom_tochdr structure
215
216
217 outputs:
218 cdrom_tochdr structure
219
220
221 error return:
222 - ENOSYS cd drive not audio-cap
223
224
225
226 CDROMREADTOCENTRY
227 Read TOC entry
228
229 (struct cdrom_tocentry)
230
231
232 usage::
233
234 struct cdrom_tocentry entry;
235
236 ioctl(fd, CDROMREADTOCENTRY, &entry)
237
238 inputs:
239 cdrom_tocentry structure
240
241
242 outputs:
243 cdrom_tocentry structure
244
245
246 error return:
247 - ENOSYS cd drive not audio-cap
248 - EINVAL entry.cdte_format not
249 - EINVAL requested track out of
250 - EIO I/O error reading TOC
251
252 notes:
253 - TOC stands for Table Of Cont
254 - MSF stands for minutes-secon
255 - LBA stands for logical block
256
257
258
259 CDROMSTOP
260 Stop the cdrom drive
261
262
263 usage::
264
265 ioctl(fd, CDROMSTOP, 0);
266
267
268 inputs:
269 none
270
271
272 outputs:
273 none
274
275
276 error return:
277 - ENOSYS cd drive not audio-cap
278
279 notes:
280 - Exact interpretation of this ioctl
281 but most seem to spin the drive do
282
283
284 CDROMSTART
285 Start the cdrom drive
286
287
288 usage::
289
290 ioctl(fd, CDROMSTART, 0);
291
292
293 inputs:
294 none
295
296
297 outputs:
298 none
299
300
301 error return:
302 - ENOSYS cd drive not audio-cap
303
304 notes:
305 - Exact interpretation of this ioctl
306 but most seem to spin the drive up
307 Other devices ignore the ioctl com
308
309
310 CDROMEJECT
311 - Ejects the cdrom media
312
313
314 usage::
315
316 ioctl(fd, CDROMEJECT, 0);
317
318
319 inputs:
320 none
321
322
323 outputs:
324 none
325
326
327 error returns:
328 - ENOSYS cd drive not capable o
329 - EBUSY other processes are ac
330
331 notes:
332 - See CDROM_LOCKDOOR, below.
333
334
335
336
337 CDROMCLOSETRAY
338 pendant of CDROMEJECT
339
340
341 usage::
342
343 ioctl(fd, CDROMCLOSETRAY, 0);
344
345
346 inputs:
347 none
348
349
350 outputs:
351 none
352
353
354 error returns:
355 - ENOSYS cd drive not capable o
356 - EBUSY other processes are ac
357
358 notes:
359 - See CDROM_LOCKDOOR, below.
360
361
362
363
364 CDROMVOLCTRL
365 Control output volume (struct cdrom_vo
366
367
368 usage::
369
370 struct cdrom_volctrl volume;
371
372 ioctl(fd, CDROMVOLCTRL, &volume);
373
374 inputs:
375 cdrom_volctrl structure contai
376 channels.
377
378 outputs:
379 none
380
381
382 error return:
383 - ENOSYS cd drive not audio-cap
384
385
386
387 CDROMVOLREAD
388 Get the drive's volume setting
389
390 (struct cdrom_volctrl)
391
392
393 usage::
394
395 struct cdrom_volctrl volume;
396
397 ioctl(fd, CDROMVOLREAD, &volume);
398
399 inputs:
400 none
401
402
403 outputs:
404 The current volume settings.
405
406
407 error return:
408 - ENOSYS cd drive not audio-cap
409
410
411
412 CDROMSUBCHNL
413 Read subchannel data
414
415 (struct cdrom_subchnl)
416
417
418 usage::
419
420 struct cdrom_subchnl q;
421
422 ioctl(fd, CDROMSUBCHNL, &q);
423
424 inputs:
425 cdrom_subchnl structure
426
427
428 outputs:
429 cdrom_subchnl structure
430
431
432 error return:
433 - ENOSYS cd drive not audio-cap
434 - EINVAL format not CDROM_MSF o
435
436 notes:
437 - Format is converted to CDROM
438 as per user request on retur
439
440
441
442 CDROMREADRAW
443 read data in raw mode (2352 Bytes)
444
445 (struct cdrom_read)
446
447 usage::
448
449 union {
450
451 struct cdrom_msf msf;
452 char buffer[CD_FRAMESIZE_RAW];
453 } arg;
454 ioctl(fd, CDROMREADRAW, &arg);
455
456 inputs:
457 cdrom_msf structure indicating
458
459 Only the start values are sign
460
461 outputs:
462 Data written to address provid
463
464
465 error return:
466 - EINVAL address less than 0, o
467 - ENOMEM out of memory
468
469 notes:
470 - As of 2.6.8.1, comments in <
471 ioctl accepts a cdrom_read s
472 reads a cdrom_msf structure
473 the same address.
474
475 - MSF values are converted to
476
477 lba = (((m * CD_SECS) + s)
478
479
480
481
482 CDROMREADMODE1
483 Read CDROM mode 1 data (2048 Bytes)
484
485 (struct cdrom_read)
486
487 notes:
488 Identical to CDROMREADRAW exce
489 CD_FRAMESIZE (2048) bytes
490
491
492
493 CDROMREADMODE2
494 Read CDROM mode 2 data (2336 Bytes)
495
496 (struct cdrom_read)
497
498 notes:
499 Identical to CDROMREADRAW exce
500 CD_FRAMESIZE_RAW0 (2336) bytes
501
502
503
504 CDROMREADAUDIO
505 (struct cdrom_read_audio)
506
507 usage::
508
509 struct cdrom_read_audio ra;
510
511 ioctl(fd, CDROMREADAUDIO, &ra);
512
513 inputs:
514 cdrom_read_audio structure con
515 point and length
516
517 outputs:
518 audio data, returned to buffer
519
520
521 error return:
522 - EINVAL format not CDROM_MSF o
523 - EINVAL nframes not in range [
524 - ENXIO drive has no queue (pr
525 - ENOMEM out of memory
526
527
528 CDROMEJECT_SW
529 enable(1)/disable(0) auto-ejecting
530
531
532 usage::
533
534 int val;
535
536 ioctl(fd, CDROMEJECT_SW, val);
537
538 inputs:
539 Flag specifying auto-eject fla
540
541
542 outputs:
543 none
544
545
546 error return:
547 - ENOSYS Drive is not capable o
548 - EBUSY Door is locked
549
550
551
552
553 CDROMMULTISESSION
554 Obtain the start-of-last-session addre
555
556 (struct cdrom_multisession)
557
558 usage::
559
560 struct cdrom_multisession ms_info;
561
562 ioctl(fd, CDROMMULTISESSION, &ms_inf
563
564 inputs:
565 cdrom_multisession structure c
566
567 format.
568
569 outputs:
570 cdrom_multisession structure i
571 information.
572
573 error return:
574 - EINVAL format not CDROM_MSF o
575
576
577 CDROM_GET_MCN
578 Obtain the "Universal Product Code"
579 if available
580
581 (struct cdrom_mcn)
582
583
584 usage::
585
586 struct cdrom_mcn mcn;
587
588 ioctl(fd, CDROM_GET_MCN, &mcn);
589
590 inputs:
591 none
592
593
594 outputs:
595 Universal Product Code
596
597
598 error return:
599 - ENOSYS Drive is not capable o
600
601 notes:
602 - Source code comments state::
603
604 The following function is
605 audio discs give Universal
606 should just be the Medium
607 that the way the code is w
608 across all discs!
609
610
611
612
613 CDROM_GET_UPC
614 CDROM_GET_MCN (deprecated)
615
616
617 Not implemented, as of 2.6.8.1
618
619
620
621 CDROMRESET
622 hard-reset the drive
623
624
625 usage::
626
627 ioctl(fd, CDROMRESET, 0);
628
629
630 inputs:
631 none
632
633
634 outputs:
635 none
636
637
638 error return:
639 - EACCES Access denied: requir
640 - ENOSYS Drive is not capable o
641
642
643
644
645 CDROMREADCOOKED
646 read data in cooked mode
647
648
649 usage::
650
651 u8 buffer[CD_FRAMESIZE]
652
653 ioctl(fd, CDROMREADCOOKED, buffer);
654
655 inputs:
656 none
657
658
659 outputs:
660 2048 bytes of data, "cooked" m
661
662
663 notes:
664 Not implemented on all drives.
665
666
667
668
669
670 CDROMREADALL
671 read all 2646 bytes
672
673
674 Same as CDROMREADCOOKED, but reads 264
675
676
677
678 CDROMSEEK
679 seek msf address
680
681
682 usage::
683
684 struct cdrom_msf msf;
685
686 ioctl(fd, CDROMSEEK, &msf);
687
688 inputs:
689 MSF address to seek to.
690
691
692 outputs:
693 none
694
695
696
697
698 CDROMPLAYBLK
699 scsi-cd only
700
701 (struct cdrom_blk)
702
703
704 usage::
705
706 struct cdrom_blk blk;
707
708 ioctl(fd, CDROMPLAYBLK, &blk);
709
710 inputs:
711 Region to play
712
713
714 outputs:
715 none
716
717
718
719
720 CDROMGETSPINDOWN
721 Obsolete, was ide-cd only
722
723
724 usage::
725
726 char spindown;
727
728 ioctl(fd, CDROMGETSPINDOWN, &spindow
729
730 inputs:
731 none
732
733
734 outputs:
735 The value of the current 4-bit
736
737
738
739
740
741 CDROMSETSPINDOWN
742 Obsolete, was ide-cd only
743
744
745 usage::
746
747 char spindown
748
749 ioctl(fd, CDROMSETSPINDOWN, &spindow
750
751 inputs:
752 4-bit value used to control sp
753
754
755 outputs:
756 none
757
758
759
760
761
762
763 CDROM_SET_OPTIONS
764 Set behavior options
765
766
767 usage::
768
769 int options;
770
771 ioctl(fd, CDROM_SET_OPTIONS, options
772
773 inputs:
774 New values for drive options.
775
776 ============== ==============
777 CDO_AUTO_CLOSE close tray on
778 CDO_AUTO_EJECT open tray on l
779 CDO_USE_FFLAGS use O_NONBLOCK
780 CDO_LOCK lock tray on o
781 CDO_CHECK_TYPE check type on
782 ============== ==============
783
784 outputs:
785 Returns the resulting options
786 ioctl return value. Returns -
787
788 error return:
789 - ENOSYS selected option(s) not
790
791
792
793
794 CDROM_CLEAR_OPTIONS
795 Clear behavior options
796
797
798 Same as CDROM_SET_OPTIONS, except that
799 turned off.
800
801
802
803 CDROM_SELECT_SPEED
804 Set the CD-ROM speed
805
806
807 usage::
808
809 int speed;
810
811 ioctl(fd, CDROM_SELECT_SPEED, speed)
812
813 inputs:
814 New drive speed.
815
816
817 outputs:
818 none
819
820
821 error return:
822 - ENOSYS speed selection not su
823
824
825
826 CDROM_SELECT_DISC
827 Select disc (for juke-boxes)
828
829
830 usage::
831
832 int disk;
833
834 ioctl(fd, CDROM_SELECT_DISC, disk);
835
836 inputs:
837 Disk to load into drive.
838
839
840 outputs:
841 none
842
843
844 error return:
845 - EINVAL Disk number beyond cap
846
847
848
849 CDROM_MEDIA_CHANGED
850 Check is media changed
851
852
853 usage::
854
855 int slot;
856
857 ioctl(fd, CDROM_MEDIA_CHANGED, slot)
858
859 inputs:
860 Slot number to be tested, alwa
861
862 May also be special values CDS
863
864 outputs:
865 Ioctl return value is 0 or 1 d
866
867 has been changed, or -1 on error.
868
869 error returns:
870 - ENOSYS Drive can't detect med
871 - EINVAL Slot number beyond cap
872 - ENOMEM Out of memory
873
874
875
876 CDROM_DRIVE_STATUS
877 Get tray position, etc.
878
879
880 usage::
881
882 int slot;
883
884 ioctl(fd, CDROM_DRIVE_STATUS, slot);
885
886 inputs:
887 Slot number to be tested, alwa
888
889 May also be special values CDS
890
891 outputs:
892 Ioctl return value will be one
893
894 from <linux/cdrom.h>:
895
896 =================== ==============
897 CDS_NO_INFO Information no
898 CDS_NO_DISC
899 CDS_TRAY_OPEN
900 CDS_DRIVE_NOT_READY
901 CDS_DISC_OK
902 -1 error
903 =================== ==============
904
905 error returns:
906 - ENOSYS Drive can't detect dri
907 - EINVAL Slot number beyond cap
908 - ENOMEM Out of memory
909
910
911
912
913 CDROM_DISC_STATUS
914 Get disc type, etc.
915
916
917 usage::
918
919 ioctl(fd, CDROM_DISC_STATUS, 0);
920
921
922 inputs:
923 none
924
925
926 outputs:
927 Ioctl return value will be one
928
929 from <linux/cdrom.h>:
930
931 - CDS_NO_INFO
932 - CDS_AUDIO
933 - CDS_MIXED
934 - CDS_XA_2_2
935 - CDS_XA_2_1
936 - CDS_DATA_1
937
938 error returns:
939 none at present
940
941 notes:
942 - Source code comments state::
943
944
945 Ok, this is where problems sta
946 the CDROM_DISC_STATUS ioctl is
947 assumption that CDs are all CD
948 Unfortunately, while this is o
949 very common for CDs to have so
950 tracks with audio. Just b
951 the following to be the best w
952 ANY data tracks on it, it will
953 If it has any XA tracks, I wil
954 could simplify this interface
955 the above, but this more clear
956 with the current interface. T
957 to use bitmasks...
958
959 Well, now we have the option C
960 User level programmers might f
961 useful.
962 ---david
963
964
965
966
967 CDROM_CHANGER_NSLOTS
968 Get number of slots
969
970
971 usage::
972
973 ioctl(fd, CDROM_CHANGER_NSLOTS, 0);
974
975
976 inputs:
977 none
978
979
980 outputs:
981 The ioctl return value will be
982 CD changer. Typically 1 for n
983
984 error returns:
985 none
986
987
988
989 CDROM_LOCKDOOR
990 lock or unlock door
991
992
993 usage::
994
995 int lock;
996
997 ioctl(fd, CDROM_LOCKDOOR, lock);
998
999 inputs:
1000 Door lock flag, 1=lock, 0=unl
1001
1002
1003 outputs:
1004 none
1005
1006
1007 error returns:
1008 - EDRIVE_CANT_DO_THIS
1009
1010 Door lock fun
1011 - EBUSY
1012
1013 Attempt to un
1014 have the driv
1015
1016 notes:
1017 As of 2.6.8.1, the lock flag
1018 all CD drives will be locked
1019 probably a bug.
1020
1021 The EDRIVE_CANT_DO_THIS value
1022 and is currently (2.6.8.1) th
1023
1024
1025
1026 CDROM_DEBUG
1027 Turn debug messages on/off
1028
1029
1030 usage::
1031
1032 int debug;
1033
1034 ioctl(fd, CDROM_DEBUG, debug);
1035
1036 inputs:
1037 Cdrom debug flag, 0=disable,
1038
1039
1040 outputs:
1041 The ioctl return value will b
1042
1043
1044 error return:
1045 - EACCES Access denied: requi
1046
1047
1048
1049 CDROM_GET_CAPABILITY
1050 get capabilities
1051
1052
1053 usage::
1054
1055 ioctl(fd, CDROM_GET_CAPABILITY, 0);
1056
1057
1058 inputs:
1059 none
1060
1061
1062 outputs:
1063 The ioctl return value is the
1064 flags. See CDC_CLOSE_TRAY, C
1065
1066
1067
1068 CDROMAUDIOBUFSIZ
1069 set the audio buffer size
1070
1071
1072 usage::
1073
1074 int arg;
1075
1076 ioctl(fd, CDROMAUDIOBUFSIZ, val);
1077
1078 inputs:
1079 New audio buffer size
1080
1081
1082 outputs:
1083 The ioctl return value is the
1084 on error.
1085
1086 error return:
1087 - ENOSYS Not supported by this
1088
1089 notes:
1090 Not supported by all drivers.
1091
1092
1093
1094
1095 DVD_READ_STRUCT Read structur
1096
1097 usage::
1098
1099 dvd_struct s;
1100
1101 ioctl(fd, DVD_READ_STRUCT, &s);
1102
1103 inputs:
1104 dvd_struct structure, contain
1105
1106 =================== =============
1107 type specifies the
1108 DVD_STRUCT_PH
1109 DVD_STRUCT_DI
1110 DVD_STRUCT_MA
1111 physical.layer_num desired layer
1112 copyright.layer_num desired layer
1113 disckey.agid
1114 =================== =============
1115
1116 outputs:
1117 dvd_struct structure, contain
1118
1119 =================== =============
1120 physical for type == D
1121 copyright for type == D
1122 disckey.value for type == D
1123 bca.{len,value} for type == D
1124 manufact.{len,valu} for type == D
1125 =================== =============
1126
1127 error returns:
1128 - EINVAL physical.layer_num ex
1129 - EIO Received invalid resp
1130
1131
1132
1133 DVD_WRITE_STRUCT Write structu
1134
1135 Not implemented, as of 2.6.8.1
1136
1137
1138
1139 DVD_AUTH Authenticatio
1140
1141 usage::
1142
1143 dvd_authinfo ai;
1144
1145 ioctl(fd, DVD_AUTH, &ai);
1146
1147 inputs:
1148 dvd_authinfo structure. See
1149
1150
1151 outputs:
1152 dvd_authinfo structure.
1153
1154
1155 error return:
1156 - ENOTTY ai.type not recognize
1157
1158
1159
1160 CDROM_SEND_PACKET
1161 send a packet to the drive
1162
1163
1164 usage::
1165
1166 struct cdrom_generic_command cgc;
1167
1168 ioctl(fd, CDROM_SEND_PACKET, &cgc);
1169
1170 inputs:
1171 cdrom_generic_command structu
1172
1173
1174 outputs:
1175 none
1176
1177 cdrom_generic_command structure con
1178
1179 error return:
1180 - EIO
1181
1182 command failed.
1183 - EPERM
1184
1185 Operation not permitt
1186 write command was att
1187 is opened read-only,
1188 requires CAP_SYS_RAWI
1189 - EINVAL
1190
1191 cgc.data_direction no
1192
1193
1194
1195 CDROM_NEXT_WRITABLE
1196 get next writable block
1197
1198
1199 usage::
1200
1201 long next;
1202
1203 ioctl(fd, CDROM_NEXT_WRITABLE, &nex
1204
1205 inputs:
1206 none
1207
1208
1209 outputs:
1210 The next writable block.
1211
1212
1213 notes:
1214 If the device does not suppor
1215
1216 ioctl will return CDROM_LAST_WRITTE
1217
1218
1219
1220 CDROM_LAST_WRITTEN
1221 get last block written on disc
1222
1223
1224 usage::
1225
1226 long last;
1227
1228 ioctl(fd, CDROM_LAST_WRITTEN, &last
1229
1230 inputs:
1231 none
1232
1233
1234 outputs:
1235 The last block written on dis
1236
1237
1238 notes:
1239 If the device does not suppor
1240 result is derived from the di
1241 table of contents can't be re
1242 error.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.