class Socket::Option - Documentation for Ruby 4.0
Description: class Socket::Option: Option represents a socket option used by BasicSocket#getsockopt and BasicSocket#setsockopt. A socket option contains the socket #family, protocol #le
Keywords: ruby,class,Socket::Option

🔍

No recent searches

# class Socket::Option

`Socket::Option` represents a socket option used by `BasicSocket#getsockopt` and `BasicSocket#setsockopt`. A socket option contains the socket `family`, protocol `level`, option name `optname` and option value `data`.

### Public Class Methods

Socket::Option.bool(family, level, optname, bool) → sockopt
Source

    static VALUE
    sockopt_s_bool(VALUE klass, VALUE vfamily, VALUE vlevel, VALUE voptname, VALUE vbool)
    {
        int family = rsock_family_arg(vfamily);
        int level = rsock_level_arg(family, vlevel);
        int optname = rsock_optname_arg(family, level, voptname);
        int i = RTEST(vbool) ? 1 : 0;
        return rsock_sockopt_new(family, level, optname, pack_var(i));
    }

Creates a new `Socket::Option` object which contains boolean as data. Actually 0 or 1 as int is used.

    require 'socket'

    p Socket::Option.bool(:INET, :SOCKET, :KEEPALIVE, true)
    #=> #<Socket::Option: INET SOCKET KEEPALIVE 1>

    p Socket::Option.bool(:INET, :SOCKET, :KEEPALIVE, false)
    #=> #<Socket::Option: AF_INET SOCKET KEEPALIVE 0>

Socket::Option.byte(family, level, optname, integer) → sockopt
Source

    static VALUE
    sockopt_s_byte(VALUE klass, VALUE vfamily, VALUE vlevel, VALUE voptname, VALUE vint)
    {
        int family = rsock_family_arg(vfamily);
        int level = rsock_level_arg(family, vlevel);
        int optname = rsock_optname_arg(family, level, voptname);
        return rsock_sockopt_new(family, level, optname, sockopt_pack_byte(vint));
    }

Creates a new `Socket::Option` object which contains a byte as data.

    p Socket::Option.byte(:INET, :SOCKET, :KEEPALIVE, 1)
    #=> #<Socket::Option: INET SOCKET KEEPALIVE 1>

Socket::Option.int(family, level, optname, integer) → sockopt
Source

    static VALUE
    sockopt_s_int(VALUE klass, VALUE vfamily, VALUE vlevel, VALUE voptname, VALUE vint)
    {
        int family = rsock_family_arg(vfamily);
        int level = rsock_level_arg(family, vlevel);
        int optname = rsock_optname_arg(family, level, voptname);
        return rsock_sockopt_new(family, level, optname, sockopt_pack_int(vint));
    }

Creates a new `Socket::Option` object which contains an int as data.

The size and endian is dependent on the platform.

    p Socket::Option.int(:INET, :SOCKET, :KEEPALIVE, 1)
    #=> #<Socket::Option: INET SOCKET KEEPALIVE 1>

Socket::Option.ipv4_multicast_loop(integer) → sockopt
Source

    static VALUE
    sockopt_s_ipv4_multicast_loop(VALUE klass, VALUE value)
    {

    #if defined(IPPROTO_IP) && defined(IP_MULTICAST_LOOP)
        VALUE o = XCAT(sockopt_pack_,TYPE_IP_MULTICAST_LOOP)(value);
        return rsock_sockopt_new(AF_INET, IPPROTO_IP, IP_MULTICAST_LOOP, o);
    #else
    # error IPPROTO_IP or IP_MULTICAST_LOOP is not implemented
    #endif
    }

Creates a new `Socket::Option` object for IP_MULTICAST_LOOP.

The size is dependent on the platform.

    sockopt = Socket::Option.int(:INET, :IPPROTO_IP, :IP_MULTICAST_LOOP, 1)
    p sockopt.int => 1

    p Socket::Option.ipv4_multicast_loop(10)
    #=> #<Socket::Option: INET IP MULTICAST_LOOP 10>

Socket::Option.ipv4_multicast_ttl(integer) → sockopt
Source

    static VALUE
    sockopt_s_ipv4_multicast_ttl(VALUE klass, VALUE value)
    {
    #if defined(IPPROTO_IP) && defined(IP_MULTICAST_TTL)
        VALUE o = XCAT(sockopt_pack_,TYPE_IP_MULTICAST_TTL)(value);
        return rsock_sockopt_new(AF_INET, IPPROTO_IP, IP_MULTICAST_TTL, o);
    #else
    # error IPPROTO_IP or IP_MULTICAST_TTL is not implemented
    #endif
    }

