misc_utils.sgml

GLib是GTK+和GNOME工程的基础底层核心程序库

<refentry id="glib-Miscellaneous-Utility-Functions">
<refmeta>
<refentrytitle>Miscellaneous Utility Functions</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GLIB Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Miscellaneous Utility Functions</refname><refpurpose>a selection of portable utility functions.</refpurpose>
</refnamediv>

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

#include &lt;glib.h&gt;


<link linkend="gchar">gchar</link>*      <link linkend="g-get-prgname">g_get_prgname</link>                   (void);
void        <link linkend="g-set-prgname">g_set_prgname</link>                   (const <link linkend="gchar">gchar</link> *prgname);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-getenv">g_getenv</link>              (const <link linkend="gchar">gchar</link> *variable);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-get-user-name">g_get_user_name</link>       (void);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-get-real-name">g_get_real_name</link>       (void);

G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-get-home-dir">g_get_home_dir</link>        (void);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-get-tmp-dir">g_get_tmp_dir</link>         (void);
<link linkend="gchar">gchar</link>*      <link linkend="g-get-current-dir">g_get_current_dir</link>               (void);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-basename">g_basename</link>            (const <link linkend="gchar">gchar</link> *file_name);
#define     <link linkend="g-dirname">g_dirname</link>
<link linkend="gboolean">gboolean</link>    <link linkend="g-path-is-absolute">g_path_is_absolute</link>              (const <link linkend="gchar">gchar</link> *file_name);
G_CONST_RETURN <link linkend="gchar">gchar</link>* <link linkend="g-path-skip-root">g_path_skip_root</link>      (const <link linkend="gchar">gchar</link> *file_name);
<link linkend="gchar">gchar</link>*      <link linkend="g-path-get-basename">g_path_get_basename</link>             (const <link linkend="gchar">gchar</link> *file_name);
<link linkend="gchar">gchar</link>*      <link linkend="g-path-get-dirname">g_path_get_dirname</link>              (const <link linkend="gchar">gchar</link> *file_name);
<link linkend="gchar">gchar</link>*      <link linkend="g-build-filename">g_build_filename</link>                (const <link linkend="gchar">gchar</link> *first_element,
                                             ...);
<link linkend="gchar">gchar</link>*      <link linkend="g-build-path">g_build_path</link>                    (const <link linkend="gchar">gchar</link> *separator,
                                             const <link linkend="gchar">gchar</link> *first_element,
                                             ...);

<link linkend="gchar">gchar</link>*      <link linkend="g-find-program-in-path">g_find_program_in_path</link>          (const <link linkend="gchar">gchar</link> *program);

<link linkend="gint">gint</link>        <link linkend="g-bit-nth-lsf">g_bit_nth_lsf</link>                   (<link linkend="gulong">gulong</link> mask,
                                             <link linkend="gint">gint</link> nth_bit);
<link linkend="gint">gint</link>        <link linkend="g-bit-nth-msf">g_bit_nth_msf</link>                   (<link linkend="gulong">gulong</link> mask,
                                             <link linkend="gint">gint</link> nth_bit);
<link linkend="guint">guint</link>       <link linkend="g-bit-storage">g_bit_storage</link>                   (<link linkend="gulong">gulong</link> number);

<link linkend="guint">guint</link>       <link linkend="g-spaced-primes-closest">g_spaced_primes_closest</link>         (<link linkend="guint">guint</link> num);

void        <link linkend="g-atexit">g_atexit</link>                        (<link linkend="GVoidFunc">GVoidFunc</link> func);

<link linkend="guint">guint</link>       <link linkend="g-parse-debug-string">g_parse_debug_string</link>            (const <link linkend="gchar">gchar</link> *string,
                                             const <link linkend="GDebugKey">GDebugKey</link> *keys,
                                             <link linkend="guint">guint</link> nkeys);
struct      <link linkend="GDebugKey">GDebugKey</link>;

void        (<link linkend="GVoidFunc">*GVoidFunc</link>)                    (void);
void        (<link linkend="GFreeFunc">*GFreeFunc</link>)                    (<link linkend="gpointer">gpointer</link> data);

void        <link linkend="g-qsort-with-data">g_qsort_with_data</link>               (<link linkend="gconstpointer">gconstpointer</link> pbase,
                                             <link linkend="gint">gint</link> total_elems,
                                             <link linkend="size-t">size_t</link> size,
                                             <link linkend="GCompareDataFunc">GCompareDataFunc</link> compare_func,
                                             <link linkend="gpointer">gpointer</link> user_data);

void        <link linkend="g-nullify-pointer">g_nullify_pointer</link>               (<link linkend="gpointer">gpointer</link> *nullify_location);

</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
These are portable utility functions.
</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="g-get-prgname">g_get_prgname ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_get_prgname                   (void);</programlisting>
<para>
Gets the name of the program.
(If you are using GDK or GTK+ the program name is set in <link linkend="gdk-init">gdk_init</link>(), which
is called by <link linkend="gtk-init">gtk_init</link>(). The program name is found by taking the last
component of <literal>argv[0]</literal>.)
</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>the name of the program.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-set-prgname">g_set_prgname ()</title>
<programlisting>void        g_set_prgname                   (const <link linkend="gchar">gchar</link> *prgname);</programlisting>
<para>
Sets the name of the program.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>prgname</parameter>&nbsp;:</entry>
<entry>the name of the program.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-getenv">g_getenv ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_getenv              (const <link linkend="gchar">gchar</link> *variable);</programlisting>
<para>
Returns an environment variable.
</para><informaltable pgwide="1" frame="none" role="params">
<tgroup cols="2">
<colspec colwidth="2*">
<colspec colwidth="8*">
<tbody>
<row><entry align="right"><parameter>variable</parameter>&nbsp;:</entry>
<entry>the environment variable to get.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry>the value of the environment variable, or <literal>NULL</literal> if the environment
variable is not found.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-get-user-name">g_get_user_name ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_get_user_name       (void);</programlisting>
<para>
Gets the user name of the current user.
</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>the user name of the current user.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-get-real-name">g_get_real_name ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_get_real_name       (void);</programlisting>
<para>
Gets the real name of the user. This usually comes from the user's entry in the
<filename>passwd</filename> file.
</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>the user's real name.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-get-home-dir">g_get_home_dir ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_get_home_dir        (void);</programlisting>
<para>
Gets the current user's home directory.
</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>the current user's home directory.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-get-tmp-dir">g_get_tmp_dir ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_get_tmp_dir         (void);</programlisting>
<para>
Gets the directory to use for temporary files.
This is found from inspecting the environment variables <envar>TMPDIR</envar>, 
<envar>TMP</envar>, and <envar>TEMP</envar>
in that order. If none of those are defined "/tmp" is returned on UNIX and 
"C:\" on Windows.
</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>the directory to use for temporary files.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-get-current-dir">g_get_current_dir ()</title>
<programlisting><link linkend="gchar">gchar</link>*      g_get_current_dir               (void);</programlisting>
<para>
Gets the current directory.
The returned string should be freed when no longer needed.
</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>the current directory.


</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="g-basename">g_basename ()</title>
<programlisting>G_CONST_RETURN <link linkend="gchar">gchar</link>* g_basename            (const <link linkend="gchar">gchar</link> *file_name);</programlisting>
<warning>
<para>
<literal>g_basename</literal> is deprecated and should not be used in newly-written code.
</para>
</warning>
<para>
This function is deprecated and will be removed in the next major
release of GLib. Use <link linkend="g-path-get-basename">g_path_get_basename</link>() instead. 
</para>