diff options
Diffstat (limited to 'lib/kernel/doc/src/inet.xml')
| -rw-r--r-- | lib/kernel/doc/src/inet.xml | 222 |
1 files changed, 121 insertions, 101 deletions
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml index f502b30c8d..fd843b00d9 100644 --- a/lib/kernel/doc/src/inet.xml +++ b/lib/kernel/doc/src/inet.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2009</year> + <year>1997</year><year>2011</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -13,12 +13,12 @@ compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. - + Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. - + </legalnotice> <title>inet</title> @@ -54,33 +54,6 @@ $ <input>erl -sname test -kernel \</input> <input>inet_default_listen_options '[{delay_send,true}]'</input></pre> <p>Note that the default option <c>{active, true}</c> currently cannot be changed, for internal reasons.</p> - </description> - - <section> - <title>DATA TYPES</title> - <code type="none"> -#hostent{h_addr_list = [ip_address()] % list of addresses for this host - h_addrtype = inet | inet6 - h_aliases = [hostname()] % list of aliases - h_length = int() % length of address in bytes - h_name = hostname() % official name for host - The record is defined in the Kernel include file "inet.hrl" - Add the following directive to the module: - -include_lib("kernel/include/inet.hrl"). - -hostname() = atom() | string() - -ip_address() = {N1,N2,N3,N4} % IPv4 - | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6 - Ni = 0..255 - Ki = 0..65535 - -posix() - an atom which is named from the Posix error codes used in - Unix, and in the runtime libraries of most C compilers - -socket() - see gen_tcp(3), gen_udp(3)</code> <p>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 <c>gethostbyaddr/1</c> either as the string "150.236.20.73" @@ -109,24 +82,58 @@ fe80::204:acff:fe17:bf38 {ok,{192,168,42,2}} 2> <input>inet_parse:address("FFFF::192.168.42.2").</input> {ok,{65535,0,0,0,0,0,49320,10754}}</pre> - </section> + </description> + + <datatypes> + <datatype> + <name name="hostent"/> + <desc> + <p>The record is defined in the Kernel include file "inet.hrl". + Add the following directive to the module:</p> +<code>-include_lib("kernel/include/inet.hrl").</code></desc> + </datatype> + <datatype> + <name name="hostname"/> + </datatype> + <datatype> + <name name="ip_address"/> + </datatype> + <datatype> + <name name="ip4_address"/> + </datatype> + <datatype> + <name name="ip6_address"/> + </datatype> + <datatype> + <name name="posix"/> + <desc><p>An atom which is named from the Posix error codes + used in Unix, and in the runtime libraries of most + C compilers. See + <seealso marker="#error_codes">POSIX Error Codes</seealso>.</p> + </desc> + </datatype> + <datatype> + <name><marker id="type-socket">socket()</marker></name> + <desc><p>See <seealso marker="gen_tcp#type-socket">gen_tcp(3)</seealso> + and <seealso marker="gen_udp#type-socket">gen_udp(3)</seealso>.</p> + </desc> + </datatype> + <datatype> + <name name="family_option"/> + </datatype> + </datatypes> + <funcs> <func> - <name>close(Socket) -> ok</name> + <name name="close" arity="1"/> <fsummary>Close a socket of any type</fsummary> - <type> - <v>Socket = socket()</v> - </type> <desc> <p>Closes a socket of any type.</p> </desc> </func> <func> - <name>get_rc() -> [{Par, Val}]</name> + <name name="get_rc" arity="0"/> <fsummary>Return a list of IP configuration parameters</fsummary> - <type> - <v>Par, Val -- see below</v> - </type> <desc> <p>Returns the state of the Inet configuration database in form of a list of recorded configuration parameters. (See the @@ -135,106 +142,129 @@ fe80::204:acff:fe17:bf38 </desc> </func> <func> - <name>format_error(Posix) -> string()</name> + <name name="format_error" arity="1"/> <fsummary>Return a descriptive string for an error reason</fsummary> - <type> - <v>Posix = posix()</v> - </type> <desc> <p>Returns a diagnostic error string. See the section below - for possible <c>Posix</c> values and the corresponding + for possible <c><anno>Posix</anno></c> values and the corresponding strings.</p> </desc> </func> <func> - <name>getaddr(Host, Family) -> {ok, Address} | {error, posix()}</name> + <name name="getaddr" arity="2"/> <fsummary>Return the IP-address for a host</fsummary> - <type> - <v>Host = ip_address() | string() | atom()</v> - <v>Family = inet | inet6</v> - <v>Address = ip_address()</v> - <v>posix() = term()</v> - </type> <desc> - <p>Returns the IP-address for <c>Host</c> as a tuple of - integers. <c>Host</c> can be an IP-address, a single hostname + <p>Returns the IP-address for <c><anno>Host</anno></c> as a tuple of + integers. <c><anno>Host</anno></c> can be an IP-address, a single hostname or a fully qualified hostname.</p> </desc> </func> <func> - <name>getaddrs(Host, Family) -> {ok, Addresses} | {error, posix()}</name> + <name name="getaddrs" arity="2"/> <fsummary>Return the IP-addresses for a host</fsummary> - <type> - <v>Host = ip_address() | string() | atom()</v> - <v>Addresses = [ip_address()]</v> - <v>Family = inet | inet6</v> - </type> <desc> - <p>Returns a list of all IP-addresses for <c>Host</c>. - <c>Host</c> can be an IP-address, a single hostname or a fully + <p>Returns a list of all IP-addresses for <c><anno>Host</anno></c>. + <c><anno>Host</anno></c> can be an IP-address, a single hostname or a fully qualified hostname.</p> </desc> </func> <func> - <name>gethostbyaddr(Address) -> {ok, Hostent} | {error, posix()}</name> + <name name="gethostbyaddr" arity="1"/> <fsummary>Return a hostent record for the host with the given address</fsummary> - <type> - <v>Address = string() | ip_address()</v> - <v>Hostent = #hostent{}</v> - </type> <desc> <p>Returns a <c>hostent</c> record given an address.</p> </desc> </func> <func> - <name>gethostbyname(Name) -> {ok, Hostent} | {error, posix()}</name> + <name name="gethostbyname" arity="1"/> <fsummary>Return a hostent record for the host with the given name</fsummary> - <type> - <v>Hostname = hostname()</v> - <v>Hostent = #hostent{}</v> - </type> <desc> <p>Returns a <c>hostent</c> record given a hostname.</p> </desc> </func> <func> - <name>gethostbyname(Name, Family) -> {ok, Hostent} | {error, posix()}</name> + <name name="gethostbyname" arity="2"/> <fsummary>Return a hostent record for the host with the given name</fsummary> - <type> - <v>Hostname = hostname()</v> - <v>Family = inet | inet6</v> - <v>Hostent = #hostent{}</v> - </type> <desc> <p>Returns a <c>hostent</c> record given a hostname, restricted to the given address family.</p> </desc> </func> <func> - <name>gethostname() -> {ok, Hostname}</name> + <name name="gethostname" arity="0"/> <fsummary>Return the local hostname</fsummary> - <type> - <v>Hostname = string()</v> - </type> <desc> <p>Returns the local hostname. Will never fail.</p> </desc> </func> + + <func> + <name name="getifaddrs" arity="0"/> + <fsummary>Return a list of interfaces and their addresses</fsummary> + <desc> + <p> + Returns a list of 2-tuples containing interface names and the + interface's addresses. <c><anno>Ifname</anno></c> is a Unicode string. + <c><anno>Hwaddr</anno></c> is hardware dependent, e.g on Ethernet interfaces + it is the 6-byte Ethernet address (MAC address (EUI-48 address)). + </p> + <p> + The <c>{addr,<anno>Addr</anno>}</c>, <c>{netmask,_}</c> and <c>{broadaddr,_}</c> + tuples are repeated in the result list iff the interface has multiple + addresses. If you come across an interface that has + multiple <c>{flag,_}</c> or <c>{hwaddr,_}</c> tuples you have + a really strange interface or possibly a bug in this function. + The <c>{flag,_}</c> tuple is mandatory, all other optional. + </p> + <p> + Do not rely too much on the order of <c><anno>Flag</anno></c> atoms or + <c><anno>Ifopt</anno></c> tuples. There are some rules, though: + <list> + <item> + Immediately after <c>{addr,_}</c> follows <c>{netmask,_}</c> + </item> + <item> + Immediately thereafter follows <c>{broadaddr,_}</c> if + the <c>broadcast</c> flag is <em>not</em> set and the + <c>pointtopoint</c> flag <em>is</em> set. + </item> + <item> + Any <c>{netmask,_}</c>, <c>{broadaddr,_}</c> or + <c>{dstaddr,_}</c> tuples that follow an <c>{addr,_}</c> + tuple concerns that address. + </item> + </list> + </p> + <p> + The <c>{hwaddr,_}</c> tuple is not returned on Solaris since the + hardware address historically belongs to the link layer and only + the superuser can read such addresses. + </p> + <p> + On Windows, the data is fetched from quite different OS API + functions, so the <c><anno>Netmask</anno></c> and <c><anno>Broadaddr</anno></c> + values may be calculated, just as some <c><anno>Flag</anno></c> values. + You have been warned. Report flagrant bugs. + </p> + </desc> + </func> + <func> - <name>getopts(Socket, Options) -> OptionValues | {error, posix()}</name> + <name>getopts(Socket, Options) -> {ok, OptionValues} | {error, posix()}</name> <fsummary>Get one or more options for a socket</fsummary> <type> <v>Socket = term()</v> <v>Options = [Opt | RawOptReq]</v> <v>Opt = atom()</v> <v>RawOptReq = {raw, Protocol, OptionNum, ValueSpec}</v> - <v>Protocol = int()</v> - <v>OptionNum = int()</v> + <v>Protocol = integer()</v> + <v>OptionNum = integer()</v> <v>ValueSpec = ValueSize | ValueBin</v> - <v>ValueSize = int()</v> + <v>ValueSize = integer()</v> <v>ValueBin = binary()</v> <v>OptionValues = [{Opt, Val} | {raw, Protocol, OptionNum, ValueBin}]</v> </type> + <type name="socket_getopt"/> <desc> <p>Gets one or more options for a socket. See <seealso marker="#setopts/2">setopts/2</seealso> @@ -356,37 +386,27 @@ fe80::204:acff:fe17:bf38 </func> <func> - <name>peername(Socket) -> {ok, {Address, Port}} | {error, posix()}</name> + <name name="peername" arity="1"/> <fsummary>Return the address and port for the other end of a connection</fsummary> - <type> - <v>Socket = socket()</v> - <v>Address = ip_address()</v> - <v>Port = int()</v> - </type> <desc> <p>Returns the address and port for the other end of a connection.</p> </desc> </func> <func> - <name>port(Socket) -> {ok, Port}</name> + <name>port(Socket) -> {ok, Port} | {error, any()}</name> <fsummary>Return the local port number for a socket</fsummary> <type> <v>Socket = socket()</v> - <v>Port = int()</v> + <v>Port = integer()</v> </type> <desc> <p>Returns the local port number for a socket.</p> </desc> </func> <func> - <name>sockname(Socket) -> {ok, {Address, Port}} | {error, posix()}</name> + <name name="sockname" arity="1"/> <fsummary>Return the local address and port number for a socket</fsummary> - <type> - <v>Socket = socket()</v> - <v>Address = ip_address()</v> - <v>Port = int()</v> - </type> <desc> <p>Returns the local address and port number for a socket.</p> </desc> @@ -397,8 +417,8 @@ fe80::204:acff:fe17:bf38 <type> <v>Socket = term()</v> <v>Options = [{Opt, Val} | {raw, Protocol, Option, ValueBin}]</v> - <v>Protocol = int()</v> - <v>OptionNum = int()</v> + <v>Protocol = integer()</v> + <v>OptionNum = integer()</v> <v>ValueBin = binary()</v> <v> Opt, Val -- see below</v> </type> |