| Current File : //proc/thread-self/root/opt/alt/ruby18/share/ri/1.8/system/Socket/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 ("http", "ssh", ...), 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 "AF_INET" or "AF_INET6" 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 => 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, "0::0" or "::" 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 "127.0.0.1" for IPv4 and "::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 "AF_INET" or "AF_INET6"
- !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