[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.