Documentation/ioctl/cdrom.txt

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