From: Martin Ling <redacted>
Date: Wed, 27 Nov 2013 14:12:12 +0000 (+0000)
Subject: Clarify documentation regarding signals and EINTR.
X-Git-Tag: libserialport-0.1.0~32
X-Git-Url: https://sigrok.org/gitaction?a=commitdiff_plain;h=b87deb7c70b739ffac312112950c4481f6f4666d;p=libserialport.git

Clarify documentation regarding signals and EINTR.
---

diff --git a/libserialport.h.in b/libserialport.h.in
index 9eb7662..46e2fda 100644
--- a/libserialport.h.in
+++ b/libserialport.h.in
@@ -758,11 +758,11 @@ enum sp_return sp_set_flowcontrol(struct sp_port *port, enum sp_flowcontrol flow
 /**
  * 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()
+ * @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(),
@@ -803,11 +803,11 @@ 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()
+ * @warning If your program runs on Unix, defines its own signal handlers, and
+ *          needs to abort blocking writes 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 write from a signal handler, you
+ *          should implement your own blocking write using sp_nonblocking_write()
  *          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(),