1.\" Copyright (c) 2004 by Internet Systems Consortium, Inc. ("ISC")
2.\" Copyright (c) 1998,1999 by Internet Software Consortium
3.\"
4.\" Permission to use, copy, modify, and distribute this software for any
5.\" purpose with or without fee is hereby granted, provided that the above
6.\" copyright notice and this permission notice appear in all copies.
7.\"
8.\" THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES
9.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10.\" MERCHANTABILITY AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR
11.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
14.\" OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
15.\"
16.\" Id: getnameinfo.man3,v 1.3 2009/02/21 01:31:39 jreed Exp
17.\"
18.Dd January 11, 1999
19.Dt GETNAMEINFO 3
20.Sh NAME
21.Nm getnameinfo
22.Nd address-to-name translation in protocol-independent manner
23.Sh SYNOPSIS
24.Fd #include <sys/socket.h>
25.Fd #include <netdb.h>
26.Ft int
27.Fn getnameinfo "const struct sockaddr *sa" "socklen_t salen" \
28"char *host" "size_t hostlen" "char *serv" "size_t servlen" "int flags"
29.Sh DESCRIPTION
30The
31.Fn getnameinfo
32function is defined for protocol-independent address-to-nodename translation.
33It performs functionality of
34.Xr gethostbyaddr 3
35and
36.Xr getservbyport 3
37in more sophisticated manner.
38.Pp
39The
40.Fa sa
41arguement is a pointer to a generic socket address structure of size
42.Fa salen .
43The arguements
44.Fa host
45and
46.Fa serv
47are pointers to buffers to hold the return values.
48Their sizes are specified by
49.Fa hostlen
50and
51.Fa servlen
52repectively.
53Either
54.Fa host
55or
56.Fa serv
57may be
58.Dv NULL
59if the hostname  or service name is not required.
60.Pp
61The
62.Fa flags
63arguement modifies the behaviour of
64.Fn getnameinfo
65as follows:
66.Pp
67If
68.Dv NI_NOFQDN
69is set only the unqualified hostname is returned for local fully
70qualified names.
71.Pp
72If
73.Dv NI_NUMERICHOST
74is set then the numeric form of the hostname is returned.
75.Pp
76If
77.Dv NI_NAMEREQD
78is set, then a error is returned if the hostname cannot be looked up.
79.Pp
80If
81.Dv NI_NUMERICSERV
82is set then the service is returned in numeric form.
83.Pp
84If
85.Dv NI_DGRAM
86is set then the service is UDP based rather than TCP based.
87.Sh SEE ALSO
88.Xr getaddrinfo 3 ,
89.Xr gethostbyaddr 3 ,
90.Xr getservbyport 3 ,
91.Xr hosts 5 ,
92.Xr services 5 ,
93.Xr hostname 7 ,
94.Pp
95R. Gilligan, S.  Thomson, J. Bound, and W. Stevens,
96``Basic Socket Interface Extensions for IPv6,'' RFC2133, April 1997.
97.Sh STANDARDS
98The
99.Fn getaddrinfo
100function is defined IEEE POSIX 1003.1g draft specification,
101and documented in ``Basic Socket Interface Extensions for IPv6''
102(RFC2133).
103