123456789_123456789_123456789_123456789_123456789_

Class: UDPSocket

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain:
self, ::IPSocket, ::BasicSocket, ::IO
Instance Chain:
self, ::IPSocket, ::BasicSocket, ::IO
Inherits: IPSocket
Defined in: ext/socket/udpsocket.c,
ext/socket/lib/socket.rb

Overview

UDPSocket represents a UDP/IP socket.

Class Attribute Summary

::BasicSocket - Inherited

.do_not_reverse_lookup

Gets the global do_not_reverse_lookup flag.
.do_not_reverse_lookup=

Sets the global do_not_reverse_lookup flag.

Class Method Summary

::IPSocket - Inherited

.getaddress

Lookups the IP address of host.

::BasicSocket - Inherited

.for_fd

Returns a socket object which contains the file descriptor, fd.

Instance Attribute Summary

::BasicSocket - Inherited

#do_not_reverse_lookup

Gets the do_not_reverse_lookup flag of basicsocket.
#do_not_reverse_lookup=

Sets the do_not_reverse_lookup flag of basicsocket.

Instance Method Summary

::IPSocket - Inherited

#addr

Returns the local address as an array which contains address_family, port, hostname and numeric_address.
#inspect

Return a string describing this ::IPSocket object.
#peeraddr

Returns the remote address as an array which contains address_family, port, hostname and numeric_address.
#recvfrom

Receives a message and return the message as a string and an address which the message come from.

::BasicSocket - Inherited

#close_read

Disallows further read using shutdown system call.
#close_write

Disallows further write using shutdown system call.
#connect_address

Returns an address of the socket suitable for connect in the local machine.
#getpeereid

Returns the user and group on the peer of the UNIX socket.
#getpeername

Returns the remote address of the socket as a sockaddr string.
#getsockname

Returns the local address of the socket as a sockaddr string.
#getsockopt

Gets a socket option.
#local_address

Returns an ::Addrinfo object for local address obtained by getsockname.
#recv

Receives a message.
#recv_nonblock

Receives up to maxlen bytes from socket using recvfrom(2) after O_NONBLOCK is set for the underlying file descriptor.
#recvmsg

recvmsg receives a message using recvmsg(2) system call in blocking manner.
#recvmsg_nonblock

recvmsg receives a message using recvmsg(2) system call in non-blocking manner.
#remote_address

Returns an ::Addrinfo object for remote address obtained by getpeername.
#send

send mesg via basicsocket.
#sendmsg

sendmsg sends a message using sendmsg(2) system call in blocking manner.
#sendmsg_nonblock

sendmsg_nonblock sends a message using sendmsg(2) system call in non-blocking manner.
#setsockopt

Sets a socket option.
#shutdown

Calls shutdown(2) system call.
#__recvmsg, #__recvmsg_nonblock, #__sendmsg, #__sendmsg_nonblock, #read_nonblock, #write_nonblock, #__read_nonblock, #__recv_nonblock, #__write_nonblock

Constructor Details

.new([address_family]) ⇒ socket

Creates a new UDPSocket object.

address_family should be an integer, a string or a symbol: Socket::AF_INET, “AF_INET”, :INET, etc.

require 'socket'

UDPSocket.new                   #=> #<UDPSocket:fd 3>
UDPSocket.new(Socket::AF_INET6) #=> #<UDPSocket:fd 4>
[ GitHub ] 

  


# File 'ext/socket/udpsocket.c', line 28



static VALUE
udp_init(int argc, VALUE *argv, VALUE sock)
{
    VALUE arg;
    int family = AF_INET;
    int fd;

    if (rb_scan_args(argc, argv, "01", &arg) == 1) {
        family = rsock_family_arg(arg);
    }
    fd = rsock_socket(family, SOCK_DGRAM, 0);
    if (fd < 0) {
        rb_sys_fail("socket(2) - udp");
    }

    return rsock_init_sock(sock, fd);
}


  







Instance Method Details



  

    #__recvfrom_nonblock(len, flg, str, ex)   (private)
  

  

    This method is for internal use only.
  

  [ GitHub ]


  

  


# File 'ext/socket/udpsocket.c', line 223



static VALUE
udp_recvfrom_nonblock(VALUE sock, VALUE len, VALUE flg, VALUE str, VALUE ex)
{
    return rsock_s_recvfrom_nonblock(sock, len, flg, str, ex, RECV_IP);
}


  








  

    #bind(host, port) # = > 0))    



  

    

Binds udpsocket to host:port.



u1 = UDPSocket.new
u1.bind("127.0.0.1", 4913)
u1.send "message-to-self", 0, "127.0.0.1", 4913
p u1.recvfrom(10) #=> ["message-to", ["AF_INET", 4913, "localhost", "127.0.0.1"]]


  



  [ GitHub ]


  

  


# File 'ext/socket/udpsocket.c', line 127



static VALUE
udp_bind(VALUE self, VALUE host, VALUE port)
{
    struct udp_arg arg = {.io = self};

    arg.res = rsock_addrinfo(host, port, rsock_fd_family(rb_io_descriptor(self)), SOCK_DGRAM, 0);

    VALUE result = rb_ensure(udp_bind_internal, (VALUE)&arg, rsock_freeaddrinfo, (VALUE)arg.res);
    if (!result) {
        rsock_sys_fail_host_port("bind(2)", host, port);
    }

    return INT2FIX(0);
}


  








  

    #connect(host, port)  ⇒ 0   



  

    

