doswrite

Purpose

     Writes to a DOS file.

Library

     DOS Services Library (libdos.a)

Syntax

     #include <dos.h>

     int doswrite (dosfile, buf, n)
     DOSFILE dosfile;
     char *buf;
     int n;

Description

     The doswrite subroutine writes the number of bytes speci-
     fied by the n parameter to the file whose handle is spec-
     ified by  the dosfile  parameter.  The bytes  are written
     from the buffer pointed to by the buf parameter.

     Writing  begins from  the current  position in  the file.
     The  current position  is  incremented by  the number  of
     bytes written.  When attempting to write to a region that
     has been locked with the doslock subroutine, the doswrite
     subroutine retries  three times at one  second intervals.
     If the region is still locked,  an error occurs and -1 is
     returned.  The  proper method for  using locks is  not to
     rely on being  denied I/O access, but to  attempt to lock
     the desired region and then examine the return code.

     If the file was opened  with the DO_APPEND flag set, then
     the file pointer  is set to the end of  the file prior to
     each write.

     If the  DO_ASCII flag was  set when the file  was opened,
     and if the file is located on a DOS file system, then the
     doswrite subroutine  translates the AIX ASCII data to DOS
     ASCII format.  If DO_ASCII was  not set when the file was
     opened, or if the file is  located on an AIX file system,
     then this translation does not take place.

     When  DOS  ASCII  translation  is  being  performed,  the
     doswrite subroutine inserts an  ASCII CR character before
     each LF  character, thus  changing each AIX  "'\n'" (new-
     line character)  to the CR-LF  sequence that DOS  uses to
     indicate a  new line.  A  Ctrl-Z character is  written as
     the last character when the file is closed.

     If a write requests that more translated bytes be written
     than there  is room for  in the  file, then only  as many
     bytes as there is room for are written.  The next request
     to write more than zero bytes returns an error.

Return Value

     Upon successful completion, a  number equal to the number
     of bytes written before  translation is returned.  If the
     doswrite subroutine fails, a value  of -1 is returned and
     doserrno is set to indicate the error.

Related Information

     In  this  book:   "DOS  services  library,"  "dosclose,"
     "doscreate,"   "doslock,"   "dosopen,"   "dosread,"  and
     "dosseek."