en:docs:fapi:doswrite

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision		Previous revision
en:docs:fapi:doswrite [2018/08/30 14:58] – created prokusheven:docs:fapi:doswrite [2021/09/17 09:16] (current) – prokushev
Line 1: Line 1:
 +{{page>en:templates:fapiint}}
 +
 +====== DosWrite ======
  
 This call transfers the specified number of bytes from a buffer to the specified file, synchronously with respect to the requesting process's execution.  This call transfers the specified number of bytes from a buffer to the specified file, synchronously with respect to the requesting process's execution. 
  
-==Syntax== +===== Syntax ===== 
- DosWrite (FileHandle, BufferArea, BufferLength, BytesWritten)+<code c> 
 +DosWrite (FileHandle, BufferArea, BufferLength, BytesWritten) 
 +</code>
  
-==Parameters== +===== Parameters ===== 
-;FileHandle (HFILE) - input : File handle from DosOpen. + 
-;BufferArea (PVOID) - input : Address of the output buffer. +  * FileHandle ([[HFILE]]) - input : File handle from DosOpen. 
-;BufferLength (USHORT) - input : Number of bytes to write. +  * BufferArea ([[PVOID]]) - input : Address of the output buffer. 
-;BytesWritten (PUSHORT) - output : Address of the number of bytes written.+  * BufferLength ([[USHORT]]) - input : Number of bytes to write. 
 +  * BytesWritten ([[PUSHORT]]) - output : Address of the number of bytes written. 
 + 
 +===== Return Code ===== 
 + 
 +rc [[(USHORT]]) - return
  
-==Return Code== 
- rc (USHORT) - return 
 Return code descriptions are: Return code descriptions are:
-* 0        NO_ERROR 
-* 5        ERROR_ACCESS_DENIED 
-* 6        ERROR_INVALID_HANDLE 
-* 26       ERROR_NOT_DOS_DISK 
-* 33       ERROR_LOCK_VIOLATION 
-* 109      ERROR_BROKEN_PIPE 
  
-==Remarks==+  * 0        NO_ERROR 
 +  * 5        ERROR_ACCESS_DENIED 
 +  * 6        ERROR_INVALID_HANDLE 
 +  * 26       ERROR_NOT_DOS_DISK 
 +  * 33       ERROR_LOCK_VIOLATION 
 +  * 109      ERROR_BROKEN_PIPE 
 + 
 +===== Remarks ===== 
 On output, BytesWritten is the number of bytes actually written. If BytesWritten is different from BufferLength, this usually indicates insufficient disk space. On output, BytesWritten is the number of bytes actually written. If BytesWritten is different from BufferLength, this usually indicates insufficient disk space.
  
Line 28: Line 38:
 Buffers that are multiples of the hardware's base physical unit for data written to the file on these base boundaries, are written directly to the device. (The base physical unit is defined as the smallest block that can be physically written to the device.) Other buffer sizes force some I/O to go through an internal system buffer and greatly reduce the efficiency of I/O operation. Buffers that are multiples of the hardware's base physical unit for data written to the file on these base boundaries, are written directly to the device. (The base physical unit is defined as the smallest block that can be physically written to the device.) Other buffer sizes force some I/O to go through an internal system buffer and greatly reduce the efficiency of I/O operation.
  
-The file pointer is moved by read and write operations. It can be moved to a desired position by calling DosChgFilePtr.+The file pointer is moved by read and write operations. It can be moved to a desired position by calling [[DosChgFilePtr]].
  
 If the file is read-only, the write to the file is not performed. If the file is read-only, the write to the file is not performed.
  
-===Family API Considerations===+==== Family API Considerations ==== 
 Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction applies to DosWrite when coding for the DOS mode. Some options operate differently in the DOS mode than in OS/2 mode. Therefore, the following restriction applies to DosWrite when coding for the DOS mode.
  
-* Only single-byte DosWrite requests can be made to the COM device, because the COM device driver for the DOS environment does not support multiple-byte I/O. +  * Only single-byte DosWrite requests can be made to the COM device, because the COM device driver for the DOS environment does not support multiple-byte I/O.  
 + 
 +==== Named Pipe Considerations ====
  
-===Named Pipe Considerations=== 
 DosWrite is also used to write bytes or messages to a named pipe. DosWrite is also used to write bytes or messages to a named pipe.
  
Line 48: Line 60:
 An attempt to write to a pipe whose other end has been closed returns ERROR_BROKEN_PIPE. An attempt to write to a pipe whose other end has been closed returns ERROR_BROKEN_PIPE.
  
-==Example Code== +===== Example Code ===== 
-===C Binding=== + 
-<PRE>+==== C Binding ==== 
 + 
 +<code c>
 #define INCL_DOSFILEMGR #define INCL_DOSFILEMGR
  
Line 61: Line 75:
  
 USHORT           rc;            /* return code */ USHORT           rc;            /* return code */
-</PRE>+</code>
 This example writes to a file.  This example writes to a file. 
-<PRE>+<code c>
 #define INCL_DOSFILEMGR #define INCL_DOSFILEMGR
  
Line 105: Line 119:
                    sizeof(FileData),     /* Buffer length */                    sizeof(FileData),     /* Buffer length */
                    &Wrote);              /* Bytes written */                    &Wrote);              /* Bytes written */
-</PRE>+</code>
  
-===MASM Binding=== +==== MASM Binding ==== 
-<PRE>+ 
 +<code asm>
 EXTRN  DosWrite:FAR EXTRN  DosWrite:FAR
 INCL_DOSFILEMGR     EQU 1 INCL_DOSFILEMGR     EQU 1
Line 117: Line 132:
 PUSH@  WORD    BytesWritten  ;Bytes written (returned) PUSH@  WORD    BytesWritten  ;Bytes written (returned)
 CALL   DosWrite CALL   DosWrite
 +</code>
 Returns WORD Returns WORD
-</PRE> 
- 
  
-====== Note ======+===== Note =====
  
 Text based on [[http://www.edm2.com/index.php/DosWrite_(FAPI)]] Text based on [[http://www.edm2.com/index.php/DosWrite_(FAPI)]]