67 lines
3.5 KiB
Groff
67 lines
3.5 KiB
Groff
|
.TH GETADDRINFO 3 "January 19, 2010"
|
||
|
|
.UC 4
|
||
|
|
.SH NAME
|
||
|
|
getaddrinfo, freeaddrinfo, gai_strerror, getnameinfo \- address information
|
||
|
|
.SH SYNOPSIS
|
||
|
|
.nf
|
||
|
|
.ft B
|
||
|
|
#include <netdb.h>
|
||
|
|
|
||
|
|
void freeaddrinfo(struct addrinfo *\fIai\fP);
|
||
|
|
int getaddrinfo(const char *\fInodename\fP,
|
||
|
|
const char *\fIservname\fP,
|
||
|
|
const struct addrinfo *\fIhints\fP,
|
||
|
|
struct addrinfo **\fIres\fP);
|
||
|
|
int getnameinfo(const struct sockaddr *\fIsa\fP, socklen_t \fIsalen\fP,
|
||
|
|
char *\fInode\fP, socklen_t \fInodelen\fP, char *\fIservice\fP,
|
||
|
|
socklen_t \fIservicelen\fP, int \fIflags\fP);
|
||
|
|
const char *gai_strerror(int \fIecode\fP);
|
||
|
|
.fi
|
||
|
|
.SH DESCRIPTION
|
||
|
|
These functions provide to convert between host and service names on the one
|
||
|
|
hand and network addresses and ports on the other.
|
||
|
|
.PP
|
||
|
|
getaddrinfo converts the hostname specified in \fInodename\fP and/or the service
|
||
|
|
name in \fIservname\fP into a socket address that can be used to connect to that
|
||
|
|
service or listen for incoming connections. One of the parameters may be NULL.
|
||
|
|
If \fInodename\fP is NULL, an address for the local host is provided. If
|
||
|
|
\fIservname\fP is NULL, the network port is not filled in (and therefore set to
|
||
|
|
zero). Buffers are allocated to store the results and a pointer to the first
|
||
|
|
element of a linked list of addresses is stored in \fIai\fP. These buffers must
|
||
|
|
be freed by calling freeaddrinfo on the pointer returned in \fIai\fP.
|
||
|
|
.PP
|
||
|
|
getnameinfo converts the specified socket address into a hostname and/or service
|
||
|
|
name. These are stored in the buffers pointed to by \fInode\fP and \fIservice\fP
|
||
|
|
resepectively. \fInodelen\fP and \fIservicelen\fP specify the sizes of these
|
||
|
|
buffers. If the result string including null terminator does not fit in the
|
||
|
|
buffer, the function fails and EAI_OVERFLOW is returned.
|
||
|
|
.PP
|
||
|
|
For both functions, some flags may be specified to alter their behaviour. For
|
||
|
|
getaddrinfo these flags are specified in the ai_flags field of the optional
|
||
|
|
\fIhints\fP parameter. AI_PASSIVE indicates that an address suitable for the
|
||
|
|
bind function should be returned, otherwise an address suitable for connect is
|
||
|
|
provided. AI_CANONNAME requests that the canonical name of the host be retrieved
|
||
|
|
and stored in the ai_canonname field of the result. AI_NUMERICHOST and
|
||
|
|
AI_NUMERICSERV indicate respectively that \fInodename\fP is an IP address and
|
||
|
|
\fIservname\fP is a port number, avoiding a lookup. Search can be limited to a
|
||
|
|
specific socket type by setting \fIhints\fP\->ai_socktype to SOCK_STREAM or
|
||
|
|
SOCK_DGRAM. \fIhints\fP\->ai_family can be set to AF_UNSPEC or AF_INET but this
|
||
|
|
doesn't make a difference as MINIX supports only IPv4. Unused fields of
|
||
|
|
\fIhints\fP must be set to zero.
|
||
|
|
.PP
|
||
|
|
Flags for getnameinfo are specified in the \fIflags\fP parameter. NI_NUMERICHOST
|
||
|
|
and NI_NUMERICSERV respectively cause \fInode\fP to be set to an IP address
|
||
|
|
and \fIservice\fP to be set to a port number. NI_NAMEREQD causes the function
|
||
|
|
to fail with EAI_NONAME if a name is not found for the host (otherwise the IP
|
||
|
|
address is returned). NI_DGRAM indicates that a datagram service is specified,
|
||
|
|
the default being a stream service.
|
||
|
|
.SH "RETURN VALUE
|
||
|
|
If the functions succeed, they return 0. If they fail, one of the EAI_* values
|
||
|
|
defined in netdb.h is returned. This value can be converted into a string using
|
||
|
|
gai_strerror. The most important ones are EAI_NONAME (host name not found),
|
||
|
|
EAI_SERVICE (service name not found) and EAI_OVERFLOW (buffer too small, only
|
||
|
|
for getnameinfo).
|
||
|
|
.SH "KNOWN ISSUES
|
||
|
|
Since MINIX does not support IPv6, the related flags are not supported.
|
||
|
|
The NI_NOFQDN flag is also not (yet) supported.
|