| 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 |
Return address information for host and port. The remaining arguments are hints that limit the address information returned.
This method corresponds closely to the POSIX.1g getaddrinfo() definition.
Returns an array of arrays, where each subarray contains:
The first four values are identical to what is commonly returned as an address array, see IPSocket for more information.
Not all input combinations are valid, and while there are many combinations, only a few cases are common.
A typical client will call getaddrinfo with the host and service it wants to connect to. It knows that it will attempt to connect with either TCP or UDP, and specifies socktype accordingly. It loops through all returned addresses, and try to connect to them in turn:
addrinfo = Socket::getaddrinfo('www.example.com', 'www', nil, Socket::SOCK_STREAM)
addrinfo.each do |af, port, name, addr|
begin
sock = TCPSocket.new(addr, port)
# ...
exit 1
rescue
end
end
With UDP you don‘t know if connect suceeded, but if communication fails, the next address can be tried.
A typical server will call getaddrinfo with a host of nil, the service it listens to, and a flags of Socket::AI_PASSIVE. It will listen for connections on the first returned address:
addrinfo = Socket::getaddrinfo(nil, 'www', nil, Socket::SOCK_STREAM, nil, Socket::AI_PASSIVE)
af, port, name, addr = addrinfo.first
sock = TCPServer(addr, port)
while( client = s.accept )
# ...
end
Resolve host and return name and address information for it, similarly to gethostbyname(3). host can be a domain name or the presentation format of an address.
Returns an array of information similar to that found in a +struct hostent+:
- cannonical name: the cannonical name for host in the DNS, or a
string representing the address
- aliases: an array of aliases for the canonical name, there may be no aliases
- address family: usually one of Socket::AF_INET or Socket::AF_INET6
- address: a string, the binary value of the +struct sockaddr+ for this name, in
the indicated address family
- ...: if there are multiple addresses for this host, a series of
strings/+struct sockaddr+s may follow, not all necessarily in the same
address family. Note that the fact that they may not be all in the same
address family is a departure from the behaviour of gethostbyname(3).
Note: I believe that the fact that the multiple addresses returned are not necessarily in the same address family may be a bug, since if this function actually called gethostbyname(3), ALL the addresses returned in the trailing address list (h_addr_list from struct hostent) would be of the same address family! Examples from my system, OS X 10.3:
["localhost", [], 30, "\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\001", "\177\000\000\001"]
and
["ensemble.local", [], 30, "\376\200\000\004\000\000\000\000\002\003\223\377\376\255\010\214", "\300\250{\232" ]
Similar information can be returned by Socket.getaddrinfo if called as:
Socket.getaddrinfo(+host+, 0, Socket::AF_UNSPEC, Socket::SOCK_STREAM, nil, Socket::AI_CANONNAME)
Socket.gethostbyname "example.com" => ["example.com", [], 2, "\300\000\"\246"]
This name has no DNS aliases, and a single IPv4 address.
Socket.gethostbyname "smtp.telus.net" => ["smtp.svc.telus.net", ["smtp.telus.net"], 2, "\307\271\334\371"]
This name is an an alias so the canonical name is returned, as well as the alias and a single IPv4 address.
Socket.gethostbyname "localhost" => ["localhost", [], 30, "\000\000\000\000\000\000\000\000\000\000\000\000\000\000\000\001", "\177\000\000\001"]
This machine has no aliases, returns an IPv6 address, and has an additional IPv4 address.
host can also be an IP address in presentation format, in which case a reverse lookup is done on the address:
Socket.gethostbyname("127.0.0.1")
=> ["localhost", [], 2, "\177\000\000\001"]
Socket.gethostbyname("192.0.34.166")
=> ["www.example.com", [], 2, "\300\000\"\246"]
See: Socket.getaddrinfo
name is a service name ("ftp", "telnet", …) and proto is a protocol name ("udp", "tcp", …). ’/etc/services’ (or your system‘s equivalent) is searched for a service for name and proto, and the port number is returned.
Note that unlike Socket.getaddrinfo, proto may not be specified using the Socket::SOCK_* constants, a string must must be used.
Accepts an incoming connection returning an array containing a new Socket object and a string holding the struct sockaddr information about the caller.
# 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, client_sockaddr = socket.accept
puts "The client said, '#{client.readline.chomp}'"
client.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
On unix-based based systems the following system exceptions may be raised if the call to accept fails:
On Windows systems the following system exceptions may be raised if the call to accept fails:
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::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::EAGAIN.
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
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::EAGAIN.
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 service of James Britt and Neurogami, a Ruby application development company in Phoenix, AZ.
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.