← Back
Editing: 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
Save File
Cancel