关于 ioctl 详细信息

Summary of CDROM ioctl calls.2============================34Edward A. Falk <[e-mail]>56November, 200478This document attempts to describe the ioctl(2) calls supported by9the CDROM layer.  These are by-and-large implemented (as of Linux 2.6)10in drivers/cdrom/cdrom.c and drivers/block/scsi_ioctl.c1112ioctl values are listed in <linux/cdrom.h>.  As of this writing, they13are as follows:1415CDROMPAUSEPause Audio Operation16CDROMRESUMEResume paused Audio Operation17CDROMPLAYMSFPlay Audio MSF (struct cdrom_msf)18CDROMPLAYTRKINDPlay Audio Track/index (struct cdrom_ti)19CDROMREADTOCHDRRead TOC header (struct cdrom_tochdr)20CDROMREADTOCENTRYRead TOC entry (struct cdrom_tocentry)21CDROMSTOPStop the cdrom drive22CDROMSTARTStart the cdrom drive23CDROMEJECTEjects the cdrom media24CDROMVOLCTRLControl output volume (struct cdrom_volctrl)25CDROMSUBCHNLRead subchannel data (struct cdrom_subchnl)26CDROMREADMODE2Read CDROM mode 2 data (2336 Bytes)27   (struct cdrom_read)28CDROMREADMODE1Read CDROM mode 1 data (2048 Bytes)29   (struct cdrom_read)30CDROMREADAUDIO(struct cdrom_read_audio)31CDROMEJECT_SWenable(1)/disable(0) auto-ejecting32CDROMMULTISESSIONObtain the start-of-last-session33  address of multi session disks34  (struct cdrom_multisession)35CDROM_GET_MCNObtain the "Universal Product Code"36   if available (struct cdrom_mcn)37CDROM_GET_UPCDeprecated, use CDROM_GET_MCN instead.38CDROMRESEThard-reset the drive39CDROMVOLREADGet the drive's volume setting40  (struct cdrom_volctrl)41CDROMREADRAWread data in raw mode (2352 Bytes)42   (struct cdrom_read)43CDROMREADCOOKEDread data in cooked mode44CDROMSEEKseek msf address45CDROMPLAYBLKscsi-cd only, (struct cdrom_blk)46CDROMREADALLread all 2646 bytes47CDROMGETSPINDOWNreturn 4-bit spindown value48CDROMSETSPINDOWNset 4-bit spindown value49CDROMCLOSETRAYpendant of CDROMEJECT50CDROM_SET_OPTIONSSet behavior options51CDROM_CLEAR_OPTIONSClear behavior options52CDROM_SELECT_SPEEDSet the CD-ROM speed53CDROM_SELECT_DISCSelect disc (for juke-boxes)54CDROM_MEDIA_CHANGEDCheck is media changed55CDROM_DRIVE_STATUSGet tray position, etc.56CDROM_DISC_STATUSGet disc type, etc.57CDROM_CHANGER_NSLOTSGet number of slots58CDROM_LOCKDOORlock or unlock door59CDROM_DEBUGTurn debug messages on/off60CDROM_GET_CAPABILITYget capabilities61CDROMAUDIOBUFSIZset the audio buffer size62DVD_READ_STRUCTRead structure63DVD_WRITE_STRUCTWrite structure64DVD_AUTHAuthentication65CDROM_SEND_PACKETsend a packet to the drive66CDROM_NEXT_WRITABLEget next writable block67CDROM_LAST_WRITTENget last block written on disc686970The information that follows was determined from reading kernel source71code.  It is likely that some corrections will be made over time.7273747576777879General:8081Unless otherwise specified, all ioctl calls return 0 on success82and -1 with errno set to an appropriate value on error.  (Some83ioctls return non-negative data values.)8485Unless otherwise specified, all ioctl calls return -1 and set86errno to EFAULT on a failed attempt to copy data to or from user87address space.8889Individual drivers may return error codes not listed here.9091Unless otherwise specified, all data structures and constants92are defined in <linux/cdrom.h>9394959697CDROMPAUSEPause Audio Operation9899usage:100101  ioctl(fd, CDROMPAUSE, 0);102103inputs:none104105outputs:none106107error return:108  ENOSYScd drive not audio-capable.109110111CDROMRESUMEResume paused Audio Operation112113usage:114115  ioctl(fd, CDROMRESUME, 0);116117inputs:none118119outputs:none120121error return:122  ENOSYScd drive not audio-capable.123124125CDROMPLAYMSFPlay Audio MSF (struct cdrom_msf)126127usage:128129  struct cdrom_msf msf;130  ioctl(fd, CDROMPLAYMSF, &msf);131132inputs:133  cdrom_msf structure, describing a segment of music to play134135outputs:none136137error return:138  ENOSYScd drive not audio-capable.139140notes:141  MSF stands for minutes-seconds-frames142  LBA stands for logical block address143144  Segment is described as start and end times, where each time145  is described as minutes:seconds:frames.  A frame is 1/75 of146  a second.147148149CDROMPLAYTRKINDPlay Audio Track/index (struct cdrom_ti)150151usage:152153  struct cdrom_ti ti;154  ioctl(fd, CDROMPLAYTRKIND, &ti);155156inputs:157  cdrom_ti structure, describing a segment of music to play158159outputs:none160161error return:162  ENOSYScd drive not audio-capable.163164notes:165  Segment is described as start and end times, where each time166  is described as a track and an index.167168169170CDROMREADTOCHDRRead TOC header (struct cdrom_tochdr)171172usage:173174  cdrom_tochdr header;175  ioctl(fd, CDROMREADTOCHDR, &header);176177inputs:178  cdrom_tochdr structure179180outputs:181  cdrom_tochdr structure182183error return:184  ENOSYScd drive not audio-capable.185186187188CDROMREADTOCENTRYRead TOC entry (struct cdrom_tocentry)189190usage:191192  struct cdrom_tocentry entry;193  ioctl(fd, CDROMREADTOCENTRY, &entry);194195inputs:196  cdrom_tocentry structure197198outputs:199  cdrom_tocentry structure200201error return:202  ENOSYScd drive not audio-capable.203  EINVALentry.cdte_format not CDROM_MSF or CDROM_LBA204  EINVALrequested track out of bounds205  EIOI/O error reading TOC206207notes:208  TOC stands for Table Of Contents209  MSF stands for minutes-seconds-frames210  LBA stands for logical block address211212213214CDROMSTOPStop the cdrom drive215216usage:217218  ioctl(fd, CDROMSTOP, 0);219220inputs:none221222outputs:none223224error return:225  ENOSYScd drive not audio-capable.226227notes:228  Exact interpretation of this ioctl depends on the device,229  but most seem to spin the drive down.230231232CDROMSTARTStart the cdrom drive233234usage:235236  ioctl(fd, CDROMSTART, 0);237238inputs:none239240outputs:none241242error return:243  ENOSYScd drive not audio-capable.244245notes: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.249250251CDROMEJECTEjects the cdrom media252253usage:254255  ioctl(fd, CDROMEJECT, 0);256257inputs:none258259outputs:none260261error returns:262  ENOSYScd drive not capable of ejecting263  EBUSYother processes are accessing drive, or door is locked264265notes:266  See CDROM_LOCKDOOR, below.267268269270CDROMCLOSETRAYpendant of CDROMEJECT271272usage:273274  ioctl(fd, CDROMCLOSETRAY, 0);275276inputs:none277278outputs:none279280error returns:281  ENOSYScd drive not capable of closing the tray282  EBUSYother processes are accessing drive, or door is locked283284notes:285  See CDROM_LOCKDOOR, below.286287288289CDROMVOLCTRLControl output volume (struct cdrom_volctrl)290291usage:292293  struct cdrom_volctrl volume;294  ioctl(fd, CDROMVOLCTRL, &volume);295296inputs:297  cdrom_volctrl structure containing volumes for up to 4298  channels.299300outputs:none301302error return:303  ENOSYScd drive not audio-capable.304305306307CDROMVOLREADGet the drive's volume setting308  (struct cdrom_volctrl)309310usage:311312  struct cdrom_volctrl volume;313  ioctl(fd, CDROMVOLREAD, &volume);314315inputs:none316317outputs:318  The current volume settings.319320error return:321  ENOSYScd drive not audio-capable.322323324325CDROMSUBCHNLRead subchannel data (struct cdrom_subchnl)326327usage:328329  struct cdrom_subchnl q;330  ioctl(fd, CDROMSUBCHNL, &q);331332inputs:333  cdrom_subchnl structure334335outputs:336  cdrom_subchnl structure337338error return:339  ENOSYScd drive not audio-capable.340  EINVALformat not CDROM_MSF or CDROM_LBA341342notes:343  Format is converted to CDROM_MSF or CDROM_LBA344  as per user request on return345346347348CDROMREADRAWread data in raw mode (2352 Bytes)349   (struct cdrom_read)350351usage:352353  union {354    struct cdrom_msf msf;/* input */355    char buffer[CD_FRAMESIZE_RAW];/* return */356  } arg;357  ioctl(fd, CDROMREADRAW, &arg);358359inputs:360  cdrom_msf structure indicating an address to read.361  Only the start values are significant.362363outputs:364  Data written to address provided by user.365366error return:367  EINVALaddress less than 0, or msf less than 0:2:0368  ENOMEMout of memory369370notes:371  As of 2.6.8.1, comments in <linux/cdrom.h> indicate that this372  ioctl accepts a cdrom_read structure, but actual source code373  reads a cdrom_msf structure and writes a buffer of data to374  the same address.375376  MSF values are converted to LBA values via this formula:377378    lba = (((m * CD_SECS) + s) * CD_FRAMES + f) - CD_MSF_OFFSET;379380381382383CDROMREADMODE1Read CDROM mode 1 data (2048 Bytes)384   (struct cdrom_read)385386notes:387  Identical to CDROMREADRAW except that block size is388  CD_FRAMESIZE (2048) bytes389390391392CDROMREADMODE2Read CDROM mode 2 data (2336 Bytes)393   (struct cdrom_read)394395notes:396  Identical to CDROMREADRAW except that block size is397  CD_FRAMESIZE_RAW0 (2336) bytes398399400401CDROMREADAUDIO(struct cdrom_read_audio)402403usage:404405  struct cdrom_read_audio ra;406  ioctl(fd, CDROMREADAUDIO, &ra);407408inputs:409  cdrom_read_audio structure containing read start410  point and length411412outputs:413  audio data, returned to buffer indicated by ra414415error return:416  EINVALformat not CDROM_MSF or CDROM_LBA417  EINVALnframes not in range [1 75]418  ENXIOdrive has no queue (probably means invalid fd)419  ENOMEMout of memory420421422CDROMEJECT_SWenable(1)/disable(0) auto-ejecting423424usage:425426  int val;427  ioctl(fd, CDROMEJECT_SW, val);428429inputs:430  Flag specifying auto-eject flag.431432outputs:none433434error return:435  ENOSYSDrive is not capable of ejecting.436  EBUSYDoor is locked437438439440441CDROMMULTISESSIONObtain the start-of-last-session442  address of multi session disks443  (struct cdrom_multisession)444usage:445446  struct cdrom_multisession ms_info;447  ioctl(fd, CDROMMULTISESSION, &ms_info);448449inputs:450  cdrom_multisession structure containing desired451  format.452453outputs:454  cdrom_multisession structure is filled with last_session455  information.456457error return:458  EINVALformat not CDROM_MSF or CDROM_LBA459460461CDROM_GET_MCNObtain the "Universal Product Code"462   if available (struct cdrom_mcn)463464usage:465466  struct cdrom_mcn mcn;467  ioctl(fd, CDROM_GET_MCN, &mcn);468469inputs:none470471outputs:472  Universal Product Code473474error return:475  ENOSYSDrive is not capable of reading MCN data.476477notes:478  Source code comments state:479480    The following function is implemented, although very few481    audio discs give Universal Product Code information, which482    should just be the Medium Catalog Number on the box.  Note,483    that the way the code is written on the CD is /not/ uniform484    across all discs!485486487488489CDROM_GET_UPCCDROM_GET_MCN  (deprecated)490491Not implemented, as of 2.6.8.1492493494495CDROMRESEThard-reset the drive496497usage:498499  ioctl(fd, CDROMRESET, 0);500501inputs:none502503outputs:none504505error return:506  EACCESAccess denied:  requires CAP_SYS_ADMIN507  ENOSYSDrive is not capable of resetting.508509510511512CDROMREADCOOKEDread data in cooked mode513514usage:515516  u8 buffer[CD_FRAMESIZE]517  ioctl(fd, CDROMREADCOOKED, buffer);518519inputs:none520521outputs:522  2048 bytes of data, "cooked" mode.523524notes:525  Not implemented on all drives.526527528529530CDROMREADALLread all 2646 bytes531532Same as CDROMREADCOOKED, but reads 2646 bytes.533534535536CDROMSEEKseek msf address537538usage:539540  struct cdrom_msf msf;541  ioctl(fd, CDROMSEEK, &msf);542543inputs:544  MSF address to seek to.545546outputs:none547548549550CDROMPLAYBLKscsi-cd only, (struct cdrom_blk)551552usage:553554  struct cdrom_blk blk;555  ioctl(fd, CDROMPLAYBLK, &blk);556557inputs:558  Region to play559560outputs:none561562563564CDROMGETSPINDOWN565566usage:567568  char spindown;569  ioctl(fd, CDROMGETSPINDOWN, &spindown);570571inputs:none572573outputs:574  The value of the current 4-bit spindown value.575576577578579CDROMSETSPINDOWN580581usage:582583  char spindown584  ioctl(fd, CDROMSETSPINDOWN, &spindown);585586inputs:587  4-bit value used to control spindown (TODO: more detail here)588589outputs:none590591592593594595CDROM_SET_OPTIONSSet behavior options596597usage:598599  int options;600  ioctl(fd, CDROM_SET_OPTIONS, options);601602inputs:603  New values for drive options.  The logical 'or' of:604    CDO_AUTO_CLOSEclose tray on first open(2)605    CDO_AUTO_EJECTopen tray on last release606    CDO_USE_FFLAGSuse O_NONBLOCK information on open607    CDO_LOCKlock tray on open files608    CDO_CHECK_TYPEcheck type on open for data609610outputs:611  Returns the resulting options settings in the612  ioctl return value.  Returns -1 on error.613614error return:615  ENOSYSselected option(s) not supported by drive.616617618619620CDROM_CLEAR_OPTIONSClear behavior options621622Same as CDROM_SET_OPTIONS, except that selected options are623turned off.624625626627CDROM_SELECT_SPEEDSet the CD-ROM speed628629usage:630631  int speed;632  ioctl(fd, CDROM_SELECT_SPEED, speed);633634inputs:635  New drive speed.636637outputs:none638639error return:640  ENOSYSspeed selection not supported by drive.641642643644CDROM_SELECT_DISCSelect disc (for juke-boxes)645646usage:647648  int disk;649  ioctl(fd, CDROM_SELECT_DISC, disk);650651inputs:652  Disk to load into drive.653654outputs:none655656error return:657  EINVALDisk number beyond capacity of drive658659660661CDROM_MEDIA_CHANGEDCheck is media changed662663usage:664665  int slot;666  ioctl(fd, CDROM_MEDIA_CHANGED, slot);667668inputs:669  Slot number to be tested, always zero except for jukeboxes.670  May also be special values CDSL_NONE or CDSL_CURRENT671672outputs:673  Ioctl return value is 0 or 1 depending on whether the media674  has been changed, or -1 on error.675676error returns:677  ENOSYSDrive can't detect media change678  EINVALSlot number beyond capacity of drive679  ENOMEMOut of memory680681682683CDROM_DRIVE_STATUSGet tray position, etc.684685usage:686687  int slot;688  ioctl(fd, CDROM_DRIVE_STATUS, slot);689690inputs:691  Slot number to be tested, always zero except for jukeboxes.692  May also be special values CDSL_NONE or CDSL_CURRENT693694outputs:695  Ioctl return value will be one of the following values696  from <linux/cdrom.h>:697698    CDS_NO_INFOInformation not available.699    CDS_NO_DISC700    CDS_TRAY_OPEN701    CDS_DRIVE_NOT_READY702    CDS_DISC_OK703    -1error704705error returns:706  ENOSYSDrive can't detect drive status707  EINVALSlot number beyond capacity of drive708  ENOMEMOut of memory709710711712713CDROM_DISC_STATUSGet disc type, etc.714715usage:716717  ioctl(fd, CDROM_DISC_STATUS, 0);718719inputs:none720721outputs:722  Ioctl return value will be one of the following values723  from <linux/cdrom.h>:724    CDS_NO_INFO725    CDS_AUDIO726    CDS_MIXED727    CDS_XA_2_2728    CDS_XA_2_1729    CDS_DATA_1730731error returns:none at present732733notes:734  Source code comments state:735736    Ok, this is where problems start.  The current interface for737    the CDROM_DISC_STATUS ioctl is flawed.  It makes the false738    assumption that CDs are all CDS_DATA_1 or all CDS_AUDIO, etc.739    Unfortunately, while this is often the case, it is also740    very common for CDs to have some tracks with data, and some741    tracks with audio.Just because I feel like it, I declare742    the following to be the best way to cope.  If the CD has743    ANY data tracks on it, it will be returned as a data CD.744    If it has any XA tracks, I will return it as that.Now I745    could simplify this interface by combining these returns with746    the above, but this more clearly demonstrates the problem747    with the current interface.  Too bad this wasn't designed748    to use bitmasks...       -Erik749750    Well, now we have the option CDS_MIXED: a mixed-type CD.751    User level programmers might feel the ioctl is not very752    useful.753---david754755756757758CDROM_CHANGER_NSLOTSGet number of slots759760usage:761762  ioctl(fd, CDROM_CHANGER_NSLOTS, 0);763764inputs:none765766outputs:767  The ioctl return value will be the number of slots in a768  CD changer.  Typically 1 for non-multi-disk devices.769770error returns:none771772773774CDROM_LOCKDOORlock or unlock door775776usage:777778  int lock;779  ioctl(fd, CDROM_LOCKDOOR, lock);780781inputs:782  Door lock flag, 1=lock, 0=unlock783784outputs:none785786error returns:787  EDRIVE_CANT_DO_THISDoor lock function not supported.788  EBUSYAttempt to unlock when multiple users789  have the drive open and not CAP_SYS_ADMIN790791notes:792  As of 2.6.8.1, the lock flag is a global lock, meaning that793  all CD drives will be locked or unlocked together.  This is794  probably a bug.795796  The EDRIVE_CANT_DO_THIS value is defined in <linux/cdrom.h>797  and is currently (2.6.8.1) the same as EOPNOTSUPP798799800801CDROM_DEBUGTurn debug messages on/off802803usage:804805  int debug;806  ioctl(fd, CDROM_DEBUG, debug);807808inputs:809  Cdrom debug flag, 0=disable, 1=enable810811outputs:812  The ioctl return value will be the new debug flag.813814error return:815  EACCESAccess denied:  requires CAP_SYS_ADMIN816817818819CDROM_GET_CAPABILITYget capabilities820821usage:822823  ioctl(fd, CDROM_GET_CAPABILITY, 0);824825inputs:none826827outputs:828  The ioctl return value is the current device capability829  flags.  See CDC_CLOSE_TRAY, CDC_OPEN_TRAY, etc.830831832833CDROMAUDIOBUFSIZset the audio buffer size834835usage:836837  int arg;838  ioctl(fd, CDROMAUDIOBUFSIZ, val);839840inputs:841  New audio buffer size842843outputs:844  The ioctl return value is the new audio buffer size, or -1845  on error.846847error return:848  ENOSYSNot supported by this driver.849850notes:851  Not supported by all drivers.852853854855DVD_READ_STRUCTRead structure856857usage:858859  dvd_struct s;860  ioctl(fd, DVD_READ_STRUCT, &s);861862inputs:863  dvd_struct structure, containing:864    typespecifies the information desired, one of865    DVD_STRUCT_PHYSICAL, DVD_STRUCT_COPYRIGHT,866DVD_STRUCT_DISCKEY, DVD_STRUCT_BCA,867DVD_STRUCT_MANUFACT868    physical.layer_numdesired layer, indexed from 0869    copyright.layer_numdesired layer, indexed from 0870    disckey.agid871872outputs:873  dvd_struct structure, containing:874    physicalfor type == DVD_STRUCT_PHYSICAL875    copyrightfor type == DVD_STRUCT_COPYRIGHT876    disckey.valuefor type == DVD_STRUCT_DISCKEY877    bca.{len,value}for type == DVD_STRUCT_BCA878    manufact.{len,valu}for type == DVD_STRUCT_MANUFACT879880error returns:881  EINVALphysical.layer_num exceeds number of layers882  EIOReceived invalid response from drive883884885886DVD_WRITE_STRUCTWrite structure887888Not implemented, as of 2.6.8.1889890891892DVD_AUTHAuthentication893894usage:895896  dvd_authinfo ai;897  ioctl(fd, DVD_AUTH, &ai);898899inputs:900  dvd_authinfo structure.  See <linux/cdrom.h>901902outputs:903  dvd_authinfo structure.904905error return:906  ENOTTYai.type not recognized.907908909910CDROM_SEND_PACKETsend a packet to the drive911912usage:913914  struct cdrom_generic_command cgc;915  ioctl(fd, CDROM_SEND_PACKET, &cgc);916917inputs:918  cdrom_generic_command structure containing the packet to send.919920outputs:none921  cdrom_generic_command structure containing results.922923error return:924  EIOcommand failed.925  EPERMOperation not permitted, either because a926write command was attempted on a drive which927is opened read-only, or because the command928requires CAP_SYS_RAWIO929  EINVALcgc.data_direction not set930931932933CDROM_NEXT_WRITABLEget next writable block934935usage:936937  long next;938  ioctl(fd, CDROM_NEXT_WRITABLE, &next);939940inputs:none941942outputs:943  The next writable block.944945notes:946  If the device does not support this ioctl directly, the947  ioctl will return CDROM_LAST_WRITTEN + 7.948949950951CDROM_LAST_WRITTENget last block written on disc952953usage:954955  long last;956  ioctl(fd, CDROM_LAST_WRITTEN, &last);957958inputs:none959960outputs:961  The last block written on disc962963notes:964  If the device does not support this ioctl directly, the965  result is derived from the disc's table of contents.  If the966  table of contents can't be read, this ioctl returns an967  error.