Reads and returns a line of input from the connection <conn> (or, if not provided, from the player that typed the command that initiated the current task). If <non-blocking> is false or not provided, this function suspends the current task, resuming it when there is input available to be read. If <non-blocking> is provided and true, this function never suspends the calling task; if there is no input currently available for input, `read()' simply returns 0 immediately.
If <conn> is provided, then the programmer must either be a wizard or the owner of <conn>, if <conn> is not provided, then `read()' may only be called by a wizard and only in the task that was last spawned by a command from the connection in question. Otherwise, E_PERM is raised. If the given <conn> is not currently connected and has no pending lines of input, or if the connection is closed while a task is waiting for input but before any lines of input are received, then `read()' raises E_INVARG.
The restriction on the use of `read()' without any arguments preserves the following simple invariant: if input is being read from a player, it is for the task started by the last command that the player typed. This invariant adds responsibility to the programmer, however. If your program calls another verb before doing a `read()', then either that verb must not suspend, or else you must arrange that no commands will be read from the connection in the meantime. The most straightforward way to do this is to call
set_connection_option(<conn>, "hold-input", 1)
before any task suspension could happen, then make all of your calls to `read()' and other code that might suspend, and finally call
set_connection_option(<conn>, "hold-input", 0)
to allow commands once again to be read and interpreted normally.