<refentry id="pango-Version-Checking">
<refmeta>
<refentrytitle role="top_of_page">Version Checking</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>PANGO Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Version Checking</refname>
<refpurpose>Tools for checking Pango version at compile- and run-time.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>



#define             <link linkend="PANGO-VERSION-ENCODE:CAPS">PANGO_VERSION_ENCODE</link>                (major, minor, micro)
#define             <link linkend="PANGO-VERSION:CAPS">PANGO_VERSION</link>
#define             <link linkend="PANGO-VERSION-MAJOR:CAPS">PANGO_VERSION_MAJOR</link>
#define             <link linkend="PANGO-VERSION-MINOR:CAPS">PANGO_VERSION_MINOR</link>
#define             <link linkend="PANGO-VERSION-MICRO:CAPS">PANGO_VERSION_MICRO</link>
#define             <link linkend="PANGO-VERSION-STRING:CAPS">PANGO_VERSION_STRING</link>
#define             <link linkend="PANGO-VERSION-CHECK:CAPS">PANGO_VERSION_CHECK</link>                 (major,minor,micro)
<link linkend="int">int</link>                 <link linkend="pango-version">pango_version</link>                       (void);
const <link linkend="char">char</link>*         <link linkend="pango-version-string">pango_version_string</link>                (void);
const <link linkend="char">char</link>*         <link linkend="pango-version-check">pango_version_check</link>                 (<link linkend="int">int</link> required_major,
                                                         <link linkend="int">int</link> required_minor,
                                                         <link linkend="int">int</link> required_micro);
</synopsis>
</refsynopsisdiv>









<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>
The capital-letter macros defined here can be used to check the version of
Pango at compile-time, and to <firstterm>encode</firstterm> Pango versions into
integers.

The functions can be used to check the version of the linked Pango library
at run-time.
</para>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="PANGO-VERSION-ENCODE:CAPS" role="macro"/>PANGO_VERSION_ENCODE()</title>
<indexterm><primary>PANGO_VERSION_ENCODE</primary></indexterm><programlisting>#define             PANGO_VERSION_ENCODE(major, minor, micro)</programlisting>
<para>
This macro encodes the given Pango version into an integer.  The numbers
returned by <link linkend="PANGO-VERSION:CAPS"><literal>PANGO_VERSION</literal></link> and <link linkend="pango-version"><function>pango_version()</function></link> are encoded using this macro.
Two encoded version numbers can be compared as integers.
</para><variablelist role="params">
<varlistentry><term><parameter>major</parameter>&nbsp;:</term>
<listitem><simpara>the major component of the version number
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>minor</parameter>&nbsp;:</term>
<listitem><simpara>the minor component of the version number
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>micro</parameter>&nbsp;:</term>
<listitem><simpara>the micro component of the version number


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION:CAPS" role="macro"/>PANGO_VERSION</title>
<indexterm><primary>PANGO_VERSION</primary></indexterm><programlisting>#define             PANGO_VERSION</programlisting>
<para>
The version of Pango available at compile-time, encoded using
<link linkend="PANGO-VERSION-ENCODE:CAPS"><function>PANGO_VERSION_ENCODE()</function></link>.
</para></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION-MAJOR:CAPS" role="macro"/>PANGO_VERSION_MAJOR</title>
<indexterm><primary>PANGO_VERSION_MAJOR</primary></indexterm><programlisting>#define PANGO_VERSION_MAJOR 1
</programlisting>
<para>
The major component of the version of Pango available at compile-time.
</para></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION-MINOR:CAPS" role="macro"/>PANGO_VERSION_MINOR</title>
<indexterm><primary>PANGO_VERSION_MINOR</primary></indexterm><programlisting>#define PANGO_VERSION_MINOR 18
</programlisting>
<para>
The minor component of the version of Pango available at compile-time.
</para></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION-MICRO:CAPS" role="macro"/>PANGO_VERSION_MICRO</title>
<indexterm><primary>PANGO_VERSION_MICRO</primary></indexterm><programlisting>#define PANGO_VERSION_MICRO 4
</programlisting>
<para>
The micro component of the version of Pango available at compile-time.
</para></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION-STRING:CAPS" role="macro"/>PANGO_VERSION_STRING</title>
<indexterm><primary>PANGO_VERSION_STRING</primary></indexterm><programlisting>#define PANGO_VERSION_STRING "1.18.4"
</programlisting>
<para>
A string literal containing the version of Pango available at compile-time.
</para></refsect2>
<refsect2>
<title><anchor id="PANGO-VERSION-CHECK:CAPS" role="macro"/>PANGO_VERSION_CHECK()</title>
<indexterm><primary>PANGO_VERSION_CHECK</primary></indexterm><programlisting>#define             PANGO_VERSION_CHECK(major,minor,micro)</programlisting>
<para>
Checks that the version of Pango available at compile-time is not older than
the provided version number.
</para><variablelist role="params">
<varlistentry><term><parameter>major</parameter>&nbsp;:</term>
<listitem><simpara>the major component of the version number
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>minor</parameter>&nbsp;:</term>
<listitem><simpara>the minor component of the version number
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>micro</parameter>&nbsp;:</term>
<listitem><simpara>the micro component of the version number


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="pango-version" role="function" condition="since:1.16"/>pango_version ()</title>
<indexterm role="1.16"><primary>pango_version</primary></indexterm><programlisting><link linkend="int">int</link>                 pango_version                       (void);</programlisting>
<para>
This is similar to the macro <link linkend="PANGO-VERSION:CAPS"><literal>PANGO_VERSION</literal></link> except that
it returns the encoded version of Pango available at run-time,
as opposed to the version available at compile-time.
</para>
<para>
A version number can be encoded into an integer using
<link linkend="PANGO-VERSION-ENCODE:CAPS"><function>PANGO_VERSION_ENCODE()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>value: The encoded version of Pango library
  available at run time.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since  1.16
