Adding upstream version 1:9.11.5.P4+dfsg.upstream/1%9.11.5.P4+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 381 insertions, 0 deletions

diff --git a/lib/lwres/man/lwres_getaddrinfo.docbook b/lib/lwres/man/lwres_getaddrinfo.docbook
new file mode 100644
index 0000000..bfe649a
--- /dev/null
+++ b/lib/lwres/man/lwres_getaddrinfo.docbook
@@ -0,0 +1,381 @@
+<!DOCTYPE book [
+<!ENTITY mdash "&#8212;">]>
+<!--
+ - Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+ -
+ - This Source Code Form is subject to the terms of the Mozilla Public
+ - License, v. 2.0. If a copy of the MPL was not distributed with this
+ - file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ -
+ - See the COPYRIGHT file distributed with this work for additional
+ - information regarding copyright ownership.
+-->
+
+<!-- Converted by db4-upgrade version 1.0 -->
+<refentry xmlns:db="http://docbook.org/ns/docbook" version="5.0">
+  <info>
+    <date>2007-06-18</date>
+  </info>
+  <refentryinfo>
+    <corpname>ISC</corpname>
+    <corpauthor>Internet Systems Consortium, Inc.</corpauthor>
+  </refentryinfo>
+
+  <refmeta>
+    <refentrytitle>lwres_getaddrinfo</refentrytitle>
+    <manvolnum>3</manvolnum>
+    <refmiscinfo>BIND9</refmiscinfo>
+  </refmeta>
+
+  <docinfo>
+    <copyright>
+      <year>2000</year>
+      <year>2001</year>
+      <year>2003</year>
+      <year>2004</year>
+      <year>2005</year>
+      <year>2007</year>
+      <year>2014</year>
+      <year>2015</year>
+      <year>2016</year>
+      <year>2018</year>
+      <year>2019</year>
+      <holder>Internet Systems Consortium, Inc. ("ISC")</holder>
+    </copyright>
+  </docinfo>
+
+  <refnamediv>
+    <refname>lwres_getaddrinfo</refname>
+    <refname>lwres_freeaddrinfo</refname>
+    <refpurpose>socket address structure to host and service name</refpurpose>
+  </refnamediv>
+  <refsynopsisdiv>
+    <funcsynopsis>
+<funcsynopsisinfo>#include &lt;lwres/netdb.h&gt;</funcsynopsisinfo>
+<funcprototype>
+        <funcdef>
+int
+<function>lwres_getaddrinfo</function></funcdef>
+        <paramdef>const char *<parameter>hostname</parameter></paramdef>
+        <paramdef>const char *<parameter>servname</parameter></paramdef>
+        <paramdef>const struct addrinfo *<parameter>hints</parameter></paramdef>
+        <paramdef>struct addrinfo **<parameter>res</parameter></paramdef>
+        </funcprototype>
+<funcprototype>
+        <funcdef>
+void
+<function>lwres_freeaddrinfo</function></funcdef>
+        <paramdef>struct addrinfo *<parameter>ai</parameter></paramdef>
+      </funcprototype>
+</funcsynopsis>
+
+    <para>
+      If the operating system does not provide a
+      <type>struct addrinfo</type>,
+      the following structure is used:
+    </para>
+    <para><programlisting>
+struct  addrinfo {
+        int             ai_flags;       /* AI_PASSIVE, AI_CANONNAME */
+        int             ai_family;      /* PF_xxx */
+        int             ai_socktype;    /* SOCK_xxx */
+        int             ai_protocol;    /* 0 or IPPROTO_xxx for IPv4 and IPv6 */
+        size_t          ai_addrlen;     /* length of ai_addr */
+        char            *ai_canonname;  /* canonical name for hostname */
+        struct sockaddr *ai_addr;       /* binary address */
+        struct addrinfo *ai_next;       /* next structure in linked list */
+};
+</programlisting>
+    </para>
+
+  </refsynopsisdiv>
+
+  <refsection><info><title>DESCRIPTION</title></info>
+
+
+    <para><function>lwres_getaddrinfo()</function>
+      is used to get a list of IP addresses and port numbers for host
+      <parameter>hostname</parameter> and service
+      <parameter>servname</parameter>.
+
+      The function is the lightweight resolver's implementation of
+      <function>getaddrinfo()</function> as defined in RFC2133.
+      <parameter>hostname</parameter> and
+      <parameter>servname</parameter> are pointers to null-terminated
+      strings or <type>NULL</type>.
+
+      <parameter>hostname</parameter> is either a host name or a
+      numeric host address string: a dotted decimal IPv4 address or an
+      IPv6 address.  <parameter>servname</parameter> is either a
+      decimal port number or a service name as listed in
+      <filename>/etc/services</filename>.
+    </para>
+
+    <para><parameter>hints</parameter>
+      is an optional pointer to a
+      <type>struct addrinfo</type>.
+      This structure can be used to provide hints concerning the type of
+      socket
+      that the caller supports or wishes to use.
+      The caller can supply the following structure elements in
+      <parameter>*hints</parameter>:
+
+      <variablelist>
+        <varlistentry>
+          <term><constant>ai_family</constant></term>
+          <listitem>
+            <para>
+              The protocol family that should be used.
+              When
+              <constant>ai_family</constant>
+              is set to
+              <type>PF_UNSPEC</type>,
+              it means the caller will accept any protocol family supported by
+              the
+              operating system.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><constant>ai_socktype</constant></term>
+          <listitem>
+            <para>
+              denotes the type of socket &mdash;
+              <type>SOCK_STREAM</type>,
+              <type>SOCK_DGRAM</type>
+              or
+              <type>SOCK_RAW</type>
+              &mdash; that is wanted.
+              When
+              <constant>ai_socktype</constant>
+              is zero the caller will accept any socket type.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><constant>ai_protocol</constant></term>
+          <listitem>
+            <para>
+              indicates which transport protocol is wanted: IPPROTO_UDP or
+              IPPROTO_TCP.
+              If
+              <constant>ai_protocol</constant>
+              is zero the caller will accept any protocol.
+            </para>
+          </listitem>
+        </varlistentry>
+        <varlistentry>
+          <term><constant>ai_flags</constant></term>
+          <listitem>
+            <para>
+              Flag bits.
+              If the
+              <type>AI_CANONNAME</type>
+              bit is set, a successful call to
+              <function>lwres_getaddrinfo()</function>
+              will return a null-terminated string containing the canonical
+              name
+              of the specified hostname in
+              <constant>ai_canonname</constant>
+              of the first
+              <type>addrinfo</type>
+              structure returned.
+              Setting the
+              <type>AI_PASSIVE</type>
+              bit indicates that the returned socket address structure is
+              intended
+              for used in a call to
+              <citerefentry>
+                <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
+              </citerefentry>.
+
+              In this case, if the hostname argument is a
+              <type>NULL</type>
+              pointer, then the IP address portion of the socket
+              address structure will be set to
+              <type>INADDR_ANY</type>
+              for an IPv4 address or
+              <type>IN6ADDR_ANY_INIT</type>
+              for an IPv6 address.
+            </para>
+            <para>
+              When
+              <constant>ai_flags</constant>
+              does not set the
+              <type>AI_PASSIVE</type>
+              bit, the returned socket address structure will be ready
+              for use in a call to
+              <citerefentry>
+                <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
+              </citerefentry>
+              for a connection-oriented protocol or
+              <citerefentry>
+                <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
+              </citerefentry>,
+
+              <citerefentry>
+                <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
+              </citerefentry>,
+
+              or
+              <citerefentry>
+                <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
+              </citerefentry>
+              if a connectionless protocol was chosen.
+              The IP address portion of the socket address structure will be
+              set to the loopback address if
+              <parameter>hostname</parameter>
+              is a
+              <type>NULL</type>
+              pointer and
+              <type>AI_PASSIVE</type>
+              is not set in
+              <constant>ai_flags</constant>.
+            </para>
+            <para>
+              If
+              <constant>ai_flags</constant>
+              is set to
+              <type>AI_NUMERICHOST</type>
+              it indicates that
+              <parameter>hostname</parameter>
+              should be treated as a numeric string defining an IPv4 or IPv6
+              address
+              and no name resolution should be attempted.
+            </para>
+          </listitem>
+        </varlistentry>
+      </variablelist>
+    </para>
+
+    <para>
+      All other elements of the <type>struct addrinfo</type> passed
+      via <parameter>hints</parameter> must be zero.
+    </para>
+
+    <para>
+      A <parameter>hints</parameter> of <type>NULL</type> is
+      treated as if
+      the caller provided a <type>struct addrinfo</type> initialized to zero
+      with <constant>ai_family</constant>set to
+      <constant>PF_UNSPEC</constant>.
+    </para>
+
+    <para>
+      After a successful call to
+      <function>lwres_getaddrinfo()</function>,
+      <parameter>*res</parameter>
+      is a pointer to a linked list of one or more
+      <type>addrinfo</type>
+      structures.
+      Each
+      <type>struct addrinfo</type>
+      in this list cn be processed by following
+      the
+      <constant>ai_next</constant>
+      pointer, until a
+      <type>NULL</type>
+      pointer is encountered.
+      The three members
+      <constant>ai_family</constant>,
+      <constant>ai_socktype</constant>,
+      and
+      <constant>ai_protocol</constant>
+      in each
+      returned
+      <type>addrinfo</type>
+      structure contain the corresponding arguments for a call to
+      <citerefentry>
+        <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
+      </citerefentry>.
+      For each
+      <type>addrinfo</type>
+      structure in the list, the
+      <constant>ai_addr</constant>
+      member points to a filled-in socket address structure of length
+      <constant>ai_addrlen</constant>.
+    </para>
+
+    <para>
+      All of the information returned by
+      <function>lwres_getaddrinfo()</function>
+      is dynamically allocated: the addrinfo structures, and the socket
+      address structures and canonical host name strings pointed to by the
+      <constant>addrinfo</constant>structures.
+      Memory allocated for the dynamically allocated structures created by
+      a successful call to
+      <function>lwres_getaddrinfo()</function>
+      is released by
+      <function>lwres_freeaddrinfo()</function>.
+      <parameter>ai</parameter>
+      is a pointer to a
+      <type>struct addrinfo</type>
+      created by a call to
+      <function>lwres_getaddrinfo()</function>.
+    </para>
+
+  </refsection>
+
+  <refsection><info><title>RETURN VALUES</title></info>
+
+
+    <para><function>lwres_getaddrinfo()</function>
+      returns zero on success or one of the error codes listed in
+      <citerefentry>
+        <refentrytitle>gai_strerror</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>
+      if an error occurs.  If both <parameter>hostname</parameter> and
+      <parameter>servname</parameter> are <type>NULL</type>
+      <function>lwres_getaddrinfo()</function> returns
+      <errorcode>EAI_NONAME</errorcode>.
+    </para>
+  </refsection>
+  <refsection><info><title>SEE ALSO</title></info>
+
+    <para><citerefentry>
+        <refentrytitle>lwres</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>lwres_getaddrinfo</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>lwres_freeaddrinfo</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>lwres_gai_strerror</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>RFC2133</refentrytitle>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>getservbyname</refentrytitle><manvolnum>3</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>bind</refentrytitle><manvolnum>2</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>connect</refentrytitle><manvolnum>2</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>sendto</refentrytitle><manvolnum>2</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>sendmsg</refentrytitle><manvolnum>2</manvolnum>
+      </citerefentry>,
+
+      <citerefentry>
+        <refentrytitle>socket</refentrytitle><manvolnum>2</manvolnum>
+      </citerefentry>.
+    </para>
+
+  </refsection>
+</refentry>