[Ericsson AB]

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.

Note!

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.

Note!

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.1
Copyright © 1991-2006 Ericsson AB