<refentry id="gnome-gnome-util" revision="21 Mar 2000">
<refmeta>
<refentrytitle>gnome-util</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GNOME Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>gnome-util</refname><refpurpose>Miscellaneous utility functions for GNOME and C programs.</refpurpose>
</refnamediv>

<refsynopsisdiv><title>Synopsis</title>
<synopsis>

#include &lt;gnome.h&gt;


#define     <link linkend="PATH-SEP">PATH_SEP</link>
#define     <link linkend="PATH-SEP-STR">PATH_SEP_STR</link>
char*       <link linkend="gnome-libdir-file">gnome_libdir_file</link>               (const char *filename);
char*       <link linkend="gnome-datadir-file">gnome_datadir_file</link>              (const char *filename);
char*       <link linkend="gnome-sound-file">gnome_sound_file</link>                (const char *filename);
char*       <link linkend="gnome-pixmap-file">gnome_pixmap_file</link>               (const char *filename);
char*       <link linkend="gnome-config-file">gnome_config_file</link>               (const char *filename);
char*       <link linkend="gnome-unconditional-libdir-file">gnome_unconditional_libdir_file</link> (const char *filename);
char*       <link linkend="gnome-unconditional-datadir-file">gnome_unconditional_datadir_file</link>
                                            (const char *filename);
char*       <link linkend="gnome-unconditional-sound-file">gnome_unconditional_sound_file</link>  (const char *filename);
char*       <link linkend="gnome-unconditional-pixmap-file">gnome_unconditional_pixmap_file</link> (const char *filename);
char*       <link linkend="gnome-unconditional-config-file">gnome_unconditional_config_file</link> (const char *filename);
int         <link linkend="g-file-test">g_file_test</link>                     (const char *filename,
                                             int test);
int         <link linkend="g-file-exists">g_file_exists</link>                   (const char *filename);
#define     <link linkend="g-copy-strings">g_copy_strings</link>
const char* <link linkend="g-unix-error-string">g_unix_error_string</link>             (int error_num);
char*       <link linkend="g-concat-dir-and-file">g_concat_dir_and_file</link>           (const char *dir,
                                             const char *file);
#define     <link linkend="g-filename-index">g_filename_index</link>                (path)
#define     <link linkend="g-filename-pointer">g_filename_pointer</link>
const char* <link linkend="g-extension-pointer">g_extension_pointer</link>             (const char *path);
char**      <link linkend="g-copy-vector">g_copy_vector</link>                   (char **vec);
#define     <link linkend="g-flatten-vector">g_flatten_vector</link>
#define     <link linkend="gnome-util-user-home">gnome_util_user_home</link>            ()
#define     <link linkend="gnome-util-prepend-user-home">gnome_util_prepend_user_home</link>    (x)
#define     <link linkend="gnome-util-home-file">gnome_util_home_file</link>            (afile)
char*       <link linkend="gnome-util-user-shell">gnome_util_user_shell</link>           (void);
<link linkend="gboolean">gboolean</link>    <link linkend="g-is-image-filename">g_is_image_filename</link>             (const char *path);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>

</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="PATH-SEP">PATH_SEP</title>
<programlisting>#define PATH_SEP '/'
</programlisting>
<para>
A <type>int</type> macro that represents the character used as
the path separator in this operating system
</para></refsect2>
<refsect2>
<title><anchor id="PATH-SEP-STR">PATH_SEP_STR</title>
<programlisting>#define PATH_SEP_STR "/"
</programlisting>
<para>
A <type>char *</type> string that represents the character used as
the path separator in this operating system.  This comes in string fashion.
</para></refsect2>
<refsect2>
<title><anchor id="gnome-libdir-file">gnome_libdir_file ()</title>
<programlisting>char*       gnome_libdir_file               (const char *filename);</programlisting>
<para>
Locates a shared file either in the GNOMEDIR tree, the GNOME
installation directory or in the current directory</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> filename to locate in libdir
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly allocated pathname pointing to a file in the gnome libdir
or NULL if the file does not exist.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-datadir-file">gnome_datadir_file ()</title>
<programlisting>char*       gnome_datadir_file              (const char *filename);</programlisting>
<para>
Locates a shared file either in the GNOMEDIR tree, the GNOME
installation directory or in the current directory</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> shared filename to locate
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly allocated pathname pointing to a file in the gnome sharedir
or NULL if the file does not exist.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-sound-file">gnome_sound_file ()</title>
<programlisting>char*       gnome_sound_file                (const char *filename);</programlisting>
<para>
Locates a sound file either in the GNOMEDIR tree, the GNOME
installation directory or in the current directory</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> sound filename to locate.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly allocated pathname pointing to a file in the gnome sound directory
or NULL if the file does not exist.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-pixmap-file">gnome_pixmap_file ()</title>
<programlisting>char*       gnome_pixmap_file               (const char *filename);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> pixmap filename
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly allocated filename from the GNOMEDIR tree or from the
GNOME installation directory for the pixmap directory ($prefix/share/pixmaps),
or NULL if the file does not exist.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-config-file">gnome_config_file ()</title>
<programlisting>char*       gnome_config_file               (const char *filename);</programlisting>
<para>
Locates a configuration file ($prefix/etc) in the GNOMEDIR tree, the
GNOME installation direcory or the current directory.</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> config filename
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly allocated filename from the GNOMEDIR tree or from the
GNOME installation directory
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-unconditional-libdir-file">gnome_unconditional_libdir_file ()</title>
<programlisting>char*       gnome_unconditional_libdir_file (const char *filename);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> library filename
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly allocated pathname pointing to a (possibly
non-existent) file from the GNOMEDIR tree or from the GNOME
installation directory
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-unconditional-datadir-file">gnome_unconditional_datadir_file ()</title>
<programlisting>char*       gnome_unconditional_datadir_file
                                            (const char *filename);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> datadir filename
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly allocated pathname pointing to a (possibly
non-existent) file from the GNOMEDIR tree or from the GNOME
installation directory
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-unconditional-sound-file">gnome_unconditional_sound_file ()</title>
<programlisting>char*       gnome_unconditional_sound_file  (const char *filename);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> sound filename
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly allocated filename from the GNOMEDIR tree or from the
GNOME installation directory
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-unconditional-pixmap-file">gnome_unconditional_pixmap_file ()</title>
<programlisting>char*       gnome_unconditional_pixmap_file (const char *filename);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> pixmap filename
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly allocated filename from the GNOMEDIR tree or from the
GNOME installation directory for the pixmap directory ($prefix/share/pixmaps)
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-unconditional-config-file">gnome_unconditional_config_file ()</title>
<programlisting>char*       gnome_unconditional_config_file (const char *filename);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> configuration filename
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly allocated filename pointing to a (possibly
non-existent) file from the GNOMEDIR tree or from the GNOME
installation directory for the configuration directory
($prefix/etc).
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-file-test">g_file_test ()</title>
<programlisting>int         g_file_test                     (const char *filename,
                                             int test);</programlisting>
