diff options
Diffstat (limited to 'lib/kernel/doc')
| -rw-r--r-- | lib/kernel/doc/src/Makefile | 1 | ||||
| -rw-r--r-- | lib/kernel/doc/src/application.xml | 11 | ||||
| -rw-r--r-- | lib/kernel/doc/src/code.xml | 26 | ||||
| -rw-r--r-- | lib/kernel/doc/src/erl_ddll.xml | 159 | ||||
| -rw-r--r-- | lib/kernel/doc/src/error_handler.xml | 53 | ||||
| -rw-r--r-- | lib/kernel/doc/src/error_logger.xml | 5 | ||||
| -rw-r--r-- | lib/kernel/doc/src/file.xml | 189 | ||||
| -rw-r--r-- | lib/kernel/doc/src/global.xml | 14 | ||||
| -rw-r--r-- | lib/kernel/doc/src/inet.xml | 207 | ||||
| -rw-r--r-- | lib/kernel/doc/src/notes.xml | 231 | ||||
| -rw-r--r-- | lib/kernel/doc/src/os.xml | 49 | ||||
| -rw-r--r-- | lib/kernel/doc/src/packages.xml | 208 | ||||
| -rw-r--r-- | lib/kernel/doc/src/ref_man.xml | 3 | ||||
| -rw-r--r-- | lib/kernel/doc/src/specs.xml | 1 |
14 files changed, 717 insertions, 440 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..697de6681f 100644 --- a/lib/kernel/doc/src/application.xml +++ b/lib/kernel/doc/src/application.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -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 08d8f49ef6..6f04741f85 100644 --- a/lib/kernel/doc/src/code.xml +++ b/lib/kernel/doc/src/code.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> @@ -728,19 +728,29 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), </desc> </func> <func> - <name>is_module_native(Module) -> boolean() | undefined</name> + <name name="is_module_native" arity="1"/> <fsummary>Test whether a module has native code</fsummary> - <type> - <v>Module = module()</v> - </type> <desc> - <p>This function returns <c>true</c> if <c>Module</c> is + <p>This function returns <c>true</c> if <c><anno>Module</anno></c> is name of a loaded module that has native code loaded, and - <c>false</c> if <c>Module</c> is loaded but does not have - native. If <c>Module</c> is not loaded, this function returns + <c>false</c> if <c><anno>Module</anno></c> is loaded but does not have + native. If <c><anno>Module</anno></c> is not loaded, this function returns <c>undefined</c>.</p> </desc> </func> + + <func> + <name name="get_mode" arity="0"/> + <fsummary>The code_server's mode.</fsummary> + <desc> + <p>This function returns an atom describing the code_server's mode: + <c>interactive</c> or <c>embedded</c>. </p> + <p>This information is useful when an external entity (for example, + an IDE) provides additional code for a running node. If in interactive + mode, it only needs to add to the code path. If in embedded mode, + the code has to be loaded with <c>load_binary/3</c></p> + </desc> + </func> </funcs> </erlref> diff --git a/lib/kernel/doc/src/erl_ddll.xml b/lib/kernel/doc/src/erl_ddll.xml index 1911fb628e..26db11cfcd 100644 --- a/lib/kernel/doc/src/erl_ddll.xml +++ b/lib/kernel/doc/src/erl_ddll.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> @@ -182,11 +182,8 @@ </datatypes> <funcs> <func> - <name>demonitor(MonitorRef) -> ok</name> + <name name="demonitor" arity="1"/> <fsummary>Remove a monitor for a driver</fsummary> - <type> - <v>MonitorRef = reference()</v> - </type> <desc> <p>Removes a driver monitor in much the same way as <seealso marker="erts:erlang#erlang:demonitor/1">erlang:demonitor/1</seealso> does with process @@ -232,24 +229,19 @@ </desc> </func> <func> - <name>info(Name, Tag) -> Value</name> + <name name="info" arity="2"/> <fsummary>Retrieve specific information about one driver</fsummary> - <type> - <v>Name = string() | atom()</v> - <v>Tag = processes | driver_options | port_count | linked_in_driver | permanent | awaiting_load | awaiting_unload</v> - <v>Value = term()</v> - </type> <desc> <p>This function returns specific information about one aspect - of a driver. The <c>Tag</c> parameter specifies which aspect - to get information about. The <c>Value</c> return differs + of a driver. The <c><anno>Tag</anno></c> parameter specifies which aspect + to get information about. The <c><anno>Value</anno></c> return differs between different tags:</p> <taglist> <tag><em>processes</em></tag> <item> <p>Return all processes containing <seealso marker="#users">users</seealso> of the specific drivers - as a list of tuples <c>{pid(),int()}</c>, where the - <c>int()</c> denotes the number of users in the process + as a list of tuples <c>{pid(),integer() >= 0}</c>, where the + <c>integer()</c> denotes the number of users in the process <c>pid()</c>.</p> </item> <tag><em>driver_options</em></tag> @@ -261,16 +253,16 @@ </item> <tag><em>port_count</em></tag> <item> - <p>Return the number of ports (an <c>int()</c>) using the driver.</p> + <p>Return the number of ports (an <c>integer >= 0()</c>) using the driver.</p> </item> <tag><em>linked_in_driver</em></tag> <item> - <p>Return a <c>bool()</c>, being <c>true</c> if the driver is a + <p>Return a <c>boolean()</c>, being <c>true</c> if the driver is a statically linked in one and <c>false</c> otherwise.</p> </item> <tag><em>permanent</em></tag> <item> - <p>Return a <c>bool()</c>, being <c>true</c> if the driver has made + <p>Return a <c>boolean()</c>, being <c>true</c> if the driver has made itself permanent (and is <em>not</em> a statically linked in driver). <c>false</c> otherwise.</p> </item> @@ -278,14 +270,14 @@ <item> <p>Return a list of all processes having monitors for <c>loading</c> active, each process returned as - <c>{pid(),int()}</c>, where the <c>int()</c> is the + <c>{pid(),integer() >= 0}</c>, where the <c>integer()</c> is the number of monitors held by the process <c>pid()</c>.</p> </item> <tag><em>awaiting_unload</em></tag> <item> <p>Return a list of all processes having monitors for <c>unloading</c> active, each process returned as - <c>{pid(),int()}</c>, where the <c>int()</c> is the + <c>{pid(),integer() >= 0}</c>, where the <c>integer()</c> is the number of monitors held by the process <c>pid()</c>.</p> </item> </taglist> @@ -377,41 +369,34 @@ </desc> </func> <func> - <name>monitor(Tag, Item) -> MonitorRef</name> + <name name="monitor" arity="2"/> <fsummary>Create a monitor for a driver</fsummary> - <type> - <v>Tag = driver </v> - <v>Item = {Name, When}</v> - <v>Name = atom() | string()</v> - <v>When = loaded | unloaded | unloaded_only</v> - <v>MonitorRef = reference()</v> - </type> <desc> <p>This function creates a driver monitor and works in many ways as the function <seealso marker="erts:erlang#erlang:monitor/2">erlang:monitor/2</seealso>, does for processes. When a driver changes state, the monitor results in a monitor-message being sent to the calling - process. The <c>MonitorRef</c> returned by this function is + process. The <c><anno>MonitorRef</anno></c> returned by this function is included in the message sent.</p> <p>As with process monitors, each driver monitor set will only generate <em>one single message</em>. The monitor is "destroyed" after the message is sent and there is then no need to call <seealso marker="#demonitor/1">demonitor/1</seealso>.</p> - <p>The <c>MonitorRef</c> can also be used in subsequent calls + <p>The <c><anno>MonitorRef</anno></c> can also be used in subsequent calls to <seealso marker="#demonitor/1">demonitor/1</seealso> to remove a monitor.</p> <p>The function accepts the following parameters:</p> <taglist> - <tag><em>Tag</em></tag> + <tag><em><anno>Tag</anno></em></tag> <item> <p>The monitor tag is always <c>driver</c> as this function can only be used to create driver monitors. In the future, driver monitors will be integrated with process monitors, why this parameter has to be given for consistence.</p> </item> - <tag><em>Item</em></tag> + <tag><em><anno>Item</anno></em></tag> <item> - <p>The <c>Item</c> parameter specifies which driver one + <p>The <c><anno>Item</anno></c> parameter specifies which driver one wants to monitor (the name of the driver) as well as which state change one wants to monitor. The parameter is a tuple of arity two whose first element is the @@ -588,22 +573,8 @@ </desc> </func> <func> - <name>try_load(Path, Name, OptionList) -> {ok,Status} | {ok, PendingStatus, Ref} | {error, ErrorDesc}</name> + <name name="try_load" arity="3"/> <fsummary>Load a driver</fsummary> - <type> - <v>Path = Name = string() | atom()</v> - <v>OptionList = [ Option ]</v> - <v>Option = {driver_options, DriverOptionList} | {monitor, MonitorOption} | {reload, ReloadOption}</v> - <v>DriverOptionList = [ DriverOption ]</v> - <v>DriverOption = kill_ports</v> - <v>MonitorOption = pending_driver | pending</v> - <v>ReloadOption = pending_driver | pending</v> - <v>Status = loaded | already_loaded | PendingStatus </v> - <v>PendingStatus = pending_driver | pending_process</v> - <v>Ref = reference()</v> - <v>ErrorDesc = ErrorAtom | OpaqueError</v> - <v>ErrorAtom = linked_in_driver | inconsistent | permanent | not_loaded_by_this_process | not_loaded | pending_reload | pending_process</v> - </type> <desc> <p>This function provides more control than the <c>load/2</c>/<c>reload/2</c> and @@ -655,65 +626,65 @@ <p>When the function returns <c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c>, one might want to get information about when the driver is <em>actually</em> loaded. This can - be achieved by using the <c>{monitor, PendingOption}</c> option.</p> + be achieved by using the <c>{monitor, <anno>MonitorOption</anno>}</c> option.</p> <p>When monitoring is requested, and a corresponding <c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c> would be - returned, the function will instead return a tuple <c>{ok, PendingStatus, reference()}</c> and the process will, at a later + returned, the function will instead return a tuple <c>{ok, <anno>PendingStatus</anno>, reference()}</c> and the process will, at a later time when the driver actually gets loaded, get a monitor message. The monitor message one can expect is described in the <seealso marker="#monitor/2">monitor/2</seealso> function description. </p> <note> <p>Note that in case of loading, monitoring can - <em>not</em> only get triggered by using the <c>{reload, ReloadOption}</c> option, but also in special cases where + <em>not</em> only get triggered by using the <c>{reload, <anno>ReloadOption</anno>}</c> option, but also in special cases where the load-error is transient, why <c>{monitor, pending_driver}</c> should be used under basically <em>all</em> real world circumstances!</p> </note> <p>The function accepts the following parameters:</p> <taglist> - <tag><em>Path</em></tag> + <tag><em><anno>Path</anno></em></tag> <item> <p>The filesystem path to the directory where the driver object file is situated. The filename of the object file (minus extension) must correspond to the driver name (used in the name parameter) and the driver must identify itself with the very same name. The - <c>Path</c> might be provided as an <em>io_list</em>, - meaning it can be a list of other io_lists, characters + <c><anno>Path</anno></c> might be provided as an <em>iolist()</em>, + meaning it can be a list of other <c>iolist()</c>s, characters (eight bit integers) or binaries, all to be flattened into a sequence of characters.</p> - <p>The (possibly flattened) <c>Path</c> parameter must be + <p>The (possibly flattened) <c><anno>Path</anno></c> parameter must be consistent throughout the system, a driver should, by all <seealso marker="#users">users</seealso>, be loaded - using the same <em>literal</em><c>Path</c>. The + using the same <em>literal</em><c><anno>Path</anno></c>. The exception is when <em>reloading</em> is requested, in - which case the <c>Path</c> may be specified + which case the <c><anno>Path</anno></c> may be specified differently. Note that all <seealso marker="#users">users</seealso> trying to load the - driver at a later time will need to use the <em>new</em><c>Path</c> if the <c>Path</c> is changed using a + driver at a later time will need to use the <em>new</em><c><anno>Path</anno></c> if the <c><anno>Path</anno></c> is changed using a <c>reload</c> option. This is yet another reason to have <em>only one loader</em> of a driver one wants to upgrade in a running system! </p> </item> - <tag><em>Name</em></tag> + <tag><em><anno>Name</anno></em></tag> <item> <p>The name parameter is the name of the driver to be used in subsequent calls to <seealso marker="erts:erlang#open_port/2">open_port</seealso>. The - name can be specified either as an <c>io_list()</c> or + name can be specified either as an <c>iolist()</c> or as an <c>atom()</c>. The name given when loading is used to find the actual object file (with the - help of the <c>Path</c> and the system implied + help of the <c><anno>Path</anno></c> and the system implied extension suffix, i.e. <c>.so</c>). The name by which the driver identifies itself must also be consistent - with this <c>Name</c> parameter, much as a beam-file's + with this <c><anno>Name</anno></c> parameter, much as a beam-file's module name much correspond to its filename.</p> </item> - <tag><em>OptionList</em></tag> + <tag><em><anno>OptionList</anno></em></tag> <item> <p>A number of options can be specified to control the loading operation. The options are given as a list of two-tuples, the tuples having the following values and meanings:</p> <taglist> - <tag><em>{driver_options, DriverOptionsList}</em></tag> + <tag><em>{driver_options, <anno>DriverOptionList</anno>}</em></tag> <item> <p>This option is to provide options that will change its general behavior and will "stick" to the driver @@ -729,14 +700,14 @@ when the last <seealso marker="#users">user</seealso> calls <seealso marker="#try_unload/2">try_unload/2</seealso>, or the last process having loaded the driver exits.</p> </item> - <tag><em>{monitor, MonitorOption}</em></tag> + <tag><em>{monitor, <anno>MonitorOption</anno>}</em></tag> <item> - <p>A <c>MonitorOption</c> tells <c>try_load/3</c> to + <p>A <c><anno>MonitorOption</anno></c> tells <c>try_load/3</c> to trigger a driver monitor under certain conditions. When the monitor is triggered, the - function will return a three-tuple <c>{ok, PendingStatus, reference()}</c>, where the <c>reference()</c> is + function will return a three-tuple <c>{ok, <anno>PendingStatus</anno>, reference()}</c>, where the <c>reference()</c> is the monitor ref for the driver monitor.</p> - <p>Only one <c>MonitorOption</c> can be specified and + <p>Only one <c><anno>MonitorOption</anno></c> can be specified and it is either the atom <c>pending</c>, which means that a monitor should be created whenever a load operation is delayed, and the atom @@ -747,7 +718,7 @@ is present for completeness, it is very well defined which reload-options might give rise to which delays. It might, however, be a good idea to use the - same <c>MonitorOption</c> as the <c>ReloadOption</c> + same <c><anno>MonitorOption</anno></c> as the <c><anno>ReloadOption</anno></c> if present.</p> <p>If reloading is not requested, it might still be useful to specify the <c>monitor</c> option, as @@ -760,12 +731,12 @@ <c>{monitor, pending_driver}</c> in production code (see the monitor discussion above). </p> </item> - <tag><em>{reload,RealoadOption}</em></tag> + <tag><em>{reload,<anno>ReloadOption</anno>}</em></tag> <item> <p>This option is used when one wants to <em>reload</em> a driver from disk, most often in a code upgrade scenario. Having a <c>reload</c> option - also implies that the <c>Path</c> parameter need + also implies that the <c><anno>Path</anno></c> parameter need <em>not</em> be consistent with earlier loads of the driver.</p> <p>To reload a driver, the process needs to have previously @@ -814,9 +785,9 @@ <tag><em>{error,inconsistent}</em></tag> <item> <p>The driver has already been loaded with either other - <c>DriverOptions</c> or a different <em>literal</em><c>Path</c> argument.</p> + <c><anno>DriverOptionList</anno></c> or a different <em>literal</em><c>Path</c> argument.</p> <p>This can happen even if a <c>reload</c> option is given, - if the <c>DriverOptions</c> differ from the current.</p> + if the <c>DriverOptionList</c> differ from the current.</p> </item> <tag><em>{error, permanent}</em></tag> <item> @@ -830,19 +801,19 @@ </item> <tag><em>{error, pending_reload}</em></tag> <item> - <p>Driver reload is already requested by another <seealso marker="#users">user</seealso> when the <c>{reload, ReloadOption}</c> option was given.</p> + <p>Driver reload is already requested by another <seealso marker="#users">user</seealso> when the <c>{reload, <anno>ReloadOption</anno>}</c> option was given.</p> </item> <tag><em>{error, not_loaded_by_this_process}</em></tag> <item> <p>Appears when the <c>reload</c> option is given. The - driver <c>Name</c> is present in the system, but there is no + driver <c><anno>Name</anno></c> is present in the system, but there is no <seealso marker="#users">user</seealso> of it in this process.</p> </item> <tag><em>{error, not_loaded}</em></tag> <item> <p>Appears when the <c>reload</c> option is given. The - driver <c>Name</c> is not in the system. Only drivers + driver <c><anno>Name</anno></c> is not in the system. Only drivers loaded by this process can be reloaded.</p> </item> </taglist> @@ -856,18 +827,8 @@ </desc> </func> <func> - <name>try_unload(Name, OptionList) -> {ok,Status} | {ok, PendingStatus, Ref} | {error, ErrorAtom}</name> + <name name="try_unload" arity="2"/> <fsummary>Unload a driver</fsummary> - <type> - <v>Name = string() | atom()</v> - <v>OptionList = [ Option ]</v> - <v>Option = {monitor, MonitorOption} | kill_ports</v> - <v>MonitorOption = pending_driver | pending</v> - <v>Status = unloaded | PendingStatus </v> - <v>PendingStatus = pending_driver | pending_process</v> - <v>Ref = reference()</v> - <v>ErrorAtom = linked_in_driver | not_loaded | not_loaded_by_this_process | permanent</v> - </type> <desc> <p>This is the low level function to unload (or decrement reference counts of) a driver. It can be used to force port @@ -948,15 +909,15 @@ </taglist> <p>The function accepts the following parameters:</p> <taglist> - <tag><em>Name</em></tag> + <tag><em><anno>Name</anno></em></tag> <item> <p>The name parameter is the name of the driver to be unloaded. The name can be specified either as an - <c>io_list()</c> or as an <c>atom()</c>. </p> + <c>iolist()</c> or as an <c>atom()</c>. </p> </item> - <tag><em>OptionList</em></tag> + <tag><em><anno>OptionList</anno></em></tag> <item> - <p>The <c>OptionList</c> argument can be used to specify + <p>The <c><anno>OptionList</anno></c> argument can be used to specify certain behavior regarding ports as well as triggering monitors under certain conditions:</p> <taglist> @@ -972,10 +933,10 @@ unloads, one should use the driver option <c>kill_ports</c> when loading the driver instead.</p> </item> - <tag><em>{monitor, MonitorOption}</em></tag> + <tag><em>{monitor, <anno>MonitorOption</anno>}</em></tag> <item> <p>This option creates a driver monitor if the condition - given in <c>MonitorOptions</c> is true. The valid + given in <c><anno>MonitorOption</anno></c> is true. The valid options are:</p> <taglist> <tag><em>pending_driver</em></tag> @@ -989,7 +950,7 @@ <c>{ok, pending_driver}</c> or <c>{ok, pending_process}</c>.</p> </item> </taglist> - <p>The <c>pending_driver</c> <c>MonitorOption</c> is by far + <p>The <c>pending_driver</c> <c><anno>MonitorOption</anno></c> is by far the most useful and it has to be used to ensure that the driver has really been unloaded and the ports closed whenever the <c>kill_ports</c> option is used or the @@ -1016,11 +977,11 @@ </item> <tag><em>{error, not_loaded}</em></tag> <item> - <p>The driver <c>Name</c> is not present in the system.</p> + <p>The driver <c><anno>Name</anno></c> is not present in the system.</p> </item> <tag><em>{error, not_loaded_by_this_process}</em></tag> <item> - <p>The driver <c>Name</c> is present in the system, but + <p>The driver <c><anno>Name</anno></c> is present in the system, but there is no <seealso marker="#users">user</seealso> of it in this process. </p> <p>As a special case, drivers can be unloaded from @@ -1088,12 +1049,8 @@ </desc> </func> <func> - <name>loaded_drivers() -> {ok, Drivers}</name> + <name name="loaded_drivers" arity="0"/> <fsummary>List loaded drivers</fsummary> - <type> - <v>Drivers = [Driver]</v> - <v>Driver = string()</v> - </type> <desc> <p>Returns a list of all the available drivers, both (statically) linked-in and dynamically loaded ones.</p> diff --git a/lib/kernel/doc/src/error_handler.xml b/lib/kernel/doc/src/error_handler.xml index acbf9a2c6e..84ec3927c8 100644 --- a/lib/kernel/doc/src/error_handler.xml +++ b/lib/kernel/doc/src/error_handler.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2011</year> + <year>2013</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -43,19 +43,52 @@ 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> + <warning> + <p>Defining <c>'$handle_undefined_function'/2</c> in + ordinary application code is highly discouraged. It is very + easy to make subtle errors that can take a long time to + debug. Furthermore, none of the tools for static code + analysis (such as Dialyzer and Xref) supports the use of + <c>'$handle_undefined_function'/2</c> and no such support + will be added. Only use this function after having carefully + considered other, less dangerous, solutions. One example of + potential legitimate use is creating stubs for other + sub-systems during testing and debugging. + </p> + </warning> + <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/error_logger.xml b/lib/kernel/doc/src/error_logger.xml index ec3274965a..cd86b364f6 100644 --- a/lib/kernel/doc/src/error_logger.xml +++ b/lib/kernel/doc/src/error_logger.xml @@ -127,11 +127,8 @@ ok</pre> </desc> </func> <func> - <name>warning_map() -> Tag</name> + <name name="warning_map" arity="0"/> <fsummary>Return the current mapping for warning events</fsummary> - <type> - <v>Tag = error | warning | info</v> - </type> <desc> <p>Returns the current mapping for warning events. Events sent using <c>warning_msg/1,2</c> or <c>warning_report/1,2</c> diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml index 772eff13cc..66ecba1bf2 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>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -60,14 +60,6 @@ converted, why the Unicode mode for file names is not default on systems having completely transparent file naming.</p> - <note> - <p>As of R14B01, the most basic file handling modules - (<c>file</c>, <c>prim_file</c>, <c>filelib</c> and - <c>filename</c>) accept raw file names, but the rest of OTP is not - guaranteed to handle them, why Unicode file naming on systems - where it is not default is still considered experimental.</p> - </note> - <p>Raw file names is a new feature in OTP R14B01, which allows the user to supply completely uninterpreted file names to the underlying OS/filesystem. They are supplied as binaries, where it @@ -100,17 +92,24 @@ <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"/> </datatype> <datatype> + <name name="filename_all"/> + </datatype> + <datatype> <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> @@ -118,6 +117,14 @@ <desc> <p>If VM is in Unicode filename mode, <c>string()</c> and <c>char()</c> are allowed to be > 255. + </p> + </desc> + </datatype> + <datatype> + <name name="name_all"/> + <desc> + <p>If VM is in Unicode filename mode, <c>string()</c> and <c>char()</c> + are allowed to be > 255. <c><anno>RawFilename</anno></c> is a filename not subject to Unicode translation, meaning that it can contain characters not conforming to @@ -152,9 +159,6 @@ <datatype> <name name="file_info_option"/> </datatype> - <datatype> - <name name="sendfile_option"/> - </datatype> </datatypes> <funcs> @@ -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> @@ -412,7 +434,7 @@ </desc> </func> <func> - <name>file_info(Filename) -> {ok, FileInfo} | {error, Reason}</name> + <name name="file_info" arity="1"/> <fsummary>Get information about a file (deprecated)</fsummary> <desc> <p>This function is obsolete. Use <c>read_file_info/1,2</c> @@ -482,7 +504,8 @@ <name name="list_dir" arity="1"/> <fsummary>List files in a directory</fsummary> <desc> - <p>Lists all the files in a directory. Returns + <p>Lists all files in a directory, <b>except</b> files + with "raw" names. Returns <c>{ok, <anno>Filenames</anno>}</c> if successful. Otherwise, it returns <c>{error, <anno>Reason</anno>}</c>. <c><anno>Filenames</anno></c> is a list of @@ -499,6 +522,37 @@ <item> <p>The directory does not exist.</p> </item> + <tag><c>{no_translation, <anno>Filename</anno>}</c></tag> + <item> + <p><c><anno>Filename</anno></c> is a <c>binary()</c> with + characters coded in ISO-latin-1 and the VM was started + with the parameter <c>+fnue</c>.</p> + </item> + </taglist> + </desc> + </func> + <func> + <name name="list_dir_all" arity="1"/> + <fsummary>List all files in a directory</fsummary> + <desc> + <p>Lists all the files in a directory, including files with + "raw" names. + Returns <c>{ok, <anno>Filenames</anno>}</c> if successful. + Otherwise, it returns <c>{error, <anno>Reason</anno>}</c>. + <c><anno>Filenames</anno></c> is a list of + the names of all the files in the directory. The names are + not sorted.</p> + <p>Typical error reasons are:</p> + <taglist> + <tag><c>eacces</c></tag> + <item> + <p>Missing search or write permissions for <c><anno>Dir</anno></c> + or one of its parent directories.</p> + </item> + <tag><c>enoent</c></tag> + <item> + <p>The directory does not exist.</p> + </item> </taglist> </desc> </func> @@ -598,7 +652,7 @@ </desc> </func> <func> - <name>native_name_encoding() -> latin1 | utf8</name> + <name name="native_name_encoding" arity="0"/> <fsummary>Return the VM's configured filename encoding.</fsummary> <desc> <p>This function returns the configured default file name encoding to use for raw file names. Generally an application supplying file names raw (as binaries), should obey the character encoding returned by this function.</p> @@ -610,7 +664,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 +698,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 +822,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 +920,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 +964,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 +1036,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 +1288,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 +1300,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 +1346,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> @@ -1373,10 +1441,41 @@ <fsummary>See what a link is pointing to</fsummary> <desc> <p>This function returns <c>{ok, <anno>Filename</anno>}</c> if + <c><anno>Name</anno></c> refers to a symbolic link that is + not a "raw" file name, or <c>{error, <anno>Reason</anno>}</c> + otherwise. + On platforms that do not support symbolic links, the return + value will be <c>{error,enotsup}</c>.</p> + <p>Typical error reasons:</p> + <taglist> + <tag><c>einval</c></tag> + <item> + <p><c><anno>Name</anno></c> does not refer to a symbolic link + or the name of the file that it refers to does not conform + to the expected encoding.</p> + </item> + <tag><c>enoent</c></tag> + <item> + <p>The file does not exist.</p> + </item> + <tag><c>enotsup</c></tag> + <item> + <p>Symbolic links are not supported on this platform.</p> + </item> + </taglist> + </desc> + </func> + <func> + <name name="read_link_all" arity="1"/> + <fsummary>See what a link is pointing to</fsummary> + <desc> + <p>This function returns <c>{ok, <anno>Filename</anno>}</c> if <c><anno>Name</anno></c> refers to a symbolic link or <c>{error, <anno>Reason</anno>}</c> otherwise. On platforms that do not support symbolic links, the return value will be <c>{error,enotsup}</c>.</p> + <p>Note that <c><anno>Filename</anno></c> can be either a list + or a binary.</p> <p>Typical error reasons:</p> <taglist> <tag><c>einval</c></tag> @@ -1502,6 +1601,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> @@ -1541,6 +1643,12 @@ <p><c><anno>Dir</anno></c> had an improper type, such as tuple.</p> </item> + <tag><c>no_translation</c></tag> + <item> + <p><c><anno>Dir</anno></c> is a <c>binary()</c> with + characters coded in ISO-latin-1 and the VM was started + with the parameter <c>+fnue</c>.</p> + </item> </taglist> <warning> <p>In a future release, a bad type for the @@ -1609,6 +1717,7 @@ <func> <name name="sendfile" arity="5"/> <fsummary>send a file to a socket</fsummary> + <type name="sendfile_option"/> <desc> <p>Sends <c>Bytes</c> from the file referenced by <c>RawFile</c> beginning at <c>Offset</c> to @@ -1732,22 +1841,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 +1887,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/global.xml b/lib/kernel/doc/src/global.xml index 304a9b1d88..53958c47c2 100644 --- a/lib/kernel/doc/src/global.xml +++ b/lib/kernel/doc/src/global.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2011</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -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/inet.xml b/lib/kernel/doc/src/inet.xml index b727960d96..541500a300 100644 --- a/lib/kernel/doc/src/inet.xml +++ b/lib/kernel/doc/src/inet.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2012</year> + <year>1997</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -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> @@ -446,16 +493,6 @@ fe80::204:acff:fe17:bf38 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>. - </p> - <p>Note that the <c>bit8</c> option is deprecated and will be removed in Erlang/OTP R16.</p> - </item> - <tag><c>{broadcast, Boolean}</c>(UDP sockets)</tag> <item> <p>Enable/disable permission to send broadcasts.</p> @@ -522,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> @@ -550,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 78bc533464..c18ae897b4 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>2012</year> + <year>2004</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -30,6 +30,235 @@ </header> <p>This document describes the changes made to the Kernel application.</p> +<section><title>Kernel 2.16.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> A bug that could cause a crash with wrong reason has + been corrected in the <c>application_controller</c> + module. </p> + <p> + Own Id: OTP-10754</p> + </item> + <item> + <p> + Fix <c>code:is_module_native/1</c> that sometimes in R16A + returned false for hipe compiled modules containing BIFs + such as <c>lists</c>.</p> + <p> + Own Id: OTP-10870</p> + </item> + <item> + <p> + Respect <c>{exit_on_close,false}</c> option on tcp socket + in non-passive mode when receiving fails (due to an + ill-formed packet for example) by only doing a half close + and still allow sending on the socket. (Thanks to Anthony + Molinaro and Steve Vinoski for reporting the problem)</p> + <p> + Own Id: OTP-10879</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Slightly nicer error message when node start fails due to + duplicate name. Thanks to Magnus Henoch.</p> + <p> + Own Id: OTP-10797</p> + </item> + <item> + <p> Miscellaneous updates due to Unicode support. </p> + <p> + Own Id: OTP-10820</p> + </item> + <item> + <p> + Add a new function code:get_mode() can be used to detect + how the code servers behaves. Thanks to Vlad Dumitrescu</p> + <p> + Own Id: OTP-10823</p> + </item> + <item> + <p> + Fix type of error Reason on gen_tcp:send/2. Thanks to + Sean Cribbs.</p> + <p> + Own Id: OTP-10839</p> + </item> + <item> + <p><c>file:list_dir_all/1</c> and + <c>file:read_link_all/1</c> that can handle raw file + names have been added. See the User Guide for STDLIB for + information about raw file names.</p> + <p> + Own Id: OTP-10852</p> + </item> + </list> + </section> + +</section> + +<section><title>Kernel 2.16</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + It is no longer possible to have <c>{Mod,Vsn}</c> in the + 'modules' list in a .app file.</p> + <p> + This was earlier possible, although never documented in + the .app file reference manual. It was however visible in + the documentation of <c>application:load/[1,2]</c>, where + the same term as in a .app file can be used as the first + argument.</p> + <p> + The possibility has been removed since the <c>Vsn</c> + part was never used.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-10417</p> + </item> + <item> + <p> The contract of <c>erl_ddll:format_error/1</c> has + been corrected. (Thanks to Joseph Wayne Norton.) </p> + <p> + Own Id: OTP-10473</p> + </item> + <item> + <p> + Change printout of application crash message on startup + to formated strings (Thanks to Serge Aleynikov)</p> + <p> + Own Id: OTP-10620</p> + </item> + <item> + <p> The type <c>ascii_string()</c> in the <c>base64</c> + module has been corrected. The type + <c>file:file_info()</c> has been cleaned up. The type + <c>file:fd()</c> has been made opaque in the + documentation. </p> + <p> + Own Id: OTP-10624 Aux Id: kunagi-352 [263] </p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Inet exported functionality</p> + <p> + inet:parse_ipv4_address/1, + inet:parse_ipv4strict_address/1, + inet:parse_ipv6_address/1, + inet:parse_ipv6strict_address/1, inet:parse_address/1 and + inet:parse_strict_address is now exported from the inet + module.</p> + <p> + Own Id: OTP-8067 Aux Id: kunagi-274 [185] </p> + </item> + <item> + <p> + A boolean socket option 'ipv6_v6only' for IPv6 sockets + has been added. The default value of the option is OS + dependent, so applications aiming to be portable should + consider using <c>{ipv6_v6only,true}</c> when creating an + <c>inet6</c> listening/destination socket, and if + neccesary also create an <c>inet</c> socket on the same + port for IPv4 traffic. See the documentation.</p> + <p> + Own Id: OTP-8928 Aux Id: kunagi-193 [104] </p> + </item> + <item> + <p> Support for Unicode has been implemented. </p> + <p> + Own Id: OTP-10302</p> + </item> + <item> + <p> + The documentation for <c>global:register_name/3</c> has + been updated to mention that the use of + <c>{Module,Function}</c> as the method argument (resolve + function) is deprecated.</p> + <p> + Own Id: OTP-10419</p> + </item> + <item> + <p> + Fixed bug where sendfile on oracle solaris would return + an error when a partial send was done.</p> + <p> + Own Id: OTP-10549</p> + </item> + <item> + <p> + The <c>error_handler</c> module will now call + <c>'$handle_undefined_function'/2</c> if an attempt is + made to call a non-existing function in a module that + exists. See the documentation for <c>error_handler</c> + module for details.</p> + <p> + Own Id: OTP-10617 Aux Id: kunagi-340 [251] </p> + </item> + <item> + <p>Where necessary a comment stating encoding has been + added to Erlang files. The comment is meant to be removed + in Erlang/OTP R17B when UTF-8 becomes the default + encoding. </p> + <p> + Own Id: OTP-10630</p> + </item> + <item> + <p> + Do not return wrong terms unnecessarily. (Thanks to + Kostis Sagonas.)</p> + <p> + Own Id: OTP-10662</p> + </item> + <item> + <p> Some examples overflowing the width of PDF pages have + been corrected. </p> + <p> + Own Id: OTP-10665</p> + </item> + <item> + <p>Add file:allocate/3 operation</p> + <p>This operation allows pre-allocation of space for + files. It succeeds only on systems that support such + operation. (Thanks to Filipe David Manana)</p> + <p> + Own Id: OTP-10680</p> + </item> + <item> + <p> + Add application:get_key/3. The new function provides a + default value for a configuration parameter. Thanks to + Serge Aleynikov.</p> + <p> + Own Id: OTP-10694</p> + </item> + <item> + <p> + Add search to Erlang shell's history. Thanks to Fred + Herbert.</p> + <p> + Own Id: OTP-10739</p> + </item> + </list> + </section> + +</section> + <section><title>Kernel 2.15.3</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 f3a051c989..5e182de41d 100644 --- a/lib/kernel/doc/src/os.xml +++ b/lib/kernel/doc/src/os.xml @@ -73,7 +73,7 @@ DirOut = os:cmd("dir"), % on Win32 platform</code> </desc> </func> <func> - <name>getenv() -> [string()]</name> + <name name="getenv" arity="0"/> <fsummary>List all environment variables</fsummary> <desc> <p>Returns a list of all environment variables. @@ -87,66 +87,51 @@ DirOut = os:cmd("dir"), % on Win32 platform</code> </desc> </func> <func> - <name>getenv(VarName) -> Value | false</name> + <name name="getenv" arity="1"/> <fsummary>Get the value of an environment variable</fsummary> - <type> - <v>VarName = string() </v> - <v>Value = string()</v> - </type> <desc> - <p>Returns the <c>Value</c> of the environment variable - <c>VarName</c>, or <c>false</c> if the environment variable + <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>VarName</c> and - <c>Value</c>) may contain characters with codepoints > 255.</p> + 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> - <name>getpid() -> Value </name> + <name name="getpid" arity="0"/> <fsummary>Return the process identifier of the emulator process</fsummary> - <type> - <v>Value = string()</v> - </type> <desc> <p>Returns the process identifier of the current Erlang emulator in the format most commonly used by the operating system - environment. <c>Value</c> is returned as a string containing + 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>Value</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> </func> <func> - <name>putenv(VarName, Value) -> true</name> + <name name="putenv" arity="2"/> <fsummary>Set a new value for an environment variable</fsummary> - <type> - <v>VarName = string() </v> - <v>Value = string()</v> - </type> <desc> - <p>Sets a new <c>Value</c> for the environment variable - <c>VarName</c>.</p> + <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>VarName</c> and - <c>Value</c>) may contain characters with codepoints > 255.</p> + 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> - <name>timestamp() -> Timestamp</name> + <name name="timestamp" arity="0"/> + <type_desc variable="Timestamp">Timestamp = {MegaSecs, Secs, MicroSecs}</type_desc> <fsummary>Returna a timestamp from the OS in the erlang:now/0 format</fsummary> - <type> - <v>Timestamp = {MegaSecs, Secs, MicroSecs} = <seealso marker="erts:erlang#type-timestamp">erlang:timestamp()</seealso></v> - <v>MegaSecs = Secs = MicroSecs = integer() >= 0</v> - </type> <desc> <p>Returns a tuple in the same format as <seealso marker="erts:erlang#now/0">erlang:now/0</seealso>. The difference is that this function returns what the operating system thinks (a.k.a. the wall clock time) without any attempts at time correction. The result of two different calls to this function is <em>not</em> guaranteed to be different.</p> <p>The most obvious use for this function is logging. The tuple can be used together with the function <seealso marker="stdlib:calendar#now_to_universal_time/1">calendar:now_to_universal_time/1</seealso> @@ -183,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 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..96604a2fa2 100644 --- a/lib/kernel/doc/src/ref_man.xml +++ b/lib/kernel/doc/src/ref_man.xml @@ -4,7 +4,7 @@ <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2009</year> + <year>1996</year><year>2013</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -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> diff --git a/lib/kernel/doc/src/specs.xml b/lib/kernel/doc/src/specs.xml index b41addaa0c..813bb06e1f 100644 --- a/lib/kernel/doc/src/specs.xml +++ b/lib/kernel/doc/src/specs.xml @@ -29,5 +29,4 @@ <xi:include href="../specs/specs_user.xml"/> <xi:include href="../specs/specs_wrap_log_reader.xml"/> <xi:include href="../specs/specs_zlib_stub.xml"/> - <xi:include href="../specs/specs_packages.xml"/> </specs> |