Rename [gs]et_timeout_[begin|end] to [gs]et_[response|byte]_timeout

The following functions have been renamed:
- modbus_get_timeout_begin -> modbus_get_response_timeout
- modbus_set_timeout_begin -> modbus_set_response_timeout
- modbus_get_timeout_end -> modbus_get_byte_timeout
- modbus_set_timeout_end -> modbus_set_byte_timeout

The meaning of these timeout intervals is now clearer. The documentation
has been updated.

doc/Makefile.am

@@ -5,8 +5,8 @@ MAN3 = \
         modbus_free.3 \
         modbus_get_header_length.3 \
         modbus_get_socket.3 \
-        modbus_get_timeout_begin.3 \
-        modbus_get_timeout_end.3 \
+        modbus_get_response_timeout.3 \
+        modbus_get_byte_timeout.3 \
         modbus_new_rtu.3 \
         modbus_new_tcp_pi.3 \
         modbus_new_tcp.3 \
@@ -21,8 +21,8 @@ MAN3 = \
         modbus_set_error_recovery.3 \
         modbus_set_slave.3 \
         modbus_set_socket.3 \
-        modbus_set_timeout_begin.3 \
-        modbus_set_timeout_end.3 \
+        modbus_set_response_timeout.3 \
+        modbus_set_byte_timeout.3 \
         modbus_strerror.3 \
         modbus_write_bits.3 \
         modbus_write_bit.3 \

doc/modbus_get_byte_timeout.txt

