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/gen_tcp.xml | 163 +++++++++++++++++------------------------ 1 file changed, 69 insertions(+), 94 deletions(-) (limited to 'lib/kernel/doc/src/gen_tcp.xml') diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml index aa171c77c2..f1d42d9faa 100644 --- a/lib/kernel/doc/src/gen_tcp.xml +++ b/lib/kernel/doc/src/gen_tcp.xml @@ -4,7 +4,7 @@
- 19972010 + 19972011 Ericsson AB. All Rights Reserved. @@ -63,36 +63,45 @@ do_recv(Sock, Bs) ->

For more examples, see the examples section.

-
- DATA TYPES - -ip_address() - see inet(3) - -posix() - see inet(3) + + + + + + + +

Represents an address of a TCP socket. + It is a tuple as explained in + inet(3).

+ + + + + + + + +

See + inet(3); POSIX Error Codes.

+ + + + socket() + +

As returned by accept/1,2 and connect/3,4.

+ + + + -socket() - as returned by accept/1,2 and connect/3,4 - -
- connect(Address, Port, Options) -> {ok, Socket} | {error, Reason} - connect(Address, Port, Options, Timeout) -> {ok, Socket} | {error, Reason} + + Connect to a TCP port - - Address = string() | atom() | ip_address() - Port = 0..65535 - Options = [Opt] -  Opt -- see below - Timeout = int() | infinity - Socket = socket() - Reason = posix() - -

Connects to a server on TCP port Port on the host - with IP address Address. The Address argument +

Connects to a server on TCP port Port on the host + with IP address Address. The Address argument can be either a hostname, or an IP address.

The available options are:

@@ -127,13 +136,13 @@ socket()

Set up the socket for IPv4.

 - Opt + Opt

See inet:setopts/2.

 -

Packets can be sent to the returned socket Socket +

Packets can be sent to the returned socket Socket using send/2. Packets sent from the peer are delivered as messages:

@@ -148,7 +157,7 @@ socket()

unless {active, false} is specified in the option list for the socket, in which case packets are retrieved by calling recv/2.

-

The optional Timeout parameter specifies a timeout in +

The optional Timeout parameter specifies a timeout in milliseconds. The default value is infinity.

The default values for options given to connect can @@ -159,19 +168,12 @@ socket() - listen(Port, Options) -> {ok, ListenSocket} | {error, Reason} + Set up a socket to listen on a port - - Port = 0..65535 - Options = [Opt] -  Opt -- see below - ListenSocket -- see below - Reason = posix() - -

Sets up a socket to listen on the port Port on +

Sets up a socket to listen on the port Port on the local host.

-

If Port == 0, the underlying OS assigns an available +

If Port == 0, the underlying OS assigns an available port number, use inet:port/1 to retrieve it.

The available options are:

@@ -214,7 +216,7 @@ socket() inet:setopts/2.

 -

The returned socket ListenSocket can only be used in +

The returned socket ListenSocket can only be used in calls to accept/1,2.

The default values for options given to listen can @@ -225,27 +227,23 @@ socket() - accept(ListenSocket) -> {ok, Socket} | {error, Reason} - accept(ListenSocket, Timeout) -> {ok, Socket} | {error, Reason} + + Accept an incoming connection request on a listen socket - - ListenSocket -- see listen/2 - Timeout = int() | infinity - Socket = socket() - Reason = closed | timeout | posix() - + Returned by listen/2. +

Accepts an incoming connection request on a listen socket. - Socket must be a socket returned from listen/2. - Timeout specifies a timeout value in ms, defaults to + Socket must be a socket returned from listen/2. + Timeout specifies a timeout value in ms, defaults to infinity.

-

Returns {ok, Socket} if a connection is established, - or {error, closed} if ListenSocket is closed, +

Returns {ok, Socket} if a connection is established, + or {error, closed} if ListenSocket is closed, or {error, timeout} if no connection is established within the specified time. May also return a POSIX error value if something else goes wrong, see inet(3) for possible error values.

-

Packets can be sent to the returned socket Socket +

Packets can be sent to the returned socket Socket using send/2. Packets sent from the peer are delivered as messages:

@@ -264,13 +262,8 @@ socket() - send(Socket, Packet) -> ok | {error, Reason} + Send a packet - - Socket = socket() - Packet = [char()] | binary() - Reason = posix() -

Sends a packet on a socket.

There is no send call with timeout option, you use the @@ -279,70 +272,52 @@ socket() - recv(Socket, Length) -> {ok, Packet} | {error, Reason} - recv(Socket, Length, Timeout) -> {ok, Packet} | {error, Reason} + + Receive a packet from a passive socket - - Socket = socket() - Length = int() - Packet = [char()] | binary() | HttpPacket - Timeout = int() | infinity - Reason = closed | posix() - HttpPacket = see the description of HttpPacket in erlang:decode_packet/3 - + See the description of + HttpPacket in + erlang:decode_packet/3. +

This function receives a packet from a socket in passive mode. A closed socket is indicated by a return value {error, closed}.

-

The Length argument is only meaningful when +

The Length argument is only meaningful when the socket is in raw mode and denotes the number of - bytes to read. If Length = 0, all available bytes are - returned. If Length > 0, exactly Length + bytes to read. If Length = 0, all available bytes are + returned. If Length > 0, exactly Length bytes are returned, or an error; possibly discarding less - than Length bytes of data when the socket gets closed + than Length bytes of data when the socket gets closed from the other side.

-

The optional Timeout parameter specifies a timeout in +

The optional Timeout parameter specifies a timeout in milliseconds. The default value is infinity.

 - controlling_process(Socket, Pid) -> ok | {error, Reason} + Change controlling process of a socket - - Socket = socket() - Pid = pid() - Reason = closed | not_owner | posix() - -

Assigns a new controlling process Pid to - Socket. The controlling process is the process which +

Assigns a new controlling process Pid to + Socket. The controlling process is the process which receives messages from the socket. If called by any other process than the current controlling process, {error, eperm} is returned.

 - close(Socket) -> ok | {error, Reason} + Close a TCP socket - - Socket = socket() - Reason = posix() -

Closes a TCP socket.

 - shutdown(Socket, How) -> ok | {error, Reason} + Immediately close a socket - - Socket = socket() - How = read | write | read_write - Reason = posix() -

Immediately close a socket in one or two directions.

-

How == write means closing the socket for writing, +

How == write means closing the socket for writing, reading from it is still possible.

To be able to handle that the peer has done a shutdown on the write side, the {exit_on_close, false} option -- cgit v1.2.3