| Class | Socket |
| In: |
lib/ipaddr.rb
ext/socket/socket.c |
| Parent: | Object |
Class Socket provides access to the underlying operating system socket implementations. It can be used to provide more operating system specific functionality than the protocol-specific socket classes but at the expense of greater complexity. In particular, the class handles addresses using struct sockaddr structures packed into Ruby strings, which can be a joy to manipulate.
Ruby‘s implementation of Socket causes an exception to be raised based on the error generated by the system dependent implementation. This is why the methods are documented in a way that isolate Unix-based system exceptions from Windows based exceptions. If more information on particular exception is needed please refer to the Unix manual pages or the Windows WinSock reference.
Much material in this documentation is taken with permission from Programming Ruby from The Pragmatic Bookshelf.
| AF_INET6 | = | Object.new |
Accepts an incoming connection using accept(2) after O_NONBLOCK is set for the underlying file descriptor. It returns an array containg the accpeted socket for the incoming connection, client_socket, and a string that contains the struct sockaddr information about the caller, client_sockaddr.
# In one script, start this first
require 'socket'
include Socket::Constants
socket = Socket.new(AF_INET, SOCK_STREAM, 0)
sockaddr = Socket.sockaddr_in(2200, 'localhost')
socket.bind(sockaddr)
socket.listen(5)
begin
client_socket, client_sockaddr = socket.accept_nonblock
rescue Errno::EAGAIN, Errno::EWOULDBLOCK, Errno::ECONNABORTED, Errno::EPROTO, Errno::EINTR
IO.select([socket])
retry
end
puts "The client said, '#{client_socket.readline.chomp}'"
client_socket.puts "Hello from script one!"
socket.close
# In another script, start this second
require 'socket'
include Socket::Constants
socket = Socket.new(AF_INET, SOCK_STREAM, 0)
sockaddr = Socket.sockaddr_in(2200, 'localhost')
socket.connect(sockaddr)
socket.puts "Hello from script 2."
puts "The server said, '#{socket.readline.chomp}'"
socket.close
Refer to Socket#accept for the exceptions that may be thrown if the call to accept_nonblock fails.
Socket#accept_nonblock may raise any error corresponding to accept(2) failure, including Errno::EWOULDBLOCK.
Binds to the given struct sockaddr.
require 'socket'
include Socket::Constants
socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
socket.bind( sockaddr )
On unix-based based systems the following system exceptions may be raised if the call to bind fails:
On unix-based based systems if the address family of the calling socket is Socket::AF_UNIX the follow exceptions may be raised if the call to bind fails:
On Windows systems the following system exceptions may be raised if the call to bind fails:
Requests a connection to be made on the given server_sockaddr. Returns 0 if successful, otherwise an exception is raised.
# Pull down Google's web page
require 'socket'
include Socket::Constants
socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
sockaddr = Socket.pack_sockaddr_in( 80, 'www.google.com' )
socket.connect( sockaddr )
socket.write( "GET / HTTP/1.0\r\n\r\n" )
results = socket.read
On unix-based systems the following system exceptions may be raised if the call to connect fails:
On unix-based systems if the address family of the calling socket is AF_UNIX the follow exceptions may be raised if the call to connect fails:
On Windows systems the following system exceptions may be raised if the call to connect fails:
Requests a connection to be made on the given server_sockaddr after O_NONBLOCK is set for the underlying file descriptor. Returns 0 if successful, otherwise an exception is raised.
# Pull down Google's web page
require 'socket'
include Socket::Constants
socket = Socket.new(AF_INET, SOCK_STREAM, 0)
sockaddr = Socket.sockaddr_in(80, 'www.google.com')
begin
socket.connect_nonblock(sockaddr)
rescue Errno::EINPROGRESS
IO.select(nil, [socket])
begin
socket.connect_nonblock(sockaddr)
rescue Errno::EISCONN
end
end
socket.write("GET / HTTP/1.0\r\n\r\n")
results = socket.read
Refer to Socket#connect for the exceptions that may be thrown if the call to connect_nonblock fails.
Socket#connect_nonblock may raise any error corresponding to connect(2) failure, including Errno::EINPROGRESS.
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.
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 )
require 'socket'
include Socket::Constants
socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
socket.listen( 1 )
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:
On Windows systems the following system exceptions may be raised if the call to listen fails:
Receives up to maxlen bytes from socket. flags is zero or more of the MSG_ options. The first element of the results, mesg, is the data received. The second element, sender_sockaddr, contains protocol-specific information on the sender.
# In one file, start this first
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 )
client, client_sockaddr = socket.accept
data = client.recvfrom( 20 )[0].chomp
puts "I only received 20 bytes '#{data}'"
sleep 1
socket.close
# In another file, start this second
require 'socket'
include Socket::Constants
socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
socket.connect( sockaddr )
socket.puts "Watch this get cut short!"
socket.close
On unix-based based systems the following system exceptions may be raised if the call to recvfrom fails:
On Windows systems the following system exceptions may be raised if the call to recvfrom fails:
Receives up to maxlen bytes from socket using recvfrom(2) after O_NONBLOCK is set for the underlying file descriptor. flags is zero or more of the MSG_ options. The first element of the results, mesg, is the data received. The second element, sender_sockaddr, contains protocol-specific information on the sender.
When recvfrom(2) returns 0, Socket#recvfrom_nonblock returns an empty string as data. The meaning depends on the socket: EOF on TCP, empty packet on UDP, etc.
# In one file, start this first
require 'socket'
include Socket::Constants
socket = Socket.new(AF_INET, SOCK_STREAM, 0)
sockaddr = Socket.sockaddr_in(2200, 'localhost')
socket.bind(sockaddr)
socket.listen(5)
client, client_sockaddr = socket.accept
begin
pair = client.recvfrom_nonblock(20)
rescue Errno::EAGAIN, Errno::EWOULDBLOCK
IO.select([client])
retry
end
data = pair[0].chomp
puts "I only received 20 bytes '#{data}'"
sleep 1
socket.close
# In another file, start this second
require 'socket'
include Socket::Constants
socket = Socket.new(AF_INET, SOCK_STREAM, 0)
sockaddr = Socket.sockaddr_in(2200, 'localhost')
socket.connect(sockaddr)
socket.puts "Watch this get cut short!"
socket.close
Refer to Socket#recvfrom for the exceptions that may be thrown if the call to recvfrom_nonblock fails.
Socket#recvfrom_nonblock may raise any error corresponding to recvfrom(2) failure, including Errno::EWOULDBLOCK.
Accepts an incoming connection returnings an array containg the (integer) file descriptor for the incoming connection, client_socket_fd, and a string that contains the struct sockaddr information about the caller, client_sockaddr.
# In one script, start this first
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 )
client_fd, client_sockaddr = socket.sysaccept
client_socket = Socket.for_fd( client_fd )
puts "The client said, '#{client_socket.readline.chomp}'"
client_socket.puts "Hello from script one!"
socket.close
# In another script, start this second
require 'socket'
include Socket::Constants
socket = Socket.new( AF_INET, SOCK_STREAM, 0 )
sockaddr = Socket.pack_sockaddr_in( 2200, 'localhost' )
socket.connect( sockaddr )
socket.puts "Hello from script 2."
puts "The server said, '#{socket.readline.chomp}'"
socket.close
Refer to Socket#accept for the exceptions that may be thrown if the call to sysaccept fails.
ruby-doc.org is a community service provided by Happy Camper Studios, a Phoenix, Arizona, Ruby application development company.
Documentation content on ruby-doc.org is provided by remarkable members of the Ruby community.
For more information on the Ruby programming language, visit ruby-lang.org.
Want to help improve Ruby's API docs? See Ruby Documentation Guidelines.