lib/libutil/realhostname_sa.3

   1 .\" Copyright (C) 1995, 1996, 1997, 1998, 1999, and 2000 WIDE Project.
   2 .\" All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the project nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" Copyright (c) 1999 Brian Somers <brian@Awfulhak.org>
  29 .\" All rights reserved.
  30 .\"
  31 .\" Redistribution and use in source and binary forms, with or without
  32 .\" modification, are permitted provided that the following conditions
  33 .\" are met:
  34 .\" 1. Redistributions of source code must retain the above copyright
  35 .\"    notice, this list of conditions and the following disclaimer.
  36 .\" 2. Redistributions in binary form must reproduce the above copyright
  37 .\"    notice, this list of conditions and the following disclaimer in the
  38 .\"    documentation and/or other materials provided with the distribution.
  39 .\"
  40 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  41 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  42 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  43 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  44 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  45 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  46 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  47 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  48 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  49 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  50 .\" SUCH DAMAGE.
  51 .\"
  52 .\" $FreeBSD: head/lib/libutil/realhostname_sa.3 213573 2010-10-08 12:40:16Z uqs $
  53 .\"
  54 .Dd January 11, 2000
  55 .Dt REALHOSTNAME_SA 3
  56 .Os
  57 .Sh NAME
  58 .Nm realhostname_sa
  59 .Nd "convert a"
  60 .Vt "struct sockaddr"
  61 to the real host name
  62 .Sh LIBRARY
  63 .Lb libutil
  64 .Sh SYNOPSIS
  65 .In sys/types.h
  66 .In netinet/in.h
  67 .In libutil.h
  68 .Ft int
  69 .Fn realhostname_sa "char *host" "size_t hsize" "struct sockaddr *addr" "int addrlen"
  70 .Sh DESCRIPTION
  71 The function
  72 .Fn realhostname_sa
  73 converts
  74 .Ar addr
  75 to the corresponding host name.
  76 This is done by resolving
  77 .Ar addr
  78 to a host name and then ensuring that the host name resolves
  79 back to
  80 .Ar addr .
  81 .Pp
  82 .Ar host
  83 must point to a buffer of at least
  84 .Ar hsize
  85 bytes, and will always be written to by this function.
  86 .Pp
  87 If the name resolution does not work both ways or if the host name is longer
  88 than
  89 .Ar hsize
  90 bytes,
  91 .Xr getnameinfo 3
  92 with
  93 .Dv NI_NUMERICHOST
  94 specified, is used to convert
  95 .Ar addr
  96 to an ASCII form.
  97 .Pp
  98 If the string written to
  99 .Ar host
 100 is
 101 .Ar hsize
 102 bytes long,
 103 .Ar host
 104 will not be NUL terminated.
 105 .Sh RETURN VALUES
 106 The
 107 .Fn realhostname_sa
 108 function will return one of the following constants which are defined in
 109 .In libutil.h :
 110 .Bl -tag -width ".Dv HOSTNAME_INCORRECTNAME" -offset indent
 111 .It Dv HOSTNAME_FOUND
 112 A valid host name was found.
 113 .It Dv HOSTNAME_INCORRECTNAME
 114 A host name was found, but it did not resolve back to the passed
 115 .Ar ip .
 116 .Ar host
 117 now contains the numeric value of
 118 .Ar ip .
 119 .It Dv HOSTNAME_INVALIDADDR
 120 .Ar ip
 121 could not be resolved.
 122 .Ar host
 123 now contains the numeric value of
 124 .Ar ip .
 125 .It Dv HOSTNAME_INVALIDNAME
 126 A host name was found, but it could not be resolved back to any ip number.
 127 .Ar host
 128 now contains the numeric value of
 129 .Ar ip .
 130 .El
 131 .Sh SEE ALSO
 132 .Xr getaddrinfo 3 ,
 133 .Xr getnameinfo 3 ,
 134 .Xr realhostname 3