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

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