@@ -0,0 +1,47 @@
+modbus_get_byte_timeout(3)
+==========================
+
+
+NAME
+----
+modbus_get_byte_timeout - get timeout between bytes
+
+
+SYNOPSIS
+--------
+*void modbus_get_byte_timeout(*modbus_t 'ctx', struct timeval *'timeout');*
+
+
+DESCRIPTION
+-----------
+The _modbus_get_byte_timeout()_ function shall store the timeout interval
+between two consecutive bytes of the same message in the 'timeout' argument.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+struct timeval byte_timeout;
+
+/* Save original timeout */
+modbus_get_byte_timeout(ctx, &byte_timeout);
+-------------------
+
+
+SEE ALSO
+--------
+linkmb:modbus_get_response_timeout[3]
+linkmb:modbus_set_response_timeout[3]
+linkmb:modbus_set_byte_timeout[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_get_response_timeout.txt

@@ -0,0 +1,53 @@
+modbus_get_response_timeout(3)
+==============================
+
+
+NAME
+----
+modbus_get_response_timeout - get timeout for response
+
+
+SYNOPSIS
+--------
+*void modbus_get_response_timeout(*modbus_t 'ctx', struct timeval *'timeout');*
+
+
+DESCRIPTION
+-----------
+The _modbus_get_response_timeout()_ function shall store the timeout interval
+used to wait for a response in the 'timeout' argument.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+struct timeval old_response_timeout;
+struct timeval response_timeout;
+
+/* Save original timeout */
+modbus_get_response_timeout(ctx, &old_response_timeout);
+
+/* Define a new and too short timeout! */
+response_timeout.tv_sec = 0;
+response_timeout.tv_usec = 0;
+modbus_set_response_timeout(ctx, &response_timeout);
+-------------------
+
+
+SEE ALSO
+--------
+linkmb:modbus_set_response_timeout[3]
+linkmb:modbus_get_byte_timeout[3]
+linkmb:modbus_set_byte_timeout[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_get_timeout_begin.txt

@@ -1,53 +0,0 @@
-modbus_get_timeout_begin(3)
-===========================
-
-
-NAME
-----
-modbus_get_timeout_begin - get timeout of begin of message
-
-
-SYNOPSIS
---------
-*void modbus_get_timeout_begin(*modbus_t 'ctx', struct timeval *'timeout');*
-
-
-DESCRIPTION
------------
-The _modbus_get_timeout_begin()_ function shall store the current timeout of
-begin of message in the 'timeout' argument.
-
-
-RETURN VALUE
-------------
-There is no return values.
-
-
-EXAMPLE
--------
-[source,c]
--------------------
-struct timeval timeout_begin_old;
-struct timeval timeout_begin_new;
-
-/* Save original timeout */
-modbus_get_timeout_begin(ctx, &timeout_begin_old);
-
-/* Define a new and too short timeout! */
-timeout_begin_new.tv_sec = 0;
-timeout_begin_new.tv_usec = 0;
-modbus_set_timeout_begin(ctx, &timeout_begin_new);
--------------------
-
-
-SEE ALSO
---------
-linkmb:modbus_set_timeout_begin[3]
-linkmb:modbus_get_timeout_end[3]
-linkmb:modbus_set_timeout_end[3]
-
-
-AUTHORS
--------
-The libmodbus documentation was written by Stéphane Raimbault
-<stephane.raimbault@gmail.com>

doc/modbus_get_timeout_end.txt

@@ -1,47 +0,0 @@
-modbus_get_timeout_end(3)
-===========================
-
-
-NAME
-----
-modbus_get_timeout_end - get timeout of end of message
-
-
-SYNOPSIS
---------
-*void modbus_get_timeout_end(*modbus_t 'ctx', struct timeval *'timeout');*
-
-
-DESCRIPTION
------------
-The _modbus_get_timeout_end()_ function shall store the current timeout between
-the begin and the end of message in the 'timeout' argument.
-
-
-RETURN VALUE
-------------
-There is no return values.
-
-
-EXAMPLE
--------
-[source,c]
--------------------
-struct timeval timeout_end;
-
-/* Save original timeout */
-modbus_get_timeout_end(ctx, &timeout_end);
--------------------
-
-
-SEE ALSO
---------
-linkmb:modbus_get_timeout_begin[3]
-linkmb:modbus_set_timeout_begin[3]
-linkmb:modbus_set_timeout_end[3]
-
-
-AUTHORS
--------
-The libmodbus documentation was written by Stéphane Raimbault
-<stephane.raimbault@gmail.com>

doc/modbus_set_byte_timeout.txt

@@ -0,0 +1,37 @@
+modbus_set_byte_timeout(3)
+==========================
+
+
+NAME
+----
+modbus_set_byte_timeout - set timeout between bytes
+
+
+SYNOPSIS
+--------
+*void modbus_set_byte_timeout(*modbus_t 'ctx', struct timeval *'timeout');*
+
+
+DESCRIPTION
+-----------
+The _modbus_set_byte_timeout()_ function shall set the timeout interval between
+two consecutive bytes of the same message. If the delay between is longer than
+the given timeout, an error will be raised.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+SEE ALSO
+--------
+linkmb:modbus_get_byte_timeout[3]
+linkmb:modbus_get_response_timeout[3]
+linkmb:modbus_set_response_timeout[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_set_response_timeout.txt

@@ -0,0 +1,54 @@
+modbus_set_response_timeout(3)
+==============================
+
+
+NAME
+----
+modbus_set_response_timeout - set timeout for response
+
+
+SYNOPSIS
+--------
+*void modbus_set_response_timeout(*modbus_t 'ctx', struct timeval *'timeout');*
+
+
+DESCRIPTION
+-----------
+The _modbus_set_response_timeout()_ function shall set the timeout interval used
+to wait for a response. If the waiting before receiving the response is longer than
+the given timeout, an error will be raised.
+
+
+RETURN VALUE
+------------
+There is no return values.
+
+
+EXAMPLE
+-------
+[source,c]
+-------------------
+struct timeval old_response_timeout;
+struct timeval response_timeout;
+
+/* Save original timeout */
+modbus_get_response_timeout(ctx, &old_response_timeout);
+
+/* Define a new and too short timeout! */
+response_timeout.tv_sec = 0;
+response_timeout.tv_usec = 0;
+modbus_set_response_timeout(ctx, &response_timeout);
+-------------------
+
+
+SEE ALSO
+--------
+linkmb:modbus_get_response_timeout[3]
+linkmb:modbus_get_byte_timeout[3]
+linkmb:modbus_set_byte_timeout[3]
+
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>

doc/modbus_set_timeout_begin.txt

@@ -1,54 +0,0 @@
-modbus_set_timeout_begin(3)
-===========================
-
-
-NAME
-----
-modbus_set_timeout_begin - set timeout of begin of message
-
-
-SYNOPSIS
---------
-*void modbus_set_timeout_begin(*modbus_t 'ctx', struct timeval *'timeout');*
-
-
-DESCRIPTION
------------
-The _modbus_set_timeout_begin()_ function shall set the timeout of begin of
-message. If the waiting before receiving a message is longer than the given
-timeout, an error will be raised.
-
-
-RETURN VALUE
-------------
-There is no return values.
-
-
-EXAMPLE
--------
-[source,c]
--------------------
-struct timeval timeout_begin_old;
-struct timeval timeout_begin_new;
-
-/* Save original timeout */
-modbus_get_timeout_begin(ctx, &timeout_begin_old);
-
-/* Define a new and too short timeout! */
-timeout_begin_new.tv_sec = 0;
-timeout_begin_new.tv_usec = 0;
-modbus_set_timeout_begin(ctx, &timeout_begin_new);
--------------------
-
-
-SEE ALSO
---------
-linkmb:modbus_get_timeout_begin[3]
-linkmb:modbus_get_timeout_end[3]
-linkmb:modbus_set_timeout_end[3]
-
-
-AUTHORS
--------
-The libmodbus documentation was written by Stéphane Raimbault
-<stephane.raimbault@gmail.com>

doc/modbus_set_timeout_end.txt

@@ -1,37 +0,0 @@
-modbus_set_timeout_end(3)
-===========================
-
-
-NAME
-----
-modbus_set_timeout_end - set timeout of end of message
-
-
-SYNOPSIS
---------
-*void modbus_set_timeout_end(*modbus_t 'ctx', struct timeval *'timeout');*
-
-
-DESCRIPTION
------------
-The _modbus_set_timeout_end()_ function shall set the timeout of end of
-message. If the delay between the begin and the end of message is longer than
-the given timeout, an error will be raised.
-
-
-RETURN VALUE
-------------
-There is no return values.
-
-
-SEE ALSO
---------
-linkmb:modbus_get_timeout_begin[3]
-linkmb:modbus_set_timeout_begin[3]
-linkmb:modbus_get_timeout_end[3]
-
-
-AUTHORS
--------
-The libmodbus documentation was written by Stéphane Raimbault
-<stephane.raimbault@gmail.com>

src/modbus-private.h

@@ -45,9 +45,9 @@ MODBUS_BEGIN_DECLS
 
 #define _MODBUS_EXCEPTION_RSP_LENGTH  5
 
-/* Time out between messages in microsecond */
-#define _TIME_OUT_BEGIN_OF_MESSAGE    500000
-#define _TIME_OUT_END_OF_MESSAGE      500000
+/* Timeouts in microsecond (0.5 s) */
+#define _RESPONSE_TIMEOUT    500000
+#define _BYTE_TIMEOUT        500000
 
 /* Function codes */
 #define _FC_READ_COILS                0x01
@@ -104,8 +104,8 @@ struct _modbus {
     int s;
     int debug;
     int error_recovery;
-    struct timeval timeout_begin;
-    struct timeval timeout_end;
+    struct timeval response_timeout;
+    struct timeval byte_timeout;
     const modbus_backend_t *backend;
     void *backend_data;
 };

src/modbus.c

@@ -331,8 +331,8 @@ static int receive_msg(modbus_t *ctx, uint8_t *msg, msg_type_t msg_type)
         tv.tv_sec = 60;
         tv.tv_usec = 0;
     } else {
-        tv.tv_sec = ctx->timeout_begin.tv_sec;
-        tv.tv_usec = ctx->timeout_begin.tv_usec;
+        tv.tv_sec = ctx->response_timeout.tv_sec;
+        tv.tv_usec = ctx->response_timeout.tv_usec;
     }
 
     while (length_to_read != 0) {
@@ -398,10 +398,11 @@ static int receive_msg(modbus_t *ctx, uint8_t *msg, msg_type_t msg_type)
         }
 
         if (length_to_read > 0) {
-            /* If no character at the buffer wait
-               TIME_OUT_END_OF_MESSAGE before raising an error. */
-            tv.tv_sec = ctx->timeout_end.tv_sec;
-            tv.tv_usec = ctx->timeout_end.tv_usec;
+            /* If there is no character in the buffer, the allowed timeout
+               interval between two consecutive bytes is defined by
+               byte_timeout */
+            tv.tv_sec = ctx->byte_timeout.tv_sec;
+            tv.tv_usec = ctx->byte_timeout.tv_usec;
         }
     }
 
@@ -1311,11 +1312,11 @@ void _modbus_init_common(modbus_t *ctx)
     ctx->debug = FALSE;
     ctx->error_recovery = FALSE;
 
-    ctx->timeout_begin.tv_sec = 0;
-    ctx->timeout_begin.tv_usec = _TIME_OUT_BEGIN_OF_MESSAGE;
+    ctx->response_timeout.tv_sec = 0;
+    ctx->response_timeout.tv_usec = _RESPONSE_TIMEOUT;
 
-    ctx->timeout_end.tv_sec = 0;
-    ctx->timeout_end.tv_usec = _TIME_OUT_END_OF_MESSAGE;
+    ctx->byte_timeout.tv_sec = 0;
+    ctx->byte_timeout.tv_usec = _BYTE_TIMEOUT;
 }
 
 /* Define the slave number */
