class Socket

yield socket and client address for each a connection accepted via given sockets.

The arguments are a list of sockets. The individual argument should be a socket or an array of sockets.

This method yields the block sequentially. It means that the next connection is not accepted until the block returns. So concurrent mechanism, thread for example, should be used to service multiple clients at a time.

# File rake/lib/socket.rb, line 407
def self.accept_loop(*sockets) # :yield: socket, client_addrinfo
  sockets.flatten!(1)
  if sockets.empty?
    raise ArgumentError, "no sockets"
  end
  loop {
    readable, _, _ = IO.select(sockets)
    readable.each {|r|
      begin
        sock, addr = r.accept_nonblock
      rescue IO::WaitReadable
        next
      end
      yield sock, addr
    }
  }
end

creates a new socket object connected to host:port using TCP/IP.

If local_host:local_port is given, the socket is bound to it.

If a block is given, the block is called with the socket. The value of the block is returned. The socket is closed when this method returns.

If no block is given, the socket is returned.

Socket.tcp("www.ruby-lang.org", 80) {|sock|
  sock.print "GET / HTTP/1.0\r\nHost: www.ruby-lang.org\r\n\r\n"
  sock.close_write
  puts sock.read
}

# File rake/lib/socket.rb, line 236
def self.tcp(host, port, local_host=nil, local_port=nil) # :yield: socket
  last_error = nil
  ret = nil

  local_addr_list = nil
  if local_host != nil || local_port != nil
    local_addr_list = Addrinfo.getaddrinfo(local_host, local_port, nil, :STREAM, nil)
  end

  Addrinfo.foreach(host, port, nil, :STREAM) {|ai|
    if local_addr_list
      local_addr = local_addr_list.find {|local_ai| local_ai.afamily == ai.afamily }
      next if !local_addr
    else
      local_addr = nil
    end
    begin
      sock = local_addr ? ai.connect_from(local_addr) : ai.connect
    rescue SystemCallError
      last_error = $!
      next
    end
    ret = sock
    break
  }
  if !ret
    if last_error
      raise last_error
    else
      raise SocketError, "no appropriate local address"
    end
  end
  if block_given?
    begin
      yield ret
    ensure
      ret.close if !ret.closed?
    end
  else
    ret
  end
end

creates a TCP/IP server on port and calls the block for each connection accepted. The block is called with a socket and a client_address as an Addrinfo object.

If host is specified, it is used with port to determine the server addresses.

The socket is not closed when the block returns. So application should close it explicitly.

This method calls the block sequentially. It means that the next connection is not accepted until the block returns. So concurrent mechanism, thread for example, should be used to service multiple clients at a time.

Note that Addrinfo.getaddrinfo is used to determine the server socket addresses. When Addrinfo.getaddrinfo returns two or more addresses, IPv4 and IPv6 address for example, all of them are used. ::tcp_server_loop succeeds if one socket can be used at least.

# Sequential echo server.
# It services only one client at a time.
Socket.tcp_server_loop(16807) {|sock, client_addrinfo|
  begin
    IO.copy_stream(sock, sock)
  ensure
    sock.close
  end
}

# Threaded echo server
# It services multiple clients at a time.
# Note that it may accept connections too much.
Socket.tcp_server_loop(16807) {|sock, client_addrinfo|
  Thread.new {
    begin
      IO.copy_stream(sock, sock)
    ensure
      sock.close
    end
  }
}

# File rake/lib/socket.rb, line 466
def self.tcp_server_loop(host=nil, port, &b) # :yield: socket, client_addrinfo
  tcp_server_sockets(host, port) {|sockets|
    accept_loop(sockets, &b)
  }
end

creates TCP/IP server sockets for host and port. host is optional.

If no block given, it returns an array of listening sockets.

If a block is given, the block is called with the sockets. The value of the block is returned. The socket is closed when this method returns.

If port is 0, actual port number is choosen dynamically. However all sockets in the result has same port number.

# tcp_server_sockets returns two sockets.
sockets = Socket.tcp_server_sockets(1296)
p sockets #=> [#<Socket:fd 3>, #<Socket:fd 4>]

# The sockets contains IPv6 and IPv4 sockets.
sockets.each {|s| p s.local_address }
#=> #<Addrinfo: [::]:1296 TCP>
#   #<Addrinfo: 0.0.0.0:1296 TCP>

