gen_tcp(3)

MODULE
gen_tcp - Interface to TCP/IP sockets

DESCRIPTION

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

The available options are described in the setopts/2 function in the inet manual page.

The possible {error, Reason} results are described in the inet manual page.

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.

EXPORTS

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

    Types
        ListenSocket = socket()
        Socket = socket()
        Timeout = integer()
        Reason = atom()

    Accepts an incoming connection request on a listen socket. Socket must be a socket returned from listen/1. If no Timeout argument is specified, or it is infinity, the accept function will not return until a connection has been established or the ListenSocket has been closed. If accept returns because the ListenSocket has been closed {error, closed} is returned. If Timeout is specified and no connection is accepted within the given time, accept will return {error, timeout}.

    Packets can be sent to the returned socket using the send/2 function. Packets sent from the peer will be delivered as messages
            {tcp, Socket, Data}

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

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

    Types
        Socket = socket()
        Reason = atom()

    Closes an TCP socket.

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

    Types
        Address = string() | atom() | ip_address()
        Port = Timeout = integer()
        Options = list()
        Socket = socket()
        Reason = atom()

    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, IPAddress}:
            If the host has several network interfaces, this option specifies which one to use.

        {port, Port}:
            Specify which local port number to use.

        {fd, Fd}:
            If a socket has somehow been connected without using gen_tcp, use this option to pass in the file descriptor for it and create a Socket for it.

        inet6:
            Set up the socket for IPv6

        inet:
            Set up the socket for IPv4

        common inet options:
            The common inet options available are described in the setopts/2 function in the inet manual page.

    Packets can be sent to the returned socket using the send/2 function. Packets sent from the peer will be delivered as messages
            {tcp, Socket, Data}

    If the socket was closed the following message is delivered:
            {tcp_closed, Socket}

    If an error occurred on the socket the following message is delivered:
            {tcp_error, Socket, Reason}

    unless the socket is in passive mode, in which case packets are retrieved by calling recv/2.

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

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

    Types
        Socket = socket()
        NewOwner = pid()

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

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

    Types
        Port = integer()
        Options = list()
        Socket = socket()
        Reason = atom()

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

    If the port number is zero, the listen function picks an available port number (use inet:port/1 to retrieve it); otherwise, the specified port number is used.

    The available options are described in the setopts/2 function in the inet manual page.

    Additionally, the following options can be given.

        {backlog, B}:
            B is an integer >= 0. The backlog value defaults to 5. The backlog value defines the maximum length the queue of pending connections may grow to.

        {ip, IPAddress}:
            If the host has several network interfaces, this option specifies which one to listen on.

        {fd, Fd}:
            If a listen socket has somehow been opened without using gen_tcp, use this option to pass in the file descriptor for it and create a Socket for it.

        inet6:
            Set up the socket for IPv6

        inet:
            Set up the socket for IPv4

    The returned socket can only be used in calls to accept.

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

    Types
        Socket = socket()
        Length = integer()
        Packet = list() | binary()
        Timeout = integer()
        Reason = atom()

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

    The Length argument is only meaningful when the socket is in raw mode and denotes number of bytes to read. If Length = 0 all available bytes are returned.

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

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

    Types
        Socket = socket()
        Packet = list() | binary()
        Reason = atom()

    Sends a packet on a socket.

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

    Types
        Socket = socket()
        Reason = atom()
        How = read | write | read_write

    Immediately close a socket in one or two directions.

    Closing a socket in the write allows you to still read from the socket.

    To be able to handle that the peer has done a shutdown on the write side, you'll need to set the exit_on_close option for the socket to false as described in the setopts/2 function in inet manual page.

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