@@ -1346,28 +1347,26 @@ int modbus_get_socket(modbus_t *ctx)
     return ctx->s;
 }
 
-/* Get the timeout of begin of message */
-void modbus_get_timeout_begin(modbus_t *ctx, struct timeval *timeout)
+/* Get the timeout interval used to wait for a response */
+void modbus_get_response_timeout(modbus_t *ctx, struct timeval *timeout)
 {
-    *timeout = ctx->timeout_begin;
+    *timeout = ctx->response_timeout;
 }
 
-/* Set timeout when waiting the beginning of a message */
-void modbus_set_timeout_begin(modbus_t *ctx, const struct timeval *timeout)
+void modbus_set_response_timeout(modbus_t *ctx, const struct timeval *timeout)
 {
-    ctx->timeout_begin = *timeout;
+    ctx->response_timeout = *timeout;
 }
 
-/* Get the timeout of end of message */
-void modbus_get_timeout_end(modbus_t *ctx, struct timeval *timeout)
+/* Get the timeout interval between two consecutive bytes of a message */
+void modbus_get_byte_timeout(modbus_t *ctx, struct timeval *timeout)
 {
-    *timeout = ctx->timeout_end;
+    *timeout = ctx->byte_timeout;
 }
 
-/* Set timeout when waiting the end of a message */
-void modbus_set_timeout_end(modbus_t *ctx, const struct timeval *timeout)
+void modbus_set_byte_timeout(modbus_t *ctx, const struct timeval *timeout)
 {
-    ctx->timeout_end = *timeout;
+    ctx->byte_timeout = *timeout;
 }
 
 int modbus_get_header_length(modbus_t *ctx)

