- Inheritance
- < IO
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.
Exception Handling
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.
Documentation by
- Zach Dennis
- Sam Roberts
- Programming Ruby from The Pragmatic Bookshelf.
Much material in this documentation is taken with permission from Programming Ruby from The Pragmatic Bookshelf.
Methods
Instance
| Visibility | Signature |
|---|---|
| public | getsockopt (p1, p2) |
| public | recv_nonblock (...) |
| public | setsockopt (p1, p2, p3) |
Instance Method Detail
getsockopt(level, optname)
Gets a socket option. These are protocol and system specific, see your local sytem documentation for details. The option is returned as a String with the data being the binary value of the socket option.
Parameters
- level is an integer, usually one of the SOL_ constants such as Socket::SOL_SOCKET, or a protocol level.
- optname is an integer, usually one of the SO_ constants, such as Socket::SO_REUSEADDR.
Examples
Some socket options are integers with boolean values, in this case getsockopt could be called like this:
optval = sock.getsockopt(Socket::SOL_SOCKET,Socket::SO_REUSEADDR) optval = optval.unpack "i" reuseaddr = optval[0] == 0 ? false : true
Some socket options are integers with numeric values, in this case getsockopt could be called like this:
optval = sock.getsockopt(Socket::IPPROTO_IP, Socket::IP_TTL)
ipttl = optval.unpack("i")[0]
Option values may be structs. Decoding them can be complex as it involves examining your system headers to determine the correct definition. An example is a +struct linger+, which may be defined in your system headers as:
struct linger {
int l_onoff;
int l_linger;
};
In this case getsockopt could be called like this:
optval = sock.getsockopt(Socket::SOL_SOCKET, Socket::SO_LINGER) onoff, linger = optval.unpack "ii"
basicsocket.recv_nonblock(maxlen) => mesg
basicsocket.recv_nonblock(maxlen, flags) => mesg
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 result, mesg, is the data received.
When recvfrom(2) returns 0, Socket#recv_nonblock returns an empty string as data. The meaning depends on the socket: EOF on TCP, empty packet on UDP, etc.
Parameters
- maxlen - the number of bytes to receive from the socket
- flags - zero or more of the MSG_ options
Example
serv = TCPServer.new("127.0.0.1", 0)
af, port, host, addr = serv.addr
c = TCPSocket.new(addr, port)
s = serv.accept
c.send "aaa", 0
IO.select([s])
p s.recv_nonblock(10) #=> "aaa"
Refer to Socket#recvfrom for the exceptions that may be thrown if the call to recv_nonblock fails.
BasicSocket#recv_nonblock may raise any error corresponding to recvfrom(2) failure, including Errno::EAGAIN.
See
setsockopt(level, optname, optval)
Sets a socket option. These are protocol and system specific, see your local sytem documentation for details.
Parameters
- level is an integer, usually one of the SOL_ constants such as Socket::SOL_SOCKET, or a protocol level.
- optname is an integer, usually one of the SO_ constants, such as Socket::SO_REUSEADDR.
- optval is the value of the option, it is passed to the underlying
setsockopt() as a pointer to a
certain number of bytes. How this is done depends on the type:
- Fixnum: value is assigned to an int, and a pointer to the int is passed, with length of sizeof(int).
- true or false: 1 or 0 (respectively) is assigned to an int, and the int is passed as for a Fixnum. Note that false must be passed, not nil.
- String: the string‘s data and length is passed to the socket.
Examples
Some socket options are integers with boolean values, in this case setsockopt could be called like this:
sock.setsockopt(Socket::SOL_SOCKET,Socket::SO_REUSEADDR, true)
Some socket options are integers with numeric values, in this case setsockopt could be called like this:
sock.setsockopt(Socket::IPPROTO_IP, Socket::IP_TTL, 255)
Option values may be structs. Passing them can be complex as it involves examining your system headers to determine the correct definition. An example is an ip_mreq, which may be defined in your system headers as:
struct ip_mreq {
struct in_addr imr_multiaddr;
struct in_addr imr_interface;
};
In this case setsockopt could be called like this:
optval = IPAddr.new("224.0.0.251") + Socket::INADDR_ANY
sock.setsockopt(Socket::IPPROTO_IP, Socket::IP_ADD_MEMBERSHIP, optval)