diff options
Diffstat (limited to 'lib/kernel/doc')
| -rw-r--r-- | lib/kernel/doc/src/code.xml | 21 | ||||
| -rw-r--r-- | lib/kernel/doc/src/disk_log.xml | 147 | ||||
| -rw-r--r-- | lib/kernel/doc/src/file.xml | 6 | ||||
| -rw-r--r-- | lib/kernel/doc/src/os.xml | 17 | ||||
| -rw-r--r-- | lib/kernel/doc/src/socket.xml | 2701 | ||||
| -rw-r--r-- | lib/kernel/doc/src/socket_usage.xml | 12 |
6 files changed, 2170 insertions, 734 deletions
diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml index 0d485b25bb..82c91318c3 100644 --- a/lib/kernel/doc/src/code.xml +++ b/lib/kernel/doc/src/code.xml @@ -968,12 +968,6 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), <c>removed</c> otherwise. Modules whose load path is an empty string (which is the convention for auto-generated code) will only be reported as <c>loaded</c> or <c>not_loaded</c>.</p> - <p>For modules that have native code loaded (see - <seemfa marker="#is_module_native/1"><c>is_module_native/1</c></seemfa>), - the MD5 sum of the native code in the object file is used for the - comparison, if it exists; the Beam code in the file is ignored. - Reversely, for modules that do not currently have native code - loaded, any native code in the file will be ignored.</p> <p>See also <seemfa marker="#modified_modules/0"><c>modified_modules/0</c></seemfa>.</p> </desc> </func> @@ -990,17 +984,10 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]), <name name="is_module_native" arity="1" since=""/> <fsummary>Test if a module has native code.</fsummary> <desc> - <p>Returns:</p> - <taglist> - <tag><c>true</c></tag> - <item><p>If <c><anno>Module</anno></c> is the - name of a loaded module that has native code loaded</p></item> - <tag><c>false</c></tag> - <item><p>If <c><anno>Module</anno></c> is loaded but does not have - native code</p></item> - <tag><c>undefined</c></tag> - <item><p>If <c><anno>Module</anno></c> is not loaded</p></item> - </taglist> + <p>Returns <c>false</c> if the given <c><anno>Module</anno></c> is + loaded, and <c>undefined</c> if it is not.</p> + <warning><p>This function is deprecated and will be removed in a future + release.</p></warning> </desc> </func> diff --git a/lib/kernel/doc/src/disk_log.xml b/lib/kernel/doc/src/disk_log.xml index 5a33796005..d49ab07267 100644 --- a/lib/kernel/doc/src/disk_log.xml +++ b/lib/kernel/doc/src/disk_log.xml @@ -127,52 +127,10 @@ functions fail. The corresponding terms (not the binaries) are returned when <c>chunk/2,3</c> is called. </p> - <note><p> - The distributed disk log feature has been deprecated. This - feature has also been scheduled for removal in OTP 24. - </p></note> - <p>A collection of open disk logs with the same name running on - different nodes is said to be a <em>distributed disk log</em> - if requests made to any of the logs are automatically made to - the other logs as well. The members of such a collection are - called individual distributed disk logs, or just distributed - disk logs if there is no risk of confusion. There is no order - between the members of such a collection. For example, logged - terms are not necessarily written to the node where the - request was made before written to the other nodes. However, - a few functions do not make requests to all - members of distributed disk logs, namely - <seemfa marker="#info/1"><c>info/1</c></seemfa>, - <seemfa marker="#chunk/2"><c>chunk/2,3</c></seemfa>, - <seemfa marker="#bchunk/2"><c>bchunk/2,3</c></seemfa>, - <seemfa marker="#chunk_step/3"><c>chunk_step/3</c></seemfa>, and - <seemfa marker="#lclose/1"><c>lclose/1,2</c></seemfa>.</p> - <p>An open disk log that is not a distributed disk - log is said to be a <em>local disk log</em>. A local disk log is - only accessible from the node where the disk log process runs, - whereas a distributed disk log is accessible from all nodes in - the Erlang system, except for those nodes where a local - disk log with the same name as the distributed disk log exists. - All processes on nodes that have access to a local or - distributed disk log can log items or otherwise change, inspect, - or close the log. + <p>An open disk log is only accessible from the node where the disk + log process runs. All processes on the node where the disk log process + runs can log items or otherwise change, inspect, or close the log. </p> - <p>It is not guaranteed that all log files of a distributed disk log - contain the same log items. No attempt is made to synchronize - the contents of the files. However, as long as at least one of - the involved nodes is alive at each time, all items are logged. - When logging items to a distributed log, or otherwise trying to - change the log, the replies from individual logs are - ignored. If all nodes are down, the disk log functions - reply with a <c>nonode</c> error. - </p> - <note> - <p>In some applications, it can be unacceptable that - replies from individual logs are ignored. An alternative in such - situations is to use many local disk logs instead of one - distributed disk log, and implement the distribution without use - of the <c>disk_log</c> module.</p> - </note> <p>Errors are reported differently for asynchronous log attempts and other uses of the <c>disk_log</c> module. When used synchronously, this module replies with an error message, but when called @@ -242,16 +200,28 @@ </datatypes> <funcs> <func> - <name name="accessible_logs" arity="0" since=""/> + <name name="all" arity="0" since="OTP 24.0"/> <fsummary>Return the accessible disk logs on the current node.</fsummary> <desc> <p>Returns the names of the disk logs accessible on the current node. - The first list contains local disk logs and the - second list contains distributed disk logs. </p> </desc> </func> <func> + <name name="accessible_logs" arity="0" since=""/> + <fsummary>Return the accessible disk logs on the current node.</fsummary> + <desc> + <p>Returns the names of the disk logs accessible on the current node. + The first list contains the logs. The second list is always empty + (before Erlang/OTP 24.0 it used to contain so called distributed + disk logs). + </p> + <note><p>This function is deprecated. + Use <seemfa marker="#all/0"><c>all/0</c></seemfa> instead. + </p></note> + </desc> + </func> + <func> <name name="alog" arity="2" since=""/> <name name="balog" arity="2" since=""/> <fsummary>Asynchronously log an item on to a disk log.</fsummary> @@ -409,10 +379,7 @@ </p> <p>The first time <c>chunk()</c> (or <c>bchunk()</c>) is called, an initial continuation, the atom <c>start</c>, must be - provided. If a disk log process is running on the - current node, terms are read from that log. Otherwise, an - individual distributed log on some other node is chosen, if - such a log exists. + provided. </p> <p>When <c>chunk/3</c> is called, <c><anno>N</anno></c> controls the maximum number of terms that are read from the log in each @@ -472,10 +439,8 @@ continuation returned, points to the first log item in the new current file. </p> - <p>If atom <c>start</c> is specified as continuation, a disk log - to read terms from is chosen. A local or distributed disk log - on the current node is preferred to an - individual distributed log on some other node. + <p>If atom <c>start</c> is specified as continuation, the first + file of the wrap log is chosen as the new current file. </p> <p>If the wrap log is not full because all files are not yet used, <c>{error, end_of_log}</c> is returned if trying to @@ -489,7 +454,7 @@ <type name="close_error_rsn"/> <desc> <p><marker id="close_1"></marker>Closes a - local or distributed disk log properly. An internally + disk log properly. An internally formatted log must be closed before the Erlang system is stopped. Otherwise, the log is regarded as unclosed and the automatic repair procedure is activated next time the @@ -542,10 +507,8 @@ <fsummary>Return information about a disk log.</fsummary> <type name="dlog_info"/> <desc> - <p>Returns a list of <c>{Tag, Value}</c> pairs describing the log. - If a disk log process is running on the current node, - that log is used as source of information, otherwise an individual - distributed log on some other node is chosen, if such a log exists. + <p>Returns a list of <c>{Tag, Value}</c> pairs describing a log + running on the node. </p> <p>The following pairs are returned for all logs: </p> @@ -607,17 +570,6 @@ current invocation of function <c>info/1</c> is gathered from the disk log process running on <c><anno>Node</anno></c>.</p> </item> - <tag><c>{distributed, <anno>Dist</anno>}</c></tag> - <item> - <p>If the log is local on - the current node, <c><anno>Dist</anno></c> has the value <c>local</c>, - otherwise all nodes where the log is distributed - are returned as a list.</p> - <warning><p> - The distributed disk log feature has been deprecated. This - feature has also been scheduled for removal in OTP 24. - </p></warning> - </item> </taglist> <p>The following pairs are returned for all logs opened in <c>read_write</c> mode: @@ -698,17 +650,19 @@ <fsummary>Close a disk log on one node.</fsummary> <type name="lclose_error_rsn"/> <desc> - <p><c>lclose/1</c> closes a local log or an individual distributed - log on the current node.</p> - <p><c>lclose/2</c> closes an individual distributed log on the - specified node if the node is not the current one.</p> + <p><c>lclose/1</c> closes a disk log on the current node.</p> + <p><c>lclose/2</c> closes a disk log on the + current node if <anno>Node</anno> is the current node.</p> <p><c>lclose(<anno>Log</anno>)</c> is equivalent to <c>lclose(<anno>Log</anno>, node())</c>. See also <seeerl marker="#close_1"><c>close/1</c></seeerl>. </p> - <p>If no log with the specified name exist on the specified node, + <p>If no log with the specified name exist on the current node, <c>no_such_log</c> is returned. </p> + <note><p>These functions are deprecated. Use + <seemfa marker="#close/1"><c>close/1</c></seemfa> + instead.</p></note> </desc> </func> <func> @@ -723,8 +677,7 @@ <p>Synchronously appends a term to a disk log. Returns <c>ok</c> or <c>{error, <anno>Reason</anno>}</c> when the term is written to - disk. If the log is distributed, <c>ok</c> is returned, - unless all nodes are down. Terms are written by + disk. Terms are written by the ordinary <c>write()</c> function of the operating system. Hence, it is not guaranteed that the term is written to disk, it can linger in @@ -781,9 +734,6 @@ <type name="dlog_options"/> <type name="dlog_option"/> <type name="open_ret"/> - <type name="ret"/> - <type name="dist_open_ret"/> - <type name="dist_error_rsn"/> <type name="open_error_rsn"/> <type name="dlog_optattr"/> <type name="dlog_size"/> @@ -873,18 +823,6 @@ the tuple <c>{error, {size_mismatch, <anno>CurrentSize</anno>, <anno>NewSize</anno>}}</c> is returned.</p> </item> - <tag><c>{distributed, <anno>Nodes</anno>}</c></tag> - <item> - <p>This option can be used for - adding members to a distributed disk log. - Defaults to <c>[]</c>, which means that - the log is local on the current node. - </p> - <warning><p> - The distributed disk log feature has been deprecated. This - feature has also been scheduled for removal in OTP 24. - </p></warning> - </item> <tag><c>{notify, boolean()}</c><marker id="notify"></marker></tag> <item> <p>If <c>true</c>, the log owners @@ -994,10 +932,7 @@ is returned, where <c><anno>Rec</anno></c> is the number of whole Erlang terms found in the file and <c><anno>Bad</anno></c> is the number of bytes in the file that - are non-Erlang terms. If the parameter <c>distributed</c> - is specified, <c>open/1</c> returns a list of - successful replies and a list of erroneous replies. Each - reply is tagged with the node name. + are non-Erlang terms. </p> <p>When a disk log is opened in read-write mode, any existing log file is checked for. If there is none, a new empty @@ -1024,23 +959,9 @@ as owner once again, it is acknowledged with the return value <c>{ok, <anno>Log</anno>}</c>, but the state of the disk log is not affected.</p></note> - <p>If a log with a specified name is local on some node, - and one tries to open the log distributed on the same node, - the tuple <c>{error, {node_already_open, <anno>Log</anno>}}</c> is - returned. The same tuple is returned if the log is distributed on - some node, and one tries to open the log locally on the same node. - Opening individual distributed disk logs for the first time - adds those logs to a (possibly empty) distributed disk log. - The supplied option values are used - on all nodes mentioned by option <c>distributed</c>. - Individual distributed logs know nothing - about each other's option values, so each node can be - given unique option values by creating a distributed - log with many calls to <c>open/1</c>. - </p> <p>A log file can be opened more than once by giving different values to option <c>name</c> or by using the - same file when distributing a log on different nodes. + same file when opening a log on different nodes. It is up to the user of module <c>disk_log</c> to ensure that not more than one disk log process has write access to any file, otherwise the file can be corrupted. diff --git a/lib/kernel/doc/src/file.xml b/lib/kernel/doc/src/file.xml index 9f369e63ff..7332f0ca3b 100644 --- a/lib/kernel/doc/src/file.xml +++ b/lib/kernel/doc/src/file.xml @@ -425,10 +425,16 @@ f.txt: {person, "kalle", 25}. </func> <func> <name name="delete" arity="1" since=""/> + <name name="delete" arity="2" since=""/> <fsummary>Delete a file.</fsummary> + <type name="delete_option"/> <desc> <p>Tries to delete file <c><anno>Filename</anno></c>. Returns <c>ok</c> if successful.</p> + <p>If the option <c>raw</c> is set, the file server is not called. + This can be useful in particular during the early boot stage when + the file server is not yet registered, to still be able to delete + local files.</p> <p>Typical error reasons:</p> <taglist> <tag><c>enoent</c></tag> diff --git a/lib/kernel/doc/src/os.xml b/lib/kernel/doc/src/os.xml index 666aca988f..33b8dbcdb7 100644 --- a/lib/kernel/doc/src/os.xml +++ b/lib/kernel/doc/src/os.xml @@ -173,6 +173,21 @@ DirOut = os:cmd("dir"), % on Win32 platform</code> </func> <func> + <name name="env" arity="0" since="OTP @OTP-16793@"/> + <fsummary>List all environment variables.</fsummary> + <desc> + <p>Returns a list of all environment variables. + Each environment variable is expressed as a tuple + <c>{VarName,Value}</c>, where <c>VarName</c> is the name of + the variable and <c>Value</c> its value.</p> + <p>If Unicode filename encoding is in effect (see the + <seecom marker="erts:erl#file_name_encoding"><c>erl</c> manual + page</seecom>), the strings can contain characters with + codepoints > 255.</p> + </desc> + </func> + + <func> <name name="find_executable" arity="1" since=""/> <name name="find_executable" arity="2" since=""/> <fsummary>Absolute filename of a program.</fsummary> @@ -201,6 +216,8 @@ DirOut = os:cmd("dir"), % on Win32 platform</code> <seecom marker="erts:erl#file_name_encoding"><c>erl</c> manual page</seecom>), the strings can contain characters with codepoints > 255.</p> + <p>Consider using <seemfa marker="#env/0"><c>env/0</c></seemfa> + for a nicer 2-tuple format.</p> </desc> </func> diff --git a/lib/kernel/doc/src/socket.xml b/lib/kernel/doc/src/socket.xml index 66c149ebaa..3873f1a5b4 100644 --- a/lib/kernel/doc/src/socket.xml +++ b/lib/kernel/doc/src/socket.xml @@ -33,13 +33,13 @@ <modulesummary>Socket interface.</modulesummary> <description> <p>This module provides an API for network socket. - Functions are provided to create, delete and manupilate the sockets - aswell as sending and reciving data on them. </p> + Functions are provided to create, delete and manipulate the sockets + as well as sending and receiving data on them. </p> <p>The intent is that it shall be as "close as possible" to the OS level socket interface. The only significant addition is that some of the functions, e.g. <seemfa marker="#recv/3"><c>recv/3</c></seemfa>, - has a timeout argument. </p> + have a timeout argument. </p> <note> <p>Some functions allow for an <i>asynchronous</i> call. This is achieved by setting the <c>Timeout</c> argument to @@ -50,18 +50,34 @@ <c>{select, </c> <seetype marker="#select_info"><c>SelectInfo</c></seetype><c>}</c> (<c>SelectInfo</c> contains the - <seetype marker="socket#select_ref">SelectRef</seetype>). + <seetype marker="socket#select_handle">SelectHandle</seetype>). When data eventually arrives a 'select' message will be sent to the caller: </p> <taglist> <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> <tag></tag> - <item><c>{'$socket', socket(), select, SelectRef}</c></item> + <item><c>{'$socket', socket(), select, SelectHandle}</c></item> </taglist> - <p>The caller can now make another - call to the recv function and now expect data.</p> - <p>Note that all other users are <em>locked out</em> until the - 'current user' has called the function (recv in this case).</p> + <p> + The caller can now make new call + to the recv function and expect data. + </p> + <p> + Note that all other users are <em>locked out</em> until the + 'current user' has called the function (recv in this case). + </p> + <p> + Instead of <c>Timeout = nowait</c> it is equivalent to create a + <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype>) + with + <seemfa marker="erts:erlang#make_ref/0"><c>make_ref()</c></seemfa> + and give as <c>Timeout</c>. + This will then be the <c>SelectHandle</c> in the 'select' message, + which enables a compiler optimization for receiving + a message containing a newly created <c>reference()</c> + (ignore the part of the message queue that had arrived + before the the <c>reference()</c> was created). + </p> <p>Another message the user must be prepared for (when making asynchronous calls) is the <c>abort</c> message:</p> <taglist> @@ -72,7 +88,7 @@ <p>This message indicates that the (asynchronous) operation has been aborted. If, for instance, the socket has been closed (by another process), - <c>Info</c> will be <c>{SelectRef, closed}</c>. </p> + <c>Info</c> will be <c>{SelectHandle, closed}</c>. </p> </note> <note> <p>There is currently <em>no</em> support for Windows. </p> @@ -83,13 +99,42 @@ <datatypes> <datatype> + <name name="invalid"/> + </datatype> + <datatype> <name name="domain"/> + <desc> + <p> + A lowercase <c>atom()</c> representing a protocol domain + on the platform named <c>AF_*</c> (or <c>PF_*</c>). + </p> + </desc> </datatype> <datatype> <name name="type"/> + <desc> + <p> + A lowercase <c>atom()</c> representing a protocol type + on the platform named <c>SOCK_*</c>. + </p> + </desc> </datatype> <datatype> <name name="protocol"/> + <desc> + <p> + An <c>atom()</c> means any protocol as enumerated by the + <c>C</c> library call <c>getprotoent()</c> + on the platform, or at least the supported ones of + <c>ip | ipv6 | tcp | udp | sctp</c>. + </p> + <p>See <seemfa marker="#open/3"><c>open/2,3,4</c></seemfa></p> + <p> + The call + <seemfa marker="#supports/2"><c>supports(protocols)</c></seemfa> + returns the supported protocol atoms. + </p> + </desc> </datatype> <datatype> <name>socket()</name> @@ -105,9 +150,12 @@ </desc> </datatype> <datatype> - <name name="select_ref"/> + <name name="select_handle"/> <desc> - <p>A reference that uniquely identifies the (select) operation.</p> + <p> + A <c>reference()</c> that uniquely identifies + the (select) operation. + </p> </desc> </datatype> <datatype> @@ -120,27 +168,53 @@ <name name="socket_info"/> </datatype> <datatype> - <name name="ip4_address"/> + <name name="in_addr"/> </datatype> <datatype> - <name name="ip6_address"/> + <name name="in6_addr"/> </datatype> <datatype> <name name="sockaddr"/> </datatype> <datatype> - <name name="sockaddr_in4"/> + <name name="sockaddr_in"/> </datatype> <datatype> <name name="sockaddr_in6"/> </datatype> <datatype> <name name="sockaddr_un"/> + <desc> + <p> + The <c>path</c> element will always be a <c>binary</c> when + returned from this module. When supplied to an API function + in this module it may be a <c>string()</c>, which will be + encoded into a binary according to the + <seemfa marker="file#native_name_encoding/0"> + native file name encoding + </seemfa> + on the platform. + </p> + <p> + A terminating zero character will be appended before + the address path is given to the OS, and the terminating + zero will be stripped before giving the address path + to the caller. + </p> + <p> + Linux's non-portable abstract socket address extension is handled + by not doing any terminating zero processing in either direction, + if the first byte of the address is zero. + </p> + </desc> </datatype> <datatype> <name name="sockaddr_ll"/> </datatype> <datatype> + <name name="sockaddr_recv"/> + </datatype> + <datatype> <name name="packet_type"/> </datatype> <datatype> @@ -153,120 +227,927 @@ <name name="in6_scope_id"/> </datatype> <datatype> - <name name="send_flags"/> - </datatype> - <datatype> - <name name="send_flag"/> - </datatype> - <datatype> - <name name="recv_flags"/> - </datatype> - <datatype> - <name name="recv_flag"/> - </datatype> - <datatype> - <name name="shutdown_how"/> + <name name="msg_flag"/> + <desc> + <p> + Flags corresponding to the message flag constants + on the platform. The flags are lowercase and + the constants are uppercase with the prefix <c>MSG_</c>. + </p> + <p> + Some flags are only used for sending, + some only for receiving, + some in received control messages, + and some for several of these. + Not all flags are supported on all platforms. + See the platform's documentation. + </p> + </desc> </datatype> <datatype> - <name name="sockopt_level"/> + <name name="level"/> + <desc> + <p> + The OS protocol levels for, for example, + socket options and control messages, + with the following names in the OS header files: + </p> + <taglist> + <tag><c>socket</c></tag> + <item> + <c>SOL_SOCKET</c> with options named <c>SO_</c>*. + </item> + <tag><c>ip</c></tag> + <item> + <c>IPPROTO_IP</c> a.k.a <c>SOL_IP</c> + with options named <c>IP_</c>*. + </item> + <tag><c>ipv6</c></tag> + <item> + <c>IPPROTO_IPV6</c> a.k.a <c>SOL_IPV6</c> + with options named <c>IPV6_</c>*. + </item> + <tag><c>tcp</c></tag> + <item> + <c>IPPROTO_TCP</c> with options named <c>TCP_</c>*. + </item> + <tag><c>udp</c></tag> + <item> + <c>IPPROTO_UDP</c> with options named <c>UDP_</c>*. + </item> + <tag><c>sctp</c></tag> + <item> + <c>IPPROTO_SCTP</c> with options named <c>SCTP_</c>*. + </item> + </taglist> + <p> + There are many other possible protocols, but the ones + above are those for which this socket library + implements socket options and/or control messages. + </p> + <p> + All protocols known to the OS are enumerated + when the Erlang VM is started. + See the OS man page for protocols(5). + The protocol level 'socket' is always implemented + as <c>SOL_SOCKET</c> and all the others mentioned + in the list above are valid, + if supported by the platform, enumerated or not. + </p> + </desc> </datatype> <datatype> <name name="otp_socket_option"/> + <desc> + <p> + These are socket options for the <c>otp</c> protocol level, + that is <c>{otp, Name}</c> options, + above all OS protocol levels. + They affect Erlang/OTP's socket implementation. + </p> + <taglist> + <tag><c>debug</c></tag> + <item><c>boolean()</c> - Activate debug printout.</item> + <tag><c>iow</c></tag> + <item> + <c>boolean()</c> + - Inform On Wrap of statistics counters. + </item> + <tag><c>controlling_process</c></tag> + <item> + <c>pid()</c> + - The socket "owner". + Only the current controlling process can set this option. + </item> + <tag><c>rcvbuf</c></tag> + <item> + <c> + BufSize :: (default | integer()>0) | + {N :: integer()>0, + BufSize :: (default | integer()>0)} + </c> + - Receive buffer size. + The value <c>default</c> is only valid to <em>set</em>. + <c>N</c> specifies the number of read attempts to do + in a tight loop before assuming no more data is pending. + </item> + <tag><c>rcvctrlbuf</c></tag> + <item> + <c> + BufSize :: (default | integer()>0) + </c> + - Buffer size for received ancillary messages. + The value <c>default</c> is only valid to <em>set</em>. + </item> + <tag><c>sndctrlbuf</c></tag> + <item> + <c> + BufSize :: (default | integer()>0) + </c> + - Buffer size for sent ancillary messages. + The value <c>default</c> is only valid to <em>set</em>. + </item> + <tag><c>fd</c></tag> + <item> + <c>integer()</c> + - Only valid to <em>get</em>. + The OS protocol levels' socket descriptor. + Functions <seemfa marker="#open/1"><c>open/1,2</c></seemfa> + can be used to create a socket according to this module + from an existing OS socket descriptor. + </item> + <tag><c>use_registry</c></tag> + <item> + <c>boolean()</c> + - Only valid to <em>get</em>. + The value is set when the socket is created with + <seemfa marker="#open/2"><c>open/2</c></seemfa> + or + <seemfa marker="#open/4"><c>open/4</c></seemfa>. + </item> + </taglist> + <p> + Options not described here are intentionally undocumented + and for Erlang/OTP internal use only. + </p> + </desc> </datatype> <datatype> <name name="socket_option"/> + <desc> + <p> + Socket option on the form + <c>{Level, Opt}</c> where the OS protocol + <c>Level</c> = + <seetype marker="#level"><c>level()</c></seetype> + and <c>Opt</c> is a socket option on that protocol level. + </p> + <p> + The OS name for an options is, except where otherwise noted, + the <c>Opt</c> atom, in capitals, with prefix according to + <seetype marker="#level"><c>level()</c></seetype>. + </p> + <note><p>See the OS documentation for every socket option.</p></note> + <p> + An option below that has the value type <c>boolean()</c> + will translate the value <c>false</c> + to a C <c>int</c> with value <c>0</c>, + and the value <c>true</c> to <c>!!0</c> (not (not false)). + </p> + <p> + An option with value type <c>integer()</c> + will be translated to a C <c>int</c> that may have + a restricted range, for example byte: <c>0..255</c>. + See the OS documentation. + </p> + <!-- ## Protocol level 'socket' ###################### --> + <p> + <em>Options for protocol level</em> + <seetype marker="#level"><em><c>socket</c></em>:</seetype> + </p> + <taglist> + <tag><c>{socket, acceptconn}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{socket, bindtodevice}</c></tag> + <item><p><c>Value = string()</c></p></item> + <tag><c>{socket, broadcast}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{socket, debug}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{socket, domain}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#domain"><c>domain()</c></seetype> + </p> + <p>Only valid to <em>get</em>.</p> + <p> + The socket's protocol domain. + Does <em>not</em> work on for instance FreeBSD. + </p> + </item> + <tag><c>{socket, dontroute}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{socket, keepalive}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{socket, linger}</c></tag> + <item> + <p> + <c>Value = abort |</c> + <seetype marker="#linger"><c>linger()</c></seetype> + </p> + <p> + The value <c>abort</c> + is shorthand for <c>#{onoff => true, linger => 0}</c>, + and only valid to <em>set</em>. + </p> + </item> + <tag><c>{socket, oobinline}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{socket, passcred}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{socket, peek_off}</c></tag> + <item> + <p><c>Value = integer()</c></p> + <p> + Currently disabled due to a possible infinite loop when calling + <seemfa marker="#recv/1"><c>recv/1-4</c></seemfa> + with + <seetype marker="#msg_flag"><c>peek</c></seetype> + in <c>Flags</c>. + </p> + </item> + <tag><c>{socket, priority}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{socket, protocol}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#protocol"><c>protocol()</c></seetype> + </p> + <p>Only valid to <em>get</em>.</p> + <p> + The socket's protocol. + Does <em>not</em> work on for instance Darwin. + </p> + </item> + <tag><c>{socket, rcvbuf}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{socket, rcvlowat}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{socket, rcvtimeo}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#timeval"><c>timeval()</c></seetype> + </p> + <p> + This option is unsupported per default; + OTP has to be explicitly built with the + <c>--enable-esock-rcvsndtimeo</c> configure option + for this to be available. + </p> + <p> + Since our implementation uses nonblocking sockets, + it is unknown if and how this option works, + or even if it may cause malfunction. + Therefore, we do not recommend setting this option. + </p> + <p> + Instead, use the <c>Timeout</c> argument to, + for instance, the + <seemfa marker="#recv/3"><c>recv/3</c></seemfa> + function. + </p> + </item> + <tag><c>{socket, reuseaddr}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{socket, reuseport}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{socket, sndbuf}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{socket, sndlowat}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{socket, sndtimeo}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#timeval"><c>timeval()</c></seetype> + </p> + <p> + This option is unsupported per default; + OTP has to be explicitly built with the + <c>--enable-esock-rcvsndtimeo</c> configure option + for this to be available. + </p> + <p> + Since our implementation uses nonblocking sockets, + it is unknown if and how this option works, + or even if it may cause malfunction. + Therefore, we do not recommend setting this option. + </p> + <p> + Instead, use the <c>Timeout</c> argument to, + for instance, the + <seemfa marker="#send/3"><c>send/3</c></seemfa> + function. + </p> + </item> + <tag><c>{socket, timestamp}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + + <tag><c>{socket, type}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#type"><c>type()</c></seetype> + </p> + <p>Only valid to <em>get</em>.</p> + <p>The socket's type.</p> + </item> + </taglist> + <p></p> + <!-- ## Protocol level 'ip' ########################## --> + <p> + <em>Options for protocol level</em> + <seetype marker="#level"><em><c>ip</c></em>:</seetype> + </p> + <taglist> + <tag><c>{ip, add_membership}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ip_mreq"><c>ip_mreq()</c></seetype> + </p> + <p>Only valid to <em>set</em>.</p> + </item> + <tag><c>{ip, add_source_membership}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ip_mreq_source"> + <c>ip_mreq_source()</c> + </seetype> + </p> + <p>Only valid to <em>set</em>.</p> + </item> + <tag><c>{ip, block_source}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ip_mreq_source"> + <c>ip_mreq_source()</c> + </seetype> + </p> + <p>Only valid to <em>set</em>.</p> + </item> + <tag><c>{ip, drop_membership}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ip_mreq"><c>ip_mreq()</c></seetype> + </p> + <p>Only valid to <em>set</em>.</p> + </item> + <tag><c>{ip, drop_source_membership}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ip_mreq_source"> + <c>ip_mreq_source()</c> + </seetype> + </p> + <p>Only valid to <em>set</em>.</p> + </item> + <tag><c>{ip, freebind}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, hdrincl}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, minttl}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{ip, msfilter}</c></tag> + <item> + <p> + <c>Value =</c> + <c>null |</c> + <seetype marker="#ip_msfilter"> + <c>ip_msfilter()</c> + </seetype> + </p> + <p>Only valid to <em>set</em>.</p> + <p> + The value <c>null</c> passes a <c>NULL</c> pointer + and size <c>0</c> to the C library call. + </p> + </item> + <tag><c>{ip, mtu}</c></tag> + <item> + <p><c>Value = integer()</c></p> + <p>Only valid to <em>get</em>.</p> + </item> + <tag><c>{ip, mtu_discover}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ip_pmtudisc"> + <c>ip_pmtudisc()</c> + </seetype> + <c>| integer()</c> + </p> + <p> + An <c>integer()</c> value is according + to the platform's header files. + </p> + </item> + <tag><c>{ip, multicast_all}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, multicast_if}</c></tag> + <item> + <p> + <c>Value =</c> + <c>any |</c> + <seetype marker="#in_addr"> + <c>in_addr()</c> + </seetype> + </p> + </item> + <tag><c>{ip, multicast_loop}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, multicast_ttl}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{ip, nodefrag}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, pktinfo}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, recvdstaddr}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, recverr}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, recvif}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, recvopts}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, recvorigdstaddr}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, recvtos}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, recvttl}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, retopts}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, router_alert}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{ip, sendsrcaddr}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, tos}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ip_tos"> + <c>ip_tos()</c> + </seetype> + <c> | integer()</c> + </p> + <p> + An <c>integer()</c> value is according + to the platform's header files. + </p> + </item> + <tag><c>{ip, transparent}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ip, ttl}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{ip, unblock_source}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ip_mreq_source"> + <c>ip_mreq_source()</c> + </seetype> + </p> + <p>Only valid to <em>set</em>.</p> + </item> + </taglist> + <p></p> + <!-- ## Protocol level 'ipv6' ######################## --> + <p> + <em>Options for protocol level</em> + <seetype marker="#level"><em><c>ipv6</c></em>:</seetype> + </p> + <taglist> + <tag><c>{ipv6, addrform}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#domain"> + <c>domain()</c> + </seetype> + </p> + <p> + As far as we know the only valid value is <c>inet</c> + and it is only allowed for an IPv6 socket that is connected + and bound to an IPv4-mapped IPv6 address. + </p> + </item> + <tag><c>{ipv6, add_membership}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ipv6_mreq"><c>ipv6_mreq()</c></seetype> + </p> + <p>Only valid to <em>set</em>.</p> + </item> + <tag><c>{ipv6, authhdr}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, drop_membership}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ipv6_mreq"><c>ipv6_mreq()</c></seetype> + </p> + <p>Only valid to <em>set</em>.</p> + </item> + <tag><c>{ipv6, dstopts}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, flowinfo}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, hoplimit}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, hopopts}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, mtu}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{ipv6, mtu_discover}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ipv6_pmtudisc"> + <c>ipv6_pmtudisc()</c> + </seetype> + <c>| integer()</c> + </p> + <p> + An <c>integer()</c> value is according + to the platform's header files. + </p> + </item> + <tag><c>{ipv6, multicast_hops}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ipv6_hops"><c>ipv6_hops()</c></seetype> + </p> + </item> + <tag><c>{ipv6, multicast_if}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{ipv6, multicast_loop}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, recverr}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, recvhoplimit}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, recvpktinfo}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, recvtclass}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, router_alert}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{ipv6, rthdr}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, tclass}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{ipv6, unicast_hops}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#ipv6_hops"><c>ipv6_hops()</c></seetype> + </p> + </item> + <tag><c>{ipv6, v6only}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + </taglist> + <p></p> + <!-- ## Protocol level 'sctp' ######################## --> + <p> + <em>Options for protocol level</em> + <seetype marker="#level"><em><c>sctp</c></em></seetype>. + See also RFC 6458. + </p> + <taglist> + <tag><c>{sctp, associnfo}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#sctp_assocparams"> + <c>sctp_assocparams()</c> + </seetype> + </p> + </item> + <tag><c>{sctp, autoclose}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{sctp, disable_fragments}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{sctp, events}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#sctp_event_subscribe"> + <c>sctp_event_subscribe()</c> + </seetype> + </p> + <p>Only valid to <em>set</em>.</p> + </item> + <tag><c>{sctp, initmsg}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#sctp_initmsg"> + <c>sctp_initmsg()</c> + </seetype> + </p> + </item> + <tag><c>{sctp, maxseg}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{sctp, nodelay}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{sctp, rtoinfo}</c></tag> + <item> + <p> + <c>Value =</c> + <seetype marker="#sctp_rtoinfo"> + <c>sctp_rtoinfo()</c> + </seetype> + </p> + </item> + </taglist> + <p></p> + <!-- ## Protocol level 'tcp' ######################### --> + <p> + <em>Options for protocol level</em> + <seetype marker="#level"><em><c>tcp</c>:</em></seetype> + </p> + <taglist> + <tag><c>{tcp, congestion}</c></tag> + <item><p><c>Value = string()</c></p></item> + <tag><c>{tcp, cork}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + <tag><c>{tcp, maxseg}</c></tag> + <item><p><c>Value = integer()</c></p></item> + <tag><c>{tcp, nodelay}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + </taglist> + <p></p> + <!-- ## Protocol level 'udp' ######################### --> + <p> + <em>Options for protocol level</em> + <seetype marker="#level"><em><c>udp</c>:</em></seetype> + </p> + <taglist> + <tag><c>{udp, cork}</c></tag> + <item><p><c>Value = boolean()</c></p></item> + </taglist> + </desc> </datatype> <datatype> - <name name="ip_socket_option"/> - </datatype> - <datatype> - <name name="ipv6_socket_option"/> - </datatype> - <datatype> - <name name="tcp_socket_option"/> - </datatype> - <datatype> - <name name="udp_socket_option"/> - </datatype> - <datatype> - <name name="sctp_socket_option"/> + <name name="linger"/> + <desc> + <p> + Corresponds to the C <c>struct linger</c> + for managing the + <seetype marker="#socket_option">socket option</seetype> + <c>{socket, linger}</c>. + </p> + </desc> </datatype> <datatype> <name name="timeval"/> - </datatype> - <datatype> - <name name="ip_tos"/> + <desc> + <p> + Corresponds to the C <c>struct timeval</c>. + The field <c>sec</c> holds seconds, + and <c>usec</c> microseconds. + </p> + </desc> </datatype> <datatype> <name name="ip_mreq"/> + <desc> + <p> + Corresponds to the C <c>struct ip_mreq</c> + for managing multicast groups. + </p> + </desc> </datatype> <datatype> <name name="ip_mreq_source"/> + <desc> + <p> + Corresponds to the C <c>struct ip_mreq_source</c> + for managing multicast groups. + </p> + </desc> </datatype> <datatype> - <name name="ip_pmtudisc"/> + <name name="ip_msfilter"/> + <desc> + <p> + Corresponds to the C <c>struct ip_msfilter</c> + for managing multicast source filtering (RFC 3376). + </p> + </desc> </datatype> <datatype> - <name name="ip_msfilter_mode"/> + <name name="ip_pmtudisc"/> + <desc> + <p> + Lowercase <c>atom()</c> values corresponding to + the C library constants <c>IP_PMTUDISC_*</c>. + Some constant(s) may be unsupported by the platform. + </p> + </desc> </datatype> <datatype> - <name name="ip_msfilter"/> + <name name="ip_tos"/> + <desc> + <p> + Lowercase <c>atom()</c> values corresponding to + the C library constants <c>IPTOS_*</c>. + Some constant(s) may be unsupported by the platform. + </p> + </desc> </datatype> <datatype> <name name="ip_pktinfo"/> </datatype> <datatype> <name name="ipv6_mreq"/> + <desc> + <p> + Corresponds to the C <c>struct ipv6_mreq</c> + for managing multicast groups. + See also RFC 2553. + </p> + </desc> </datatype> <datatype> - <name name="ipv6_pmtudisc"/> + <name name="ipv6_hops"/> + <desc> + <p> + The value <c>default</c> is only valid to <em>set</em> + and is translated to the C value <c>-1</c>, + meaning the route default. + </p> + </desc> </datatype> <datatype> - <name name="ipv6_pktinfo"/> + <name name="ipv6_pmtudisc"/> + <desc> + <p> + Lowercase <c>atom()</c> values corresponding to + the C library constants <c>IPV6_PMTUDISC_*</c>. + Some constant(s) may be unsupported by the platform. + </p> + </desc> </datatype> <datatype> - <name name="sctp_assoc_id"/> + <name name="ipv6_pktinfo"/> </datatype> <datatype> - <name name="sctp_sndrcvinfo"/> + <name name="sctp_assocparams"/> + <desc> + <p> + Corresponds to the C <c>struct sctp_assocparams</c>. + </p> + </desc> </datatype> <datatype> <name name="sctp_event_subscribe"/> - </datatype> - <datatype> - <name name="sctp_assocparams"/> + <desc> + <p> + Corresponds to the C <c>struct sctp_event_subscribe</c>. + </p> + <p> + Not all fields are implemented on all platforms; + unimplemented fields are ignored, + but implemented fields are mandatory. + Note that the '_event' suffixes have been stripped + from the C struct field names, for convenience. + </p> + </desc> </datatype> <datatype> <name name="sctp_initmsg"/> + <desc> + <p> + Corresponds to the C <c>struct sctp_initmsg</c>. + </p> + </desc> </datatype> <datatype> <name name="sctp_rtoinfo"/> + <desc> + <p> + Corresponds to the C <c>struct sctp_rtoinfo</c>. + </p> + </desc> </datatype> <datatype> - <name name="msghdr_flag"/> - </datatype> - <datatype> - <name name="msghdr_flags"/> - </datatype> - <datatype> - <name name="msghdr"/> + <name name="msg"/> </datatype> <datatype> - <name name="cmsghdr_level"/> + <name name="msg_send"/> + <desc> + <p> + Message sent by + <seemfa marker="#sendmsg/2"><c>sendmsg/2,3,4</c></seemfa>. + </p> + <p> + Corresponds to a C <c>struct msghdr</c>, + see your platform documentation for <c>sendmsg(2)</c>. + </p> + <taglist> + <tag><c>addr</c></tag> + <item> + Optional peer address, used on unconnected sockets. + Corresponds to <c>msg_name</c> and <c>msg_namelen</c> + fields of a <c>struct msghdr</c>. + If not used they are set to <c>NULL</c>, <c>0</c>. + </item> + <tag><c>iov</c></tag> + <item> + Mandatory data as a list of binaries. + The <c>msg_iov</c> and <c>msg_iovlen</c> + fields of a <c>struct msghdr</c>. + </item> + <tag><c>ctrl</c></tag> + <item> + Optional list of control messages (CMSG). + Corresponds to the <c>msg_control</c> and <c>msg_controllen</c> + fields of a <c>struct msghdr</c>. + If not used they are set to <c>NULL</c>, <c>0</c>. + </item> + </taglist> + <p> + The <c>msg_flags</c> field of the <c>struct msghdr</c> + is set to <c>0</c>. + </p> + </desc> </datatype> <datatype> - <name name="cmsghdr_type"/> + <name name="msg_recv"/> + <desc> + <p> + Message returned by + <seemfa marker="#recvmsg/1"><c>recvmsg/1,2,3,5</c></seemfa>. + </p> + <p> + Corresponds to a C <c>struct msghdr</c>, + see your platform documentation for <c>recvmsg(2)</c>. + </p> + <taglist> + <tag><c>addr</c></tag> + <item> + Optional peer address, used on unconnected sockets. + Corresponds to <c>msg_name</c> and <c>msg_namelen</c> + fields of a <c>struct msghdr</c>. + If <c>NULL</c> the map key is not present. + </item> + <tag><c>iov</c></tag> + <item> + Data as a list of binaries. + The <c>msg_iov</c> and <c>msg_iovlen</c> + fields of a <c>struct msghdr</c>. + </item> + <tag><c>ctrl</c></tag> + <item> + A possibly empty list of control messages (CMSG). + Corresponds to the <c>msg_control</c> and <c>msg_controllen</c> + fields of a <c>struct msghdr</c>. + </item> + <tag><c>flags</c></tag> + <item> + Message flags. + Corresponds to the <c>msg_flags</c> + field of a <c>struct msghdr</c>. + Unknown flags, if any, are returned in one <c>integer()</c>, + last in the containing list. + </item> + </taglist> + </desc> </datatype> - <!-- <datatype> - <name name="cmsghdr_data"/> + <name name="native_value"/> </datatype> - --> <datatype> - <name name="cmsghdr_recv"/> + <name name="cmsg_send"/> + <desc> + <p> + Control messages (ancillary messages) accepted by + <seemfa marker="#sendmsg/2"><c>sendmsg/2,3,4</c></seemfa>. + </p> + <p> + A control message may for some message types have a + <c>value</c> field with a symbolic value, + or a <c>data</c> field with a native value, + that has to be binary compatible what is defined + in the platform's header files. + </p> + </desc> </datatype> <datatype> - <name name="cmsghdr_send"/> + <name name="cmsg_recv"/> + <desc> + <p> + Control messages (ancillary messages) returned by + <seemfa marker="#recvmsg/1"><c>recvmsg/1,2,3,5</c></seemfa>. + </p> + <p> + A control message has got a <c>data</c> field with + a native (<c>binary</c>) value for the message data, + and may also have a decoded <c>value</c> field + if this socket library succesfully decoded the data. + </p> + </desc> </datatype> <datatype> <name name="icmp_dest_unreach"/> @@ -281,43 +1162,12 @@ <name name="extended_err"/> </datatype> <datatype> - <name name="uint8"/> - </datatype> - <datatype> - <name name="uint16"/> - </datatype> - <datatype> - <name name="uint20"/> - </datatype> - <datatype> - <name name="uint32"/> - </datatype> - <datatype> - <name name="int32"/> - </datatype> - <datatype> - <name name="errcode"/> + <name name="posix"/> <desc> <p> - The POSIX error codes are mostly come from the - OS level socket interface, - but this module may generate some appropriate - POSIX codes. - </p> - <p> - The other values come from this module's lower levels - and are all fairly fatal internal errors: + The POSIX error codes originates from the + OS level socket interface. </p> - <taglist> - <tag><c>exalloc</c></tag> - <item>Memory allocation failed</item> - <tag><c>exmonitor</c></tag> - <item>Failed to set a monitor on a process</item> - <tag><c>exselect</c></tag> - <item>Select operation failed</item> - <tag><c>exself</c></tag> - <item>Failed to get current process</item> - </taglist> </desc> </datatype> </datatypes> @@ -325,36 +1175,78 @@ <funcs> <func> <name name="accept" arity="1" since="OTP 22.0"/> - <name name="accept" arity="2" clause_i="2" since="OTP 22.0"/> + <name name="accept" arity="2" clause_i="3" since="OTP 22.0"/> <fsummary>Accept a connection on a socket.</fsummary> <desc> <p>Accept a connection on a socket.</p> - <p>This call is used with connection-based socket types - (<c>stream</c> or <c>seqpacket</c>). It extracs the first pending - connection request for the listen socket and returns the (newly) - connected socket.</p> + <p> + This call is used with connection oriented socket types + (<c>stream</c> or <c>seqpacket</c>). + It returns the first pending incoming connection + for a listen socket, or waits for one to arrive, + and returns the (newly) connected socket. + </p> </desc> </func> <func> - <name name="accept" arity="2" clause_i="1" anchor="accept_async" since="OTP 22.1"/> + <name name="accept" arity="2" clause_i="4" since="OTP 22.0"/> <fsummary>Accept a connection on a socket.</fsummary> <desc> - <p>Accept a connection on a socket.</p> - - <p>This call is used with connection-based socket types - (<c>stream</c> or <c>seqpacket</c>). It extracs the first pending - connection request for the listen socket and returns the (newly) - connected socket.</p> + <p> + The same as + <seemfa marker="#accept/1">accept/1</seemfa> + but returns <c>{error, timeout}</c> + if no connection has been accepted after + <c><anno>Timeout</anno></c> milliseconds. + </p> + </desc> + </func> - <p>In the case when there is no connections waiting, the function - will return with the <c>SelectInfo</c>. The caller can then await a - select message, <c>{'$socket', Socket, select, Info}</c> (where - <c>Info</c> is the - <seetype marker="socket#select_ref"><c>ref</c></seetype> - field from the <c>SelectInfo</c>), - when a client connects (a subsequent call to accept will then return - the socket). </p> + <func> + <name name="accept" arity="2" clause_i="1" anchor="accept_async" + since="OTP 22.1"/> + <name name="accept" arity="2" clause_i="2" anchor="accept_async" + since="OTP @OTP-16749@"/> + <fsummary>Accept a connection on a socket.</fsummary> + <desc> + <p> + The same as + <seemfa marker="#accept/1">accept/1</seemfa> + but returns promptly. + </p> + <p> + When there is no pending connection to return, + the function will return + <seetype marker="#select_info"><c>{select, <anno>SelectInfo</anno>}</c></seetype>, + and the caller will later receive a select message, + <c>{'$socket', Socket, select, SelectHandle}</c> ( + with the + <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype> + contained in the + <seetype marker="#select_info"> + <c><anno>SelectInfo</anno></c> + </seetype> + ) when a client connects. + A subsequent call to <c>accept/1,2</c> + will then return the socket. + </p> + <p> + If the timeout argument is <c>SelectHandle</c>, + that term will be contained in a returned + <c><anno>SelectInfo</anno></c> + and the corresponding select message. + The <c>SelectHandle</c> is presumed to be + unique to this call. + </p> + <p> + If the timeout argument is <c>nowait</c>, and a + <c><anno>SelectInfo</anno></c> is returned, + it will contain a + <seetype marker="socket#select_handle"> + <c>select_handle()</c> + </seetype> generated by the call. + </p> </desc> </func> @@ -363,11 +1255,26 @@ <fsummary>Bind a name to a socket.</fsummary> <desc> <p>Bind a name to a socket.</p> - <p>When a socket is created - (with <seemfa marker="#open/2"><c>open</c></seemfa>), - it has no address assigned to it. <c>bind</c> assigns the - address specified by the <c>Addr</c> argument.</p> - <p>The rules used for name binding vary between domains.</p> + <p> + When a socket is created + (with <seemfa marker="#open/2"><c>open</c></seemfa>), + it has no address assigned to it. <c>bind</c> assigns the + address specified by the <c>Addr</c> argument. + </p> + <p> + The rules used for name binding vary between domains. + </p> + <p> + If you bind a socket to an address in for example + the 'inet' or 'inet6' address families, + with an ephemeral port number (0), + and want to know which port that was chosen, + you can find out using something like: + <c>{ok, #{port := Port}} =</c> + <seemfa marker ="#sockname/1"> + <c>socket:sockname(<anno>Socket</anno>)</c> + </seemfa> + </p> </desc> </func> @@ -376,10 +1283,11 @@ <fsummary>Cancel an asynchronous request.</fsummary> <desc> <p>Cancel an asynchronous request.</p> - - <p>Call this function in order to cancel a previous - asynchronous call to, e.g. - <seemfa marker="#recv/3"><c>recv/3</c></seemfa>. </p> + <p> + Call this function in order to cancel a previous + asynchronous call to, e.g. + <seemfa marker="#recv/3"><c>recv/3</c></seemfa>. + </p> </desc> </func> @@ -404,72 +1312,277 @@ <func> <name name="connect" arity="2" since="OTP 22.0"/> - <name name="connect" arity="3" clause_i="2" since="OTP 22.0"/> + <name name="connect" arity="3" clause_i="3" since="OTP 22.0"/> <fsummary>Initiate a connection on a socket.</fsummary> <desc> - <p>This function connects the socket to the address - specied by the <c>SockAddr</c> argument.</p> + <p> + This function connects the socket to the address + specified by the <c>SockAddr</c> argument, + and returns when the connection has been established + or failed. + </p> + <p> + If a connection attempt is already in progress + (by another process), <c>{error, already}</c> is returned. + </p> </desc> </func> <func> - <name name="connect" arity="3" clause_i="1" anchor="connect_async" since="OTP 22.1"/> + <name name="connect" arity="3" clause_i="4" since="OTP 22.0"/> <fsummary>Initiate a connection on a socket.</fsummary> <desc> - <p>This function connects the socket to the address - specied by the <c>SockAddr</c> argument.</p> - - <p>In the case when its not possible to immediately establish a - connection, the function will return with the - <seetype marker="#select_info"><c>SelectInfo</c></seetype>. - The caller can then await a - select message, <c>{'$socket', Socket, select, Info}</c> (where - <c>Info</c> is the - <seetype marker="socket#select_ref"><c>ref</c></seetype> - field from the <c>SelectInfo</c>, - a subsequent call to connect will then - establish the connection). </p> - </desc> + <p> + The same as + <seemfa marker="#connect/2">connect/2</seemfa> + but returns <c>{error, timeout}</c> + if no connection has been established + after <c><anno>Timeout</anno></c> milliseconds. + </p> + <note> + <p> + Note that when this call has returned + <c>{error, timeout</c> the connection state of the socket + is uncertain since the platform's network stack + may complete the connection at any time, + up to some platform specific timeout. + </p> + <p> + Repeating a connection attempt towards the same address + would be ok, but towards a different address could + end up with a connection to either address. + </p> + <p> + The safe play would be to close the socket and start over. + </p> + <p> + Also note that all this applies to cancelling + a connect call with a no-wait timeout described below. + </p> + </note> + </desc> </func> <func> - <name name="getopt" arity="3" clause_i="1" since="OTP 22.0"/> - <name name="getopt" arity="3" clause_i="2" since="OTP 22.0"/> - <name name="getopt" arity="3" clause_i="3" since="OTP 22.0"/> - <name name="getopt" arity="3" clause_i="4" since="OTP 22.0"/> - <name name="getopt" arity="3" clause_i="5" since="OTP 22.0"/> - <name name="getopt" arity="3" clause_i="6" since="OTP 22.0"/> - <name name="getopt" arity="3" clause_i="7" since="OTP 22.0"/> - <fsummary>Get an option on a socket.</fsummary> + <name name="connect" arity="3" clause_i="1" anchor="connect_async" + since="OTP 22.1"/> + <name name="connect" arity="3" clause_i="2" anchor="connect_async" + since="OTP @OTP-16749@"/> + <fsummary>Initiate a connection on a socket.</fsummary> <desc> - <p>Get an option on a socket.</p> - <p>What properties are valid depend both on <c>Level</c> and - on what kind of socket it is (<c>domain</c>, <c>type</c> and - <c>protocol</c>).</p> - - <p>See the - <seeguide marker="socket_usage#socket_options">socket options</seeguide> - chapter of the users guide for more info. </p> + <p> + The same as + <seemfa marker="#connect/2">connect/2</seemfa> + but returns promptly. + </p> + <p> + If it is not possible to immediately establish a + connection, the function will return + <seetype marker="#select_info"><c>{select, SelectInfo}</c></seetype>, + and the caller will later receive a select message, + <c>{'$socket', Socket, select, SelectHandle}</c> ( + with the + <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype> + contained in the + <seetype marker="#select_info"><c>SelectInfo</c></seetype> + ) when the connection has been completed or failed. + A subsequent call to + <seemfa marker="#connect/1"><c>connect/1</c></seemfa> + will then finalize the connection and return the result. + </p> + <p> + If the timeout argument is <c>SelectHandle</c>, + that term will be contained in a returned + <c><anno>SelectInfo</anno></c> + and the corresponding select message. + The <c>SelectHandle</c> is presumed to be + unique to this call. + </p> + <p> + If the timeout argument is <c>nowait</c>, and a + <c><anno>SelectInfo</anno></c> is returned, + it will contain a + <seetype marker="socket#select_handle"> + <c>select_handle()</c> + </seetype> generated by the call. + </p> + </desc> + </func> - <note><p>Not all options are valid on all platforms. That is, - even if "we" support an option, that does not mean that the - underlying OS does.</p></note> + <func> + <name name="connect" arity="1" since="OTP @OTP-16749@"/> + <fsummary>Finalize a connection initiation on a socket.</fsummary> + <desc> + <p> + This function finalizes a connection setup on a socket, + after calling + <seemfa marker="#connect/3"> + <c>connect(_, _, nowait | select_handle())</c> + </seemfa> + that returned + <seetype marker="#select_info"><c>{select, SelectInfo}</c></seetype>, + and receiving the select message + <c>{'$socket', Socket, select, SelectHandle}</c>, + and returns whether the connection setup was succesful or not. + </p> + <p> + Instead of calling this function, for backwards compatibility, + it is allowed to call + <seemfa marker="#connect/2"><c>connect/2,3</c></seemfa>, + but that incurs more overhead since the connect address + and timeout are processed in vain. + </p> + </desc> + </func> + <func> + <name name="getopt" arity="2" clause_i="1" since="OTP 22.0"/> + <fsummary> + Get a socket option from the protocol level <c>otp</c>. + </fsummary> + <desc> + <p> + Gets a socket option from the protocol level <c>otp</c>, + which is this implementation's level + above the OS protocol layers. + </p> + <p> + See the type + <seetype marker="#otp_socket_option"> + otp_socket_option() + </seetype> + for a description of the options on this level. + </p> </desc> </func> <func> - <name name="getopt" arity="3" clause_i="8" since="OTP 22.0"/> - <fsummary>Get an option on a socket.</fsummary> + <name name="getopt" arity="2" clause_i="2" since="OTP 22.0"/> + <fsummary> + Get a socket option from one of the OS's protocol levels. + </fsummary> <desc> - <p>Get an option on a socket.</p> + <p> + Gets a socket option from one of the OS's protocol levels. + See the type + <seetype marker="#socket_option">socket_option()</seetype> + for which options that this implementation knows about, + how they are related to option names in the OS, + and if there are known pecularities with any of them. + </p> + <p> + What options are valid depends on what kind of socket it is + (<seetype marker="#domain"><c>domain()</c></seetype>, + <seetype marker="#type"><c>type()</c></seetype> and + <seetype marker="#protocol"><c>protocol()</c></seetype>). + </p> + <p> + See the + <seeguide marker="socket_usage#socket_options"> + socket options + </seeguide> + chapter of the users guide for more info. + </p> + <note> + <p> + Not all options are valid, nor possible to get, + on all platforms. + That is, even if "we" support an option; + it does not mean that the underlying OS does. + </p> + </note> + </desc> + </func> - <p>When specifying <c>Level</c> as an integer, and therefor - using "native mode", it is *currently* up to the caller to - know how to interpret the result.</p> + <func> + <!-- + Backwards compatibility function - remove documentation? + Document the Native clause? + --> + <name since="OTP 22.0"> + getopt(Socket, Level, Opt) -> ok | {error, Reason} + </name> + <fsummary> + Get a socket protocol option. + </fsummary> + <type> + <v> + Socket = <seetype marker="#socket">socket()</seetype> + </v> + <v> + Reason = <seetype marker="inet#posix">inet:posix()</seetype> + | <seetype marker="#invalid"><c>invalid()</c></seetype> + | closed + </v> + </type> + <desc> + <p>Backwards compatibility function.</p> + <p> + The same as + <seemfa marker="#getopt/2"> + <c>getopt(Socket, {Level, Opt})</c> + </seemfa> + </p> + </desc> + </func> - <p>For more info, see - <seemfa marker="#getopt/3">getopt</seemfa> above. </p> + <func> + <name name="getopt_native" arity="3" clause_i="1" since="OTP 22.0"/> + <name name="getopt_native" arity="3" clause_i="2" since="OTP 22.0"/> + <name name="getopt_native" arity="3" clause_i="3" since="OTP 22.0"/> + <name name="getopt_native" arity="3" clause_i="4" since="OTP 24.0"/> + <fsummary>Get a "native" socket option.</fsummary> + <desc> + <p> + Gets a socket option that may be unknown to our + implementation, or that has a type not compatible + with our implementation, that is; in "native mode". + </p> + <p> + The socket option may be specified with an ordinary + <seetype marker="#socket_option"> + <c>socket_option()</c> + </seetype> + tuple, with a known + <seetype marker="#level"> + <c><anno>Level</anno> = level()</c> + </seetype> + and an integer <c><anno>NativeOpt</anno></c>, + or with both an integer <c><anno>NativeLevel</anno></c> + and <c><anno>NativeOpt</anno></c>. + </p> + <p> + How to decode the option value has to be specified + either with <c><anno>ValueType</anno></c>, + by specifying the <c><anno>ValueSize</anno></c> + for a <c>binary()</c> that will contain + the fetched option value, + or by specifying a <c>binary()</c> <c><anno>ValueSpec</anno></c> + that will be copied to a buffer for the + <c>getsockopt()</c> call to write the value + in which will be returned as a new <c>binary()</c>. + </p> + <p> + If <c><anno>ValueType</anno></c> is <c>integer</c> + a <c>C</c> type <c>(int)</c> will be fetched, + if it is <c>boolean</c> a <c>C</c> type <c>(int)</c> + will be fetched and converted into a <c>boolean()</c> + according to the <c>C</c> implementation. + </p> + <p> + What options are valid depends on what kind of socket it is + (<seetype marker="#domain"><c>domain()</c></seetype>, + <seetype marker="#type"><c>type()</c></seetype> and + <seetype marker="#protocol"><c>protocol()</c></seetype>). + </p> + <p> + The integer values for + <c><anno>NativeLevel</anno></c> and + <c><anno>NativeOpt</anno></c> + as well as the <c><anno>Value</anno></c> encoding + has to be deduced from the header files for + the running system. + </p> </desc> </func> @@ -488,6 +1601,30 @@ </func> <func> + <name name="is_supported" arity="1" since="OTP 23.0"/> + <name name="is_supported" arity="2" since="OTP 23.0"/> + <fsummary>Report info about what the platform supports.</fsummary> + <desc> + <p> + This function retreives information about what the + platform supports, such as if SCTP is supported, + or if a socket options are supported. + </p> + <p> + For keys other than the known <c>false</c> is returned. + Note that in a future version or on a different platform + there might be more supported items. + </p> + <p> + This functions returns a <c>boolean</c> corresponding to what + <seemfa marker="#supports/0"><c>supports/0-2</c></seemfa> + reports for the same <c><anno>Key1</anno></c> + (and <c><anno>Key2</anno></c>). + </p> + </desc> + </func> + + <func> <name name="listen" arity="1" since="OTP 22.0"/> <name name="listen" arity="2" since="OTP 22.0"/> <fsummary>Listen for connections on a socket.</fsummary> @@ -518,34 +1655,54 @@ <p>The <c>Opts</c> argument is intended for providing extra information for the open call:</p> <taglist> - <tag><c><![CDATA[dup: boolean()]]></c></tag> + <tag> + <c>domain</c> + </tag> <item> - <p>Shall the provided descriptor be duplicated (dup) or not. - <br/>Defaults to <c>true</c>. </p> + <p> + Which protocol domain is the descriptor of. + See also <seemfa marker="#open/3"><c>open/2,3,4</c></seemfa>. + </p> </item> - <tag><c><![CDATA[debug: boolean()]]></c></tag> + <tag> + <c>type</c> + </tag> <item> - <p>Enable or disable debug during the open call. - <br/>Defaults to <c>false</c>. </p> + <p>Which protocol type type is the descriptor of.</p> + <p> + See also <seemfa marker="#open/3"><c>open/2,3,4</c></seemfa>. + </p> </item> - <tag><c><![CDATA[domain: socket:domain()]]></c></tag> + <tag> + <c>protocol</c> + </tag> <item> - <p>Which domain is the descriptor of. </p> + <p> + Which protocol is the descriptor of. + The atom <c>default</c> is equivalent to the integer + protocol number <c>0</c> which means the default + protocol for a given domain and type. + </p> + <p> + See also <seemfa marker="#open/3"><c>open/2,3,4</c></seemfa>. + </p> </item> - <tag><c><![CDATA[type: socket:type()]]></c></tag> + <tag><c>dup</c></tag> <item> - <p>Which type is the descriptor of. </p> + <p>Shall the provided descriptor be duplicated (dup) or not. + <br/>Defaults to <c>true</c>. </p> </item> - <tag><c><![CDATA[protocol: socket:protocol()]]></c></tag> + <tag><c>debug</c></tag> <item> - <p>Which protocol is the descriptor of. </p> + <p>Enable or disable debug during the open call. + <br/>Defaults to <c>false</c>. </p> </item> - <tag><c><![CDATA[use_registry: boolean()]]></c></tag> + <tag><c>use_registry></c></tag> <item> <p>Enable or disable use of the socket registry for this socket. This overrides the global value. @@ -566,17 +1723,28 @@ <func> <name name="open" arity="2" clause_i="2" since="OTP 22.0"/> - <name name="open" arity="3" since="OTP 22.0"/> + <name name="open" arity="3" clause_i="1" since="OTP 24.0"/> + <name name="open" arity="3" clause_i="2" since="OTP 22.0"/> <name name="open" arity="4" since="OTP 22.0"/> <fsummary>Create an endpoint for communication.</fsummary> <desc> <p>Creates an endpoint (socket) for communication.</p> - <p>For some <c>types</c> there is a default protocol, + <p> + <c><anno>Domain</anno></c> and + <c><anno>Type</anno></c> may be <c>integer()</c>s, + as defined in the platform's header files. + The same goes for <c><anno>Protocol</anno></c> + but according to the platform's <c>services(5)</c> database. + See the OS man page for the library call <c>socket(2)</c> + </p> + + <p>For some <c><anno>Type</anno></c>s there is a default protocol, indicated by <c>default</c>, which it <em>may</em> be possible to specify. - And for <c>Domain = local</c>, if a protocol <em>is</em> pecified, - it <em>must</em> be <c>default</c>. </p> + And for <c>Domain = local</c>, + if a protocol <em>is</em> specified, + it <em>must</em> be <c>default</c>.</p> <p>The <c>Opts</c> argument is intended for "other" options. The supported option(s) are described below:</p> @@ -626,532 +1794,872 @@ <name name="recv" arity="1" since="OTP 22.0"/> <name name="recv" arity="2" since="OTP 22.0"/> <name name="recv" arity="3" clause_i="1" since="OTP 22.0"/> - <name name="recv" arity="3" clause_i="3" since="OTP 22.0"/> - <name name="recv" arity="4" clause_i="2" since="OTP 22.0"/> - <fsummary>Receive a message from a socket.</fsummary> + <name name="recv" arity="3" clause_i="4" since="OTP 22.0"/> + <name name="recv" arity="4" clause_i="3" since="OTP 22.0"/> + <fsummary>Receive data from a socket.</fsummary> <desc> - <p>Receive a message from a socket.</p> - <p>There is a special case for the argument <c>Length</c>. - If it is set to zero (0), it means "give me everything you - currently have".</p> + <p>Receive data from a socket.</p> + <p> + The argument <c><anno>Length</anno></c> + specifies how many bytes to receive, + with the special case <c>0</c> meaning "all available". + </p> + <p> + This call will not return until all requested + data can be delivered. + For "all available" this means the first data + chunk that arrives. + </p> + <p> + The message <c>Flags</c> may be symbolic + <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s and/or + <c>integer()</c>s, as in the platform's appropriate header files. + The values of all symbolic flags and integers are or:ed together. + </p> + <p> + When there is a socket error this function returns + <c>{error, <anno>Reason</anno>}</c>, + or if some data arrived before the error; + <c>{error, {<anno>Reason</anno>, <anno>Data</anno>}}</c>. + </p> </desc> </func> <func> - <name name="recv" arity="3" clause_i="2" anchor="recv_async" since="OTP 22.1"/> - <name name="recv" arity="4" clause_i="1" since="OTP 22.1"/> - <fsummary>Receive a message from a socket.</fsummary> + <name name="recv" arity="3" clause_i="5" since="OTP 22.0"/> + <name name="recv" arity="4" clause_i="4" since="OTP 22.0"/> + <fsummary>Receive data from a socket.</fsummary> <desc> - <p>Receive a message from a socket.</p> + <p> + The same as + <seemfa marker="#recv/1">recv/1,2,3</seemfa> + but returns <c>{error, timeout}</c> or + <c>{error, {timeout, <anno>Data</anno>}}</c> + after <c><anno>Timeout</anno></c> milliseconds, + if the requested data could not be delivered. + </p> + </desc> + </func> - <p>There is a special case for the argument <c>Length</c>. - If it is set to zero (0), it means "give me everything you - currently have".</p> - - <p>In the case when there is no data waiting, the function - will return with the <c>SelectInfo</c>. The caller can then await a - select message, <c>{'$socket', Socket, select, Info}</c> (where - <c>Info</c> is the - <seetype marker="socket#select_ref"><c>ref</c></seetype> - field from the <c>SelectInfo</c>), - when data has arrived (a subsequent call to recv will then return - the data). </p> - <p>Note that if a length (<c>> 0</c>) is specified, and only part - of that amount of data is available, the function will return with - that data <em>and</em> the <c>SelectInfo</c> (if the caller don't - want to wait for the remaining data, it must immediately call - the <seemfa marker="#cancel/2"><c>cancel/2</c></seemfa> function.)</p> + <func> + <name name="recv" arity="3" clause_i="2" since="OTP 22.1" + anchor="recv_async"/> + <name name="recv" arity="3" clause_i="3" since="OTP @OTP-16749@"/> + <name name="recv" arity="4" clause_i="1" since="OTP 22.1"/> + <name name="recv" arity="4" clause_i="2" since="OTP @OTP-16749@"/> + <fsummary>Receive data from a socket.</fsummary> + <desc> + <p> + The same as + <seemfa marker="#recv/1">recv/1,2,3</seemfa> + but if the data can not be immediately delivered, + the function returns + <seetype marker="#select_info"><c>{select, <anno>SelectInfo</anno>}</c></seetype>, + and the caller will then receive a select message, + <c>{'$socket', Socket, select, SelectHandle}</c> ( + with the + <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype> + contained in the + <seetype marker="#select_info"> + <c><anno>SelectInfo</anno></c> + </seetype> + ) when data has arrived. + A subsequent call to <c>recv/1,2,3,4</c> + will then return the data. + </p> + <p> + If the timeout argument is <c>SelectHandle</c>, + that term will be contained in a returned + <c><anno>SelectInfo</anno></c> + and the corresponding select message. + The <c>SelectHandle</c> is presumed to be + unique to this call. + </p> + <p> + If the timeout argument is <c>nowait</c>, and a + <c><anno>SelectInfo</anno></c> is returned, + it will contain a + <seetype marker="socket#select_handle"> + <c>select_handle()</c> + </seetype> generated by the call. + </p> + <p> + Note that if a <c><anno>Length</anno> > 0</c> + and only part of that amount of data is available, + the function will return + <seetype marker="#select_info"> + <c>{ok, {<anno>Data</anno>, <anno>SelectInfo</anno></c> + </seetype> + with partial data. If the caller doesn't want to wait + for more data, it must call + <seemfa marker="#cancel/2"><c>cancel/2</c></seemfa>. + </p> </desc> </func> <func> <name name="recvfrom" arity="1" since="OTP 22.0"/> <name name="recvfrom" arity="2" since="OTP 22.0"/> - <name name="recvfrom" arity="3" clause_i="2" since="OTP 22.0"/> <name name="recvfrom" arity="3" clause_i="3" since="OTP 22.0"/> <name name="recvfrom" arity="3" clause_i="5" since="OTP 22.0"/> - <name name="recvfrom" arity="4" clause_i="2" since="OTP 22.0"/> + <name name="recvfrom" arity="3" clause_i="8" since="OTP 22.0"/> + <name name="recvfrom" arity="4" clause_i="3" since="OTP 22.0"/> <fsummary>Receive a message from a socket.</fsummary> <desc> <p>Receive a message from a socket.</p> - <p>This function reads "messages", which means that regardless of - how much we want to read, it returns when we get a message - (if the buffer size is too small, the message will be truncated).</p> - <p>The <c>BufSz</c> argument basically defines the size of the - receive buffer. By setting the value to zero (0), the configured - size (setopt with <c>Level</c> = <c>otp</c> and - <c>Key</c> = <c>rcvbuf</c>) is used.</p> - <p>It may be impossible to know what (buffer) size is appropriate - "in advance", and in those cases it may be convenient to use the - (recv) 'peek' flag. When this flag is provided, the message is *not* - "consumed" from the underlying buffers, so another recvfrom call - is needed, possibly with a then adjusted buffer size.</p> + <p> + The function returns when a message is received. + Argument <c><anno>BufSz</anno></c> specifies the + number of bytes for the receive buffer. + If the buffer size is too small, + the message will be truncated... + </p> + <p> + If <c><anno>BufSz</anno></c> is not specified or <c>0</c>, + a default buffer size is used, which can be set by + <seemfa marker="#setopt/3"> + <c>socket:setopt(Socket, {otp,recvbuf}, <anno>BufSz</anno>)</c>. + </seemfa> + </p> + <p> + If it is impossible to know the appropriate buffer size, + it may be possible to use the receive + <seetype marker="#msg_flag">message flag</seetype> + <c>peek</c>. When this flag is used, the message is + <em>not</em> "consumed" from the underlying buffers, + so another + <seemfa marker="#recvfrom/1"><c>recvfrom/1,2,3</c></seemfa> + call is needed, possibly with an adjusted buffer size. + </p> + <p> + The message <c>Flags</c> may be symbolic + <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s and/or + <c>integer()</c>s, as in the platform's appropriate header files. + The values of all symbolic flags and integers are or:ed together. + </p> + </desc> + </func> + + <func> + <name name="recvfrom" arity="3" clause_i="4" since="OTP 22.0"/> + <name name="recvfrom" arity="3" clause_i="9" since="OTP 22.0"/> + <name name="recvfrom" arity="4" clause_i="4" since="OTP 22.0"/> + <fsummary>Receive a message from a socket.</fsummary> + <desc> + <p> + The same as + <seemfa marker="#recvfrom/1">recvfrom/1,2,3</seemfa> + but returns <c>{error, timeout}</c> + after <c><anno>Timeout</anno></c> milliseconds, + if the requested data could not be delivered. + </p> </desc> </func> <func> - <name name="recvfrom" arity="3" clause_i="1" anchor="recvfrom_async" since="OTP 22.1"/> - <name name="recvfrom" arity="3" clause_i="4" since="OTP 22.1"/> + <name name="recvfrom" arity="3" clause_i="1" since="OTP 22.1" + anchor="recvfrom_async"/> + <name name="recvfrom" arity="3" clause_i="2" anchor="recvfrom_async" + since="OTP @OTP-16749@"/> + <name name="recvfrom" arity="3" clause_i="6" since="OTP 22.1"/> + <name name="recvfrom" arity="3" clause_i="7" since="OTP @OTP-16749@"/> <name name="recvfrom" arity="4" clause_i="1" since="OTP 22.1"/> + <name name="recvfrom" arity="4" clause_i="2" since="OTP @OTP-16749@"/> <fsummary>Receive a message from a socket.</fsummary> <desc> - <p>Receive a message from a socket.</p> - <p>This function reads "messages", which means that regardless of - how much we want to read, it returns when we get a message - (if the buffer size is too small, the message will be truncated).</p> - <p>The <c>BufSz</c> argument basically defines the size of the - receive buffer. By setting the value to zero (0), the configured - size (setopt with <c>Level</c> = <c>otp</c> and - <c>Key</c> = <c>rcvbuf</c>) is used.</p> - <p>It may be impossible to know what (buffer) size is appropriate - "in advance", and in those cases it may be convenient to use the - (recv) 'peek' flag. When this flag is provided, the message is *not* - "consumed" from the underlying buffers, so another recvfrom call - is needed, possibly with a then adjusted buffer size.</p> - - <p>In the case when there is no data waiting, the function - will return with the <c>SelectInfo</c>. The caller can then await a - select message, <c>{'$socket', Socket, select, Info}</c> (where - <c>Info</c> is the - <seetype marker="socket#select_ref"><c>ref</c></seetype> - field from the <c>SelectInfo</c>), - when data has arrived (a subsequent call to recvfrom will then return - the data). </p> + <p> + The same as + <seemfa marker="#recvfrom/1">recvfrom/1,2,3</seemfa> + but if the data can not be immediately delivered, + the function returns + <seetype marker="#select_info"><c>{select, <anno>SelectInfo</anno>}</c></seetype>, + and the caller will then receive a select message, + <c>{'$socket', Socket, select, SelectHandle}</c> ( + with the + <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype> + contained in the + <seetype marker="#select_info"> + <c><anno>SelectInfo</anno></c> + </seetype> + ) when data has arrived. + A subsequent call to <c>recvfrom/1,2,3,4</c> + will then return the data. + </p> + <p> + If the timeout argument is <c>SelectHandle</c>, + that term will be contained in a returned + <c><anno>SelectInfo</anno></c> + and the corresponding select message. + The <c>SelectHandle</c> is presumed to be + unique to this call. + </p> + <p> + If the timeout argument is <c>nowait</c>, and a + <c><anno>SelectInfo</anno></c> is returned, + it will contain a + <seetype marker="socket#select_handle"> + <c>select_handle()</c> + </seetype> generated by the call. + </p> </desc> </func> <func> <name name="recvmsg" arity="1" since="OTP 22.0"/> <name name="recvmsg" arity="2" clause_i="1" since="OTP 22.0"/> - <name name="recvmsg" arity="2" clause_i="3" since="OTP 22.0"/> - <name name="recvmsg" arity="3" clause_i="2" since="OTP 22.0"/> + <name name="recvmsg" arity="2" clause_i="4" since="OTP 22.0"/> <name name="recvmsg" arity="3" clause_i="3" since="OTP 22.0"/> - <name name="recvmsg" arity="5" clause_i="2" since="OTP 22.0"/> + <name name="recvmsg" arity="3" clause_i="5" since="OTP 22.0"/> + <name name="recvmsg" arity="5" clause_i="3" since="OTP 22.0"/> <fsummary>Receive a message from a socket.</fsummary> <desc> <p>Receive a message from a socket.</p> - <p>This function reads "messages", which means that regardless of - how much we want to read, it returns when we get a message.</p> - <p>The message will be delivered in the form of a <c>msghdr()</c>, - which may contain the source address (if socket not connected), - a list of <c>cmsghdr_recv()</c> (depends on what socket options have - been set and what the protocol and platform supports) and - also a set of flags, providing further info about the read. </p> - - <p>The <c>BufSz</c> argument basically defines the size of the - receive buffer. By setting the value to zero (0), the configured - size (setopt with <c>Level</c> = <c>otp</c> and - <c>Key</c> = <c>rcvbuf</c>) is used.</p> - - <p>The <c>CtrlSz</c> argument basically defines the size of the - receive buffer for the control messages. - By setting the value to zero (0), the configured size (setopt - with <c>Level</c> = <c>otp</c>) is used.</p> - - <p>It may be impossible to know what (buffer) size is appropriate - "in advance", and in those cases it may be convenient to use the - (recv) 'peek' flag. When this flag is provided, the message is *not* - "consumed" from the underlying buffers, so another recvmsg call - is needed, possibly with a then adjusted buffer size.</p> + <p> + The function returns when a message is received. + Arguments <c><anno>BufSz</anno></c> + and <c><anno>CtrlSz</anno></c> specifies the + number of bytes for the receive buffer + and the control message buffer. + If the buffer size(s) is(are) too small, + the message and/or control message list will be truncated... + </p> + <p> + If <c><anno>BufSz</anno></c> is not specified or <c>0</c>, + a default buffer size is used, which can be set by + <seemfa marker="#setopt/3"> + <c>socket:setopt(Socket, {otp,recvbuf}, <anno>BufSz</anno>)</c>. + </seemfa> + The same applies to <c><anno>CtrlSz</anno></c> and + <seemfa marker="#setopt/3"> + <c>socket:setopt(Socket, {otp,recvctrlbuf}, + <anno>CtrlSz</anno>)</c>. + </seemfa> + </p> + <p> + If it is impossible to know the appropriate buffer size, + it may be possible to use the receive + <seetype marker="#msg_flag">message flag</seetype> + <c>peek</c>. When this flag is used, the message is + <em>not</em> "consumed" from the underlying buffers, + so another + <seemfa marker="#recvmsg/1"><c>recvfrom/1,2,3,5</c></seemfa> + call is needed, possibly with an adjusted buffer size. + </p> + <p> + The message <c>Flags</c> may be symbolic + <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s and/or + <c>integer()</c>s, as in the platform's appropriate header files. + The values of all symbolic flags and integers are or:ed together. + </p> </desc> </func> <func> - <name name="recvmsg" arity="2" clause_i="2" anchor="recvmsg_async" since="OTP 22.1"/> + <name name="recvmsg" arity="2" clause_i="5" since="OTP 22.0"/> + <name name="recvmsg" arity="3" clause_i="4" since="OTP 22.0"/> + <name name="recvmsg" arity="5" clause_i="4" since="OTP 22.0"/> + <fsummary>Receive a message from a socket.</fsummary> + <desc> + <p> + The same as + <seemfa marker="#recvmsg/1">recvmsg/1,2,3</seemfa> + but returns <c>{error, timeout}</c> + after <c><anno>Timeout</anno></c> milliseconds, + if the requested data could not be delivered. + </p> + </desc> + </func> + + <func> + <name name="recvmsg" arity="2" clause_i="2" anchor="recvmsg_async" + since="OTP 22.1"/> + <name name="recvmsg" arity="2" clause_i="3" anchor="recvmsg_async" + since="OTP @OTP-16749@"/> <name name="recvmsg" arity="3" clause_i="1" since="OTP 22.1"/> + <name name="recvmsg" arity="3" clause_i="2" since="OTP @OTP-16749@"/> <name name="recvmsg" arity="5" clause_i="1" since="OTP 22.1"/> + <name name="recvmsg" arity="5" clause_i="2" since="OTP @OTP-16749@"/> <fsummary>Receive a message from a socket.</fsummary> <desc> - <p>Receive a message from a socket.</p> - <p>This function reads "messages", which means that regardless of - how much we want to read, it returns when we get a message.</p> - <p>The message will be delivered in the form of a <c>msghdr()</c>, - which may contain the source address (if socket not connected), - a list of <c>cmsghdr_recv()</c> (depends on what socket options have - been set and what the protocol and platform supports) and - also a set of flags, providing further info about the read. </p> - - <p>The <c>BufSz</c> argument basically defines the size of the - receive buffer. By setting the value to zero (0), the configured - size (setopt with <c>Level</c> = <c>otp</c> and - <c>Key</c> = <c>rcvbuf</c>) is used.</p> - - <p>The <c>CtrlSz</c> argument basically defines the size of the - receive buffer for the control messages. - By setting the value to zero (0), the configured size (setopt - with <c>Level</c> = <c>otp</c>) is used.</p> - - <p>It may be impossible to know what (buffer) size is appropriate - "in advance", and in those cases it may be convenient to use the - (recv) 'peek' flag. When this flag is provided, the message is *not* - "consumed" from the underlying buffers, so another recvmsg call - is needed, possibly with a then adjusted buffer size.</p> - - <p>In the case when there is no data waiting, the function - will return with the <c>SelectInfo</c>. The caller can then await a - select message, <c>{'$socket', Socket, select, Info}</c> (where - <c>Info</c> is the - <seetype marker="socket#select_ref"><c>ref</c></seetype> - field from the <c>SelectInfo</c>), - when data has arrived (a subsequent call to recvmsg will then return - the data). </p> + <p> + The same as + <seemfa marker="#recvmsg/1">recvmsg/1,2,3</seemfa> + but if the data can not be immediately delivered, + the function returns + <seetype marker="#select_info"><c>{select, <anno>SelectInfo</anno>}</c></seetype>, + and the caller will then receive a select message, + <c>{'$socket', Socket, select, SelectHandle}</c> ( + with the + <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype> + contained in the + <seetype marker="#select_info"> + <c><anno>SelectInfo</anno></c> + </seetype> + ) when data has arrived. + A subsequent call to <c>recvmsg/1,2,3,5</c> + will then return the data. + </p> + <p> + If the timeout argument is <c>SelectHandle</c>, + that term will be contained in a returned + <c><anno>SelectInfo</anno></c> + and the corresponding select message. + The <c>SelectHandle</c> is presumed to be + unique to this call. + </p> + <p> + If the timeout argument is <c>nowait</c>, and a + <c><anno>SelectInfo</anno></c> is returned, + it will contain a + <seetype marker="socket#select_handle"> + <c>select_handle()</c> + </seetype> generated by the call. + </p> </desc> </func> <func> <name name="send" arity="2" since="OTP 22.0"/> <name name="send" arity="3" clause_i="1" since="OTP 22.0"/> - <name name="send" arity="3" clause_i="3" since="OTP 22.0"/> - <name name="send" arity="4" clause_i="2" since="OTP 22.0"/> - <fsummary>Send a message on a socket.</fsummary> + <name name="send" arity="3" clause_i="4" since="OTP 22.0"/> + <name name="send" arity="4" clause_i="3" since="OTP 22.0"/> + <fsummary>Send data on a socket.</fsummary> <desc> - <p>Send a message on a connected socket.</p> + <p>Send data on a connected socket.</p> + <p> + This call will not return until the data has been + handed over to the platform's network layer. + </p> + <p> + The message <c>Flags</c> may be symbolic + <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s and/or + <c>integer()</c>s, as in the platform's appropriate header files. + The values of all symbolic flags and integers are or:ed together. + </p> </desc> </func> <func> - <name name="send" arity="3" clause_i="2" anchor="send_async" since="OTP 22.1"/> + <name name="send" arity="3" clause_i="5" since="OTP 22.0"/> + <name name="send" arity="4" clause_i="4" since="OTP 22.0"/> + <fsummary>Send data on a socket.</fsummary> + <desc> + <p> + The same as + <seemfa marker="#send/2">send/2,3</seemfa> + but returns <c>{error, timeout}</c> + after <c><anno>Timeout</anno></c> milliseconds, + if the data could not be handed over + to the platform network layer. + </p> + </desc> + </func> + + <func> + <name name="send" arity="3" clause_i="2" since="OTP 22.1" + anchor="send_async"/> + <name name="send" arity="3" clause_i="3" since="OTP @OTP-16749@"/> <name name="send" arity="4" clause_i="1" since="OTP 22.1"/> - <fsummary>Send a message on a socket.</fsummary> + <name name="send" arity="4" clause_i="2" since="OTP @OTP-16749@"/> + <fsummary>Send data on a socket.</fsummary> <desc> - <p>Send a message on a connected socket.</p> - - <p>In the case when there is no room in the (system-) buffers, - the function will return with the <c>SelectInfo</c>. The caller - can then await a select message, - <c>{'$socket', Socket, select, Info}</c> - (where <c>Info</c> is the - <seetype marker="socket#select_ref"><c>ref</c></seetype> - field from the - <c>SelectInfo</c>), when there is room for more data (a subsequent - call to send will then send the data). </p> - <p>Note that if not all the data was sent, the function will return - with the remaining data <em>and</em> the <c>SelectInfo</c> - (if the caller don't - want to wait to be able to send the rest, it should immediately call - the <seemfa marker="#cancel/2"><c>cancel/2</c></seemfa> function.)</p> + <p> + The same as + <seemfa marker="#send/2">send/2,3</seemfa>, + but if the data can not be immediately handed over + to the platform network layer, + the function returns + <seetype marker="#select_info"><c>{select, <anno>SelectInfo</anno>}</c></seetype>, + and the caller will then receive a select message, + <c>{'$socket', Socket, select, SelectHandle}</c> ( + with the + <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype> + contained in the + <seetype marker="#select_info"> + <c><anno>SelectInfo</anno></c> + </seetype> + ) when there is room for more data. + A subsequent call to <c>send/2-4</c> will then send the data. + </p> + <p> + If the timeout argument is <c>SelectHandle</c>, + that term will be contained in a returned + <c><anno>SelectInfo</anno></c> + and the corresponding select message. + The <c>SelectHandle</c> is presumed to be + unique to this call. + </p> + <p> + If the timeout argument is <c>nowait</c>, and a + <c><anno>SelectInfo</anno></c> is returned, + it will contain a + <seetype marker="socket#select_handle"> + <c>select_handle()</c> + </seetype> generated by the call. + </p> + <p> + Note that if some of the data was sent, the function will return + <seetype marker="#select_info"> + <c>{ok, {<anno>RestData</anno>, <anno>SelectInfo</anno>}</c> + </seetype> + If the caller does not want to wait to send the rest, + it should call + <seemfa marker="#cancel/2"><c>cancel/2</c></seemfa>. + </p> + <p> + <c><anno>RestData</anno></c> is also returned with + an error, but then it is unclear if the network stack + managed to send some data before the error. + </p> </desc> </func> <func> <name name="sendmsg" arity="2" since="OTP 22.0"/> <name name="sendmsg" arity="3" clause_i="1" since="OTP 22.0"/> - <name name="sendmsg" arity="3" clause_i="3" since="OTP 22.0"/> - <name name="sendmsg" arity="4" clause_i="2" since="OTP 22.0"/> + <name name="sendmsg" arity="3" clause_i="4" since="OTP 22.0"/> + <name name="sendmsg" arity="4" clause_i="3" since="OTP 22.0"/> <fsummary>Send a message on a socket.</fsummary> <desc> - <p>Send a message on a socket. The destination, if needed - (socket <em>not</em> connected) is provided in the <c>MsgHdr</c>, - which also contains the message to send, - The <c>MsgHdr</c> may also contain an list of optional <c>cmsghdr_send()</c> - (depends on what the protocol and platform supports).</p> - - <p>Unlike the <seemfa marker="#send/2"><c>send</c></seemfa> function, - this one sends <em>one message</em>. - This means that if, for whatever reason, its not possible to send the - message in one go, the function will instead return with the - <em>remaining</em> data (<c>{ok, Remaining}</c>). Thereby leaving it - up to the caller to decide what to do (retry with the remaining data - of give up). </p> - + <p>Send a message on a socket.</p> + <p> + The destination, if needed (socket <em>not</em> connected) + is provided in <c><anno>Msg</anno></c>, + which also contains the message to send, + <c>Msg</c> may also contain an list of optional + <seetype marker="#cmsg_send">control messages</seetype> + (depends on what the protocol and platform supports). + </p> + <p> + Unlike the <seemfa marker="#send/2"><c>send</c></seemfa> function, + this one sends <em>one message</em>. + That means that if, for whatever reason, + it is not possible to send the message in one go, + this function will return the <em>remaining</em> data + (<c>{ok, <anno>Remaining</anno>}</c>), + thereby leaving it up to the caller to decide what to do + (retry with the remaining data or give up, etc). + </p> + <p> + This call will not return until the data has been + handed over to the platform's network layer. + </p> + <p> + The message <c>Flags</c> may be symbolic + <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s and/or + <c>integer()</c>s, as in the platform's appropriate header files. + The values of all symbolic flags and integers are or:ed together. + </p> </desc> </func> <func> - <name name="sendmsg" arity="3" clause_i="2" anchor="sendmsg_async" since="OTP 22.1"/> - <name name="sendmsg" arity="4" clause_i="1" since="OTP 22.1"/> + <name name="sendmsg" arity="3" clause_i="5" since="OTP 22.0"/> + <name name="sendmsg" arity="4" clause_i="4" since="OTP 22.0"/> <fsummary>Send a message on a socket.</fsummary> <desc> - <p>Send a message on a socket. The destination, if needed - (socket <em>not</em> connected) is provided in the <c>MsgHdr</c>, - which also contains the message to send, - The <c>MsgHdr</c> may also contain an list of optional <c>cmsghdr_send()</c> - (depends on what the protocol and platform supports).</p> - - <p>Unlike the <seemfa marker="#send/2"><c>send</c></seemfa> function, - this one sends <em>one message</em>. - This means that if, for whatever reason, its not possible to send the - message in one go, the function will instead return with the - <em>remaining</em> data (<c>{ok, Remaining}</c>). Thereby leaving it - up to the caller to decide what to do (retry with the remaining data - of give up). </p> - - <p>In the case when there is no room in the (system-) buffers, - the function will return with the <c>SelectInfo</c>. The caller - can then await a select message, - <c>{'$socket', Socket, select, Info}</c> - (where <c>Info</c> is the - <seetype marker="socket#select_ref"><c>ref</c></seetype> - field from the - <c>SelectInfo</c>), when there is room for more data (a subsequent - call to sendmsg will then send the data). </p> + <p> + The same as + <seemfa marker="#sendmsg/2">sendmsg/2,3</seemfa> + but returns <c>{error, timeout}</c> + after <c><anno>Timeout</anno></c> milliseconds, + if the data could not be handed over + to the platform network layer. + </p> </desc> </func> <func> - <name name="sendto" arity="3" since="OTP 22.0"/> - <name name="sendto" arity="4" clause_i="1" since="OTP 22.0"/> - <name name="sendto" arity="4" clause_i="3" since="OTP 22.0"/> - <name name="sendto" arity="5" clause_i="2" since="OTP 22.0"/> + <name name="sendmsg" arity="3" clause_i="2" since="OTP 22.1" + anchor="sendmsg_async"/> + <name name="sendmsg" arity="3" clause_i="3" since="OTP @OTP-16749@"/> + <name name="sendmsg" arity="4" clause_i="1" since="OTP 22.1"/> + <name name="sendmsg" arity="4" clause_i="2" since="OTP @OTP-16749@"/> <fsummary>Send a message on a socket.</fsummary> <desc> - <p>Send a message on a socket, to the specified destination.</p> + <p> + The same as + <seemfa marker="#sendmsg/2">sendmsg/2,3</seemfa> + but if the data can not be immediately handed over + to the platform network layer, + the function returns + <seetype marker="#select_info"><c>{select, <anno>SelectInfo</anno>}</c></seetype>, + and the caller will then receive a select message, + <c>{'$socket', Socket, select, SelectHandle}</c> ( + with the + <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype> + contained in the + <seetype marker="#select_info"> + <c><anno>SelectInfo</anno></c> + </seetype> + ) when there is room for more data. + A subsequent call to <c>sendmsg/2-4</c> will then send the data. + </p> + <p> + If the timeout argument is <c>SelectHandle</c>, + that term will be contained in a returned + <c><anno>SelectInfo</anno></c> + and the corresponding select message. + The <c>SelectHandle</c> is presumed to be + unique to this call. + </p> + <p> + If the timeout argument is <c>nowait</c>, and a + <c><anno>SelectInfo</anno></c> is returned, + it will contain a + <seetype marker="socket#select_handle"> + <c>select_handle()</c> + </seetype> generated by the call. + </p> </desc> </func> <func> - <name name="sendto" arity="4" clause_i="2" anchor="sendto_async" since="OTP 22.1"/> - <name name="sendto" arity="5" clause_i="1" since="OTP 22.1"/> - <fsummary>Send a message on a socket.</fsummary> + <name name="sendto" arity="3" since="OTP 22.0"/> + <name name="sendto" arity="4" clause_i="1" since="OTP 22.0"/> + <name name="sendto" arity="4" clause_i="4" since="OTP 22.0"/> + <name name="sendto" arity="5" clause_i="3" since="OTP 22.0"/> + <fsummary>Send data on a socket.</fsummary> <desc> - <p>Send a message on a socket, to the specified destination.</p> - - <p>In the case when there is no room in the (system-) buffers, - the function will return with the <c>SelectInfo</c>. The caller - can then await a select message, - <c>{'$socket', Socket, select, Info}</c> - (where <c>Info</c> is the - <seetype marker="socket#select_ref"><c>ref</c></seetype> - field from the - <c>SelectInfo</c>), when there is room for more data (a subsequent - call to sendto will then send the data). </p> + <p>Send data on a socket, to the specified destination.</p> + <p> + This call will not return until the data has been + handed over to the platform's network layer. + </p> + <p> + The message <c>Flags</c> may be symbolic + <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s and/or + <c>integer()</c>s, as in the platform's appropriate header files. + The values of all symbolic flags and integers are or:ed together. + </p> </desc> </func> <func> - <name name="setopt" arity="4" clause_i="1" since="OTP 22.0"/> - <name name="setopt" arity="4" clause_i="2" since="OTP 22.0"/> - <name name="setopt" arity="4" clause_i="3" since="OTP 22.0"/> - <name name="setopt" arity="4" clause_i="4" since="OTP 22.0"/> - <name name="setopt" arity="4" clause_i="5" since="OTP 22.0"/> - <name name="setopt" arity="4" clause_i="6" since="OTP 22.0"/> - <name name="setopt" arity="4" clause_i="7" since="OTP 22.0"/> - <name name="setopt" arity="4" clause_i="8" since="OTP 22.0"/> - <fsummary>Set an option on a socket.</fsummary> - <desc> - <p>Set an option on a socket.</p> - <p>What options are valid depend both on <c>Level</c> and on - what kind of socket it is (<c>domain</c>, <c>type</c> and - <c>protocol</c>).</p> - - <p>See the - <seeguide marker="socket_usage#socket_options">socket options</seeguide> - chapter of the users guide for more info. </p> - - <note><p>Not all options are valid on all platforms. That is, - even if "we" support an option, that does not mean that the - underlying OS does.</p></note> - - <note><p>Sockets are set 'non-blocking' when created, so this option - is *not* available (as it would adversely effect the Erlang VM - to set a socket 'blocking').</p></note> + <name name="sendto" arity="4" clause_i="5" since="OTP 22.0"/> + <name name="sendto" arity="5" clause_i="4" since="OTP 22.0"/> + <fsummary>Send data on a socket.</fsummary> + <desc> + <p> + The same as + <seemfa marker="#sendto/3">sendto/3,4</seemfa> + but returns <c>{error, timeout}</c> + after <c><anno>Timeout</anno></c> milliseconds, + if the data could not be handed over + to the platform network layer. + </p> </desc> </func> <func> - <name name="setopt" arity="4" clause_i="8" since="OTP 22.0"/> - <fsummary>Set options on a socket.</fsummary> + <name name="sendto" arity="4" clause_i="2" since="OTP 22.1" + anchor="sendto_async"/> + <name name="sendto" arity="4" clause_i="3" since="OTP @OTP-16749@"/> + <name name="sendto" arity="5" clause_i="1" since="OTP 22.1"/> + <name name="sendto" arity="5" clause_i="2" since="OTP @OTP-16749@"/> + <fsummary>Send data on a socket.</fsummary> <desc> - <p>Set options on a socket.</p> - - <p>When specifying <c>Level</c> as an integer, and therefor - using "native mode", it is *currently* up to the caller to - know how to encode the <c>Value</c>.</p> - - <p>For more info, see - <seemfa marker="#setopt/4">setopt</seemfa> above. </p> + <p> + The same as + <seemfa marker="#sendto/3">sendto/3,4</seemfa>, + but if the data can not be immediately handed over + to the platform network layer, + the function returns + <seetype marker="#select_info"><c>{select, <anno>SelectInfo</anno>}</c></seetype>, + and the caller will then receive a select message, + <c>{'$socket', Socket, select, SelectHandle}</c> ( + with the + <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype> + contained in the + <seetype marker="#select_info"> + <c><anno>SelectInfo</anno></c> + </seetype> + ) when there is room for more data. + A subsequent call to <c>sendto/3-5</c> will then send the data. + </p> + <p> + If the timeout argument is <c>SelectHandle</c>, + that term will be contained in a returned + <c><anno>SelectInfo</anno></c> + and the corresponding select message. + The <c>SelectHandle</c> is presumed to be + unique to this call. + </p> + <p> + If the timeout argument is <c>nowait</c>, and a + <c><anno>SelectInfo</anno></c> is returned, + it will contain a + <seetype marker="socket#select_handle"> + <c>select_handle()</c> + </seetype> generated by the call. + </p> </desc> </func> <func> - <name name="shutdown" arity="2" since="OTP 22.0"/> - <fsummary>Shut down part of a full-duplex connection.</fsummary> + <name name="setopt" arity="3" clause_i="1" since="OTP 22.0"/> + <fsummary> + Set a socket option in the protocol level <c>otp</c>. + </fsummary> <desc> - <p>Shut down all or part of a full-duplex connection.</p> + <p> + Sets a socket option in the protocol level <c>otp</c>, + which is this implementation's level + above the OS protocol layers. + </p> + <p> + See the type + <seetype marker="#otp_socket_option"> + otp_socket_option() + </seetype> + for a description of the options on this level. + </p> </desc> </func> <func> - <name name="sockname" arity="1" since="OTP 22.0"/> - <fsummary>Get socket name.</fsummary> + <name name="setopt" arity="3" clause_i="2" since="OTP 22.0"/> + <fsummary> + Set a socket option in one of the OS's protocol levels. + </fsummary> <desc> - <p>Returns the current address to which the socket is bound.</p> + <p> + Set a socket option in one of the OS's protocol levels. + See the type + <seetype marker="#socket_option">socket_option()</seetype> + for which options that this implementation knows about, + how they are related to option names in the OS, + and if there are known pecularities with any of them. + </p> + <p> + What options are valid depends on what kind of socket it is + (<seetype marker="#domain"><c>domain()</c></seetype>, + <seetype marker="#type"><c>type()</c></seetype> and + <seetype marker="#protocol"><c>protocol()</c></seetype>). + </p> + <p> + See the + <seeguide marker="socket_usage#socket_options"> + socket options + </seeguide> + chapter of the users guide for more info. + </p> + <note> + <p> + Not all options are valid, nor possible to set, + on all platforms. + That is, even if "we" support an option; + it does not mean that the underlying OS does. + </p> + </note> </desc> </func> <func> - <name since="OTP 22.0"> - supports() -> Supports - </name> - <name since="OTP 22.0"> - supports(Key1 :: options) -> SupportsOptions - </name> - <name since="OTP 22.0"> - supports(Key1 :: send_flags) -> SupportsSendFlags - </name> - <name since="OTP 22.0"> - supports(Key1 :: recv_flags) -> SupportsRecvFlags - </name> - <name since="OTP 22.0"> - supports(Key1 :: options, Key2 :: socket) -> SupportsOptionsSocket - </name> - <name since="OTP 22.0"> - supports(Key1 :: options, Key2 :: ip) -> SupportsOptionsIP - </name> - <name since="OTP 22.0"> - supports(Key1 :: options, Key2 :: ipv6) -> SupportsOptionsIPv6 - </name> - <name since="OTP 22.0"> - supports(Key1 :: options, Key2 :: tcp) -> SupportsOptionsTCP - </name> - <name since="OTP 22.0"> - supports(Key1 :: options, Key2 :: udp) -> SupportsOptionsUDP - </name> - <name since="OTP 22.0"> - supports(Key1 :: options, Key2 :: sctp) -> SupportsOptionsSCTP - </name> <!-- - <name name="supports" arity="0" since="OTP 22.0"/> - <name name="supports" arity="1" since="OTP 22.0"/> - <name name="supports" arity="2" since="OTP 22.0"/> + Backwards compatibility function - remove documentation? + Document the Native clause? --> - <fsummary>Report info about what the platform supports.</fsummary> + <name since="OTP 22.0"> + setopt(Socket, Level, Opt, Value) -> ok | {error, Reason} + </name> + <fsummary> + Set a socket protocol option. + </fsummary> <type> <v> - Supports :: [{Feature, boolean()} - | {send_flags, SupportsSendFlags} - | {recv_flags, SupportsRecvFlags} - | {options, SupportsOptions}] - </v> - <v>Feature :: sctp | ipv6 | local | netns</v> - <v> - SupportsSendFlags :: - [{<seetype marker="#send_flag">send_flag()</seetype>, boolean()}] - </v> - <v> - SupportsRecvFlags :: - [{<seetype marker="#recv_flag">recv_flag()</seetype>, boolean()}] - </v> - <v> - SupportsOptions :: - [{socket, SupportsOptionsSocket} - | {ip, SupportsOptionsIP} - | {ipv6, SupportsOptionsIPv6} - | {tcp, SupportsOptionsTCP} - | {udp, SupportsOptionsUDP} - | {sctp, SupportsOptionsSCTP}] - </v> - <v> - SupportsOptionsSocket :: - [{<seetype marker="#socket_option">socket_option()</seetype>, boolean()}] - </v> - <v> - SupportsOptionsIP :: - [{<seetype marker="#ip_socket_option">ip_socket_option()</seetype>, boolean()}] - </v> - <v> - SupportsOptionsIPv6 :: - [{<seetype marker="#ipv6_socket_option">ipv6_socket_option()</seetype>, boolean()}] - </v> - <v> - SupportsOptionsTCP :: - [{<seetype marker="#tcp_socket_option">tcp_socket_option()</seetype>, boolean()}] + Socket = <seetype marker="#socket">socket()</seetype> </v> <v> - SupportsOptionsUDP :: - [{<seetype marker="#udp_socket_option">udp_socket_option()</seetype>, boolean()}] + Value = term() </v> <v> - SupportsOptionsSCTP :: - [{<seetype marker="#sctp_socket_option">sctp_socket_option()</seetype>, boolean()}] + Reason = <seetype marker="inet#posix">inet:posix()</seetype> + | <seetype marker="#invalid"><c>invalid()</c></seetype> + | closed </v> </type> <desc> + <p>Backwards compatibility function.</p> + <p> + The same as + <seemfa marker="#setopt/3"> + <c>setopt(Socket, {Level, Opt}, Value)</c> + </seemfa> + </p> + </desc> + </func> + + <func> + <name name="setopt_native" arity="3" since="OTP 22.0"/> + <fsummary>Set a "native" socket option.</fsummary> + <desc> + <p> + Sets a socket option that may be unknown to our + implementation, or that has a type not compatible + with our implementation, that is; in "native mode". + </p> <p> - This function retreives information about what the - platform supports, such as if SCTP is supported, - or which socket options are supported. + If <c><anno>Value</anno></c> is an <c>integer()</c> + it will be used as a <c>C</c> type <c>(int)</c>, + if it is a <c>boolean()</c> it will be used + as a <c>C</c> type <c>(int)</c> with the <c>C</c> + implementations values for <c>false</c> or <c>true</c>, + and if it is a <c>binary()</c> its content and size + will be used as the option value. </p> <p> - For keys other than the known the empty list is returned, - Note that in a future version or on a different platform - there might be more supported items. + The socket option may be specified with an ordinary + <seetype marker="#socket_option"> + <c>socket_option()</c> + </seetype> + tuple, with a known + <seetype marker="#level"> + <c><anno>Level</anno> = level()</c> + </seetype> + and an integer <c><anno>NativeOpt</anno></c>, + or with both an integer <c><anno>NativeLevel</anno></c> + and <c><anno>NativeOpt</anno></c>. + </p> + <p> + What options are valid depends on what kind of socket it is + (<seetype marker="#domain"><c>domain()</c></seetype>, + <seetype marker="#type"><c>type()</c></seetype> and + <seetype marker="#protocol"><c>protocol()</c></seetype>). + </p> + <p> + The integer values for + <c><anno>NativeLevel</anno></c> and + <c><anno>NativeOpt</anno></c> + as well as the encoding of <c><anno>Value</anno></c> + has to be deduced from the header files for + the running system. </p> </desc> </func> <func> - <name since="OTP 23.0"> - is_supported(Key1 :: sctp | ipv6 | local | netns) -> boolean() - </name> - <name since="OTP 23.0"> - is_supported(Key1 :: send_flags, Key2 :: SendFlag) -> boolean() - </name> - <name since="OTP 23.0"> - is_supported(Key1 :: recv_flags, Key2 :: RecvFlag) -> boolean() - </name> - <name since="OTP 23.0"> - is_supported(Key1 :: options, Key2 :: socket, Key3 :: SocketOption) -> - boolean() - </name> - <name since="OTP 23.0"> - is_supported(Key1 :: options, Key2 :: ip, Key3 :: IPSocketOption) -> - boolean() - </name> - <name since="OTP 23.0"> - is_supported(Key1 :: options, Key2 :: ipv6, Key3 :: IPv6SocketOption) -> - boolean() - </name> - <name since="OTP 23.0"> - is_supported(Key1 :: options, Key2 :: tcp, Key3 :: TCPSocketOption) -> - boolean() - </name> - <name since="OTP 23.0"> - is_supported(Key1 :: options, Key2 :: udp, Key3 :: UDPSocketOption) -> - boolean() - </name> - <name since="OTP 23.0"> - is_supported(Key1 :: options, Key2 :: sctp, Key3 :: SCTPSocketOption) -> - boolean() - </name> + <name name="shutdown" arity="2" since="OTP 22.0"/> + <fsummary>Shut down part of a full-duplex connection.</fsummary> + <desc> + <p>Shut down all or part of a full-duplex connection.</p> + </desc> + </func> + + <func> + <name name="sockname" arity="1" since="OTP 22.0"/> + <fsummary>Get socket name.</fsummary> + <desc> + <p>Returns the current address to which the socket is bound.</p> + </desc> + </func> + + <func> + <name name="supports" arity="0" since="OTP 22.0"/> + <name name="supports" arity="1" since="OTP 22.0"/> + <name name="supports" arity="2" since="OTP 22.0"/> <fsummary>Report info about what the platform supports.</fsummary> - <type> - <v> - SocketOption :: - <seetype marker="#socket_option">socket_option()</seetype> - </v> - <v> - IPSocketOption :: - <seetype marker="#ip_socket_option">ip_socket_option()</seetype> - </v> - <v> - IPv6SocketOption :: - <seetype marker="#ipv6_socket_option">ipv6_socket_option()</seetype> - </v> - <v> - TCPSocketOption :: - <seetype marker="#tcp_socket_option">tcp_socket_option()</seetype> - </v> - <v> - UDPSocketOption :: - <seetype marker="#udp_socket_option">udp_socket_option()</seetype> - </v> - <v> - SCTPSocketOption :: - <seetype marker="#sctp_socket_option">sctp_socket_option()</seetype> - </v> - </type> <desc> <p> - This function retreives information about what the - platform supports, such as if SCTP is supported, - or which socket options are supported. + These functions function retreives information about what the + platform supports, such which platform features + or which socket options, are supported. </p> <p> - For keys other than the known <c>false</c> is returned. + For keys other than the known the empty list is returned, Note that in a future version or on a different platform there might be more supported items. </p> + <taglist> + <tag><c>supports()</c></tag> + <item> + <p> + Returns a list of + <c>{<anno>Key1</anno>, supports(Key1)}</c> tuples + for every <c><anno>Key1</anno></c> described in + <seemfa marker="#supports/1">supports/1</seemfa> and + <c>{<anno>Key1</anno>, boolean()}</c> tuples + for each of the following keys: + </p> + <taglist> + <tag><c>sctp</c></tag> + <item>SCTP support</item> + <tag><c>ipv6</c></tag> + <item>IPv6 support</item> + <tag><c>local</c></tag> + <item> + Unix Domain sockets support (<c>AF_UNIX | AF_LOCAL</c>) + </item> + <tag><c>netns</c></tag> + <item> + Network Namespaces support (Linux, <c>setns(2)</c>) + </item> + </taglist> + <p></p> + </item> + <tag><c>supports(msg_flags = <anno>Key1</anno>)</c></tag> + <item> + <p> + Returns a list of + <c>{Flag, boolean()}</c> tuples + for every <c>Flag</c> in + <seetype marker="#msg_flag"> + <c>msg_flag()</c> + </seetype> + with the <c>boolean()</c> indicating if the flag + is supported on this platform. + </p> + </item> + <tag><c>supports(protocols = <anno>Key1</anno>)</c></tag> + <item> + <p> + Returns a list of + <c>{Name :: atom(), boolean()}</c> tuples + for every <c>Name</c> in + <seetype marker="#protocol"> + <c>protocol()</c> + </seetype> + with the <c>boolean()</c> indicating if the protocol + is supported on this platform. + </p> + </item> + <tag><c>supports(options = <anno>Key1</anno>)</c></tag> + <item> + <p> + Returns a list of + <c>{SocketOption, boolean()}</c> tuples + for every <c>SocketOption</c> in + <seetype marker="#socket_option"> + <c>socket_option()</c> + </seetype> + with the <c>boolean()</c> indicating if + the socket option is supported on this platform. + </p> + </item> + <tag> + <c> + supports(options = <anno>Key1</anno>, <anno>Key2</anno>) + </c> + </tag> + <item> + <p> + For a <c><anno>Key2</anno></c> in + <seetype marker="#level"> + <c>level()</c> + </seetype> + returns a list of <c>{Opt, boolean()}</c> tuples + for all known + <seetype marker="#socket_option"> + socket options <c>Opt</c> + on that <c>Level =:= <anno>Key2</anno></c>, + </seetype> + and the <c>boolean()</c> indicating if the socket option + is supported on this platform. + See <seemfa marker="#setopt/3">setopt/3</seemfa> + and <seemfa marker="#getopt/2">getopt/2</seemfa>. + </p> + </item> + </taglist> </desc> </func> @@ -1220,14 +2728,12 @@ <title>Examples</title> <marker id="examples"></marker> <code type="none"> -client(Addr, SAddr, SPort) -> +client(SAddr, SPort) -> {ok, Sock} = socket:open(inet, stream, tcp), - {ok, _} = socket:bind(Sock, #{family => inet, - addr => Addr}), ok = socket:connect(Sock, #{family => inet, addr => SAddr, - port => SPort}), - Msg = list_to_binary("hello"), + port => SPort}), + Msg = <<"hello">>, ok = socket:send(Sock, Msg), ok = socket:shutdown(Sock, write), {ok, Msg} = socket:recv(Sock), @@ -1235,14 +2741,13 @@ client(Addr, SAddr, SPort) -> server(Addr, Port) -> {ok, LSock} = socket:open(inet, stream, tcp), - {ok, _} = socket:bind(LSock, #{family => inet, - port => Port, - addr => Addr}), + ok = socket:bind(LSock, #{family => inet, + port => Port, + addr => Addr}), ok = socket:listen(LSock), {ok, Sock} = socket:accept(LSock), {ok, Msg} = socket:recv(Sock), ok = socket:send(Sock, Msg), - ok = socket:shutdown(Sock, write), ok = socket:close(Sock), ok = socket:close(LSock). </code> diff --git a/lib/kernel/doc/src/socket_usage.xml b/lib/kernel/doc/src/socket_usage.xml index d132c7541f..c6ec4c5f97 100644 --- a/lib/kernel/doc/src/socket_usage.xml +++ b/lib/kernel/doc/src/socket_usage.xml @@ -59,13 +59,13 @@ <c>{select, </c> <seetype marker="socket#select_info"><c>SelectInfo</c></seetype><c>}</c> (<c>SelectInfo</c> contains the - <seetype marker="socket#select_ref">SelectRef</seetype>). + <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype>). When data eventually arrives a 'select message' will be sent to the caller:</p> <taglist> <!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL --> <tag></tag> - <item><c>{'$socket', socket(), select, SelectRef}</c></item> + <item><c>{'$socket', socket(), select, SelectHandle}</c></item> </taglist> <p>The caller can then make another call to the recv function and now expect data.</p> @@ -82,7 +82,7 @@ <p>If the operation is aborted for whatever reason (e.g. if the socket is closed "by someone else"). The <c>Info</c> part contains the abort reason (in this case that - the socket has been closed <c>Info = {SelectRef, closed}</c>). </p> + the socket has been closed <c>Info = {SelectHandle, closed}</c>). </p> <p>The general form of the 'socket' message is: </p> <taglist> @@ -98,15 +98,15 @@ </row> <row> <cell>select</cell> - <cell>select_ref()</cell> + <cell>select_handle()</cell> </row> <row> <cell>abort</cell> - <cell>{select_ref(), Reason :: term()}</cell> + <cell>{select_handle(), Reason :: term()}</cell> </row> <tcaption>socket message info value type</tcaption> </table> - <p>The <c>select_ref()</c> is the same as was received in the + <p>The <c>select_handle()</c> is the same as was returned in the <seetype marker="socket#select_info"><c>SelectInfo</c></seetype>. </p> </section> </section> |