<refentry id="gnome-gnome-util"> <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 <gnome.h> #define <link linkend="PATH-SEP-CAPS">PATH_SEP</link> #define <link linkend="PATH-SEP-STR-CAPS">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-CAPS">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-CAPS">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> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</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> :</entry> <entry> filename to test </entry></row> <row><entry align="right"><parameter>test</parameter> :</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> :</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> :</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> :</entry> <entry> directory name </entry></row> <row><entry align="right"><parameter>file</parameter> :</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> :</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>