<?xml version="1.0"?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<refentry id="libedataserver-e-util">
<refmeta>
<refentrytitle role="top_of_page">Utility Functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>LIBEDATASERVER Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Utility Functions</refname>
<refpurpose>Miscellaneous utility functions for evolution-data-server.</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

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

<synopsis>



struct      <link linkend="tm">tm</link>;
<link linkend="int">int</link>         <link linkend="e-util-mkdir-hier">e_util_mkdir_hier</link>               (const <link linkend="char">char</link> *path,
                                             <link linkend="mode-t">mode_t</link> mode);
<link linkend="gchar">gchar</link>*      <link linkend="e-util-strstrcase">e_util_strstrcase</link>               (const <link linkend="gchar">gchar</link> *haystack,
                                             const <link linkend="gchar">gchar</link> *needle);
<link linkend="gchar">gchar</link>*      <link linkend="e-util-unicode-get-utf8">e_util_unicode_get_utf8</link>         (const <link linkend="gchar">gchar</link> *text,
                                             <link linkend="gunichar">gunichar</link> *out);
const <link linkend="gchar">gchar</link>* <link linkend="e-util-utf8-strstrcase">e_util_utf8_strstrcase</link>         (const <link linkend="gchar">gchar</link> *haystack,
                                             const <link linkend="gchar">gchar</link> *needle);
const <link linkend="gchar">gchar</link>* <link linkend="e-util-utf8-strstrcasedecomp">e_util_utf8_strstrcasedecomp</link>   (const <link linkend="gchar">gchar</link> *haystack,
                                             const <link linkend="gchar">gchar</link> *needle);
<link linkend="int">int</link>         <link linkend="e-util-utf8-strcasecmp">e_util_utf8_strcasecmp</link>          (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2);
<link linkend="guint64">guint64</link>     <link linkend="e-util-pthread-id">e_util_pthread_id</link>               (<link linkend="pthread-t">pthread_t</link> t);
<link linkend="void">void</link>        <link linkend="e-filename-make-safe">e_filename_make_safe</link>            (<link linkend="gchar">gchar</link> *string);
<link linkend="size-t">size_t</link>      <link linkend="e-utf8-strftime">e_utf8_strftime</link>                 (<link linkend="char">char</link> *s,
                                             <link linkend="size-t">size_t</link> max,
                                             const <link linkend="char">char</link> *fmt,
                                             const <link linkend="struct-tm">struct tm</link> *tm);
<link linkend="size-t">size_t</link>      <link linkend="e-strftime">e_strftime</link>                      (<link linkend="char">char</link> *s,
                                             <link linkend="size-t">size_t</link> max,
                                             const <link linkend="char">char</link> *fmt,
                                             const <link linkend="struct-tm">struct tm</link> *tm);
const <link linkend="char">char</link>* <link linkend="e-util-get-prefix">e_util_get_prefix</link>               (void);
const <link linkend="char">char</link>* <link linkend="e-util-get-cp-prefix">e_util_get_cp_prefix</link>            (void);
const <link linkend="char">char</link>* <link linkend="e-util-get-localedir">e_util_get_localedir</link>            (void);
<link linkend="char">char</link>*       <link linkend="e-util-replace-prefix">e_util_replace_prefix</link>           (const <link linkend="char">char</link> *configure_time_prefix,
                                             const <link linkend="char">char</link> *runtime_prefix,
                                             const <link linkend="char">char</link> *configure_time_path);
</synopsis>
</refsynopsisdiv>









<refsect1 role="desc">
<title role="desc.title">Description</title>
<para>

</para>
</refsect1>

<refsect1 role="details">
<title role="details.title">Details</title>
<refsect2>
<title><anchor id="tm" role="struct"/>struct tm</title>
<indexterm><primary>tm</primary></indexterm><programlisting>struct tm;</programlisting>
<para>

</para></refsect2>
<refsect2>
<title><anchor id="e-util-mkdir-hier" role="function"/>e_util_mkdir_hier ()</title>
<indexterm><primary>e_util_mkdir_hier</primary></indexterm><programlisting><link linkend="int">int</link>         e_util_mkdir_hier               (const <link linkend="char">char</link> *path,
                                             <link linkend="mode-t">mode_t</link> mode);</programlisting>
<para>
Creates a directory hierarchy based on the string <parameter>path</parameter>. If <parameter>path</parameter>
is an absolute path, the directories will be created relative to
the root of the file system; otherwise, the directories will be
created relative to the current directory.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>path</parameter>&nbsp;:</term>
<listitem><simpara> The directory hierarchy to create.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>mode</parameter>&nbsp;:</term>
<listitem><simpara> The permissions to use for the directories.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> 0 on success; -1 on failure.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-util-strstrcase" role="function"/>e_util_strstrcase ()</title>
<indexterm><primary>e_util_strstrcase</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*      e_util_strstrcase               (const <link linkend="gchar">gchar</link> *haystack,
                                             const <link linkend="gchar">gchar</link> *needle);</programlisting>
