docs/modbus_tcp_listen.md

   1 # modbus_tcp_listen
   2
   3 ## Name
   4
   5 modbus_tcp_listen - create and listen a TCP Modbus socket (IPv4)
   6
   7
   8 ## Synopsis
   9
  10 ```c
  11 int modbus_tcp_listen(modbus_t *ctx, int nb_connection);
  12 ```
  13
  14 ## Description
  15
  16 The *modbus_tcp_listen()* function shall create a socket and listen to maximum
  17 `nb_connection` incoming connections on the specified IP address.  The context
  18 `ctx` must be allocated and initialized with [modbus_new_tcp](modbus_new_tcp) before to
  19 set the IP address to listen, if IP address is set to NULL or '0.0.0.0', any addresses will be
  20 listen.
  21
  22 ## Return value
  23
  24 The function shall return a new socket if successful. Otherwise it shall return
  25 -1 and set errno.
  26
  27 ## Example
  28
  29 For detailed examples, see source files in tests directory:
  30
  31 - unit-test-server.c, simple but handle only one connection
  32 - bandwidth-server-many-up.c, handles several connections at once
  33
  34 ```c
  35 ...
  36
  37 /* To listen any addresses on port 502 */
  38 ctx = modbus_new_tcp(NULL, 502);
  39
  40 /* Handle until 10 established connections */
  41 server_socket = modbus_tcp_listen(ctx, 10);
  42
  43 /* Clear the reference set of socket */
  44 FD_ZERO(&refset);
  45
  46 /* Add the server socket */
  47 FD_SET(server_socket, &refset);
  48
  49 if (select(server_socket + 1, &refset, NULL, NULL, NULL) == -1) {
  50 }
  51
  52 ...
  53
  54 close(server_socket);
  55 modbus_free(ctx);
  56 ```
  57
  58 ## See also
  59
  60 - [modbus_new_tcp](modbus_new_tcp)
  61 - [modbus_tcp_accept](modbus_tcp_accept)
  62 - [modbus_tcp_pi_listen](modbus_tcp_pi_listen)