From f98977b2dac48fc66822402b095336e683715126 Mon Sep 17 00:00:00 2001 From: Caleb Maclennan Date: Wed, 23 Mar 2022 00:09:53 +0300 Subject: Move doc→docs so we can serve it with GitHub Pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/tcp.html | 732 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 732 insertions(+) create mode 100644 docs/tcp.html (limited to 'docs/tcp.html') diff --git a/docs/tcp.html b/docs/tcp.html new file mode 100644 index 0000000..9cc173e --- /dev/null +++ b/docs/tcp.html @@ -0,0 +1,732 @@ + + + + + + +LuaSocket: TCP/IP support + + + + + + + +
+
+
+ + + +
+LuaSocket +
Network support for the Lua language +
+

+home · +download · +installation · +introduction · +reference +

+
+
+
+ + + +

TCP

+ + + +

+server:accept() +

+ +

+Waits for a remote connection on the server +object and returns a client object representing that connection. +

+ +

+If a connection is successfully initiated, a client object is returned. +If a timeout condition is met, the method returns nil +followed by the error string 'timeout'. Other errors are +reported by nil followed by a message describing the error. +

+ +

+Note: calling socket.select +with a server object in +the recvt parameter before a call to accept does +not guarantee accept will return immediately. Use the settimeout method or accept +might block until another client shows up. +

+ + + +

+master:bind(address, port) +

+ +

+Binds a master object to address and port on the +local host. +

+ +

+Address can be an IP address or a host name. +Port must be an integer number in the range [0..64K). +If address +is '*', the system binds to all local interfaces +using the INADDR_ANY constant or +IN6ADDR_ANY_INIT, according to the family. +If port is 0, the system automatically +chooses an ephemeral port. +

+ +

+In case of success, the method returns 1. In case of error, the +method returns nil followed by an error message. +

+ +

+Note: The function socket.bind +is available and is a shortcut for the creation of server sockets. +

+ + + +

+master:close()
+client:close()
+server:close() +

+ +

+Closes a TCP 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 close method) are allowed on +a closed socket. +

+ +

+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. +

+ + + +

+master:connect(address, port) +

+ +

+Attempts to connect a master object to a remote host, transforming it into a +client object. +Client objects support methods +send, +receive, +getsockname, +getpeername, +settimeout, +and close. +

+ +

+Address can be an IP address or a host name. +Port must be an integer number in the range [1..64K). +

+ +

+In case of error, the method returns nil followed by a string +describing the error. In case of success, the method returns 1. +

+ +

+Note: The function socket.connect +is available and is a shortcut for the creation of client sockets. +

+ +

+Note: Starting with LuaSocket 2.0, +the settimeout +method affects the behavior of connect, causing it to return +with an error in case of a timeout. If that happens, you can still call socket.select with the socket in the +sendt table. The socket will be writable when the connection is +established. +

+ +

+Note: Starting with LuaSocket 3.0, the host name resolution +depends on whether the socket was created by +socket.tcp, +socket.tcp4 or +socket.tcp6. Addresses from +the appropriate family (or both) are tried in the order +returned by the resolver until the +first success or until the last failure. If the timeout was +set to zero, only the first address is tried. +

+ + + +

+master:dirty()
+client:dirty()
+server:dirty() +

+ +

+Check the read buffer status. +

+ +

+Returns true if there is any data in the read buffer, false otherwise. +

+ +

+Note: This is an internal method, use at your own risk. +

+ + + + +

+master:getfd()
+client:getfd()
+server:getfd() +

+ +

+Returns the underling socket descriptor or handle associated to the object. +

+ +

+The descriptor or handle. In case the object has been closed, the return value +will be -1. For an invalid socket it will be +_SOCKETINVALID. +

+ +

+Note: This is an internal method. Unlikely to be +portable. Use at your own risk. +

+ + + + +

+client:getoption(option)
+server:getoption(option) +

+ +

+Gets options for the TCP object. +See setoption for description of the +option names and values. +

+ +

+Option is a string with the option name.

+ + +

+The method returns the option value in case of success, or +nil followed by an error message otherwise. +

+ + + + +

+client:getpeername() +

+ +

+Returns information about the remote side of a connected client object. +

+ +

+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 ("inet" or "inet6"). +In case of error, the method returns nil. +

+ +

+Note: It makes no sense to call this method on server objects. +

+ + + +

+master:getsockname()
+client:getsockname()
+server:getsockname() +

+ +

+Returns the local address information associated to the object. +

+ +

+The method returns a string with local IP address, a number with +the local port, +and a string with the family ("inet" or "inet6"). +In case of error, the method returns nil. +

