diff options
Diffstat (limited to 'lib/kernel/doc/src')
| -rw-r--r-- | lib/kernel/doc/src/Makefile | 3 | ||||
| -rw-r--r-- | lib/kernel/doc/src/application.xml | 9 | ||||
| -rw-r--r-- | lib/kernel/doc/src/code.xml | 2 | ||||
| -rw-r--r-- | lib/kernel/doc/src/error_handler.xml | 38 | ||||
| -rw-r--r-- | lib/kernel/doc/src/file.xml | 91 | ||||
| -rw-r--r-- | lib/kernel/doc/src/gen_sctp.xml | 2 | ||||
| -rw-r--r-- | lib/kernel/doc/src/gen_udp.xml | 2 | ||||
| -rw-r--r-- | lib/kernel/doc/src/global.xml | 12 | ||||
| -rw-r--r-- | lib/kernel/doc/src/heart.xml | 35 | ||||
| -rw-r--r-- | lib/kernel/doc/src/inet.xml | 195 | ||||
| -rw-r--r-- | lib/kernel/doc/src/notes.xml | 131 | ||||
| -rw-r--r-- | lib/kernel/doc/src/os.xml | 20 | ||||
| -rw-r--r-- | lib/kernel/doc/src/packages.xml | 214 | ||||
| -rw-r--r-- | lib/kernel/doc/src/ref_man.xml | 1 |
14 files changed, 476 insertions, 279 deletions
diff --git a/lib/kernel/doc/src/Makefile b/lib/kernel/doc/src/Makefile index 78e5f7bc26..de3ca1e176 100644 --- a/lib/kernel/doc/src/Makefile +++ b/lib/kernel/doc/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1997-2011. All Rights Reserved. +# Copyright Ericsson AB 1997-2012. All Rights Reserved. # # The contents of this file are subject to the Erlang Public License, # Version 1.1, (the "License"); you may not use this file except in @@ -58,7 +58,6 @@ XML_REF3_FILES = application.xml \ net_adm.xml \ net_kernel.xml \ os.xml \ - packages.xml \ pg2.xml \ rpc.xml \ seq_trace.xml \ diff --git a/lib/kernel/doc/src/application.xml b/lib/kernel/doc/src/application.xml index 51a3311ec2..9f19efc793 100644 --- a/lib/kernel/doc/src/application.xml +++ b/lib/kernel/doc/src/application.xml @@ -121,6 +121,15 @@ </desc> </func> <func> + <name name="get_env" arity="3"/> + <fsummary>Get the value of a configuration parameter using a default</fsummary> + <desc> + <p>Works like <seealso marker="#get_env/2">get_env/2</seealso> but returns + <c><anno>Def</anno></c> value when configuration parameter + <c><anno>Par</anno></c> does not exist.</p> + </desc> + </func> + <func> <name name="get_key" arity="1"/> <name name="get_key" arity="2"/> <fsummary>Get the value of an application specification key</fsummary> diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml index bb111a2242..279c7558bc 100644 --- a/lib/kernel/doc/src/code.xml +++ b/lib/kernel/doc/src/code.xml @@ -91,7 +91,7 @@ of the additional library directories will override modules with the same name in OTP, except for modules in Kernel and STDLIB.</p> - <p>The environment variable <c>ERL_LIBS</c> (if defined) shold contain + <p>The environment variable <c>ERL_LIBS</c> (if defined) should contain a colon-separated (for Unix-like systems) or semicolon-separated (for Windows) list of additional libraries.</p> <p>Example: On an Unix-like system, <c>ERL_LIBS</c> could be set to diff --git a/lib/kernel/doc/src/error_handler.xml b/lib/kernel/doc/src/error_handler.xml index acbf9a2c6e..610b65f0a2 100644 --- a/lib/kernel/doc/src/error_handler.xml +++ b/lib/kernel/doc/src/error_handler.xml @@ -43,19 +43,39 @@ A (possibly empty) list of arguments <c>Arg1,..,ArgN</c> </type_desc> <desc> - <p>This function is evaluated if a call is made to + <p>This function is called by the run-time system if a call is made to <c><anno>Module</anno>:<anno>Function</anno>(Arg1,.., ArgN)</c> and <c><anno>Module</anno>:<anno>Function</anno>/N</c> is undefined. Note that <c>undefined_function/3</c> is evaluated inside the process making the original call.</p> - <p>If <c><anno>Module</anno></c> is interpreted, the interpreter is invoked - and the return value of the interpreted - <c><anno>Function</anno>(Arg1,.., ArgN)</c> call is returned.</p> - <p>Otherwise, it returns, if possible, the value of - <c>apply(<anno>Module</anno>, <anno>Function</anno>, <anno>Args</anno>)</c> after an attempt has been - made to autoload <c><anno>Module</anno></c>. If this is not possible, the - call to <c><anno>Module</anno>:<anno>Function</anno>(Arg1,.., ArgN)</c> fails with - exit reason <c>undef</c>.</p> + + <p>This function will first attempt to autoload + <c><anno>Module</anno></c>. If that is not possible, + an <c>undef</c> exception will be raised.</p> + + <p>If it was possible to load <c><anno>Module</anno></c> + and the function <c><anno>Function</anno>/N</c> is exported, + it will be called.</p> + + <p>Otherwise, if the function <c>'$handle_undefined_function'/2</c> + is exported, it will be called as + <c>'$handle_undefined_function'(</c><anno>Function</anno>, + <anno>Args</anno>). + </p> + <p>Otherwise an <c>undef</c> exception will be raised.</p> + </desc> + </func> + <func> + <name name="raise_undef_exception" arity="3"/> + <fsummary>Raise an undef exception</fsummary> + <type_desc variable="Args"> + A (possibly empty) list of arguments <c>Arg1,..,ArgN</c> + </type_desc> + <desc> + <p>Raise an <c>undef</c> exception with a stacktrace indicating + that <c><anno>Module</anno>:<anno>Function</anno>/N</c> is + undefined. + </p> </desc> </func> <func> diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml index b2a259080d..4a9b7d2ceb 100644 --- a/lib/kernel/doc/src/file.xml +++ b/lib/kernel/doc/src/file.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2012</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -100,7 +100,11 @@ <name name="deep_list"/> </datatype> <datatype> - <name name="fd"/> + <name><marker id="type-fd">fd()</marker></name> + <desc> + <p>A file descriptor representing a file opened in <seealso + marker="#raw">raw</seealso> mode.</p> + </desc> </datatype> <datatype> <name name="filename"/> @@ -109,8 +113,8 @@ <name name="io_device"/> <desc> <p>As returned by - <seealso marker="#open/2">file:open/2</seealso>, - a process handling IO protocols.</p> + <seealso marker="#open/2">file:open/2</seealso>; + <c>pid()</c> is a process handling I/O-protocols.</p> </desc> </datatype> <datatype> @@ -170,6 +174,18 @@ </desc> </func> <func> + <name name="allocate" arity="3"/> + <fsummary>Allocate file space</fsummary> + <desc> + <p><c>allocate/3</c> can be used to preallocate space for a file.</p> + <p>This function only succeeds in platforms that implement this + feature. When it succeeds, space is preallocated for the file but + the file size might not be updated. This behaviour depends on the + preallocation implementation. To guarantee the file size is updated + one must truncate the file to the new size.</p> + </desc> + </func> + <func> <name name="change_group" arity="2"/> <fsummary>Change group of a file</fsummary> <desc> @@ -261,6 +277,9 @@ {person, "pelle", 30}.</code> <pre>1> <input>file:consult("f.txt").</input> {ok,[{person,"kalle",25},{person,"pelle",30}]}</pre> + <p>The encoding of of <c><anno>Filename</anno></c> can be set + by a comment as described in <seealso + marker="stdlib:epp#encoding">epp(3)</seealso>.</p> </desc> </func> <func> @@ -399,6 +418,9 @@ of the error.</p> </item> </taglist> + <p>The encoding of of <c><anno>Filename</anno></c> can be set + by a comment as described in <seealso + marker="stdlib:epp#encoding">epp(3)</seealso>.</p> </desc> </func> <func> @@ -610,7 +632,7 @@ <name name="open" arity="2"/> <fsummary>Open a file</fsummary> <desc> - <p>Opens the file <c><anno>Filename</anno></c> in the mode determined + <p>Opens the file <c><anno>File</anno></c> in the mode determined by <c><anno>Modes</anno></c>, which may contain one or more of the following items:</p> <taglist> @@ -644,7 +666,8 @@ </item> <tag><c>raw</c></tag> <item> - <p>The <c>raw</c> option allows faster access to a file, + <p><marker id="raw"/> + The <c>raw</c> option allows faster access to a file, because no Erlang process is needed to handle the file. However, a file opened in this way has the following limitations:</p> @@ -767,6 +790,10 @@ <p>The Encoding can be changed for a file "on the fly" by using the <seealso marker="stdlib:io#setopts/2">io:setopts/2</seealso> function, why a file can be analyzed in latin1 encoding for i.e. a BOM, positioned beyond the BOM and then be set for the right encoding before further reading.See the <seealso marker="stdlib:unicode">unicode(3)</seealso> module for functions identifying BOM's.</p> <p>This option is not allowed on <c>raw</c> files.</p> </item> + <tag><c>ram</c></tag> + <item> + <p><c>File</c> must be <c>iodata()</c>. Returns an <c>fd()</c> which lets the <c>file</c> module operate on the data in-memory as if it is a file.</p> + </item> </taglist> <p>Returns:</p> <taglist> @@ -861,6 +888,9 @@ the error.</p> </item> </taglist> + <p>The encoding of of <c><anno>Filename</anno></c> can be set + by a comment as described in <seealso + marker="stdlib:epp#encoding">epp(3)</seealso>.</p> </desc> </func> <func> @@ -902,6 +932,9 @@ of the error.</p> </item> </taglist> + <p>The encoding of of <c><anno>Filename</anno></c> can be set + by a comment as described in <seealso + marker="stdlib:epp#encoding">epp(3)</seealso>.</p> </desc> </func> <func> @@ -971,7 +1004,10 @@ of the error.</p> </item> </taglist> - </desc> + <p>The encoding of of <c><anno>Filename</anno></c> can be set + by a comment as described in <seealso + marker="stdlib:epp#encoding">epp(3)</seealso>.</p> + </desc> </func> <func> <name name="path_script" arity="3"/> @@ -1220,11 +1256,11 @@ <p>The record <c>file_info</c> contains the following fields.</p> <taglist> - <tag><c>size = integer()</c></tag> + <tag><c>size = integer() >= 0</c></tag> <item> <p>Size of file in bytes.</p> </item> - <tag><c>type = device | directory | regular | other</c></tag> + <tag><c>type = device | directory | other | regular | symlink</c></tag> <item> <p>The type of the file.</p> </item> @@ -1232,22 +1268,22 @@ <item> <p>The current system access to the file.</p> </item> - <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag> + <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso> | integer() >= 0</c></tag> <item> <p>The last time the file was read.</p> </item> - <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag> + <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso> | integer() >= 0</c></tag> <item> <p>The last time the file was written.</p> </item> - <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag> + <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso> | integer() >=0</c></tag> <item> <p>The interpretation of this time field depends on the operating system. On Unix, it is the last time the file or the inode was changed. In Windows, it is the create time.</p> </item> - <tag><c>mode = integer()</c></tag> + <tag><c>mode = integer() >= 0</c></tag> <item> <p>The file permissions as the sum of the following bit values:</p> @@ -1278,33 +1314,33 @@ <p>On Unix platforms, other bits than those listed above may be set.</p> </item> - <tag><c>links = integer()</c></tag> + <tag><c>links = integer() >= 0</c></tag> <item> <p>Number of links to the file (this will always be 1 for file systems which have no concept of links).</p> </item> - <tag><c>major_device = integer()</c></tag> + <tag><c>major_device = integer() >= 0</c></tag> <item> <p>Identifies the file system where the file is located. In Windows, the number indicates a drive as follows: 0 means A:, 1 means B:, and so on.</p> </item> - <tag><c>minor_device = integer()</c></tag> + <tag><c>minor_device = integer() >= 0</c></tag> <item> <p>Only valid for character devices on Unix. In all other cases, this field is zero.</p> </item> - <tag><c>inode = integer()</c></tag> + <tag><c>inode = integer() >= 0</c></tag> <item> <p>Gives the <c>inode</c> number. On non-Unix file systems, this field will be zero.</p> </item> - <tag><c>uid = integer()</c></tag> + <tag><c>uid = integer() >= 0</c></tag> <item> <p>Indicates the owner of the file. Will be zero for non-Unix file systems.</p> </item> - <tag><c>gid = integer()</c></tag> + <tag><c>gid = integer() >= 0</c></tag> <item> <p>Gives the group that the owner of the file belongs to. Will be zero for non-Unix file systems.</p> @@ -1502,6 +1538,9 @@ of the error.</p> </item> </taglist> + <p>The encoding of of <c><anno>Filename</anno></c> can be set + by a comment as described in <seealso + marker="stdlib:epp#encoding">epp(3)</seealso>.</p> </desc> </func> <func> @@ -1732,22 +1771,22 @@ <p>The following fields are used from the record, if they are given.</p> <taglist> - <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</c></tag> + <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso> | integer() >= 0</c></tag> <item> <p>The last time the file was read.</p> </item> - <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</c></tag> + <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso> | integer() >= 0</c></tag> <item> <p>The last time the file was written.</p> </item> - <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</c></tag> + <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso> | integer() >= 0</c></tag> <item> <p>On Unix, any value give for this field will be ignored (the "ctime" for the file will be set to the current time). On Windows, this field is the new creation time to set for the file.</p> </item> - <tag><c>mode = integer()</c></tag> + <tag><c>mode = integer() >= 0</c></tag> <item> <p>The file permissions as the sum of the following bit values:</p> @@ -1778,15 +1817,15 @@ <p>On Unix platforms, other bits than those listed above may be set.</p> </item> - <tag><c>uid = integer()</c></tag> + <tag><c>uid = integer() >= 0</c></tag> <item> <p>Indicates the owner of the file. Ignored for non-Unix file systems.</p> </item> - <tag><c>gid = integer()</c></tag> + <tag><c>gid = integer() >= 0</c></tag> <item> <p>Gives the group that the owner of the file belongs to. - Ignored non-Unix file systems.</p> + Ignored for non-Unix file systems.</p> </item> </taglist> <p>Typical error reasons:</p> diff --git a/lib/kernel/doc/src/gen_sctp.xml b/lib/kernel/doc/src/gen_sctp.xml index e327a4f907..7ea58fffff 100644 --- a/lib/kernel/doc/src/gen_sctp.xml +++ b/lib/kernel/doc/src/gen_sctp.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2007</year><year>2011</year> + <year>2007</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml index 726dc30546..4850278a64 100644 --- a/lib/kernel/doc/src/gen_udp.xml +++ b/lib/kernel/doc/src/gen_udp.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2011</year> + <year>1997</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/kernel/doc/src/global.xml b/lib/kernel/doc/src/global.xml index 304a9b1d88..9c50049503 100644 --- a/lib/kernel/doc/src/global.xml +++ b/lib/kernel/doc/src/global.xml @@ -163,7 +163,8 @@ <fsummary>Globally register a name for a pid</fsummary> <type name="method"/> <type_desc name="method">{<c>Module</c>, <c>Function</c>} - is also allowed + is currently also allowed for backward compatibility, but its use is + deprecated </type_desc> <desc> <p>Globally associates the name <c><anno>Name</anno></c> with a pid, that is, @@ -180,6 +181,15 @@ unregistered. This function is called once for each name clash.</p> + <warning> + <p>If you plan to change code without restarting your system, + you must use an external fun (<c>fun Module:Function/Arity</c>) + as the <c><anno>Resolve</anno></c> function; if you use a + local fun you can never replace the code for the module that + the fun belongs to. + </p> + </warning> + <p>There are three pre-defined resolve functions: <c>random_exit_name/3</c>, <c>random_notify_name/3</c>, and <c>notify_all_name/3</c>. If no <c><anno>Resolve</anno></c> function is diff --git a/lib/kernel/doc/src/heart.xml b/lib/kernel/doc/src/heart.xml index 26d1e27822..2856d84dcf 100644 --- a/lib/kernel/doc/src/heart.xml +++ b/lib/kernel/doc/src/heart.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -71,6 +71,39 @@ timeout and try to reboot the system. This can happen, for example, if the system clock is adjusted automatically by use of NTP (Network Time Protocol).</p> + + <p> If a crash occurs, an <c><![CDATA[erl_crash.dump]]></c> will <em>not</em> be written + unless the environment variable <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> is set. + </p> + + <pre> +% <input>erl -heart -env ERL_CRASH_DUMP_SECONDS 10 ...</input></pre> + <p> + Furthermore, <c><![CDATA[ERL_CRASH_DUMP_SECONDS]]></c> has the following behaviour on + <c>heart</c>: + </p> + <taglist> + <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=0]]></c></tag> + <item><p> + Suppresses the writing a crash dump file entirely, + thus rebooting the runtime system immediately. + This is the same as not setting the environment variable. + </p> + </item> + <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=-1]]></c></tag> + <item><p> Setting the environment variable to a negative value will not reboot + the runtime system until the crash dump file has been completly written. + </p> + </item> + <tag><c><![CDATA[ERL_CRASH_DUMP_SECONDS=S]]></c></tag> + <item><p> + Heart will wait for <c>S</c> seconds to let the crash dump file be written. + After <c>S</c> seconds <c>heart</c> will reboot the runtime system regardless of + the crash dump file has been written or not. + </p> + </item> + </taglist> + <p>In the following descriptions, all function fails with reason <c>badarg</c> if <c>heart</c> is not started.</p> </description> diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml index 32b4a429dd..3d929a772e 100644 --- a/lib/kernel/doc/src/inet.xml +++ b/lib/kernel/doc/src/inet.xml @@ -323,8 +323,11 @@ fe80::204:acff:fe17:bf38 <type name="stat_option"/> <desc> <p>Gets one or more statistic options for a socket.</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> + <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> @@ -371,7 +374,51 @@ fe80::204:acff:fe17:bf38 </taglist> </desc> </func> - + <func> + <name name="parse_ipv4_address" arity="1" /> + <fsummary>Parse an IPv4 address</fsummary> + <desc> + <p>Parses an IPv4 address string and returns an <a href="#type-ip4_address">ip4_address()</a>. + Accepts a shortened IPv4 shortened address string.</p> + </desc> + </func> + <func> + <name name="parse_ipv4strict_address" arity="1" /> + <fsummary>Parse an IPv4 address strict.</fsummary> + <desc> + <p>Parses an IPv4 address string containing four fields, i.e <b>not</b> shortened, and returns an <a href="#type-ip4_adress">ip4_address()</a>.</p> + </desc> + </func> + <func> + <name name="parse_ipv6_address" arity="1" /> + <fsummary>Parse an IPv6 address</fsummary> + <desc> + <p>Parses an IPv6 address string and returns an <a href="#type-ip6_address">ip6_address()</a>. + If an IPv4 address string is passed, an IPv4-mapped IPv6 address is returned.</p> + </desc> + </func> + <func> + <name name="parse_ipv6strict_address" arity="1" /> + <fsummary>Parse an IPv6 address strict.</fsummary> + <desc> + <p>Parses an IPv6 address string and returns an <a href="#type-ip6_address">ip6_address()</a>. + Does <b>not</b> accept IPv4 adresses.</p> + </desc> + </func> + <func> + <name name="parse_address" arity="1" /> + <fsummary>Parse an IPv4 or IPv6 address.</fsummary> + <desc> + <p>Parses an IPv4 or IPv6 address string and returns an <a href="#type-ip4_address">ip4_address()</a> or <a href="#type-ip6_address">ip6_address()</a>. Accepts a shortened IPv4 address string.</p> + </desc> + </func> + <func> + <name name="parse_strict_address" arity="1" /> + <fsummary>Parse an IPv4 or IPv6 address strict.</fsummary> + <desc> + <p>Parses an IPv4 or IPv6 address string and returns an <a href="#type-ip4_address">ip4_address()</a> or <a href="#type-ip6_adress">ip6_address()</a>. Does <b>not</b> accept a shortened IPv4 address string.</p> + </desc> + </func> <func> <name name="peername" arity="1"/> <fsummary>Return the address and port for the other end of a connection</fsummary> @@ -512,13 +559,100 @@ fe80::204:acff:fe17:bf38 <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>{high_msgq_watermark, Size}</c> (TCP/IP sockets)</tag> + <item> + <p>The socket message queue will be set into a busy + state when the amount of data queued on the message + queue reaches this limit. Note that this limit only + concerns data that have not yet reached the ERTS internal + socket implementation. Default value used is 8 kB.</p> + <p>Senders of data to the socket will be suspended if + either the socket message queue is busy, or the socket + itself is busy.</p> + <p>For more information see the <c>low_msgq_watermark</c>, + <c>high_watermark</c>, and <c>low_watermark</c> options.</p> + <p>Note that distribution sockets will disable the use of + <c>high_msgq_watermark</c> and <c>low_msgq_watermark</c>, + and will instead use the + <seealso marker="erts:erlang#system_info_dist_buf_busy_limit">distribution + buffer busy limit</seealso> which is a similar feature.</p> + </item> + + <tag><c>{high_watermark, Size}</c> (TCP/IP sockets)</tag> + <item> + <p>The socket will be set into a busy state when the amount + of data queued internally by the ERTS socket implementation + reaches this limit. Default value used is 8 kB.</p> + <p>Senders of data to the socket will be suspended if + either the socket message queue is busy, or the socket + itself is busy.</p> + <p>For more information see the <c>low_watermark</c>, + <c>high_msgq_watermark</c>, and <c>low_msqg_watermark</c> + options.</p> + </item> + + <tag><c>{ipv6_v6only, Boolean}</c></tag> + <item> + <p> + Restricts the socket to only use IPv6, prohibiting any + IPv4 connections. This is only applicable for + IPv6 sockets (option <c>inet6</c>). + </p> + <p> + On most platforms this option has to be set on the socket + before associating it to an address. Therefore it is only + reasonable to give it when creating the socket and not + to use it when calling the function + (<seealso marker="#setopts/2">setopts/2</seealso>) + containing this description. + </p> + <p> + The behaviour of a socket with this socket option set to + <c>true</c> is becoming the only portable one. The original + idea when IPv6 was new of using IPv6 for all traffic + is now not recommended by FreeBSD (you can use + <c>{ipv6_v6only,false}</c> to override the recommended + system default value), + forbidden by OpenBSD (the supported GENERIC kernel) + and impossible on Windows (that has separate + IPv4 and IPv6 protocol stacks). Most Linux distros + still have a system default value of <c>false</c>. + This policy shift among operating systems towards + separating IPv6 from IPv4 traffic has evolved since + it gradually proved hard and complicated to get + a dual stack implementation correct and secure. + </p> + <p> + On some platforms the only allowed value for this option + is <c>true</c>, e.g. OpenBSD and Windows. Trying to set + this option to <c>false</c> when creating the socket + will in this case fail. + </p> + <p> + Setting this option on platforms where it does not exist + is ignored and getting this option with + <seealso marker="#getopts/2">getopts/2</seealso> + returns no value i.e the returned list will not contain an + <c>{ipv6_v6only,_}</c> tuple. On Windows the option acually + does not exist, but it is emulated as being a + read-only option with the value <c>true</c>. + </p> + <p> + So it boils down to that setting this option to <c>true</c> + when creating a socket will never fail except possibly + (at the time of this writing) on a platform where you + have customized the kernel to only allow <c>false</c>, + which might be doable (but weird) on e.g. OpenBSD. + </p> + <p> + If you read back the option value using + <seealso marker="#getopts/2">getopts/2</seealso> + and get no value the option does not exist in the host OS + and all bets are off regarding the behaviour of both + an IPv6 and an IPv4 socket listening on the same port + as well as for an IPv6 socket getting IPv4 traffic. + </p> + </item> <tag><c>{keepalive, Boolean}</c>(TCP/IP sockets)</tag> <item> @@ -540,14 +674,41 @@ fe80::204:acff:fe17:bf38 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>{low_msgq_watermark, Size}</c> (TCP/IP sockets)</tag> + <item> + <p>If the socket message queue is in a busy state, the + socket message queue will be set in a not busy state when + the amount of data queued in the message queue falls + below this limit. Note that this limit only concerns data + that have not yet reached the ERTS internal socket + implementation. Default value used is 4 kB.</p> + <p>Senders that have been suspended due to either a + busy message queue or a busy socket, will be resumed + when neither the socket message queue, nor the socket + are busy.</p> + <p>For more information see the <c>high_msgq_watermark</c>, + <c>high_watermark</c>, and <c>low_watermark</c> options.</p> + <p>Note that distribution sockets will disable the use of + <c>high_msgq_watermark</c> and <c>low_msgq_watermark</c>, + and will instead use the + <seealso marker="erts:erlang#system_info_dist_buf_busy_limit">distribution + buffer busy limit</seealso> which is a similar feature.</p> + </item> + + <tag><c>{low_watermark, Size}</c> (TCP/IP sockets)</tag> + <item> + <p>If the socket is in a busy state, the socket will + be set in a not busy state when the amount of data + queued internally by the ERTS socket implementation + falls below this limit. Default value used is 4 kB.</p> + <p>Senders that have been suspended due to either a + busy message queue or a busy socket, will be resumed + when neither the socket message queue, nor the socket + are busy.</p> + <p>For more information see the <c>high_watermark</c>, + <c>high_msgq_watermark</c>, and <c>low_msgq_watermark</c> + options.</p> + </item> <tag><c>{mode, Mode :: binary | list}</c></tag> <item> diff --git a/lib/kernel/doc/src/notes.xml b/lib/kernel/doc/src/notes.xml index 94624bf512..78bc533464 100644 --- a/lib/kernel/doc/src/notes.xml +++ b/lib/kernel/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2011</year> + <year>2004</year><year>2012</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -30,6 +30,135 @@ </header> <p>This document describes the changes made to the Kernel application.</p> +<section><title>Kernel 2.15.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Ensure 'erl_crash.dump' when asked for it. This will + change erl_crash.dump behaviour.</p> + <p> + * Not setting ERL_CRASH_DUMP_SECONDS will now terminate + beam immediately on a crash without writing a crash dump + file.</p> + <p> + * Setting ERL_CRASH_DUMP_SECONDS to 0 will also terminate + beam immediately on a crash without writing a crash dump + file, i.e. same as not setting ERL_CRASH_DUMP_SECONDS + environment variable.</p> + <p> + * Setting ERL_CRASH_DUMP_SECONDS to a negative value will + let the beam wait indefinitely on the crash dump file + being written.</p> + <p> + * Setting ERL_CRASH_DUMP_SECONDS to a positive value will + let the beam wait that many seconds on the crash dump + file being written.</p> + <p> + A positive value will set an alarm/timeout for restart + both in beam and in heart if heart is running.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10422 Aux Id: kunagi-250 [161] </p> + </item> + </list> + </section> + +</section> + +<section><title>Kernel 2.15.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Fixed issue where using controlling_process/2 with self() + as the second argument caused the port to leak if self() + crashes. (Thanks to Ricardo Catalinas Jim�nez)</p> + <p> + Own Id: OTP-10094</p> + </item> + <item> + <p> + When sending large files using the file:sendfile fallback + file:sendfile would crash. This is now fixed.</p> + <p> + Own Id: OTP-10098</p> + </item> + <item> + <p> + Fix rpc:call/5 for local calls with a finite Timeout + (Thanks to Tomer Chachamu)</p> + <p> + Own Id: OTP-10149</p> + </item> + <item> + <p> + fix escript/primary archive reloading</p> + <p> + If the mtime of an escript/primary archive file changes + after being added to the code path, correctly reload the + archive and update the cache. (Thanks to Tuncer Ayaz)</p> + <p> + Own Id: OTP-10151</p> + </item> + <item> + <p> + Support added for home directories named with non-ASCII + characters (codepoints above 127) on a system running in + Unicode file mode (e.g. on MacOSX or Linux with startup + arguments +fnu or +fna with the right LOCALE). Also + environment variables with Unicode content are supported + in applicable environments.</p> + <p> + Own Id: OTP-10160</p> + </item> + <item> + <p> + Allow mixed IPv4 and IPv6 addresses to sctp_bindx</p> + <p> + Also allow mixed address families to bind, since the + first address on a multihomed sctp socket must be bound + with bind, while the rest are to be bound using + sctp_bindx. At least Linux supports adding address of + mixing families. Make inet_set_faddress function + available also when HAVE_SCTP is not defined, since we + use it to find an address for bind to be able to mix ipv4 + and ipv6 addresses. Thanks to Tomas Abrahamsson</p> + <p> + Own Id: OTP-10217</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>Document inet options: high_watermark, priority, + linger and a some other options that previously was + undocumented.</p> + <p> + Own Id: OTP-10053</p> + </item> + <item> + <p>Remove bit8 option support from inet</p> + <p> + Own Id: OTP-10056</p> + </item> + <item> + <p> The type of the disk log header has been corrected. + (Thanks to Niclas Eklund.) </p> + <p> + Own Id: OTP-10131</p> + </item> + </list> + </section> + +</section> + <section><title>Kernel 2.15.1</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/kernel/doc/src/os.xml b/lib/kernel/doc/src/os.xml index 1bc5b9e464..5e182de41d 100644 --- a/lib/kernel/doc/src/os.xml +++ b/lib/kernel/doc/src/os.xml @@ -80,6 +80,10 @@ DirOut = os:cmd("dir"), % on Win32 platform</code> Each environment variable is given as a single string on the format <c>"VarName=Value"</c>, where <c>VarName</c> is the name of the variable and <c>Value</c> its value.</p> + <p>If Unicode file name encoding is in effect (see the <seealso + marker="erts:erl#file_name_encoding">erl manual + page</seealso>), the strings may contain characters with + codepoints > 255.</p> </desc> </func> <func> @@ -89,6 +93,10 @@ DirOut = os:cmd("dir"), % on Win32 platform</code> <p>Returns the <c><anno>Value</anno></c> of the environment variable <c><anno>VarName</anno></c>, or <c>false</c> if the environment variable is undefined.</p> + <p>If Unicode file name encoding is in effect (see the <seealso + marker="erts:erl#file_name_encoding">erl manual + page</seealso>), the strings (both <c><anno>VarName</anno></c> and + <c><anno>Value</anno></c>) may contain characters with codepoints > 255.</p> </desc> </func> <func> @@ -100,8 +108,7 @@ DirOut = os:cmd("dir"), % on Win32 platform</code> environment. <c><anno>Value</anno></c> is returned as a string containing the (usually) numerical identifier for a process. On Unix, this is typically the return value of the <c>getpid()</c> - system call. On VxWorks, <c><anno>Value</anno></c> contains the task id - (decimal notation) of the Erlang task. On Windows, + system call. On Windows, the process id as returned by the <c>GetCurrentProcessId()</c> system call is used.</p> </desc> @@ -112,6 +119,13 @@ DirOut = os:cmd("dir"), % on Win32 platform</code> <desc> <p>Sets a new <c><anno>Value</anno></c> for the environment variable <c><anno>VarName</anno></c>.</p> + <p>If Unicode filename encoding is in effect (see the <seealso + marker="erts:erl#file_name_encoding">erl manual + page</seealso>), the strings (both <c><anno>VarName</anno></c> and + <c><anno>Value</anno></c>) may contain characters with codepoints > 255.</p> + <p>On Unix platforms, the environment will be set using UTF-8 encoding + if Unicode file name translation is in effect. On Windows the + environment is set using wide character interfaces.</p> </desc> </func> <func> @@ -154,8 +168,6 @@ format_utc_timestamp() -> Solaris 1 and 2, it will be <c>sunos</c>.</p> <p>In Windows, <c><anno>Osname</anno></c> will be either <c>nt</c> (on Windows NT), or <c>windows</c> (on Windows 95).</p> - <p>On VxWorks the OS family alone is returned, that is - <c>vxworks</c>.</p> <note> <p>Think twice before using this function. Use the <c>filename</c> module if you want to inspect or build diff --git a/lib/kernel/doc/src/packages.xml b/lib/kernel/doc/src/packages.xml deleted file mode 100644 index 80de2e05fc..0000000000 --- a/lib/kernel/doc/src/packages.xml +++ /dev/null @@ -1,214 +0,0 @@ -<?xml version="1.0" encoding="latin1" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> - -<erlref> - <header> - <copyright> - <year>2004</year><year>2009</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. - - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. - - </legalnotice> - - <title>packages</title> - <prepared>Kenneth Lundin</prepared> - <responsible>Kenneth Lundin</responsible> - <docno>1</docno> - <approved>Kenneth Lundin</approved> - <checked></checked> - <date>2004-09-07</date> - <rev>A</rev> - <file>packages.sgml</file> - </header> - <module>packages</module> - <modulesummary>Packages in Erlang</modulesummary> - <description> - <warning><p> - Packages has since it was introduced more than 5 years ago been an - experimental feature. Use it at your own risk, we do not - actively maintain and develop this feature. It might however be - supported some - day. - </p> - <p> - In spite of this packages work quite well, but there are some - known issues in tools and other parts where packages don't work well. - </p> - </warning> - <p><em>Introduction</em></p> - <p>Packages are simply namespaces for modules. - All old Erlang modules automatically belong to the top level - ("empty-string") namespace, and do not need any changes.</p> - <p>The full name of a packaged module is written as e.g. - "<c>fee.fie.foe.foo</c>", - i.e., as atoms separated by periods, - where the package name is the part up to - but not including the last period; - in this case "<c>fee.fie.foe</c>". - A more concrete example is the module <c>erl.lang.term</c>, - which is in the - package <c>erl.lang</c>. - Package names can have any number of segments, as in - <c>erl.lang.list.sort</c>. - The atoms in the name can be quoted, as in <c>foo.'Bar'.baz</c>, - or even the - whole name, as in <c>'foo.bar.baz'</c> but the concatenation of - atoms and - periods must not contain two consecutive period characters or - end with a period, - as in <c>'foo..bar'</c>, <c>foo.'.bar'</c>, or <c>foo.'bar.'</c>. - The periods must not be followed by whitespace.</p> - <p>The code loader maps module names onto the file system directory - structure. - E.g., the module <c>erl.lang.term</c> corresponds to a file - <c>.../erl/lang/term.beam</c> - in the search path. - Note that the name of the actual object file corresponds to - the last part only of the full module name. - (Thus, old existing modules such as <c>lists</c> - simply map to <c>.../lists.beam</c>, exactly as before.)</p> - <p>A packaged module in a file "<c>foo/bar/fred.erl</c>" is declared - as:</p> - <code type="none"> --module(foo.bar.fred).</code> - <p>This can be compiled and loaded from the Erlang shell using - <c>c(fred)</c>, if - your current directory is the same as that of the file. - The object file will be named <c>fred.beam</c>.</p> - <p>The Erlang search path works exactly as before, - except that the package segments will be appended to each - directory in the path in order to find the - file. E.g., assume the path is <c>["/usr/lib/erl", "/usr/local/lib/otp/legacy/ebin", "/home/barney/erl"]</c>. - Then, the code for a module named <c>foo.bar.fred</c> will be - searched for - first as <c>"/usr/lib/erl/foo/bar/fred.beam"</c>, then - <c>"/usr/local/lib/otp/legacy/ebin/foo/bar/fred.beam"</c> - and lastly <c>"/home/barney/erl/foo/bar/fred.beam"</c>. - A module - like <c>lists</c>, which is in the top-level package, - will be looked for as <c>"/usr/lib/erl/lists.beam"</c>, - <c>"/usr/local/lib/otp/legacy/ebin/lists.beam"</c> and - <c>"/home/barney/erl/lists.beam"</c>.</p> - <p><em>Programming</em></p> - <p>Normally, if a call is made from one module to another, - it is assumed that the - called module belongs to the same package as the source module. - The compiler - automatically expands such calls. E.g., in:</p> - <code type="none"> --module(foo.bar.m1). --export([f/1]). - -f(X) -> m2:g(X).</code> - <p><c>m2:g(X)</c> becomes a call to <c>foo.bar.m2</c> - If this is not what was intended, the call can be written - explicitly, as in</p> - <code type="none"> --module(foo.bar.m1). --export([f/1]). - -f(X) -> fee.fie.foe.m2:g(X).</code> - <p>Because the called module is given with an explicit package name, - no expansion is done in this case.</p> - <p>If a module from another package is used repeatedly in a module, - an import declaration can make life easier:</p> - <code type="none"> --module(foo.bar.m1). --export([f/1, g/1]). --import(fee.fie.foe.m2). - -f(X) -> m2:g(X). -g(X) -> m2:h(X).</code> - <p>will make the calls to <c>m2</c> refer to <c>fee.fie.foe.m2</c>. - More generally, a declaration <c>-import(Package.Module).</c> - will cause calls to <c>Module</c> - to be expanded to <c>Package.Module</c>.</p> - <p>Old-style function imports work as normal (but full module - names must be - used); e.g.:</p> - <code type="none"> --import(fee.fie.foe.m2, [g/1, h/1]).</code> - <p>however, it is probably better to avoid this form of import - altogether in new - code, since it makes it hard to see what calls are really "remote".</p> - <p>If it is necessary to call a module in the top-level package - from within a - named package, the module name can be written either with an - initial period as - in e.g. "<c>.lists</c>", or with an empty initial atom, as in - "<c>''.lists</c>". - However, the best way is to use an import declaration - - this is most obvious to - the eye, and makes sure we don't forget adding a period somewhere:</p> - <code type="none"> --module(foo.bar.fred). --export([f/1]). --import(lists). - -f(X) -> lists:reverse(X).</code> - <p>The dot-syntax for module names can be used in any expression. - All segments must - be constant atoms, and the result must be a well-formed - package/module name. - E.g.:</p> - <code type="none"> -spawn(foo.bar.fred, f, [X])</code> - <p>is equivalent to <c>spawn('foo.bar.fred', f, [X])</c>.</p> - <p><em>The Erlang Shell</em></p> - <p>The shell also automatically expands remote calls, - however currently no - expansions are made by default. - The user can change the behaviour by using the <c>import/1</c> - shell command (or its abbreviation <c>use/1</c>). E.g.:</p> - <pre> -1> <input>import(foo.bar.m).</input> -ok -2> <input>m:f().</input></pre> - <p>will evaluate <c>foo.bar.m:f()</c>. - If a new import is made of the same name, - this overrides any previous import. - (It is likely that in the future, some - system packages will be pre-imported.)</p> - <p>In addition, the shell command <c>import_all/1</c> - (and its alias <c>use_all/1</c>) - imports all modules currently found in the path for a given - package name. E.g., - assuming the files "<c>.../foo/bar/fred.beam</c>", - "<c>.../foo/bar/barney.beam</c>" - and "<c>.../foo/bar/bambam.beam</c>" can be found from our current - path,</p> - <pre> -1> <input>import_all(foo.bar).</input></pre> - <p>will make <c>fred</c>, <c>barney</c> and <c>bambam</c> - expand to <c>foo.bar.fred</c>, - <c>foo.bar.barney</c> and <c>foo.bar.bambam</c>, respectively.</p> - <p>Note: The compiler does not have an "import all" directive, for the - reason that Erlang has no compile time type checking. - E.g. if the wrong search - path is used at compile time, a call <c>m:f(...)</c> - could be expanded to <c>foo.bar.m:f(...)</c> - without any warning, instead of the intended - <c>frob.ozz.m:f(...)</c>, if - package <c>foo.bar</c> happens to be found first in the path. - Explicitly - declaring each use of a module makes for safe code.</p> - </description> - <funcs> - <func> - <name>no functions exported</name> - <fsummary>x</fsummary> - </func> - </funcs> -</erlref> - diff --git a/lib/kernel/doc/src/ref_man.xml b/lib/kernel/doc/src/ref_man.xml index 9ef0959271..67d91ba585 100644 --- a/lib/kernel/doc/src/ref_man.xml +++ b/lib/kernel/doc/src/ref_man.xml @@ -64,6 +64,5 @@ <xi:include href="zlib_stub.xml"/> <xi:include href="app.xml"/> <xi:include href="config.xml"/> - <xi:include href="packages.xml"/> </application> |