ares_gethostbyname_file.3 (1908B)
1 .\" 2 .\" Copyright 1998 by the Massachusetts Institute of Technology. 3 .\" SPDX-License-Identifier: MIT 4 .\" 5 .TH ARES_GETHOSTBYNAME 3 "25 July 1998" 6 .SH NAME 7 ares_gethostbyname_file \- Lookup a name in the system's hosts file 8 .SH SYNOPSIS 9 .nf 10 #include <ares.h> 11 12 int ares_gethostbyname_file(ares_channel_t *\fIchannel\fP, const char *\fIname\fP, 13 int \fIfamily\fP, struct hostent **host) 14 .fi 15 .SH DESCRIPTION 16 The 17 .B ares_gethostbyname_file 18 function performs a host lookup by name against the system's hosts file (or equivalent local hostname database). 19 The 20 .IR channel 21 parameter is required, but no asynchronous queries are performed. Instead, the 22 lookup is done via the same mechanism used to perform 'f' lookups 23 (see the 24 .I lookups 25 options field in \fIares_init_options(3)\fP). 26 The parameter 27 .I name 28 gives the hostname as a NUL-terminated C string, and 29 .I family 30 gives the desired type of address for the resulting host entry. 31 .PP 32 The return value indicates whether the query succeeded and, if not, how it 33 failed. It may have any of the following values: 34 .TP 19 35 .B ARES_SUCCESS 36 The host lookup completed successfully and 37 .I host 38 now points to the result (and must be freed with \fIares_free_hostent(3)\fP). 39 .TP 19 40 .B ARES_ENOTFOUND 41 The hostname 42 .I name 43 was not found. 44 .TP 19 45 .B ARES_EFILE 46 There was a file I/O error while performing the lookup. 47 .TP 19 48 .B ARES_ENOMEM 49 Memory was exhausted. 50 .PP 51 On successful completion of the query, the pointer pointed to by 52 .I host 53 points to a 54 .B struct hostent 55 containing the address of the host returned by the lookup. The user must 56 free the memory pointed to by 57 .IR host 58 when finished with it by calling \fIares_free_hostent(3)\fP. If the lookup did 59 not complete successfully, 60 .I host 61 will be 62 .BR NULL . 63 .SH AVAILABILITY 64 Added in c-ares 1.5.4 65 .SH SEE ALSO 66 .BR ares_gethostbyname (3), 67 .BR ares_free_hostent (3), 68 .BR ares_init_options (3)