ares_gethostbyname_file.3

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