/**
* Allocate a port configuration structure.
*
- * The user should allocate a variable of type "struct sp_config *" and pass a
- * pointer to this to receive the result. The variable will be updated to
- * point to the new configuration structure. The structure is opaque and must
- * be accessed via the functions provided.
+ * The user should allocate a variable of type "struct sp_port_config *" and
+ * pass a pointer to this to receive the result. The variable will be updated
+ * to point to the new configuration structure. The structure is opaque and
+ * must be accessed via the functions provided.
*
* All parameters in the structure will be initialised to special values which
* are ignored by sp_set_config().
*/
enum sp_return sp_blocking_read(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms);
+/**
+ * Read bytes from the specified serial port, returning as soon as any data is
+ * available.
+ *
+ * @warning If your program runs on Unix, defines its own signal handlers, and
+ * needs to abort blocking reads when these are called, then you
+ * should not use this function. It repeats system calls that return
+ * with EINTR. To be able to abort a read from a signal handler, you
+ * should implement your own blocking read using sp_nonblocking_read()
+ * together with a blocking method that makes sense for your program.
+ * E.g. you can obtain the file descriptor for an open port using
+ * sp_get_port_handle() and use this to call select() or pselect(),
+ * with appropriate arrangements to return if a signal is received.
+ *
+ * @param[in] port Pointer to a port structure. Must not be NULL.
+ * @param[out] buf Buffer in which to store the bytes read. Must not be NULL.
+ * @param[in] count Maximum number of bytes to read. Must not be zero.
+ * @param[in] timeout_ms Timeout in milliseconds, or zero to wait indefinitely.
+ *
+ * @return The number of bytes read on success, or a negative error code. If
+ * the result is zero, the timeout was reached before any bytes were
+ * available. If timeout_ms is zero, the function will always return
+ * either at least one byte, or a negative error code.
+ *
+ * @since 0.1.1
+ */
+enum sp_return sp_blocking_read_next(struct sp_port *port, void *buf, size_t count, unsigned int timeout_ms);
+
/**
* Read bytes from the specified serial port, without blocking.
*
*
* In order to obtain the correct result, this function should be called
* straight after the failure, before executing any other system operations.
+ * The result is thread-specific, and only valid when called immediately
+ * after a previous call returning SP_ERR_FAIL.
*
* @return The system's numeric code for the error that caused the last
* operation to fail.
*
* In order to obtain the correct result, this function should be called
* straight after the failure, before executing other system operations.
+ * The result is thread-specific, and only valid when called immediately
+ * after a previous call returning SP_ERR_FAIL.
*
* @return The system's message for the error that caused the last
* operation to fail. This string may be allocated by the function,