<para>
Find the first instance of <parameter>needle</parameter> in <parameter>haystack</parameter>, ignoring case for
bytes that are ASCII characters.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>haystack</parameter>&nbsp;:</term>
<listitem><simpara> The string to search in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>needle</parameter>&nbsp;:</term>
<listitem><simpara> The string to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A pointer to the start of <parameter>needle</parameter> in <parameter>haystack</parameter>, or NULL if
         <parameter>needle</parameter> is not found.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-util-unicode-get-utf8" role="function"/>e_util_unicode_get_utf8 ()</title>
<indexterm><primary>e_util_unicode_get_utf8</primary></indexterm><programlisting><link linkend="gchar">gchar</link>*      e_util_unicode_get_utf8         (const <link linkend="gchar">gchar</link> *text,
                                             <link linkend="gunichar">gunichar</link> *out);</programlisting>
<para>
Get a UTF-8 character from the beginning of <parameter>text</parameter>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>text</parameter>&nbsp;:</term>
<listitem><simpara> The string to take the UTF-8 character from.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>out</parameter>&nbsp;:</term>
<listitem><simpara> The location to store the UTF-8 character in.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A pointer to the next character in <parameter>text</parameter> after <parameter>out</parameter>. 
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-util-utf8-strstrcase" role="function"/>e_util_utf8_strstrcase ()</title>
<indexterm><primary>e_util_utf8_strstrcase</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* e_util_utf8_strstrcase         (const <link linkend="gchar">gchar</link> *haystack,
                                             const <link linkend="gchar">gchar</link> *needle);</programlisting>
<para>
Find the first instance of <parameter>needle</parameter> in <parameter>haystack</parameter>, ignoring case. (No
proper case folding or decomposing is done.) Both <parameter>needle</parameter> and
<parameter>haystack</parameter> are UTF-8 strings.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>haystack</parameter>&nbsp;:</term>
<listitem><simpara> The string to search in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>needle</parameter>&nbsp;:</term>
<listitem><simpara> The string to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A pointer to the first instance of <parameter>needle</parameter> in <parameter>haystack</parameter>, or
         <link linkend="NULL:CAPS"><literal>NULL</literal></link> if no match is found, or if either of the strings are
         not legal UTF-8 strings.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-util-utf8-strstrcasedecomp" role="function"/>e_util_utf8_strstrcasedecomp ()</title>
<indexterm><primary>e_util_utf8_strstrcasedecomp</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* e_util_utf8_strstrcasedecomp   (const <link linkend="gchar">gchar</link> *haystack,
                                             const <link linkend="gchar">gchar</link> *needle);</programlisting>
<para>
Find the first instance of <parameter>needle</parameter> in <parameter>haystack</parameter>, where both <parameter>needle</parameter>
and <parameter>haystack</parameter> are UTF-8 strings. Both strings are stripped and
decomposed for comparison, and case is ignored.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>haystack</parameter>&nbsp;:</term>
<listitem><simpara> The string to search in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>needle</parameter>&nbsp;:</term>
<listitem><simpara> The string to search for.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A pointer to the first instance of <parameter>needle</parameter> in <parameter>haystack</parameter>, or
         <link linkend="NULL:CAPS"><literal>NULL</literal></link> if either of the strings are not legal UTF-8 strings.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-util-utf8-strcasecmp" role="function"/>e_util_utf8_strcasecmp ()</title>
<indexterm><primary>e_util_utf8_strcasecmp</primary></indexterm><programlisting><link linkend="int">int</link>         e_util_utf8_strcasecmp          (const <link linkend="gchar">gchar</link> *s1,
                                             const <link linkend="gchar">gchar</link> *s2);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>s1</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>s2</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-util-pthread-id" role="function"/>e_util_pthread_id ()</title>