Creates a new `Socket::Option` object for IP_MULTICAST_TTL.

The size is dependent on the platform.

    p Socket::Option.ipv4_multicast_ttl(10)
    #=> #<Socket::Option: INET IP MULTICAST_TTL 10>

Socket::Option.linger(onoff, secs) → sockopt
Source

    static VALUE
    sockopt_s_linger(VALUE klass, VALUE vonoff, VALUE vsecs)
    {
        VALUE tmp;
        struct linger l;
        memset(&l, 0, sizeof(l));
        if (!NIL_P(tmp = rb_check_to_integer(vonoff, "to_int")))
            l.l_onoff = NUM2INT(tmp);
        else
            l.l_onoff = RTEST(vonoff) ? 1 : 0;
        l.l_linger = NUM2INT(vsecs);
        return rsock_sockopt_new(AF_UNSPEC, SOL_SOCKET, SO_LINGER, pack_var(l));
    }

Creates a new `Socket::Option` object for SOL_SOCKET/SO_LINGER.

onoff should be an integer or a boolean.

secs should be the number of seconds.

    p Socket::Option.linger(true, 10)
    #=> #<Socket::Option: UNSPEC SOCKET LINGER on 10sec>

Socket::Option.new(family, level, optname, data) → sockopt
Source

    static VALUE
    sockopt_initialize(VALUE self, VALUE vfamily, VALUE vlevel, VALUE voptname, VALUE data)
    {
        int family = rsock_family_arg(vfamily);
        int level = rsock_level_arg(family, vlevel);
        int optname = rsock_optname_arg(family, level, voptname);
        StringValue(data);
        rb_ivar_set(self, rb_intern("family"), INT2NUM(family));
        rb_ivar_set(self, rb_intern("level"), INT2NUM(level));
        rb_ivar_set(self, rb_intern("optname"), INT2NUM(optname));
        rb_ivar_set(self, rb_intern("data"), data);
        return self;
    }

Returns a new `Socket::Option` object.

    sockopt = Socket::Option.new(:INET, :SOCKET, :KEEPALIVE, [1].pack("i"))
    p sockopt #=> #<Socket::Option: INET SOCKET KEEPALIVE 1>

### Public Instance Methods

bool → true or false
Source

    static VALUE
    sockopt_bool(VALUE self)
    {
        int i;
        long len;
        VALUE data = sockopt_data(self);
        StringValue(data);
        len = RSTRING_LEN(data);
        if (len == 1) {
            return *RSTRING_PTR(data) == 0 ? Qfalse : Qtrue;
        }
        check_size(len, sizeof(int));
        memcpy((char*)&i, RSTRING_PTR(data), len);
        return i == 0 ? Qfalse : Qtrue;
    }

Returns the data in sockopt as an boolean value.

    sockopt = Socket::Option.int(:INET, :SOCKET, :KEEPALIVE, 1)
    p sockopt.bool => true

byte → integer
Source

    static VALUE
    sockopt_byte(VALUE self)
    {
        VALUE data = sockopt_data(self);
        StringValue(data);
        check_size(RSTRING_LEN(data), sizeof(char));
        return CHR2FIX(*RSTRING_PTR(data));
    }

Returns the data in sockopt as an byte.

    sockopt = Socket::Option.byte(:INET, :SOCKET, :KEEPALIVE, 1)
    p sockopt.byte => 1

data → string
Source

    static VALUE
    sockopt_data(VALUE self)
    {
        VALUE v = rb_attr_get(self, rb_intern("data"));
        StringValue(v);
        return v;
    }

returns the socket option data as a string.

    p Socket::Option.new(:INET6, :IPV6, :RECVPKTINFO, [1].pack("i!")).data
    #=> "\x01\x00\x00\x00"

Also aliased as: to_s
family → integer
Source

    static VALUE
    sockopt_family_m(VALUE self)
    {
        return rb_attr_get(self, rb_intern("family"));
    }

returns the socket family as an integer.

    p Socket::Option.new(:INET6, :IPV6, :RECVPKTINFO, [1].pack("i!")).family
    #=> 10