# IPv6 and IPv4 socket has same port number, 53114, even if it is choosen dynamically.
sockets = Socket.tcp_server_sockets(0)
sockets.each {|s| p s.local_address }
#=> #<Addrinfo: [::]:53114 TCP>
#   #<Addrinfo: 0.0.0.0:53114 TCP>

# The block is called with the sockets.
Socket.tcp_server_sockets(0) {|sockets|
  p sockets #=> [#<Socket:fd 3>, #<Socket:fd 4>]
}

# File rake/lib/socket.rb, line 364
def self.tcp_server_sockets(host=nil, port)
  if port == 0
    sockets = tcp_server_sockets_port0(host)
  else
    begin
      last_error = nil
      sockets = []
      Addrinfo.foreach(host, port, nil, :STREAM, nil, Socket::AI_PASSIVE) {|ai|
        begin
          s = ai.listen
        rescue SystemCallError
          last_error = $!
          next
        end
        sockets << s
      }
      if sockets.empty?
        raise last_error
      end
    ensure
      sockets.each {|s| s.close if !s.closed? } if $!
    end
  end
  if block_given?
    begin
      yield sockets
    ensure
      sockets.each {|s| s.close if !s.closed? }
    end
  else
    sockets
  end
end

creates a UDP/IP server on port and calls the block for each message arrived. The block is called with the message and its source information.

This method allocates sockets internally using port. If host is specified, it is used conjunction with port to determine the server addresses.

The msg is a string.

The msg_src is a Socket::UDPSource object. It is used for reply.

# UDP/IP echo server.
Socket.udp_server_loop(9261) {|msg, msg_src|
  msg_src.reply msg
}

# File rake/lib/socket.rb, line 638
def self.udp_server_loop(host=nil, port, &b) # :yield: message, message_source
  udp_server_sockets(host, port) {|sockets|
    udp_server_loop_on(sockets, &b)
  }
end

Run UDP/IP server loop on the given sockets.

The return value of ::udp_server_sockets is appropriate for the argument.

It calls the block for each message received.

# File rake/lib/socket.rb, line 611
def self.udp_server_loop_on(sockets, &b) # :yield: msg, msg_src
  loop {
    readable, _, _ = IO.select(sockets)
    udp_server_recv(readable, &b)
  }
end

Receive UDP/IP packets from the given sockets. For each packet received, the block is called.

The block receives msg and msg_src. msg is a string which is the payload of the received packet. msg_src is a Socket::UDPSource object which is used for reply.

::udp_server_loop can be implemented using this method as follows.

udp_server_sockets(host, port) {|sockets|
  loop {
    readable, _, _ = IO.select(sockets)
    udp_server_recv(readable) {|msg, msg_src| ... }
  }
}

# File rake/lib/socket.rb, line 581
def self.udp_server_recv(sockets)
  sockets.each {|r|
    begin
      msg, sender_addrinfo, _, *controls = r.recvmsg_nonblock
    rescue IO::WaitReadable
      next
    end
    ai = r.local_address
    if ai.ipv6? and pktinfo = controls.find {|c| c.cmsg_is?(:IPV6, :PKTINFO) }
      ai = Addrinfo.udp(pktinfo.ipv6_pktinfo_addr.ip_address, ai.ip_port)
      yield msg, UDPSource.new(sender_addrinfo, ai) {|reply_msg|
        r.sendmsg reply_msg, 0, sender_addrinfo, pktinfo
      }
    else
      yield msg, UDPSource.new(sender_addrinfo, ai) {|reply_msg|
        r.send reply_msg, 0, sender_addrinfo
      }
    end
  }
end

Creates UDP/IP sockets for a UDP server.

If no block given, it returns an array of sockets.

If a block is given, the block is called with the sockets. The value of the block is returned. The sockets are closed when this method returns.

If port is zero, some port is choosen. But the choosen port is used for the all sockets.

# UDP/IP echo server
Socket.udp_server_sockets(0) {|sockets|
  p sockets.first.local_address.ip_port     #=> 32963
  Socket.udp_server_loop_on(sockets) {|msg, msg_src|
    msg_src.reply msg
  }
}

