external/bsd/libbind/dist/doc/getnameinfo.man3

   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
  30 The
  31 .Fn getnameinfo
  32 function is defined for protocol-independent address-to-nodename translation.
  33 It performs functionality of
  34 .Xr gethostbyaddr 3
  35 and
  36 .Xr getservbyport 3
  37 in more sophisticated manner.
  38 .Pp
  39 The
  40 .Fa sa
  41 arguement is a pointer to a generic socket address structure of size
  42 .Fa salen .
  43 The arguements
  44 .Fa host
  45 and
  46 .Fa serv
  47 are pointers to buffers to hold the return values.
  48 Their sizes are specified by
  49 .Fa hostlen
  50 and
  51 .Fa servlen
  52 repectively.
  53 Either
  54 .Fa host
  55 or
  56 .Fa serv
  57 may be
  58 .Dv NULL
  59 if the hostname  or service name is not required.
  60 .Pp
  61 The
  62 .Fa flags
  63 arguement modifies the behaviour of
  64 .Fn getnameinfo
  65 as follows:
  66 .Pp
  67 If
  68 .Dv NI_NOFQDN
  69 is set only the unqualified hostname is returned for local fully
  70 qualified names.
  71 .Pp
  72 If
  73 .Dv NI_NUMERICHOST
  74 is set then the numeric form of the hostname is returned.
  75 .Pp
  76 If
  77 .Dv NI_NAMEREQD
  78 is set, then a error is returned if the hostname cannot be looked up.
  79 .Pp
  80 If
  81 .Dv NI_NUMERICSERV
  82 is set then the service is returned in numeric form.
  83 .Pp
  84 If
  85 .Dv NI_DGRAM
  86 is 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
  95 R. Gilligan, S.  Thomson, J. Bound, and W. Stevens,
  96 ``Basic Socket Interface Extensions for IPv6,'' RFC2133, April 1997.
  97 .Sh STANDARDS
  98 The
  99 .Fn getaddrinfo
 100 function is defined IEEE POSIX 1003.1g draft specification,
 101 and documented in ``Basic Socket Interface Extensions for IPv6''
 102 (RFC2133).