INT 21 - DOS 2+ - "WRITE" - WRITE TO FILE OR DEVICE
AH = 40h
BX = file handle
CX = number of bytes to write
DS:DX -> data to write
Return: CF clear if successful
AX = number of bytes actually written
CF set on error
AX = error code (05h,06h) (see #01680 at AH=59h/BX=0000h)
Notes: if CX is zero, no data is written, and the file is truncated or
extended to the current position
data is written beginning at the current file position, and the file
position is updated after a successful write
for FAT32 drives, the file must have been opened with AX=6C00h with
the "extended size" flag in order to expand the file beyond 2GB;
otherwise the write will fail with error code 0005h (access denied)
the usual cause for AX < CX on return is a full disk
when a file must be extended (it was shorter than the current seek
plus input CX) but there isn't enough disk space free, FreeDOS will
allocate all remaining free clusters to the file, and may do a
partial write. it may return AX = 0000h or 0 < AX < CX in this case.
MS-DOS instead always returns AX = 0000h with the file size
preserved from what it was prior to this call (no partial write and
not even extending to the file seek prior to this call).
a portable check that a write succeeded in full should first check
that the returned CF is clear, then check that the returned AX == CX
(only applicable if CX was nonzero, see BUGS below).
dosemu2 mfs redirected drives return error 0005h if CX = 0000h and
the file cannot grow to the indicated size, with the prior file size
preserved. non-zero writes are passed to the Linux write syscall.
under the FlashTek X-32 DOS extender, the pointer is in DS:EDX
BUGS: a write of zero bytes will appear to succeed when it actually failed
if the write is extending the file and there is not enough disk
space for the expanded file (DOS 5.0-6.0); one should therefore check
whether the file was in fact extended by seeking to 0 bytes from
the end of the file (INT 21/AX=4202h with CX:DX=0000h:0000h)
FreeDOS kernel bug #241 concerns seeking to a position larger than the
disk free space, then writing using this function. it will allocate
all free clusters to the file but fail to update the file size field.
MS-DOS v4 and v5 (at least) will truncate the "amount of clusters to
allocate" to a 16-bit quantity so if trying to allocate eg slightly
more than 256 MiB (1000_1000h Bytes) on a FAT12 1440 KiB diskette
(512 BpC) the needed amount is truncated (eg to 8 clusters) and the
file is corrupted. this bug does not exist on MS-DOS v7.10,
presumably because it calculates the amount as a 32-bit number as it
needs to support large values for FAT32 drives.
SeeAlso: AH=28h,AH=3Fh"DOS",AH=93h,INT 2F/AX=1109h