<!DOCTYPE File PUBLIC "-//Liam Quin//DTD C API Documentation v1.1//EN" "doc.dtd"><File>
<Entry dir="liblqutil">
<Function File="../../src/liblqutil/eread.c">
<Name>LQU_Eread</Name>
<Class>Utilities/Files
<Purpose>
This routine provides an error-checking wrapper around the
read(2) system call.  If the underlying read() returns -1,
a diagnostic message is printed using by calling Error at the
given Severity (bitwise or'd with E_SYS if appropriate).
The message includes What, which should be a
short, succinct summary of the purpose of the file, and Name,
which is normally given as the name of the file, but could be
any string.
<Returns>
the number of bytes read on success, or -1 on an error.
If E_FATAL was given, LQU_Eread does not return after an error.
<Example>
nBytesRead = LQU_Eread(E_FATAL, "passwd", "list of users", 0, p, 12);
</Example>
<Notes>
<P>There are several error flags, such as E_BUG, that include E_FATAL.
See &lt;error.h&gt; for the current list.</P>
<P>The example does not need to check to see whether nBytesRead is
less than 0, since in that case the program would exit.  LQU_Eread can,
however, return a number other than ByteCount, just as the underlying
system call read(2) can, and in the same circumstances.  The caller
of LQU_Eread should therefore check that the expected number of bytes
were returned.</P>
</Notes>
</Function>
<Decl>
API int
LQU_Eread(Severity, Name, What, fd, Buffer, ByteCount)
    int Severity;
    CONST char *Name;
    CONST char *What;
    int fd;
    char *Buffer;
    int ByteCount;
</Decl>
</Entry>