src/modbus.h

@@ -139,11 +139,11 @@ int modbus_set_error_recovery(modbus_t *ctx, int enabled);
 void modbus_set_socket(modbus_t *ctx, int socket);
 int modbus_get_socket(modbus_t *ctx);
 
-void modbus_get_timeout_begin(modbus_t *ctx, struct timeval *timeout);
-void modbus_set_timeout_begin(modbus_t *ctx, const struct timeval *timeout);
+void modbus_get_response_timeout(modbus_t *ctx, struct timeval *timeout);
+void modbus_set_response_timeout(modbus_t *ctx, const struct timeval *timeout);
 
-void modbus_get_timeout_end(modbus_t *ctx, struct timeval *timeout);
-void modbus_set_timeout_end(modbus_t *ctx, const struct timeval *timeout);
+void modbus_get_byte_timeout(modbus_t *ctx, struct timeval *timeout);
+void modbus_set_byte_timeout(modbus_t *ctx, const struct timeval *timeout);
 
 int modbus_get_header_length(modbus_t *ctx);
 

tests/unit-test-client.c

@@ -42,8 +42,8 @@ int main(int argc, char *argv[])
     int nb_points;
     int rc;
     float real;
-    struct timeval timeout_begin_old;
-    struct timeval timeout_begin_new;
+    struct timeval old_response_timeout;
+    struct timeval response_timeout;
     int use_backend;
 
     if (argc > 1) {
@@ -549,12 +549,12 @@ int main(int argc, char *argv[])
     }
 
     /* Save original timeout */
-    modbus_get_timeout_begin(ctx, &timeout_begin_old);
+    modbus_get_response_timeout(ctx, &old_response_timeout);
 
     /* Define a new and too short timeout */
-    timeout_begin_new.tv_sec = 0;
-    timeout_begin_new.tv_usec = 0;
-    modbus_set_timeout_begin(ctx, &timeout_begin_new);
+    response_timeout.tv_sec = 0;
+    response_timeout.tv_usec = 0;
+    modbus_set_response_timeout(ctx, &response_timeout);
 
     rc = modbus_read_registers(ctx, UT_REGISTERS_ADDRESS,
                                UT_REGISTERS_NB, tab_rp_registers);
@@ -567,7 +567,7 @@ int main(int argc, char *argv[])
     }
 
     /* Restore original timeout */
-    modbus_set_timeout_begin(ctx, &timeout_begin_old);
+    modbus_set_response_timeout(ctx, &old_response_timeout);
 
     /* Wait for data before flushing */
     usleep(250000);