`
`Interrupt 21H (33)
`Function 3FH (63)
`Read File or Device
`
`2.0 and later
`
`Function 3FH reads from the file or device referenced by a handle.
`To Call
`
`AH
`BX
`ex
`DS:DX
`Returns
`
`=3FH
`= handle number
`= number of bytes to read
`= segment:offset of data buffer
`
`If function is successful:
`
`Carry flag is clear.
`
`AX
`DS:DX
`
`= number of bytes read from file
`= segment:offset of data read from file
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`05H
`access denied
`06H
`invalid handle
`Programmer's Notes
`• Data is read from the file beginning at the current location of the file pointer. After a
`successful read, the file pointer is updated to point to the byte following the last byte
`read.
`If Function 3FH returns OOH in the AX register, the function attempted to read when
`the file pointer was at the end of the file. If AX is less than CX, a partial record at the
`end of the file was read.
`Function 3FH can be used with all handles, including standard input (normally the
`keyboard). When reading from standard input, this function normally reads charac(cid:173)
`ters only to the first carriage-return character. Thus, the number of bytes read in AX
`will not necessarily match the length requested in CX.
`• On networks running under MS-DOS version 3.1 or later, the user must have Read
`access to the directory and file containing the information to be read.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`
`•
`
`•
`
`•
`
`1306
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1316
`
`
`
`Interrupt 21H Function 3FH
`
`Related Functions
`40H (Write File or Device)
`42H (Move File Pointer)
`59H (Get'Extended.Error Information)
`Example
`
`;************************************************************;
`
`Function 3FH: Read File or Device
`
`int read(handle,pbuffer,nbytes)
`int handle,nbytes;
`char *pbuffer;
`
`Returns -1 if there was a read error,
`otherwise returns number of bytes read.
`
`;************************************************************;
`
`cProc
`parmW
`parmDP
`parmW
`cBegin
`
`read,PUBLIC,ds
`handle
`pbuffer
`nbytes
`
`bx 1 handle
`mov
`loadDP ds,dx,pbuffer
`mov
`cx,nbytes
`mov
`ah,3fh
`int
`21h
`jnb
`rcLok
`mov
`ax,-1
`
`Get handle.
`Get pointer to buffer.
`Get number of bytes to read.
`Set function code.
`Ask MS-DOS to read ex bytes.
`Branch if read worked.
`Else return -1.
`
`rcLok:
`cEnd
`
`Section V: System Calls
`
`1307
`
`
`
`ZTE (USA) 1007, Page 1317
`
`
`
`Interrupt 21H Function 40H
`
`Interrupt 21H (33)
`Function 40H (64)
`Write File or Device
`
`2.0 and later
`
`Function 40H writes the specified number of bytes to a file or device referenced by a
`handle.
`To Call
`
`=40H
`=handle
`=number of bytes to write
`= segment: offset of data buffer
`
`AH
`BX
`ex
`DS:DX
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`AX
`
`= number of bytes written to file or device
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`05H
`access denied
`06H
`invalid handle
`Programmer's Notes
`
`•
`
`• Data is written to the file or device beginning at the· current location of the file
`pointer. After writing the specified data, Function 40H updates the position of the
`file pointer and returns the actual number of bytes written in AX.
`Function 40H returns error code 05H (access denied) if the file was opened as read(cid:173)
`only with Function 3CH (Create File with Handle), 3DH (Open File with Handle),
`5AH (Create Temporary File), or 5BH (Create New File). On networks running under
`MS-DOS version 3.1 or later, access is also denied if the file or record has been locked
`by another process.
`The handle number in BX must be one of the predefined device handles (0 through 4)
`or a handle obtained through a previous call to open or create a file (such as Function
`3CH, 3DH, 5AH, or 5BH).
`If CX = 0, the file is truncated or extended to the current file pointer location. Clusters
`are allocated or released in the file allocation table (FAT) as required to fulfill the
`request.
`
`•
`
`•
`
`1308
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1318
`
`
`
`Interrupt 21H Function 40H
`
`•
`
`•
`
`If the handle parameter for Function 40H refers to a disk file and the number of bytes
`written (returned in AX) is less than the number requested in CX, the destination disk
`is full. The carry flag is not set in this situation.
`Function 59H (Get Extended Error Information) provides further information on any
`·error-in partkular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`3FH (Read File or Device)
`42H (Move File Pointer)
`Example
`
`;************************************************************;
`
`Function 40H: Write File or Device
`
`int write(handle,pbuffer,nbytes)
`int handle,nbytes;
`char *pbuffer;
`
`Returns -1 if there was a write error,
`otherwise returns number of bytes written.
`
`;************************************************************;
`
`cProc
`parmW
`parmDP
`parmW
`cBegin
`
`write,PUBLIC,ds
`handle
`pbuffer
`nbytes
`
`bx,handle
`mov
`loadDP ds,dx,pbuffer
`mov
`cx,nbytes
`mov
`ah,40h
`int
`21h
`wr_ok
`jnb
`mov
`ax,-1
`
`Get handle.
`Get pointer to buffer.
`Get number of byt.es to write.
`Set function code.
`Ask MS-DOS to write CX bytes.
`Branch if write successful.
`Else return -1 .
`
`wr_ok:
`cEnd
`
`Section V.· System Calls
`
`1309
`
`
`
`ZTE (USA) 1007, Page 1319
`
`
`
`2.0 and later
`
`Interrupt 21H Function 41H
`
`Interrupt 21H (33)
`Function 41H (65)
`Delete File
`
`Function 41H deletes the directory entry of the specified file.
`To Call
`
`=41H
`= segment: offset of ASCIIZ pathname
`
`AH
`DS:DX
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`02H
`file not found
`03H
`path not found
`05H
`access denied
`Programmer's Notes
`• The pathname must be a null-terminated ASCII string (ASCIIZ). Unlike Function 13H
`(Delete File), Function 41H does not allow wildcard characters in the pathname.
`• Because Function 41H supports the use of full pathnames, it is preferable to Function
`13H.
`Function 41H returns error code 05H (access denied) and fails if the file has either a
`directory or volume attribute or if it is a read-only file.
`A directory can be deleted (if it is empty) with Function 3AH (Remove Directory). A
`read-only file can be deleted if its attribute is changed to normal with Function 43H
`.(Get/Set File Attributes) before Function 41H is called.
`• On networks running under MS-DOS version 3.1 or later, the user must have Create
`access to the directory containing the file to be deleted.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`3AH (Remove Directory)
`43H (Get/Set File Attributes)
`
`•
`
`•
`
`1310
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1320
`
`
`
`Interrupt 21H Function 41H
`
`Example
`
`;************************************************************;
`
`Function 41H: Delete File
`
`int delete(pfilepath)
`char *pfilepath;
`
`Returns 0 if file deleted,
`otherwise returns error code.
`
`;~***********************************************************;
`
`delete,PUBLIC,ds
`cProc
`parrnDP pfilepath
`cBegin
`
`loadDP ds,dx,pfilepath
`mov
`ah, 41h
`iht
`21h
`dl_err
`jb
`
`xor
`
`a:x:,a:x:
`
`dl_err:
`cEnd
`
`Get pointer to pathnarne.
`Set function code.
`Ask MS-DOS to delete file.
`Branch if MS-DOS could not delete
`file.
`Else return 0.
`
`Section V: System Calls
`
`1311
`
`
`
`ZTE (USA) 1007, Page 1321
`
`
`
`Interrupt 21H Function 42H
`
`Interrupt 21H (33)
`Function 42H (66)
`Move File Pointer
`
`2.0 and later
`
`Function 42H sets the position of the file pointer (for the next read/write operation) for .
`the file associated with the specified handle.
`To Call
`
`AH
`AL
`
`BX
`CX:DX
`
`=42H
`= method code:
`OOH
`byte offset from beginning of file
`01H
`byte offset from current location of file pointer
`02H
`byte offset from end of file
`= handle number
`= offset value to move pointer:
`ex
`most significant half of a doubleword value
`DX
`least significant half of a doubleword value
`
`Returns
`!(function is successful:
`
`Carry flag is clear.
`
`DX:AX
`
`= new file pointer position (absolute byte offset from beginning of file)
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`01H
`invalid function (AL not OOH, 01H, or 02H)
`06H
`invalid handle
`Programmer's Notes
`•
`The value in CX:DX is an offset specifying how far the file pointer is to be moved.
`With method code OOH, the value in CX:DX is always interpreted as a positive 32-bit
`integer, meaning the file pointer is always set relative to the beginning of the file.
`With method codes 01H and 02H, the value in CX:DX can be either a positive or nega(cid:173)
`tive 32-bit integer. Thus, method 1 can move the file pointer either forward or back(cid:173)
`ward from its current position; method 2 can move the file pointer either forward or
`backward from the end of the file.
`
`1312
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1322
`
`
`
`Interrupt 21H Function 42H
`
`•
`
`Specifying method code OOH with an offset of 0 positions the file pointer at the begin(cid:173)
`ning of the file. Similarly, specifying method code 02H with an offset of 0 conve(cid:173)
`niently positions the file pointer at the end of the file. With method code 02H offset 0,
`the size of the file can also be determined by examining the pointer position returned
`by the function.
`• Depending on the offset specified in CX:DX, methods 1 and 2 may move the file
`pointer to a position before the start of the file. Function 42H does not return an error
`code if this happens, but later attempts to read from or write to the file will produce
`unexpected errors.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`3FH (Read File or Device)
`40H (Write File or Device)
`Example
`
`•
`
`:************************************************************;
`
`Function 42H: Move File Pointer
`
`long seek(handle,distance,mode)
`int handle,mode;
`long distance;
`
`Modes:
`
`0: from beginning of file
`1: from the current position
`2: from the end of the file
`
`Returns -1 if there wa$ a seek error,
`otherwise returns long pointer position.
`
`:************************************************************:
`
`cProc
`parmw
`parmD
`parmB
`cBegin
`
`$eek,PUBtlC
`handle
`distance
`mode
`
`mov
`les
`mov
`mov
`mov
`
`bx,handle
`dx,distance
`cx,es
`al,mode
`ah,42h
`
`Get handle.
`Get distance into ES:DX.
`Put high word of di$tance into ex.
`Get move method code.
`set function code.
`
`(more)
`
`Section V.· System Calls
`
`1313
`
`
`
`ZTE (USA) 1007, Page 1323
`
`
`
`Interrupt 21H Function 42H
`
`int
`jnb
`mov
`cwd
`
`21h
`sk_ok
`ax,-1
`
`sLok:
`cEnd
`
`Ask MS-DOS to move file pointer.
`Branch if seek successful.
`Else return -1 .
`
`1314
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1324
`
`
`
`Interrupt 21H (33)
`Function 43H (67)
`Get/Set File Attributes
`
`Function 43H gets or sets the attributes of the specified file.
`To Call
`AH
`
`=43H
`
`To get file attributes:
`
`AL
`DS:DX
`
`=OOH
`= segment: offset of ASCIIZ pathname
`
`To set file attributes:
`
`AL
`ex
`
`=01H
`= attributes to set:
`
`Bit
`
`Attribute
`
`0
`1
`2
`5
`
`Read-only file
`Hidden file
`System file
`Archive
`
`DS:DX
`Returns
`
`= segment:offset of ASCIIZ pathname
`
`If function is successful:
`
`Carry flag is clear.
`ex
`If function is not successful:
`
`= attribute .
`
`Carry flag is set.
`
`AX
`
`= error code:
`01H
`invalid function (AL not OOH or 01H)
`file not found
`02H
`03H
`path not found
`05H
`access denied
`
`Interrupt 21H Function 43H
`
`2.0 and later
`
`Section V: System Calls
`
`1315
`
`
`
`ZTE (USA) 1007, Page 1325
`
`
`
`Interrupt 21H Function 43H
`
`Programmer's Notes
`•
`The pathname must be a null-terminated ASCII string (ASCIIZ).
`•
`Function 43H cannot be used to set or change either a volume-label or directory at(cid:173)
`tribute (bits 3 and 4 of the attribute byte). With MS-DOS versions 3.x, Function 43H
`can be used to make a directory hidden or read-only.
`• On networks running under MS-DOS version 3.1 or later, the user must have Create
`access to the directory containing the file in order to change the read-only, hidden, or
`system attribute. The archive bit, however, can be changed regardless of access rights.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`None
`Example
`
`•
`
`:************************************************************;
`
`Function 43H: Get/Set File Attributes
`
`int file_attr(pfilepath,func,attr)
`char *pfilepath;
`int func, attr;
`
`Returns -1 for all errors,
`otherwise returns file attribute.
`
`:************************************************************:
`
`cProc
`parmDP
`parmB
`parmW
`cBegin
`
`file_attr,PUBLIC,ds
`pfilepath
`func
`attr
`
`loadDP ds,dx,pfilepath
`mov
`al,func
`mov
`cx,attr
`ah,43h
`mov
`int
`21h
`fa_ok
`jnb
`cx,-1
`mov
`
`Get pointer to pathname.
`Get/set flag into AL.
`Get new attr (if pres"ent).
`Set code function.
`Call MS-DOS.,
`Branch if no error.
`Else return -1 .
`
`mov
`
`ax, ex
`
`Return this value.
`
`fa_ok:
`
`cEnd
`
`13}6
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1326
`
`
`
`Interrupt 2m (33)
`Function 44H (68)
`IOCTL
`
`Interrupt 21H Function 44H
`
`2.0 and later
`
`Function 44H is a collection of subfunctions that provide a process a direct path of com(cid:173)
`munication with a device driver. As such, this function is the most flexible means of gain(cid:173)
`ing access to the full capabilities of an installed device.
`
`An IOCTL subfunction is called with 44H in AH and the value for the subfunction in AL. If
`a subfunction has minor functions, those values are specified in CL. Otherwise, the BX,
`CX, and DX registers are used for such information as handles, drive identifiers, buffer ad(cid:173)
`dresses, and so on.
`
`The subfunctions and the versions of MS-DOS with which they are available are
`
`Subfunction
`
`Name
`
`OOH
`01H
`02H
`03H
`04H
`05H
`06H
`07H
`08H
`09H
`OAH
`OBH
`OCH
`
`ODH
`
`Get Device Data
`Set Device Data
`Receive Control Data from Character Device
`Send Control Data to Character Device
`Receive Control Data from Block Device
`Send Control Data to Block Device
`Check Input Status
`Check Output Status
`Check If Block Device Is Removable
`Check If Block Device Is Remote
`Check If Handle Is Remote
`Change Sharing Retry Count
`Generic I/0 Control for Handles
`Minor Code 45H: Set Iteration Count
`Minor Code 65H: Get Iteration Count
`Generic I/0 Control for Block Devices
`Minor Code 40H: Set Device Parameters
`Minor Code 60H: Get Device Parameters .
`Minor Code 41H: Write Track on Logical Drive
`Minor Code 61H: Read Track on Logical Drive
`Minor Code 42H: Format and Verify Track
`on Logical Drive
`Minor Code 62H: Verify Track on Logical Drive
`
`MS-DOS
`Versions
`
`2.0 and later
`2.0 and later
`2.0 and later
`2.0 and later
`2.0 and later
`2.0 and later
`2.0 and later
`2.0 and later
`3.0 and later
`3.1 and later
`3.1 and later
`3.1 and later
`3.2
`
`3.2
`
`(more)
`
`Section V System Calls
`
`1317
`
`
`
`ZTE (USA) 1007, Page 1327
`
`
`
`Interrupt 21H Function 44H
`
`Sub function
`
`Name
`
`OEH
`OFH
`
`Get Logical Drive Map
`Set Logical Drive Map
`
`MS-DOS
`Versions
`
`3.2
`3.2
`
`These subfunctions are documented, either individually or in related pairs, in the entries
`that follow.
`
`1318
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1328
`
`
`
`Interrupt 21H Function 44H Subfunction OOH
`
`Interrupt 21H (33)
`Function 44H (68) Subfunction OOH
`IOCTL: Get Device Data
`
`2.0 and later
`
`Function 44H Subfunction OOH gets information about a character device or file referenced
`by a handle.
`To Call
`
`AH =44H
`AL =OOH
`BX = handle number
`Returns
`
`If function is successful:
`
`Carry flag is clear.
`
`DX contains information on file or device:
`
`Bit
`
`Value
`
`Meaning
`
`For a file (bit 7 = 0):
`8-15
`0
`7
`0
`6
`0
`0-5
`
`For a device (bit 7 = 1):
`0
`15
`14
`1
`
`8-13
`7
`6
`5
`
`0
`1
`0
`0
`1
`
`Reserved.
`Handle refers to a file.
`File has been written.
`Drive number (0 = A, 1 = B, 2 = C, and so on).
`
`Reserved.
`Processes control strings transferred by IOCTL Subfunctions 02H
`(Receive Control Data from Character Device) and 03H (Send
`Control Data to Character Device), set by MS-DOS.
`Reserved.
`Handle refers to a device.
`End of file on input.
`Checks for control characters (cooked mode).
`Does not check for control characters (raw mode).
`
`(more)
`
`Section V: System Calls
`
`1319
`
`
`
`ZTE (USA) 1007, Page 1329
`
`
`
`Interrupt 21H Function 44H Subfunction OOH
`
`Bit
`
`Value
`
`Meaning
`
`4
`3
`2
`1
`0
`
`0
`1
`1
`1
`1
`
`Reserved.
`Clock device.
`Null device.
`Standard output device.
`Standard input device.
`
`If function is not successful:
`
`Carry flag is set.
`
`AX = error code:
`01H
`invalid IOCTL subfunction
`05H
`access denied
`06H
`invalid handle
`Programmer's Notes
`• Bits 8-15 of DX correspond to the upper 8 bits of the device-driver attribute word.
`• The handle in BX must reference an open device or file.
`• Bit 5 of the device data word for character-device handles defines whether that han(cid:173)
`dle is in raw mode or cooked mode. In cooked mode, MS-DOS checks for Control-C,
`Control-P, Control-S, and Control-Z characters and transfers control to the Control-C
`exception handler (whose address is saved in the vector for Interrupt 23H) when a
`Control-C is detected. In raw mode, MS-DOS does not check for such characters when
`1/0 is performed to the handle; however, it will still check for a Control-C entered at
`the keyboard on other function calls unless such checking has been turned off with
`Function 33H, the BREAK= OFF directive in CONFIG.SYS, or a BREAK OFF com(cid:173)
`mand at the MS-DOS prompt.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`33H (Get/Set Control-C Check Flag)
`3CH (Create File with Handle)
`3DH (Open File with Handle)
`
`•
`
`1320
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1330
`
`
`
`Interrupt 21H Function 44H Subfunction OOH ·
`
`Example
`
`;************************************************************;
`
`Function 44H, Subfunctions OOH,01H:
`Get/Set IOCTL Device Data
`
`int ioctl_char_flags(setflag,handle,newflags)
`int setflag;
`int handle;
`int newflags;
`
`Set setflag = 0 to get flags, 1 to set flags.
`
`Returns -1 for error, else returns flags.
`
`;************************************************************;
`
`cProc
`parmB
`parmW
`parmW
`cBegin
`
`ioctl_char_flags,PUBLIC
`set flag
`handle
`newflags
`
`mov
`and
`mov
`mov
`
`mov
`int
`mov
`
`jnc
`mov
`
`al,setflag
`al, 1
`bx,handle
`dx,newflags
`
`ah,44h
`21h
`ax,dx
`
`iocfx
`ax,-1
`
`Ge.t set flag.
`Save only lsb.
`Get handle to character device.
`Get new flags (they are used only
`by "set" option).
`Set function code.
`Call MS-DOS.
`Assume success - prepare to return
`flags.
`Branch if no error.
`Else return error flag.
`
`iocfx:
`cEnd
`
`Section V.· System Calls
`
`1321
`
`
`
`ZTE (USA) 1007, Page 1331
`
`
`
`·Interrupt 21H Function 44H Subfunction OlH
`
`Interrupt 21H (33)
`Function 44H (68) Subfunction OlH
`IOCTL: Set Device Data
`
`2.0 and later
`
`Function 44H Subfunction 01H, the complement of IOCTL Subfunction OOH, sets informa(cid:173)
`tion about a character device- but not a file- referenced by a handle.
`To Call
`AH =44H
`AL =01H
`BX = handle number
`OX = device data word:
`
`Bit
`
`8-15
`7
`6
`5
`
`4
`3
`2
`1
`0
`
`Value
`
`Meaning
`
`0
`1
`0
`0
`
`1
`
`0
`1
`1
`1
`1
`
`Reserved.
`Handle refers to a device.
`End of file on input.
`Check for control characters
`(cooked mode).
`Do not check for control characters
`(raw mode).
`Reserved.
`Clock device.
`Null device.
`Standard output device.
`Standard input device.
`
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`If function is not successful:
`
`Carry flag is set.
`
`AX = error code:
`01H
`invalid IOCTL subfunction
`05H
`access denied
`06H
`invalid handle
`
`1322
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1332
`
`
`
`Interrupt 21H Function 44H Subfunction OlH
`
`Programmer's Notes
`• The handle in BX must reference an open device.
`• DH must be OOH. If it is not, the carry flag is set and error code OlH (invalid function)
`is returned.
`• Bit 5 of the device data word for character-device handles selects raw mode or cooked
`mode for the handle. In cooked mode, MS-DOS checks for Control-C, Control-P,
`Control-S, and Control-Z characters and transfers control to the Control-C exception
`handler (whose address is saved in the vector for Interrupt 23H) when a Control-Cis
`detected. In raw mode, MS-DOS does not check for such characters when I/0 is per(cid:173)
`formed to the handle; however, it will still check for a Control-C entered at the key(cid:173)
`board on other function calls unless such checking has been turned off with Function
`33H, the BREAK=OFF directive in CONFIG.SYS, or a BREAK OFF command at the
`MS-DOS prompt.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`33H (Get/Set Control-C Check Flag)
`3CH (Create File with Handle)
`3DH (Open File with Handle)
`Example
`See SYSTEM CALLS: INTERRUPT 21H: Function 44H Subfunction OOH.
`
`•
`
`Section V: System Calls
`
`1323
`
`
`
`ZTE (USA) 1007, Page 1333
`
`
`
`Interrupt 21H Function 44H Subfunctions 02H and 03H
`
`Interrupt 21H (33)
`2.0 and later
`Function 44H (68) Subfunctions 02H and 03H
`IOCTL: Receive Control Data from Character Device; Send Control Data to
`Character Device
`
`Function 44H Subfunctions 02H and 03H respectively receive and send control strings
`from and to a character-oriented device driver.
`To Call
`
`AH
`AL
`
`=44H
`receive control strings
`= 02H
`send control strings
`03H
`= handle number
`= number of bytes to transfer
`= segment: offset of data buffer
`
`BX
`ex
`DS:DX
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`AX
`
`= number of bytes transferred
`
`If AL was 02H on call:
`
`Buffer at DS:DX contains data read from device driver.
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`OlH
`invalid function
`05H
`access denied
`06H
`invalid handle
`ODH
`invalid data (bad control string)
`Programmer's Notes
`•
`Subfunctions 02H and 03H provide a means of transferring control information of any
`type or length between an application program and a character-device driver. They
`do not necessarily result in any input to or output from the physical device itself.
`Subfunction 02H can be used to read control information about such features as
`device status, availability, and current output location. Subfunction 03H is often used
`to configure the driver or device for subsequent I/0; for example. it may be used to set
`the baud rate, word length, and parity for a serial communication'S adapter or to initial(cid:173)
`ize a printer for a specific font, page length, and so on. The format of the control data
`passed by these subfunctions is driver specific and does not follow any standard.
`
`•
`
`1324
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1334
`
`
`
`Interrupt 21H Function 44H Subfunctions 02H and 03H
`
`•
`
`• Character-device drivers are not required to support IOCTL Subfunctions 02H and
`03H. Therefore, Subfunction OOH (Get Device Data) should be called before either
`Subfunction 02H or 03H to determine whether a device can process control strings.
`If bit 14 of the device data word returned bySubfunction OOH is set, the device driver
`supports IOCTL Subfunctions 02H and 03H.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`44H Subfunction OOH (Get Device Data)
`44H Subfunction 04H (Receive Control Data from Block Device)
`44H Subfunction 05H (Send Control Data to Block Device)
`Example
`
`;************************************************************;
`
`Function 44H, Subfunctions 02H,03H:
`IOCTL Character Device control
`
`int ioctl_char_ctrl(recvflag,handle,pbuffer,nbytes)
`int
`recvflag;
`int
`handle;
`char *pbuffer;
`int
`nbytes;
`
`Set recvflag = 0 to receive info, 1 to send.
`
`Returns -1 for error, otherwise returns number of
`byte~ sent or received.
`
`;************************************************************;
`
`cProc
`parmB
`parmW
`parmDP
`parmW
`cBegin
`
`ioctl_char_ctrl,PUBLIC,<ds>
`recvflag
`handle
`pbuffer
`nbytes
`
`mov
`and
`add
`mov
`mov
`loadDP
`mov
`int
`jnc
`mov
`
`al,recvflag
`al, 1
`al,2
`bx,handle
`cx,nbytes
`ds,dx,pbuffer
`ah,44h
`21h
`iccx
`ax,-1
`
`Get recvflag.
`Keep only lsb.
`AL = 02H for receive, 03H for send.
`Get character-device handle.
`Get number of bytes to receive/send.
`Get pointer to buffer.
`Set function code.
`Call MS-DOS.
`Branch if no error.
`Return -1 for all errors.
`
`iccx:
`cEnd
`
`Section V: System Calls
`
`1325
`
`
`
`ZTE (USA) 1007, Page 1335
`
`
`
`Interrupt 21H Function 44H Subfunctions 04H and OSH
`
`Interrupt 21H (33)
`2.0andlater
`Function 44H (68) Subfunctions 04H and.05H
`IOCTL: Receive Control Data from Block Device; Send Control Data to Block
`Device
`
`Function 44H Subfunctions 04H and 05H respectively receive and send control strings
`from and to a block-oriented device driver.
`To Call
`AH
`AL
`
`=44H
`receive block-device data
`=04H
`send block-device data
`05H
`= drive number (0 = default drive, 1 = drive A, 2 = drive B, and so on)
`= number of bytes to transfer
`= segment:offset of data buffer
`
`BL
`ex
`DS:DX
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`AX
`
`= number of bytes transferred
`
`If AL was 04H on call:
`
`Buffer at DS:DX contains control data read from device driver.
`
`If function is not successful:
`
`Carry flag is set.
`
`AX
`
`= error code:
`01H
`invalid function
`05H
`access denied
`06H
`invalid handle
`ODH
`invalid data (bad control string)
`Programmer's Notes
`•
`Subfunctions 04H and 05H provide a means of transferring control information of any
`type or length between an application program and a block-device driver. They do
`not necessarily result in any input to or output from the physical device itself.
`• Control strings can be used to request driver operations that are not file oriented, such
`as tape rewind or disk eject (if hardware supported). The contents of such control
`strings are specific to individual device drivers and do not follow any standard format.
`
`1326
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1336
`
`
`
`Interrupt 21H Function 44H Subfunctions 04H and 05H
`
`•
`
`•
`
`Subfunction 04H can be used to obtain a code from the driver indicating device avail(cid:173)
`ability or status. Block devices that might use this subfunction include magnetic tape
`or tape cassette, CD ROM, and Small Computer Standard Interface (SCSI) devices.
`• Block-device drivers are not required to support IOCTL Subfunctions 04H and 05H. If
`the driver does not support these subfunctions, error code OlH (Invalid Function) is
`returned.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`44H Subfunction OOH (Get Device Data)
`44H Subfunction 02H (Receive Control Data from Character Device)
`44H Subfunction 03H (Send Control Data to Character Device)
`Example
`
`;************************************************************;
`
`Function 44H, Subfunctions 04H,05H:
`IOCTL Block Device Control
`
`int ioctl-block_ctrl(recvflag,drive_ltr,pbuffer,nbytes)
`int
`recvflag;
`int
`drive_ltr;
`char *pbuffer;
`int
`nbytes;
`
`Set recvflag = 0 to receive info, 1 to send.
`
`Returns -1 for error, otherwise returns number of
`bytes sent or received.
`
`;********************************~***************************;
`
`cProc
`parmB
`parmB
`parmDP
`parmW
`cBegin
`
`ioctl-block_ctrl,PUBLIC,<ds>
`recvflag
`drive_ltr
`pbuffer
`nbytes
`
`mov
`and
`add
`mov
`or
`jz
`and
`sub
`
`al,recvflag
`al, 1
`al,4
`bl,drive_ltr
`bl,bl
`ibc
`bl,not 20h
`bl, 'A'-1
`
`Get recvflag.
`Keep only lsb.
`AL = 04H for receive, OSH for send.
`Get drive letter.
`Leave 0 alone.
`
`Convert letter to uppercase.
`Convert to drive number:
`'A'
`'B' = 2, etc.
`
`1,
`
`(more)
`
`Section V: System Calls
`
`1327
`
`
`
`ZTE (USA) 1007, Page 1337
`
`
`
`Interrupt 21H Function 44H Subfunctions 04H and OSH
`
`ibc:
`
`ibex:
`cEnd
`
`cx,nbytes
`mov
`loadDP ds,dx,pbuffer
`mov
`ah,44h
`int
`21h
`jnc
`ibex
`mov
`ax,-1
`
`Get number of bytes to receive/send.
`Get pointer to buffer.
`Set function code.
`Call MS-DOS.
`Branch if no error.
`Return -1 for all errors.
`
`1328
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1338
`
`
`
`Interrupt 21H Function 44H Subfunctions 06H and 07H
`
`Interrupt 21H (33)
`2.0andlater
`Function 44H (68) Subfunctions 06H and 07H
`IOCTL: Check Input Status; Check Output Status
`
`Function 44H Subfunctions 06H and 07H respectively determine whether a device or file
`associated with a handle is ready for input or output.
`To Call
`AH =44H
`get input status
`AL = 06H
`get output status
`07H
`BX = handle number
`Returns
`
`If function is successful:
`
`Carry flag is clear.
`
`AL = input or output status:
`OOH
`not ready
`FFH
`ready
`
`If function is not successful:
`
`Carry flag is set.
`
`AX = error .code:
`OlH
`invalid function
`05H
`access denied
`06H
`invalid handle
`ODH
`invalid data (bad control string)
`Programmer's Notes
`• The status returned in AL has the following meanings:
`
`Status
`
`Device
`
`Input File
`
`Output File
`
`OOH
`OFFH
`
`Not ready
`Ready
`
`Pointer at EOF
`Ready
`
`Ready
`Ready
`
`Section V: System Calls
`
`1329
`
`
`
`ZTE (USA) 1007, Page 1339
`
`
`
`Interrupt 21H Function 44H Subfunctions 06H and 07H
`
`•
`
`• Output files always return a ready condition, even if the disk is full or no disk is in the
`drive.
`Function 59H (Get Extended Error Information) provides further information on any
`error- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`None
`Example
`
`;************************************************************;
`
`Function 44H, Subfunctions 06H,07H:
`IOCTL Input/Output Status
`
`int ioctl_char_status(outputflag,handle)
`int output flag;
`int handle;
`
`Set outputflag = 0 for input status, 1 for output status.
`
`Returns -1 for all errors, 0 for not ready,
`and 1 for ready.
`
`;************************************************************;
`
`cProc
`parmB
`parmW
`cBegin
`
`ioctl_char_status,PUBLIC
`output flag
`handle
`
`mov
`and
`add
`
`al,outputflag
`al, 1
`al,6
`
`Get outputflag.
`Keep only lsb.
`AL = 06H for input status, 07H for output
`status.
`Get handle.
`Set function code.
`Call MS-DOS.
`Branch if no error.
`Return error code.
`
`bx,handle
`ah,44h
`21h
`isnoerr
`ax,-1
`short isx
`
`mov
`mov
`int
`jnc
`mov
`jmp
`isnoerr:
`and
`
`isx:
`cEnd
`
`ax, 1
`
`Keep only lsb for return value.
`
`1330
`
`The MS-DOS Encyclopedia
`
`
`
`ZTE (USA) 1007, Page 1340
`
`
`
`Interrupt 21H Function 44H Subfunction 08H
`
`Interrupt 21H (33)
`Function 44H (68) Subfunction.OSH
`IOCTL: Check If Block Device Is Removable
`
`3.0 and later
`
`Function 44H Subfunction 08H checks whether the specified block device contains a
`removable storage medium, such as a floppy disk.
`To Call
`AH =44H
`AL = 08H
`BL = drive number (0 = default drive, 1 = drive A, 2 = drive B, and so on)
`Returns
`If function is successful:
`
`Carry flag is clear.
`
`AX =OOH
`OlH
`
`storage medium removable
`storage medium not removable
`
`If function is not successful:
`
`Carry flag is set.
`
`AX = error code:
`01H
`invalid function
`OFH
`invalid drive
`Programmer's Notes
`•
`This subfunction exists to allow an application to check for a removable disk so that
`the user can be prompted to change disks if a required file is not found.
`• When the carry flag is set, error code 01H normally means that MS-DOS did not recog(cid:173)
`nize the function call. However, this error can also mean that the device driver does
`not support Subfunction 08H. In this case, MS-DOS assumes that the storage medium
`is not removable.
`Function 59H (Get Extended Error Information) provides further information on any
`erro£- in particular, the code, class, recommended corrective action, and locus of
`the error.
`Related Functions
`None
`
`•
`
`Section V.· System Calls
`
`1331
`
`
`
`ZTE (USA) 1007, Page 1341
`
`
`
`Interrupt 21H F