aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc')
-rw-r--r--lib/kernel/doc/src/Makefile22
-rw-r--r--lib/kernel/doc/src/gen_sctp.xml41
-rw-r--r--lib/kernel/doc/src/gen_tcp.xml57
-rw-r--r--lib/kernel/doc/src/gen_udp.xml57
-rw-r--r--lib/kernel/doc/src/inet.xml95
-rw-r--r--lib/kernel/doc/src/notes.xml127
6 files changed, 342 insertions, 57 deletions
diff --git a/lib/kernel/doc/src/Makefile b/lib/kernel/doc/src/Makefile
index 214e994889..78e5f7bc26 100644
--- a/lib/kernel/doc/src/Makefile
+++ b/lib/kernel/doc/src/Makefile
@@ -155,18 +155,18 @@ $(SPECDIR)/specs_zlib_stub.xml:
include $(ERL_TOP)/make/otp_release_targets.mk
release_docs_spec: docs
- $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf
- $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf
- $(INSTALL_DIR) $(RELSYSDIR)/doc/html
+ $(INSTALL_DIR) "$(RELSYSDIR)/doc/pdf"
+ $(INSTALL_DATA) $(TOP_PDF_FILE) "$(RELSYSDIR)/doc/pdf"
+ $(INSTALL_DIR) "$(RELSYSDIR)/doc/html"
$(INSTALL_DATA) $(HTMLDIR)/* \
- $(RELSYSDIR)/doc/html
- $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR)
- $(INSTALL_DIR) $(RELEASE_PATH)/man/man3
- $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3
- $(INSTALL_DIR) $(RELEASE_PATH)/man/man4
- $(INSTALL_DATA) $(MAN4_FILES) $(RELEASE_PATH)/man/man4
- $(INSTALL_DIR) $(RELEASE_PATH)/man/man6
- $(INSTALL_DATA) $(MAN6_FILES) $(RELEASE_PATH)/man/man6
+ "$(RELSYSDIR)/doc/html"
+ $(INSTALL_DATA) $(INFO_FILE) "$(RELSYSDIR)"
+ $(INSTALL_DIR) "$(RELEASE_PATH)/man/man3"
+ $(INSTALL_DATA) $(MAN3DIR)/* "$(RELEASE_PATH)/man/man3"
+ $(INSTALL_DIR) "$(RELEASE_PATH)/man/man4"
+ $(INSTALL_DATA) $(MAN4_FILES) "$(RELEASE_PATH)/man/man4"
+ $(INSTALL_DIR) "$(RELEASE_PATH)/man/man6"
+ $(INSTALL_DATA) $(MAN6_FILES) "$(RELEASE_PATH)/man/man6"
release_spec:
diff --git a/lib/kernel/doc/src/gen_sctp.xml b/lib/kernel/doc/src/gen_sctp.xml
index 579b7f1f74..e327a4f907 100644
--- a/lib/kernel/doc/src/gen_sctp.xml
+++ b/lib/kernel/doc/src/gen_sctp.xml
@@ -123,7 +123,7 @@
<p>Completely closes the socket and all associations on it. The unsent
data is flushed as in <c>eof/2</c>. The <c>close/1</c> call
is blocking or otherwise depending of the value of
- the <seealso marker="#option-linger">linger</seealso> socket
+ the <seealso marker="inet#option-linger">linger</seealso> socket
<seealso marker="#options">option</seealso>.
If <c>close</c> does not linger or linger timeout expires,
the call returns and the data is flushed in the background.</p>
@@ -309,8 +309,8 @@
<seealso marker="#option-active">passive</seealso> mode,
with <anno>SockType</anno> <c>seqpacket</c>,
and with reasonably large
- <seealso marker="#option-sndbuf">kernel</seealso> and driver
- <seealso marker="#option-buffer">buffers.</seealso></p>
+ <seealso marker="inet#option-sndbuf">kernel</seealso> and driver
+ <seealso marker="inet#option-buffer">buffers.</seealso></p>
</desc>
</func>
<func>
@@ -530,19 +530,8 @@
SCTP data interleaved with other inter-process messages.</p>
</item>
</list>
- <marker id="option-buffer"></marker>
</item>
- <tag><c>{buffer, integer()}</c></tag>
- <item>
- <p>Determines the size of the user-level software buffer used by
- the SCTP driver. Not to be confused with <c>sndbuf</c>
- and <c>recbuf</c> options which correspond to
- the kernel socket buffers. It is recommended
- to have <c>val(buffer) &gt;= max(val(sndbuf),val(recbuf))</c>.
- In fact, the <c>val(buffer)</c> is automatically set to
- the above maximum when <c>sndbuf</c> or <c>recbuf</c> values are set.</p>
- </item>
- <tag><c>{tos, integer()}</c></tag>
+ <tag><c>{tos, integer()}</c></tag>
<item>
<p>Sets the Type-Of-Service field on the IP datagrams being sent,
to the given value, which effectively determines a prioritization
@@ -567,19 +556,8 @@
<c>{IP,Port}</c> of the socket can be re-used immediately:
no waiting in the CLOSE_WAIT state is performed (may be
required for high-throughput servers).</p>
- <marker id="option-linger"></marker>
- </item>
- <tag><c>{linger, {true|false, integer()}</c></tag>
- <item>
- <p>Determines the timeout in seconds for flushing unsent data in the
- <c>gen_sctp:close/1</c> socket call. If the 1st component of the value
- tuple is <c>false</c>, the 2nd one is ignored, which means that
- <c>gen_sctp:close/1</c> returns immediately not waiting
- for data to be flushed. Otherwise, the 2nd component is
- the flushing time-out in seconds.</p>
- <marker id="option-sndbuf"></marker>
</item>
- <tag><c>{sndbuf, integer()}</c></tag>
+ <tag><c>{sndbuf, integer()}</c></tag>
<item>
<p>The size, in bytes, of the *kernel* send buffer for this socket.
Sending errors would occur for datagrams larger than
@@ -593,6 +571,15 @@
<c>val(sndbuf)</c>. Setting this option also adjusts
the size of the driver buffer (see <c>buffer</c> above).</p>
</item>
+
+ <tag><c>{sctp_module, module()}</c></tag>
+ <item> <p>
+ Override which callback module is used. Defaults to
+ <c>inet_sctp</c> for IPv4 and <c>inet6_sctp</c> for IPv6.
+ </p>
+ </item>
+
+
<tag><c>{sctp_rtoinfo, #sctp_rtoinfo{}}</c></tag>
<item>
<pre> #sctp_rtoinfo{
diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index cf97607af1..11a0843c10 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.xml
@@ -96,37 +96,47 @@ do_recv(Sock, Bs) ->
can be either a hostname, or an IP address.</p>
<p>The available options are:</p>
<taglist>
- <tag><c>list</c></tag>
- <item>
- <p>Received <c>Packet</c> is delivered as a list.</p>
- </item>
- <tag><c>binary</c></tag>
- <item>
- <p>Received <c>Packet</c> is delivered as a binary.</p>
- </item>
- <tag><c>{ip, ip_address()}</c></tag>
+ <tag><c>{ip, ip_address()}</c></tag>
<item>
<p>If the host has several network interfaces, this option
specifies which one to use.</p>
</item>
- <tag><c>{port, Port}</c></tag>
+
+ <tag><c>{ifaddr, ip_address()}</c></tag>
<item>
- <p>Specify which local port number to use.</p>
- </item>
+ <p>Same as <c>{ip, ip_address()}</c>. If the host has several network interfaces, this option
+ specifies which one to use.</p>
+ </item>
+
<tag><c>{fd, integer() >= 0}</c></tag>
<item>
<p>If a socket has somehow been connected without using
<c>gen_tcp</c>, use this option to pass the file
descriptor for it.</p>
</item>
- <tag><c>inet6</c></tag>
+
+ <tag><c>inet</c></tag>
<item>
+ <p>Set up the socket for IPv4.</p>
+ </item>
+
+ <tag><c>inet6</c></tag>
+ <item>
<p>Set up the socket for IPv6.</p>
</item>
- <tag><c>inet</c></tag>
+
+ <tag><c>{port, Port}</c></tag>
<item>
- <p>Set up the socket for IPv4.</p>
+ <p>Specify which local port number to use.</p>
</item>
+
+ <tag><c>{tcp_module, module()}</c></tag>
+ <item> <p>
+ Override which callback module is used. Defaults to
+ <c>inet_tcp</c> for IPv4 and <c>inet6_tcp</c> for IPv6.
+ </p>
+ </item>
+
<tag><c>Opt</c></tag>
<item>
<p>See
@@ -197,6 +207,13 @@ do_recv(Sock, Bs) ->
<c>gen_tcp</c>, use this option to pass the file
descriptor for it.</p>
</item>
+
+ <tag><c>{ifaddr, ip_address()}</c></tag>
+ <item>
+ <p>Same as <c>{ip, ip_address()}</c>. If the host has several network interfaces, this option
+ specifies which one to use.</p>
+ </item>
+
<tag><c>inet6</c></tag>
<item>
<p>Set up the socket for IPv6.</p>
@@ -205,6 +222,14 @@ do_recv(Sock, Bs) ->
<item>
<p>Set up the socket for IPv4.</p>
</item>
+
+ <tag><c>{tcp_module, module()}</c></tag>
+ <item> <p>
+ Override which callback module is used. Defaults to
+ <c>inet_tcp</c> for IPv4 and <c>inet6_tcp</c> for IPv6.
+ </p>
+ </item>
+
<tag><c>Opt</c></tag>
<item>
<p>See
@@ -299,7 +324,7 @@ do_recv(Sock, Bs) ->
<c><anno>Socket</anno></c>. The controlling process is the process which
receives messages from the socket. If called by any other
process than the current controlling process,
- <c>{error, eperm}</c> is returned.</p>
+ <c>{error, not_owner}</c> is returned.</p>
</desc>
</func>
<func>
diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml
index daa9b7d887..726dc30546 100644
--- a/lib/kernel/doc/src/gen_udp.xml
+++ b/lib/kernel/doc/src/gen_udp.xml
@@ -72,6 +72,14 @@
<p>If the host has several network interfaces, this option
specifies which one to use.</p>
</item>
+
+ <tag><c>{ifaddr, ip_address()}</c></tag>
+ <item>
+ <p>Same as <c>{ip, ip_address()}</c>. If the host has several network interfaces, this option
+ specifies which one to use.</p>
+ </item>
+
+
<tag><c>{fd, integer() >= 0}</c></tag>
<item>
<p>If a socket has somehow been opened without using
@@ -86,6 +94,51 @@
<item>
<p>Set up the socket for IPv4.</p>
</item>
+
+ <tag><c>{udp_module, module()}</c></tag>
+ <item> <p>
+ Override which callback module is used. Defaults to
+ <c>inet_udp</c> for IPv4 and <c>inet6_udp</c> for IPv6.
+ </p>
+ </item>
+
+ <tag><c>{multicast_if, Address}</c></tag>
+ <item>
+ <p>Set the local device for a multicast socket.</p>
+ </item>
+
+ <tag><c>{multicast_loop, true | false}</c></tag>
+ <item>
+ <p>
+ When <c>true</c> sent multicast packets will be looped back to the local
+ sockets.
+ </p>
+ </item>
+
+ <tag><c>{multicast_ttl, Integer}</c></tag>
+ <item>
+ <p>
+ The <c>multicast_ttl</c> option changes the time-to-live (TTL) for
+ outgoing multicast datagrams in order to control the scope of the
+ multicasts.
+ </p>
+ <p>
+ Datagrams with a TTL of 1 are not forwarded beyond the local
+ network.
+ <br />Default: 1
+ </p>
+ </item>
+
+ <tag><c>{add_membership, {MultiAddress, InterfaceAddress}}</c></tag>
+ <item>
+ <p>Join a multicast group. </p>
+ </item>
+
+ <tag><c>{drop_membership, {MultiAddress, InterfaceAddress}}</c></tag>
+ <item>
+ <p>Leave multicast group.</p>
+ </item>
+
<tag><c>Opt</c></tag>
<item>
<p>See
@@ -136,7 +189,9 @@
<desc>
<p>Assigns a new controlling process <c><anno>Pid</anno></c> to
<c><anno>Socket</anno></c>. The controlling process is the process which
- receives messages from the socket.</p>
+ receives messages from the socket. If called by any other
+ process than the current controlling process,
+ <c>{error, not_owner}</c> is returned.</p>
</desc>
</func>
<func>
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
index bf6c4cfb1a..096ddfd847 100644
--- a/lib/kernel/doc/src/inet.xml
+++ b/lib/kernel/doc/src/inet.xml
@@ -445,10 +445,34 @@ fe80::204:acff:fe17:bf38
flow control; the other side will not be able send
faster than the receiver can read.</p>
</item>
+
+ <tag><c>{bit8, clear | set | on | off}</c></tag>
+ <item>
+ <p>
+ Scans every byte in received data-packets and checks if the 8 bit
+ is set in any of them. Information is retrieved with
+ <c>inet:getopts/2</c>.
+ <note>Deprecated! Will be removed in Erlang/OTP R16.</note>
+ </p>
+ </item>
+
<tag><c>{broadcast, Boolean}</c>(UDP sockets)</tag>
<item>
<p>Enable/disable permission to send broadcasts.</p>
+ <marker id="option-buffer"></marker>
</item>
+
+ <tag><c>{buffer, Size}</c></tag>
+ <item>
+ <p>Determines the size of the user-level software buffer used by
+ the driver. Not to be confused with <c>sndbuf</c>
+ and <c>recbuf</c> options which correspond to
+ the kernel socket buffers. It is recommended
+ to have <c>val(buffer) &gt;= max(val(sndbuf),val(recbuf))</c>.
+ In fact, the <c>val(buffer)</c> is automatically set to
+ the above maximum when <c>sndbuf</c> or <c>recbuf</c> values are set.</p>
+ </item>
+
<tag><c>{delay_send, Boolean}</c></tag>
<item>
<p>Normally, when an Erlang process sends to a socket,
@@ -463,10 +487,19 @@ fe80::204:acff:fe17:bf38
real property of the socket. Needless to say it is an
implementation specific option. Default is <c>false</c>.</p>
</item>
+
+ <tag><c>{deliver, port | term}</c></tag>
+ <item> <p> When <c>{active, true}</c> delivers data on the forms
+ <c>port</c> : <c>{S, {data, [H1,..Hsz | Data]}}</c> or
+ <c>term</c> : <c>{tcp, S, [H1..Hsz | Data]}</c>.
+ </p>
+ </item>
+
<tag><c>{dontroute, Boolean}</c></tag>
<item>
<p>Enable/disable routing bypass for outgoing messages.</p>
</item>
+
<tag><c>{exit_on_close, Boolean}</c></tag>
<item>
<p>By default this option is set to <c>true</c>.</p>
@@ -476,6 +509,7 @@ fe80::204:acff:fe17:bf38
<seealso marker="gen_tcp#shutdown/2">gen_tcp:shutdown/2</seealso>
to shutdown the write side.</p>
</item>
+
<tag><c>{header, Size}</c></tag>
<item>
<p>This option is only meaningful if the <c>binary</c>
@@ -487,6 +521,15 @@ fe80::204:acff:fe17:bf38
example <c>Size == 2</c>, the data received will match
<c>[Byte1,Byte2|Binary]</c>.</p>
</item>
+
+ <tag><c>{high_watermark, Size}</c></tag>
+ <item> <p>
+ Sender is forced busy if sent and enqueued data
+ reaches the highwater mark.
+ <br /> Default: 8192 kB.
+ </p>
+ </item>
+
<tag><c>{keepalive, Boolean}</c>(TCP/IP sockets)</tag>
<item>
<p>Enables/disables periodic transmission on a connected
@@ -494,7 +537,43 @@ fe80::204:acff:fe17:bf38
the other end does not respond, the connection is
considered broken and an error message will be sent to
the controlling process. Default disabled.</p>
+ <marker id="option-linger"></marker>
</item>
+
+ <tag><c>{linger, {true|false, Seconds}}</c></tag>
+ <item>
+ <p>Determines the timeout in seconds for flushing unsent data in the
+ <c>close/1</c> socket call. If the 1st component of the value
+ tuple is <c>false</c>, the 2nd one is ignored, which means that
+ <c>close/1</c> returns immediately not waiting
+ for data to be flushed. Otherwise, the 2nd component is
+ the flushing time-out in seconds.</p>
+ </item>
+
+ <tag><c>{low_watermark, Size}</c></tag>
+ <item> <p>
+ If the port has reached its <c>high_watermark</c> it will
+ force busy onto senders. When the port data queue reaches the
+ <c>low_watermark</c> callers are no longer forced busy.
+ <br /> Default: 4096 kB.
+ </p>
+ </item>
+
+ <tag><c>{mode, Mode :: binary | list}</c></tag>
+ <item>
+ <p>Received <c>Packet</c> is delivered as defined by Mode.</p>
+ </item>
+
+ <tag><c>list</c></tag>
+ <item>
+ <p>Received <c>Packet</c> is delivered as a list.</p>
+ </item>
+
+ <tag><c>binary</c></tag>
+ <item>
+ <p>Received <c>Packet</c> is delivered as a binary.</p>
+ </item>
+
<tag><c>{nodelay, Boolean}</c>(TCP/IP sockets)</tag>
<item>
<p>If <c>Boolean == true</c>, the <c>TCP_NODELAY</c> option
@@ -578,6 +657,16 @@ fe80::204:acff:fe17:bf38
indicated length are accepted and not considered invalid due
to internal buffer limitations.</p>
</item>
+
+ <tag><c>{priority, Priority}</c></tag>
+ <item> <p>Set the protocol-defined priority for all packets to be sent
+ on this socket.</p>
+ </item>
+
+ <tag><c>{raw, Protocol, OptionNum, ValueBin}</c></tag>
+ <item> <p>See below.</p>
+ </item>
+
<tag><c>{read_packets, Integer}</c>(UDP sockets)</tag>
<item>
<p>Sets the max number of UDP packets to read without
@@ -589,7 +678,7 @@ fe80::204:acff:fe17:bf38
high the system can become unresponsive due to
UDP packet flooding.</p>
</item>
- <tag><c>{recbuf, Integer}</c></tag>
+ <tag><c>{recbuf, Size}</c></tag>
<item>
<p>Gives the size of the receive buffer to use for
the socket.</p>
@@ -618,9 +707,10 @@ fe80::204:acff:fe17:bf38
returns <c>{error,timeout}</c>. The recommended setting is
<c>true</c> which will automatically close the socket.
Default is <c>false</c> due to backward compatibility.</p>
+ <marker id="option-sndbuf"></marker>
</item>
- <tag><c>{sndbuf, Integer}</c></tag>
+ <tag><c>{sndbuf, Size}</c></tag>
<item>
<p>Gives the size of the send buffer to use for the socket.</p>
</item>
@@ -639,6 +729,7 @@ fe80::204:acff:fe17:bf38
not implemented. Use with caution.</p>
</item>
</taglist>
+
<p>In addition to the options mentioned above, <em>raw</em>
option specifications can be used. The raw options are
specified as a tuple of arity four, beginning with the tag
diff --git a/lib/kernel/doc/src/notes.xml b/lib/kernel/doc/src/notes.xml
index 9121186631..94624bf512 100644
--- a/lib/kernel/doc/src/notes.xml
+++ b/lib/kernel/doc/src/notes.xml
@@ -30,6 +30,133 @@
</header>
<p>This document describes the changes made to the Kernel application.</p>
+<section><title>Kernel 2.15.1</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>
+ Driver output has been corrected so output of large
+ binaries (> 4 GiB) now does not silently fail or crash
+ the emulator, but either outputs the binary or fails the
+ call. This means that writing a binary > 4 Gib to file
+ now works but on e.g 64-bit Windows (that has
+ scatter/gather I/O buffer segment lengths of 32 bits)
+ fails. The behaviour may change in the future to always
+ write the binary, in parts if necessary.</p>
+ <p>
+ Own Id: OTP-9820 Aux Id: OTP-9795 </p>
+ </item>
+ <item>
+ <p>
+ erts: minor fix for unnecessary condition erts: change
+ SENDFILE_CHUNK_SIZE from signed to unsigned (Thanks to
+ jovi zhang)</p>
+ <p>
+ Own Id: OTP-9872</p>
+ </item>
+ <item>
+ <p> Two contracts in <c>gen_sctp</c> have been corrected.
+ </p>
+ <p>
+ Own Id: OTP-9874</p>
+ </item>
+ <item>
+ <p>If a process calls a module with an running on_load
+ handler, the process is supposed to be suspended. But if
+ the module with the on_load handler was loading used
+ <c>code:load_binary/3</c>, the call would instead fail
+ with an <c>undef</c> exception.</p>
+ <p>
+ Own Id: OTP-9875</p>
+ </item>
+ <item>
+ <p>
+ File name and error reason is now returned if creation of
+ a cookie fails. (Thanks to Magnus Henoch)</p>
+ <p>
+ Own Id: OTP-9954</p>
+ </item>
+ <item>
+ <p>
+ Fix port leak in <c>zlib</c> when passing invalid data to
+ <c>compress,uncompress,zip,unzip,gzip,gunzip</c>.</p>
+ <p>
+ Own Id: OTP-9981</p>
+ </item>
+ <item>
+ <p>
+ Various typographical errors corrected in documentation
+ for the global, error_logger, etop, lists, ets and
+ supervisor modules and in the c_portdriver and kernel_app
+ documentation. (Thanks to Ricardo Catalinas Jim�nez)</p>
+ <p>
+ Own Id: OTP-9987</p>
+ </item>
+ <item>
+ <p> Fix returned error from gen_tcp:accept/1,2 when
+ running out of ports
+ <p>
+ The {error, enfile} return value is badly misleading and
+ confusing for this case, since the Posix ENFILE errno
+ value has a well-defined meaning that has nothing to do
+ with Erlang ports. The fix changes the return value to
+ {error, system_limit}, which is consistent with e.g.
+ various file(3) functions. inet:format_error/1 has also
+ been updated to support system_limit in the same manner
+ as file:format_error/1. (Thanks to Per Hedeland)</p></p>
+ <p>
+ Own Id: OTP-9990</p>
+ </item>
+ <item>
+ <p><c>erts_debug:size/1</c> has been corrected to take
+ sharing in the environment of funs into account. For funs
+ it used to always give the same result as
+ <c>erts_debug:flat_size/1</c>.</p>
+ <p>
+ Own Id: OTP-9991</p>
+ </item>
+ <item>
+ <p>
+ In some cases when the process doing file:sendfile
+ crashes while sending the file the efile_drv code would
+ not clean up after itself correctly. This has now been
+ fixed.</p>
+ <p>
+ Own Id: OTP-9993</p>
+ </item>
+ <item>
+ <p>
+ On BSD based platforms file:sendfile would sometime go
+ into an infinite loop when sending big files. This has
+ now been fixed.</p>
+ <p>
+ Own Id: OTP-9994</p>
+ </item>
+ <item>
+ <p>While <c>disk_log</c> eagerly collects logged terms
+ for better performance, collecting too much data may
+ choke the system and cause huge binaries to be
+ written.</p>
+ <p>The problem was addressed in OTP-9764, but the
+ situation was not improved in all cases.</p>
+ <p>(Thanks to Richard Carlsson.)</p>
+ <p>
+ Own Id: OTP-9999 Aux Id: OTP-9764 </p>
+ </item>
+ <item>
+ <p>
+ The documentation of .app files incorrectly said that the
+ default value for the <c>mod</c> parameter is
+ <c>undefined</c>. This is now corrected to <c>[]</c>.</p>
+ <p>
+ Own Id: OTP-10002</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
<section><title>Kernel 2.15</title>
<section><title>Fixed Bugs and Malfunctions</title>