man3/getnameinfo.3

   1 .\" This page is in the public domain.
   2 .\" Almost all details are from RFC 2553.
   3 .\"
   4 .\" 2004-12-14, mtk, Added EAI_OVERFLOW error
   5 .\" 2004-12-14 Fixed description of error return
   6 .\"
   7 .TH getnameinfo 3 2000-12-11 "Linux Man Page" "UNIX Programmer's Manual"
   8 .SH NAME
   9 getnameinfo \- address-to-name translation in protocol-independent manner
  10 .SH SYNOPSIS
  11 .nf
  12 .B #include <sys/socket.h>
  13 .B #include <netdb.h>
  14 .sp
  15 .BI "int getnameinfo(const struct sockaddr *" "sa" ", socklen_t " "salen" ,
  16 .BI "                char *" "host" ", size_t " "hostlen" ,
  17 .BI "                char *" "serv" ", size_t " "servlen" ", int " "flags" );
  18 .fi
  19 .SH DESCRIPTION
  20 The
  21 .BR getnameinfo (3)
  22 function is defined for protocol-independent address-to-nodename translation.
  23 It combines the functionality of
  24 .BR gethostbyaddr (3)
  25 and
  26 .BR getservbyport (3)
  27 and is the inverse of
  28 .BR getaddrinfo (3).
  29 The
  30 .I sa
  31 argument is a pointer to a generic socket address structure
  32 (of type
  33 .I sockaddr_in
  34 or
  35 .IR sockaddr_in6 )
  36 of size
  37 .IR salen
  38 that holds the input IP address and port number.
  39 The arguments
  40 .I host
  41 and
  42 .I serv
  43 are pointers to buffers (of size
  44 .I hostlen
  45 and
  46 .I servlen
  47 respectively) to hold the return values.
  48
  49 The caller can specify that no hostname (or no service name)
  50 is required by providing a NULL
  51 .I host
  52 (or
  53 .IR serv )
  54 argument or a zero
  55 .I hostlen
  56 (or
  57 .IR servlen )
  58 parameter. However, at least one of hostname or service name
  59 must be requested.
  60
  61 The
  62 .I flags
  63 argument modifies the behaviour of
  64 .BR getnameinfo (3)
  65 as follows:
  66 .TP
  67 .B NI_NOFQDN
  68 If set, return only the hostname part of the FQDN for local hosts.
  69 .TP
  70 .B NI_NUMERICHOST
  71 If set, then the numeric form of the hostname is returned.
  72 .\" For example, by calling
  73 .\" .I inet_ntop()
  74 .\" instead of
  75 .\" .IR gethostbyaddr() .
  76 (When not set, this will still happen in case the node's name
  77 cannot be looked up.)
  78 .TP
  79 .B NI_NAMEREQD
  80 If set, then a error is returned if the hostname cannot be looked up.
  81 .TP
  82 .B NI_NUMERICSERV
  83 If set, then the service address is returned in numeric form,
  84 for example by its port number.
  85 .TP
  86 .B NI_DGRAM
  87 If set, then the service is datagram (UDP) based rather than
  88 stream (TCP) based. This is required for the few ports (512-514)
  89 that have different services for UDP and TCP.
  90 .SH "RETURN VALUE"
  91 On success 0 is returned, and node and service names, if requested,
  92 are filled with NUL-terminated strings, possibly truncated to fit
  93 the specified buffer lengths.
  94 On error one of the following non-zero error codes is returned:
  95 .TP
  96 .B EAI_AGAIN
  97 The name could not be resolved at this time. Try again later.
  98 .TP
  99 .B EAI_BADFLAGS
 100 The
 101 .I flags
 102 parameter has an invalid value.
 103 .TP
 104 .B EAI_FAIL
 105 A non-recoverable error occurred.
 106 .TP
 107 .B EAI_FAMILY
 108 The address family was not recognized,
 109 or the address length was invalid for the specified family.
 110 .TP
 111 .B EAI_MEMORY
 112 Out of memory.
 113 .TP
 114 .B EAI_NONAME
 115 The name does not resolve for the supplied parameters.
 116 NI_NAMEREQD is set and the host's name cannot be located,
 117 or neither hostname nor service name were requested.
 118 .TP
 119 .B EAI_OVERFLOW
 120 The buffer pointed to by
 121 .I host
 122 or
 123 .I serv
 124 was too small.
 125 .TP
 126 .B EAI_SYSTEM
 127 A system error occurred. The error code can be found in
 128 .IR errno .
 129 .SH FILES
 130 /etc/hosts
 131 .br
 132 /etc/nsswitch.conf
 133 .br
 134 /etc/resolv.conf
 135 The
 136 .BR gai_strerror (3)
 137 function translates these error codes to a human readable string,
 138 suitable for error reporting.
 139 .SH NOTE
 140 In order to assist the programmer in choosing reasonable sizes
 141 for the supplied buffers,
 142 .I <netdb.h>
 143 defines the constants
 144 .RS
 145 .nf
 146 # define NI_MAXHOST      1025
 147 .br
 148 # define NI_MAXSERV      32
 149 .fi
 150 .RE
 151 The former is the constant MAXDNAME in recent versions of BIND's
 152 .I <arpa/nameser.h>
 153 header file. The latter is a guess based on the services listed
 154 in the current Assigned Numbers RFC.
 155 .SH EXAMPLES
 156 The following code tries to get the numeric hostname and service name, for
 157 a given socket address. Note that there is no hardcoded reference to
 158 a particular address family.
 159
 160 .RS
 161 .nf
 162   struct sockaddr *sa;    /* input */
 163   char hbuf[NI_MAXHOST], sbuf[NI_MAXSERV];
 164
 165   if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf), sbuf,
 166       sizeof(sbuf), NI_NUMERICHOST | NI_NUMERICSERV) == 0)
 167           printf("host=%s, serv=%s\en", hbuf, sbuf);
 168 .fi
 169 .RE
 170
 171 The following version checks if the socket address has a
 172 reverse address mapping.
 173
 174 .RS
 175 .fi
 176   struct sockaddr *sa;    /* input */
 177   char hbuf[NI_MAXHOST];
 178
 179   if (getnameinfo(sa, sa->sa_len, hbuf, sizeof(hbuf),
 180       NULL, 0, NI_NAMEREQD))
 181          printf("could not resolve hostname");
 182   else
 183          printf("host=%s\en", hbuf);
 184 .fi
 185 .RE
 186 .SH "CONFORMING TO"
 187 RFC 2553. (See also XNS, issue 5.2.)
 188 .SH "SEE ALSO"
 189 .BR getaddrinfo (3),
 190 .BR gethostbyaddr (3),
 191 .BR getservbyname (3),
 192 .BR getservbyport (3),
 193 .BR inet_ntop (3),
 194 .BR socket (3),
 195 .BR hosts (5),
 196 .BR services (5),
 197 .BR hostname (7),
 198 .BR named (8)
 199 .LP
 200 R. Gilligan, S. Thomson, J. Bound and W. Stevens,
 201 .IR "Basic Socket Interface Extensions for IPv6" ,
 202 RFC 2553, March 1999.
 203 .LP
 204 Tatsuya Jinmei and Atsushi Onoe,
 205 .IR "An Extension of Format for IPv6 Scoped Addresses" ,
 206 internet draft, work in progress.
 207 ftp://ftp.ietf.org/internet-drafts/draft-ietf-ipngwg-scopedaddr-format-02.txt
 208 .LP
 209 Craig Metz,
 210 .IR "Protocol Independence Using the Sockets API" ,
 211 Proceedings of the freenix track:
 212 2000 USENIX annual technical conference, June 2000.
 213 http://www.usenix.org/publications/library/proceedings/usenix2000/freenix/metzprotocol.html