aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/inet.xml
diff options
context:
space:
mode:
authorHans Bolinder <[email protected]>2011-05-06 16:01:56 +0200
committerHans Bolinder <[email protected]>2011-05-11 14:20:58 +0200
commit5a485461a1157fef1bb3ce8426bfd1ad57b5ca52 (patch)
treed77f79b9a1b98e7bf2bf3886ebec61d504317fc4 /lib/kernel/doc/src/inet.xml
parent68fe6a14539b82250373ef114d6576e74e1b8f2e (diff)
downloadotp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.tar.gz
otp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.tar.bz2
otp-5a485461a1157fef1bb3ce8426bfd1ad57b5ca52.zip
Use Erlang specs and types for documentation
Diffstat (limited to 'lib/kernel/doc/src/inet.xml')
-rw-r--r--lib/kernel/doc/src/inet.xml193
1 files changed, 75 insertions, 118 deletions
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
index f05a224f33..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>2010</year>
+ <year>1997</year><year>2011</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -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,116 +142,74 @@ 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>getifaddrs() -> {ok,Iflist} | {error,posix}</name>
+ <name name="getifaddrs" arity="0"/>
<fsummary>Return a list of interfaces and their addresses</fsummary>
- <type>
- <v>Iflist = {Ifname,[Ifopt]}</v>
- <v>Ifname = string()</v>
- <v>Ifopt = {flag,[Flag]} | {addr,Addr} | {netmask,Netmask}
- | {broadaddr,Broadaddr} | {dstaddr,Dstaddr}
- | {hwaddr,Hwaddr}</v>
- <v>Flag = up | broadcast | loopback | pointtopoint
- | running | multicast</v>
- <v>Addr = Netmask = Broadadddr = Dstaddr = ip_address()</v>
- <v>Hwaddr = [byte()]</v>
- </type>
- </func>
<desc>
<p>
Returns a list of 2-tuples containing interface names and the
- interface's addresses. <c>Ifname</c> is a Unicode string.
- <c>Hwaddr</c> is hardware dependent, e.g on Ethernet interfaces
+ 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,Addr}</c>, <c>{netmask,_}</c> and <c>{broadaddr,_}</c>
+ 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
@@ -252,8 +217,8 @@ fe80::204:acff:fe17:bf38
The <c>{flag,_}</c> tuple is mandatory, all other optional.
</p>
<p>
- Do not rely too much on the order of <c>Flag</c> atoms or
- <c>Ifopt</c> tuples. There are some rules, though:
+ 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>
@@ -261,7 +226,7 @@ fe80::204:acff:fe17:bf38
<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.
+ <c>pointtopoint</c> flag <em>is</em> set.
</item>
<item>
Any <c>{netmask,_}</c>, <c>{broadaddr,_}</c> or
@@ -277,11 +242,12 @@ fe80::204:acff:fe17:bf38
</p>
<p>
On Windows, the data is fetched from quite different OS API
- functions, so the <c>Netmask</c> and <c>Broadaddr</c>
- values may be calculated, just as some <c>Flag</c> values.
+ 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) -> {ok, OptionValues} | {error, posix()}</name>
@@ -291,13 +257,14 @@ fe80::204:acff:fe17:bf38
<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>
@@ -419,13 +386,8 @@ 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>
@@ -436,20 +398,15 @@ fe80::204:acff:fe17:bf38
<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>
@@ -460,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>&nbsp;Opt, Val -- see below</v>
</type>