Network and Web Libraries

---

Ruby provides two levels of access to network services. At a low level, you can access the basic socket support in the underlying operating system, which allows you to implement clients and servers for both connection-oriented and connectionless protocols. These are documented in the next section.

Ruby also has libraries that provide higher-level access to specific application-level network protocols, such as FTP, HTTP, and so on. These are documented starting on page 482.

Finally, the CGIlibraries, documented beginning on page 497, provide server-side developers with a convenient interface for developing Web applications.

Socket-Level Access

Sockets are the endpoints of a bidirectional communications channel. Sockets may communicate within a process, between processes on the same machine, or between processes on different continents. Sockets may be implemented over a number of different channel types: Unix domain sockets, TCP, UDP, and so on. The socket library provides specific classes for handling the common transports as well as a generic interface for handling the rest. All functionality in the socket library is accessible through a single extension library. Access it using

require 'socket'

Sockets have their own vocabulary:

domain

The family of protocols that will be used as the transport mechanism. These values are constants such as PF_INET, PF_UNIX, PF_X25, and so on.

type

The type of communications between the two endpoints, typically SOCK_STREAMfor connection-oriented protocols and SOCK_DGRAMfor connectionless protocols.

protocol

Typically zero, this may be used to identify a variant of a protocol within a domain and type.

hostName

The identifier of a network interface:

• a string, which can be a host name, a dotted-quad address, or an IPV6 address in colon (and possibly dot) notation,
• the string ``'', which specifies anINADDR_BROADCASTaddress,
• a zero-length string, which specifiesINADDR_ANY, or
• anInteger, interpreted as a binary address in host byte order.

port

(sometimes called service) Each server listens for clients calling on one or more ports. A port may be a Fixnumport number, a string containing a port number, or the name of a service.

Sockets are children of class IO. Once a socket has been successfully opened, the conventional I/O methods may be used. However, greater efficiency is sometimes obtained by using socket-specific methods. As with other I/O classes, socket I/O blocks by default. The hierarchy of the socket classes is shown in Figure 26.1 on page 471.

For more information on the use of sockets, see your operating system documentation. You'll also find a comprehensive treatment in W. Richard Stevens, Unix Network Programming, Volumes 1 and 2.

class BasicSocket

Parent: IO Version: 1.6

Index:

do_not_reverse_lookup do_not_reverse_lookup= lookup_order lookup_order= close_read close_write getpeername getsockname getsockopt recv send setsockopt shutdown

---

BasicSocketis an abstract base class for all other socket classes.

This class and its subclasses often manipulate addresses using something called a struct sockaddr, which is effectively an opaque binary string. [In reality, it maps onto the underlying C-languagestruct sockaddrset of structures, documented in the man pages and in the books by Stevens.]

class methods
do_not_reverse_lookup	BasicSocket.do_not_reverse_lookup ->trueorfalse
	Returns the value of the global reverse lookup flag. If set totrue, queries on remote addresses will return the numeric address but not the host name.
do_not_reverse_lookup=	BasicSocket.do_not_reverse_lookup =trueorfalse
	Sets the global reverse lookup flag.
lookup_order	BasicSocket.lookup_order ->aFixnum
	Returns the global address lookup order, one of: Order Families Searched LOOKUP_UNSP AF_UNSPEC LOOKUP_INET AF_INET,AF_INET6,AF_UNSPEC LOOKUP_INET6 AF_INET6,AF_INET,AF_UNSPEC
lookup_order=	BasicSocket.lookup_order =aFixnum
	Sets the global address lookup order.

instance methods
close_read	aSession.close_read ->nil
	Closes the readable connection on this socket.
close_write	aSession.close_write ->nil
	Closes the writable connection on this socket.
getpeername	aSession.getpeername ->aString
	Returns thestruct sockaddrstructure associated with the other end of this socket connection.
getsockname	aSession.getsockname ->aString
	Returns thestruct sockaddrstructure associated withaSession.
getsockopt	aSession.getsockopt(level,optname) ->aString
	Returns the value of the specified option.
recv	aSession.recv(len,[,flags]) ->aString
	Receives up tolenbytes fromaSession.
send	aSession.send(aString,flags,[,to]) ->aFixnum
	SendsaStringoveraSession. If specified,tois astruct sockaddrspecifying the recipient address.flagsare the sum or one or more of theMSG_options (listed on page 478). Returns the number of characters sent.
setsockopt	aSession.setsockopt(level,optname,optval) -> 0
	Sets a socket option.levelis one of the socket-level options (listed on page 478).optnameandoptvalare protocol specific---see your system documentation for details.
shutdown	aSession.shutdown(how=2 ) -> 0
	Shuts down the receive (how== 0), or send (how== 1), or both (how== 2), parts of this socket.

class IPSocket

Parent: BasicSocket Version: 1.6

Index:

getaddress addr peeraddr

---

Class IPSocketis a base class for sockets using IP as their transport. TCPSocketand UDPSocketare based on this class.

class methods
getaddress	IPSocket.getaddress(hostName) ->aString
	Returns the dotted-quad IP address ofhostName. a = IPSocket.getaddress('www.ruby-lang.org') a