-spec accept(ListenSocket :: term()) -> _.

Equivalent to accept(ListenSocket, infinity).

-spec accept(ListenSocket, Timeout :: infinity) -> {ok, Socket} | {error, Reason}
          when
              ListenSocket :: socket(),
              Socket :: socket(),
              Reason ::
                  posix() |
                  closed |
                  invalid() |
                  {create_accept_socket, posix()} |
                  {add_socket, posix()} |
                  {update_accept_context, posix()};
      (ListenSocket, Timeout :: non_neg_integer()) -> {ok, Socket} | {error, Reason}
          when
              ListenSocket :: socket(),
              Socket :: socket(),
              Reason ::
                  posix() |
                  closed |
                  invalid() |
                  timeout |
                  {create_accept_socket, posix()} |
                  {add_socket, posix()} |
                  {update_accept_context, posix()};
      (ListenSocket, nowait | (Handle :: select_handle() | completion_handle())) ->
          {ok, Socket} | {select, SelectInfo} | {completion, CompletionInfo} | {error, Reason}
          when
              ListenSocket :: socket(),
              Socket :: socket(),
              SelectInfo :: select_info(),
              CompletionInfo :: completion_info(),
              Reason ::
                  posix() |
                  closed |
                  invalid() |
                  {create_accept_socket, posix()} |
                  {add_accept_socket, posix()} |
                  {update_accept_context, posix()}.

Accept a connection on a listening socket.

ListenSocket has to be of a connection oriented type (types stream or seqpacket, see open/1), and set to listen (see listen/1).

If the Timeout argument is infinity; accepts the first pending incoming connection for the listen socket or wait for one to arrive, and return the new connection socket.

If the Timeout argument is a time-out value (non_neg_integer/0); returns {error, timeout} if no connection has arrived after Timeout milliseconds.

If the Handle argument nowait (since OTP 22.1), starts an asynchronous call if the operation couldn't be completed immediately.

If the Handle argument is a select_handle/0, (since OTP 24.0), or on Windows, the equivalent completion_handle/0 (since OTP 26.0), starts an asynchronous call like for nowait.

See the note Asynchronous Calls at the start of this module reference manual page.

-spec bind(Socket, Addr) -> ok | {error, Reason}
        when
            Socket :: socket(),
            Addr :: sockaddr() | any | broadcast | loopback,
            Reason :: posix() | closed | invalid().

Bind a name to a socket.