inspect → string
Source

    static VALUE
    sockopt_inspect(VALUE self)
    {
        int family = NUM2INT(sockopt_family_m(self));
        int level = NUM2INT(sockopt_level_m(self));
        int optname = NUM2INT(sockopt_optname_m(self));
        VALUE data = sockopt_data(self);
        VALUE v, ret;
        ID family_id, level_id, optname_id;
        int inspected;

        StringValue(data);

        ret = rb_sprintf("#<%s:", rb_obj_classname(self));

        family_id = rsock_intern_family_noprefix(family);
        if (family_id)
            rb_str_catf(ret, " %s", rb_id2name(family_id));
        else
            rb_str_catf(ret, " family:%d", family);

        if (level == SOL_SOCKET) {
            rb_str_cat2(ret, " SOCKET");

            optname_id = rsock_intern_so_optname(optname);
            if (optname_id)
                rb_str_catf(ret, " %s", rb_id2name(optname_id));
            else
                rb_str_catf(ret, " optname:%d", optname);
        }
    #ifdef HAVE_TYPE_STRUCT_SOCKADDR_UN
        else if (family == AF_UNIX) {
            rb_str_catf(ret, " level:%d", level);

            optname_id = rsock_intern_local_optname(optname);
            if (optname_id)
                rb_str_catf(ret, " %s", rb_id2name(optname_id));
            else
                rb_str_catf(ret, " optname:%d", optname);
        }
    #endif
        else if (IS_IP_FAMILY(family)) {
            level_id = rsock_intern_iplevel(level);
            if (level_id)
                rb_str_catf(ret, " %s", rb_id2name(level_id));
            else
                rb_str_catf(ret, " level:%d", level);

            v = optname_to_sym(level, optname);
            if (SYMBOL_P(v))
                rb_str_catf(ret, " %"PRIsVALUE, rb_sym2str(v));
            else
                rb_str_catf(ret, " optname:%d", optname);
        }
        else {
            rb_str_catf(ret, " level:%d", level);
            rb_str_catf(ret, " optname:%d", optname);
        }

        inspected = 0;

        if (level == SOL_SOCKET)
            family = AF_UNSPEC;
        switch (family) {
          case AF_UNSPEC:
            switch (level) {
              case SOL_SOCKET:
                switch (optname) {
    #            if defined(SO_DEBUG) /* POSIX */
                  case SO_DEBUG: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_ERROR) /* POSIX */
                  case SO_ERROR: inspected = inspect_errno(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_TYPE) /* POSIX */
                  case SO_TYPE: inspected = inspect_socktype(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_ACCEPTCONN) /* POSIX */
                  case SO_ACCEPTCONN: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_BROADCAST) /* POSIX */
                  case SO_BROADCAST: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_REUSEADDR) /* POSIX */
                  case SO_REUSEADDR: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_KEEPALIVE) /* POSIX */
                  case SO_KEEPALIVE: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_OOBINLINE) /* POSIX */
                  case SO_OOBINLINE: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_SNDBUF) /* POSIX */
                  case SO_SNDBUF: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_RCVBUF) /* POSIX */
                  case SO_RCVBUF: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_DONTROUTE) /* POSIX */
                  case SO_DONTROUTE: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_RCVLOWAT) /* POSIX */
                  case SO_RCVLOWAT: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_SNDLOWAT) /* POSIX */
                  case SO_SNDLOWAT: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_LINGER) /* POSIX */
                  case SO_LINGER: inspected = inspect_linger(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_RCVTIMEO) /* POSIX */
                  case SO_RCVTIMEO: inspected = inspect_timeval_as_interval(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_SNDTIMEO) /* POSIX */
                  case SO_SNDTIMEO: inspected = inspect_timeval_as_interval(level, optname, data, ret); break;
    #            endif
    #            if defined(SO_PEERCRED) /* GNU/Linux, OpenBSD */
                  case SO_PEERCRED: inspected = inspect_peercred(level, optname, data, ret); break;
    #            endif
                }
                break;
            }
            break;

          case AF_INET:
    #ifdef INET6
          case AF_INET6:
    #endif
            switch (level) {
    #        if defined(IPPROTO_IP)
              case IPPROTO_IP:
                switch (optname) {
    #            if defined(IP_MULTICAST_IF) && defined(HAVE_TYPE_STRUCT_IP_MREQN) /* 4.4BSD, GNU/Linux */
                  case IP_MULTICAST_IF: inspected = inspect_ipv4_multicast_if(level, optname, data, ret); break;
    #            endif
    #            if defined(IP_ADD_MEMBERSHIP) /* 4.4BSD, GNU/Linux */
                  case IP_ADD_MEMBERSHIP: inspected = inspect_ipv4_add_drop_membership(level, optname, data, ret); break;
    #            endif
    #            if defined(IP_DROP_MEMBERSHIP) /* 4.4BSD, GNU/Linux */
                  case IP_DROP_MEMBERSHIP: inspected = inspect_ipv4_add_drop_membership(level, optname, data, ret); break;
    #            endif
    #            if defined(IP_MULTICAST_LOOP) /* 4.4BSD, GNU/Linux */
                  case IP_MULTICAST_LOOP: inspected = inspect_ipv4_multicast_loop(level, optname, data, ret); break;
    #            endif
    #            if defined(IP_MULTICAST_TTL) /* 4.4BSD, GNU/Linux */
                  case IP_MULTICAST_TTL: inspected = inspect_ipv4_multicast_ttl(level, optname, data, ret); break;
    #            endif
                }
                break;
    #        endif

    #        if defined(IPPROTO_IPV6)
              case IPPROTO_IPV6:
                switch (optname) {
    #            if defined(IPV6_MULTICAST_HOPS) /* POSIX */
                  case IPV6_MULTICAST_HOPS: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(IPV6_MULTICAST_IF) /* POSIX */
                  case IPV6_MULTICAST_IF: inspected = inspect_ipv6_multicast_if(level, optname, data, ret); break;
    #            endif
    #            if defined(IPV6_MULTICAST_LOOP) /* POSIX */
                  case IPV6_MULTICAST_LOOP: inspected = inspect_uint(level, optname, data, ret); break;
    #            endif
    #            if defined(IPV6_JOIN_GROUP) /* POSIX */
                  case IPV6_JOIN_GROUP: inspected = inspect_ipv6_mreq(level, optname, data, ret); break;
    #            endif
    #            if defined(IPV6_LEAVE_GROUP) /* POSIX */
                  case IPV6_LEAVE_GROUP: inspected = inspect_ipv6_mreq(level, optname, data, ret); break;
    #            endif
    #            if defined(IPV6_UNICAST_HOPS) /* POSIX */
                  case IPV6_UNICAST_HOPS: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(IPV6_V6ONLY) /* POSIX */
                  case IPV6_V6ONLY: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
                }
                break;
    #        endif

    #        if defined(IPPROTO_TCP)
              case IPPROTO_TCP:
                switch (optname) {
    #            if defined(TCP_NODELAY) /* POSIX */
                  case TCP_NODELAY: inspected = inspect_int(level, optname, data, ret); break;
    #            endif
    #            if defined(TCP_INFO) && defined(HAVE_TYPE_STRUCT_TCP_INFO) /* Linux, FreeBSD */
                  case TCP_INFO: inspected = inspect_tcp_info(level, optname, data, ret); break;
    #            endif
                }
                break;
    #        endif
            }
            break;

    #ifdef HAVE_TYPE_STRUCT_SOCKADDR_UN
          case AF_UNIX:
            switch (level) {
              case 0:
                switch (optname) {
    #            if defined(LOCAL_PEERCRED)
                  case LOCAL_PEERCRED: inspected = inspect_local_peercred(level, optname, data, ret); break;
    #            endif
                }
                break;
            }
            break;
    #endif
        }

        if (!inspected) {
            rb_str_cat2(ret, " ");
            rb_str_append(ret, rb_str_dump(data));
        }

        rb_str_cat2(ret, ">");

        return ret;
    }

