This module provides access to TCP/IP protocols.
See also
The following two Kernel configuration parameters affect the behavior of all sockets opened on an Erlang node:
When
Using the Kernel configuration parameters above, one
can set default options for all TCP sockets on a node, but use this
with care. Options such as
$ erl -sname test -kernel \
inet_default_connect_options '[{delay_send,true}]' \
inet_default_listen_options '[{delay_send,true}]'
Notice that default option
Addresses as inputs to functions can be either a string or a
tuple. For example, the IP address 150.236.20.73 can be passed to
IPv4 address examples:
Address ip_address()
------- ------------
127.0.0.1 {127,0,0,1}
192.168.42.2 {192,168,42,2}
IPv6 address examples:
Address ip_address()
------- ------------
::1 {0,0,0,0,0,0,0,1}
::192.168.42.2 {0,0,0,0,0,0,(192 bsl 8) bor 168,(42 bsl 8) bor 2}
::FFFF:192.168.42.2
{0,0,0,0,0,16#FFFF,(192 bsl 8) bor 168,(42 bsl 8) bor 2}
3ffe:b80:1f8d:2:204:acff:fe17:bf38
{16#3ffe,16#b80,16#1f8d,16#2,16#204,16#acff,16#fe17,16#bf38}
fe80::204:acff:fe17:bf38
{16#fe80,0,0,0,0,16#204,16#acff,16#fe17,16#bf38}
Function
1> inet:parse_address("192.168.42.2").
{ok,{192,168,42,2}}
2> inet:parse_address("::FFFF:192.168.42.2").
{ok,{0,0,0,0,0,65535,49320,10754}}
The record is defined in the Kernel include file
Add the following directive to the module:
-include_lib("kernel/include/inet.hrl").
A general address format on the form
This address format is for now experimental
and for completeness to make all address families have a
This address format is for now experimental
and for completeness to make all address families have a
This address family only works on Unix-like systems.
A
Other addresses are possible, for example Linux implements
"Abstract Addresses". See the documentation for
Unix Domain Sockets on your system,
normally
In most API functions where you can use
this address family the port number must be
Addresses besides
Ancillary data received with the data packet,
read with the socket option
The value(s) correspond to the currently active socket
Interface address description list returned from
The tuples
Do not rely too much on the order
of
A
Immediately after
Immediately thereafter may
Any
The tuple
On Windows, the data is fetched from different
OS API functions, so the
An atom that is named from the POSIX error codes used in Unix,
and in the runtime libraries of most C compilers. See section
See
Closes a socket of any type.
Returns a diagnostic error string. For possible POSIX values and
corresponding strings, see section
Returns the state of the
Only actual parameters with other than default values are returned, for example not directives that specify other sources for configuration parameters nor directives that clear parameters.
Returns the IP address for
Returns a list of all IP addresses for
Returns a
Returns a
If resolver option
Returns a
Returns the local hostname. Never fails.
Returns a list of 2-tuples containing interface names and
the interfaces' addresses.
The interface address description tuples
are documented under the type of the
The same as
See the socket option
Gets one or more options for a socket. For a list of available
options, see
The number of elements in the returned
A raw option request
Asking for and inspecting raw socket options require low-level information about the current operating system and TCP stack.
Example:
Consider a Linux machine where option
By inspecting the headers or writing a small C program, it is found
that
{ok,[{raw,_,_,Info}]} = inet:getopts(Sock,[{raw,6,11,92}]),
<<_:28/binary,TcpiSacked:32/native,_/binary>> = Info,
TcpiSacked.]]>
Preferably, you would check the machine type, the operating system, and the Kernel version before executing anything similar to this code.
Gets one or more statistic options for a socket.
The following options are available:
Average size of packets, in bytes, received by the socket.
Number of packets received by the socket.
Average packet size deviation, in bytes, received by the socket.
Size of the largest packet, in bytes, received by the socket.
Number of bytes received by the socket.
Average size of packets, in bytes, sent from the socket.
Number of packets sent from the socket.
Average packet size deviation, in bytes, sent from the socket.
Size of the largest packet, in bytes, sent from the socket.
Number of bytes sent from the socket.
Lists all TCP, UDP and SCTP sockets, including those that the Erlang runtime system uses as well as those created by the application.
The following options are available:
The internal index of the port.
The callback module of the socket.
Number of bytes received by the socket.
Number of bytes sent from the socket.
The socket owner process.
The local address of the socket.
The address and port of the other end of the connection.
The connection state.
STREAM or DGRAM or SEQPACKET.
Parses an
Parses an IPv4 or IPv6 address string and returns an
Parses an IPv4 address string and returns an
Parses an IPv4 address string containing four fields, that is,
not shortened, and returns an
Parses an IPv6 address string and returns an
Parses an IPv6 address string and returns an
Convert an IPv4 address to an IPv4-mapped IPv6 address or the reverse. When converting from an IPv6 address all but the 2 low words are ignored so this function also works on some other types of addresses than IPv4-mapped.
Parses an IPv4 or IPv6 address string and returns an
Returns the address and port for the other end of a connection.
Notice that for SCTP sockets, this function returns only
one of the peer addresses of the socket. Function
Equivalent to
Notice that the behavior of this function for an SCTP
one-to-many style socket is not defined by the
Returns a list of all address/port number pairs for the other end
of an association
This function can return multiple addresses for multihomed sockets, such as SCTP sockets. For other sockets it returns a one-element list.
Notice that parameter
Returns the local port number for a socket.
Sets one or more options for a socket.
The following options are available:
If the value is
If the value is
If the value is
If the value is an integer
When using
Notice that
Use active mode only if
your high-level protocol provides its own flow control
(for example, acknowledging received messages) or the
amount of data exchanged is small.
Enables/disables permission to send broadcasts.
The size of the user-level buffer used by
the driver. Not to be confused with options
Note that this is also the maximum amount of data that can be received from a single recv call. If you are using higher than normal MTU consider setting buffer higher.
Normally, when an Erlang process sends to a socket,
the driver tries to send the data immediately. If that
fails, the driver uses any means available to queue
up the message to be sent whenever the operating system
says it can handle it. Setting
When
Enables/disables routing bypass for outgoing messages.
This option is set to
The only reason to set it to
This option is only meaningful if option
The socket message queue is set to a busy state when the amount of data on the message queue reaches this limit. Notice that this limit only concerns data that has not yet reached the ERTS internal socket implementation. Defaults to 8 kB.
Senders of data to the socket are suspended if either the socket message queue is busy or the socket itself is busy.
For more information, see options
Notice that distribution sockets disable the use of
The socket is set to a busy state when the amount of data queued internally by the ERTS socket implementation reaches this limit. Defaults to 8 kB.
Senders of data to the socket are suspended if either the socket message queue is busy or the socket itself is busy.
For more information, see options
Restricts the socket to use only IPv6, prohibiting any
IPv4 connections. This is only applicable for
IPv6 sockets (option
On most platforms this option must be set on the socket
before associating it to an address. It is therefore only
reasonable to specify it when creating the socket and not
to use it when calling function
(
The behavior of a socket with this option set to
On some platforms, the only allowed value for this option
is
Setting this option on platforms where it does not exist
is ignored. Getting this option with
Therefore, setting this option to
If you read back the option value using
Enables/disables periodic transmission on a connected
socket when no other data is exchanged. If
the other end does not respond, the connection is
considered broken and an error message is sent to
the controlling process. Defaults to
Determines the time-out, in seconds, for flushing unsent data
in the
The first component is if linger is enabled, the second component is the flushing time-out, in seconds. There are 3 alternatives:
close/1 or shutdown/2 returns immediately, not waiting for data to be flushed, with closing happening in the background.
Aborts the connection when it is closed. Discards any data still remaining in the send buffers and sends RST to the peer.
This avoids TCP's TIME_WAIT state, but leaves open the possibility that another "incarnation" of this connection being created.
close/1 or shutdown/2 will not return until all queued messages for the socket have been successfully sent or the linger timeout (Time) has been reached.
If the socket message queue is in a busy state, the socket message queue is set in a not busy state when the amount of data queued in the message queue falls below this limit. Notice that this limit only concerns data that has not yet reached the ERTS internal socket implementation. Defaults to 4 kB.
Senders that are suspended because of either a busy message queue or a busy socket are resumed when the socket message queue and the socket are not busy.
For more information, see options
Notice that distribution sockets disable the use of
If the socket is in a busy state, the socket is set in a not busy state when the amount of data queued internally by the ERTS socket implementation falls below this limit. Defaults to 4 kB.
Senders that are suspended because of a busy message queue or a busy socket are resumed when the socket message queue and the socket are not busy.
For more information, see options
Received
Sets a network namespace for the socket. Parameter
This option uses the Linux-specific syscall
The virtual machine also needs elevated privileges, either
running as superuser or (for Linux) having capability
Example:
setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp
Notice that the filesystem containing the virtual machine
executable (
Emulator flag
Binds a socket to a specific network interface. This option
must be used in a function call that creates a socket, that is,
Unlike
This option uses the Linux-specific socket option
Before Linux 3.8, this socket option could be set, but could not retrieved
with
The virtual machine also needs elevated privileges, either
running as superuser or (for Linux) having capability
The primary use case for this option is to bind sockets into
Received
Received
If
This translates to
If
Note that while
No packaging is done.
Packets consist of a header specifying the number of bytes in the packet, followed by that number of bytes. The header length can be one, two, or four bytes, and containing an unsigned integer in big-endian byte order. Each send operation generates the header, and the header is stripped off on each receive operation.
The 4-byte header is limited to 2Gb.
These packet types only have effect on receiving.
When sending a packet, it is the responsibility of
the application to supply a correct header. On
receiving, however, one message is sent to
the controlling process for each complete packet
received, and, similarly, each call to
The meanings of the packet types are as follows:
The Hypertext Transfer Protocol. The packets
are returned with the format according to
These two types are often not needed, as the socket
automatically switches from
Sets the maximum allowed length of the packet body. If the packet header indicates that the length of the packet is longer than the maximum allowed length, the packet is considered invalid. The same occurs if the packet header is too large for the socket receive buffer.
For line-oriented protocols (
Sets the line delimiting character for line-oriented protocols
(
See below.
Sets the maximum number of UDP packets to read without
intervention from the socket when data is available.
When this many packets have been read and delivered
to the destination process, new packets are not read
until a new notification of available data has arrived.
Defaults to
The minimum size of the receive buffer to use for
the socket. You are encouraged to use
If set to
For packet oriented sockets that supports receiving
ancillary data with the payload data
(
If set to
For packet oriented sockets that supports receiving
ancillary data with the payload data
(
If set to
For packet oriented sockets that supports receiving
ancillary data with the payload data
(
Allows or disallows local reuse of port numbers. By default, reuse is disallowed.
Only allowed for connection-oriented sockets.
Specifies a longest time to wait for a send operation to
be accepted by the underlying TCP stack. When the limit is
exceeded, the send operation returns
Only allowed for connection-oriented sockets.
Used together with
When this option is set to
Setting this option to
A connected socket returned from
The minimum size of the send buffer to use for the socket.
You are encouraged to use
Sets the
Sets
Sets
In addition to these options, raw
option specifications can be used. The raw options are
specified as a tuple of arity four, beginning with tag
Using raw socket options requires detailed knowledge about the current operating system and TCP stack.
Example:
This example concerns the use of raw options. Consider a Linux
system where you want to set option
>}]),]]>
As many options are silently discarded by the stack if they
are specified out of range; it can be a good idea to check that
a raw option is accepted. The following code places the value
in variable
>}]}=inet:getopts(Sock,[{raw,6,8,4}]),]]>
Code such as these examples is inherently non-portable, even different versions of the same OS on the same platform can respond differently to this kind of option manipulation. Use with care.
Notice that the default options for TCP/IP sockets can be changed with the Kernel configuration parameters mentioned in the beginning of this manual page.
Returns the local address and port number for a socket.
Notice that for SCTP sockets this function returns only
one of the socket addresses. Function
Equivalent to
Returns a list of all local address/port number pairs for a socket
for the specified association
This function can return multiple addresses for multihomed sockets, such as SCTP sockets. For other sockets it returns a one-element list.
Notice that parameter