[Contents] [Index] [Help] [Retrace] [browse <] [Browse >]


NAME
    Read -- read input from serial port

FUNCTION
    This command causes a stream of characters to be read in from
    the serial port buffer.  The number of characters is specified
    in io_Length.

    The Query function can be used to check how many characters
    are currently waiting in the serial port buffer.  If more characters
    are requested than are currently available, the ioRequest
    will be queued until it can be satisfied.


    The best way to handle reads is to first Query to get the number
    of characters currently in the buffer.  Then post a read request
    for that number of characters (or the maximum size of your buffer).

    If zero characters are in the buffer, post a request
    for 1 character.  When at least one is ready, the device will return
    it.  Now start over with another Query.

    Before the program exits, it must be sure to abortio() then waitio()
    any outstanding ioRequests.

IO REQUEST
    io_Message      A mn_ReplyPort is required
    io_Device       set by opendevice
    io_Unit         set by opendevice
    io_Command      CMD_READ
    io_Flags        If the IOB_QUICK bit is set, read will try
                     to complete the IO quickly
    io_Length       number of characters to receive.
    io_Data         pointer to buffer

RESULTS
    Error -- if the Read succeded, then io_Error will be null.
             If the Read failed, then io_Error will be non-zero.
             io_Error will indicate problems such as parity mismatch,
             break, and buffer overrun.

SEE ALSO
     serial.device/sdcmd_query
     serial.device/sdcmd_setparams

BUGS
     Having multiple outstanding read IORequests at any one time will
     probably fail.

     Old documentation mentioned a mode where io_Length was set to -1.
     If you want a NULL terminated read, use the io_TermArray instead.