This module provides an API for network socket. Functions are provided to create, delete and manipulate the sockets as well as sending and receiving data on them.
The intent is that it shall be as "close as possible" to the OS
level socket interface. The only significant addition is that some of
the functions,
e.g.
Some functions allow for an asynchronous call.
This is achieved by setting the
The caller can now make new call to the recv function and expect data.
Note that all other users are locked out until the 'current user' has called the function (recv in this case).
Instead of
Another message the user must be prepared for (when making asynchronous
calls) is the
This message indicates
that the (asynchronous) operation has been aborted.
If, for instance, the socket has been closed (by another process),
There is currently no support for Windows.
Support for IPv6 has been implemented but not tested.
SCTP has only been partly implemented (and not tested).
A lowercase
The calls
A lowercase
An
See
The call
As returned by
A tag that describes the (select) operation,
contained in the returned
A
Returned by an operation that requires the caller to wait
for a
The smallest allowed
The
A terminating zero character will be appended before the address path is given to the OS, and the terminating zero will be stripped before giving the address path to the caller.
Linux's non-portable abstract socket address extension is handled by not doing any terminating zero processing in either direction, if the first byte of the address is zero.
Flags corresponding to the message flag constants
on the platform. The flags are lowercase and
the constants are uppercase with the prefix
Some flags are only used for sending,
some only for receiving,
some in received control messages,
and some for several of these.
Not all flags are supported on all platforms.
See the platform's documentation,
The OS protocol levels for, for example, socket options and control messages, with the following names in the OS header files:
There are many other possible protocols, but the ones above are those for which this socket library implements socket options and/or control messages.
All protocols known to the OS are enumerated
when the Erlang VM is started.
See the OS man page for protocols(5).
The protocol level 'socket' is always implemented
as
The calls
These are socket options for the
Options not described here are intentionally undocumented and for Erlang/OTP internal use only.
Socket option on the form
The OS name for an options is, except where otherwise noted,
the
See the OS documentation for every socket option.
An option below that has the value type
An option with value type
The calls
Options for protocol level
Only valid to get.
The socket's protocol domain. Does not work on for instance FreeBSD.
The value
Currently disabled due to a possible infinite loop when calling
Only valid to get.
The socket's protocol. Does not work on for instance Darwin.
This option is unsupported per default;
OTP has to be explicitly built with the
Since our implementation uses nonblocking sockets, it is unknown if and how this option works, or even if it may cause malfunction. Therefore, we do not recommend setting this option.
Instead, use the
This option is unsupported per default;
OTP has to be explicitly built with the
Since our implementation uses nonblocking sockets, it is unknown if and how this option works, or even if it may cause malfunction. Therefore, we do not recommend setting this option.
Instead, use the
Only valid to get.
The socket's type.
Options for protocol level
Only valid to set.
Only valid to set.
Only valid to set.
Only valid to set.
Only valid to set.
Only valid to set.
The value
Only valid to get.
An
Warning!
When this option is enabled, error messages may
arrive on the socket's error queue, which should be read
using the message flag
A working strategy should be to first poll
the error queue using
An
Only valid to set.
Options for protocol level
As far as we know the only valid value is
Only valid to set.
Only valid to set.
An
Warning!
See the socket option
Options for protocol level
Only valid to set.
Options for protocol level
Options for protocol level
Corresponds to the C
Corresponds to the C
Corresponds to the C
Corresponds to the C
Corresponds to the C
Lowercase
Lowercase
Corresponds to the C
The value
Lowercase
Corresponds to the C
Corresponds to the C
Not all fields are implemented on all platforms; unimplemented fields are ignored, but implemented fields are mandatory. Note that the '_event' suffixes have been stripped from the C struct field names, for convenience.
Corresponds to the C
Corresponds to the C
Message sent by
Corresponds to a C
The
Message returned by
Corresponds to a C
Control messages (ancillary messages) accepted by
A control message may for some message types have a
Control messages (ancillary messages) returned by
A control message has got a
The POSIX error codes originates from the OS level socket interface.
Accept a connection on a socket.
This call is used with connection oriented socket types
(
The same as
The same as
When there is no pending connection to return,
the function will return
If the time-out argument is
If the time-out argument is
Bind a name to a socket.
When a socket is created
(with
The rules used for name binding vary between domains.
If you bind a socket to an address in for example
the 'inet' or 'inet6' address families,
with an ephemeral port number (0),
and want to know which port that was chosen,
you can find out using something like:
Cancel an asynchronous request.
Call this function in order to cancel a previous
asynchronous call to, e.g.
Closes the socket.
Note that for e.g.
One way to handle this is to use the
This function connects the socket to the address
specified by the
If a connection attempt is already in progress
(by another process),
The same as
Note that when this call has returned
Repeating a connection attempt towards the same address would be ok, but towards a different address could end up with a connection to either address.
The safe play would be to close the socket and start over.
Also note that all this applies to cancelling a connect call with a no-wait time-out described below.
The same as
If it is not possible to immediately establish a
connection, the function will return
If the time-out argument is
If the time-out argument is
This function finalizes a connection setup on a socket,
after calling
Instead of calling this function, for backwards compatibility,
it is allowed to call
Gets a socket option from the protocol level
See the type
Gets a socket option from one of the OS's protocol levels.
See the type
What options are valid depends on what kind of socket it is
(
See the
Not all options are valid, nor possible to get, on all platforms. That is, even if "we" support an option; it does not mean that the underlying OS does.
Backwards compatibility function.
The same as
Gets a socket option that may be unknown to our implementation, or that has a type not compatible with our implementation, that is; in "native mode".
The socket option may be specified with an ordinary
How to decode the option value has to be specified
either with
If
What options are valid depends on what kind of socket it is
(
The integer values for
Get miscellaneous info about the socket library.
The function returns a map with each info item as a key-value binding.
In order to ensure data integrity, mutex'es are taken when needed. So, do not call this function often.
Get miscellaneous info about the socket.
The function returns a map with each info item as a key-value binding. It reflects the "current" state of the socket.
In order to ensure data integrity, mutex'es are taken when needed. So, do not call this function often.
This function retreives information about what the platform supports, such as if SCTP is supported, or if a socket options are supported.
For keys other than the known
This functions returns a
Listen for connections on a socket.
Returns the number of active sockets.
Create an endpoint (socket) for communication based on an
already existing file descriptor.
The function attempts to retrieve domain, type and protocol from
the system. This is however not possible on all platforms, and
in those cases it expects it in
The
Which protocol domain is the descriptor of.
See also
Which protocol type type is the descriptor of.
See also
Which protocol is the descriptor of.
The atom
See also
Shall the provided descriptor be duplicated (dup) or not.
Defaults to
Enable or disable debug during the open call.
Defaults to
Enable or disable use of the socket registry for this socket.
This overrides the global value.
Defaults to the global value, see
This function should be used with care!
On some platforms its necessary to provide the
Creates an endpoint (socket) for communication.
For some
The
Used to set the network namespace during the open call. Only supported on the Linux platform.
Enable or disable debug during the open call.
Defaults to
Enable or disable use of the socket registry for this socket.
This overrides the global value.
Defaults to the global value, see
It may not be possible to specify the default protocol (except
when
Returns the address of the peer connected to the socket.
Receives data from a socket, waiting for it to arrive.
The argument
For a socket of
The message
When there is a socket error this function returns
Receives data from a socket, waiting at most
The same as
Receives data from a socket, but returns a select continuation if the data could not be returned immediately.
The same as
If the time-out argument is
If the time-out argument is
Note that for a socket of type
Receive a message from a socket, waiting for it to arrive.
The function returns when a message is received,
or when there is a socket error.
Argument
If
If it is impossible to know the appropriate buffer size,
it may be possible to use the receive
The message
Receives a message from a socket, waiting at most
The same as
Receives a message from a socket, but returns a select continuation if no message could be returned immediately.
The same as
If the time-out argument is
If the time-out argument is
Receive a message from a socket, waiting for it to arrive.
The function returns when a message is received,
or when there is a socket error.
Arguments
If
If it is impossible to know the appropriate buffer size,
it may be possible to use the receive
The message
Receives a message from a socket, waiting at most
The same as
Receives a message from a socket, but returns a select continuation if no message could be returned immediately.
The same as
If the time-out argument is
If the time-out argument is
Sends data on a connected socket, waiting for it to be sent.
This call will not return until the
The message
The
The return value indicates the result from the platform's network layer:
All data has been accepted.
Not all data has been accepted,
but no error has been reported.
This can not happen for a socket of
For a socket of
It is nevertheless possible for the platform's network layer to return this.
An error has been reported and no data has been accepted.
The
An error has been reported
but before that some data was accepted.
This can only happen for a socket of
Sends data on a connected socket, waiting at most
The same as
Sends data on a connected socket, but return a select continuation if the data could not be sent immediately.
The same as
If
If
If some of the data was sent, the function will return
Continues sending data on a connected socket, where the
send operation was initiated by
If
The return value indicates the result from
the platform's network layer.
See
Sends a message on a socket, waiting for it to be sent.
The destination, if needed,
that is: if the socket is not connected,
is provided in
For a connected socket no address field should be
present in
The message data is given to to the platform's network layer
in the form of an I/O vector without copying the content.
If the number of elements in the I/O vector is larger than
allowed on the platform
(reported in the
This call will not return until the data has been handed over to the platform's network layer, or when it reports an error.
The message
The return value indicates the result from
the platform's network layer.
See
Sends a message on a socket, waiting at most
The same as
Sends a message on a socket, but return a select continuation if the data could not be sent immediately.
The same as
If
If
If some of the data was sent, the function will return
Continues sending a message data on a socket, where the
send operation was initiated by
The return value indicates the result from
the platform's network layer.
See
Sends data on a socket, to the specified destination, waiting for it to be sent.
This call will not return until the data has been accepted by the platform's network layer, or it reports an error.
If this call is used on a connection mode socket or on a connected socket, the platforms's network layer may return an error or ignore the destination address.
The message
The return value indicates the result from
the platform's network layer.
See
Sends data on a socket, waiting at most
The same as
Sends data on a socket, but return a select continuation if the data could not be sent immediately.
The same as
If
If
If some of the data was sent, the function will return
Continues sending data on a socket, where the
send operation was initiated by
If
The return value indicates the result from
the platform's network layer.
See
Sets a socket option in the protocol level
See the type
Set a socket option in one of the OS's protocol levels.
See the type
What options are valid depends on what kind of socket it is
(
See the
Not all options are valid, nor possible to set, on all platforms. That is, even if "we" support an option; it does not mean that the underlying OS does.
Backwards compatibility function.
The same as
Sets a socket option that may be unknown to our implementation, or that has a type not compatible with our implementation, that is; in "native mode".
If
The socket option may be specified with an ordinary
What options are valid depends on what kind of socket it is
(
The integer values for
Shut down all or part of a full-duplex connection.
Returns the current address to which the socket is bound.
These functions function retreives information about what the platform supports, such which platform features or which socket options, are supported.
For keys other than the known the empty list is returned, Note that in a future version or on a different platform there might be more supported items.
Returns a list of
Returns a list of
Returns a list of
Returns a list of
For a
Globally change if the socket registry is to be used or not.
Note that its still possible to override this explicitly when
creating an individual sockets,
see
Returns a list of all sockets, according to the filter rule.
There are several pre-made filter rule(s) and one general:
Selection based on the domain of the socket.
Only a subset is valid.
Selection based on the type of the socket.
Only a subset is valid.
Selection based on the protocol of the socket.
Only a subset is valid.
Selection base on which sockets has this pid as Controlling Process.
The general filter rule.
A fun that takes the socket info and returns a
client(SAddr, SPort) ->
{ok, Sock} = socket:open(inet, stream, tcp),
ok = socket:connect(Sock, #{family => inet,
addr => SAddr,
port => SPort}),
Msg = <<"hello">>,
ok = socket:send(Sock, Msg),
ok = socket:shutdown(Sock, write),
{ok, Msg} = socket:recv(Sock),
ok = socket:close(Sock).
server(Addr, Port) ->
{ok, LSock} = socket:open(inet, stream, tcp),
ok = socket:bind(LSock, #{family => inet,
port => Port,
addr => Addr}),
ok = socket:listen(LSock),
{ok, Sock} = socket:accept(LSock),
{ok, Msg} = socket:recv(Sock),
ok = socket:send(Sock, Msg),
ok = socket:close(Sock),
ok = socket:close(LSock).