Documentation/userspace-api/ioctl/cdrom.rst

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