inet(3)

MODULE
inet - Access to TCP/IP protocols.

DESCRIPTION

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:
        List of addresses for this host

    h_addrtype:
        Type of address: inet or inet6

    h_aliases:
        List of aliases (additional names for host)

    h_length:
        Length of address in bytes

    h_name:
        Official name for host

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 \n          '[{delay_send,true}]' \n          -kernel inet_default_listen_options \n          '[{delay_send,true}]'

Note that the default {active, true} currently cannot be changed with these application variables, for internal reasons.

EXPORTS

get_rc()

    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.

format_error(Tag)

    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.

port(Socket) -> {ok, Number}

    Types
        Socket = socket()
        Number = integer()

    Returns the local port number for a socket.

close(Socket) -> ok

    Types
        Socket = socket()

    Closes a socket of any type.

getaddr(IP,inet) -> {ok,{A1,A2,A3,A4}} | {error, Reason}

    Types
        IP = {A1, A2, A3, A4} | string() | atom()
        A1 = A2 = A3 = A4 = integer()
        Reason = term()

    Returns the IP-address as a tuple with integers for IP which can be an IP-address a single hostname or a fully qualified hostname. At present only IPv4 adresses (the inet argument) is supported, but the function is prepared to support IPv6 (inet6) in a near future.

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}:
            If the active option is 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}:
            Enable/disable permission to send broadcasts. (UDP)

        {delay_send, Boolean}:
            Normally, when an erlang process sends to a socket, the driver will try to immediately send the data. If that fails, the driver will use any means available to que up the message to be sent whenever the operating system says it can handle it. Setting {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}:
            Use {dontroute, true} to enable/disable routing bypass for outgoing messages.

        {exit_on_close, Boolean}:
            By default this option is set to 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}:
            This option is only meaningful if the 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}:
            (TCP/IP sockets) Enables periodic transmission on a connected socket, when no other data is being exchanged. If the other end does not respond, the connection is considered broken and an error message will be sent to the controlling process. Default disabled.

        {nodelay, Boolean}:
            If Boolean is 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}:
            (TCP/IP sockets) Defines the type of packets to use for a socket. The following values are valid:

                raw | 0:
                    No packaging is done.

                1 | 2 | 4:
                    Packets consist of a header specifying the number of bytes in the packet, followed by that number of bytes. The length of header can be one, two, or four bytes; the order of the bytes is big-endian. Each send operation will generate the header, and the header will be stripped off on each receive operation.

                asn1 | cdr | sunrm | fcgi | tpkt | line:
                    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, there will be one message sent to the controlling process for each complete packet received, and, similarly, each call to 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}:
            (TCP/IP sockets) Sets the max allowed length of the packet body. If the packet header indicates that the length of the packet is longer than the max allowed length, the packet is considered invalid. The same happens if the packet header is too big for the socket receive buffer.

        {recbuf, Integer}:
            Gives the size of the receive buffer to use for the socket.

        {reuseaddr, Boolean}:
            Allows or disallows local reuse of port numbers. By default, reuse is disallowed.

        {sndbuf, Integer}:
            Gives the size of the send buffer to use for the socket.

    Please note that the default options for TCP sockets can be changed with the kernel application variables mentioned in the beginning of this document.

ERRORS

