diff options
Diffstat (limited to 'lib/kernel/doc/src')
| -rw-r--r-- | lib/kernel/doc/src/Makefile | 1 | ||||
| -rw-r--r-- | lib/kernel/doc/src/application.xml | 9 | ||||
| -rw-r--r-- | lib/kernel/doc/src/file.xml | 40 | ||||
| -rw-r--r-- | lib/kernel/doc/src/inet.xml | 132 | ||||
| -rw-r--r-- | lib/kernel/doc/src/packages.xml | 208 | ||||
| -rw-r--r-- | lib/kernel/doc/src/ref_man.xml | 1 |
6 files changed, 161 insertions, 230 deletions
diff --git a/lib/kernel/doc/src/Makefile b/lib/kernel/doc/src/Makefile index 5e04bff0c1..de3ca1e176 100644 --- a/lib/kernel/doc/src/Makefile +++ b/lib/kernel/doc/src/Makefile @@ -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/file.xml b/lib/kernel/doc/src/file.xml index b2a259080d..e30ade1bd2 100644 --- a/lib/kernel/doc/src/file.xml +++ b/lib/kernel/doc/src/file.xml @@ -110,7 +110,7 @@ <desc> <p>As returned by <seealso marker="#open/2">file:open/2</seealso>, - a process handling IO protocols.</p> + a process handling I/O-protocols.</p> </desc> </datatype> <datatype> @@ -170,6 +170,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 +273,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 +414,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 +628,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> @@ -767,6 +785,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 +883,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 +927,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 +999,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"/> @@ -1502,6 +1533,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> diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml index f498a88c5e..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,37 @@ 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> @@ -603,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/packages.xml b/lib/kernel/doc/src/packages.xml deleted file mode 100644 index 8a82b91a90..0000000000 --- a/lib/kernel/doc/src/packages.xml +++ /dev/null @@ -1,208 +0,0 @@ -<?xml version="1.0" encoding="latin1" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> - -<erlref> - <header> - <copyright> - <year>2004</year><year>2012</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> -</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> |