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_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 socket
Timeout: 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 socket
Address: 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 socket
Address: 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 socket
Backlog: 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 domain
Type: the network type
Protocol: 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 socket
Length: number of bytes to receive
Timeout: 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 socket
Length: number of bytes to receive
Timeout: 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 socket
Data: 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 socket
Data: the data to send
Dest: 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 socket
Value: 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 socket
How: 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)