From 5a485461a1157fef1bb3ce8426bfd1ad57b5ca52 Mon Sep 17 00:00:00 2001 From: Hans Bolinder Date: Fri, 6 May 2011 16:01:56 +0200 Subject: Use Erlang specs and types for documentation --- lib/kernel/doc/src/inet.xml | 193 +++++++++++++++++--------------------------- 1 file changed, 75 insertions(+), 118 deletions(-) (limited to 'lib/kernel/doc/src/inet.xml') 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 @@
- 19972010 + 19972011 Ericsson AB. All Rights Reserved. @@ -54,33 +54,6 @@ $ erl -sname test -kernel \ inet_default_listen_options '[{delay_send,true}]'

Note that the default option {active, true} currently cannot be changed, for internal reasons.

- - -
- DATA TYPES - -#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)

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" @@ -109,24 +82,58 @@ fe80::204:acff:fe17:bf38 {ok,{192,168,42,2}} 2> inet_parse:address("FFFF::192.168.42.2"). {ok,{65535,0,0,0,0,0,49320,10754}} -

+ + + + + + +

The record is defined in the Kernel include file "inet.hrl". + Add the following directive to the module:

+-include_lib("kernel/include/inet.hrl"). + + + + + + + + + + + + + + + +

An atom which is named from the Posix error codes + used in Unix, and in the runtime libraries of most + C compilers. See + POSIX Error Codes.

+ + + + socket() +

See gen_tcp(3) + and gen_udp(3).

+ + + + + + + - close(Socket) -> ok + Close a socket of any type - - Socket = socket() -

Closes a socket of any type.

 - get_rc() -> [{Par, Val}] + Return a list of IP configuration parameters - - Par, Val -- see below -

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 - format_error(Posix) -> string() + Return a descriptive string for an error reason - - Posix = posix() -

Returns a diagnostic error string. See the section below - for possible Posix values and the corresponding + for possible Posix values and the corresponding strings.

 - getaddr(Host, Family) -> {ok, Address} | {error, posix()} + Return the IP-address for a host - - Host = ip_address() | string() | atom() - Family = inet | inet6 - Address = ip_address() - posix() = term() - -

Returns the IP-address for Host as a tuple of - integers. Host can be an IP-address, a single hostname +

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, Addresses} | {error, posix()} + Return the IP-addresses for a host - - Host = ip_address() | string() | atom() - Addresses = [ip_address()] - Family = inet | inet6 - -

Returns a list of all IP-addresses for Host. - Host can be an IP-address, a single hostname or a fully +

Returns a list of all IP-addresses for Host. + Host can be an IP-address, a single hostname or a fully qualified hostname.

 - gethostbyaddr(Address) -> {ok, Hostent} | {error, posix()} + Return a hostent record for the host with the given address - - Address = string() | ip_address() - Hostent = #hostent{} -

Returns a hostent record given an address.

 - gethostbyname(Name) -> {ok, Hostent} | {error, posix()} + Return a hostent record for the host with the given name - - Hostname = hostname() - Hostent = #hostent{} -

Returns a hostent record given a hostname.

 - gethostbyname(Name, Family) -> {ok, Hostent} | {error, posix()} + Return a hostent record for the host with the given name - - Hostname = hostname() - Family = inet | inet6 - Hostent = #hostent{} -

Returns a hostent record given a hostname, restricted to the given address family.

 - gethostname() -> {ok, Hostname} + Return the local hostname - - Hostname = string() -

Returns the local hostname. Will never fail.

 - getifaddrs() -> {ok,Iflist} | {error,posix} + Return a list of interfaces and their addresses - - Iflist = {Ifname,[Ifopt]} - Ifname = string() - Ifopt = {flag,[Flag]} | {addr,Addr} | {netmask,Netmask} - | {broadaddr,Broadaddr} | {dstaddr,Dstaddr} - | {hwaddr,Hwaddr} - Flag = up | broadcast | loopback | pointtopoint - | running | multicast - Addr = Netmask = Broadadddr = Dstaddr = ip_address() - Hwaddr = [byte()] - -

Returns a list of 2-tuples containing interface names and the - interface's addresses. Ifname is a Unicode string. - Hwaddr is hardware dependent, e.g on Ethernet interfaces + interface's addresses. Ifname is a Unicode string. + Hwaddr is hardware dependent, e.g on Ethernet interfaces it is the 6-byte Ethernet address (MAC address (EUI-48 address)).

- The {addr,Addr}, {netmask,_} and {broadaddr,_} + The {addr,Addr}, {netmask,_} and {broadaddr,_} tuples are repeated in the result list iff the interface has multiple addresses. If you come across an interface that has multiple {flag,_} or {hwaddr,_} tuples you have @@ -252,8 +217,8 @@ fe80::204:acff:fe17:bf38 The {flag,_} tuple is mandatory, all other optional.

- Do not rely too much on the order of Flag atoms or - Ifopt tuples. There are some rules, though: + Do not rely too much on the order of Flag atoms or + Ifopt tuples. There are some rules, though: Immediately after {addr,_} follows {netmask,_} @@ -261,7 +226,7 @@ fe80::204:acff:fe17:bf38 Immediately thereafter follows {broadaddr,_} if the broadcast flag is not set and the - pointtopointflag is set. + pointtopoint flag is set. Any {netmask,_}, {broadaddr,_} or @@ -277,11 +242,12 @@ fe80::204:acff:fe17:bf38

On Windows, the data is fetched from quite different OS API - functions, so the Netmask and Broadaddr - values may be calculated, just as some Flag values. + functions, so the Netmask and Broadaddr + values may be calculated, just as some Flag values. You have been warned. Report flagrant bugs.

+ getopts(Socket, Options) -> {ok, OptionValues} | {error, posix()} @@ -291,13 +257,14 @@ fe80::204:acff:fe17:bf38 Options = [Opt | RawOptReq] Opt = atom() RawOptReq = {raw, Protocol, OptionNum, ValueSpec} - Protocol = int() - OptionNum = int() + Protocol = integer() + OptionNum = integer() ValueSpec = ValueSize | ValueBin - ValueSize = int() + ValueSize = integer() ValueBin = binary() OptionValues = [{Opt, Val} | {raw, Protocol, OptionNum, ValueBin}] +

Gets one or more options for a socket. See setopts/2 @@ -419,13 +386,8 @@ fe80::204:acff:fe17:bf38 - peername(Socket) -> {ok, {Address, Port}} | {error, posix()} + Return the address and port for the other end of a connection - - Socket = socket() - Address = ip_address() - Port = int() -

Returns the address and port for the other end of a connection.

@@ -436,20 +398,15 @@ fe80::204:acff:fe17:bf38 Return the local port number for a socket Socket = socket() - Port = int() + Port = integer()

Returns the local port number for a socket.

 - sockname(Socket) -> {ok, {Address, Port}} | {error, posix()} + Return the local address and port number for a socket - - Socket = socket() - Address = ip_address() - Port = int() -

Returns the local address and port number for a socket.

 @@ -460,8 +417,8 @@ fe80::204:acff:fe17:bf38 Socket = term() Options = [{Opt, Val} | {raw, Protocol, Option, ValueBin}] - Protocol = int() - OptionNum = int() + Protocol = integer() + OptionNum = integer() ValueBin = binary()  Opt, Val -- see below -- cgit v1.2.3