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