lwres/man/lwres_getrrsetbyname.html

	lwres_getrrsetbyname.html revision 2cd182921e1b04ccda0a56995c4cc491c882af04
d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews<!--
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont - Copyright (C) 2004  Internet Systems Consortium, Inc. ("ISC")
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox User - Copyright (C) 2001  Internet Software Consortium.
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox User -
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - Permission to use, copy, modify, and distribute this software for any
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - purpose with or without fee is hereby granted, provided that the above
5347c0fcb04eaea19d9f39795646239f487c6207Tinderbox User - copyright notice and this permission notice appear in all copies.
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont -
d6fa26d0adaec6c910115be34fe7a5a5f402c14fMark Andrews - THE SOFTWARE IS PROVIDED "AS IS" AND ISC DISCLAIMS ALL WARRANTIES WITH
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont - REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont - AND FITNESS.  IN NO EVENT SHALL ISC BE LIABLE FOR ANY SPECIAL, DIRECT,
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont - INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox User - LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont - OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox User - PERFORMANCE OF THIS SOFTWARE.
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont-->
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<!-- $Id: lwres_getrrsetbyname.html,v 1.9 2004/08/23 00:05:48 marka Exp $ -->
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<HTML
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><HEAD
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont><TITLE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>lwres_getrrsetbyname</TITLE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><META
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserNAME="GENERATOR"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserCONTENT="Modular DocBook HTML Stylesheet Version 1.7"></HEAD
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont><BODY
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserCLASS="REFENTRY"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserBGCOLOR="#FFFFFF"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserTEXT="#000000"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserLINK="#0000FF"
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis DupontVLINK="#840084"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserALINK="#0000FF"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><H1
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><A
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserNAME="AEN1"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User></A
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>lwres_getrrsetbyname</H1
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><DIV
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserCLASS="REFNAMEDIV"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><A
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserNAME="AEN8"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User></A
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><H2
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox User>Name</H2
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>lwres_getrrsetbyname, lwres_freerrset&nbsp;--&nbsp;retrieve DNS records</DIV
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><DIV
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox UserCLASS="REFSYNOPSISDIV"
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont><A
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis DupontNAME="AEN12"
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox User></A
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox User><H2
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox User>Synopsis</H2
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox User><DIV
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis DupontCLASS="FUNCSYNOPSIS"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><P
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User></P
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><A
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox UserNAME="AEN13"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User></A
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><PRE
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis DupontCLASS="FUNCSYNOPSISINFO"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>#include &lt;lwres/netdb.h&gt;</PRE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><P
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont><CODE
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont><CODE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserCLASS="FUNCDEF"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>int
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupontlwres_getrrsetbyname</CODE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>(const char *hostname, unsigned int rdclass, unsigned int rdtype, unsigned int flags, struct rrsetinfo **res);</CODE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User></P
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont><P
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont><CODE
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont><CODE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserCLASS="FUNCDEF"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>void
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupontlwres_freerrset</CODE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>(struct rrsetinfo *rrset);</CODE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User></P
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont><P
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont></P
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User></DIV
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><P
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont>The following structures are used:
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<PRE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserCLASS="PROGRAMLISTING"
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont>struct  rdatainfo {
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User        unsigned int            rdi_length;     /* length of data */
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User        unsigned char           *rdi_data;      /* record data */
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont};
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Userstruct  rrsetinfo {
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont        unsigned int            rri_flags;      /* RRSET_VALIDATED... */
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User        unsigned int            rri_rdclass;    /* class number */
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User        unsigned int            rri_rdtype;     /* RR type number */
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont        unsigned int            rri_ttl;        /* time to live */
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User        unsigned int            rri_nrdatas;    /* size of rdatas array */
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User        unsigned int            rri_nsigs;      /* size of sigs array */
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont        char                    *rri_name;      /* canonical name */
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox User        struct rdatainfo        *rri_rdatas;    /* individual records */
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User        struct rdatainfo        *rri_sigs;      /* individual signatures */
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User};</PRE
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont></P
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User></DIV
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><DIV
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserCLASS="REFSECT1"
33d0a7767d53cb366039fd0ac4f63cf8a9c351b0Tinderbox User><A
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserNAME="AEN29"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User></A
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><H2
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>DESCRIPTION</H2
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><P
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User><CODE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox UserCLASS="FUNCTION"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>lwres_getrrsetbyname()</CODE
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox Usergets a set of resource records associated with a
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User<VAR
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis DupontCLASS="PARAMETER"
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>hostname</VAR
7911e6f9de303bca5a3d8b34f4330c8f7cecffaeTinderbox User>,
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont
b091b4bb803b830d2d5a9e71b6648b669655d7dcFrancis Dupont<VAR
CLASS="PARAMETER"
>class</VAR
>,

