# gen_tcp

### MODULE

gen_tcp

### MODULE SUMMARY

Interface to TCP/IP sockets

### DESCRIPTION

The `gen_tcp` module provides functions for communicating with sockets using the TCP/IP protocol.

The following code fragment provides a simple example of a client connecting to a server at port 5678, transferring a binary and closing the connection:

    client() ->
        SomeHostInNet = "localhost" % to make it runnable on one machine
        {ok, Sock} = gen_tcp:connect(SomeHostInNet, 5678,
                                     [binary, {packet, 0}]),
        ok = gen_tcp:send(Sock, "Some Data"),
        ok = gen_tcp:close(Sock).

At the other end a server is listening on port 5678, accepts the connection and receives the binary:

    server() ->
        {ok, LSock} = gen_tcp:listen(5678, [binary, {packet, 0},
                                            {active, false}]),
        {ok, Sock} = gen_tcp:accept(LSock),
        {ok, Bin} = do_recv(Sock, []),
        ok = gen_tcp:close(Sock),
        Bin.

    do_recv(Sock, Bs) ->
        case gen_tcp:recv(Sock, 0) of
            {ok, B} ->
                do_recv(Sock, [Bs, B]);
            {error, closed} ->
                {ok, list_to_binary(Bs)}
        end.

### DATA TYPES

    ip_address()
      see inet(3)

    posix()
      see inet(3)

    socket()
      as returned by accept/1,2 and connect/3,4

### EXPORTS

`connect(Address, Port, Options) -> {ok, Socket} | {error, Reason}`
`connect(Address, Port, Options, Timeout) -> {ok, Socket} | {error, Reason}`

Types:

`Address = string() | atom() | ip_address()`
`Port = 0..65535`
`Options = [Opt]`
`Opt -- see below`
`Timeout = int() | infinity`
`Socket = socket()`
`Reason = posix()`

Connects to a server on TCP port `Port` on the host with IP address `Address`. The `Address` argument can be either a hostname, or an IP address.

The available options are:

`list`
  Received `Packet` is delivered as a list.
`binary`
  Received `Packet` is delivered as a binary.
`{ip, ip_address()}`
  If the host has several network interfaces, this option specifies which one to use.
`{port, Port}`
  Specify which local port number to use.
`{fd, int()}`
  If a socket has somehow been connected without using `gen_tcp`, use this option to pass the file descriptor for it.
`inet6`
  Set up the socket for IPv6.
`inet`
  Set up the socket for IPv4.
Opt
  See inet:setopts/2.

Packets can be sent to the returned socket `Socket` using `send/2`. Packets sent from the peer are delivered as messages:

    {tcp, Socket, Data}

If the socket is closed, the following message is delivered:

    {tcp_closed, Socket}

If an error occurs on the socket, the following message is delivered:

    {tcp_error, Socket, Reason}

unless `{active, false}` is specified in the option list for the socket, in which case packets are retrieved by calling `recv/2`.

The optional `Timeout` parameter specifies a timeout in milliseconds. The default value is `infinity`.

| The default values for options given to `connect` can be affected by the Kernel configuration parameter `inet_default_connect_options`. See inet(3) for details.

`listen(Port, Options) -> {ok, ListenSocket} | {error, Reason}`

Types:

`Port = 0..65535`
`Options = [Opt]`
`Opt -- see below`
`ListenSocket -- see below`
`Reason = posix()`

Sets up a socket to listen on the port `Port` on the local host.

If `Port == 0`, the underlying OS assigns an available port number, use `inet:port/1` to retrieve it.

The available options are:

`list`
  Received `Packet` is delivered as a list.
`binary`
  Received `Packet` is delivered as a binary.
`{backlog, B}`
  `B` is an integer >= 0. The backlog value defaults to 5. The backlog value defines the maximum length that the queue of pending connections may grow to.
`{ip, ip_address()}`
  If the host has several network interfaces, this option specifies which one to listen on.
`{fd, Fd}`
  If a socket has somehow been connected without using `gen_tcp`, use this option to pass the file descriptor for it.
`inet6`
  Set up the socket for IPv6.
`inet`
  Set up the socket for IPv4.
`Opt`
  See inet:setopts/2.

The returned socket `ListenSocket` can only be used in calls to `accept/1,2`.

| The default values for options given to `listen` can be affected by the Kernel configuration parameter `inet_default_listen_options`. See inet(3) for details.

`accept(ListenSocket) -> {ok, Socket} | {error, Reason}`
`accept(ListenSocket, Timeout) -> {ok, Socket} | {error, Reason}`

Types:

`ListenSocket -- see listen/2`
`Timeout = int() | infinity`
`Socket = socket()`
`Reason = closed | timeout | posix()`

Accepts an incoming connection request on a listen socket. `Socket` must be a socket returned from `listen/2`. `Timeout` specifies a timeout value in ms, defaults to `infinity`.

Returns `{ok, Socket}` if a connection is established, or `{error, closed}` if `ListenSocket` is closed, or `{error, timeout}` if no connection is established within the specified time. May also return a POSIX error value if something else goes wrong, see inet(3) for possible error values.

Packets can be sent to the returned socket `Socket` using `send/2`. Packets sent from the peer are delivered as messages:

    {tcp, Socket, Data}

unless `{active, false}` was specified in the option list for the listen socket, in which case packets are retrieved by calling `recv/2`.

`send(Socket, Packet) -> ok | {error, Reason}`

Types:

`Socket = socket()`
`Packet = [char()] | binary()`
`Reason = posix()`

Sends a packet on a socket.

`recv(Socket, Length) -> {ok, Packet} | {error, Reason}`
`recv(Socket, Length, Timeout) -> {ok, Packet} | {error, Reason}`

Types:

`Socket = socket()`
`Length = int()`
`Packet = [char()] | binary()`
`Timeout = int() | infinity`
`Reason = closed | posix()`

This function receives a packet from a socket in passive mode. A closed socket is indicated by a return value `{error, closed}`.

The `Length` argument is only meaningful when the socket is in `raw` mode and denotes the number of bytes to read. If `Length` = 0, all available bytes are returned. If `Length` > 0, exactly `Length` bytes are returned, or an error; possibly discarding less than `Length` bytes of data when the socket gets closed from the other side.

The optional `Timeout` parameter specifies a timeout in milliseconds. The default value is `infinity`.

`controlling_process(Socket, Pid) -> ok | {error, eperm}`

Types:

`Socket = socket()`
`Pid = pid()`

Assigns a new controlling process `Pid` to `Socket`. The controlling process is the process which receives messages from the socket. If called by any other process than the current controlling process, `{error, eperm}` is returned.

`close(Socket) -> ok | {error, Reason}`

Types:

`Socket = socket()`
`Reason = posix()`

Closes a TCP socket.

`shutdown(Socket, How) -> ok | {error, Reason}`

Types:

`Socket = socket()`
`How = read | write | read_write`
`Reason = posix()`

Immediately close a socket in one or two directions.

`How == write` means closing the socket for writing, reading from it is still possible.

To be able to handle that the peer has done a shutdown on the write side, the `{exit_on_close, false}` option is useful.

### AUTHORS

tony@erix.ericsson.se - support@erlang.ericsson.se

kernel 2.11
Copyright © 1991-2006 Ericsson AB