From 9dcfed8189c473bd6308c30fdb783a2124490925 Mon Sep 17 00:00:00 2001
From: Stéphane Raimbault <stephane.raimbault@gmail.com>
Date: Tue, 16 Aug 2011 08:25:40 +0200
Subject: [PATCH] Add documentation for modbus_tcp_listen

---
 doc/Makefile.am           |  1 +
 doc/modbus_tcp_listen.txt | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 71 insertions(+), 0 deletions(-)
 create mode 100644 doc/modbus_tcp_listen.txt

diff --git a/doc/Makefile.am b/doc/Makefile.am
index 594cc30..aa1c9fa 100644
--- a/doc/Makefile.am
+++ b/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 \
diff --git a/doc/modbus_tcp_listen.txt b/doc/modbus_tcp_listen.txt
new file mode 100644
index 0000000..f15f593
--- /dev/null
+++ b/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>
--
libgit2 0.21.4