dosread

Purpose

     Reads from a DOS file.

Library

     DOS Services Library (libdos.a)

Syntax

     #include <dos.h>

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

Description

     The dosread  subroutine reads the number  of bytes speci-
     fied by the n parameter.  The dosfile parameter specifies
     the handle  of the file  from which  the bytes are  to be
     read.  The bytes read from  the file are written into the
     buffer pointed to by the buf parameter.

     Reading  begins from  the current  position in  the file.
     The current  position of the  file is incremented  by the
     number of bytes read.

     When  attempting to  read  from a  region  that has  been
     locked with  the doslock subroutine, the  dosread subrou-
     tine 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  DO_ASCII flag was  set when the file  was opened,
     and if the file is located on a DOS file system, then the
     dosread subroutine  translates the  DOS ASCII data to AIX
     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
     dosread subroutine removes the  ASCII CR characters, thus
     changing the  CR-LF sequence  used by  DOS to  the "'\n'"
     (new-line character) that AIX  uses.  An end-of-file con-
     dition occurs  when Ctrl-Z  is encountered.   The dosread
     subroutine does  not return the Ctrl-Z  character as part
     of the data.

Return Value

     Upon successful completion, the  number of bytes actually
     read (after DOS translation, if  any) is returned.  If an
     end-of-file is  read, a value  of 0 is returned.   If the
     dosread 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,"   "dosseek,"   and
     "doswrite."