When a socket is created (with open), it has no address assigned to it. bind assigns the address specified by the Addr argument.

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: {ok, #{port := Port}} =socket:sockname(Socket)

-spec cancel(Socket, SelectInfo | CompletionInfo) -> ok | {error, Reason}
          when
              Socket :: socket(),
              SelectInfo :: select_info(),
              CompletionInfo :: completion_info(),
              Reason :: closed | invalid().

Cancel an asynchronous call in progress.

Call this function to cancel an asynchronous call in progress, that is; it returned a value containing a completion_info/0 or select_info/0.

See the note Asynchronous Calls at the start of this module reference manual page.

If another process tries an operation of the same basic type (accept/1 | send/2 | recv/2) it will be enqueued and notified through a select or completion message when the current operation and all enqueued before it has been completed. If the current operation is canceled by this function it is treated as a completed operation; the process first in queue is notified.

If SelectInfo | CompletionInfo does not match an operation in progress for the calling process, this function returns {error, {invalid, SelectInfo | CompletionInfo}}.

-spec cancel_monitor(MRef :: reference()) -> boolean().

Cancel a socket monitor.

If MRef is a reference that the calling process obtained by calling monitor/1, this monitor is removed. If there is no such monitor for the calling process (or MRef doesn't correspond to a monitor), nothing happens.

The returned value is one of the following:

• true - The monitor was found and removed. In this case, no 'DOWN' message corresponding to this monitor has been delivered and will not be delivered.

• false - The monitor was not found so it couldn't be removed. This might be because the monitor has already triggered and there is a 'DOWN' message from this monitor in the caller message queue.

-spec close(Socket) -> ok | {error, Reason}
         when Socket :: socket(), Reason :: posix() | closed | timeout.

Close a socket.

Note

Note that for Protocol = tcp (see open/3), although TCP guarantees that when the other side sees the stream close all data that we sent before closing has been delivered, there is no way for us to know that the other side got all data and the stream close. All kinds of network and OS issues may obliterate that.

To get such a guarantee we need to implement an in-band acknowledge protocol on the connection, or we can use the shutdown function to signal that no more data will be sent and then wait for the other end to close the socket. Then we will see our read side getting a socket close. In this way we implement a small acknowledge protocol using shutdown/2. The other side cannot know that we ever saw the socket close, but in a client/server scenario that is often not relevant.

-spec connect(Socket :: socket()) -> ok | {error, Reason} when Reason :: posix() | closed | invalid().

Finalize a connect/3 operation.

See the note Asynchronous Calls at the start of this module reference manual page.

On select systems this function finalizes a connection setup on a socket, after receiving a select message {'$socket', Socket, select,SelectHandle}, and returns whether the connection setup was successful or not.

Instead of calling this function, for backwards compatibility, it is allowed to call connect/2,3 again, but that incurs more overhead since the connect address and time-out argument are processed in vain.

The call that completes the connect operation, the second call, cannot return a select return value.

-spec connect(Socket :: term(), SockAddr :: term()) -> _.

Equivalent to connect(Socket, SockAddr, infinity).

-spec connect(Socket, SockAddr, Timeout :: infinity) -> ok | {error, Reason}
           when
               Socket :: socket(),
               SockAddr :: sockaddr(),
               Reason ::
                   posix() |
                   closed |
                   invalid() |
                   already | not_bound |
                   {add_socket, posix()} |
                   {update_connect_context, posix()};
       (Socket, SockAddr, Timeout :: non_neg_integer()) -> ok | {error, Reason}
           when
               Socket :: socket(),
               SockAddr :: sockaddr(),
               Reason ::
                   posix() |
                   closed |
                   invalid() |
                   already | not_bound | timeout |
                   {add_socket, posix()} |
                   {update_connect_context, posix()};
       (Socket, SockAddr, nowait | Handle) ->
           ok | {select, SelectInfo} | {completion, CompletionInfo} | {error, Reason}
           when
               Socket :: socket(),
               SockAddr :: sockaddr(),
               Handle :: select_handle() | completion_handle(),
               SelectInfo :: select_info(),
               CompletionInfo :: completion_info(),
               Reason ::
                   posix() |
                   closed |
                   invalid() |
                   already | not_bound |
                   {add_socket, posix()} |
                   {update_connect_context, posix()}.

Connect the socket to the given address.

This function connects the socket to the address specified by the SockAddr argument.

If a connection attempt is already in progress (by another process), {error, already} is returned.

Note

On Windows the socket has to be bound.

If the time-out argument (argument 3) is infinity it is up to the OS implementation to decide when the connection attempt failed and then what to return; probably {error, etimedout}. The OS time-out may be very long.

If the time-out argument (argument 3) is a time-out value (non_neg_integer/0); return {error, timeout} if the connection hasn't been established within Timeout milliseconds.

Note

Note that when this call has returned {error, timeout} the connection state of the socket is uncertain since the platform's network stack may complete the connection at any time, up to some platform specific time-out.

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 is to close the socket and start over.

Also note that this applies to canceling a nowait connect call described below.

If the time-out argument (argument 2) is nowait (since OTP 22.1), start an asynchronous call if the operation couldn't be completed immediately.

If the time-out argument (argument 2) is a Handle :: select_handle/0, (since OTP 24.0), or on Windows, the equivalent Handle :: completion_handle/0 (since OTP 26.0), start an asynchronous call like for nowait.

See the note Asynchronous Calls at the start of this module reference manual page.

After receiving a select message call connect/1 to complete the operation.

If canceling the operation with cancel/2 see the note above about connection time-out.

-spec getopt(socket(), SocketOption :: {Level :: otp, Opt :: otp_socket_option()}) ->
          {ok, Value :: term()} | {error, invalid() | closed};
      (socket(), SocketOption :: socket_option()) ->
          {ok, Value :: term()} | {error, posix() | invalid() | closed}.

Get the value of a socket option.

Gets the value of an OS protocol level socket option, or from the otp pseudo protocol level, which is this module's implementation level above the OS protocol levels.

See the type otp_socket_option() for a description of the otp protocol level.

See the type socket_option/0 for which OS protocol level options that this implementation knows about, how they are related to OS option names, and if there are known peculiarities with any of them.

What options that are valid depends on the OS, and on the kind of socket (domain/0,type/0 and protocol/0). See the type t:socket_option() and the socket options chapter in the User's Guide for more info.

Note

Not all options are valid, nor possible to get, on all platforms. That is, even if this socket implementation support an option; it doesn't mean that the underlying OS does.

-spec getopt(Socket :: term(), Level :: term(), Opt :: term()) -> _.

Get a socket option (backwards compatibility function).

Equivalent to getopt(Socket, {Level, Opt}), or as a special case if Opt = {NativeOpt ::integer/0, ValueSpec} equivalent to getopt_native(Socket, {Level, NativeOpt}, ValueSpec).

Use getopt/2 or getopt_native/3 instead to handle the option level and name as a single term, and to make the difference between known options and native options clear.

-spec getopt_native(socket(),
              SocketOption ::
                  socket_option() |
                  {Level :: level() | (NativeLevel :: integer()), NativeOpt :: integer()},
              ValueType :: integer) ->
                 {ok, Value :: integer()} | {error, posix() | invalid() | closed};
             (socket(),
              SocketOption ::
                  socket_option() |
                  {Level :: level() | (NativeLevel :: integer()), NativeOpt :: integer()},
              ValueType :: boolean) ->
                 {ok, Value :: boolean()} | {error, posix() | invalid() | closed};
             (socket(),
              SocketOption ::
                  socket_option() |
                  {Level :: level() | (NativeLevel :: integer()), NativeOpt :: integer()},
              ValueSize :: non_neg_integer()) ->
                 {ok, Value :: binary()} | {error, posix() | invalid() | closed};
             (socket(),
              SocketOption ::
                  socket_option() |
                  {Level :: level() | (NativeLevel :: integer()), NativeOpt :: integer()},
              ValueSpec :: binary()) ->
                 {ok, Value :: binary()} | {error, posix() | invalid() | closed}.

Get a "native" socket option.

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 socket_option() tuple, with a known Level = level() and an integer NativeOpt, or with both an integer NativeLevel and NativeOpt.

How to decode the option value has to be specified either with ValueType, by specifying the ValueSize for a binary/0 that will contain the fetched option value, or by specifying a binary/0 ValueSpec that will be copied to a buffer for the getsockopt() call to write the value in which will be returned as a new binary/0.

If ValueType is integer a C type (int) will be fetched, if it is boolean a C type (int) will be fetched and converted into a boolean/0 according to the C implementation's notion about true and false.

If an option is valid depends both on the platform and on what kind of socket it is (domain/0, type/0 and protocol/0).

The integer values for NativeLevel and NativeOpt as well as the Value encoding has to be deduced from the header files for the running system.

-spec i() -> ok.

Print information to the erlang shell in table format for all sockets.

The information printed for each socket is specified by the default set of info_keys/0 (all keys).

The sockets that are printed are all sockets created by this socket module's implementation.

-spec i(InfoKeys :: info_keys()) -> ok;
 (Domain :: inet | inet6 | local) -> ok;
 (Proto :: sctp | tcp | udp) -> ok;
 (Type :: dgram | seqpacket | stream) -> ok.

Print information to the erlang shell in table format for all sockets.

If the argument is a list of info_keys/0, print the specified information for all sockets. See i/0.

Otherwise the same as i/2 with the same first argument and the default information (see i/0).

-spec i(Domain :: inet | inet6 | local, InfoKeys) -> ok when InfoKeys :: info_keys();
 (Proto :: sctp | tcp | udp, InfoKeys) -> ok when InfoKeys :: info_keys();
 (Type :: dgram | seqpacket | stream, InfoKeys) -> ok when InfoKeys :: info_keys().

Print information to the erlang shell in table format for a selection of sockets.

The argument InfoKeys specifies which information is printed for each socket.

If the first argument is Domain print information for all sockets of that specific domain/0.

If the first argument is Proto print information for all sockets of that specific protocol/0.

If the first argument is Type print information for all sockets of that specific type/0.

-spec info() -> info().

Get miscellaneous information about this socket library.

The function returns a map with each information item as a key-value pair.

Note

In order to ensure data integrity, mutexes are taken when needed. So, don't call this function often.

-spec info(Socket) -> socket_info() when Socket :: socket().

Get miscellaneous info about a socket.

The function returns a map with each information item as a key-value pair reflecting the "current" state of the socket.

Note

In order to ensure data integrity, mutexes are taken when needed. So, don't call this function often.

-spec ioctl(Socket, GetRequest :: gifconf) ->
         {ok, IFConf :: [#{name := string, addr := sockaddr()}]} | {error, Reason}
         when Socket :: socket(), Reason :: posix() | closed;
     (Socket, GetRequest :: nread | nwrite | nspace) ->
         {ok, NumBytes :: non_neg_integer()} | {error, Reason}
         when Socket :: socket(), Reason :: posix() | closed;
     (Socket, GetRequest :: atmark) -> {ok, Available :: boolean()} | {error, Reason}
         when Socket :: socket(), Reason :: posix() | closed;
     (Socket, GetRequest :: tcp_info) -> {ok, Info :: map()} | {error, Reason}
         when Socket :: socket(), Reason :: posix() | closed.

Set socket (device) parameters.

This function retrieves a specific parameter, according to the GetRequest argument.

• gifconf - Get a list of interface (transport layer) addresses.

  Result; a list of map/0s, one for each interface, with its name and address.

• nread - Get the number of bytes immediately available for reading (since OTP 26.1).

  Result; the number of bytes, integer/0.

• nwrite - Get the number of bytes in the send queue (since OTP 26.1).

  Result; the number of bytes, integer/0.

• nspace - Get the free space in the send queue (since OTP 26.1).

  Result; the number of bytes, integer/0.

• atmark - Test if there is OOB (out-of-bound) data waiting to be read (since OTP 26.1).

  Result; a boolean/0.

• tcp_info - Get miscellaneous TCP related information for a connected socket (since OTP 26.1).

  Result; a map/0 with information items as key-value pairs.

Note

To see if a ioctl request is supported on the current platform:

      Request = nread,
      {ok, true} = socket:is_supported(ioctl_requests, Request),
      :

-spec ioctl(Socket, GetRequest, NameOrIndex) -> {ok, Result} | {error, Reason}
         when
             Socket :: socket(),
             GetRequest ::
                 gifname | gifindex | gifaddr | gifdstaddr | gifbrdaddr | gifnetmask | gifhwaddr |
                 gifmtu | giftxqlen | gifflags | tcp_info,
             NameOrIndex :: string() | integer(),
             Result :: term(),
             Reason :: posix() | closed;
     (Socket, SetRequest, Value) -> ok | {error, Reason}
         when
             Socket :: socket(),
             SetRequest :: rcvall,
             Value :: off | on | iplevel,
             Reason :: posix() | closed;
     (Socket, SetRequest, Value) -> ok | {error, Reason}
         when
             Socket :: socket(),
             SetRequest :: rcvall_igmpmcast | rcvall_mcast,
             Value :: off | on,
             Reason :: posix() | closed.

Get or set socket (device) parameters.

This function retrieves a specific parameter, according to one of the following GetRequest arguments. The third argument is the (lookup) "key", identifying the interface, for most requests the name of the interface as a string/0.

• gifname - Get the name of the interface with the specified index (integer/0).

  Result; the name of the interface, string/0.

• gifindex - Get the index of the interface with the specified name.

  Result; the interface index, integer/0.

• gifaddr - Get the address of the interface with the specified name.

  Result; the address of the interface, sockaddr/0.

• gifdstaddr - Get the destination address of the point-to-point interface with the specified name.

  Result; the destination address of the interface, sockaddr/0.

• gifbrdaddr - Get the broadcast address of the interface with the specified name.

  Result; broadcast address of the interface, sockaddr/0.

• gifnetmask - Get the network mask of the interface with the specified name.

  Result; the network mask of the interface, sockaddr/0.

• gifhwaddr - Get the hardware address for the interface with the specified name.

  Result; the hardware address of the interface, sockaddr/0. The family field contains the 'ARPHRD' device type (or an integer).

• gifmtu - Get the MTU (Maximum Transfer Unit) for the interface with the specified name.

  Result; MTU of the interface, integer/0.

• giftxqlen - Get the transmit queue length of the interface with the specified name.

  Result; transmit queue length of the interface, integer/0.

• gifflags - Get the active flag word of the interface with the specified name.

  Result; the active flag word of the interface, is a list of ioctl_device_flag/0 | t:integer( ).

With the following SetRequest argument this function sets the Value for the request parameter (since OTP 26.1).

• rcvall - Enables (or disables) a socket to receive all IPv4 or IPv6 packages passing through a network interface.

  The Socket has to be one of:

  • An IPv4 socket - Created with the address domain inet, socket type raw and protocol ip.

  • An IPv6 socket - Created with the address domain inet6, socket type raw and protocol ipv6.

  The socket must also be bound to an (explicit) local IPv4 or IPv6 interface (any isn't allowed).

  Setting this IOCTL requires elevated privileges.

With the following SetRequest arguments this function sets the Value for the request parameter (since OTP 26.1).

• rcvall_igmpmcall - Enables (or disables) a socket to receive IGMP multicast IP traffic, without receiving any other IP traffic.

  The socket has to be created with the address domain inet, socket type raw and protocol igmp.

  The socket must also be bound to an (explicit) local interface (any isn't allowed).

  The receive buffer must be sufficiently large.

  Setting this IOCTL requires elevated privileges.

• rcvall_mcall - Enables (or disables) a socket to receive all multicast IP traffic (as in; all IP packets destined for IP addresses in the range 224.0.0.0 to 239.255.255.255).

  The socket has to be created with the address domain inet, socket type raw and protocol udp.

  The socket must also be bound to an (explicit) local interface (any isn't allowed), And bound to port 0.

  The receive buffer must be sufficiently large.

  Setting this IOCTL requires elevated privileges.

-spec ioctl(Socket, SetRequest, Name, Value) -> ok | {error, Reason}
         when
             Socket :: socket(),
             SetRequest ::
                 sifflags | sifaddr | sifdstaddr | sifbrdaddr | sifnetmask | sifhwaddr | gifmtu |
                 siftxqlen,
             Name :: string(),
             Value :: term(),
             Reason :: posix() | closed.

Set socket (device) parameters.

This function sets a specific parameter, according to the SetRequest argument. The Name argument is the name of the interface, and the Value argument is the value to set.

These operations require elevated privileges.

• sifflags - Set the the active flag word, #{Flag => boolean()}, of the interface with the specified name.

  Each flag to be changed should be added to the value map/0, with the value true if the Flag should be set and false if the flag should be cleared.

• sifaddr - Set the address, sockaddr/0, of the interface with the specified name.

• sifdstaddr - Set the destination address, sockaddr/0, of a point-to-point interface with the specified name.

• sifbrdaddr - Set the broadcast address, sockaddr/0, of the interface with the specified name.

• sifnetmask - Set the network mask, sockaddr/0, of the interface with the specified name.

• sifmtu - Set the MTU (Maximum Transfer Unit), integer/0, for the interface with the specified name.

• siftxqlen - Set the transmit queue length, integer/0, of the interface with the specified name.

-spec is_supported(Key1 :: term()) -> boolean().

Check if a socket feature is supported.

Returns true if supports/0 has a {Key1, true} tuple or a {Key1, list()} tuple in its returned list, otherwise false (also for unknown keys).

Example:

true = socket:is_supported(local),

-spec is_supported(Key1 :: term(), Key2 :: term()) -> boolean().

Check if a socket feature is supported.

Returns true if supports(Key1) has a {Key2, true} tuple in its returned list, otherwise false (also for unknown keys).

Example:

true = socket:is_supported(msg_flags, errqueue),

-spec listen(Socket :: term()) -> _.

Make a socket listen for connections.

Equivalent to listen(Socket, Backlog) with a default value for Backlog (currently 5).

-spec listen(Socket, Backlog) -> ok | {error, Reason}
          when Socket :: socket(), Backlog :: integer(), Reason :: posix() | closed.

Make a socket listen for connections.

The Backlog argument states the length of the queue for incoming not yet accepted connections. Exactly how that number is interpreted is up to the OS' protocol stack, but the resulting effective queue length will most probably be perceived as at least that long.

Note

On Windows the socket has to be bound.

-spec monitor(Socket :: socket()) -> MonitorRef :: reference().

Start a socket monitor.

If the Socket doesn't exist or when later the monitor is triggered, a 'DOWN' message is sent to the process that called monitor/1 with the following pattern:

	    {'DOWN', MonitorRef, socket, Socket, Info}

Info is the termination reason of the socket or nosock if Socket did not exist when the monitor was started.

Making several calls to socket:monitor/1 for the same Socket is not an error; each call creates an independent monitor instance.

-spec number_of() -> non_neg_integer().

Return the number of active sockets.

-spec open(FD :: integer()) -> _.

Equivalent to open(FD, #{}).

-spec open(FD, Opts) -> {ok, Socket} | {error, Reason}
        when
            FD :: integer(),
            Opts ::
                #{domain => domain() | integer(),
                  type => type() | integer(),
                  protocol => default | protocol() | integer(),
                  dup => boolean(),
                  debug => boolean(),
                  use_registry => boolean()},
            Socket :: socket(),
            Reason :: posix() | domain | type | protocol;
    (Domain :: term(), Type :: term()) -> _.

Create a socket.

With arguments Domain and Type

Equivalent to open(Domain, Type, default, #{}).

With arguments FD and Opts (since OTP 23.0)

Creates an endpoint for communication (socket) based on an already existing file descriptor that must be a socket. This function attempts to retrieve the file descriptor's domain, type and protocol from the system. This is however not possible on all platforms; in that case they should be specified in Opts.

The Opts argument can provide extra information:

• domain - The file descriptor's communication domain. See also

  open/2,3,4.

• type - The file descriptor's socket type.

  See also open/2,3,4.

• protocol - The file descriptor's protocol. The atom default is equivalent to the integer protocol number 0 which means the default protocol for a given domain and type.

  If the protocol can not be retrieved from the platform for the socket, and protocol is not specified, the default protocol is used, which may or may not be correct.

  See also open/2,3,4.

• dup - If false don't duplicate the provided file descriptor.

  Defaults to true; do duplicate the file descriptor.

• debug - If true enable socket debug logging.

  Defaults to false; don't enable socket debug logging.

• use_registry - Enable or disable use of the socket registry for this socket. This overrides the global setting.

  Defaults to the global setting, see use_registry/1.

Note

This function should be used with care!

On some platforms it is necessary to provide domain, type and protocol since they cannot be retrieved from the platform.

On some platforms it is not easy to get hold of a file descriptor to use in this function.

-spec open(Domain :: term(), Type :: term(), Opts :: map()) -> _;
    (Domain :: term(), Type :: term(), Protocol :: term()) -> _.

Create a socket.

With arguments Domain, Type and Protocol

Equivalent to open(Domain, Type, Protocol, #{}).

With arguments Domain, Type and Opts (since OTP 24.0)

Equivalent to open(Domain, Type, default, #{}).

-spec open(Domain, Type, Protocol, Opts) -> {ok, Socket} | {error, Reason}
        when
            Domain :: domain() | integer(),
            Type :: type() | integer(),
            Protocol :: default | protocol() | integer(),
            Opts :: #{netns => string(), debug => boolean(), use_registry => boolean()},
            Socket :: socket(),
            Reason :: posix() | protocol.

Create a socket.

Creates an endpoint for communication (socket).

Domain and Type may be integer/0s, as defined in the platform's header files. The same goes for Protocol as defined in the platform's services(5) database. See also the OS man page for the library call socket(2).

Note

For some combinations of Domain and Type the platform has got a default protocol that can be selected with Protocol = default, and the platform may allow or require selecting the default protocol, or a specific protocol.

Examples:

• socket:open(inet, stream, tcp) - It is common that for protocol domain and type inet,stream it is allowed to select the tcp protocol although that mostly is the default.
• socket:open(local, dgram) - It is common that for the protocol domain local it is mandatory to not select a protocol, that is; to select the default protocol.

The Opts argument is intended for "other" options. The supported option(s) are described below:

• netns: string() - Used to set the network namespace during the open call. Only supported on Linux.

• debug: boolean() - Enable or disable debug logging.

  Defaults to false.

• use_registry: boolean() - Enable or disable use of the socket registry for this socket. This overrides the global value.

  Defaults to the global value, see use_registry/1.

-spec peername(Socket :: socket()) -> {ok, SockAddr} | {error, Reason}
            when SockAddr :: sockaddr_recv(), Reason :: posix() | closed.

Return the remote address of a socket.

Returns the address of the connected peer, that is, the remote end of the socket.

-spec recv(Socket :: term()) -> _.

Equivalent to recv(Socket, 0, [], infinity).

-spec recv(Socket :: term(), Flags :: list()) -> _;
    (Socket :: term(), Length :: non_neg_integer()) -> _.

Receive data on a connected socket.

With argument Length; equivalent to recv(Socket, Length, [], infinity).

With argument Flags; equivalent to recv(Socket, 0, Flags, infinity) (since OTP 24.0).

-spec recv(Socket :: term(), Flags :: list(), TimeoutOrHandle :: term()) -> _;
    (Socket :: term(), Length :: term(), Flags :: list()) -> _;
    (Socket :: term(), Length :: term(), TimeoutOrHandle :: term()) -> _.

Receive data on a connected socket.

With arguments Length and Flags; equivalent to recv(Socket, Length, Flags, infinity).

With arguments Length and TimeoutOrHandle; equivalent to recv(Socket, Length, [], TimeoutOrHandle). TimeoutOrHandle :: nowait has been allowed since OTP 22.1. TimeoutOrHandle :: Handle has been allowed since OTP 24.0.

With arguments Flags and TimeoutOrHandle; equivalent to recv(Socket, 0, Flags, TimeoutOrHandle) (since OTP 24.0).

-spec recv(Socket, Length, Flags, Timeout :: infinity) ->
        {ok, Data} | {error, Reason} | {error, {Reason, Data}}
        when
            Socket :: socket(),
            Length :: non_neg_integer(),
            Flags :: [msg_flag() | integer()],
            Data :: binary(),
            Reason :: posix() | closed | invalid();
    (Socket, Length, Flags, Timeout :: non_neg_integer()) ->
        {ok, Data} | {error, Reason} | {error, {Reason, Data}}
        when
            Socket :: socket(),
            Length :: non_neg_integer(),
            Flags :: [msg_flag() | integer()],
            Data :: binary(),
            Reason :: posix() | closed | invalid() | timeout;
    (Socket, Length, Flags, nowait | Handle) ->
        {ok, Data} |
        {select, SelectInfo} |
        {select, {SelectInfo, Data}} |
        {completion, CompletionInfo} |
        {error, Reason} |
        {error, {Reason, Data}}
        when
            Socket :: socket(),
            Length :: non_neg_integer(),
            Flags :: [msg_flag() | integer()],
            Handle :: select_handle() | completion_handle(),
            Data :: binary(),
            SelectInfo :: select_info(),
            CompletionInfo :: completion_info(),
            Reason :: posix() | closed | invalid().

Receive data on a connected socket.

The argument Length specifies how many bytes to receive, with the special case 0 meaning "all available".

When Length is 0, a default buffer size is used, which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).

The message Flags may be symbolic msg_flag/0s and/or integer/0s as in the platform's appropriate header files. The values of all symbolic flags and integers are or:ed together.

When there is a socket error this function returns {error, Reason}, or if some data arrived before the error; {error, {Reason, Data}} (can only happen for a socket of type stream).

If the Timeout argument is infinity; waits for the data to arrive. For a socket of type stream this call won't return until all requested data can be delivered, or if "all available" was requested when the first data chunk arrives, or if the OS reports an error for the operation.

If the Timeout argument is a time-out value (non_neg_integer/0); return {error, timeout} if no data has arrived after Timeout milliseconds, or {error, {timeout, Data}} if some but not enough data has been received on a socket of type stream.

Timeout = 0 only polls the OS receive call and doesn't engage the Asynchronous Calls mechanisms. If no data is immediately available {error, timeout} is returned.On a socket of type stream, {error, {timeout, Data}} is returned if there is an insufficient amount of data immediately available.

If the Handle argument is nowait (since OTP 22.1), starts an asynchronous call if the operation couldn't be completed immediately.

If the Handle argument is a select_handle/0, (since OTP 24.0), or on Windows, the equivalent completion_handle/0 (since OTP 26.0), starts an asynchronous call like for nowait.

See the note Asynchronous Calls at the start of this module reference manual page.

On select systems, for a socket of type stream, if Length > 0 and there isn't enough data available, this function will return {select, {SelectInfo, Data}} with partial Data. A repeated call to complete the operation will probably need an updated Length argument.

-spec recvfrom(Socket :: term()) -> _.

Equivalent to recvfrom(Socket, 0, [], infinity).

-spec recvfrom(Socket :: term(), Flags :: list()) -> _;
        (Socket :: term(), BufSz :: non_neg_integer()) -> _.

Receive a message on a socket.

With argument BufSz; equivalent to recvfrom(Socket, BufSz, [], infinity).

With argument Flags; equivalent to recvfrom(Socket, 0, Flags, infinity) (since OTP 24.0).

-spec recvfrom(Socket :: term(), Flags :: list(), TimeoutOrHandle :: term()) -> _;
        (Socket :: term(), BufSz :: term(), Flags :: list()) -> _;
        (Socket :: term(), BufSz :: term(), TimeoutOrHandle :: term()) -> _.

Receive a message on a socket.

With arguments BufSz and Flags; equivalent to recvfrom(Socket, BufSz, Flags, infinity).

With arguments BufSz and TimeoutOrHandle; equivalent to recv(Socket, BufSz, [], TimeoutOrHandle).

With arguments Flags and TimeoutOrHandle; equivalent to recv(Socket, 0, Flags, TimeoutOrHandle)

TimeoutOrHandle :: 'nowait' has been allowed since OTP 22.1.

TimeoutOrHandle :: Handle has been allowed since OTP 24.0.

-spec recvfrom(Socket, BufSz, Flags, Timeout :: infinity) -> {ok, {Source, Data}} | {error, Reason}
            when
                Socket :: socket(),
                BufSz :: non_neg_integer(),
                Flags :: [msg_flag() | integer()],
                Source :: sockaddr_recv(),
                Data :: binary(),
                Reason :: posix() | closed | invalid();
        (Socket, BufSz, Flags, Timeout :: non_neg_integer()) ->
            {ok, {Source, Data}} | {error, Reason}
            when
                Socket :: socket(),
                BufSz :: non_neg_integer(),
                Flags :: [msg_flag() | integer()],
                Source :: sockaddr_recv(),
                Data :: binary(),
                Reason :: posix() | closed | invalid() | timeout;
        (Socket, BufSz, Flags, nowait | Handle) ->
            {ok, {Source, Data}} |
            {select, SelectInfo} |
            {completion, CompletionInfo} |
            {error, Reason}
            when
                Socket :: socket(),
                BufSz :: non_neg_integer(),
                Flags :: [msg_flag() | integer()],
                Handle :: select_handle() | completion_handle(),
                Source :: sockaddr_recv(),
                Data :: binary(),
                SelectInfo :: select_info(),
                CompletionInfo :: completion_info(),
                Reason :: posix() | closed | invalid().

Receive a message on a socket.

This function is intended for sockets that are not connection oriented such as type dgram or seqpacket where it may arrive messages from different source addresses.

Argument BufSz specifies the number of bytes for the receive buffer. If the buffer size is too small, the message will be truncated.

If BufSz is 0, a default buffer size is used, which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz).

If there is no known appropriate buffer size, it may be possible to use the receive message flag peek. When this flag is used, the message is not "consumed" from the underlying buffers, so another recvfrom/1,2,3,4 call is needed, possibly with an adjusted buffer size.

The message Flags may be symbolic msg_flag/0s and/or integer/0s, as in the platform's appropriate header files. The values of all symbolic flags and integers are or:ed together.

If the Timeout argument is infinity; waits for a message to arrive, or for a socket error.

If the Timeout argument is a time-out value (non_neg_integer/0); returns {error, timeout} if no message has arrived after Timeout milliseconds.

Timeout = 0 only polls the OS receive call and doesn't engage the Asynchronous Calls mechanisms. If no message is immediately available {error, timeout} is returned.

If the Handle argument is nowait (since OTP 22.1), starts an asynchronous call if the operation couldn't be completed immediately.

If the 'Handle' argument is a select_handle/0, (since OTP 24.0), or on Windows, the equivalent completion_handle/0 (since OTP 26.0), starts an asynchronous call like for nowait.

See the note Asynchronous Calls at the start of this module reference manual page.

-spec recvmsg(Socket :: term()) -> _.

Equivalent to recvmsg(Socket, 0, 0, [], infinity).

-spec recvmsg(Socket :: term(), Flags :: list()) -> _;
       (Socket :: term(), TimeoutOrHandle :: term()) -> _.

Receive a message on a socket.

With argument Flags; equivalent to recvmsg(Socket, 0, 0, Flags, infinity).

With argument TimeoutOrHandle; equivalent to recvmsg(Socket, 0, 0, [], TimeoutOrHandle).

TimeoutOrHandle :: nowait has been allowed since OTP 22.1.

TimeoutOrHandle :: Handle has been allowed since OTP 24.0.

-spec recvmsg(Socket :: term(), Flags :: list(), TimeoutOrHandle :: term()) -> _;
       (Socket :: term(), BufSz :: integer(), CtrlSz :: integer()) -> _.

Receive a message on a socket.

With arguments Flags; equivalent to recvmsg(Socket, 0, 0, Flags, infinity).

With argument TimeoutOrHandle; equivalent to recvmsg(Socket, 0, 0, [], TimeoutOrHandle).

TimeoutOrHandle :: nowait has been allowed since OTP 22.1.

TimeoutOrHandle :: Handle has been allowed since OTP 24.0.

-spec recvmsg(Socket :: term(), BufSz :: term(), CtrlSz :: term(), TimeoutOrHandle :: term()) -> _.

Equivalent to recvmsg(Socket, BufSz, CtrlSz, [], TimeoutOrHandle).

-spec recvmsg(Socket, BufSz, CtrlSz, Flags, Timeout :: infinity) -> {ok, Msg} | {error, Reason}
           when
               Socket :: socket(),
               BufSz :: non_neg_integer(),
               CtrlSz :: non_neg_integer(),
               Flags :: [msg_flag() | integer()],
               Msg :: msg_recv(),
               Reason :: posix() | closed | invalid();
       (Socket, BufSz, CtrlSz, Flags, Timeout :: non_neg_integer()) -> {ok, Msg} | {error, Reason}
           when
               Socket :: socket(),
               BufSz :: non_neg_integer(),
               CtrlSz :: non_neg_integer(),
               Flags :: [msg_flag() | integer()],
               Msg :: msg_recv(),
               Reason :: posix() | closed | invalid() | timeout;
       (Socket, BufSz, CtrlSz, Flags, nowait | Handle) ->
           {ok, Msg} | {select, SelectInfo} | {completion, CompletionInfo} | {error, Reason}
           when
               Socket :: socket(),
               BufSz :: non_neg_integer(),
               CtrlSz :: non_neg_integer(),
               Handle :: select_handle() | completion_handle(),
               Flags :: [msg_flag() | integer()],
               Msg :: msg_recv(),
               SelectInfo :: select_info(),
               CompletionInfo :: completion_info(),
               Reason :: posix() | closed | invalid().

Receive a message on a socket.

This function receives both data and control messages.

Arguments BufSz and CtrlSz specifies the number of bytes for the receive buffer and the control message buffer. If the buffer size(s) is(are) too small, the message and/or control message list will be truncated.

If BufSz is 0, a default buffer size is used, which can be set by socket:setopt(Socket, {otp,recvbuf}, BufSz). The same applies to CtrlSz and socket:setopt(Socket, {otp,recvctrlbuf}, CtrlSz).

If there is no known appropriate buffer size, it may be possible to use the receive message flag peek. When this flag is used, the message is not "consumed" from the underlying buffers, so another recvfrom/1,2,3,4 call is needed, possibly with an adjusted buffer size.

The message Flags may be symbolic msg_flag/0s and/or integer/0s, as in the platform's appropriate header files. The values of all symbolic flags and integers are or:ed together.

If the Timeout argument is infinity; waits for the message to arrive, or for a socket error.

If the Timeout argument is a time-out value (non_neg_integer/0); return {error, timeout} if no message has arrived after Timeout milliseconds.

Timeout = 0 only polls the OS receive call and doesn't engage the Asynchronous Calls mechanisms. If no message is immediately available {error, timeout} is returned.

If the Handle argument is nowait (since OTP 22.1), starts an asynchronous call if the operation couldn't be completed immediately.

If the 'Handle' argument is a select_handle/0, (since OTP 24.0), or on Windows, the equivalent completion_handle/0 (since OTP 26.0), starts an asynchronous call like for nowait.

See the note Asynchronous Calls at the start of this module reference manual page.

-spec send(Socket :: term(), Data :: term()) -> _.

Equivalent to send(Socket, Data, [], infinity).

-spec send(Socket :: term(), Data :: term(), Cont :: tuple()) -> _;
    (Socket :: term(), Data :: term(), Flags :: list()) -> _;
    (Socket :: term(), Data :: term(), Timeout :: timeout()) -> _.

Send data on a connected socket.

With argument Timeout; equivalent to send(Socket, Data, [], Timeout).

With argument Flags; equivalent to send(Socket, Data, Flags, infinity).

With argument Cont; equivalent to send(Socket, Data, Cont, infinity) (since OTP 24.0).

-spec send(Socket, Data, Flags | Cont, Timeout :: infinity) ->
        ok | {ok, RestData} | {error, Reason} | {error, {Reason, RestData}}
        when
            Socket :: socket(),
            Data :: iodata(),
            Flags :: [msg_flag() | integer()],
            Cont :: select_info(),
            RestData :: binary(),
            Reason :: posix() | closed | invalid() | netname_deleted | too_many_cmds | eei();
    (Socket, Data, Flags | Cont, Timeout :: non_neg_integer()) ->
        ok | {ok, RestData} | {error, Reason | timeout} | {error, {Reason | timeout, RestData}}
        when
            Socket :: socket(),
            Data :: iodata(),
            Flags :: [msg_flag() | integer()],
            Cont :: select_info(),
            RestData :: binary(),
            Reason :: posix() | closed | invalid() | netname_deleted | too_many_cmds | eei();
    (Socket, Data, Flags | Cont, nowait | Handle) ->
        ok |
        {ok, RestData} |
        {select, SelectInfo} |
        {select, {SelectInfo, RestData}} |
        {completion, CompletionInfo} |
        {error, Reason}
        when
            Socket :: socket(),
            Data :: iodata(),
            Flags :: [msg_flag() | integer()],
            Cont :: select_info(),
            Handle :: select_handle() | completion_handle(),
            RestData :: binary(),
            SelectInfo :: select_info(),
            CompletionInfo :: completion_info(),
            Reason :: posix() | closed | invalid() | netname_deleted | too_many_cmds | eei().

Send data on a connected socket.

The message Flags may be symbolic msg_flag/0s and/or integer/0s as in the platform's appropriate header files. The values of all symbolic flags and integers are or:ed together.

The Data, if it is not a binary/0, is copied into one before calling the platform network API, because a single buffer is required. A returned RestData is a sub binary of it.

The return value indicates the result from the platform's network layer:

• ok - All data was accepted by the OS for delivery

• {ok, RestData} - Some but not all data was accepted, but no error was reported (partially successful send). RestData is the tail of Data that wasn't accepted.

  This cannot happen for a socket of type stream where such a partially successful send is retried until the data is either accepted for delivery or there is an error.

  For a socket of type dgram this should probably also not happen since a message that cannot be passed atomically should render an error.

  It is nevertheless possible for the platform's network layer to return this, surely more possible for a socket of type seqpacket.

• {error, Reason} - An error has been reported and no data was accepted for delivery. Reason :: posix/0 is what the platform's network layer reported. closed means that this socket library was informed that the socket was closed, and invalid/0 means that this socket library found an argument to be invalid.

• {error, {Reason, RestData}} - An error was reported but before that some data was accepted for delivery. RestData is the tail of Data that wasn't accepted. See {error, Reason} above.

  This can only happen for a socket of type stream when a partially successful send is retried until there is an error.

If the Timeout argument is infinity; wait for the OS to complete the send operation (take responsibility for the data), or return an error.

If the Timeout argument is a time-out value (non_neg_integer/0); return {error, timeout} if no data has been sent within Timeout millisecond, or {error, {timeout, RestData}} if some data was sent (accepted by the OS for delivery). RestData is the tail of the data that hasn't been sent.

If the Handle argument is nowait (since OTP 22.1), starts an asynchronous call if the operation couldn't be completed immediately.

If the Handle argument is a select_handle/0, (since OTP 24.0), or on Windows, the equivalent completion_handle/0 (since OTP 26.0), starts an asynchronous call like for nowait.

See the note Asynchronous Calls at the start of this module reference manual page.

If the function is called with a Cont argument, that is; the SelectInfo from the previous send/3,4 call; the send is continued with preprocessed send parameters in the SelectInfo. Using this argument variant avoids for example having to validate and encode message flags in every call but the first.

-spec sendfile(Socket :: term(), FileHandle_or_Continuation :: term()) -> _.

Send a file on a socket.

Equivalent to sendfile(Socket, FileHandle_or_Continuation, 0, 0, infinity).

-spec sendfile(Socket :: term(), FileHandle_or_Continuation :: term(), Timeout_or_Handle :: term()) -> _.

Send a file on a socket.

Equivalent to sendfile(Socket, FileHandle_or_Continuation, 0, 0, Timeout_or_Handle).

-spec sendfile(Socket :: term(),
         FileHandle_or_Continuation :: term(),
         Offset :: term(),
         Count :: term()) ->
            _.

Send a file on a socket.

Equivalent to sendfile(Socket, FileHandle_or_Continuation, Offset, Count, infinity).

-spec sendfile(Socket, FileHandle | Continuation, Offset, Count, Timeout :: infinity) ->
            {ok, BytesSent} | {error, Reason} | {error, {Reason, BytesSent}}
            when
                Socket :: socket(),
                FileHandle :: file:fd(),
                Continuation :: select_info(),
                Offset :: integer(),
                Count :: non_neg_integer(),
                BytesSent :: non_neg_integer(),
                Reason :: posix() | closed | invalid();
        (Socket, FileHandle | Continuation, Offset, Count, Timeout :: non_neg_integer()) ->
            {ok, BytesSent} | {error, Reason} | {error, {Reason, BytesSent}}
            when
                Socket :: socket(),
                FileHandle :: file:fd(),
                Continuation :: select_info(),
                Offset :: integer(),
                Count :: non_neg_integer(),
                BytesSent :: non_neg_integer(),
                Reason :: posix() | closed | invalid() | timeout;
        (Socket,
         FileHandle | Continuation,
         Offset, Count,
         nowait | (SelectHandle :: select_handle())) ->
            {ok, BytesSent} |
            {select, SelectInfo} |
            {select, {SelectInfo, BytesSent}} |
            {error, Reason}
            when
                Socket :: socket(),
                FileHandle :: file:fd(),
                Continuation :: select_info(),
                Offset :: integer(),
                Count :: non_neg_integer(),
                BytesSent :: non_neg_integer(),
                SelectInfo :: select_info(),
                Reason :: posix() | closed | invalid().

Send a file on a socket.

Note

This function unsupported on Windows.

The FileHandle argument must refer to an open raw file as described in file:open/2.

The Offset argument is the file offset to start reading from. The default offset is 0.

The Count argument is the number of bytes to transfer from FileHandle to Socket. If Count = 0 (the default) the transfer stops at the end of file.

The return value indicates the result from the platform's network layer:

• {ok, BytesSent} - The transfer completed successfully after BytesSent bytes of data.

• {error, Reason} - An error has been reported and no data was transferred. Reason :: posix/0 is what the platform's network layer reported. closed means that this socket library was informed that the socket was closed, and invalid/0 means that this socket library found an argument to be invalid.

• {error, {Reason, BytesSent}} - An error has been reported but before that some data was transferred. See {error, Reason} and {ok, BytesSent} above.

If the Timeout argument is infinity; wait for the OS to complete the send operation (take responsibility for the data), or return an error.

If the Timeout argument is a time-out value (non_neg_integer/0); return {error, timeout} if no data has been sent within Timeout millisecond, or {error, {timeout, BytesSent}} if some but not all data was sent (accepted by the OS for delivery).

If the Handle argument is nowait, starts an asynchronous call if the operation couldn't be completed immediately.

If the Handle argument is a select_handle/0, starts an asynchronous call like for nowait.

See the note Asynchronous Calls at the start of this module reference manual page.

After receiving a select message call sendfile/2,3,4,5 with SelectInfo as the Continuation argument, to complete the operation.

If the function is called with a Continuation argument, that is; the SelectInfo from the previous sendfile/5 call; the transfer is continued with preprocessed parameters in the SelectInfo.

The Offset and maybe Count arguments will probably need to be updated between continuation calls.

-spec sendmsg(Socket :: term(), Msg :: term()) -> _.

Equivalent to sendmsg(Socket, Msg, [], infinity).

-spec sendmsg(Socket :: term(), Msg :: term(), Flags :: list()) -> _;
       (Socket :: term(), Data :: term(), Cont :: select_info()) -> _;
       (Socket :: term(), Msg :: term(), Timeout :: term()) -> _.

Send data and control messages on a socket.

With arguments Msg and Timeout; equivalent to sendmsg(Socket, Msg, [], Timeout).

With arguments Msg and Flags; equivalent to sendmsg(Socket, Msg, Flags, infinity).

With arguments Data and Cont; equivalent to sendmsg(Socket, Data, Cont, infinity) since OTP 24.0.

-spec sendmsg(Socket, Msg, Flags, Timeout :: infinity) ->
           ok | {ok, RestData} | {error, Reason} | {error, {Reason, RestData}}
           when
               Socket :: socket(),
               Msg :: msg_send(),
               Flags :: [msg_flag() | integer()],
               RestData :: erlang:iovec(),
               Reason :: posix() | closed | invalid();
       (Socket, Msg, Flags, Timeout :: non_neg_integer()) ->
           ok | {ok, RestData} | {error, Reason | timeout} | {error, {Reason | timeout, RestData}}
           when
               Socket :: socket(),
               Msg :: msg_send(),
               Flags :: [msg_flag() | integer()],
               RestData :: erlang:iovec(),
               Reason :: posix() | closed | invalid();
       (Socket, Msg, Flags, nowait | Handle) ->
           ok |
           {ok, RestData} |
           {select, SelectInfo} |
           {select, {SelectInfo, RestData}} |
           {completion, CompletionInfo} |
           {error, Reason} |
           {error, {Reason, RestData}}
           when
               Socket :: socket(),
               Msg :: msg_send(),
               Flags :: [msg_flag() | integer()],
               Handle :: select_handle() | completion_handle(),
               RestData :: erlang:iovec(),
               SelectInfo :: select_info(),
               CompletionInfo :: completion_info(),
               Reason :: posix() | closed | invalid();
       (Socket, Data, Cont, Timeout :: infinity) ->
           ok | {ok, RestData} | {error, Reason} | {error, {Reason, RestData}}
           when
               Socket :: socket(),
               Data :: msg_send() | erlang:iovec(),
               Cont :: select_info(),
               RestData :: erlang:iovec(),
               Reason :: posix() | closed | invalid();
       (Socket, Data, Cont, Timeout :: non_neg_integer()) ->
           ok | {ok, RestData} | {error, Reason | timeout} | {error, {Reason | timeout, RestData}}
           when
               Socket :: socket(),
               Data :: msg_send() | erlang:iovec(),
               Cont :: select_info(),
               RestData :: erlang:iovec(),
               Reason :: posix() | closed | invalid();
       (Socket, Data, Cont, nowait | Handle) ->
           ok |
           {ok, RestData} |
           {select, SelectInfo} |
           {select, {SelectInfo, RestData}} |
           {completion, CompletionInfo} |
           {error, Reason} |
           {error, {Reason, RestData}}
           when
               Socket :: socket(),
               Data :: msg_send() | erlang:iovec(),
               Cont :: select_info(),
               Handle :: select_handle(),
               RestData :: erlang:iovec(),
               SelectInfo :: select_info(),
               CompletionInfo :: completion_info(),
               Reason :: posix() | closed | invalid().

Send data and control messages on a socket.

The argument Msg is a map that contains the data to be sent under the key iov as anerlang:iovec/0 (list of binary/0). It may also contain the destination address under the key addr, which is mandatory if the socket isn't connected. If the socket is connected it is best to not have an addr key since the platform may regard that as an error (or ignore it). Under the key ctrl there may be a list of protocol and platform dependent control messages (a.k.a ancillary data, a.k.a control information) to send.

The message data is given to the platform's network layer as 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 iov_max field from info/0), on a socket of type stream the send is iterated over all elements, but for other socket types the call fails.

See send/4 for a description of the Flags argument and the return values.

Note

On Windows, this function can only be used with datagram and raw sockets.

If the Timeout argument is infinity; wait for the OS to complete the send operation (take responsibility for the data), or return an error.

If the Timeout argument is a time-out value (non_neg_integer/0); return {error, timeout} if no data has been sent within Timeout millisecond, or {error, {timeout, RestData}} if some data was sent (accepted by the OS for delivery). RestData is the tail of the data that hasn't been sent.

If the Handle argument is nowait (since OTP 22.1), starts an asynchronous call if the operation couldn't be completed immediately.

If the Handle argument is a select_handle/0, (since OTP 24.0), or on Windows, the equivalent completion_handle/0 (since OTP 26.0), starts an asynchronous call like for nowait.

See the note Asynchronous Calls at the start of this module reference manual page.

After receiving a select message call sendmsg/3,4 with SelectInfo as the Cont argument, to complete the operation.

With the arguments Data and Cont, continues the send operation. Cont should be the SelectInfo returned from the previous sendmsg/2,3,4 call.

Data can be a Msg map/0 where only the key iov is used, or an erlang:iovec/0.

-spec sendto(Socket :: term(), Data :: term(), Cont :: select_info()) -> _;
      (Socket :: term(), Data :: term(), Dest :: term()) -> _.

Send data on a socket.

With argument Dest; equivalent to sendto(Socket, Data, Dest, [], infinity).

With argument Cont; equivalent to sendto(Socket, Data, Cont, infinity) since OTP 24.0.

-spec sendto(Socket :: term(), Data :: term(), Dest :: term(), Flags :: list()) -> _;
      (Socket :: term(), Data :: term(), Cont :: select_info(), TimeoutOrHandle :: term()) -> _;
      (Socket :: term(), Data :: term(), Dest :: term(), TimeoutOrHandle :: term()) -> _.

Send data on a socket.

With arguments Dest and TimeoutOrHandle; equivalent to sendto(Socket, Data, Dest, [], TimeoutOrHandle).

With arguments Dest and Flags; equivalent to sendto(Socket, Data, Dest, Flags, infinity).

With arguments Cont and TimeoutOrHandle; Cont must be the SelectInfo from the previous sendto/3,4,5 call and the send is continued with preprocessed send parameters in the SelectInfo. Using this argument variant avoids for example having o validate and encode message flags in every call but the first. (Since OTP 24.0)

See the last argument (argument 5) of sendto/5 for an explanation of TimeoutOrHandle.

-spec sendto(Socket, Data, Dest, Flags, Timeout :: infinity) ->
          ok | {ok, RestData} | {error, Reason} | {error, {Reason, RestData}}
          when
              Socket :: socket(),
              Data :: iodata(),
              Dest :: sockaddr(),
              Flags :: [msg_flag() | integer()],
              RestData :: binary(),
              Reason :: posix() | closed | invalid();
      (Socket, Data, Dest, Flags, Timeout :: non_neg_integer()) ->
          ok | {ok, RestData} | {error, Reason | timeout} | {error, {Reason | timeout, RestData}}
          when
              Socket :: socket(),
              Data :: iodata(),
              Dest :: sockaddr(),
              Flags :: [msg_flag() | integer()],
              RestData :: binary(),
              Reason :: posix() | closed | invalid();
      (Socket, Data, Dest, Flags, nowait | Handle) ->
          ok |
          {ok, RestData} |
          {select, SelectInfo} |
          {select, {SelectInfo, RestData}} |
          {completion, CompletionInfo} |
          {error, Reason}
          when
              Socket :: socket(),
              Data :: iodata(),
              Dest :: sockaddr(),
              Flags :: [msg_flag() | integer()],
              Handle :: select_handle() | completion_handle(),
              RestData :: binary(),
              SelectInfo :: select_info(),
              CompletionInfo :: completion_info(),
              Reason :: posix() | closed | invalid().

Send data on a socket.

The To argument is the destination address where to send the data. For a connected socket this argument is still passed to the OS call that may ignore the address or return an error.

See send/4 for a description of the Flags and Data arguments, and the return values.

If the Timeout argument is infinity; wait for the OS to complete the send operation (take responsibility for the data), or return an error.

If the Timeout argument is a time-out value (non_neg_integer/0); return {error, timeout} if no data has been sent within Timeout millisecond, or {error, {timeout, RestData}} if some data was sent (accepted by the OS for delivery). RestData is the tail of the data that hasn't been sent.

If the Handle argument is nowait (since OTP 22.1), starts an asynchronous call if the operation couldn't be completed immediately.

If the Handle argument is a select_handle/0, (since OTP 24.0), or on Windows, the equivalent completion_handle/0 (since OTP 26.0), starts an asynchronous call like for nowait.

See the note Asynchronous Calls at the start of this module reference manual page.

After receiving a select message call sendto/3,4 with SelectInfo as the Cont argument, to complete the operation.

-spec sendv(Socket, IOV) -> ok | {ok, RestIOV} | {error, Reason} | {error, {Reason, RestIOV}}
         when
             Socket :: socket(),
             IOV :: erlang:iovec(),
             RestIOV :: erlang:iovec(),
             Reason :: posix() | closed | invalid().

Equivalent to sendv(Socket, IOV, infinity).

-spec sendv(Socket, IOV, Cont) -> ok | {ok, RestIOV} | {error, Reason} | {error, {Reason, RestIOV}}
         when
             Socket :: socket(),
             IOV :: erlang:iovec(),
             Cont :: select_info(),
             RestIOV :: erlang:iovec(),
             Reason :: posix() | closed | invalid();
     (Socket, IOV, Timeout :: nowait) ->
         ok |
         {ok, RestIOV} |
         {select, SelectInfo} |
         {select, {SelectInfo, RestIOV}} |
         {completion, CompletionInfo} |
         {error, Reason} |
         {error, {Reason, RestIOV}}
         when
             Socket :: socket(),
             IOV :: erlang:iovec(),
             RestIOV :: erlang:iovec(),
             SelectInfo :: select_info(),
             CompletionInfo :: completion_info(),
             Reason :: posix() | closed | invalid();
     (Socket, IOV, Handle :: select_handle() | completion_handle()) ->
         ok |
         {ok, RestIOV} |
         {select, SelectInfo} |
         {select, {SelectInfo, RestIOV}} |
         {completion, CompletionInfo} |
         {error, Reason} |
         {error, {Reason, RestIOV}}
         when
             Socket :: socket(),
             IOV :: erlang:iovec(),
             RestIOV :: erlang:iovec(),
             SelectInfo :: select_info(),
             CompletionInfo :: completion_info(),
             Reason :: posix() | closed | invalid();
     (Socket, IOV, Timeout :: infinity) ->
         ok | {ok, RestIOV} | {error, Reason} | {error, {Reason, RestIOV}}
         when
             Socket :: socket(),
             IOV :: erlang:iovec(),
             RestIOV :: erlang:iovec(),
             Reason :: posix() | closed | invalid();
     (Socket, IOV, Timeout :: non_neg_integer()) ->
         ok | {ok, RestIOV} | {error, Reason | timeout} | {error, {Reason | timeout, RestIOV}}
         when
             Socket :: socket(),
             IOV :: erlang:iovec(),
             RestIOV :: erlang:iovec(),
             Reason :: posix() | closed | invalid().

Send erlang:iovec/0 data on a connected socket.

• Cont - (clause 1; Cont :: select_info()) This call translates to the following call: sendv(Socket, IOV, Cont, infinity).

• Handle - (clause 3; Handle :: select_handle() | completion_handle()) that term will be contained in the returned SelectInfo or CompletionInfo and the corresponding select or completion message. The handle is presumed to be unique to this call.

• Timeout = infinity - waiting for the data to be sent. This call will not return until the IOV has been accepted by the platform's network layer, or it reports an error.

• Timeout >= 0 - waiting at most Timeout milliseconds for the data to be sent.

• Timeout = nowait - returns (on Unix) select or (on Windows) a completion continuation if the data could not be sent immediately.

The return value indicates the result from the platform's network layer:

• ok - All data has been accepted.

• {select,SelectInfo| {SelectInfo, RestIOV}} - All data was not immediately accepted by the platform network layer. The caller will then receive this messages: {'$socket', socket(), select, SelectHandle}, after which a subsequent call to sendv/4 will send the data. Only when Timeout = nowait.

• {completion,CompletionInfo} - All data was not immediately accepted by the platform network layer. The caller will then receive this messages: {'$socket', socket(), completion, {CompletionHandle, CompletionStatus}}. The result of the send will be in the CompletionStatus. Only when Timeout = nowait.

• {ok, RestIOV} - Not all data has been accepted, but no error has been reported. RestIOV is the tail of IOV that has not been accepted. It is nevertheless possible for the platform's network layer to return this.

• {error, timeout | {timeout, RestIOV}} - Was unable to send (all or part of) the data within the specified Timeout (only if Timeout >= 0).

• {error, {Reason, RestIOV}} - An error has been reported, but before that, some data was accepted. RestIOV is the tail of IOV that has not been accepted. For Reason, see above.

• {error, Reason} - An error has been reported and no data has been accepted. The posix() Reason are from the platform's network layer. closed means that this socket library knows that the socket is closed, and invalid() means that something about an argument is invalid.

-spec sendv(Socket, IOV, Cont, Timeout :: nowait) ->
         ok |
         {ok, RestIOV} |
         {select, SelectInfo} |
         {select, {SelectInfo, RestIOV}} |
         {completion, CompletionInfo} |
         {error, Reason} |
         {error, {Reason, RestIOV}}
         when
             Socket :: socket(),
             IOV :: erlang:iovec(),
             Cont :: select_info(),
             RestIOV :: erlang:iovec(),
             SelectInfo :: select_info(),
             CompletionInfo :: completion_info(),
             Reason :: posix() | closed | invalid();
     (Socket, IOV, Cont, Timeout :: infinity) ->
         ok | {ok, RestIOV} | {error, Reason} | {error, {Reason, RestIOV}}
         when
             Socket :: socket(),
             IOV :: erlang:iovec(),
             Cont :: select_info(),
             RestIOV :: erlang:iovec(),
             Reason :: posix() | closed | invalid();
     (Socket, IOV, Cont, Timeout :: non_neg_integer()) ->
         ok | {ok, RestIOV} | {error, Reason | timeout} | {error, {Reason | timeout, RestIOV}}
         when
             Socket :: socket(),
             IOV :: erlang:iovec(),
             Cont :: select_info(),
             RestIOV :: erlang:iovec(),
             Reason :: posix() | closed | invalid().

Send data on a connected socket, continuation.

Continues sending data on a connected socket, where the send operation was initiated by sendv/3 with Timeout = nowait that returned a SelectInfo continuation. Otherwise like infinite time-out sendv/2,3,4 or limited time-out sendv/3 respectively. Cont is the SelectInfo that was returned from the previous sendv() call.

The return value indicates the result from the platform's network layer. See sendv/3 (with Timeout = infinity | nowait)

-spec setopt(Socket, SocketOption, Value) -> ok | {error, invalid() | closed}
          when
              Socket :: socket(),
              SocketOption :: {Level :: otp, Opt :: otp_socket_option()},
              Value :: term();
      (Socket, SocketOption, Value) -> ok | {error, posix() | invalid() | closed}
          when Socket :: socket(), SocketOption :: socket_option(), Value :: term().

Set a socket option.

Set an OS protocol level option, or an otp pseudo protocol level option. The latter level is this module's implementation level above the OS protocol levels.

See the type otp_socket_option() for a description of the otp protocol level.

See the type socket_option/0 for which OS protocol level options that this implementation knows about, how they are related to OS option names, and if there are known peculiarities with any of them.

What options that are valid depends on the OS, and on the kind of socket (domain/0,type/0 and protocol/0). See the type t:socket_option() and the socket options chapter in the User's Guide for more info.

Note

Not all options are valid, nor possible to set, on all platforms. That is, even if this socket implementation support an option; it doesn't mean that the underlying OS does.

-spec setopt(socket(), Level :: term(), Opt :: term(), Value :: term()) -> _.

Set a socket option (backwards compatibility function).

Equivalent to setopt(Socket, {Level, Opt}, Value), or as a special case if Opt = NativeOpt :: integer/0 and Value = binary/0 equivalent to setopt_native(Socket, {Level, NativeOpt}, ValueSpec).

Use setopt/3 or setopt_native/3 instead to handle the option level and name as a single term, and to make the difference between known options and native options clear.

-spec setopt_native(Socket, Option, Value) -> ok | {error, posix() | invalid() | closed}
                 when
                     Socket :: socket(),
                     Option :: socket_option() | {Level, NativeOpt} | {NativeLevel, NativeOpt},
                     Value :: native_value(),
                     Level :: level(),
                     NativeLevel :: integer(),
                     NativeOpt :: integer().

Set a "native" socket option.

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 Value is an integer/0 it will be used as a C type (int), if it is a boolean/0 it will be used as a C type (int) with the C implementations values for false or true, and if it is a binary/0 its content and size will be used as the option value.

The socket option may be specified with an ordinary socket_option/0 tuple, with a symbolic Level as {Level :: level/0,NativeOpt :: integer/0}, or with integers for both NativeLevel and NativeOpt as {NativeLevel :: integer/0,NativeOpt :: integer/0}.

If an option is valid depends both on the platform and on what kind of socket it is (domain/0, type/0 and protocol/0).

The integer values for NativeLevel and NativeOpt as well as the Value encoding has to be deduced from the header files for the running system.

-spec shutdown(Socket, How) -> ok | {error, Reason}
            when Socket :: socket(), How :: read | write | read_write, Reason :: posix() | closed.

Shut down all or part of a full-duplex connection.

-spec sockname(Socket :: socket()) -> {ok, SockAddr} | {error, Reason}
            when SockAddr :: sockaddr_recv(), Reason :: posix() | closed.

Get the socket's address.

Returns the address to which the socket is currently bound. If the bind address had the wildcard port 0, the address returned by this function contains the ephemeral port selected by the OS.

-spec supports() ->
            [{Key1 :: term(),
              boolean() | [{Key2 :: term(), boolean() | [{Key3 :: term(), boolean()}]}]}].

Retrieve information about what socket features the module and the platform supports.

Returns a list of, in no particular order, {Key1,supports(Key1)} tuples for every Key1 described in supports/1, and {Key, boolean()} tuples for each of the following keys:

• sctp - SCTP support

• ipv6 - IPv6 support

• local - Unix Domain sockets support (AF_UNIX | AF_LOCAL)

• netns - Network Namespaces support (Linux, setns(2))

• sendfile - Sendfile support (sendfile(2))

-spec supports(Key1 :: term()) -> [{Key2 :: term(), boolean() | [{Key3 :: term(), boolean()}]}].

Retrieve information about what socket features the module and the platform supports.

If Key1 = msg_flags returns a list of {Flag, boolean()} tuples for every Flag in msg_flag/0 with the boolean/0 indicating if the flag is supported on this platform.

If Key1 = protocols returns a list of {Name, boolean()} tuples for every Name inprotocol/0 with the boolean/0 indicating if the protocol is supported on this platform.

If Key1 = options returns a list of {SocketOption, boolean()} tuples for every SocketOption in socket_option/0 with the boolean/0 indicating if the socket option is supported on this platform.

There is no particular order of any of the returned lists.

For other values of Key1 returns []. Note that in future versions of this module or on different platforms, there might be more supported keys.

-spec supports(Key1 :: term(), Key2 :: term()) -> [{Key3 :: term(), boolean()}].

Retrieve information about what socket features the module and the platform supports.

If Key1 = options, for a Key2 in level/0 returns a list of {Opt, boolean()} tuples for all known socket options Opt on that Level = Key2 with the boolean/0 indicating if the socket option is supported on this platform. See setopt/3 and getopt/2.

There is no particular order of any of the returned lists.

For other values of Key1 or Key2 returns []. Note that in future versions of this module or on different platforms, there might be more supported keys.

-spec use_registry(D :: boolean()) -> ok.

Set the global use_registry option default value.

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 open/2,3,4 for more info (the Opts :: map/0).

-spec which_sockets() -> [socket()].

Return a list of all known sockets.

Equivalent to which_sockets(fun (_) -> true end).

-spec which_sockets(FilterRule) -> [socket()]
                 when
                     FilterRule ::
                         inet | inet6 | local | stream | dgram | seqpacket | sctp | tcp | udp |
                         pid() |
                         fun((socket_info()) -> boolean()).

Return a filtered list of known sockets.

There are several predefined FilterRules and one general:

• inet | inet6 - Only the sockets with matching domain/0 are returned.

• stream | dgram | seqpacket - Only the sockets with matching type/0 are returned.

• sctp | tcp | udp - Only the sockets with matching protocol/0 are returned.

• pid/0 - Only the sockets with matching Controlling Process are returned. See the OTP socket option controlling_process.

• fun((socket_info()) -> boolean()) - The general filter rule. A fun that takes the socket info and returns a boolean/0 indicating if the socket should be returned or not.