Module socket
Data Types
domain()
domain() = inet
in_addr()
in_addr() = {0..255, 0..255, 0..255, 0..255}
port_number()
port_number() = 0..65535
protocol()
protocol() = tcp | udp
sockaddr()
sockaddr() = sockaddr_in()
sockaddr_in()
sockaddr_in() = #{family => inet, port => port_number(), addr => any | loopback | in_addr()}
socket()
abstract datatype: socket()
socket_option()
socket_option() = {socket, reuseaddr} | {socket, linger}
type()
type() = stream | dgram
Function Index
accept/1 | Equivalent to socket:accept(ListeningSocket, infinity). |
accept/2 | Wait for the socket to accept a connection. |
bind/2 | Bind a socket to an interface. |
close/1 | Close a socket. |
connect/2 | Wait for the socket to connect to an address. |
listen/1 | Set the socket to listen for connections. |
listen/2 | Set the socket to listen for connections. |
open/3 | Create a socket. |
peername/1 | Return the address of the peer connected to the specified socket. |
recv/1 | Equivalent to socket:recv(Socket, 0). |
recv/2 | Equivalent to socket:recv(Socket, Length, infinity). |
recv/3 | Receive data on the specified socket. |
recvfrom/1 | Equivalent to socket:recvfrom(Socket, 0). |
recvfrom/2 | Equivalent to socket:recvfrom(Socket, Length, infinity). |
recvfrom/3 | Receive data on the specified socket, returning the from address. |
send/2 | Send data on the specified socket. |
sendto/3 | Send data on the specified socket to the specified destination. |
setopt/3 | Set a socket option. |
shutdown/2 | Shut down one or both ends of a full-duplex socket connection. |
sockname/1 | Return the current address for the specified socket. |
Function Details
accept/1
accept(Socket::socket()) -> {ok, Connection::socket()} | {error, Reason::term()}
Equivalent to socket:accept(ListeningSocket, infinity)
.
accept/2
accept(Socket::socket(), Timeout::timeout()) -> {ok, Connection::socket()} | {error, Reason::term()}
Socket
: the socketTimeout
: timeout (in milliseconds)
returns: {ok, Connection}
if successful; {error, Reason}
, otherwise.
Wait for the socket to accept a connection.
Wait for the socket to accept a connection. The socket should be set to listen for connections.
Note that this function will block until a connection is made
from a client. Typically, users will spawn a call to accept
in a separate process.
Example:
{ok, ConnectedSocket} = socket:accept(ListeningSocket)
bind/2
bind(Socket::socket(), Address::sockaddr() | any | loopback) -> ok | {error, Reason::term()}
Socket
: the socketAddress
: the address to which to bind the socket
returns: ok
if successful; {error, Reason}
, otherwise.
Bind a socket to an interface.
Bind a socket to an interface, via a socket address. Use any
to
bind to all interfaces. Use loopback
to bind to the loopback
address. To specify a port, use a map containing the network family,
address, and port.
Example:
ok = socket:bind(ListeningSocket, #{family => inet, addr => any, port => 44404})
close/1
close(Socket::socket()) -> ok | {error, Reason::term()}
Socket
: the socket
returns: ok
if successful; {error, Reason}
, otherwise.
Close a socket.
Close a previously opened socket.
Example:
ok = socket:close(Socket)
connect/2
connect(Socket::socket(), Address::sockaddr()) -> ok | {error, Reason::term()}
Socket
: the socketAddress
: the address to which to connect the socket
returns: ok
if successful; {error, Reason}
, otherwise.
Wait for the socket to connect to an address.
Wait for the socket to connect to an address. The socket should be a connection-based socket.
Note that this function will block until a connection is made to a server.
Example:
ok = socket:connect(Socket, #{family => inet, addr => loopback, port => 44404})
listen/1
listen(Socket::socket()) -> ok | {error, Reason::term()}
Socket
: the socket
returns: ok
if successful; {error, Reason}
, otherwise.
Set the socket to listen for connections.
Listen for connections. The socket should be a connection-based socket and should be bound to an address and port.
Example:
ok = socket:listen(ListeningSocket)
listen/2
listen(Socket::socket(), Backlog::integer()) -> ok | {error, Reason::term()}
Socket
: the socketBacklog
: the maximum length for the queue of pending connections
returns: ok
if successful; {error, Reason}
, otherwise.
Set the socket to listen for connections.
Listen for connections. The socket should be a connection-based socket and should be bound to an address and port.
Use the Backlog to specify the maximum length for the queue of pending connections
Example:
ok = socket:listen(ListeningSocket, 4)
open/3
open(Domain::domain(), Type::type(), Protocol::protocol()) -> {ok, socket()} | {error, Reason::term()}
Domain
: the network domainType
: the network typeProtocol
: the network protocol
returns: {ok, Socket}
if successful; {error, Reason}
, otherwise.
Create a socket.
Create a socket with a specified domain, type, and protocol. Use the returned socket for communications.
Example:
{ok, ListeningSocket} = socket:open(inet, stream, tcp)
peername/1
peername(Socket::socket()) -> {ok, Address::sockaddr()} | {error, Reason::term()}
Socket
: the socket
returns: {ok, Address}
if successful; {error, Reason}
, otherwise.
Return the address of the peer connected to the specified socket.
Example:
{ok, Address} = socket:peername(ConnectedSocket)
recv/1
recv(Socket::socket()) -> {ok, Data::binary()} | {error, Reason::term()}
Equivalent to socket:recv(Socket, 0)
.
recv/2
recv(Socket::socket(), Length::non_neg_integer()) -> {ok, Data::binary()} | {error, Reason::term()}
Equivalent to socket:recv(Socket, Length, infinity)
.
recv/3
recv(Socket::socket(), Length::non_neg_integer(), Timeout::timeout()) -> {ok, Data::binary()} | {error, Reason::term()}
Socket
: the socketLength
: number of bytes to receiveTimeout
: timeout (in milliseconds)
returns: {ok, Data}
if successful; {error, Reason}
, otherwise.
Receive data on the specified socket.
This function is equivalent to recvfrom/3
except for the return type.
Example:
{ok, Data} = socket:recv(ConnectedSocket)
recvfrom/1
recvfrom(Socket::socket()) -> {ok, {Address::sockaddr(), Data::binary()}} | {error, Reason::term()}
Equivalent to socket:recvfrom(Socket, 0)
.
recvfrom/2
recvfrom(Socket::socket(), Length::non_neg_integer()) -> {ok, {Address::sockaddr(), Data::binary()}} | {error, Reason::term()}
Equivalent to socket:recvfrom(Socket, Length, infinity)
.
recvfrom/3
recvfrom(Socket::socket(), Length::non_neg_integer(), Timeout::timeout()) -> {ok, {Address::sockaddr(), Data::binary()}} | {error, Reason::term()}
Socket
: the socketLength
: number of bytes to receiveTimeout
: timeout (in milliseconds)
returns: {ok, {Address, Data}}
if successful; {error, Reason}
, otherwise.
Receive data on the specified socket, returning the from address.
Note that this function will block until data is received on the socket.
Example:
{ok, {Address, Data}} = socket:recvfrom(ConnectedSocket)
If socket is UDP, the function retrieves the first available packet and truncate it to Length bytes, unless Length is 0 in which case it returns the whole packet (“all available”).
If socket is TCP and Length is 0, this function retrieves all available data without waiting (using peek if the platform allows it). If socket is TCP and Length is not 0, this function waits until Length bytes are available and return these bytes.
send/2
send(Socket::socket(), Data::iodata()) -> ok | {ok, Rest::binary()} | {error, Reason::term()}
Socket
: the socketData
: the data to send
returns: {ok, Rest}
if successful; {error, Reason}
, otherwise.
Send data on the specified socket.
Note that this function will block until data is sent on the socket. The data may not have been received by the intended recipient, and the data may not even have been sent over the network.
Example:
ok = socket:send(ConnectedSocket, Data)
sendto/3
sendto(Socket::socket(), Data::iodata(), Dest::sockaddr()) -> ok | {ok, Rest::binary()} | {error, Reason::term()}
Socket
: the socketData
: the data to sendDest
: the destination to which to send the data
returns: {ok, Rest}
if successful; {error, Reason}
, otherwise.
Send data on the specified socket to the specified destination.
Note that this function will block until data is sent on the socket. The data may not have been received by the intended recipient, and the data may not even have been sent over the network.
Example:
ok = socket:sendto(ConnectedSocket, Data, Dest)
setopt/3
setopt(Socket::socket(), SocketOption::socket_option(), Value::term()) -> ok | {error, Reason::term()}
Socket
: the socketSocketOption
: the optionValue
: the option value
returns: {ok, Address}
if successful; {error, Reason}
, otherwise.
Set a socket option.
Set an option on a socket.
Currently, the following options are supported:
{socket, reuseaddr} | boolean() |
{socket, linger} | #{onoff => boolean(), linger => non_neg_integer()} |
Example:
ok = socket:setopt(ListeningSocket, {socket, reuseaddr}, true)
ok = socket:setopt(ListeningSocket, {socket, linger}, #{onoff => true, linger => 0})
shutdown/2
shutdown(Socket::socket(), How::read | write | read_write) -> ok | {error, Reason::term()}
Socket
: the socketHow
: how to shut the socket down
returns: ok
if successful; {error, Reason}
, otherwise.
Shut down one or both ends of a full-duplex socket connection.
Example:
ok = socket:shutdown(Socket, read_write)
sockname/1
sockname(Socket::socket()) -> {ok, Address::sockaddr()} | {error, Reason::term()}
Socket
: the socket
returns: {ok, Address}
if successful; {error, Reason}
, otherwise.
Return the current address for the specified socket.
Example:
{ok, Address} = socket:sockname(ConnectedSocket)