Document EINTR handling.

diff --git a/libserialport.h.in b/libserialport.h.in
index 3d38a0dc3302b98a456cb1da007c684cd3ffe7a1..e1f670d046ae9f9939368ef56f2e83864a3b6563 100644 (file)
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -756,7 +756,17 @@ enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flow
 */
 
 /**
- * Read bytes from the specified serial port, blocking until available.
+ * Read bytes from the specified serial port, blocking until complete.
+ *
+ * @warning If your program runs on Unix and makes use of signal handlers,
+ *          note that this function will repeat blocking system calls that
+ *          are interrupted by a signal and return with EINTR. If your program
+ *          needs to abort blocking reads when a signal is handled, you will
+ *          need to implement your own loop 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 port Pointer to port structure.
  * @param buf Buffer in which to store the bytes read.
@@ -793,6 +803,16 @@ enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count
  * been transmitted, use the sp_output_waiting() function. To wait until all
  * written bytes have actually been transmitted, use the sp_drain() function.
  *
+ * @warning If your program runs on Unix and makes use of signal handlers,
+ *          note that this function will repeat blocking system calls that
+ *          are interrupted by a signal and return with EINTR. If your program
+ *          needs to abort blocking reads when a signal is handled, you will
+ *          need to implement your own loop 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 port Pointer to port structure.
  * @param buf Buffer containing the bytes to write.
  * @param count Requested number of bytes to write.