</para></refsect2>
<refsect2>
<title><anchor id="pango-version-string" role="function" condition="since:1.16"/>pango_version_string ()</title>
<indexterm role="1.16"><primary>pango_version_string</primary></indexterm><programlisting>const <link linkend="char">char</link>*         pango_version_string                (void);</programlisting>
<para>
This is similar to the macro <link linkend="PANGO-VERSION-STRING:CAPS"><literal>PANGO_VERSION_STRING</literal></link> except that
it returns the version of Pango available at run-time, as opposed to
the version available at compile-time.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>value: A string containing the version of Pango library
  available at run time.
  The returned string is owned by Pango and should not be modified
  or freed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since  1.16
</para></refsect2>
<refsect2>
<title><anchor id="pango-version-check" role="function" condition="since:1.16"/>pango_version_check ()</title>
<indexterm role="1.16"><primary>pango_version_check</primary></indexterm><programlisting>const <link linkend="char">char</link>*         pango_version_check                 (<link linkend="int">int</link> required_major,
                                                         <link linkend="int">int</link> required_minor,
                                                         <link linkend="int">int</link> required_micro);</programlisting>
<para>
Checks that the Pango library in use is compatible with the
given version. Generally you would pass in the constants
<link linkend="PANGO-VERSION-MAJOR:CAPS"><literal>PANGO_VERSION_MAJOR</literal></link>, <link linkend="PANGO-VERSION-MINOR:CAPS"><literal>PANGO_VERSION_MINOR</literal></link>, <link linkend="PANGO-VERSION-MICRO:CAPS"><literal>PANGO_VERSION_MICRO</literal></link>
as the three arguments to this function; that produces
a check that the library in use at run-time is compatible with
the version of Pango the application or module was compiled against.
</para>
<para>
Compatibility is defined by two things: first the version
of the running library is newer than the version
<parameter>required_major.required_minor</parameter>.<parameter>required_micro</parameter>. Second
the running library must be binary compatible with the
version <parameter>required_major.required_minor</parameter>.<parameter>required_micro</parameter>
(same major version.)
</para>
<para>
For compile-time version checking use <link linkend="PANGO-VERSION-CHECK:CAPS"><function>PANGO_VERSION_CHECK()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>required_major</parameter>&nbsp;:</term>
<listitem><simpara> the required major version.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>required_minor</parameter>&nbsp;:</term>
<listitem><simpara> the required minor version.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>required_micro</parameter>&nbsp;:</term>
<listitem><simpara> the required major version.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> <link linkend="NULL:CAPS"><literal>NULL</literal></link> if the Pango library is compatible with the
  given version, or a string describing the version mismatch.
  The returned string is owned by Pango and should not be modified
  or freed.

</simpara></listitem></varlistentry>
</variablelist><para role="since">Since  1.16
</para></refsect2>

</refsect1>




</refentry>