The possible error reasons and the corresponding diagnostic strings returned by format_error/1 are as follows:

    :

    e2big:
        argument list too long

    eacces:
        permission denied

    eaddrinuse:
        address already in use

    eaddrnotavail:
        cannot assign requested address

    eadv:
        advertise error

    eafnosupport:
        address family not supported by protocol family

    eagain:
        resource temporarily unavailable

    ealign:
        EALIGN

    ealready:
        operation already in progress

    ebade:
        bad exchange descriptor

    ebadf:
        bad file number

    ebadfd:
        file descriptor in bad state

    ebadmsg:
        not a data message

    ebadr:
        bad request descriptor

    ebadrpc:
        RPC structure is bad

    ebadrqc:
        bad request code

    ebadslt:
        invalid slot

    ebfont:
        bad font file format

    ebusy:
        file busy

    echild:
        no children

    echrng:
        channel number out of range

    ecomm:
        communication error on send

    econnaborted:
        software caused connection abort

    econnrefused:
        connection refused

    econnreset:
        connection reset by peer

    edeadlk:
        resource deadlock avoided

    edeadlock:
        resource deadlock avoided

    edestaddrreq:
        destination address required

    edirty:
        mounting a dirty fs w/o force

    edom:
        math argument out of range

    edotdot:
        cross mount point

    edquot:
        disk quota exceeded

    eduppkg:
        duplicate package name

    eexist:
        file already exists

    efault:
        bad address in system call argument

    efbig:
        file too large

    ehostdown:
        host is down

    ehostunreach:
        host is unreachable

    eidrm:
        identifier removed

    einit:
        initialization error

    einprogress:
        operation now in progress

    eintr:
        interrupted system call

    einval:
        invalid argument

    eio:
        I/O error

    eisconn:
        socket is already connected

    eisdir:
        illegal operation on a directory

    eisnam:
        is a named file

    el2hlt:
        level 2 halted

    el2nsync:
        level 2 not synchronized

    el3hlt:
        level 3 halted

    el3rst:
        level 3 reset

    elbin:
        ELBIN

    elibacc:
        cannot access a needed shared library

    elibbad:
        accessing a corrupted shared library

    elibexec:
        cannot exec a shared library directly

    elibmax:
        attempting to link in more shared libraries than system limit

    elibscn:
        .lib section in a.out corrupted

    elnrng:
        link number out of range

    eloop:
        too many levels of symbolic links

    emfile:
        too many open files

    emlink:
        too many links

    emsgsize:
        message too long

    emultihop:
        multihop attempted

    enametoolong:
        file name too long

    enavail:
        not available

    enet:
        ENET

    enetdown:
        network is down

    enetreset:
        network dropped connection on reset

    enetunreach:
        network is unreachable

    enfile:
        file table overflow

    enoano:
        anode table overflow

    enobufs:
        no buffer space available

    enocsi:
        no CSI structure available

    enodata:
        no data available

    enodev:
        no such device

    enoent:
        no such file or directory

    enoexec:
        exec format error

    enolck:
        no locks available

    enolink:
        link has be severed

    enomem:
        not enough memory

    enomsg:
        no message of desired type

    enonet:
        machine is not on the network

    enopkg:
        package not installed

    enoprotoopt:
        bad proocol option

    enospc:
        no space left on device

    enosr:
        out of stream resources or not a stream device

    enosym:
        unresolved symbol name

    enosys:
        function not implemented

    enotblk:
        block device required

    enotconn:
        socket is not connected

    enotdir:
        not a directory

    enotempty:
        directory not empty

    enotnam:
        not a named file

    enotsock:
        socket operation on non-socket

    enotsup:
        operation not supported

    enotty:
        inappropriate device for ioctl

    enotuniq:
        name not unique on network

    enxio:
        no such device or address

    eopnotsupp:
        operation not supported on socket

    eperm:
        not owner

    epfnosupport:
        protocol family not supported

    epipe:
        broken pipe

    eproclim:
        too many processes

    eprocunavail:
        bad procedure for program

    eprogmismatch:
        program version wrong

    eprogunavail:
        RPC program not available

    eproto:
        protocol error

    eprotonosupport:
        protocol not supported

    eprototype:
        protocol wrong type for socket

    erange:
        math result unrepresentable

    erefused:
        EREFUSED

    eremchg:
        remote address changed

    eremdev:
        remote device

    eremote:
        pathname hit remote file system

    eremoteio:
        remote i/o error

    eremoterelease:
        EREMOTERELEASE

    erofs:
        read-only file system

    erpcmismatch:
        RPC version is wrong

    erremote:
        object is remote

    eshutdown:
        cannot send after socket shutdown

    esocktnosupport:
        socket type not supported

    espipe:
        invalid seek

    esrch:
        no such process

    esrmnt:
        srmount error

    estale:
        stale remote file handle

    esuccess:
        Error 0

    etime:
        timer expired

    etimedout:
        connection timed out

    etoomanyrefs:
        too many references

    etxtbsy:
        text file or pseudo-device busy

    euclean:
        structure needs cleaning

    eunatch:
        protocol driver not attached

    eusers:
        too many users

    eversion:
        version mismatch

    ewouldblock:
        operation would block

    exdev:
        cross-domain link

    exfull:
        message tables full

    nxdomain:
        the hostname or domain name could not be found

AUTHOR
tony@erix.ericsson.se - support@erlang.ericsson.se