+luasocket src

author: chai <chaifix@163.com> 2021-10-20 13:40:34 +0800
committer: chai <chaifix@163.com> 2021-10-20 13:40:34 +0800
commit: ff0f488c97fe8b554b909a0057cebc4c860eac8f (patch)
tree: 4e47262b52ffce7e9cfeaaeeab46371243bcaa78 /ThirdParty/luasocket/doc/udp.html
parent: dde719dd575090b36aaa3ad85bb3cabf33f36c5a (diff)
1 files changed, 596 insertions, 0 deletions
diff --git a/ThirdParty/luasocket/doc/udp.html b/ThirdParty/luasocket/doc/udp.html
new file mode 100644
index 0000000..4618aad
--- /dev/null
+++ b/ThirdParty/luasocket/doc/udp.html
@@ -0,0 +1,596 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+    "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+
+<head>
+<meta name="description" content="LuaSocket: The UDP support">
+<meta name="keywords" content="Lua, LuaSocket, Socket, UDP, Library, Network, Support">
+<title>LuaSocket: UDP support</title>
+<link rel="stylesheet" href="reference.css" type="text/css">
+</head>
+
+<body>
+
+<!-- header ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<div class=header>
+<hr>
+<center>
+<table summary="LuaSocket logo">
+<tr><td align=center><a href="http://www.lua.org">
+<img width=128 height=128 border=0 alt="LuaSocket" src="luasocket.png">
+</a></td></tr>
+<tr><td align=center valign=top>Network support for the Lua language
+</td></tr>
+</table>
+<p class=bar>
+<a href="index.html">home</a> &middot;
+<a href="index.html#download">download</a> &middot;
+<a href="installation.html">installation</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<a href="reference.html">reference</a>
+</p>
+</center>
+<hr>
+</div>
+
+
+<!-- udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<h2 id="udp">UDP</h2>
+
+<!-- close +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="close">
+connected:<b>close()</b><br>
+unconnected:<b>close()</b>
+</p>
+
+<p class="description">
+Closes a UDP object. The internal socket
+used by the object is closed and the local address to which the
+object was bound is made available to other applications. No
+further operations (except for further calls to the <tt>close</tt>
+method) are allowed on a closed socket.
+</p>
+
+<p class="note">
+Note: It is important to close all used sockets
+once they are not needed, since, in many systems, each socket uses
+a file descriptor, which are limited system resources.
+Garbage-collected objects are automatically closed before
+destruction, though.
+</p>
+
+<!-- getoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="getoption">
+connected:<b>getoption()</b><br>
+unconnected:<b>getoption()</b>
+</p>
+
+<p class="description">
+Gets an option value from the UDP object.
+See <a href=#setoption><tt>setoption</tt></a> for
+description of the option names and values.
+</p>
+
+<p class="parameters"><tt>Option</tt> is a string with the option name.
+<ul>
+<li> '<tt>dontroute</tt>'
+<li> '<tt>broadcast</tt>'
+<li> '<tt>reuseaddr</tt>'
+<li> '<tt>reuseport</tt>'
+<li> '<tt>ip-multicast-loop</tt>'
+<li> '<tt>ipv6-v6only</tt>'
+<li> '<tt>ip-multicast-if</tt>'
+<li> '<tt>ip-multicast-ttl</tt>'
+<li> '<tt>ip-add-membership</tt>'
+<li> '<tt>ip-drop-membership</tt>'
+</ul>
+</p>
+
+<p class=return>
+The method returns the option <tt>value</tt> in case of
+success, or
+<b><tt>nil</tt></b> followed by an error message otherwise.
+</p>
+
+<!-- getpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="getpeername">
+connected:<b>getpeername()</b>
+</p>
+
+<p class="description">
+Retrieves information about the peer
+associated with a connected UDP object.
+</p>
+
+
+<p class=return>
+Returns a string with the IP address of the peer, the
+port number that peer is using for the connection,
+and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
+In case of error, the method returns <b><tt>nil</tt></b>.
+</p>
+
+<p class="note">
+Note: It makes no sense to call this method on unconnected objects.
+</p>
+
+<!-- getsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="getsockname">
+connected:<b>getsockname()</b><br>
+unconnected:<b>getsockname()</b>
+</p>
+
+<p class="description">
+Returns the local address information associated to the object.
+</p>
+
+
+<p class=return>
+The method returns a string with local IP address, a number with
+the local port,
+and a string with the family ("<tt>inet</tt>" or "<tt>inet6</tt>").
+In case of error, the method returns <b><tt>nil</tt></b>.
+</p>
+
+<p class="note">
+Note: UDP sockets are not bound to any address
+until the <a href="#setsockname"><tt>setsockname</tt></a> or the
+<a href="#sendto"><tt>sendto</tt></a> method is called for the
+first time (in which case it is bound to an ephemeral port and the
+wild-card address).
+</p>
+
+<!-- gettimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class=name id="gettimeout">
+connected:<b>settimeout(</b>value<b>)</b><br>
+unconnected:<b>settimeout(</b>value<b>)</b>
+</p>
+
+<p class=description>
+Returns the current timeout value.
+</p>
+
+
+<!-- receive +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="receive">
+connected:<b>receive(</b>[size]<b>)</b><br>
+unconnected:<b>receive(</b>[size]<b>)</b>
+</p>
+
+<p class="description">
+Receives a datagram from the UDP object. If
+the UDP object is connected, only datagrams coming from the peer
+are accepted. Otherwise, the returned datagram can come from any
+host.
+</p>
+
+<p class="parameters">
+The optional <tt>size</tt> parameter
+specifies the maximum size of the datagram to be retrieved. If
+there are more than <tt>size</tt> bytes available in the datagram,
+the excess bytes are discarded. If there are less then
+<tt>size</tt> bytes available in the current datagram, the
+available bytes are returned.
+If <tt>size</tt> is omitted, the
+compile-time constant <a
+href=socket.html#datagramsize><tt>socket._DATAGRAMSIZE</tt></a> is used
+(it defaults to 8192 bytes). Larger sizes will cause a
+temporary buffer to be allocated for the operation.
+</p>
+
+<p class="return">
+In case of success, the method returns the
+received datagram. In case of timeout, the method returns
+<b><tt>nil</tt></b> followed by the string '<tt>timeout</tt>'.
+</p>
+
+<!-- receivefrom +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="receivefrom">
+unconnected:<b>receivefrom(</b>[size]<b>)</b>
+</p>
+
+<p class="description">
+Works exactly as the <a href="#receive"><tt>receive</tt></a>
+method, except it returns the IP
+address and port as extra return values (and is therefore slightly less
+efficient).
+</p>
+
+<!-- send ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="send">
+connected:<b>send(</b>datagram<b>)</b>
+</p>
+
+<p class="description">
+Sends a datagram to the UDP peer of a connected object.
+</p>
+
+<p class="parameters">
+<tt>Datagram</tt> is a string with the datagram contents.
+The maximum datagram size for UDP is 64K minus IP layer overhead.
+However datagrams larger than the link layer packet size will be
+fragmented, which may deteriorate performance and/or reliability.
+</p>
+
+<p class="return">
+If successful, the method returns 1. In case of
+error, the method returns <b><tt>nil</tt></b> followed by an error message.
+</p>
+
+<p class="note">
+Note: In UDP, the <tt>send</tt> method never blocks
+and the only way it can fail is if the underlying transport layer
+refuses to send a message to the specified address (i.e. no
+interface accepts the address).
+</p>
+
+<!-- sendto ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="sendto">
+unconnected:<b>sendto(</b>datagram, ip, port<b>)</b>
+</p>
+
+<p class="description">
+Sends a datagram to the specified IP address and port number.
+</p>
+
+<p class="parameters">
+<tt>Datagram</tt> is a string with the
+datagram contents.
+The maximum datagram size for UDP is 64K minus IP layer overhead.
+However datagrams larger than the link layer packet size will be
+fragmented, which may deteriorate performance and/or reliability.
+<tt>Ip</tt> is the IP address of the recipient.
+Host names are <em>not</em> allowed for performance reasons.
+
+<tt>Port</tt> is the port number at the recipient.
+</p>
+
+<p class="return">
+If successful, the method returns 1. In case of
+error, the method returns <b><tt>nil</tt></b> followed by an error message.
+</p>
+
+<p class="note">
+Note: In UDP, the <tt>send</tt> method never blocks
+and the only way it can fail is if the underlying transport layer
+refuses to send a message to the specified address (i.e. no
+interface accepts the address).
+</p>
+
+<!-- setoption +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="setoption">
+connected:<b>setoption(</b>option [, value]<b>)</b><br>
+unconnected:<b>setoption(</b>option [, value]<b>)</b>
+</p>
+
+<p class="description">
+Sets options for the UDP object. Options are
+only needed by low-level or time-critical applications. You should
+only modify an option if you are sure you need it.</p>
+<p class="parameters"><tt>Option</tt> is a string with the option
+name, and <tt>value</tt> depends on the option being set:
+</p>
+
+<ul>
+<li> '<tt>dontroute</tt>': Indicates that outgoing
+messages should bypass the standard routing facilities.
+Receives a boolean value;
+<li> '<tt>broadcast</tt>': Requests permission to send
+broadcast datagrams on the socket.
+Receives a boolean value;
+<li> '<tt>reuseaddr</tt>': Indicates that the rules used in
+validating addresses supplied in a <tt>bind()</tt> call
+should allow reuse of local addresses.
+Receives a boolean value;
+<li> '<tt>reuseport</tt>': Allows completely duplicate
+bindings by multiple processes if they all set
+'<tt>reuseport</tt>' before binding the port.
+Receives a boolean value;
+<li> '<tt>ip-multicast-loop</tt>':
+Specifies whether or not a copy of an outgoing multicast
+datagram is delivered to the sending host as long as it is a
+member of the multicast group.
+Receives a boolean value;
+<li> '<tt>ipv6-v6only</tt>':
+Specifies whether to restrict <tt>inet6</tt> sockets to
+sending and receiving only IPv6 packets.
+Receive a boolean value;
+<li> '<tt>ip-multicast-if</tt>':
+Sets the interface over which outgoing multicast datagrams
+are sent.
+Receives an IP address;
+<li> '<tt>ip-multicast-ttl</tt>':
+Sets the Time To Live in the IP header for outgoing
+multicast datagrams.
+Receives a number;
+<li> '<tt>ip-add-membership</tt>':
+Joins the multicast group specified.
+Receives a table with fields
+<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
+IP address;
+<li> '<tt>ip-drop-membership</tt>': Leaves the multicast
+group specified.
+Receives a table with fields
+<tt>multiaddr</tt> and <tt>interface</tt>, each containing an
+IP address.
+</ul>
+
+<p class="return">
+The method returns 1 in case of success, or
+<b><tt>nil</tt></b> followed by an error message otherwise.
+</p>
+
+<p class=note>
+Note: The descriptions above come from the man pages.
+</p>
+
+
+<!-- setpeername +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="setpeername">
+connected:<b>setpeername(</b>'*'<b>)</b><br>
+unconnected:<b>setpeername(</b>address, port<b>)</b>
+</p>
+
+<p class="description">
+Changes the peer of a UDP object. This
+method turns an unconnected UDP object into a connected UDP
+object or vice versa.
+</p>
+
+<p class="description">
+For connected objects, outgoing datagrams
+will be sent to the specified peer, and datagrams received from
+other peers will be discarded by the OS. Connected UDP objects must
+use the <a href="#send"><tt>send</tt></a> and
+<a href="#receive"><tt>receive</tt></a> methods instead of
+<a href="#sendto"><tt>sendto</tt></a> and
+<a href="#receivefrom"><tt>receivefrom</tt></a>.
+</p>
+
+<p class="parameters">
+<tt>Address</tt> can be an IP address or a
+host name. <tt>Port</tt> is the port number. If <tt>address</tt> is
+'<tt>*</tt>' and the object is connected, the peer association is
+removed and the object becomes an unconnected object again. In that
+case, the <tt>port</tt> argument is ignored.
+</p>
+
+<p class="return">
+In case of error the method returns
+<b><tt>nil</tt></b> followed by an error message. In case of success, the
+method returns 1.
+</p>
+
+<p class="note">
+Note: Since the address of the peer does not have
+to be passed to and from the OS, the use of connected UDP objects
+is recommended when the same peer is used for several transmissions
+and can result in up to 30% performance gains.
+</p>
+
+<p class=note>
+Note: Starting with LuaSocket 3.0, the host name resolution
+depends on whether the socket was created by <a
+href=#socket.udp><tt>socket.udp</tt></a> or <a
+href=#socket.udp6><tt>socket.udp6</tt></a>. Addresses from
+the appropriate family are tried in succession until the
+first success or until the last failure.
+</p>
+
+<!-- setsockname +++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="setsockname">
+unconnected:<b>setsockname(</b>address, port<b>)</b>
+</p>
+
+<p class="description">
+Binds the UDP object to a local address.
+</p>
+
+<p class="parameters">
+<tt>Address</tt> can be an IP address or a
+host name. If <tt>address</tt> is '<tt>*</tt>' the system binds to
+all local interfaces using the constant <tt>INADDR_ANY</tt>. If
+<tt>port</tt> is 0, the system chooses an ephemeral port.
+</p>
+
+<p class="return">
+If successful, the method returns 1. In case of
+error, the method returns <b><tt>nil</tt></b> followed by an error
+message.
+</p>
+
+<p class="note">
+Note: This method can only be called before any
+datagram is sent through the UDP object, and only once. Otherwise,
+the system automatically binds the object to all local interfaces
+and chooses an ephemeral port as soon as the first datagram is
+sent. After the local address is set, either automatically by the
+system or explicitly by <tt>setsockname</tt>, it cannot be
+changed.
+</p>
+
+<!-- settimeout +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="settimeout">
+connected:<b>settimeout(</b>value<b>)</b><br>
+unconnected:<b>settimeout(</b>value<b>)</b>
+</p>
+
+<p class="description">
+Changes the timeout values for the object.  By default, the
+<a href="#receive"><tt>receive</tt></a> and
+<a href="#receivefrom"><tt>receivefrom</tt></a>
+operations are blocking. That is, any call to the methods will block
+indefinitely, until data arrives.  The <tt>settimeout</tt> function defines
+a limit on the amount of time the functions can block. When a timeout is
+set and the specified amount of time has elapsed, the affected methods
+give up and fail with an error code.
+</p>
+
+<p class="parameters">
+The amount of time to wait is specified as
+the <tt>value</tt> parameter, in seconds. The <b><tt>nil</tt></b> timeout
+<tt>value</tt> allows operations to block indefinitely. Negative
+timeout values have the same effect.
+</p>
+
+<p class="note">
+Note: In UDP, the <a href="#send"><tt>send</tt></a>
+and <a href="#sentdo"><tt>sendto</tt></a> methods never block (the
+datagram is just passed to the OS and the call returns
+immediately). Therefore, the <tt>settimeout</tt> method has no
+effect on them.
+</p>
+
+<p class="note">
+Note: The old <tt>timeout</tt> method is
+deprecated. The name has been changed for sake of uniformity, since
+all other method names already contained verbs making their
+imperative nature obvious.
+</p>
+
+<!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="socket.udp">
+socket.<b>udp()</b>
+</p>
+
+<p class="description">
+Creates and returns an unconnected UDP object.
+Unconnected objects support the
+<a href="#sendto"><tt>sendto</tt></a>,
+<a href="#receive"><tt>receive</tt></a>,
+<a href="#receivefrom"><tt>receivefrom</tt></a>,
+<a href="#getoption"><tt>getoption</tt></a>,
+<a href="#getsockname"><tt>getsockname</tt></a>,
+<a href="#setoption"><tt>setoption</tt></a>,
+<a href="#settimeout"><tt>settimeout</tt></a>,
+<a href="#setpeername"><tt>setpeername</tt></a>,
+<a href="#setsockname"><tt>setsockname</tt></a>, and
+<a href="#close"><tt>close</tt></a>.
+The <a href="#setpeername"><tt>setpeername</tt></a>
+is used to connect the object.
+</p>
+
+<p class="return">
+In case of success, a new unconnected UDP object
+returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
+an error message.
+</p>
+
+<p class=note>
+Note: The choice between IPv4 and IPv6 happens during a call to
+<a href=#sendto><tt>sendto</tt></a>, <a
+href=#setpeername><tt>setpeername</tt></a>, or <a
+href=#setsockname><tt>sockname</tt></a>, depending on the address
+family obtained from the resolver.
+</p>
+
+<p class=note>
+Note: Before the choice between IPv4 and IPv6 happens,
+the internal socket object is invalid and therefore <a
+href=#setoption><tt>setoption</tt></a> will fail.
+</p>
+
+<!-- socket.udp4 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="socket.udp">
+socket.<b>udp4()</b>
+</p>
+
+<p class="description">
+Creates and returns an unconnected IPv4 UDP object.
+Unconnected objects support the
+<a href="#sendto"><tt>sendto</tt></a>,
+<a href="#receive"><tt>receive</tt></a>,
+<a href="#receivefrom"><tt>receivefrom</tt></a>,
+<a href="#getoption"><tt>getoption</tt></a>,
+<a href="#getsockname"><tt>getsockname</tt></a>,
+<a href="#setoption"><tt>setoption</tt></a>,
+<a href="#settimeout"><tt>settimeout</tt></a>,
+<a href="#setpeername"><tt>setpeername</tt></a>,
+<a href="#setsockname"><tt>setsockname</tt></a>, and
+<a href="#close"><tt>close</tt></a>.
+The <a href="#setpeername"><tt>setpeername</tt></a>
+is used to connect the object.
+</p>
+
+<p class="return">
+In case of success, a new unconnected UDP object
+returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
+an error message.
+</p>
+
+<!-- socket.udp ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<p class="name" id="socket.udp6">
+socket.<b>udp6()</b>
+</p>
+
+<p class="description">
+Creates and returns an unconnected IPv6 UDP object.
+Unconnected objects support the
+<a href="#sendto"><tt>sendto</tt></a>,
+<a href="#receive"><tt>receive</tt></a>,
+<a href="#receivefrom"><tt>receivefrom</tt></a>,
+<a href="#getoption"><tt>getoption</tt></a>,
+<a href="#getsockname"><tt>getsockname</tt></a>,
+<a href="#setoption"><tt>setoption</tt></a>,
+<a href="#settimeout"><tt>settimeout</tt></a>,
+<a href="#setpeername"><tt>setpeername</tt></a>,
+<a href="#setsockname"><tt>setsockname</tt></a>, and
+<a href="#close"><tt>close</tt></a>.
+The <a href="#setpeername"><tt>setpeername</tt></a>
+is used to connect the object.
+</p>
+
+<p class="return">
+In case of success, a new unconnected UDP object
+returned. In case of error, <b><tt>nil</tt></b> is returned, followed by
+an error message.
+</p>
+
+<p class=note>
+Note: The TCP object returned will have the option
+"<tt>ipv6-v6only</tt>" set to <tt><b>true</b></tt>.
+</p>
+
+
+
+<!-- footer ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ -->
+
+<div class=footer>
+<hr>
+<center>
+<p class=bar>
+<a href="index.html">home</a> &middot;
+<a href="index.html#download">download</a> &middot;
+<a href="installation.html">installation</a> &middot;
+<a href="introduction.html">introduction</a> &middot;
+<a href="reference.html">reference</a>
+</p>
+<p>
+<small>
+Last modified by Diego Nehab on <br>
+Thu Apr 20 00:26:01 EDT 2006
+</small>
+</p>
+</center>
+</div>
+
+</body>
+</html>
author	chai <chaifix@163.com>	2021-10-20 13:40:34 +0800
committer	chai <chaifix@163.com>	2021-10-20 13:40:34 +0800
commit	ff0f488c97fe8b554b909a0057cebc4c860eac8f (patch)
tree	4e47262b52ffce7e9cfeaaeeab46371243bcaa78 /ThirdParty/luasocket/doc/udp.html
parent	dde719dd575090b36aaa3ad85bb3cabf33f36c5a (diff)