# $EPIC: read.txt,v 1.3 2007/06/05 03:56:39 jnelson Exp $
======Synopsis:======
$__read__(<fd> [<length>])

======Technical:======
This function reads data from an [[open]] file.  The value <fd> must have 
been previously returned by the [[open]] function.  If <length> is given
it will read and return that number of bytes from the file.  If no <length>
is given, it will read and return the next line of text from the file.

If <length> is given, it is considered a binary read, and the return value
will be encoded with the CTCP transform, which guarantees you can send
the string over irc, or assign it to a variable.  You can use [[xform]] to 
convert this data into another format.

The function will return the empty string if <fd> is not a value previously
returned by [[open]] or if the file has reached EOF, or if there was an 
error.  Use [[isfilevalid]], [[eof]] or [[ferror]] to determine between 
these possibilities.

======Returns:======
Data read from file, or nothing on error.  Binary data reads will be 
CTCP encoded.

======Examples:======
<file>
$read(4)                           returns next line from fd 4
$read(4 30)                        returns next 30 bytes from fd 4
</file>