listen(p1)
public
Listens for connections, using the specified int as the backlog. A
call to listen only applies if
the socket is of type SOCK_STREAM or SOCK_SEQPACKET.
Parameter
- backlog - the maximum length of the queue for pending connections.
Example 1
require 'socket'
include Socket::Constants
socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
socket.bind( sockaddr )
socket.listen( 5 )
Example 2 (listening on an arbitary port, unix-based systems only):
require 'socket'
include Socket::Constants
socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
socket.listen( 1 )
Unix-based Exceptions
On unix based systems the above will work because a new sockaddr
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 socket is bound by calling bind before it can listen.
If the backlog amount exceeds the implementation-dependent maximum
queue length, the implementation’s maximum queue length will be used.
On unix-based based systems the following system exceptions may be raised
if the call to listen fails:
- Errno::EBADF - the socket argument is not a valid file descriptor
- Errno::EDESTADDRREQ - the socket is not bound to a local address,
and the protocol does not support listening on an unbound socket
- Errno::EINVAL - the socket is already connected
- Errno::ENOTSOCK - the socket argument does not refer to a socket
- Errno::EOPNOTSUPP - the socket protocol does not support listen
- Errno::EACCES - the calling process does not have approriate privileges
- Errno::EINVAL - the socket has been shut down
- Errno::ENOBUFS - insufficient resources are available in the system to
complete the call
Windows Exceptions
On Windows systems the following system exceptions may be raised if the
call to listen fails:
- Errno::ENETDOWN - the network is down
- Errno::EADDRINUSE - the socket’s local address is already in use.
This usually occurs during the execution of bind but could be delayed if the call to
bind was to a partially wildcard
address (involving ADDR_ANY) and if a specific address needs to be
commmitted at the time of the call to listen
- Errno::EINPROGRESS - a Windows Sockets 1.1 call is in progress or the
service provider is still processing a callback function
- Errno::EINVAL - the socket has not been bound with a call to
bind.
- Errno::EISCONN - the socket is already connected
- Errno::EMFILE - no more socket descriptors are available
- Errno::ENOBUFS - no buffer space is available
- Errno::ENOTSOC - socket is not a socket
- Errno::EOPNOTSUPP - the referenced socket is not a type that
supports the listen method
See
- listen manual pages on unix-based systems
- listen function in Microsoft’s
Winsock functions reference
Show source
/*
* call-seq:
* socket.listen( int ) => 0
*
* Listens for connections, using the specified +int+ as the backlog. A call
* to _listen_ only applies if the +socket+ is of type SOCK_STREAM or
* SOCK_SEQPACKET.
*
* === Parameter
* * +backlog+ - the maximum length of the queue for pending connections.
*
* === Example 1
* require 'socket'
* include Socket::Constants
* socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
* sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
* socket.bind( sockaddr )
* socket.listen( 5 )
*
* === Example 2 (listening on an arbitary port, unix-based systems only):
* require 'socket'
* include Socket::Constants
* socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
* socket.listen( 1 )
*
* === Unix-based Exceptions
* On unix based systems the above will work because a new +sockaddr+ 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 +socket+ is bound by calling _bind_ before it can _listen_.
*
* If the _backlog_ amount exceeds the implementation-dependent maximum
* queue length, the implementation's maximum queue length will be used.
*
* On unix-based based systems the following system exceptions may be raised if the
* call to _listen_ fails:
* * Errno::EBADF - the _socket_ argument is not a valid file descriptor
* * Errno::EDESTADDRREQ - the _socket_ is not bound to a local address, and
* the protocol does not support listening on an unbound socket
* * Errno::EINVAL - the _socket_ is already connected
* * Errno::ENOTSOCK - the _socket_ argument does not refer to a socket
* * Errno::EOPNOTSUPP - the _socket_ protocol does not support listen
* * Errno::EACCES - the calling process does not have approriate privileges
* * Errno::EINVAL - the _socket_ has been shut down
* * Errno::ENOBUFS - insufficient resources are available in the system to
* complete the call
*
* === Windows Exceptions
* On Windows systems the following system exceptions may be raised if
* the call to _listen_ fails:
* * Errno::ENETDOWN - the network is down
* * Errno::EADDRINUSE - the socket's local address is already in use. This
* usually occurs during the execution of _bind_ but could be delayed
* if the call to _bind_ was to a partially wildcard address (involving
* ADDR_ANY) and if a specific address needs to be commmitted at the
* time of the call to _listen_
* * Errno::EINPROGRESS - a Windows Sockets 1.1 call is in progress or the
* service provider is still processing a callback function
* * Errno::EINVAL - the +socket+ has not been bound with a call to _bind_.
* * Errno::EISCONN - the +socket+ is already connected
* * Errno::EMFILE - no more socket descriptors are available
* * Errno::ENOBUFS - no buffer space is available
* * Errno::ENOTSOC - +socket+ is not a socket
* * Errno::EOPNOTSUPP - the referenced +socket+ is not a type that supports
* the _listen_ method
*
* === See
* * listen manual pages on unix-based systems
* * listen function in Microsoft's Winsock functions reference
*/
static VALUE
sock_listen(sock, log)
VALUE sock, log;
{
rb_io_t *fptr;
int backlog;
rb_secure(4);
backlog = NUM2INT(log);
GetOpenFile(sock, fptr);
if (listen(fileno(fptr->f), backlog) < 0)
rb_sys_fail("listen(2)");
return INT2FIX(0);
}