+ + + +

+master:getstats()
+client:getstats()
+server:getstats()
+

+ +

+Returns accounting information on the socket, useful for throttling +of bandwidth. +

+ +

+The method returns the number of bytes received, the number of bytes sent, +and the age of the socket object in seconds. +

+ + + +

+master:gettimeout()
+client:gettimeout()
+server:gettimeout() +

+ +

+Returns the current block timeout followed by the curent +total timeout. +

+ + + + +

+master:listen(backlog) +

+ +

+Specifies the socket is willing to receive connections, transforming the +object into a server object. Server objects support the +accept, +getsockname, +setoption, +settimeout, +and close methods. +

+ +

+The parameter backlog specifies the number of client +connections that can +be queued waiting for service. If the queue is full and another client +attempts connection, the connection is refused. +

+ +

+In case of success, the method returns 1. In case of error, the +method returns nil followed by an error message. +

+ + + +

+client:receive([pattern [, prefix]]) +

+ +

+Reads data from a client object, according to the specified read +pattern. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible. +

+ +

+Pattern can be any of the following: +

+ + + +

+Prefix is an optional string to be concatenated to the beginning +of any received data before return. +

+ +

+If successful, the method returns the received pattern. In case of error, +the method returns nil followed by an error +message, followed by a (possibly empty) string containing +the partial that was received. The error message can be +the string 'closed' in case the connection was +closed before the transmission was completed or the string +'timeout' in case there was a timeout during the operation. +

+ +

+Important note: This function was changed severely. It used +to support multiple patterns (but I have never seen this feature used) and +now it doesn't anymore. Partial results used to be returned in the same +way as successful results. This last feature violated the idea that all +functions should return nil on error. Thus it was changed +too. +

+ + + +

+client:send(data [, i [, j]]) +

+ +

+Sends data through client object. +

+ +

+Data is the string to be sent. The optional arguments +i and j work exactly like the standard +string.sub Lua function to allow the selection of a +substring to be sent. +

+ +

+If successful, the method returns the index of the last byte +within [i, j] that has been sent. Notice that, if +i is 1 or absent, this is effectively the total +number of bytes sent. In case of error, the method returns +nil, followed by an error message, followed +by the index of the last byte within [i, j] that +has been sent. You might want to try again from the byte +following that. The error message can be 'closed' +in case the connection was closed before the transmission +was completed or the string 'timeout' in case +there was a timeout during the operation. +

+ +

+Note: Output is not buffered. For small strings, +it is always better to concatenate them in Lua +(with the '..' operator) and send the result in one call +instead of calling the method several times. +

+ + + +

+client:setoption(option [, value])
+server:setoption(option [, value]) +

+ +

+Sets options for the TCP 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. +

+ +

+Option is a string with the option name, and value +depends on the option being set:

+ + + +

+The method returns 1 in case of success, or nil +followed by an error message otherwise. +

+ +

+Note: The descriptions above come from the man pages. +

+ + + +

+master:setstats(received, sent, age)
+client:setstats(received, sent, age)
+server:setstats(received, sent, age)
+

+ +

+Resets accounting information on the socket, useful for throttling +of bandwidth. +

+ +

+Received is a number with the new number of bytes received. +Sent is a number with the new number of bytes sent. +Age is the new age in seconds. +

+ +

+The method returns 1 in case of success and nil otherwise. +

+ + + +

+master:settimeout(value [, mode])
+client:settimeout(value [, mode])
+server:settimeout(value [, mode]) +

+ +

+Changes the timeout values for the object. By default, +all I/O operations are blocking. That is, any call to the methods +send, +receive, and +accept +will block indefinitely, until the operation completes. The +settimeout method defines a limit on the amount of time the +I/O methods 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. +

+ +

+The amount of time to wait is specified as the +value parameter, in seconds. There are two timeout modes and +both can be used together for fine tuning: +

+ + + +

+The nil timeout value allows operations to block +indefinitely. Negative timeout values have the same effect. +

+ +

+Note: although timeout values have millisecond precision in LuaSocket, +large blocks can cause I/O functions not to respect timeout values due +to the time the library takes to transfer blocks to and from the OS +and to and from the Lua interpreter. Also, function that accept host names +and perform automatic name resolution might be blocked by the resolver for +longer than the specified timeout value. +

+ +

+Note: The old timeout 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. +

+ + + +

+client:shutdown(mode)
+

+ +

+Shuts down part of a full-duplex connection. +

+ +

+Mode tells which way of the connection should be shut down and can +take the value: +