# File rake/lib/socket.rb, line 494
def self.udp_server_sockets(host=nil, port)
  last_error = nil
  sockets = []

  ipv6_recvpktinfo = nil
  if defined? Socket::AncillaryData
    if defined? Socket::IPV6_RECVPKTINFO # RFC 3542
      ipv6_recvpktinfo = Socket::IPV6_RECVPKTINFO
    elsif defined? Socket::IPV6_PKTINFO # RFC 2292
      ipv6_recvpktinfo = Socket::IPV6_PKTINFO
    end
  end

  local_addrs = Socket.ip_address_list

  ip_list = []
  Addrinfo.foreach(host, port, nil, :DGRAM, nil, Socket::AI_PASSIVE) {|ai|
    if ai.ipv4? && ai.ip_address == "0.0.0.0"
      local_addrs.each {|a|
        next if !a.ipv4?
        ip_list << Addrinfo.new(a.to_sockaddr, :INET, :DGRAM, 0);
      }
    elsif ai.ipv6? && ai.ip_address == "::" && !ipv6_recvpktinfo
      local_addrs.each {|a|
        next if !a.ipv6?
        ip_list << Addrinfo.new(a.to_sockaddr, :INET6, :DGRAM, 0);
      }
    else
      ip_list << ai
    end
  }

  if port == 0
    sockets = ip_sockets_port0(ip_list, false)
  else
    ip_list.each {|ip|
      ai = Addrinfo.udp(ip.ip_address, port)
      begin
        s = ai.bind
      rescue SystemCallError
        last_error = $!
        next
      end
      sockets << s
    }
    if sockets.empty?
      raise last_error
    end
  end

  sockets.each {|s|
    ai = s.local_address
    if ipv6_recvpktinfo && ai.ipv6? && ai.ip_address == "::"
      s.setsockopt(:IPV6, ipv6_recvpktinfo, 1)
    end
  }

  if block_given?
    begin
      yield sockets
    ensure
      sockets.each {|s| s.close if !s.closed? } if sockets
    end
  else
    sockets
  end
end

creates a new socket connected to path using UNIX socket socket.

If a block is given, the block is called with the socket. The value of the block is returned. The socket is closed when this method returns.

If no block is given, the socket is returned.

# talk to /tmp/sock socket.
Socket.unix("/tmp/sock") {|sock|
  t = Thread.new { IO.copy_stream(sock, STDOUT) }
  IO.copy_stream(STDIN, sock)
  t.join
}

# File rake/lib/socket.rb, line 688
def self.unix(path) # :yield: socket
  addr = Addrinfo.unix(path)
  sock = addr.connect
  if block_given?
    begin
      yield sock
    ensure
      sock.close if !sock.closed?
    end
  else
    sock
  end
end

creates a UNIX socket server on path. It calls the block for each socket accepted.

If host is specified, it is used with port to determine the server ports.

The socket is not closed when the block returns. So application should close it.

This method deletes the socket file pointed by path at first if the file is a socket file and it is owned by the user of the application. This is safe only if the directory of path is not changed by a malicious user. So don’t use /tmp/malicious-users-directory/socket. Note that /tmp/socket and /tmp/your-private-directory/socket is safe assuming that /tmp has sticky bit.

# Sequential echo server.
# It services only one client at a time.
Socket.unix_server_loop("/tmp/sock") {|sock, client_addrinfo|
  begin
    IO.copy_stream(sock, sock)
  ensure
    sock.close
  end
}

# File rake/lib/socket.rb, line 763
def self.unix_server_loop(path, &b) # :yield: socket, client_addrinfo
  unix_server_socket(path) {|serv|
    accept_loop(serv, &b)
  }
end

creates a UNIX server socket on path

If no block given, it returns a listening socket.

If a block is given, it is called with the socket and the block value is returned. When the block exits, the socket is closed and the socket file is removed.

socket = Socket.unix_server_socket("/tmp/s")
p socket                  #=> #<Socket:fd 3>
p socket.local_address    #=> #<Addrinfo: /tmp/s SOCK_STREAM>

Socket.unix_server_socket("/tmp/sock") {|s|
  p s                     #=> #<Socket:fd 3>
  p s.local_address       #=> # #<Addrinfo: /tmp/sock SOCK_STREAM>
}

# File rake/lib/socket.rb, line 718
def self.unix_server_socket(path)
  begin
    st = File.lstat(path)
  rescue Errno::ENOENT
  end
  if st && st.socket? && st.owned?
    File.unlink path
  end
  s = Addrinfo.unix(path).listen
  if block_given?
    begin
      yield s
    ensure
      s.close if !s.closed?
      File.unlink path
    end
  else
    s
  end
end

enable the socket option IPV6_V6ONLY if IPV6_V6ONLY is available.

# File rake/lib/socket.rb, line 213
def ipv6only!
  if defined? Socket::IPV6_V6ONLY
    self.setsockopt(:IPV6, :V6ONLY, 1)
  end
end