EVOLUTION-MANAGER

Edit File: getaddrinfo-c.yaml

--- !ruby/object:RI::MethodDescription 
aliases: []

block_params: 
comment: 
- !ruby/struct:SM::Flow::P 
  body: Return address information for <tt>host</tt> and <tt>port</tt>. The remaining arguments are hints that limit the address information returned.
- !ruby/struct:SM::Flow::P 
  body: This method corresponds closely to the POSIX.1g getaddrinfo() definition.
- !ruby/struct:SM::Flow::H 
  level: 3
  text: Parameters
- !ruby/object:SM::Flow::LIST 
  contents: 
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: <tt>host</tt> is a host name or an address string (dotted decimal for IPv4, or a hex string for IPv6) for which to return information. A nil is also allowed, its meaning depends on <tt>flags</tt>, see below.
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: <tt>service</tt> is a service name (&quot;http&quot;, &quot;ssh&quot;, ...), or a port number (80, 22, ...), see Socket.getservbyname for more information. A nil is also allowed, meaning zero.
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: <tt>family</tt> limits the output to a specific address family, one of the Socket::AF_* constants. Socket::AF_INET (IPv4) and Socket::AF_INET6 (IPv6) are the most commonly used families. You will usually pass either nil or Socket::AF_UNSPEC, allowing the IPv6 information to be returned first if <tt>host</tt> is reachable via IPv6, and IPv4 information otherwise. The two strings &quot;AF_INET&quot; or &quot;AF_INET6&quot; are also allowed, they are converted to their respective Socket::AF_* constants.
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: <tt>socktype</tt> limits the output to a specific type of socket, one of the Socket::SOCK_* constants. Socket::SOCK_STREAM (for TCP) and Socket::SOCK_DGRAM (for UDP) are the most commonly used socket types. If nil, then information for all types of sockets supported by <tt>service</tt> will be returned. You will usually know what type of socket you intend to create, and should pass that socket type in.
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: <tt>protocol</tt> limits the output to a specific protocol numpber, one of the Socket::IPPROTO_* constants. It is usually implied by the socket type (Socket::SOCK_STREAM =&gt; Socket::IPPROTO_TCP, ...), if you pass other than nil you already know what this is for.
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: "<tt>flags</tt> is one of the Socket::AI_* constants. They mean:"
  - !ruby/object:SM::Flow::LIST 
    contents: 
    - !ruby/struct:SM::Flow::LI 
      label: "-"
      body: "Socket::AI_PASSIVE: when set, if <tt>host</tt> is nil the 'any' address will be returned, Socket::INADDR_ANY or 0 for IPv4, &quot;0::0&quot; or &quot;::&quot; for IPv6. This address is suitable for use by servers that will bind their socket and do a passive listen, thus the name of the flag. Otherwise the local or loopback address will be returned, this is &quot;127.0.0.1&quot; for IPv4 and &quot;::1' for IPv6."
    - !ruby/struct:SM::Flow::LI 
      label: "-"
      body: ...
    type: :BULLET
  type: :BULLET
- !ruby/struct:SM::Flow::H 
  level: 3
  text: Returns
- !ruby/struct:SM::Flow::P 
  body: "Returns an array of arrays, where each subarray contains:"
- !ruby/object:SM::Flow::LIST 
  contents: 
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: address family, a string like &quot;AF_INET&quot; or &quot;AF_INET6&quot;
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: port number, the port number for <tt>service</tt>
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: host name, either a canonical name for <tt>host</tt>, or it's address in presentation format if the address could not be looked up.
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: host IP, the address of <tt>host</tt> in presentation format
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: address family, as a numeric value (one of the Socket::AF_* constants).
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: socket type, as a numeric value (one of the Socket::SOCK_* constants).
  - !ruby/struct:SM::Flow::LI 
    label: "-"
    body: protocol number, as a numeric value (one of the Socket::IPPROTO_* constants).
  type: :BULLET
- !ruby/struct:SM::Flow::P 
  body: The first four values are identical to what is commonly returned as an address array, see IPSocket for more information.
- !ruby/struct:SM::Flow::H 
  level: 3
  text: Examples
- !ruby/struct:SM::Flow::P 
  body: Not all input combinations are valid, and while there are many combinations, only a few cases are common.
- !ruby/struct:SM::Flow::P 
  body: "A typical client will call getaddrinfo with the <tt>host</tt> and <tt>service</tt> it wants to connect to. It knows that it will attempt to connect with either TCP or UDP, and specifies <tt>socktype</tt> accordingly. It loops through all returned addresses, and try to connect to them in turn:"
- !ruby/struct:SM::Flow::VERB 
  body: "  addrinfo = Socket::getaddrinfo('www.example.com', 'www', nil, Socket::SOCK_STREAM)\n  addrinfo.each do |af, port, name, addr|\n    begin\n      sock = TCPSocket.new(addr, port)\n      # ...\n      exit 1\n    rescue\n    end\n  end\n"
- !ruby/struct:SM::Flow::P 
  body: With UDP you don't know if connect suceeded, but if communication fails, the next address can be tried.
- !ruby/struct:SM::Flow::P 
  body: "A typical server will call getaddrinfo with a <tt>host</tt> of nil, the <tt>service</tt> it listens to, and a <tt>flags</tt> of Socket::AI_PASSIVE. It will listen for connections on the first returned address:"
- !ruby/struct:SM::Flow::VERB 
  body: "  addrinfo = Socket::getaddrinfo(nil, 'www', nil, Socket::SOCK_STREAM, nil, Socket::AI_PASSIVE)\n  af, port, name, addr = addrinfo.first\n  sock = TCPServer(addr, port)\n  while( client = s.accept )\n    # ...\n  end\n"
full_name: Socket::getaddrinfo
is_singleton: true
name: getaddrinfo
params: " Socket.getaddrinfo(host, service, family=nil, socktype=nil, protocol=nil, flags=nil) => addrinfo\n"
visibility: public