Inet provides access to TCP/IP protocols.
Some functions returns a hostent
record.
Use this line in your module
-include_lib("kernel/include/inet.hrl").
to include the record definition.
h_addr_list
h_addrtype
inet
or inet6
h_aliases
h_length
h_name
Addresses as inputs to functions can be either a string or
a tuple.
For instance, the IP address 150.236.20.73 can be passed to
gethostbyaddr/1
either as the string "150.236.20.73"
or as the tuple {150, 236, 20, 73}
.
Addresses returned by any function in the inet
module
will be a tuple.
Hostnames may be specified as either atoms or a strings.
Where an address family is required, valid values are
inet
(standard IPv4 addresses) or inet6
(IPv6).
Two kernel application variables affect the behaviour of all
sockets opened on an erlang node. The kernel application
variable inet_default_connect_options
can contain a list
of default options used for all sockets returned when doing
connect
and inet_default_listen_options
can
contain a list of default options used when issuing a
listen
call. When accept is issued, the values of the
listensocket options are inherited, why no such application
variable is needed for accept
.
Using the kernel application variables mentioned above, one can
set default options for all TCP sockets on a node. This should
be used with care, but options like {delay_send,true}
might be specified in this way. An example of starting an
erlang node with all sockets using delay send would look like
this:
$ erl -sname test -kernel inet_default_connect_options \ '[{delay_send,true}]' \ -kernel inet_default_listen_options \ '[{delay_send,true}]'
Note that the default {active,true}
currently cannot be changed
with these application variables, for internal reasons.
Returns the state of the inet configuration database in form of a list of recorded configuration parameters. (See the ERTS User's Guide for more information). Only parameters with other than default values are returned.
Types:
Tag = atom()
Returns a diagnostic error string. See the section below
for possible Tag
values and the corresponding strings.
gethostbyaddr(Address) -> {ok, Hostent} | {error, Reason}
Types:
Address = address()
Hostent = hostent()
Returns a hostent
record given an address.
gethostbyname(Name) -> {ok, Hostent} | {error, Reason}
Types:
Hostname = hostname()
Hostent = hostent()
Returns a hostent
record given a hostname.
gethostbyname(Name, Family) -> {ok, Hostent} | {error, Reason}
Types:
Hostname = hostname()
Family = family()
Hostent = hostent()
Returns a hostent
record given a hostname, restricted to the
given address family.
gethostname() -> {ok, Name} | {error, Reason}
Types:
Hostname = hostname()
Returns the local hostname. Will never fail.
sockname(Socket) -> {ok, {IP, Port}} | {error, Reason}
Types:
Socket = socket()
Address = address()
Port = integer()
Returns the local address and port number for a socket.
peername(Socket) -> {ok, {Address, Port}} | {error, Reason}
Types:
Socket = socket()
Address = address()
Port = integer()
Returns the address and port for the other end of a connection.
Types:
Socket = socket()
Number = integer()
Returns the local port number for a socket.
Types:
Socket = socket()
Closes a socket of any type.
getaddr(Host, Family) -> {ok, {A1,A2,A3,A4}} | {error, Reason}
Types:
Host = {A1,A2,A3,A4} | string() | atom()
A1 = A2 = A3 = A4 = integer()
Family = family()
Reason = term()
Returns the IP-address for Host
as a tuple of integers.
Host
can be an IP-address, a single hostname or a fully
qualified hostname.
getaddrs(Host, Family) -> {ok, IPs} | {error, Reason}
Types:
Host = {A1,A2,A3,A4} | string() | atom()
IPs = [{A1,A2,A3,A4} | ...]
A1 = A2 = A3 = A4 = integer()
Family = family()
Reason = term()
Returns a list of all IP-addresses for Host
. Host
can
be an IP-adress, a single hostname or a fully qualified hostname.
setopts(Socket, Options) -> ok | {error, Reason}
Types:
Socket = term()
Options = list()
Sets one or more options for a socket. The following options are available:
{active, Boolean}
true
, which is the default,
everything received from the socket will be sent as messages
to the receiving process.
If the active option is set to false
(passive mode),
the process must explicitly receive incoming data by calling
gen_tcp:recv/N
or gen_udp:recv/N
(depending on the type of socket).
If the active option is set to once
(active once),
one
data message from the socket will be sent to the
process. To receive one more message, setopts/2
must
be called again with the {active,once}
option.
Note:
Active mode provides no flow control; a fast sender could
easily overflow the receiver with incoming messages.
Use active mode only if your high-level protocol provides
its own flow control (for instance, acknowledging received
messages) or the amount of data exchanged is small.
Passive mode or active-once mode provides flow control;
the other side will not be able send faster than the receiver
can read.
{broadcast, Boolean}
{delay_send, Boolean}
{delay_send, true}
will make
all messages que up. This makes the messages
actually sent onto the network be larger but fewer. The
option actually affects the scheduling of send requests
versus Erlang processes instead of changing any real
property of the socket. Needless to say it is an
implementation specific option. Default is false
.
{dontroute, Boolean}
{dontroute, true}
to enable/disable routing bypass for
outgoing messages.
{exit_on_close, Boolean}
true
.
The only reason to set it to false is if you want to continue
sending data to the socket after a close has been detected,
for instance if the peer has used
gen_tcp:shutdown/2
to shutdown the write side.
{header, Size}
binary
option
was specified when the socket was created.
If the header
option is specified, the first Size number bytes of
data received from the socket will be elements of a list, and the rest of the
data will be a binary given as the tail of the same list. If for example
Size
=2 the data received will match [Byte1,Byte2|Binary]
.
{keepalive, Boolean}
{nodelay, Boolean}
true
, the TCP_NODELAY
option is
turned on for the socket, which means that even small amounts of
data will be sent immediately. (TCP/IP sockets)
{packet, PacketType}
raw | 0
1 | 2 | 4
asn1 | cdr | sunrm | fcgi | tpkt | line
gen_tcp:recv/N
returns
one complete packet.
The header is not stripped off.
The meanings of the packet types are as follows:
asn1
- ASN.1 BER,
sunrm
- Sun's RPC encoding,
cdr
- CORBA (GIOP 1.1),
fcgi
- Fast CGI,
tpkt
- TPKT format [RFC1006],
line
- Line mode, a packet is a line
terminated with newline, lines longer than the
receive buffer are truncated.
{packet_size, Integer}
{recbuf, Integer}
{reuseaddr, Boolean}
{sndbuf, Integer}
Please note that the default options for TCP sockets can be changed with the kernel application variables mentioned in the beginning of this document.
The possible error reasons and the corresponding diagnostic strings
returned by format_error/1
are as follows:
e2big
eacces
eaddrinuse
eaddrnotavail
eadv
eafnosupport
eagain
ealign
ealready
ebade
ebadf
ebadfd
ebadmsg
ebadr
ebadrpc
ebadrqc
ebadslt
ebfont
ebusy
echild
echrng
ecomm
econnaborted
econnrefused
econnreset
edeadlk
edeadlock
edestaddrreq
edirty
edom
edotdot
edquot
eduppkg
eexist
efault
efbig
ehostdown
ehostunreach
eidrm
einit
einprogress
eintr
einval
eio
eisconn
eisdir
eisnam
el2hlt
el2nsync
el3hlt
el3rst
elbin
elibacc
elibbad
elibexec
elibmax
elibscn
elnrng
eloop
emfile
emlink
emsgsize
emultihop
enametoolong
enavail
enet
enetdown
enetreset
enetunreach
enfile
enoano
enobufs
enocsi
enodata
enodev
enoent
enoexec
enolck
enolink
enomem
enomsg
enonet
enopkg
enoprotoopt
enospc
enosr
enosym
enosys
enotblk
enotconn
enotdir
enotempty
enotnam
enotsock
enotsup
enotty
enotuniq
enxio
eopnotsupp
eperm
epfnosupport
epipe
eproclim
eprocunavail
eprogmismatch
eprogunavail
eproto
eprotonosupport
eprototype
erange
erefused
eremchg
eremdev
eremote
eremoteio
eremoterelease
erofs
erpcmismatch
erremote
eshutdown
esocktnosupport
espipe
esrch
esrmnt
estale
esuccess
etime
etimedout
etoomanyrefs
etxtbsy
euclean
eunatch
eusers
eversion
ewouldblock
exdev
exfull
nxdomain