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.
ip_address()
see inet(3)
posix()
see inet(3)
socket()
as returned by accept/1,2 and connect/3,4
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
Packet is delivered as a list.binary
Packet is delivered as a binary.{ip, ip_address()}
{port, Port}
{fd, int()}
gen_tcp, use this option to pass the file
descriptor for it.inet6
inet
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 |
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
Packet is delivered as a list.binary
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()}
{fd, Fd}
gen_tcp, use this option to pass the file
descriptor for it.inet6
inet
Opt
The returned socket ListenSocket can only be used in
calls to accept/1,2.
![]() |
The default values for options given to |
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.