Add documentation for tcp[_pi]_accept (closes #31)

Stéphane Raimbault
1 parent 900aa475
Showing 4 changed files with 115 additions and 3 deletions
doc/Makefile.am
doc/modbus_tcp_accept.txt
doc/modbus_tcp_pi_accept.txt
src/modbus-tcp.c
@@ -45,6 +45,8 @@ MAN3 = \
         modbus_set_slave.3 \
         modbus_set_socket.3 \
         modbus_strerror.3 \
+        modbus_tcp_accept.3 \
+        modbus_tcp_pi_accept.3 \
         modbus_tcp_listen.3 \
         modbus_tcp_pi_listen.3 \
         modbus_write_and_read_registers.3 \
+modbus_tcp_accept(3)
+====================
+
+
+NAME
+----
+modbus_tcp_accept - accept a new connection on a TCP Modbus socket (IPv4)
+
+
+SYNOPSIS
+--------
+*int modbus_tcp_accept(modbus_t *'ctx', int *'s);*
+
+
+DESCRIPTION
+-----------
+The _modbus_tcp_accept()_ function shall extract the first connection on the
+queue of pending connections, create a new socket and store it in libmodbus
+context given in argument. If available, _accept4()_ with *SOCK_CLOEXEC* will be
+called instead of _accept()_.
+
+
+RETURN VALUE
+------------
+The _modbus_tcp_accept()_ function shall return a new socket if successful.
+Otherwise it shall return -1 and set errno.
+
+
+EXAMPLE
+-------
+For detailed example, see unit-test-server.c source file in tests directory.
+
+[source,c]
+-------------------
+...
+
+ctx = modbus_new_tcp("127.0.0.1", 502);
+s = modbus_tcp_listen(ctx, 1);
+modbus_tcp_accept(ctx, &s);
+
+...
+
+close(s)
+modbus_free(ctx);
+-------------------
+
+SEE ALSO
+--------
+linkmb:modbus_tcp_pi_accept[3]
+linkmb:modbus_tcp_listen[3]
+linkmb:modbus_tcp_pi_listen[3]
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
+modbus_tcp_pi_accept(3)
+=======================
+
+
+NAME
+----
+modbus_tcp_pi_accept - accept a new connection on a TCP PI Modbus socket (IPv6)
+
+
+SYNOPSIS
+--------
+*int modbus_tcp_pi_accept(modbus_t *'ctx', int *'s);*
+
+
+DESCRIPTION
+-----------
+
+The _modbus_tcp_pi_accept()_ function shall extract the first connection on the
+queue of pending connections, create a new socket and store it in libmodbus
+context given in argument. If available, _accept4()_ with *SOCK_CLOEXEC* will be
+called instead of _accept()_.
+
+
+RETURN VALUE
+------------
+The _modbus_tcp_pi_accept()_ function shall return a new socket if successful.
+Otherwise it shall return -1 and set errno.
+
+
+EXAMPLE
+-------
+For detailed example, see unit-test-server.c source file in tests directory.
+
+[source,c]
+-------------------
+...
+
+ctx = modbus_new_tcp_pi("::0", 502);
+s = modbus_tcp_pi_listen(ctx, 1);
+modbus_tcp_pi_accept(ctx, &s);
+
+...
+
+close(s)
+modbus_free(ctx);
+-------------------
+
+SEE ALSO
+--------
+linkmb:modbus_tcp_pi_accept[3]
+linkmb:modbus_tcp_listen[3]
+linkmb:modbus_tcp_pi_listen[3]
+
+AUTHORS
+-------
+The libmodbus documentation was written by Stéphane Raimbault
+<stephane.raimbault@gmail.com>
@@ -621,9 +621,6 @@ int modbus_tcp_pi_listen(modbus_t *ctx, int nb_connection)
     return new_s;
 }
  
-/* On success, the function return a non-negative integer that is a descriptor
-for the accepted socket. On error, socket is set to -1, -1 is returned and errno
-is set appropriately. */
 int modbus_tcp_accept(modbus_t *ctx, int *s)
 {
     struct sockaddr_in addr;