+

+ +

+This function returns 1. +

+ + + +

+master:setfd(fd)
+client:setfd(fd)
+server:setfd(fd) +

+ +

+Sets the underling socket descriptor or handle associated to the object. The current one +is simply replaced, not closed, and no other change to the object state is made. +To set it as invalid use _SOCKETINVALID. +

+ +

+No return value. +

+ +

+Note: This is an internal method. Unlikely to be +portable. Use at your own risk. +

+ + + +

+socket.tcp() +

+ +

+Creates and returns an TCP master object. A master object can +be transformed into a server object with the method +listen (after a call to bind) or into a client object with +the method connect. The only other +method supported by a master object is the +close method.

+ +

+In case of success, a new master object is returned. In case of error, +nil is returned, followed by an error message. +

+ +

+Note: The choice between IPv4 and IPv6 happens during a call to +bind or connect, depending on the address +family obtained from the resolver. +

+ +

+Note: Before the choice between IPv4 and IPv6 happens, +the internal socket object is invalid and therefore setoption will fail. +

+ + + +

+socket.tcp4() +

+ +

+Creates and returns an IPv4 TCP master object. A master object can +be transformed into a server object with the method +listen (after a call to bind) or into a client object with +the method connect. The only other +method supported by a master object is the +close method.

+ +

+In case of success, a new master object is returned. In case of error, +nil is returned, followed by an error message. +

+ + + +

+socket.tcp6() +

+ +

+Creates and returns an IPv6 TCP master object. A master object can +be transformed into a server object with the method +listen (after a call to bind) or into a client object with +the method connect. The only other +method supported by a master object is the +close method.

+ +

+In case of success, a new master object is returned. In case of error, +nil is returned, followed by an error message. +

+ +

+Note: The TCP object returned will have the option +"ipv6-v6only" set to true. +

+ + + + + +
+
+
+

+home · +download · +installation · +introduction · +reference +

+

+ +Last modified by Diego Nehab on
+Thu Apr 20 00:25:57 EDT 2006 + +