Connects udpsocket to host:port.



This makes possible to send without destination address.



u1 = UDPSocket.new
u1.bind("127.0.0.1", 4913)
u2 = UDPSocket.new
u2.connect("127.0.0.1", 4913)
u2.send "uuuu", 0
p u1.recvfrom(10) #=> ["uuuu", ["AF_INET", 33230, "localhost", "127.0.0.1"]]


  



  [ GitHub ]


  

  


# File 'ext/socket/udpsocket.c', line 82



static VALUE
udp_connect(VALUE self, VALUE host, VALUE port)
{
    struct udp_arg arg = {.io = self};

    arg.res = rsock_addrinfo(host, port, rsock_fd_family(rb_io_descriptor(self)), SOCK_DGRAM, 0);

    int result = (int)rb_ensure(udp_connect_internal, (VALUE)&arg, rsock_freeaddrinfo, (VALUE)arg.res);
    if (!result) {
        rsock_sys_fail_host_port("connect(2)", host, port);
    }

    return INT2FIX(0);
}


  








  

    #recvfrom_nonblock(maxlen [, flags[, outbuf [, options]]])  ⇒ Array, sender_inet_addr   



  

    

Receives up to maxlen bytes from udpsocket 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_inet_addr, is an array to represent the sender address.



When recvfrom(2) returns 0, Socket#recv_nonblock returns nil. In most cases it means the connection was closed, but it may also mean an empty packet was received, as the underlying API makes it impossible to distinguish these two cases.



Parameters


  • 

    maxlen - the number of bytes to receive from the socket
    

  • 

    flags - zero or more of the MSG_ options
    

  • 

    outbuf - destination String buffer
    

  • 

    options - keyword hash, supporting exception: false
    




Example



require 'socket'
s1 = UDPSocket.new
s1.bind("127.0.0.1", 0)
s2 = UDPSocket.new
s2.bind("127.0.0.1", 0)
s2.connect(*s1.addr.values_at(3,1))
s1.connect(*s2.addr.values_at(3,1))
s1.send "aaa", 0
begin # emulate blocking recvfrom
  p s2.recvfrom_nonblock(10)  #=> ["aaa", ["AF_INET", 33302, "localhost.localdomain", "127.0.0.1"]]
rescue IO::WaitReadable
  IO.select([s2])
  retry
end



Refer to Socket#recvfrom for the exceptions that may be thrown if the call to recvfrom_nonblock fails.



recvfrom_nonblock may raise any error corresponding to recvfrom(2) failure, including Errno::EWOULDBLOCK.



If the exception is Errno::EWOULDBLOCK or Errno::EAGAIN, it is extended by IO::WaitReadable. So IO::WaitReadable can be used to rescue the exceptions for retrying recvfrom_nonblock.



By specifying a keyword argument exception to false, you can indicate that recvfrom_nonblock should not raise an IO::WaitReadable exception, but return the symbol :wait_readable instead.



See



  



  [ GitHub ]


  

  


# File 'ext/socket/lib/socket.rb', line 1709



def recvfrom_nonblock(len, flag = 0, outbuf = nil, exception: true)
  __recvfrom_nonblock(len, flag, outbuf, exception)
end


  








  

    

      #send(mesg, flags, host, port)  ⇒ numbytes_sent 
      #send(mesg, flags, sockaddr_to)  ⇒ numbytes_sent 
      #send(mesg, flags)  ⇒ numbytes_sent 
    

  



  

    

Sends mesg via udpsocket.



flags should be a bitwise OR of Socket::MSG_* constants.



u1 = UDPSocket.new
u1.bind("127.0.0.1", 4913)

u2 = UDPSocket.new
u2.send "hi", 0, "127.0.0.1", 4913

mesg, addr = u1.recvfrom(10)
u1.send mesg, 0, addr[3], addr[1]

p u2.recv(100) #=> "hi"


  





  


  [ GitHub ]


  

  


# File 'ext/socket/udpsocket.c', line 199



static VALUE
udp_send(int argc, VALUE *argv, VALUE sock)
{
    VALUE flags, host, port;
    struct udp_send_arg arg;
    VALUE ret;

    if (argc == 2 || argc == 3) {
        return rsock_bsock_send(argc, argv, sock);
    }
    rb_scan_args(argc, argv, "4", &arg.sarg.mesg, &flags, &host, &port);

    StringValue(arg.sarg.mesg);
    GetOpenFile(sock, arg.fptr);
    arg.sarg.fd = arg.fptr->fd;
    arg.sarg.flags = NUM2INT(flags);
    arg.res = rsock_addrinfo(host, port, rsock_fd_family(arg.fptr->fd), SOCK_DGRAM, 0);
    ret = rb_ensure(udp_send_internal, (VALUE)&arg,
                    rsock_freeaddrinfo, (VALUE)arg.res);
    if (!ret) rsock_sys_fail_host_port("sendto(2)", host, port);
    return ret;
}