From: Martin Ling <redacted>
Date: Wed, 27 Nov 2013 13:18:29 +0000 (+0000)
Subject: Document EINTR handling.
X-Git-Tag: libserialport-0.1.0~34
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=2007ce5e143185d297a9fbf907c286da44f89e7c;p=libserialport.git

Document EINTR handling.
---

diff --git a/libserialport.h.in b/libserialport.h.in
index 3d38a0d..e1f670d 100644
--- 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.