.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "val_gethostbyname 3" .TH val_gethostbyname 3 "2013-01-02" "perl v5.18.1" "Programmer's Manual" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" val_gethostbyname(), val_gethostbyname2(), val_gethostbyname_r(), val_gethostbyname2_r() \- get DNSSEC\-validated network host entry .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& extern int h_errno; \& struct hostent *val_gethostbyname(const val_context_t *ctx, \& const char *name, \& val_status_t *val_status); \& \& struct hostent *val_gethostbyname2(const val_context_t *ctx, \& const char *name, \& int af, \& val_status_t *val_status); \& \& int val_gethostbyname_r(const val_context_t *ctx, \& const char *name, \& struct hostent *ret, \& char *buf, \& size_t buflen, \& struct hostent **result, \& int *h_errnop, \& val_status_t *val_status); \& \& int val_gethostbyname2_r(const val_context_t *ctx, \& const char *name, \& int af, \& struct hostent *ret, \& char *buf, \& size_t buflen, \& struct hostent **result, \& int *h_errnop, \& val_status_t *val_status); \& \& struct hostent *val_gethostbyaddr(val_context_t * ctx, \& const char *addr, \& int len, \& int type, \& val_status_t * val_status); \& \& int val_gethostbyaddr_r(val_context_t * ctx, \& const char *addr, \& int len, \& int type, \& struct hostent *ret, \& char *buf, \& int buflen, \& struct hostent **result, \& int *h_errnop, \& val_status_t * val_status); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fI\fIval_gethostbyname()\fI\fR, \fI\fIval_gethostbyname2()\fI\fR, \fI\fIval_gethostbyname_r()\fI\fR, \&\fI\fIval_gethostbyname2_r()\fI\fR, \fI\fIval_gethostbyaddr()\fI\fR and \fI\fIval_gethostbyaddr_r()\fI\fR perform \s-1DNSSEC\s0 validation of \s-1DNS\s0 queries. They return a network host entry value of type struct \fIhostent\fR and are DNSSEC-aware versions of the \fI\fIgethostbyname\fI\|(3)\fR, \fI\fIgethostbyname2\fI\|(3)\fR, \fI\fIgethostbyname_r()\fI\fR, \&\fI\fIgethostbyname2_r()\fI\fR, \fI\fIgethostbyaddr()\fI\fR and \fI\fIgethostbyaddr_r()\fI\fR functions respectively. (See \fI\fIgethostbyname\fI\|(3)\fR for more information on type struct \&\fIhostent\fR). .PP \&\fI\fIval_gethostbyname()\fI\fR, \fI\fIval_gethostbyname_r()\fI\fR, \fI\fIval_gethostbyaddr()\fI\fR, and \&\fI\fIval_gethostbyaddr_r()\fI\fR support only IPv4 addresses. \&\fI\fIval_gethostbyname2()\fI\fR and \fI\fIval_gethostbyname2_r()\fI\fR support both IPv4 and IPv6 addresses. .PP The \fI\fIval_gethostbyname_r()\fI\fR, \fI\fIval_gethostbyname2_r()\fI\fR and \&\fI\fIval_gethostbyaddr_r()\fI\fR functions are reentrant versions and can be safely used in multi-threaded applications. .PP The \fIctx\fR parameter specifies the validation context, which can be set to \&\s-1NULL\s0 for default values (see \fI\fIlibval\fI\|(3)\fR and \fIdnsval.conf\fR for more details on validation contexts and validation policy). .PP \&\fI\fIval_gethostbyname()\fI\fR, \fI\fIval_gethostbyname2()\fI\fR and \fI\fIval_gethostbyaddr()\fI\fR set the global \fIh_errno\fR variable to return the resolver error code. The reentrant versions \fI\fIval_gethostbyname_r()\fI\fR, \fI\fIval_gethostbyname2_r()\fI\fR and \&\fI\fIval_gethostbyaddr_r()\fI\fR use the \fIh_errnop\fR parameter to return this value. This ensures thread safety, by avoiding the global \fIh_errno\fR variable. \&\fIh_errnop\fR must not be \s-1NULL. \s0(See the man page for \fI\fIgethostbyname\fI\|(3)\fR for possible values of \fIh_errno\fR.) .PP The \fIname\fR, \fIaf\fR, \fIret\fR, \fIbuf\fR, \fIbuflen\fR, and \fIresult\fR parameters have the same syntax and semantics as the corresponding parameters for the original \&\fIgethostbyname*()\fR and \fIgethostbyaddr*()\fR functions. See the manual page for \fI\fIgethostbyname\fI\|(3)\fR for more details about these parameters. .PP The \fIval_status\fR parameter is used to return the validator error code and must not be \s-1NULL. \s0\fI\fIval_istrusted()\fI\fR and \fI\fIval_isvalidated()\fI\fR can be used to determine the trustworthiness of data and \fI\fIp_val_status()\fI\fR can be used to display the status value to the user in \s-1ASCII\s0 format (See \fI\fIlibval\fI\|(3)\fR more for information). .SH "RETURN VALUES" .IX Header "RETURN VALUES" The \fI\fIval_gethostbyname()\fI\fR, \fI\fIval_gethostbyname2()\fI\fR, and \&\fI\fIval_gethostbyaddr()\fI\fR functions return a pointer to a \fIhostent\fR structure when they can resolve the given host name (with or without \s-1DNSSEC\s0 validation), and \s-1NULL\s0 if data was not available. The memory for the returned value is statically allocated by these two functions. Hence, the caller must not free the memory for the returned value. .PP The \fI\fIval_gethostbyname_r()\fI\fR, \fI\fIval_gethostbyname2_r()\fI\fR and \&\fI\fIval_gethostbyaddr_r()\fI\fR functions return 0 when they can resolve the given host name (with or without \s-1DNSSEC\s0 validation), and a non-zero error-code on failure. .PP The \fI\fIval_gethostbyaddr()\fI\fR and \fI\fIval_gethostbyaddr_r()\fI\fR functions return 0 when they can resolve the given host name (with or without \s-1DNSSEC\s0 validation), and a non-zero error-code on failure. .PP The \fIval_status\fR parameter gives an indication for trustworthiness of data. If the returned \fIhostent\fR structure is \s-1NULL,\s0 this value gives an indication of whether the non-existence of data can be trusted or not. .SH "EXAMPLE" .IX Header "EXAMPLE" .Vb 3 \& #include \& #include \& #include \& \& int main(int argc, char *argv[]) \& { \& int val_status; \& struct hostent *h = NULL; \& \& if (argc < 2) { \& printf("Usage: %s \en", argv[0]); \& exit(1); \& } \& \& h = val_gethostbyname(NULL, argv[1], &val_status); \& printf("h_errno = %d [%s]\en", h_errno, \& hstrerror(h_errno)); \& if (h) { \& printf("Validation Status = %d [%s]\en", val_status, \& p_val_status(val_status)); \& } \& \& return 0; \& } .Ve .SH "NOTES" .IX Header "NOTES" These functions do not currently read the order of lookup from \&\fB/etc/hosts.conf\fR. At present, the default order is set to consult the \&\fB/etc/hosts\fR file first and then query \s-1DNS.\s0 .PP The current versions of these functions do not support \s-1NIS\s0 lookups. .SH "COPYRIGHT" .IX Header "COPYRIGHT" Copyright 2004\-2013 \s-1SPARTA,\s0 Inc. All rights reserved. See the \s-1COPYING\s0 file included with the DNSSEC-Tools package for details. .SH "AUTHORS" .IX Header "AUTHORS" Abhijit Hayatnagarkar, Suresh Krishnaswamy. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fI\fIgethostbyname\fI\|(3)\fR, \fI\fIgethostbyname2\fI\|(3)\fR, \fI\fIgethostbyname_r\fI\|(3)\fR, \&\fI\fIgethostbyname2_r\fI\|(3)\fR .PP \&\fI\fIval_getaddrinfo\fI\|(3)\fR, \fI\fIval_res_query\fI\|(3)\fR .PP \&\fI\fIlibval\fI\|(3)\fR .PP http://www.dnssec\-tools.org