lib/libutil/realhostname.3

   1 .\" Copyright (c) 1999 Brian Somers <brian@Awfulhak.org>
   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 .\"
  13 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  14 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  15 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  16 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  17 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  18 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  19 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  20 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  21 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  22 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  23 .\" SUCH DAMAGE.
  24 .\"
  25 .Dd April 6, 1999
  26 .Dt REALHOSTNAME 3
  27 .Os
  28 .Sh NAME
  29 .Nm realhostname
  30 .Nd "convert an IP number to the real host name"
  31 .Sh LIBRARY
  32 .Lb libutil
  33 .Sh SYNOPSIS
  34 .In libutil.h
  35 .Ft int
  36 .Fn realhostname "char *host" "size_t hsize" "const struct in_addr *ip"
  37 .Sh DESCRIPTION
  38 The function
  39 .Fn realhostname
  40 converts
  41 .Ar ip
  42 to the corresponding host name.
  43 This is done by resolving
  44 .Ar ip
  45 to a host name and then ensuring that the host name resolves
  46 back to
  47 .Ar ip .
  48 .Pp
  49 .Ar host
  50 must point to a buffer of at least
  51 .Ar hsize
  52 bytes, and will always be written to by this function.
  53 .Pp
  54 If the name resolution does not work both ways or if the host name is longer
  55 than
  56 .Ar hsize
  57 bytes,
  58 .Xr inet_ntoa 3
  59 is used to convert
  60 .Ar ip
  61 to an ASCII form.
  62 .Pp
  63 If the string written to
  64 .Ar host
  65 is
  66 .Ar hsize
  67 bytes long,
  68 .Ar host
  69 will not be NUL terminated.
  70 .Sh RETURN VALUES
  71 The
  72 .Fn realhostname
  73 function will return one of the following constants which are defined in
  74 .In libutil.h :
  75 .Bl -tag -width XXX -offset XXX
  76 .It Li HOSTNAME_FOUND
  77 A valid host name was found.
  78 .It Li HOSTNAME_INCORRECTNAME
  79 A host name was found, but it did not resolve back to the passed
  80 .Ar ip .
  81 .Ar host
  82 now contains the numeric value of
  83 .Ar ip .
  84 .It Li HOSTNAME_INVALIDADDR
  85 .Ar ip
  86 could not be resolved.
  87 .Ar host
  88 now contains the numeric value of
  89 .Ar ip .
  90 .It Li HOSTNAME_INVALIDNAME
  91 A host name was found, but it could not be resolved back to any ip number.
  92 .Ar host
  93 now contains the numeric value of
  94 .Ar ip .
  95 .El
  96 .Sh SEE ALSO
  97 .Xr gethostbyaddr 3 ,
  98 .Xr gethostbyname 3 ,
  99 .Xr inet_ntoa 3 ,
 100 .Xr realhostname_sa 3
 101 .Sh HISTORY
 102 The
 103 .Fn realhostname
 104 function first appeared in
 105 .Fx 3.2 .