Add documentation for modbus_tcp_listen

doc/Makefile.am

@@ -39,6 +39,7 @@ MAN3 = \
         modbus_set_slave.3 \
         modbus_set_socket.3 \
         modbus_strerror.3 \
+        modbus_tcp_listen.3 \
         modbus_write_and_read_registers.3 \
         modbus_write_bits.3 \
         modbus_write_bit.3 \

doc/modbus_tcp_listen.txt

@@ -0,0 +1,70 @@
+modbus_tcp_listen(3)
+====================
+
+
+NAME
+----
+modbus_tcp_listen - create and listen a TCP Modbus socket
+
+
+SYNOPSIS
+--------
+*int modbus_tcp_listen(modbus_t *'ctx', int 'nb_connection');*
+
+
+DESCRIPTION
+-----------
+The _modbus_tcp_listen()_ function shall create a socket and listen for
+'nb_connection' incoming connections.
+
+
+RETURN VALUE
+------------
+The _modbus_tcp_listen()_ function shall return a new socket if
+successful. Otherwise it shall return -1 and set errno.
+
+
+EXAMPLE
+-------
+For a detailed example, see source file bandwith-server-many-up.c provided in
+tests directory.
+
+[source,c]
+-------------------
+...
+
+ctx = modbus_new_tcp("127.0.0.1", 502);
+if (modbus_connect(ctx) == -1) {
+    fprintf(stderr, "Connection failed: %s\n", modbus_strerror(errno));
+    modbus_free(ctx);
+    return -1;
+}
+
+/* Handle until 10 established connections */
+server_socket = modbus_tcp_listen(ctx, 10);
+
+/* Clear the reference set of socket */
+FD_ZERO(&refset);
+
+/* Add the server socket */
+FD_SET(server_socket, &refset);
+
+if (select(server_socket + 1, &refset, NULL, NULL, NULL) == -1) {
+}
+
+...
+
+close(server_socket);
+modbus_free(ctx);
+-------------------
+
+SEE ALSO
+--------
+linkmb:modbus_tcp_accept[3]
+linkmb:modbus_tcp_pi_accept[3]
+linkmb:modbus_tcp_pi_listen[3]
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>