Fix building for Android.

[libserialport.git] / libserialport.h.in

diff --git a/libserialport.h.in b/libserialport.h.in
index e1f670d046ae9f9939368ef56f2e83864a3b6563..41948c1828eee3bab22fdc1e60187233489e88c8 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(),
@@ -818,10 +818,10 @@ enum sp_return sp_nonblocking_read(struct sp_port *port, void *buf, size_t count
  * @param count Requested number of bytes to write.
  * @param timeout Timeout in milliseconds, or zero to wait indefinitely.
  *
- * @return The number of bytes read on success, or a negative error code. If
- *         the number of bytes returned is less than that requested, the
+ * @return The number of bytes written on success, or a negative error code.
+ *         If the number of bytes returned is less than that requested, the
  *         timeout was reached before the requested number of bytes was
- *         sent. If timeout is zero, the function will always return
+ *         written. If timeout is zero, the function will always return
  *         either the requested number of bytes or a negative error code. In
  *         the event of an error there is no way to determine how many bytes
  *         were sent before the error occured.
@@ -878,6 +878,13 @@ enum sp_return sp_flush(struct sp_port *port, enum sp_buffer buffers);
 /**
  * Wait for buffered data to be transmitted.
  *
+ * @warning If your program runs on Unix, defines its own signal handlers, and
+ *          needs to abort draining the output buffer when 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 drain from a
+ *          signal handler, you would need to implement your own blocking
+ *          drain by polling the result of sp_output_waiting().
+ *
  * @param port Pointer to port structure.
  *
  * @return SP_OK upon success, a negative error code otherwise.