and
<VAR
CLASS="PARAMETER"
>type</VAR
>.

<VAR
CLASS="PARAMETER"
>hostname</VAR
>
is
a pointer a to null-terminated string.  The
<VAR
CLASS="PARAMETER"
>flags</VAR
>
field is currently unused and must be zero.</P
><P
>After a successful call to
<CODE
CLASS="FUNCTION"
>lwres_getrrsetbyname()</CODE
>,

<VAR
CLASS="PARAMETER"
>*res</VAR
>
is a pointer to an
<SPAN
CLASS="TYPE"
>rrsetinfo</SPAN
>
structure, containing a list of one or more
<SPAN
CLASS="TYPE"
>rdatainfo</SPAN
>
structures containing resource records and potentially another list of
<SPAN
CLASS="TYPE"
>rdatainfo</SPAN
>
structures containing SIG resource records
associated with those records.
The members
<CODE
CLASS="CONSTANT"
>rri_rdclass</CODE
>
and
<CODE
CLASS="CONSTANT"
>rri_rdtype</CODE
>
are copied from the parameters.
<CODE
CLASS="CONSTANT"
>rri_ttl</CODE
>
and
<CODE
CLASS="CONSTANT"
>rri_name</CODE
>
are properties of the obtained rrset.
The resource records contained in
<CODE
CLASS="CONSTANT"
>rri_rdatas</CODE
>
and
<CODE
CLASS="CONSTANT"
>rri_sigs</CODE
>
are in uncompressed DNS wire format.
Properties of the rdataset are represented in the
<CODE
CLASS="CONSTANT"
>rri_flags</CODE
>
bitfield.  If the RRSET_VALIDATED bit is set, the data has been DNSSEC
validated and the signatures verified.  </P
><P
>All of the information returned by
<CODE
CLASS="FUNCTION"
>lwres_getrrsetbyname()</CODE
>
is dynamically allocated: the
<CODE
CLASS="CONSTANT"
>rrsetinfo</CODE
>
and
<CODE
CLASS="CONSTANT"
>rdatainfo</CODE
>
structures,
and the canonical host name strings pointed to by the
<CODE
CLASS="CONSTANT"
>rrsetinfo</CODE
>structure.

Memory allocated for the dynamically allocated structures created by
a successful call to
<CODE
CLASS="FUNCTION"
>lwres_getrrsetbyname()</CODE
>
is released by
<CODE
CLASS="FUNCTION"
>lwres_freerrset()</CODE
>.

<VAR
CLASS="PARAMETER"
>rrset</VAR
>
is a pointer to a
<SPAN
CLASS="TYPE"
>struct rrset</SPAN
>
created by a call to
<CODE
CLASS="FUNCTION"
>lwres_getrrsetbyname()</CODE
>.&#13;</P
><P
></P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN62"
></A
><H2
>RETURN VALUES</H2
><P
><CODE
CLASS="FUNCTION"
>lwres_getrrsetbyname()</CODE
>
returns zero on success, and one of the following error
codes if an error occurred:
<P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
><CODE
CLASS="CONSTANT"
>ERRSET_NONAME</CODE
></DT
><DD
><P
>the name does not exist</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>ERRSET_NODATA</CODE
></DT
><DD
><P
>the name exists, but does not have data of the desired type</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>ERRSET_NOMEMORY</CODE
></DT
><DD
><P
>memory could not be allocated</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>ERRSET_INVAL</CODE
></DT
><DD
><P
>a parameter is invalid</P
></DD
><DT
><CODE
CLASS="CONSTANT"
>ERRSET_FAIL</CODE
></DT
><DD
><P
>other failure</P
></DD
><DT
><CODE
CLASS="CONSTANT"
></CODE
></DT
><DD
><P
></P
></DD
></DL
></DIV
>&#13;</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN97"
></A
><H2
>SEE ALSO</H2
><P
><SPAN
CLASS="CITEREFENTRY"
><SPAN
CLASS="REFENTRYTITLE"
>lwres</SPAN
>(3)</SPAN
>.</P
></DIV
></BODY
></HTML
>