Important Notice

The pages on this site contain documentation for very old MS-DOS software, purely for historical purposes. If you're looking for up-to-date documentation, particularly for programming, you should not rely on the information found here, as it will be woefully out of date.

◄Function Group►  ◄Overview►  ◄Changes►               ◄Up► ◄Next► ◄Previous►
────────────────────────────────────────────────────────────────────────────
 
#define INCL_DOSFILEMGR
 
USHORT DosWrite(hf, pvBuf, cbBuf, pcbBytesWritten)
HFILE hf;                   /* file handle                              */
PVOID pvBuf;                /* pointer to buffer                        */
USHORT cbBuf;               /* number of bytes to write                 */
PUSHORT pcbBytesWritten;    /* pointer to variable receiving byte count */
 
The DosWrite function writes data from a buffer to a file, then copies the
number of bytes written to a variable.
 
The DosWrite function is a family API function.
 
Parameter        Description
────────────────────────────────────────────────────────────────────────────
 
hf               Identifies the file that receives the data. This handle
                 must have been created by using the DosOpen function.
 
pvBuf            Points to the buffer that contains the data to write.
 
cbBuf            Specifies the number of bytes to write.
 
pcbBytesWritten  Points to the variable receiving the number of bytes
                 written.
 
Return Value
 
The return value is zero if the function is successful. Otherwise, it is an
error value, which may be one of the following:
 
     ERROR_ACCESS_DENIED
     ERROR_BROKEN_PIPE
     ERROR_INVALID_HANDLE
     ERROR_LOCK_VIOLATION
     ERROR_NOT_DOS_DISK
     ERROR_WRITE_FAULT
 
Comments
 
The DosWrite function begins to write at the current file-pointer position.
The file-pointer position can be changed by using the DosChgFilePtr
function.
 
If the specified file has been opened using the write-through flag, the
DosWrite function writes data to the disk before returning. Otherwise, the
system collects the data in an internal file buffer and writes the data to
the disk only when the buffer is full.
 
The DosWrite function may write fewer bytes to the file than the number
specified in the cbBuf parameter if there is not enough space on the disk
for all of the requested bytes. The cbBuf parameter can be zero without
causing an error──that is, writing no bytes is acceptable.
 
The efficiency with which DosWrite writes to a disk is improved when cbBuf
is set to a multiple of the disk's bytes-per-sector size. When cbBuf is set
this way, DosWrite writes directly to the disk, without first copying the
data to an internal file buffer. (DosQFSInfo retrieves the bytes-per-sector
value for a disk.)
 
DosWrite can be used to write bytes or messages to a pipe. Each write to a
message pipe writes a message whose size is the length of the write;
DosWrite automatically encodes message lengths in the pipe, so applications
need not encode this information in the buffer being written.
 
Writes in blocking mode always write all requested bytes before returning.
In nonblocking mode, writes return either with all bytes written or none
written; the latter will occur in cases where DosWrite would have to block
in order to complete the request──for example, if there is no room in the
pipe buffer or if the buffer is currently being written to by another
client).
 
An attempt to write to a pipe whose other end has been closed will return
the error ERROR_BROKEN_PIPE.
 
Example
 
This example creates the file abc and calls the DosWrite function to write
the contents of the abBuf buffer to the file:
 
BYTE abBuf[512];
HFILE hf;
USHORT usAction, cbBytesWritten, usError;
usError = DosOpen("abc", &hf, &usAction, 0L, FILE_NORMAL,
    FILE_CREATE,
    OPEN_ACCESS_WRITEONLY | OPEN_SHARE_DENYWRITE, 0L);
if (!usError) {
    DosWrite(hf,                  /* file handle              */
        abBuf,                    /* buffer address           */
        sizeof(abBuf),            /* buffer size              */
        &cbBytesWritten);         /* address of bytes written */
 
See Also
 
DosChgFilePtr, DosOpen, DosQFSInfo, DosRead, DosWriteAsync
 
                                      ♦