File: C:/Ruby27-x64/share/doc/ruby/html/TCPServer.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>class TCPServer - RDoc Documentation</title>
<script type="text/javascript">
var rdoc_rel_prefix = "./";
var index_rel_prefix = "./";
</script>
<script src="./js/navigation.js" defer></script>
<script src="./js/search.js" defer></script>
<script src="./js/search_index.js" defer></script>
<script src="./js/searcher.js" defer></script>
<script src="./js/darkfish.js" defer></script>
<link href="./css/fonts.css" rel="stylesheet">
<link href="./css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="class">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="./index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="./table_of_contents.html#pages">Pages</a>
<a href="./table_of_contents.html#classes">Classes</a>
<a href="./table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div id="class-metadata">
<div id="parent-class-section" class="nav-section">
<h3>Parent</h3>
<p class="link"><a href="TCPSocket.html">TCPSocket</a>
</div>
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-new">::new</a>
<li ><a href="#method-i-accept">#accept</a>
<li ><a href="#method-i-accept_nonblock">#accept_nonblock</a>
<li ><a href="#method-i-listen">#listen</a>
<li ><a href="#method-i-sysaccept">#sysaccept</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="class-TCPServer">
<h1 id="class-TCPServer" class="class">
class TCPServer
</h1>
<section class="description">
<p><a href="TCPServer.html"><code>TCPServer</code></a> represents a TCP/IP server socket.</p>
<p>A simple TCP server may look like:</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'socket'</span>
<span class="ruby-identifier">server</span> = <span class="ruby-constant">TCPServer</span>.<span class="ruby-identifier">new</span> <span class="ruby-value">2000</span> <span class="ruby-comment"># Server bind to port 2000</span>
<span class="ruby-identifier">loop</span> <span class="ruby-keyword">do</span>
<span class="ruby-identifier">client</span> = <span class="ruby-identifier">server</span>.<span class="ruby-identifier">accept</span> <span class="ruby-comment"># Wait for a client to connect</span>
<span class="ruby-identifier">client</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">"Hello !"</span>
<span class="ruby-identifier">client</span>.<span class="ruby-identifier">puts</span> <span class="ruby-node">"Time is #{Time.now}"</span>
<span class="ruby-identifier">client</span>.<span class="ruby-identifier">close</span>
<span class="ruby-keyword">end</span>
</pre>
<p>A more usable server (serving multiple clients):</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'socket'</span>
<span class="ruby-identifier">server</span> = <span class="ruby-constant">TCPServer</span>.<span class="ruby-identifier">new</span> <span class="ruby-value">2000</span>
<span class="ruby-identifier">loop</span> <span class="ruby-keyword">do</span>
<span class="ruby-constant">Thread</span>.<span class="ruby-identifier">start</span>(<span class="ruby-identifier">server</span>.<span class="ruby-identifier">accept</span>) <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">client</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">client</span>.<span class="ruby-identifier">puts</span> <span class="ruby-string">"Hello !"</span>
<span class="ruby-identifier">client</span>.<span class="ruby-identifier">puts</span> <span class="ruby-node">"Time is #{Time.now}"</span>
<span class="ruby-identifier">client</span>.<span class="ruby-identifier">close</span>
<span class="ruby-keyword">end</span>
<span class="ruby-keyword">end</span>
</pre>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-new" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
new([hostname,] port) → tcpserver
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Creates a new server socket bound to <em>port</em>.</p>
<p>If <em>hostname</em> is given, the socket is bound to it.</p>
<pre class="ruby"><span class="ruby-identifier">serv</span> = <span class="ruby-constant">TCPServer</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"127.0.0.1"</span>, <span class="ruby-value">28561</span>)
<span class="ruby-identifier">s</span> = <span class="ruby-identifier">serv</span>.<span class="ruby-identifier">accept</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">puts</span> <span class="ruby-constant">Time</span>.<span class="ruby-identifier">now</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">close</span>
</pre>
<p>Internally, <a href="TCPServer.html#method-c-new"><code>TCPServer.new</code></a> calls getaddrinfo() function to obtain addresses. If getaddrinfo() returns multiple addresses, <a href="TCPServer.html#method-c-new"><code>TCPServer.new</code></a> tries to create a server socket for each address and returns first one that is successful.</p>
<div class="method-source-code" id="new-source">
<pre>static VALUE
tcp_svr_init(int argc, VALUE *argv, VALUE sock)
{
VALUE hostname, port;
rb_scan_args(argc, argv, "011", &hostname, &port);
return rsock_init_inetsock(sock, hostname, port, Qnil, Qnil, INET_SERVER);
}</pre>
</div>
</div>
</div>
</section>
<section id="public-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Instance Methods</h3>
</header>
<div id="method-i-accept" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
accept → tcpsocket
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Accepts an incoming connection. It returns a new <a href="TCPSocket.html"><code>TCPSocket</code></a> object.</p>
<pre class="ruby"><span class="ruby-constant">TCPServer</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">"127.0.0.1"</span>, <span class="ruby-value">14641</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">serv</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">s</span> = <span class="ruby-identifier">serv</span>.<span class="ruby-identifier">accept</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">puts</span> <span class="ruby-constant">Time</span>.<span class="ruby-identifier">now</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">close</span>
}
</pre>
<div class="method-source-code" id="accept-source">
<pre>static VALUE
tcp_accept(VALUE sock)
{
rb_io_t *fptr;
union_sockaddr from;
socklen_t fromlen;
GetOpenFile(sock, fptr);
fromlen = (socklen_t)sizeof(from);
return rsock_s_accept(rb_cTCPSocket, fptr->fd, &from.addr, &fromlen);
}</pre>
</div>
</div>
</div>
<div id="method-i-accept_nonblock" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
accept_nonblock([options]) → tcpsocket
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Accepts an incoming connection using accept(2) after O_NONBLOCK is set for the underlying file descriptor. It returns an accepted <a href="TCPSocket.html"><code>TCPSocket</code></a> for the incoming connection.</p>
<h3 id="method-i-accept_nonblock-label-Example">Example<span><a href="#method-i-accept_nonblock-label-Example">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'socket'</span>
<span class="ruby-identifier">serv</span> = <span class="ruby-constant">TCPServer</span>.<span class="ruby-identifier">new</span>(<span class="ruby-value">2202</span>)
<span class="ruby-keyword">begin</span> <span class="ruby-comment"># emulate blocking accept</span>
<span class="ruby-identifier">sock</span> = <span class="ruby-identifier">serv</span>.<span class="ruby-identifier">accept_nonblock</span>
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">IO</span><span class="ruby-operator">::</span><span class="ruby-constant">WaitReadable</span>, <span class="ruby-constant">Errno</span><span class="ruby-operator">::</span><span class="ruby-constant">EINTR</span>
<span class="ruby-constant">IO</span>.<span class="ruby-identifier">select</span>([<span class="ruby-identifier">serv</span>])
<span class="ruby-keyword">retry</span>
<span class="ruby-keyword">end</span>
<span class="ruby-comment"># sock is an accepted socket.</span>
</pre>
<p>Refer to <a href="Socket.html#method-i-accept"><code>Socket#accept</code></a> for the exceptions that may be thrown if the call to <a href="TCPServer.html#method-i-accept_nonblock"><code>TCPServer#accept_nonblock</code></a> fails.</p>
<p><a href="TCPServer.html#method-i-accept_nonblock"><code>TCPServer#accept_nonblock</code></a> may raise any error corresponding to accept(2) failure, including Errno::EWOULDBLOCK.</p>
<p>If the exception is Errno::EWOULDBLOCK, Errno::EAGAIN, <a href="Errno/ECONNABORTED.html"><code>Errno::ECONNABORTED</code></a>, <a href="Errno/EPROTO.html"><code>Errno::EPROTO</code></a>, it is extended by <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a>. So <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> can be used to rescue the exceptions for retrying accept_nonblock.</p>
<p>By specifying a keyword argument <em>exception</em> to <code>false</code>, you can indicate that <a href="TCPServer.html#method-i-accept_nonblock"><code>accept_nonblock</code></a> should not raise an <a href="IO/WaitReadable.html"><code>IO::WaitReadable</code></a> exception, but return the symbol <code>:wait_readable</code> instead.</p>
<h3 id="method-i-accept_nonblock-label-See">See<span><a href="#method-i-accept_nonblock-label-See">¶</a> <a href="#top">↑</a></span></h3>
<ul><li>
<p><a href="TCPServer.html#method-i-accept"><code>TCPServer#accept</code></a></p>
</li><li>
<p><a href="Socket.html#method-i-accept"><code>Socket#accept</code></a></p>
</li></ul>
<div class="method-source-code" id="accept_nonblock-source">
<pre><span class="ruby-comment"># File ext/socket/lib/socket.rb, line 1313</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">accept_nonblock</span>(<span class="ruby-value">exception:</span> <span class="ruby-keyword">true</span>)
<span class="ruby-identifier">__accept_nonblock</span>(<span class="ruby-identifier">exception</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-listen" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
listen( int ) → 0
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Listens for connections, using the specified <code>int</code> as the backlog. A call to <em>listen</em> only applies if the <code>socket</code> is of type SOCK_STREAM or SOCK_SEQPACKET.</p>
<h3 id="method-i-listen-label-Parameter">Parameter<span><a href="#method-i-listen-label-Parameter">¶</a> <a href="#top">↑</a></span></h3>
<ul><li>
<p><code>backlog</code> - the maximum length of the queue for pending connections.</p>
</li></ul>
<h3 id="method-i-listen-label-Example+1">Example 1<span><a href="#method-i-listen-label-Example+1">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'socket'</span>
<span class="ruby-identifier">include</span> <span class="ruby-constant">Socket</span><span class="ruby-operator">::</span><span class="ruby-constant">Constants</span>
<span class="ruby-identifier">socket</span> = <span class="ruby-constant">Socket</span>.<span class="ruby-identifier">new</span>( <span class="ruby-constant">AF_INET</span>, <span class="ruby-constant">SOCK_STREAM</span>, <span class="ruby-value">0</span> )
<span class="ruby-identifier">sockaddr</span> = <span class="ruby-constant">Socket</span>.<span class="ruby-identifier">pack_sockaddr_in</span>( <span class="ruby-value">2200</span>, <span class="ruby-string">'localhost'</span> )
<span class="ruby-identifier">socket</span>.<span class="ruby-identifier">bind</span>( <span class="ruby-identifier">sockaddr</span> )
<span class="ruby-identifier">socket</span>.<span class="ruby-identifier">listen</span>( <span class="ruby-value">5</span> )
</pre>
<h3 id="method-i-listen-label-Example+2+-28listening+on+an+arbitrary+port-2C+unix-based+systems+only-29-3A">Example 2 (listening on an arbitrary port, unix-based systems only):<span><a href="#method-i-listen-label-Example+2+-28listening+on+an+arbitrary+port-2C+unix-based+systems+only-29-3A">¶</a> <a href="#top">↑</a></span></h3>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'socket'</span>
<span class="ruby-identifier">include</span> <span class="ruby-constant">Socket</span><span class="ruby-operator">::</span><span class="ruby-constant">Constants</span>
<span class="ruby-identifier">socket</span> = <span class="ruby-constant">Socket</span>.<span class="ruby-identifier">new</span>( <span class="ruby-constant">AF_INET</span>, <span class="ruby-constant">SOCK_STREAM</span>, <span class="ruby-value">0</span> )
<span class="ruby-identifier">socket</span>.<span class="ruby-identifier">listen</span>( <span class="ruby-value">1</span> )
</pre>
<h3 id="method-i-listen-label-Unix-based+Exceptions">Unix-based Exceptions<span><a href="#method-i-listen-label-Unix-based+Exceptions">¶</a> <a href="#top">↑</a></span></h3>
<p>On unix based systems the above will work because a new <code>sockaddr</code> struct is created on the address ADDR_ANY, for an arbitrary port number as handed off by the kernel. It will not work on Windows, because Windows requires that the <code>socket</code> is bound by calling <em>bind</em> before it can <em>listen</em>.</p>
<p>If the <em>backlog</em> amount exceeds the implementation-dependent maximum queue length, the implementation's maximum queue length will be used.</p>
<p>On unix-based based systems the following system exceptions may be raised if the call to <em>listen</em> fails:</p>
<ul><li>
<p>Errno::EBADF - the <em>socket</em> argument is not a valid file descriptor</p>
</li><li>
<p>Errno::EDESTADDRREQ - the <em>socket</em> is not bound to a local address, and the protocol does not support listening on an unbound socket</p>
</li><li>
<p>Errno::EINVAL - the <em>socket</em> is already connected</p>
</li><li>
<p>Errno::ENOTSOCK - the <em>socket</em> argument does not refer to a socket</p>
</li><li>
<p>Errno::EOPNOTSUPP - the <em>socket</em> protocol does not support listen</p>
</li><li>
<p>Errno::EACCES - the calling process does not have appropriate privileges</p>
</li><li>
<p>Errno::EINVAL - the <em>socket</em> has been shut down</p>
</li><li>
<p>Errno::ENOBUFS - insufficient resources are available in the system to complete the call</p>
</li></ul>
<h3 id="method-i-listen-label-Windows+Exceptions">Windows Exceptions<span><a href="#method-i-listen-label-Windows+Exceptions">¶</a> <a href="#top">↑</a></span></h3>
<p>On Windows systems the following system exceptions may be raised if the call to <em>listen</em> fails:</p>
<ul><li>
<p>Errno::ENETDOWN - the network is down</p>
</li><li>
<p>Errno::EADDRINUSE - the socket's local address is already in use. This usually occurs during the execution of <em>bind</em> but could be delayed if the call to <em>bind</em> was to a partially wildcard address (involving ADDR_ANY) and if a specific address needs to be committed at the time of the call to <em>listen</em></p>
</li><li>
<p>Errno::EINPROGRESS - a Windows Sockets 1.1 call is in progress or the service provider is still processing a callback function</p>
</li><li>
<p>Errno::EINVAL - the <code>socket</code> has not been bound with a call to <em>bind</em>.</p>
</li><li>
<p>Errno::EISCONN - the <code>socket</code> is already connected</p>
</li><li>
<p>Errno::EMFILE - no more socket descriptors are available</p>
</li><li>
<p>Errno::ENOBUFS - no buffer space is available</p>
</li><li>
<p>Errno::ENOTSOC - <code>socket</code> is not a socket</p>
</li><li>
<p>Errno::EOPNOTSUPP - the referenced <code>socket</code> is not a type that supports the <em>listen</em> method</p>
</li></ul>
<h3 id="method-i-listen-label-See">See<span><a href="#method-i-listen-label-See">¶</a> <a href="#top">↑</a></span></h3>
<ul><li>
<p>listen manual pages on unix-based systems</p>
</li><li>
<p>listen function in Microsoft's Winsock functions reference</p>
</li></ul>
<div class="method-source-code" id="listen-source">
<pre>VALUE
rsock_sock_listen(VALUE sock, VALUE log)
{
rb_io_t *fptr;
int backlog;
backlog = NUM2INT(log);
GetOpenFile(sock, fptr);
if (listen(fptr->fd, backlog) < 0)
rb_sys_fail("listen(2)");
return INT2FIX(0);
}</pre>
</div>
</div>
</div>
<div id="method-i-sysaccept" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
sysaccept → file_descriptor
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns a file descriptor of a accepted connection.</p>
<pre class="ruby"><span class="ruby-constant">TCPServer</span>.<span class="ruby-identifier">open</span>(<span class="ruby-string">"127.0.0.1"</span>, <span class="ruby-value">28561</span>) {<span class="ruby-operator">|</span><span class="ruby-identifier">serv</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">fd</span> = <span class="ruby-identifier">serv</span>.<span class="ruby-identifier">sysaccept</span>
<span class="ruby-identifier">s</span> = <span class="ruby-constant">IO</span>.<span class="ruby-identifier">for_fd</span>(<span class="ruby-identifier">fd</span>)
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">puts</span> <span class="ruby-constant">Time</span>.<span class="ruby-identifier">now</span>
<span class="ruby-identifier">s</span>.<span class="ruby-identifier">close</span>
}
</pre>
<div class="method-source-code" id="sysaccept-source">
<pre>static VALUE
tcp_sysaccept(VALUE sock)
{
rb_io_t *fptr;
union_sockaddr from;
socklen_t fromlen;
GetOpenFile(sock, fptr);
fromlen = (socklen_t)sizeof(from);
return rsock_s_accept(0, fptr->fd, &from.addr, &fromlen);
}</pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.2.1.1.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>