Returns a string which shows sockopt in human-readable form.

    p Socket::Option.new(:INET, :SOCKET, :KEEPALIVE, [1].pack("i")).inspect
    #=> "#<Socket::Option: INET SOCKET KEEPALIVE 1>"

int → integer
Source

    static VALUE
    sockopt_int(VALUE self)
    {
        int i;
        VALUE data = sockopt_data(self);
        StringValue(data);
        check_size(RSTRING_LEN(data), sizeof(int));
        memcpy((char*)&i, RSTRING_PTR(data), sizeof(int));
        return INT2NUM(i);
    }

Returns the data in sockopt as an int.

The size and endian is dependent on the platform.

    sockopt = Socket::Option.int(:INET, :SOCKET, :KEEPALIVE, 1)
    p sockopt.int => 1

ipv4_multicast_loop → integer
Source

    static VALUE
    sockopt_ipv4_multicast_loop(VALUE self)
    {
        int family = NUM2INT(sockopt_family_m(self));
        int level = sockopt_level(self);
        int optname = sockopt_optname(self);

    #if defined(IPPROTO_IP) && defined(IP_MULTICAST_LOOP)
        if (family == AF_INET && level == IPPROTO_IP && optname == IP_MULTICAST_LOOP) {
            return XCAT(sockopt_,TYPE_IP_MULTICAST_LOOP)(self);
        }
    #endif
        rb_raise(rb_eTypeError, "ipv4_multicast_loop socket option expected");
        UNREACHABLE_RETURN(Qnil);
    }