<para>
test is one of:
G_FILE_TEST_ISFILE, to check if the pathname is a file
G_FILE_TEST_ISLINK, to check if the pathname is a symlink
G_FILE_TEST_ISDIR,  to check if the pathname is a directory</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry>  filename to test
</entry></row>
<row><entry align="right"><parameter>test</parameter>&nbsp;:</entry>
<entry>      test to perform on the file
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>true if filename passes the specified test (an or expression of
tests)
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-file-exists">g_file_exists ()</title>
<programlisting>int         g_file_exists                   (const char *filename);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>filename</parameter>&nbsp;:</entry>
<entry> pathname to test for existance.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>true if filename exists
left in for binary compatibility for a while FIXME: remove
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-copy-strings">g_copy_strings</title>
<programlisting>#define     g_copy_strings</programlisting>
<para>
</para>
<para>
Deprecated. Use <function><link linkend="g-strconcat">g_strconcat</link>()</function>.
</para></refsect2>
<refsect2>
<title><anchor id="g-unix-error-string">g_unix_error_string ()</title>
<programlisting>const char* g_unix_error_string             (int error_num);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>error_num</parameter>&nbsp;:</entry>
<entry> The errno number.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a pointer to a static buffer containing the description of
the error reported by the errno.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-concat-dir-and-file">g_concat_dir_and_file ()</title>
<programlisting>char*       g_concat_dir_and_file           (const char *dir,
                                             const char *file);</programlisting>
<para>
</para>
<para>

</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>dir</parameter>&nbsp;:</entry>
<entry>  directory name
</entry></row>
<row><entry align="right"><parameter>file</parameter>&nbsp;:</entry>
<entry> filename.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a new allocated string that is the concatenation of dir and file,
takes care of the exact details for concatenating them.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-filename-index">g_filename_index()</title>
<programlisting>#define     g_filename_index(path)</programlisting>
</refsect2>
<refsect2>
<title><anchor id="g-filename-pointer">g_filename_pointer</title>
<programlisting>#define     g_filename_pointer</programlisting>
</refsect2>
<refsect2>
<title><anchor id="g-extension-pointer">g_extension_pointer ()</title>
<programlisting>const char* g_extension_pointer             (const char *path);</programlisting>
</refsect2>
<refsect2>
<title><anchor id="g-copy-vector">g_copy_vector ()</title>
<programlisting>char**      g_copy_vector                   (char **vec);</programlisting>
</refsect2>
<refsect2>
<title><anchor id="g-flatten-vector">g_flatten_vector</title>
<programlisting>#define     g_flatten_vector</programlisting>
<para>
Deprecated. Use <function><link linkend="g-strjoinv">g_strjoinv</link>()</function>.
</para></refsect2>
<refsect2>
<title><anchor id="gnome-util-user-home">gnome_util_user_home()</title>
<programlisting>#define     gnome_util_user_home()</programlisting>
<para>
Deprecated. Use <function><link linkend="g-get-home-dir">g_get_home_dir</link>()</function>.
</para></refsect2>
<refsect2>
<title><anchor id="gnome-util-prepend-user-home">gnome_util_prepend_user_home()</title>
<programlisting>#define     gnome_util_prepend_user_home(x)</programlisting>
<para>
Deprecated. Use <function><link linkend="g-get-home-dir">g_get_home_dir</link>()</function> and <function><link linkend="g-concat-dir-and-file">g_concat_dir_and_file</link>()</function>.
</para></refsect2>
<refsect2>
<title><anchor id="gnome-util-home-file">gnome_util_home_file()</title>
<programlisting>#define     gnome_util_home_file(afile)</programlisting>
<para>
Deprecated.
</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>afile</parameter>&nbsp;:</entry>
<entry>

</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-util-user-shell">gnome_util_user_shell ()</title>
<programlisting>char*       gnome_util_user_shell           (void);</programlisting>
<para>
</para>
<para>
Get the user's shell.
</para><informaltable pgwide=1 frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>a newly allocated string that is the path to the user's
preferred shell.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-is-image-filename">g_is_image_filename ()</title>
<programlisting><link linkend="gboolean">gboolean</link>    g_is_image_filename             (const char *path);</programlisting>
<para>
Deprecated. Extra lame way of figuring if a filename is an image file.  You
should use the gnome_mime functions instead and match against "image/".</para>
<para>
Deprecated. Use gnome-mime stuff instead.
</para></refsect2>

</refsect1>




</refentry>
