ares_gethostbyname_file.3

   1 .\" $Id$
   2 .\"
   3 .\" Copyright 1998 by the Massachusetts Institute of Technology.
   4 .\"
   5 .\" Permission to use, copy, modify, and distribute this
   6 .\" software and its documentation for any purpose and without
   7 .\" fee is hereby granted, provided that the above copyright
   8 .\" notice appear in all copies and that both that copyright
   9 .\" notice and this permission notice appear in supporting
  10 .\" documentation, and that the name of M.I.T. not be used in
  11 .\" advertising or publicity pertaining to distribution of the
  12 .\" software without specific, written prior permission.
  13 .\" M.I.T. makes no representations about the suitability of
  14 .\" this software for any purpose.  It is provided "as is"
  15 .\" without express or implied warranty.
  16 .\"
  17 .TH ARES_GETHOSTBYNAME 3 "25 July 1998"
  18 .SH NAME
  19 ares_gethostbyname_file \- Lookup a name in the system's hosts file
  20 .SH SYNOPSIS
  21 .nf
  22 .B #include <ares.h>
  23 .PP
  24 .B int ares_gethostbyname_file(ares_channel \fIchannel\fP, const char *\fIname\fP,
  25 .B      int \fIfamily\fP, struct hostent **host)
  26 .fi
  27 .SH DESCRIPTION
  28 The
  29 .B ares_gethostbyname_file
  30 function performs a host lookup by name against the system's hosts file (or equivalent local hostname database).
  31 The
  32 .IR channel
  33 parameter is required, but no asynchronous queries are performed.  Instead, the
  34 lookup is done via the same mechanism used to perform 'f' lookups
  35 (see the
  36 .I lookups
  37 options field in \fIares_init_options(3)\fP).
  38 The parameter
  39 .I name
  40 gives the hostname as a NUL-terminated C string, and
  41 .I family
  42 gives the desired type of address for the resulting host entry.
  43 .PP
  44 The return value indicates whether the query succeeded and, if not, how it
  45 failed.  It may have any of the following values:
  46 .TP 19
  47 .B ARES_SUCCESS
  48 The host lookup completed successfully and
  49 .I host
  50 now points to the result (and must be freed with \fIares_free_hostent(3)\fP).
  51 .TP 19
  52 .B ARES_ENOTFOUND
  53 The hostname
  54 .I name
  55 was not found.
  56 .TP 19
  57 .B ARES_EFILE
  58 There was a file I/O error while performing the lookup.
  59 .TP 19
  60 .B ARES_ENOMEM
  61 Memory was exhausted.
  62 .PP
  63 On successful completion of the query, the pointer pointed to by
  64 .I host
  65 points to a
  66 .B struct hostent
  67 containing the address of the host returned by the lookup.  The user must
  68 free the memory pointed to by
  69 .IR host
  70 when finished with it by calling \fIares_free_hostent(3)\fP.  If the lookup did
  71 not complete successfully,
  72 .I host
  73 will be
  74 .BR NULL .
  75 .SH AVAILABILITY
  76 Added in c-ares 1.5.4
  77 .SH SEE ALSO
  78 .BR ares_gethostbyname (3),
  79 .BR ares_free_hostent (3),
  80 .BR ares_init_options (3)
  81 .SH AUTHOR
  82 Brad Spencer
  83 .br
  84 Copyright 1998 by the Massachusetts Institute of Technology.