Clarify documentation regarding signals and EINTR.

diff --git a/libserialport.h.in b/libserialport.h.in
index 9eb7662461e727b1f65df885596d65fa0f365b44..46e2fda55fc467f2ba770cf56259081b7db76e0d 100644 (file)
--- 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(),