SunOS man pages : getaddrinfo (3)
Network Functions getaddrinfo(3SOCKET)
NAME
getaddrinfo, getnameinfo, freeaddrinfo, gai_strerror -
translate between node name and address
SYNOPSIS
cc [flag ...] file ... -lsocket -lnsl [library ...]
#include <sys/socket.h>
#include <netdb.h>
int getaddrinfo(const char *nodename, const char *servname,
const struct addrinfo *hints, struct addrinfo **res);
int getnameinfo(const struct sockaddr *sa, socklen_t salen,
char *host, size_t hostlen, char *serv, size_t servlen, int
flags);
void freeaddrinfo(struct addrinfo *ai);
char *gai_strerror(int errcode);
DESCRIPTION
These functions perform translations from node name to
address and from address to node name in a protocol-
independent manner.
The getaddrinfo() function performs the node name to address
translation. The nodename and servname arguments are
pointers to null-terminated strings or NULL. One or both of
these arguments must be a non-null pointer. In the normal
client scenario, both the nodename and servname are speci-
fied. In the normal server scenario, only the servname is
specified. A non-null nodename string can be either a node
name or a numeric host address string (a dotted-decimal IPv4
address or an IPv6 hex address). A non-null servname string
can be either a service name or a decimal port number.
The caller can optionally pass an addrinfo structure,
pointed to by the third argument, to provide hints concern-
ing the type of socket that the caller supports.
The addrinfo structure is defined as:
struct addrinfo {
int ai_flags; /* AI_PASSIVE, AI_CANONNAME, AI_NUMERICHOST */
int ai_family; /* PF_xxx */
int ai_socktype; /* SOCK_xxx */
int ai_protocol; /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
size_t ai_addrlen; /* length of ai_addr */
char *ai_canonname; /* canonical name for nodename */
struct sockaddr *ai_addr; /* binary address */
struct addrinfo *ai_next; /* next structure in linked list */
};
SunOS 5.8 Last change: 15 Dec 2000 1
Network Functions getaddrinfo(3SOCKET)
In this hints structure, all members other than ai_flags,
ai_family, ai_socktype, and ai_protocol must be 0 or a null
pointer. A value of PF_UNSPEC for ai_family indicates that
the caller will accept any protocol family. A value of 0
for ai_socktype indicates that the caller will accept any
socket type. A value of 0 for ai_protocol indicates that
the caller will accept any protocol. For example, if the
caller handles only TCP and not UDP, then the ai_socktype
member of the hints structure should be set to SOCK_STREAM
when getaddrinfo() is called. If the caller handles only
IPv4 and not IPv6, then the ai_family member of the hints
structure should be set to PF_INET when getaddrinfo() is
called. If the third argument to getaddrinfo() is a null
pointer, it is as if the caller had filled in an addrinfo
structure initialized to 0 with ai_family set to PF_UNSPEC.
Upon success, a pointer to a linked list of one or more
addrinfo structures is returned through the final argument.
The caller can process each addrinfo structure in this list
by following the ai_next pointer, until a null pointer is
encountered. In each returned addrinfo structure the three
members ai_family, ai_socktype, and ai_protocol are the
corresponding arguments for a call to the socket(3SOCKET)
function. In each addrinfo structure the ai_addr member
points to a filled-in socket address structure whose length
is specified by the ai_addrlen member.
If the AI_PASSIVE bit is set in the ai_flags member of the
hints structure, the caller plans to use the returned socket
address structure in a call to bind(3SOCKET). In this case,
if the nodename argument is a null pointer, the IP address
portion of the socket address structure will be set to
INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an
IPv6 address.
If the AI_PASSIVE bit is not set in the ai_flags member of
the hints structure, then the returned socket address struc-
ture will be ready for a call to connect(3SOCKET) (for a
connection-oriented protocol) or either connect(3SOCKET),
sendto(3SOCKET), or sendmsg(3SOCKET) (for a connectionless
protocol). If the nodename argument is a null pointer, the
IP address portion of the socket address structure will be
set to the loopback address.
If the AI_CANONNAME bit is set in the ai_flags member of the
hints structure, then upon successful return the
ai_canonname member of the first addrinfo structure in the
linked list will point to a null-terminated string contain-
ing the canonical name of the specified nodename.
If the AI_NUMERICHOST bit is set in the ai_flags member of
the hints structure, then a non-null nodename string must be
SunOS 5.8 Last change: 15 Dec 2000 2
Network Functions getaddrinfo(3SOCKET)
a numeric host address string. Otherwise an error of
EAI_NONAME is returned. This flag prevents any type of name
resolution service (such as DNS) from being called.
All of the information returned by getaddrinfo() is dynami-
cally allocated: the addrinfo structures as well as the
socket address structures and canonical node name strings
pointed to by the addrinfo structures. The freeaddrinfo()
function is called to return this information to the system
the function . For freeaddrinfo(), the addrinfo structure
pointed to by the ai argument is freed, along with any
dynamic storage pointed to by the structure. This operation
is repeated until a null ai_next pointer is encountered.
To aid applications in printing error messages based on the
EAI_* codes returned by getaddrinfo(), the gai_strerror() is
defined. The argument is one of the EAI_* values defined
below and the return value points to a string describing the
error. If the argument is not one of the EAI_* values, the
function still returns a pointer to a string whose contents
indicate an unknown error.
The getnameinfo() function looks up an IP address and port
number provided by the caller in the name service database
and system-specific database, and returns text strings for
both in buffers provided by the caller. The function indi-
cates successful completion by a 0 return value; a non-zero
return value indicates failure.
The first argument, sa, points to either a sockaddr_in
structure (for IPv4) or a sockaddr_in6 structure (for IPv6)
that holds the IP address and port number. The salen argu-
ment gives the length of the sockaddr_in or sockaddr_in6
structure.
The function returns the node name associated with the IP
address in the buffer pointed to by the host argument. The
caller provides the size of this buffer with the hostlen
argument. The service name associated with the port number
is returned in the buffer pointed to by serv, and the
servlen argument gives the length of this buffer. The
caller specifies not to return either string by providing a
0 value for the hostlen or servlen arguments. Otherwise,
the caller must provide buffers large enough to hold the
node name and the service name, including the terminating
null characters.
To aid the application in allocating buffers for these two
returned strings, the following constants are defined in
<netdb.h>:
SunOS 5.8 Last change: 15 Dec 2000 3
Network Functions getaddrinfo(3SOCKET)
#define NI_MAXHOST 1025
#define NI_MAXSERV 32
The final argument is a flag that changes the default
actions of this function. By default, the fully-qualified
domain name (FQDN) for the host is looked up in the name
service database and returned. If the flag bit NI_NOFQDN is
set, only the node name portion of the FQDN is returned for
local hosts.
If the flag bit NI_NUMERICHOST is set, or if the host's name
cannot be located in the name service, the numeric form of
the host's address is returned instead of its name, for
example, by calling inet_ntop() (see inet(3SOCKET)) instead
of getipnodebyname(3SOCKET). If the flag bit NI_NAMEREQD is
set, an error is returned if the host's name cannot be
located in the name service database.
If the flag bit NI_NUMERICSERV is set, the numeric form of
the service address is returned (for example, its port
number) instead of its name. The two NI_NUMERIC* flags are
required to support the "-n" flag that many commands pro-
vide.
A fifth flag bit, NI_DGRAM, specifies that the service is a
datagram service, and causes getservbyport(3SOCKET) to be
called with a second argument of "udp" instead of the
default "tcp". This is required for the few ports (for
example, 512-514) that have different services for UDP and
TCP.
These NI_* flags are defined in <netdb.h> along with the
AI_* flags already defined for getaddrinfo().
RETURN VALUES
For getaddrinfo(), if the query is successful, a pointer to
a linked list of one or more addrinfo structures is returned
by the fourth argument and the function returns 0. If the
query fails, a non-zero error code will be returned. For
getnameinfo(), if successful, the strings hostname and ser-
vice are copied into host and serv, respectively. If unsuc-
cessful, zero values for either hostlen or servlen will
suppress the associated lookup; in this case no data is
copied into the applicable buffer. If gai_strerror() is
successful, a pointer to a string containing an error mes-
sage appropriate for the EAI_* errors is returned. If
errcode is not one of the EAI_* values, a pointer to a
string indicating an unknown error is returned.
ERRORS
The following names are the error values returned by getad-
drinfo() and are defined in <netdb.h>:
SunOS 5.8 Last change: 15 Dec 2000 4
Network Functions getaddrinfo(3SOCKET)
EAI_ADDRFAMILY address family for nodename not supported
EAI_AGAIN temporary failure in name resolution
EAI_BADFLAGS invalid value for ai_flags
EAI_FAIL non-recoverable failure in name resolution
EAI_FAMILY ai_family not supported
EAI_MEMORY memory allocation failure
EAI_NODATA no address associated with nodename
EAI_NONAME nodename nor servname provided, or not known
EAI_SERVICE servname not supported for ai_socktype
EAI_SOCKTYPE ai_socktype not supported
EAI_SYSTEM system error returned in errno
FILES
/etc/inet/hosts
/etc/inet/ipnodes
/etc/netconfig
/etc/nsswitch.conf
SEE ALSO
gethostbyname(3NSL), getipnodebyname(3SOCKET),
htonl(3SOCKET), inet(3SOCKET), netdb(3HEAD),
socket(3SOCKET), hosts(4), ipnodes(4), nsswitch.conf(4)
SunOS 5.8 Last change: 15 Dec 2000 5
|
 |
|
|
