|
NAMEgetaddrinfo , freeaddrinfo
—
socket address structure to host and service name
SYNOPSIS#include <sys/types.h>
#include <sys/socket.h>
#include <netdb.h>
int
void
DESCRIPTIONThegetaddrinfo () function is used to get a list of
addresses and port numbers for host hostname and service
servname. It is a replacement for and provides more
flexibility than the
gethostbyname(3)
and
getservbyname(3)
functions.
The hostname and servname arguments are either pointers to NUL-terminated strings or the null pointer. An acceptable value for hostname is either a valid host name or a numeric host address string consisting of a dotted decimal IPv4 address, an IPv6 address, or a UNIX-domain address. The servname is either a decimal port number or a service name listed in services(5). At least one of hostname and servname must be non-null. hints is an optional pointer to a
struct addrinfo { int ai_flags; /* AI_PASSIVE, AI_CANONNAME, .. */ int ai_family; /* AF_xxx */ int ai_socktype; /* SOCK_xxx */ int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */ socklen_t ai_addrlen; /* length of ai_addr */ char *ai_canonname; /* canonical name for hostname */ struct sockaddr *ai_addr; /* binary address */ struct addrinfo *ai_next; /* next structure in linked list */ }; This structure can be used to provide hints concerning the type of socket that the caller supports or wishes to use. The caller can supply the following structure elements in hints:
All other elements of the If hints is the null pointer,
After a successful call to This implementation of At this moment the code supports only link-local addresses with
the format. The scope identifier is hardcoded to the name of the hardware
interface associated with the link (such as The current implementation assumes a one-to-one relationship between the interface and link, which is not necessarily true from the specification. All of the information returned by
Memory allocated for the dynamically allocated structures created
by a successful call to IMPLEMENTATION NOTESThe behavior offreeadrinfo(NULL) is left unspecified by
both Version 4 of the Single UNIX Specification
(“SUSv4”) and RFC 3493 . The
current implementation ignores a NULL argument for
compatibility with programs that rely on the implementation details of other
operating systems.
RETURN VALUESgetaddrinfo () returns zero on success or one of the
error codes listed in
gai_strerror(3)
if an error occurs.
EXAMPLESThe following code tries to connect to “www.kame.net ” service
“http ” via a stream socket. It loops
through all the addresses available, regardless of address family. If the
destination resolves to an IPv4 address, it will use an
AF_INET socket. Similarly, if it resolves to IPv6, an
AF_INET6 socket is used. Observe that there is no
hardcoded reference to a particular address family. The code works even if
getaddrinfo () returns addresses that are not IPv4/v6.
struct addrinfo hints, *res, *res0; int error; int s; const char *cause = NULL; memset(&hints, 0, sizeof(hints)); hints.ai_family = AF_UNSPEC; hints.ai_socktype = SOCK_STREAM; error = getaddrinfo("www.kame.net", "http", &hints, &res0); if (error) { errx(1, "%s", gai_strerror(error)); /* NOTREACHED */ } s = -1; for (res = res0; res; res = res->ai_next) { s = socket(res->ai_family, res->ai_socktype, res->ai_protocol); if (s < 0) { cause = "socket"; continue; } if (connect(s, res->ai_addr, res->ai_addrlen) < 0) { cause = "connect"; close(s); s = -1; continue; } break; /* okay we got one */ } if (s < 0) { err(1, "%s", cause); /* NOTREACHED */ } freeaddrinfo(res0); The following example tries to open a wildcard listening socket
onto service “ struct addrinfo hints, *res, *res0; int error; int s[MAXSOCK]; int nsock; const char *cause = NULL; memset(&hints, 0, sizeof(hints)); hints.ai_family = AF_UNSPEC; hints.ai_socktype = SOCK_STREAM; hints.ai_flags = AI_PASSIVE; error = getaddrinfo(NULL, "http", &hints, &res0); if (error) { errx(1, "%s", gai_strerror(error)); /* NOTREACHED */ } nsock = 0; for (res = res0; res && nsock < MAXSOCK; res = res->ai_next) { s[nsock] = socket(res->ai_family, res->ai_socktype, res->ai_protocol); if (s[nsock] < 0) { cause = "socket"; continue; } if (bind(s[nsock], res->ai_addr, res->ai_addrlen) < 0) { cause = "bind"; close(s[nsock]); continue; } (void) listen(s[nsock], 5); nsock++; } if (nsock == 0) { err(1, "%s", cause); /* NOTREACHED */ } freeaddrinfo(res0); SEE ALSObind(2), connect(2), send(2), socket(2), gai_strerror(3), gethostbyname(3), getnameinfo(3), getservbyname(3), resolver(3), inet(4), inet6(4), unix(4), hosts(5), resolv.conf(5), services(5), hostname(7), named(8)R. Gilligan, S. Thomson, J. Bound, J. McCann, and W. Stevens, Basic Socket Interface Extensions for IPv6, RFC 3493, February 2003. S. Deering, B. Haberman, T. Jinmei, E. Nordmark, and B. Zill, IPv6 Scoped Address Architecture, RFC 4007, March 2005. Craig Metz, Protocol Independence Using the Sockets API, Proceedings of the freenix track: 2000 USENIX annual technical conference, June 2000. STANDARDSThegetaddrinfo () function is defined by the
IEEE Std 1003.1-2004 (“POSIX.1”)
specification and documented in RFC 3493 ,
“Basic Socket Interface Extensions for IPv6”.
Visit the GSP FreeBSD Man Page Interface. |