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.
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
Packet
is delivered as a list.
binary
Packet
is delivered as a binary.
{ip,IPAddress}
{port,Port}
{fd,Fd}
gen_tcp
, use this option to pass in the file descriptor for it
and create a Socket for it.
inet6
inet
inet
options
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
.
The default values for options given to
|
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}
{ip,IPAddress}
{fd,Fd}
gen_tcp
, use this option to pass in the file descriptor for it
and create a Socket for it.
inet6
inet
The returned socket can only be used in calls to accept
.
The default values for options given to
|
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.