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: src/lib/libutil/realhostname_sa.3,v 1.2.2.3 2001/12/17 10:08:32 ru Exp $
  53 .\" $DragonFly: src/lib/libutil/realhostname_sa.3,v 1.3 2006/05/26 21:39:38 swildner Exp $
  54 .\"
  55 .Dd January 11, 2000
  56 .Os
  57 .Dt REALHOSTNAME_SA 3
  58 .Sh NAME
  59 .Nm realhostname_sa
  60 .Nd "convert an struct sockaddr to the real host name"
  61 .Sh LIBRARY
  62 .Lb libutil
  63 .Sh SYNOPSIS
  64 .In sys/types.h
  65 .In netinet/in.h
  66 .In libutil.h
  67 .Ft int
  68 .Fn realhostname_sa "char *host" "size_t hsize" "struct sockaddr *addr" "int addrlen"
  69 .Sh DESCRIPTION
  70 The function
  71 .Fn realhostname_sa
  72 converts
  73 .Ar addr
  74 to the corresponding host name.  This is done by resolving
  75 .Ar addr
  76 to a host name and then ensuring that the host name resolves
  77 back to
  78 .Ar addr .
  79 .Pp
  80 .Ar host
  81 must point to a buffer of at least
  82 .Ar hsize
  83 bytes, and will always be written to by this function.
  84 .Pp
  85 If the name resolution doesn't work both ways or if the host name is longer
  86 than
  87 .Ar hsize
  88 bytes,
  89 .Xr getnameinfo 3
  90 with NI_NUMERICHOST specified, is used to convert
  91 .Ar addr
  92 to an ASCII form.
  93 .Pp
  94 If the string written to
  95 .Ar host
  96 is
  97 .Ar hsize
  98 bytes long,
  99 .Ar host
 100 will not be NUL terminated.
 101 .Sh RETURN VALUES
 102 .Fn realhostname_sa
 103 will return one of the following constants which are defined in
 104 .In libutil.h :
 105 .Pp
 106 .Bl -tag -width XXX -offset XXX
 107 .It Li HOSTNAME_FOUND
 108 A valid host name was found.
 109 .It Li HOSTNAME_INCORRECTNAME
 110 A host name was found, but it did not resolve back to the passed
 111 .Ar ip .
 112 .Ar host
 113 now contains the numeric value of
 114 .Ar ip .
 115 .It Li HOSTNAME_INVALIDADDR
 116 .Ar ip
 117 could not be resolved.
 118 .Ar host
 119 now contains the numeric value of
 120 .Ar ip .
 121 .It Li HOSTNAME_INVALIDNAME
 122 A host name was found, but it could not be resolved back to any ip number.
 123 .Ar host
 124 now contains the numeric value of
 125 .Ar ip .
 126 .El
 127 .Sh SEE ALSO
 128 .Xr getaddrinfo 3 ,
 129 .Xr getnameinfo 3 ,
 130 .Xr realhostname 3