<indexterm><primary>e_util_pthread_id</primary></indexterm><programlisting><link linkend="guint64">guint64</link>     e_util_pthread_id               (<link linkend="pthread-t">pthread_t</link> t);</programlisting>
<para>
Returns a 64-bit integer hopefully uniquely identifying the
thread. To be used in debugging output and logging only. To test
whether two pthread_t values refer to the same thread, use
<link linkend="pthread-equal"><function>pthread_equal()</function></link>.
</para>
<para>
There is no guarantee that calling <link linkend="e-util-pthread-id"><function>e_util_pthread_id()</function></link> on one
thread first and later after that thread has dies on another won't
return the same integer.
</para>
<para>
On some platforms it might even be that when called two times on
the same thread's pthread_t (with some pthread API calls inbetween)
we will return different values (this of course makes this function
rather useless on such platforms).
</para>
<para>
On Linux and Win32, known to really return a unique id for each
thread existing at a certain time. No guarantee that ids won't be
reused after a thread has terminated, though.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>t</parameter>&nbsp;:</term>
<listitem><simpara> A pthread_t value
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> A 64-bit integer.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-filename-make-safe" role="function"/>e_filename_make_safe ()</title>
<indexterm><primary>e_filename_make_safe</primary></indexterm><programlisting><link linkend="void">void</link>        e_filename_make_safe            (<link linkend="gchar">gchar</link> *string);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>string</parameter>&nbsp;:</term>
<listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-utf8-strftime" role="function"/>e_utf8_strftime ()</title>
<indexterm><primary>e_utf8_strftime</primary></indexterm><programlisting><link linkend="size-t">size_t</link>      e_utf8_strftime                 (<link linkend="char">char</link> *s,
                                             <link linkend="size-t">size_t</link> max,
                                             const <link linkend="char">char</link> *fmt,
                                             const <link linkend="struct-tm">struct tm</link> *tm);</programlisting>
<para>
The UTF-8 equivalent of <link linkend="e-strftime"><function>e_strftime()</function></link>.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>s</parameter>&nbsp;:</term>
<listitem><simpara> The string array to store the result in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max</parameter>&nbsp;:</term>
<listitem><simpara> The size of array <parameter>s</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fmt</parameter>&nbsp;:</term>
<listitem><simpara> The formatting to use on <parameter>tm</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>tm</parameter>&nbsp;:</term>
<listitem><simpara> The time value to format.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> The number of characters placed in <parameter>s</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-strftime" role="function"/>e_strftime ()</title>
<indexterm><primary>e_strftime</primary></indexterm><programlisting><link linkend="size-t">size_t</link>      e_strftime                      (<link linkend="char">char</link> *s,
                                             <link linkend="size-t">size_t</link> max,
                                             const <link linkend="char">char</link> *fmt,
                                             const <link linkend="struct-tm">struct tm</link> *tm);</programlisting>
<para>
This function is a wrapper around the strftime(3) function, which
converts the &amp;percnt;l and &amp;percnt;k (12h and 24h) format variables if necessary.</para>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>s</parameter>&nbsp;:</term>
<listitem><simpara> The string array to store the result in.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>max</parameter>&nbsp;:</term>
<listitem><simpara> The size of array <parameter>s</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>fmt</parameter>&nbsp;:</term>
<listitem><simpara> The formatting to use on <parameter>tm</parameter>.
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>tm</parameter>&nbsp;:</term>
<listitem><simpara> The time value to format.
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara> The number of characters placed in <parameter>s</parameter>.
</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-util-get-prefix" role="function"/>e_util_get_prefix ()</title>
<indexterm><primary>e_util_get_prefix</primary></indexterm><programlisting>const <link linkend="char">char</link>* e_util_get_prefix               (void);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-util-get-cp-prefix" role="function"/>e_util_get_cp_prefix ()</title>
<indexterm><primary>e_util_get_cp_prefix</primary></indexterm><programlisting>const <link linkend="char">char</link>* e_util_get_cp_prefix            (void);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-util-get-localedir" role="function"/>e_util_get_localedir ()</title>
<indexterm><primary>e_util_get_localedir</primary></indexterm><programlisting>const <link linkend="char">char</link>* e_util_get_localedir            (void);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>
<refsect2>
<title><anchor id="e-util-replace-prefix" role="function"/>e_util_replace_prefix ()</title>
<indexterm><primary>e_util_replace_prefix</primary></indexterm><programlisting><link linkend="char">char</link>*       e_util_replace_prefix           (const <link linkend="char">char</link> *configure_time_prefix,
                                             const <link linkend="char">char</link> *runtime_prefix,
                                             const <link linkend="char">char</link> *configure_time_path);</programlisting>
<para>

</para><variablelist role="params">
<varlistentry><term><parameter>configure_time_prefix</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>runtime_prefix</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><parameter>configure_time_path</parameter>&nbsp;:</term>
<listitem><simpara>
</simpara></listitem></varlistentry>
<varlistentry><term><emphasis>Returns</emphasis>&nbsp;:</term><listitem><simpara>


</simpara></listitem></varlistentry>
</variablelist></refsect2>

</refsect1>




</refentry>