Returns the `ipv4_multicast_loop` data in sockopt as an integer.

    sockopt = Socket::Option.ipv4_multicast_loop(10)
    p sockopt.ipv4_multicast_loop => 10

ipv4_multicast_ttl → integer
Source

    static VALUE
    sockopt_ipv4_multicast_ttl(VALUE self)
    {
        int family = NUM2INT(sockopt_family_m(self));
        int level = sockopt_level(self);
        int optname = sockopt_optname(self);

    #if defined(IPPROTO_IP) && defined(IP_MULTICAST_TTL)
        if (family == AF_INET && level == IPPROTO_IP && optname == IP_MULTICAST_TTL) {
            return XCAT(sockopt_,TYPE_IP_MULTICAST_TTL)(self);
        }
    #endif
        rb_raise(rb_eTypeError, "ipv4_multicast_ttl socket option expected");
        UNREACHABLE_RETURN(Qnil);
    }

Returns the `ipv4_multicast_ttl` data in sockopt as an integer.

    sockopt = Socket::Option.ipv4_multicast_ttl(10)
    p sockopt.ipv4_multicast_ttl => 10

level → integer
Source

    static VALUE
    sockopt_level_m(VALUE self)
    {
        return INT2NUM(sockopt_level(self));
    }

returns the socket level as an integer.

    p Socket::Option.new(:INET6, :IPV6, :RECVPKTINFO, [1].pack("i!")).level
    #=> 41

linger → [bool, seconds]
Source

    static VALUE
    sockopt_linger(VALUE self)
    {
        int level = sockopt_level(self);
        int optname = sockopt_optname(self);
        VALUE data = sockopt_data(self);
        struct linger l;
        VALUE vonoff, vsecs;

        if (level != SOL_SOCKET || optname != SO_LINGER)
            rb_raise(rb_eTypeError, "linger socket option expected");
        check_size(RSTRING_LEN(data), sizeof(struct linger));
        memcpy((char*)&l, RSTRING_PTR(data), sizeof(struct linger));
        switch (l.l_onoff) {
          case 0: vonoff = Qfalse; break;
          case 1: vonoff = Qtrue; break;
          default: vonoff = INT2NUM(l.l_onoff); break;
        }
        vsecs = INT2NUM(l.l_linger);
        return rb_assoc_new(vonoff, vsecs);
    }

Returns the linger data in sockopt as a pair of boolean and integer.

    sockopt = Socket::Option.linger(true, 10)
    p sockopt.linger => [true, 10]

optname → integer
Source

    static VALUE
    sockopt_optname_m(VALUE self)
    {
        return INT2NUM(sockopt_optname(self));
    }

returns the socket option name as an integer.

    p Socket::Option.new(:INET6, :IPV6, :RECVPKTINFO, [1].pack("i!")).optname
    #=> 2

to_s → string

returns the socket option data as a string.

    p Socket::Option.new(:INET6, :IPV6, :RECVPKTINFO, [1].pack("i!")).data
    #=> "\x01\x00\x00\x00"

Alias for: data
unpack(template) → array
Source

    static VALUE
    sockopt_unpack(VALUE self, VALUE template)
    {
        return rb_funcall(sockopt_data(self), rb_intern("unpack"), 1, template);
    }

Calls `String#unpack` on sockopt.data.

    sockopt = Socket::Option.new(:INET, :SOCKET, :KEEPALIVE, [1].pack("i"))
    p sockopt.unpack("i")      #=> [1]
    p sockopt.data.unpack("i") #=> [1]