diff options
Diffstat (limited to 'lib/kernel/doc/src/inet.xml')
| -rw-r--r-- | lib/kernel/doc/src/inet.xml | 247 |
1 files changed, 93 insertions, 154 deletions
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml index f05a224f33..fad5af85bb 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,61 @@ 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="port_number"/> + </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="address_family"/> + </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 +145,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 +220,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 +229,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,32 +245,23 @@ 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> + <name name="getopts" arity="2"/> <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>ValueSpec = ValueSize | ValueBin</v> - <v>ValueSize = int()</v> - <v>ValueBin = binary()</v> - <v>OptionValues = [{Opt, Val} | {raw, Protocol, OptionNum, ValueBin}]</v> - </type> + <type name="socket_getopt"/> + <type name="socket_setopt"/> <desc> <p>Gets one or more options for a socket. See <seealso marker="#setopts/2">setopts/2</seealso> for a list of available options.</p> - <p>The number of elements in the returned <c>OptionValues</c> + <p>The number of elements in the returned <c><anno>OptionValues</anno></c> list does not necessarily correspond to the number of options asked for. If the operating system fails to support an option, it is simply left out in the returned list. An error tuple is only @@ -310,12 +269,12 @@ fe80::204:acff:fe17:bf38 (i.e. the socket is closed or the buffer size in a raw request is too large). This behavior is kept for backward compatibility reasons.</p> - <p>A <c>RawOptReq</c> can be used to get information about + <p>A raw option request <c>RawOptReq = {raw, Protocol, OptionNum, ValueSpec}</c> can be used to get information about socket options not (explicitly) supported by the emulator. The use of raw socket options makes the code non portable, but allows the Erlang programmer to take advantage of unusual features present on the current platform.</p> - <p>The <c>RawOptReq</c> consists of the tag <c>raw</c> followed + <p>The <c>RawOptReq</c> consists of the tag <c>raw</c> followed by the protocol level, the option number and either a binary or the size, in bytes, of the buffer in which the option value is to be stored. A binary @@ -358,19 +317,14 @@ fe80::204:acff:fe17:bf38 </func> <func> - <name>getstat(Socket)</name> - <name>getstat(Socket, Options) -> {ok, OptionValues} | {error, posix()}</name> + <name name="getstat" arity="1"/> + <name name="getstat" arity="2"/> <fsummary>Get one or more statistic options for a socket</fsummary> - <type> - <v>Socket = term()</v> - <v>Options = [Opt]</v> - <v>OptionValues = [{Opt, Val}]</v> - <v> Opt, Val -- see below</v> - </type> + <type name="stat_option"/> <desc> <p>Gets one or more statistic options for a socket.</p> - <p><c>getstat(Socket)</c> is equivalent to - <c>getstat(Socket, [recv_avg, recv_cnt, recv_dvi, recv_max, recv_oct, send_avg, send_cnt, send_dvi, send_max, send_oct])</c></p> + <p><c>getstat(<anno>Socket</anno>)</c> is equivalent to + <c>getstat(<anno>Socket</anno>, [recv_avg, recv_cnt, recv_dvi, recv_max, recv_oct, send_avg, send_cnt, send_dvi, send_max, send_oct])</c></p> <p>The following options are available:</p> <taglist> <tag><c>recv_avg</c></tag> @@ -419,52 +373,31 @@ 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} | {error, any()}</name> + <name name="port" arity="1"/> <fsummary>Return the local port number for a socket</fsummary> - <type> - <v>Socket = socket()</v> - <v>Port = int()</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> </func> <func> - <name>setopts(Socket, Options) -> ok | {error, posix()}</name> + <name name="setopts" arity="2"/> <fsummary>Set one or more options for a socket</fsummary> - <type> - <v>Socket = term()</v> - <v>Options = [{Opt, Val} | {raw, Protocol, Option, ValueBin}]</v> - <v>Protocol = int()</v> - <v>OptionNum = int()</v> - <v>ValueBin = binary()</v> - <v> Opt, Val -- see below</v> - </type> + <type name="socket_setopt"/> <desc> <p>Sets one or more options for a socket. The following options are available:</p> @@ -622,8 +555,14 @@ fe80::204:acff:fe17:bf38 mode will return <c>{ok, HttpPacket}</c> from <c>gen_tcp:recv</c> while an active socket will send messages like <c>{http, Socket, HttpPacket}</c>.</p> - <p>Note that the packet type <c>httph</c> is not - needed when reading from a socket.</p> + </item> + <tag><c>httph | httph_bin</c></tag> + <item> + <p>These two types are often not needed as the socket will + automatically switch from <c>http</c>/<c>http_bin</c> to + <c>httph</c>/<c>httph_bin</c> internally after the first line + has been read. There might be occasions however when they are + useful, such as parsing trailers from chunked encoding.</p> </item> </taglist> </item> |