<refentry id="read">
<refnamediv>
<refname>Read</refname>
<refname>Readln</refname>
<refpurpose>read from a file</refpurpose>
</refnamediv>

<refsynopsisdiv>
<funcsynopsis>
<funcprototype>
  <funcdef><function>read</function></funcdef>
  <paramdef>int <parameter>pn</parameter></paramdef>
  <paramdef>char *<parameter>buffer</parameter></paramdef>
  <paramdef>int <parameter>count</parameter></paramdef>
</funcprototype>
<funcprototype>
  <funcdef><function>readln</function></funcdef>
  <paramdef>int <parameter>pn</parameter></paramdef>
  <paramdef>char *<parameter>buffer</parameter></paramdef>
  <paramdef>int <parameter>count</parameter></paramdef>
</funcprototype>
</funcsynopsis>

</refsynopsisdiv>

<refsect1><title>Assembler Equivalent</title>
<para>
os9 I$READ
</para>
<para>
os9 I$READLN
</para>
</refsect1>

<refsect1><title>Description</title>
<para>
The path number, "pn" is an integer which is one of the
standard path numbers 0, 1, or 2, or the path number should
have been returned by a successful call to "open", "creat", or
"dup". "Buffer" is a pointer to space with at least "count"
bytes of memory into which read will put the data from the
file.
</para>
<para>
It is guaranteed that at most "count" bytes will be read, but
often less will be, either because, for <function>readln</function>, the file
represents a terminal and input stops at the end of a line, or
for both, end-of-file has been reached.
</para>
<para>
Readln causes "line-editing" such as echoin to take place and
returns once the first "\n" is encountered in the input or the
number of bytes requested has been read. Readln is the
preferred call for reading from the user's terminal.
</para>
<para>
Read does not cause any such editing. See the OS-9 manual for
a fuller description of the actions of these calls.
</para>
</refsect1>

<refsect1><title>Diagnostics</title>
<para>
Read and readln return the number of bytes actually read (0 at
end-of-file) or -1 for physical i/o errors, a bad path number,
or a ridicolous "count".
</para>
<para>
NOTE that end-of-file is not considered an error, and no error
indication is returned. Zero is returned on EOF.
</para>
</refsect1>

<refsect1><title>See Also</title>
<para>
<link linkend="open">open()</link>,
<link linkend="creat">creat()</link>,
<link linkend="dup">dup()</link>
</para>
</refsect1>

</refentry>