man/man3/getaddrinfo.3

   1 .TH GETADDRINFO 3  "January 19, 2010"
   2 .UC 4
   3 .SH NAME
   4 getaddrinfo, freeaddrinfo, gai_strerror, getnameinfo \- address information
   5 .SH SYNOPSIS
   6 .nf
   7 .ft B
   8 #include <netdb.h>
   9
  10 void freeaddrinfo(struct addrinfo *\fIai\fP);
  11 int getaddrinfo(const char *\fInodename\fP,
  12        const char *\fIservname\fP,
  13        const struct addrinfo *\fIhints\fP,
  14        struct addrinfo **\fIres\fP);
  15 int getnameinfo(const struct sockaddr *\fIsa\fP, socklen_t \fIsalen\fP,
  16        char *\fInode\fP, socklen_t \fInodelen\fP, char *\fIservice\fP,
  17        socklen_t \fIservicelen\fP, int \fIflags\fP);
  18 const char *gai_strerror(int \fIecode\fP);
  19 .fi
  20 .SH DESCRIPTION
  21 These functions provide to convert between host and service names on the one
  22 hand and network addresses and ports on the other.
  23 .PP
  24 getaddrinfo converts the hostname specified in \fInodename\fP and/or the service
  25 name in \fIservname\fP into a socket address that can be used to connect to that
  26 service or listen for incoming connections. One of the parameters may be NULL.
  27 If \fInodename\fP is NULL, an address for the local host is provided. If
  28 \fIservname\fP is NULL, the network port is not filled in (and therefore set to
  29 zero). Buffers are allocated to store the results and a pointer to the first
  30 element of a linked list of addresses is stored in \fIai\fP. These buffers must
  31 be freed by calling freeaddrinfo on the pointer returned in \fIai\fP.
  32 .PP
  33 getnameinfo converts the specified socket address into a hostname and/or service
  34 name. These are stored in the buffers pointed to by \fInode\fP and \fIservice\fP
  35 resepectively. \fInodelen\fP and \fIservicelen\fP specify the sizes of these
  36 buffers. If the result string including null terminator does not fit in the
  37 buffer, the function fails and EAI_OVERFLOW is returned.
  38 .PP
  39 For both functions, some flags may be specified to alter their behaviour. For
  40 getaddrinfo these flags are specified in the ai_flags field of the optional
  41 \fIhints\fP parameter. AI_PASSIVE indicates that an address suitable for the
  42 bind function should be returned, otherwise an address suitable for connect is
  43 provided. AI_CANONNAME requests that the canonical name of the host be retrieved
  44 and stored in the ai_canonname field of the result. AI_NUMERICHOST and
  45 AI_NUMERICSERV indicate respectively that \fInodename\fP is an IP address and
  46 \fIservname\fP is a port number, avoiding a lookup. Search can be limited to a
  47 specific socket type by setting \fIhints\fP\->ai_socktype to SOCK_STREAM or
  48 SOCK_DGRAM. \fIhints\fP\->ai_family can be set to AF_UNSPEC or AF_INET but this
  49 doesn't make a difference as MINIX supports only IPv4. Unused fields of
  50 \fIhints\fP must be set to zero.
  51 .PP
  52 Flags for getnameinfo are specified in the \fIflags\fP parameter. NI_NUMERICHOST
  53 and NI_NUMERICSERV respectively cause \fInode\fP to be set to an IP address
  54 and \fIservice\fP to be set to a port number. NI_NAMEREQD causes the function
  55 to fail with EAI_NONAME if a name is not found for the host (otherwise the IP
  56 address is returned). NI_DGRAM indicates that a datagram service is specified,
  57 the default being a stream service.
  58 .SH "RETURN VALUE
  59 If the functions succeed, they return 0. If they fail, one of the EAI_* values
  60 defined in netdb.h is returned. This value can be converted into a string using
  61 gai_strerror. The most important ones are EAI_NONAME (host name not found),
  62 EAI_SERVICE (service name not found) and EAI_OVERFLOW (buffer too small, only
  63 for getnameinfo).
  64 .SH "KNOWN ISSUES
  65 Since MINIX does not support IPv6, the related flags are not supported.
  66 The NI_NOFQDN flag is also not (yet) supported.