+
+
+ + + -- cgit v1.2.3-55-g6feb From 0c7df119c2b71bed814db7b3da8fc379131433fe Mon Sep 17 00:00:00 2001 From: Kim Alvefur Date: Wed, 27 Jul 2022 08:16:43 +0200 Subject: feat(tcp): Add support for TCP Fast Open --- docs/tcp.html | 4 ++++ src/options.c | 16 ++++++++++++++++ src/options.h | 7 +++++++ src/tcp.c | 6 ++++++ 4 files changed, 33 insertions(+) (limited to 'docs/tcp.html') diff --git a/docs/tcp.html b/docs/tcp.html index 9cc173e..f15196c 100644 --- a/docs/tcp.html +++ b/docs/tcp.html @@ -485,6 +485,10 @@ disables the Nagle's algorithm for the connection;
  • 'tcp-keepintvl': value for TCP_KEEPINTVL Linux only!!
    • +
  • 'tcp-fastopen': value for TCP_FASTOPEN Linux only!!
    • + +
  • 'tcp-fastopen-connect': value for TCP_FASTOPEN_CONNECT Linux only!!
    • +
  • 'ipv6-v6only': Setting this option to true restricts an inet6 socket to sending and receiving only IPv6 packets.
    • diff --git a/src/options.c b/src/options.c index 2b53c67..51ea351 100644 --- a/src/options.c +++ b/src/options.c @@ -190,6 +190,22 @@ int opt_set_send_buf_size(lua_State *L, p_socket ps) return opt_setint(L, ps, SOL_SOCKET, SO_SNDBUF); } +// /*------------------------------------------------------*/ + +#ifdef TCP_FASTOPEN +int opt_set_tcp_fastopen(lua_State *L, p_socket ps) +{ + return opt_setint(L, ps, IPPROTO_TCP, TCP_FASTOPEN); +} +#endif + +#ifdef TCP_FASTOPEN_CONNECT +int opt_set_tcp_fastopen_connect(lua_State *L, p_socket ps) +{ + return opt_setint(L, ps, IPPROTO_TCP, TCP_FASTOPEN_CONNECT); +} +#endif + /*------------------------------------------------------*/ int opt_set_ip6_unicast_hops(lua_State *L, p_socket ps) { diff --git a/src/options.h b/src/options.h index 41f7337..a4d5d75 100644 --- a/src/options.h +++ b/src/options.h @@ -64,6 +64,13 @@ int opt_get_recv_buf_size(lua_State *L, p_socket ps); int opt_set_send_buf_size(lua_State *L, p_socket ps); int opt_get_send_buf_size(lua_State *L, p_socket ps); +#ifdef TCP_FASTOPEN +int opt_set_tcp_fastopen(lua_State *L, p_socket ps); +#endif +#ifdef TCP_FASTOPEN_CONNECT +int opt_set_tcp_fastopen_connect(lua_State *L, p_socket ps); +#endif + int opt_set_ip6_unicast_hops(lua_State *L, p_socket ps); int opt_get_ip6_unicast_hops(lua_State *L, p_socket ps); diff --git a/src/tcp.c b/src/tcp.c index 5876bfb..e24cb0c 100644 --- a/src/tcp.c +++ b/src/tcp.c @@ -109,6 +109,12 @@ static t_opt optset[] = { {"linger", opt_set_linger}, {"recv-buffer-size", opt_set_recv_buf_size}, {"send-buffer-size", opt_set_send_buf_size}, +#ifdef TCP_FASTOPEN + {"tcp-fastopen", opt_set_tcp_fastopen}, +#endif +#ifdef TCP_FASTOPEN_CONNECT + {"tcp-fastopen-connect", opt_set_tcp_fastopen_connect}, +#endif {NULL, NULL} }; -- cgit v1.2.3-55-g6feb From d1ad8160cba9e504c9d17665492044a93efdc3ab Mon Sep 17 00:00:00 2001 From: Kim Alvefur Date: Wed, 27 Jul 2022 08:40:18 +0200 Subject: feat(tcp): Add support for TCP Defer Accept This makes it so that a listening socket does not become readable for accept() until a connection has been fully established *and* started sending something, thus the program doesn't have to wait for the first data. This only makes sense for client-speaks-first protocols. Co-authored-by: Caleb Maclennan --- docs/tcp.html | 2 ++ src/options.c | 9 +++++++++ src/options.h | 4 ++++ src/tcp.c | 3 +++ 4 files changed, 18 insertions(+) (limited to 'docs/tcp.html') diff --git a/docs/tcp.html b/docs/tcp.html index f15196c..a26228d 100644 --- a/docs/tcp.html +++ b/docs/tcp.html @@ -485,6 +485,8 @@ disables the Nagle's algorithm for the connection;
  • 'tcp-keepintvl': value for TCP_KEEPINTVL Linux only!!
    • +
  • 'tcp-defer-accept': value for TCP_DEFER_ACCEPT Linux only!!
    • +
  • 'tcp-fastopen': value for TCP_FASTOPEN Linux only!!
  • 'tcp-fastopen-connect': value for TCP_FASTOPEN_CONNECT Linux only!!
    • diff --git a/src/options.c b/src/options.c index 51ea351..3280c51 100644 --- a/src/options.c +++ b/src/options.c @@ -206,6 +206,15 @@ int opt_set_tcp_fastopen_connect(lua_State *L, p_socket ps) } #endif +/*------------------------------------------------------*/ + +#ifdef TCP_DEFER_ACCEPT +int opt_set_tcp_defer_accept(lua_State *L, p_socket ps) +{ + return opt_setint(L, ps, IPPROTO_TCP, TCP_DEFER_ACCEPT); +} +#endif + /*------------------------------------------------------*/ int opt_set_ip6_unicast_hops(lua_State *L, p_socket ps) { diff --git a/src/options.h b/src/options.h index a4d5d75..456eeb5 100644 --- a/src/options.h +++ b/src/options.h @@ -49,6 +49,10 @@ int opt_set_tcp_keepintvl(lua_State *L, p_socket ps); int opt_get_tcp_keepintvl(lua_State *L, p_socket ps); #endif +#ifdef TCP_DEFER_ACCEPT +int opt_set_tcp_defer_accept(lua_State *L, p_socket ps); +#endif + int opt_set_keepalive(lua_State *L, p_socket ps); int opt_get_keepalive(lua_State *L, p_socket ps); diff --git a/src/tcp.c b/src/tcp.c index e24cb0c..e84db84 100644 --- a/src/tcp.c +++ b/src/tcp.c @@ -109,6 +109,9 @@ static t_opt optset[] = { {"linger", opt_set_linger}, {"recv-buffer-size", opt_set_recv_buf_size}, {"send-buffer-size", opt_set_send_buf_size}, +#ifdef TCP_DEFER_ACCEPT + {"tcp-defer-accept", opt_set_tcp_defer_accept}, +#endif #ifdef TCP_FASTOPEN {"tcp-fastopen", opt_set_tcp_fastopen}, #endif -- cgit v1.2.3-55-g6feb