diff options
Diffstat (limited to 'lib/kernel/doc')
| -rw-r--r-- | lib/kernel/doc/src/gen_sctp.xml | 69 | ||||
| -rw-r--r-- | lib/kernel/doc/src/gen_tcp.xml | 28 | ||||
| -rw-r--r-- | lib/kernel/doc/src/gen_udp.xml | 35 | ||||
| -rw-r--r-- | lib/kernel/doc/src/inet.xml | 123 | ||||
| -rw-r--r-- | lib/kernel/doc/src/logger.xml | 2 | ||||
| -rw-r--r-- | lib/kernel/doc/src/logger_chapter.xml | 14 | ||||
| -rw-r--r-- | lib/kernel/doc/src/logger_formatter.xml | 7 | ||||
| -rw-r--r-- | lib/kernel/doc/src/logger_std_h.xml | 23 |
8 files changed, 267 insertions, 34 deletions
diff --git a/lib/kernel/doc/src/gen_sctp.xml b/lib/kernel/doc/src/gen_sctp.xml index 737800c6b1..1e08b25f66 100644 --- a/lib/kernel/doc/src/gen_sctp.xml +++ b/lib/kernel/doc/src/gen_sctp.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>2007</year><year>2016</year> + <year>2007</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -331,6 +331,37 @@ connect(Socket, Ip, Port>, with <anno>SockType</anno> <c>seqpacket</c>, and with reasonably large <seealso marker="inet#option-sndbuf">kernel</seealso> and driver <seealso marker="inet#option-buffer">buffers</seealso>.</p> + <p> + If the socket is in + <seealso marker="#option-active">passive</seealso> + mode data can be received through the + <seealso marker="#recv/1"><c>recv/1,2</c></seealso> + calls. + </p> + <p> + If the socket is in + <seealso marker="#option-active">active</seealso> + mode data received data is delivered to the controlling process + as messages: + </p> + <code type="none"> +{sctp, <anno>Socket</anno>, FromIP, FromPort, {AncData, Data}} + </code> + <p> + See + <seealso marker="#recv/1"><c>recv/1,2</c></seealso> + for a description of the message fields. + </p> + <note> + <p> + This message format unfortunately differs slightly from the + <seealso marker="gen_udp#open/1"><c>gen_udp</c></seealso> + message format with ancillary data, + and from the + <seealso marker="#recv/1"><c>recv/1,2</c></seealso> + return tuple format. + </p> + </note> </desc> </func> @@ -380,6 +411,19 @@ connect(Socket, Ip, Port>, socket option <seealso marker="#option-sctp_get_peer_addr_info"><c>sctp_get_peer_addr_info</c></seealso>, but this does still not produce the stream number).</p> + <p> + <c><anno>AncData</anno></c> may also contain + <seealso marker="inet#type-ancillary_data"> + ancillary data + </seealso> + from the socket + <seealso marker="#type-option">options</seealso> + <seealso marker="inet#option-recvtos"><c>recvtos</c></seealso>, + <seealso marker="inet#option-recvtclass"><c>recvtclass</c></seealso> + or + <seealso marker="inet#option-recvttl"><c>recvttl</c></seealso>, + if that is supported by the platform for the socket. + </p> <p>The <c><anno>Data</anno></c> received can be a <c>binary()</c> or a <c>list()</c> of bytes (integers in the range 0 through 255) depending on the socket mode, or an SCTP event.</p> @@ -544,12 +588,25 @@ connect(Socket, Ip, Port>, <seealso marker="#recv/1"><c>recv</c></seealso> call to retrieve the available data from the socket.</p> </item> + <item> + <p> + If <c>true|once|N</c> (active modes) + received data or events are sent to the owning process. + See <seealso marker="#open/0"><c>open/0..2</c></seealso> + for the message format. + </p> + </item> <item> - <p>If <c>true</c> (full active mode), the pending data or events are - sent to the owning process.</p> - <p>Notice that this can cause the message queue to overflow, - as there is no way to throttle the sender in this case - (no flow control).</p> + <p> + If <c>true</c> (full active mode) there is no flow control. + </p> + <note> + <p> + Note that this can cause the message queue to overflow + causing for example the virtual machine + to run out of memory and crash. + </p> + </note> </item> <item> <p>If <c>once</c>, only one message is automatically placed diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml index e6104b0c76..24d63693fd 100644 --- a/lib/kernel/doc/src/gen_tcp.xml +++ b/lib/kernel/doc/src/gen_tcp.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2017</year> + <year>1997</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -70,6 +70,32 @@ do_recv(Sock, Bs) -> <name name="option"/> </datatype> <datatype> + <name name="pktoptions_value"/> + <desc> + <p> + If the platform implements the IPv4 option + <c>IP_PKTOPTIONS</c>, or the IPv6 option + <c>IPV6_PKTOPTIONS</c> or <c>IPV6_2292PKTOPTIONS</c> for the socket + this value is returned from + <seealso marker="inet#getopts/2"><c>inet:getopts/2</c></seealso> + when called with the option name + <seealso marker="#type-option_name"><c>pktoptions</c></seealso>. + </p> + <note> + <p> + This option appears to be VERY Linux specific, + and its existence in future Linux kernel versions + is also worrying since the option is part of RFC 2292 + which is since long (2003) obsoleted by RFC 3542 + that <em>explicitly</em> removes this possibility to get + packet information from a stream socket. + For comparision: it has existed in FreeBSD but is now removed, + at least since FreeBSD 10. + </p> + </note> + </desc> + </datatype> + <datatype> <name name="option_name"/> </datatype> <datatype> diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml index f79566ef71..840ca3c188 100644 --- a/lib/kernel/doc/src/gen_udp.xml +++ b/lib/kernel/doc/src/gen_udp.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1997</year><year>2016</year> + <year>1997</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -147,7 +147,21 @@ at the opened port, if the socket is in an active mode, the packets are delivered as messages to the controlling process:</p> <code type="none"> -{udp, Socket, IP, InPortNo, Packet}</code> +{udp, Socket, IP, InPortNo, Packet} % Without ancillary data +{udp, Socket, IP, InPortNo, AncData, Packet} % With ancillary data + </code> + <p> + The message contains an <c>AncData</c> field + if any of the socket + <seealso marker="#type-option">options</seealso> + <seealso marker="inet#option-recvtos"><c>recvtos</c></seealso>, + <seealso marker="inet#option-recvtclass"><c>recvtclass</c></seealso> + or + <seealso marker="inet#option-recvttl"><c>recvttl</c></seealso> + are active, otherwise it does not. + </p> + <p> + </p> <p>If the socket is not in an active mode, data can be retrieved through the <seealso marker="#recv/2"><c>recv/2,3</c></seealso> calls. @@ -179,9 +193,22 @@ <name name="recv" arity="3"/> <fsummary>Receive a packet from a passive socket.</fsummary> <desc> - <p>Receives a packet from a socket in passive mode. Optional parameter + <p> + Receives a packet from a socket in passive mode. Optional parameter <c><anno>Timeout</anno></c> specifies a time-out in milliseconds. - Defaults to <c>infinity</c>.</p> + Defaults to <c>infinity</c>. + </p> + <p> + If any of the socket + <seealso marker="#type-option">options</seealso> + <seealso marker="inet#option-recvtos"><c>recvtos</c></seealso>, + <seealso marker="inet#option-recvtclass"><c>recvtclass</c></seealso> + or + <seealso marker="inet#option-recvttl"><c>recvttl</c></seealso> + are active, the <c><anno>RecvData</anno></c> tuple contains an + <c><anno>AncData</anno></c> field, + otherwise it does not. + </p> </desc> </func> diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml index f281d61459..ed775d67eb 100644 --- a/lib/kernel/doc/src/inet.xml +++ b/lib/kernel/doc/src/inet.xml @@ -177,6 +177,27 @@ fe80::204:acff:fe17:bf38 </desc> </datatype> <datatype> + <name name="ancillary_data"/> + <desc> + <p> + Ancillary data received with the data packet + or read with the socket option + <seealso marker="gen_tcp#type-pktoptions_value"> + <c>pktoptions</c> + </seealso> + from a TCP socket. + </p> + <p> + The value(s) correspond to the currently active socket + <seealso marker="#type-socket_setopt">options</seealso> + <seealso marker="inet#option-recvtos"><c>recvtos</c></seealso>, + <seealso marker="inet#option-recvtclass"><c>recvtclass</c></seealso> + and + <seealso marker="inet#option-recvttl"><c>recvttl</c></seealso>. + </p> + </desc> + </datatype> + <datatype> <name name="posix"/> <desc> <p>An atom that is named from the POSIX error codes used in Unix, @@ -344,7 +365,11 @@ fe80::204:acff:fe17:bf38 <desc> <p>Gets one or more options for a socket. For a list of available options, see - <seealso marker="#setopts/2"><c>setopts/2</c></seealso>.</p> + <seealso marker="#setopts/2"><c>setopts/2</c></seealso>. + See also the description for the type + <seealso marker="gen_tcp#type-pktoptions_value"> + <c>gen_tcp:pktoptions_value()</c> + </seealso>.</p> <p>The number of elements in the returned <c><anno>OptionValues</anno></c> list does not necessarily correspond to the number of options @@ -360,7 +385,7 @@ fe80::204:acff:fe17:bf38 socket options not (explicitly) supported by the emulator. The use of raw socket options makes the code non-portable, but allows the Erlang programmer to take advantage of unusual features - present on the current platform.</p> + present on a particular platform.</p> <p><c>RawOptReq</c> consists of tag <c>raw</c> followed by the protocol level, the option number, and either a binary or the size, in bytes, of the @@ -1115,6 +1140,100 @@ setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp</code> the socket. You are encouraged to use <seealso marker="#getopts/2"><c>getopts/2</c></seealso> to retrieve the size set by your operating system.</p> + <marker id="option-recvtclass"></marker> + </item> + <tag><c>{recvtclass, Boolean}</c></tag> + <item> + <p> + If set to <c>true</c> activates returning the received + <c>TCLASS</c> value on platforms that implements + the protocol <c>IPPROTO_IPV6</c> + option <c>IPV6_RECVTCLASS</c> or <c>IPV6_2292RECVTCLASS</c> + for the socket. + The value is returned as a <c>{tclass,TCLASS}</c> tuple + regardless of if the platform returns an <c>IPV6_TCLASS</c> + or an <c>IPV6_RECVTCLASS</c> CMSG value. + </p> + <p> + For packet oriented sockets that supports receiving + ancillary data with the payload data + (<c>gen_udp</c> and <c>gen_sctp</c>), + the <c>TCLASS</c> value is returned + in an extended return tuple contained in an + <seealso marker="inet#type-ancillary_data"> + ancillary data + </seealso> + list. + For stream oriented sockets (<c>gen_tcp</c>) + the only way to get the <c>TCLASS</c> + value is if the platform supports the + <seealso marker="gen_tcp#type-pktoptions_value"> + <c>pktoptions</c> + </seealso> + option. + </p> + <marker id="option-recvtos"></marker> + </item> + <tag><c>{recvtos, Boolean}</c></tag> + <item> + <p> + If set to <c>true</c> activates returning the received + <c>TOS</c> value on platforms that implements + the protocol <c>IPPROTO_IP</c> option <c>IP_RECVTOS</c> + for the socket. + The value is returned as a <c>{tos,TOS}</c> tuple + regardless of if the platform returns an <c>IP_TOS</c> + or an <c>IP_RECVTOS</c> CMSG value. + </p> + <p> + For packet oriented sockets that supports receiving + ancillary data with the payload data + (<c>gen_udp</c> and <c>gen_sctp</c>), + the <c>TOS</c> value is returned + in an extended return tuple contained in an + <seealso marker="inet#type-ancillary_data"> + ancillary data + </seealso> + list. + For stream oriented sockets (<c>gen_tcp</c>) + the only way to get the <c>TOS</c> + value is if the platform supports the + <seealso marker="gen_tcp#type-pktoptions_value"> + <c>pktoptions</c> + </seealso> + option. + </p> + <marker id="option-recvttl"></marker> + </item> + <tag><c>{recvttl, Boolean}</c></tag> + <item> + <p> + If set to <c>true</c> activates returning the received + <c>TTL</c> value on platforms that implements + the protocol <c>IPPROTO_IP</c> option <c>IP_RECVTTL</c> + for the socket. + The value is returned as a <c>{ttl,TTL}</c> tuple + regardless of if the platform returns an <c>IP_TTL</c> + or an <c>IP_RECVTTL</c> CMSG value. + </p> + <p> + For packet oriented sockets that supports receiving + ancillary data with the payload data + (<c>gen_udp</c> and <c>gen_sctp</c>), + the <c>TTL</c> value is returned + in an extended return tuple contained in an + <seealso marker="inet#type-ancillary_data"> + ancillary data + </seealso> + list. + For stream oriented sockets (<c>gen_tcp</c>) + the only way to get the <c>TTL</c> + value is if the platform supports the + <seealso marker="gen_tcp#type-pktoptions_value"> + <c>pktoptions</c> + </seealso> + option. + </p> </item> <tag><c>{reuseaddr, Boolean}</c></tag> <item> diff --git a/lib/kernel/doc/src/logger.xml b/lib/kernel/doc/src/logger.xml index a4d6efa2d8..464c65ba76 100644 --- a/lib/kernel/doc/src/logger.xml +++ b/lib/kernel/doc/src/logger.xml @@ -527,7 +527,7 @@ start(_, []) -> Error -> Error end.</code> <p>This reads the <c>logger</c> configuration parameter from - the <c>my_all</c> application and starts the configured + the <c>my_app</c> application and starts the configured handlers. The contents of the configuration use the same rules as the <seealso marker="logger_chapter#handler-configuration">logger handler configuration</seealso>. diff --git a/lib/kernel/doc/src/logger_chapter.xml b/lib/kernel/doc/src/logger_chapter.xml index d58c4a4d42..4a81cfa34a 100644 --- a/lib/kernel/doc/src/logger_chapter.xml +++ b/lib/kernel/doc/src/logger_chapter.xml @@ -208,12 +208,14 @@ coversion to a string:</p> <pre>fun((<seealso marker="logger#type-report"><c>logger:report()</c></seealso>,<seealso marker="logger#type-report_cb_config"><c>logger:report_cb_config()</c></seealso>) -> <seealso marker="stdlib:unicode#type-chardata"><c>unicode:chardata()</c></seealso>) </pre> - <p>The fun must obey the <c>encoding</c>, <c>depth</c> - and <c>chars_limit</c> parameters provided in the second - argument, as the formatter can not do anything useful of these - parameters with the returned string. This variant is used when - the formatting of the report depends on the size and encoding - parameters.</p> + <p>The fun must obey the <c>depth</c> and <c>chars_limit</c> + parameters provided in the second argument, as the formatter can + not do anything useful of these parameters with the returned + string. The extra data also contains a field named + <c>single_line</c>, indicating if the printed log message may + contain line breaks or not. This variant is used when the + formatting of the report depends on the size or single line + parameters.</p> <p>Example, format string and arguments:</p> <code>logger:error("The file does not exist: ~ts",[Filename])</code> <p>Example, string:</p> diff --git a/lib/kernel/doc/src/logger_formatter.xml b/lib/kernel/doc/src/logger_formatter.xml index 5a060fd42b..24772fd6c4 100644 --- a/lib/kernel/doc/src/logger_formatter.xml +++ b/lib/kernel/doc/src/logger_formatter.xml @@ -82,13 +82,6 @@ in STDLIB.</p> <p>Defaults to <c>unlimited</c>.</p> </item> - <tag><c>encoding = </c><seealso marker="stdlib:unicode#type-encoding"> - <c>unicode:encoding()</c></seealso></tag> - <item> - <p>This parameter must reflect the encoding of the device - that the handler prints to.</p> - <p>Defaults to <c>utf8</c></p> - </item> <tag><c>legacy_header = boolean()</c></tag> <item> <p>If set to <c>true</c> a header field is added to diff --git a/lib/kernel/doc/src/logger_std_h.xml b/lib/kernel/doc/src/logger_std_h.xml index b526ed037d..fcd8189bae 100644 --- a/lib/kernel/doc/src/logger_std_h.xml +++ b/lib/kernel/doc/src/logger_std_h.xml @@ -59,13 +59,22 @@ <item> <p>This has the value <c>standard_io</c>, <c>standard_error</c>, <c>{file,LogFileName}</c>, or <c>{file,LogFileName,LogFileOpts}</c>.</p> + <p>If <c>LogFileOpts</c> is specified, it replaces the default + list of options used when opening the log file. The default + list is <c>[raw,append,delayed_write]</c>. One reason to do + so can be to change <c>append</c> to, for + example, <c>write</c>, ensuring that the old log is + truncated when a node is restarted. See the reference manual + for <seealso marker="file#open-2"><c>file:open/2</c></seealso> + for more information about file options.</p> + <p>Log files are always UTF-8 encoded. The encoding can not be + changed by setting the option <c>{encoding,Encoding}</c> + in <c>LogFileOpts</c>.</p> + <p>Notice that the standard handler does not have support for + circular logging. Use the disk_log handler, + <seealso marker="logger_disk_log_h"><c>logger_disk_log_h</c></seealso>, + for this.</p> <p> Defaults to <c>standard_io</c>.</p> - <p>It is recommended not to specify <c>LogFileOpts</c> unless absolutely - necessary. The default options used by the handler to open a file for logging are - <c>raw</c>, <c>append</c>, and <c>delayed_write</c>. Notice that the standard - handler does not have support for circular logging. Use the disk_log handler, - <seealso marker="logger_disk_log_h"><c>logger_disk_log_h</c></seealso>, - for this.</p> </item> <tag><c>filesync_repeat_interval</c></tag> <item> @@ -73,12 +82,12 @@ a file sync operation to write buffered data to disk. The handler attempts the operation repeatedly, but only performs a new sync if something has actually been logged.</p> - <p>Defaults to <c>5000</c> milliseconds.</p> <p>If <c>no_repeat</c> is set as value, the repeated file sync operation is disabled, and it is the operating system settings that determine how quickly or slowly data is written to disk. The user can also call the <seealso marker="logger_std_h#filesync-1"><c>filesync/1</c></seealso> function to perform a file sync.</p> + <p>Defaults to <c>5000</c> milliseconds.</p> </item> </taglist> <p>Other configuration parameters exist, to be used for customizing |