diff options
Diffstat (limited to 'lib/kernel/doc')
-rw-r--r-- | lib/kernel/doc/src/code.xml | 6 | ||||
-rw-r--r-- | lib/kernel/doc/src/error_logger.xml | 2 | ||||
-rw-r--r-- | lib/kernel/doc/src/file.xml | 114 | ||||
-rw-r--r-- | lib/kernel/doc/src/gen_sctp.xml | 2 | ||||
-rw-r--r-- | lib/kernel/doc/src/gen_tcp.xml | 4 | ||||
-rw-r--r-- | lib/kernel/doc/src/inet.xml | 6 | ||||
-rw-r--r-- | lib/kernel/doc/src/kernel_app.xml | 2 | ||||
-rw-r--r-- | lib/kernel/doc/src/notes.xml | 235 |
8 files changed, 343 insertions, 28 deletions
diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml index 6b89711924..ee687511a3 100644 --- a/lib/kernel/doc/src/code.xml +++ b/lib/kernel/doc/src/code.xml @@ -229,10 +229,10 @@ <c>-code_path_choice Choice</c>. If the flag is set to <c>relaxed</c>, the code server will instead choose a suitable directory depending on the actual file structure. If there exists a regular - application ebin directory,situation it will be choosen. But if it does - not exist, the ebin directory in the archive is choosen if it + application ebin directory,situation it will be chosen. But if it does + not exist, the ebin directory in the archive is chosen if it exists. If neither of them exists the original directory will be - choosen.</p> + chosen.</p> <p>The command line flag <c>-code_path_choice Choice</c> does also affect how <c>init</c> interprets the <c>boot script</c>. The diff --git a/lib/kernel/doc/src/error_logger.xml b/lib/kernel/doc/src/error_logger.xml index 2d95f96ac7..95b23e4aef 100644 --- a/lib/kernel/doc/src/error_logger.xml +++ b/lib/kernel/doc/src/error_logger.xml @@ -49,7 +49,7 @@ that events are logged to file instead, or not logged at all, see <seealso marker="kernel_app">kernel(6)</seealso>.</p> <p>Also the SASL application, if started, adds its own event - handler, which by default writes supervisor-, crash- and progress + handler, which by default writes supervisor, crash and progress reports to tty. See <seealso marker="sasl:sasl_app">sasl(6)</seealso>.</p> <p>It is recommended that user defined applications should report diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml index 7db20e6343..772eff13cc 100644 --- a/lib/kernel/doc/src/file.xml +++ b/lib/kernel/doc/src/file.xml @@ -149,6 +149,12 @@ <datatype> <name name="mode"/> </datatype> + <datatype> + <name name="file_info_option"/> + </datatype> + <datatype> + <name name="sendfile_option"/> + </datatype> </datatypes> <funcs> @@ -409,7 +415,7 @@ <name>file_info(Filename) -> {ok, FileInfo} | {error, Reason}</name> <fsummary>Get information about a file (deprecated)</fsummary> <desc> - <p>This function is obsolete. Use <c>read_file_info/1</c> + <p>This function is obsolete. Use <c>read_file_info/1,2</c> instead.</p> </desc> </func> @@ -536,7 +542,7 @@ <desc> <p>Makes a hard link from <c><anno>Existing</anno></c> to <c><anno>New</anno></c>, on - platforms that support links (Unix). This function returns + platforms that support links (Unix and Windows). This function returns <c>ok</c> if the link was successfully created, or <c>{error, <anno>Reason</anno>}</c>. On platforms that do not support links, <c>{error,enotsup}</c> is returned.</p> @@ -563,11 +569,12 @@ <name name="make_symlink" arity="2"/> <fsummary>Make a symbolic link to a file or directory</fsummary> <desc> - <p>This function creates a symbolic link <c><anno>Name2</anno></c> to - the file or directory <c><anno>Name1</anno></c>, on platforms that - support - symbolic links (most Unix systems). <c><anno>Name1</anno></c> need not - exist. This function returns <c>ok</c> if the link was + <p>This function creates a symbolic link <c><anno>New</anno></c> to + the file or directory <c><anno>Existing</anno></c>, on platforms that + support symbolic links (most Unix systems and Windows beginning with + Vista). + <c><anno>Existing</anno></c> need not exist. + This function returns <c>ok</c> if the link was successfully created, or <c>{error, <anno>Reason</anno>}</c>. On platforms that do not support symbolic links, <c>{error, enotsup}</c> @@ -577,11 +584,11 @@ <tag><c>eacces</c></tag> <item> <p>Missing read or write permissions for the parent directories - of <c><anno>Name1</anno></c> or <c><anno>Name2</anno></c>.</p> + of <c><anno>Existing</anno></c> or <c><anno>New</anno></c>.</p> </item> <tag><c>eexist</c></tag> <item> - <p><c><anno>Name2</anno></c> already exists.</p> + <p><c><anno>New</anno></c> already exists.</p> </item> <tag><c>enotsup</c></tag> <item> @@ -1185,6 +1192,7 @@ </func> <func> <name name="read_file_info" arity="1"/> + <name name="read_file_info" arity="2"/> <fsummary>Get information about a file</fsummary> <desc> <p>Retrieves information about a file. Returns @@ -1196,6 +1204,20 @@ from which the function is called:</p> <code type="none"> -include_lib("kernel/include/file.hrl").</code> + <p>The time type returned in <c>atime</c>, <c>mtime</c> and <c>ctime</c> + is dependent on the time type set in <c>Opts :: {time, Type}</c>. + Type <c>local</c> will return local time, <c>universal</c> will + return universal time and <c>posix</c> will return seconds since + or before unix time epoch which is 1970-01-01 00:00 UTC. + Default is <c>{time, local}</c>. + </p> + <note> + <p> + Since file times is stored in posix time on most OS it is + faster to query file information with the <c>posix</c> option. + </p> + </note> + <p>The record <c>file_info</c> contains the following fields.</p> <taglist> <tag><c>size = integer()</c></tag> @@ -1210,15 +1232,15 @@ <item> <p>The current system access to the file.</p> </item> - <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso></c></tag> + <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag> <item> - <p>The last (local) time the file was read.</p> + <p>The last time the file was read.</p> </item> - <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso></c></tag> + <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag> <item> - <p>The last (local) time the file was written.</p> + <p>The last time the file was written.</p> </item> - <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso></c></tag> + <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso> | integer() </c></tag> <item> <p>The interpretation of this time field depends on the operating system. On Unix, it is the last time @@ -1374,9 +1396,11 @@ </func> <func> <name name="read_link_info" arity="1"/> + <name name="read_link_info" arity="2"/> <fsummary>Get information about a link or file</fsummary> <desc> - <p>This function works like <c>read_file_info/1</c>, except that + <p>This function works like + <seealso marker="#read_file_info/2">read_file_info/1,2</seealso> except that if <c><anno>Name</anno></c> is a symbolic link, information about the link will be returned in the <c>file_info</c> record and the <c>type</c> field of the record will be set to @@ -1574,6 +1598,48 @@ </desc> </func> <func> + <name name="sendfile" arity="2"/> + <fsummary>send a file to a socket</fsummary> + <desc> + <p>Sends the file <c>Filename</c> to <c>Socket</c>. + Returns <c>{ok, BytesSent}</c> if successful, + otherwise <c>{error, Reason}</c>.</p> + </desc> + </func> + <func> + <name name="sendfile" arity="5"/> + <fsummary>send a file to a socket</fsummary> + <desc> + <p>Sends <c>Bytes</c> from the file + referenced by <c>RawFile</c> beginning at <c>Offset</c> to + <c>Socket</c>. + Returns <c>{ok, BytesSent}</c> if successful, + otherwise <c>{error, Reason}</c>. If <c>Bytes</c> is set to + 0 all data after the given <c>Offset</c> is sent.</p> + <p>The file used must be opened using the raw flag, and the process + calling sendfile must be the controlling process of the socket. + See <seealso marker="gen_tcp#controlling_process-2">gen_tcp:controlling_process/2</seealso></p> + <p>If the OS used does not support sendfile, an Erlang fallback + using file:read and gen_tcp:send is used.</p> + <p>The option list can contain the following options: + <taglist> + <tag><c>chunk_size</c></tag> + <item>The chunk size used by the erlang fallback to send + data. If using the fallback, this should be set to a value + which comfortably fits in the systems memory. Default is 20 MB.</item> + </taglist> + </p> + <p>On operating systems with thread support, it is recommended to use + async threads. See the command line flag + <c>+A</c> in <seealso marker="erts:erl">erl(1)</seealso>. If it is not + possible to use async threads for sendfile, it is recommended to use + a relatively small value for the send buffer on the socket. Otherwise + the Erlang VM might loose some of its soft realtime guarantees. + Which size to use depends on the OS/hardware and the requirements + of the application.</p> + </desc> + </func> + <func> <name name="write" arity="2"/> <fsummary>Write to a file</fsummary> <desc> @@ -1645,6 +1711,7 @@ </func> <func> <name name="write_file_info" arity="2"/> + <name name="write_file_info" arity="3"/> <fsummary>Change information about a file</fsummary> <desc> <p>Change file information. Returns <c>ok</c> if successful, @@ -1655,18 +1722,25 @@ from which the function is called:</p> <code type="none"> -include_lib("kernel/include/file.hrl").</code> + <p>The time type set in <c>atime</c>, <c>mtime</c> and <c>ctime</c> + is dependent on the time type set in <c>Opts :: {time, Type}</c>. + Type <c>local</c> will interpret the time set as local, <c>universal</c> will + interpret it as universal time and <c>posix</c> must be seconds since + or before unix time epoch which is 1970-01-01 00:00 UTC. + Default is <c>{time, local}</c>. + </p> <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></c></tag> + <tag><c>atime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</c></tag> <item> - <p>The last (local) time the file was read.</p> + <p>The last time the file was read.</p> </item> - <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso></c></tag> + <tag><c>mtime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</c></tag> <item> - <p>The last (local) time the file was written.</p> + <p>The last time the file was written.</p> </item> - <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso></c></tag> + <tag><c>ctime = <seealso marker="#type-date_time">date_time()</seealso> | integer()</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 diff --git a/lib/kernel/doc/src/gen_sctp.xml b/lib/kernel/doc/src/gen_sctp.xml index 418bfae4b8..579b7f1f74 100644 --- a/lib/kernel/doc/src/gen_sctp.xml +++ b/lib/kernel/doc/src/gen_sctp.xml @@ -270,7 +270,7 @@ it is bound to.</p> <p>For type <c>seqpacket</c> sockets (the default) <c><anno>IsServer</anno></c> must be <c>true</c> or <c>false</c>. - In the contrast to TCP, in SCTP there is no listening queue length. + In contrast to TCP, in SCTP there is no listening queue length. If <c><anno>IsServer</anno></c> is <c>true</c> the socket accepts new associations, i.e. it will become an SCTP server socket.</p> <p>For type <c>stream</c> sockets <anno>Backlog</anno> defines diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml index 8a5d40bb16..9f362841ce 100644 --- a/lib/kernel/doc/src/gen_tcp.xml +++ b/lib/kernel/doc/src/gen_tcp.xml @@ -235,7 +235,9 @@ do_recv(Sock, Bs) -> <p>Returns <c>{ok, <anno>Socket</anno>}</c> if a connection is established, or <c>{error, closed}</c> if <c><anno>ListenSocket</anno></c> is closed, or <c>{error, timeout}</c> if no connection is established - within the specified time. May also return a POSIX error + within the specified time, + or <c>{error, system_limit}</c> if all available ports in the + Erlang emulator are in use. May also return a POSIX error value if something else goes wrong, see inet(3) for possible error values.</p> <p>Packets can be sent to the returned socket <c><anno>Socket</anno></c> diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml index fad5af85bb..86950b3ecc 100644 --- a/lib/kernel/doc/src/inet.xml +++ b/lib/kernel/doc/src/inet.xml @@ -149,7 +149,7 @@ fe80::204:acff:fe17:bf38 <fsummary>Return a descriptive string for an error reason</fsummary> <desc> <p>Returns a diagnostic error string. See the section below - for possible <c><anno>Posix</anno></c> values and the corresponding + for possible Posix values and the corresponding strings.</p> </desc> </func> @@ -573,6 +573,10 @@ fe80::204:acff:fe17:bf38 is longer than the max allowed length, the packet is considered invalid. The same happens if the packet header is too big for the socket receive buffer.</p> + <p>For line oriented protocols (<c>line</c>,<c>http*</c>), + option <c>packet_size</c> also guarantees that lines up to the + indicated length are accepted and not considered invalid due + to internal buffer limitations.</p> </item> <tag><c>{read_packets, Integer}</c>(UDP sockets)</tag> <item> diff --git a/lib/kernel/doc/src/kernel_app.xml b/lib/kernel/doc/src/kernel_app.xml index 0f71a4f0f2..63fdc223f4 100644 --- a/lib/kernel/doc/src/kernel_app.xml +++ b/lib/kernel/doc/src/kernel_app.xml @@ -104,7 +104,7 @@ that node. <c>Value</c> is one of:</p> <taglist> <tag><c>never</c></tag> - <item>Connections are never automatically connected, they + <item>Connections are never automatically established, they must be explicitly connected. See <c>net_kernel(3)</c>.</item> <tag><c>once</c></tag> <item>Connections will be established automatically, but only diff --git a/lib/kernel/doc/src/notes.xml b/lib/kernel/doc/src/notes.xml index ec57b03bd9..9121186631 100644 --- a/lib/kernel/doc/src/notes.xml +++ b/lib/kernel/doc/src/notes.xml @@ -30,6 +30,241 @@ </header> <p>This document describes the changes made to the Kernel application.</p> +<section><title>Kernel 2.15</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> Calls to <c>global:whereis_name/1</c> have been + substituted for calls to + <c>global:safe_whereis_name/1</c> since the latter is not + safe at all.</p> + <p>The reason for not doing this earlier is that setting + a global lock masked out a bug concerning the restart of + supervised children. The bug has now been fixed by a + modification of <c>global:whereis_name/1</c>. (Thanks to + Ulf Wiger for code contribution.)</p> + <p>A minor race conditions in <c>gen_fsm:start*</c> has + been fixed: if one of these functions returned <c>{error, + Reason}</c> or ignore, the name could still be registered + (either locally or in <c>global</c>. (This is the same + modification as was done for gen_server in OTP-7669.)</p> + <p>The undocumented function + <c>global:safe_whereis_name/1</c> has been removed. </p> + <p> + Own Id: OTP-9212 Aux Id: seq7117, OTP-4174 </p> + </item> + <item> + <p> + Honor option <c>packet_size</c> for http packet parsing + by both TCP socket and <c>erlang:decode_packet</c>. This + gives the ability to accept HTTP headers larger than the + default setting, but also avoid DoS attacks by accepting + lines only up to whatever length you wish to allow. For + consistency, packet type <c>line</c> also honor option + <c>packet_size</c>. (Thanks to Steve Vinoski)</p> + <p> + Own Id: OTP-9389</p> + </item> + <item> + <p> <c>disk_log:reopen/2,3</c> and + <c>disk_log:breopen/3</c> could return the error reason + from <c>file:rename/2</c> rather than the reason + <c>{file_error, Filename, Reason}</c>. This bug has been + fixed. </p> <p> The message <c>{disk_log, Node, {error, + disk_log_stopped}}</c> which according the documentation + is sent upon failure to truncate or reopen a disk log was + sometimes turned into a reply. This bug has been fixed. + </p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-9508</p> + </item> + <item> + <p> + Environment variable 'shutdown_timeout' is added to + kernel application. Earlier, application_controller would + hang forever if an application top supervisor did not + terminate upon a shutdown request. If this new + environment variable is set to a positive integer T, then + application controller will now give up after T + milliseconds and instead brutally kill the application. + For backwards compatibility, the default value for + shutdown_timeout is 'infinity'.</p> + <p> + Own Id: OTP-9540</p> + </item> + <item> + <p> + Add '-callback' attributes in stdlib's behaviours</p> + <p> + Replace the behaviour_info(callbacks) export in stdlib's + behaviours with -callback' attributes for all the + callbacks. Update the documentation with information on + the callback attribute Automatically generate + 'behaviour_info' function from '-callback' attributes</p> + <p> + 'behaviour_info(callbacks)' is a special function that is + defined in a module which describes a behaviour and + returns a list of its callbacks.</p> + <p> + This function is now automatically generated using the + '-callback' specs. An error is returned by lint if user + defines both '-callback' attributes and the + behaviour_info/1 function. If no type info is needed for + a callback use a generic spec for it. Add '-callback' + attribute to language syntax</p> + <p> + Behaviours may define specs for their callbacks using the + familiar spec syntax, replacing the '-spec' keyword with + '-callback'. Simple lint checks are performed to ensure + that no callbacks are defined twice and all types + referred are declared.</p> + <p> + These attributes can be then used by tools to provide + documentation to the behaviour or find discrepancies in + the callback definitions in the callback module.</p> + <p> + Add callback specs into 'application' module in kernel + Add callback specs to tftp module following internet + documentation Add callback specs to inets_service module + following possibly deprecated comments</p> + <p> + Own Id: OTP-9621</p> + </item> + <item> + <p> + make tab completion work in remote shells (Thanks to Mats + Cronqvist)</p> + <p> + Own Id: OTP-9673</p> + </item> + <item> + <p> + Add missing parenthesis in heart doc.</p> + <p> + Add missing spaces in the Reference Manual distributed + section.</p> + <p> + In the HTML version of the doc those spaces are necessary + to separate those words.</p> + <p> + Own Id: OTP-9693</p> + </item> + <item> + <p> + Fixes net_kernel:get_net_ticktime() doc</p> + <p> + Adds missing description when `ignored' is returned. + (Thanks to Ricardo Catalinas Jim�nez )</p> + <p> + Own Id: OTP-9713</p> + </item> + <item> + <p> While <c>disk_log</c> eagerly collects logged terms + for better performance, collecting too much data may + choke the system and cause huge binaries to be written. + In order to remedy the situation a (small) limit on the + amount of data that is collected before writing to disk + has been introduced. </p> + <p> + Own Id: OTP-9764</p> + </item> + <item> + <p> + <list> <item><p>Correct callback spec in application + module</p></item> <item><p>Refine warning about callback + specs with extra ranges</p></item> <item><p>Cleanup + autoimport compiler directives</p></item> <item><p>Fix + Dialyzer's warnings in typer</p></item> <item><p>Fix + Dialyzer's warning for its own code</p></item> + <item><p>Fix bug in Dialyzer's behaviours + analysis</p></item> <item><p>Fix crash in + Dialyzer</p></item> <item><p>Variable substitution was + not generalizing any unknown variables.</p></item> + </list></p> + <p> + Own Id: OTP-9776</p> + </item> + <item> + <p> + Fix a crash when file:change_time/2,3 are called with + invalid dates</p> + <p> + Calling file:change_time/2,3 with an invalid date tuple + (e.g file:change_time("file.txt", {undefined, + undefined})) will cause file_server_2 to crash. + error_logger will shutdown and the whole VM will stop. + Change behavior to validate given dates on system + boundaries. (i.e before issuing a server call).(Thanks to + Ahmed Omar)</p> + <p> + Own Id: OTP-9785</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> An option list argument can now be passed to + <c>file:read_file_info/2, file:read_link_info/2</c> and + <c>file:write_file_info/3</c> and set time type + information in the call. Valid options are <c>{time, + local}, {time, universal}</c> and <c>{time, posix}</c>. + In the case of <c>posix</c> time no conversions are made + which makes the operation a bit faster. </p> + <p> + Own Id: OTP-7687</p> + </item> + <item> + <p><c>file:list_dir/1,2</c> will now fill an buffer + entire with filenames from the efile driver before + sending it to an erlang process. This will speed up this + file operation in most cases.</p> + <p> + Own Id: OTP-9023</p> + </item> + <item> + <p>gen_sctp:open/0-2 may now return + {error,eprotonosupport} if SCTP is not supported</p> + <p>gen_sctp:peeloff/1 has been implemented and creates a + one-to-one socket which also are supported now</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-9239</p> + </item> + <item> + <p> + Sendfile has been added to the file module's API. + sendfile/2 is used to read data from a file and send it + to a tcp socket using a zero copying mechanism if + available on that OS.</p> + <p> + Thanks to Tuncer Ayaz and Steve Vinovski for original + implementation</p> + <p> + Own Id: OTP-9240</p> + </item> + <item> + <p> + Tuple funs (a two-element tuple with a module name and a + function) are now officially deprecated and will be + removed in R16. Use '<c>fun M:F/A</c>' instead. To make + you aware that your system uses tuple funs, the very + first time a tuple fun is applied, a warning will be sent + to the error logger.</p> + <p> + Own Id: OTP-9649</p> + </item> + </list> + </section> + +</section> + <section><title>Kernel 2.14.5</title> <section><title>Fixed Bugs and Malfunctions</title> |