1
<refentry id="libxfce4util-Miscellaneous-Utilities">
3
<refentrytitle role="top_of_page">Miscellaneous Utilities</refentrytitle>
4
<manvolnum>3</manvolnum>
5
<refmiscinfo>LIBXFCE4UTIL Library</refmiscinfo>
9
<refname>Miscellaneous Utilities</refname>
10
<refpurpose>Miscellaneous utility functions</refpurpose>
11
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
14
<refsynopsisdiv role="synopsis">
15
<title role="synopsis.title">Synopsis</title>
19
#include <libxfce4util/libxfce4util.h>
22
const <link linkend="gchar">gchar</link>* <link linkend="xfce-get-homedir">xfce_get_homedir</link> (void);
23
#define <link linkend="xfce-get-homefile">xfce_get_homefile</link> (...)
24
<link linkend="gchar">gchar</link>* <link linkend="xfce-get-homefile-r">xfce_get_homefile_r</link> (<link linkend="gchar">gchar</link> *buffer,
25
<link linkend="size-t">size_t</link> length,
26
const <link linkend="gchar">gchar</link> *format,
28
const <link linkend="gchar">gchar</link>* <link linkend="xfce-get-userdir">xfce_get_userdir</link> (void);
29
#define <link linkend="xfce-get-userfile">xfce_get_userfile</link> (...)
30
<link linkend="gchar">gchar</link>* <link linkend="xfce-get-userfile-r">xfce_get_userfile_r</link> (<link linkend="gchar">gchar</link> *buffer,
31
<link linkend="size-t">size_t</link> length,
32
const <link linkend="gchar">gchar</link> *format,
34
<link linkend="gchar">gchar</link>* <link linkend="xfce-strjoin">xfce_strjoin</link> (const <link linkend="gchar">gchar</link> *separator,
35
<link linkend="gchar">gchar</link> **strings,
36
<link linkend="gint">gint</link> count);
37
<link linkend="gchar">gchar</link>* <link linkend="xfce-gethostname">xfce_gethostname</link> (void);
38
<link linkend="gint">gint</link> <link linkend="xfce-putenv">xfce_putenv</link> (const <link linkend="gchar">gchar</link> *string);
39
<link linkend="gint">gint</link> <link linkend="xfce-setenv">xfce_setenv</link> (const <link linkend="gchar">gchar</link> *name,
40
const <link linkend="gchar">gchar</link> *value,
41
<link linkend="gboolean">gboolean</link> overwrite);
42
<link linkend="void">void</link> <link linkend="xfce-unsetenv">xfce_unsetenv</link> (const <link linkend="gchar">gchar</link> *name);
43
<link linkend="gchar">gchar</link>* <link linkend="xfce-expand-variables">xfce_expand_variables</link> (const <link linkend="gchar">gchar</link> *command,
44
<link linkend="gchar">gchar</link> **envp);
56
<refsect1 role="desc">
57
<title role="desc.title">Description</title>
63
<refsect1 role="details">
64
<title role="details.title">Details</title>
66
<title><anchor id="xfce-get-homedir" role="function"/>xfce_get_homedir ()</title>
67
<indexterm><primary>xfce_get_homedir</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* xfce_get_homedir (void);</programlisting>
69
Similar to <link linkend="g-get-homedir"><function>g_get_homedir()</function></link> in functionality but will never return NULL.
70
While <link linkend="g-get-homedir"><function>g_get_homedir()</function></link> may return NULL under certain circumstances, this
71
function is garantied to never ever return NULL, but always return a
72
valid character pointer with the absolute path to the user's home directory.
75
The returned string is owned by libxfce4util and must not be freed by
79
</para><variablelist role="params">
80
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the path to the current user's home directory.
81
</simpara></listitem></varlistentry>
82
</variablelist></refsect2>
84
<title><anchor id="xfce-get-homefile" role="macro"/>xfce_get_homefile()</title>
85
<indexterm><primary>xfce_get_homefile</primary></indexterm><programlisting>#define xfce_get_homefile(...)</programlisting>
87
Returns the path to a file in the user's home directory by taking a
88
NULL terminated list of strings and appending them to the absolute
89
path of the current user's home directory.
90
</para><variablelist role="params">
91
<varlistentry><term><parameter>...</parameter> :</term>
93
</simpara></listitem></varlistentry>
94
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the absolute path to the specified file in the current user's
95
home directory. The caller is responsible for freeing the
96
returned string using <link linkend="g-free"><function>g_free()</function></link>.
97
</simpara></listitem></varlistentry>
98
</variablelist></refsect2>
100
<title><anchor id="xfce-get-homefile-r" role="function"/>xfce_get_homefile_r ()</title>
101
<indexterm><primary>xfce_get_homefile_r</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* xfce_get_homefile_r (<link linkend="gchar">gchar</link> *buffer,
102
<link linkend="size-t">size_t</link> length,
103
const <link linkend="gchar">gchar</link> *format,
104
...);</programlisting>
106
Similar in functionality to <link linkend="xfce-get-homefile"><type>xfce_get_homefile</type></link>, but uses a user
107
defined <parameter>buffer</parameter> instead of allocating a new buffer.
110
xfce_get_homefile_r uses safe string operations, that says, it garanties
111
that the resulting string is always zero terminated, as long as the
112
<parameter>length</parameter> is greater than zero.</para>
115
</para><variablelist role="params">
116
<varlistentry><term><parameter>buffer</parameter> :</term>
117
<listitem><simpara> pointer to a user provided destination buffer.
118
</simpara></listitem></varlistentry>
119
<varlistentry><term><parameter>length</parameter> :</term>
120
<listitem><simpara> size of <parameter>buffer</parameter> in bytes.
121
</simpara></listitem></varlistentry>
122
<varlistentry><term><parameter>format</parameter> :</term>
123
<listitem><simpara> printf style format string.
124
</simpara></listitem></varlistentry>
125
<varlistentry><term><parameter>...</parameter> :</term>
126
<listitem><simpara> the arguments to substitute in the output.
127
</simpara></listitem></varlistentry>
128
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> pointer to <parameter>buffer</parameter>.
129
</simpara></listitem></varlistentry>
130
</variablelist></refsect2>
132
<title><anchor id="xfce-get-userdir" role="function"/>xfce_get_userdir ()</title>
133
<indexterm><primary>xfce_get_userdir</primary></indexterm><programlisting>const <link linkend="gchar">gchar</link>* xfce_get_userdir (void);</programlisting>
135
Safe way to retrieve the path to the user's ".xfce4" directory. The path
136
to the current user's ".xfce4" directory is either taken from the
137
environment variable XFCE4HOME if defined, or if unset, is gained by
138
concatenating the path to the user's home directory and the ".xfce4".
139
That says, it will, by default, return the path "$HOME/.xfce4", where
140
$HOME is replaced with the absolute path to the user's home directory.
143
The returned string is managed by libxfce4util and must not be freed by
147
</para><variablelist role="params">
148
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the path to the current user's ".xfce4" directory.
149
</simpara></listitem></varlistentry>
150
</variablelist></refsect2>
152
<title><anchor id="xfce-get-userfile" role="macro"/>xfce_get_userfile()</title>
153
<indexterm><primary>xfce_get_userfile</primary></indexterm><programlisting>#define xfce_get_userfile(...)</programlisting>
155
Returns the absolute path to a file within the user's ".xfce4" directory,
156
formed by a NULL terminated list of path components.
157
</para><variablelist role="params">
158
<varlistentry><term><parameter>...</parameter> :</term>
160
</simpara></listitem></varlistentry>
161
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara>the absolute path to the specified file in the user's ".xfce4"
162
directory. The caller is responsible for freeing the returned
163
string using <link linkend="g-free"><function>g_free()</function></link>.
164
</simpara></listitem></varlistentry>
165
</variablelist></refsect2>
167
<title><anchor id="xfce-get-userfile-r" role="function"/>xfce_get_userfile_r ()</title>
168
<indexterm><primary>xfce_get_userfile_r</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* xfce_get_userfile_r (<link linkend="gchar">gchar</link> *buffer,
169
<link linkend="size-t">size_t</link> length,
170
const <link linkend="gchar">gchar</link> *format,
171
...);</programlisting>
176
</para><variablelist role="params">
177
<varlistentry><term><parameter>buffer</parameter> :</term>
178
<listitem><simpara> user provided destination buffer.
179
</simpara></listitem></varlistentry>
180
<varlistentry><term><parameter>length</parameter> :</term>
181
<listitem><simpara> size of <parameter>buffer</parameter> in bytes.
182
</simpara></listitem></varlistentry>
183
<varlistentry><term><parameter>format</parameter> :</term>
184
<listitem><simpara> printf style format string.
185
</simpara></listitem></varlistentry>
186
<varlistentry><term><parameter>...</parameter> :</term>
187
<listitem><simpara> arguments to substitute in the output.
188
</simpara></listitem></varlistentry>
189
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> pointer to <parameter>buffer</parameter>.
190
</simpara></listitem></varlistentry>
191
</variablelist></refsect2>
193
<title><anchor id="xfce-strjoin" role="function"/>xfce_strjoin ()</title>
194
<indexterm><primary>xfce_strjoin</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* xfce_strjoin (const <link linkend="gchar">gchar</link> *separator,
195
<link linkend="gchar">gchar</link> **strings,
196
<link linkend="gint">gint</link> count);</programlisting>
198
Joins the <parameter>count</parameter> character strings pointed to by <parameter>strings</parameter> using <parameter>separator</parameter>
199
to a single string.</para>
202
</para><variablelist role="params">
203
<varlistentry><term><parameter>separator</parameter> :</term>
205
</simpara></listitem></varlistentry>
206
<varlistentry><term><parameter>strings</parameter> :</term>
208
</simpara></listitem></varlistentry>
209
<varlistentry><term><parameter>count</parameter> :</term>
211
</simpara></listitem></varlistentry>
212
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the joined string. The string has to be freed by the caller
213
using <link linkend="g-free"><function>g_free()</function></link> when no longer needed.
214
</simpara></listitem></varlistentry>
215
</variablelist></refsect2>
217
<title><anchor id="xfce-gethostname" role="function"/>xfce_gethostname ()</title>
218
<indexterm><primary>xfce_gethostname</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* xfce_gethostname (void);</programlisting>
220
Portable way to query the hostname of the node running the process. This
221
function does not ever return <link linkend="NULL:CAPS"><literal>NULL</literal></link>, but always returns a string containing
222
the current node's hostname.</para>
225
</para><variablelist role="params">
226
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> the current node's hostname. The string has to be freed
227
by the caller using <link linkend="g-free"><function>g_free()</function></link>.
228
</simpara></listitem></varlistentry>
229
</variablelist></refsect2>
231
<title><anchor id="xfce-putenv" role="function" condition="since:4.2"/>xfce_putenv ()</title>
232
<indexterm role="4.2"><primary>xfce_putenv</primary></indexterm><programlisting><link linkend="gint">gint</link> xfce_putenv (const <link linkend="gchar">gchar</link> *string);</programlisting>
234
Portable replacement for the Unix <link linkend="putenv"><function>putenv()</function></link> library function. <parameter>string</parameter> has
235
to have the form "name=value". Calling <link linkend="xfce-putenv"><function>xfce_putenv()</function></link> this way is equal to
236
calling xfce_setenv("name", "value", <link linkend="TRUE:CAPS"><literal>TRUE</literal></link>).</para>
239
</para><variablelist role="params">
240
<varlistentry><term><parameter>string</parameter> :</term>
241
<listitem><simpara> Character string in the form "name=value".
242
</simpara></listitem></varlistentry>
243
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the operation was successful; otherwise the global
244
variable errno is set to indicate the error and a value
247
</simpara></listitem></varlistentry>
248
</variablelist><para role="since">Since 4.2
251
<title><anchor id="xfce-setenv" role="function" condition="since:4.2"/>xfce_setenv ()</title>
252
<indexterm role="4.2"><primary>xfce_setenv</primary></indexterm><programlisting><link linkend="gint">gint</link> xfce_setenv (const <link linkend="gchar">gchar</link> *name,
253
const <link linkend="gchar">gchar</link> *value,
254
<link linkend="gboolean">gboolean</link> overwrite);</programlisting>
256
If the variable <parameter>name</parameter> does not exists in the list of environment variables,
257
it is inserted with its value being set to <parameter>value</parameter>. If the variable does
258
exist, then its value is only changed to <parameter>value</parameter> if <parameter>overwrite</parameter> is TRUE.
261
On plattforms that provide a working native <link linkend="setenv"><function>setenv()</function></link> library call, this
262
functions is used, on all other plattforms <link linkend="setenv"><function>setenv()</function></link> is emulated using
263
<link linkend="xfce-putenv"><function>xfce_putenv()</function></link>. That says, <link linkend="xfce-setenv"><function>xfce_setenv()</function></link> is not subject to the limitations
264
that apply to some <link linkend="setenv"><function>setenv()</function></link> implementations and seem also to apply to
265
<link linkend="g-setenv"><function>g_setenv()</function></link> in Glib 2.4.</para>
268
</para><variablelist role="params">
269
<varlistentry><term><parameter>name</parameter> :</term>
270
<listitem><simpara> the name of the environment variable to set, must not contain '='.
271
</simpara></listitem></varlistentry>
272
<varlistentry><term><parameter>value</parameter> :</term>
273
<listitem><simpara> the value to set the variable to.
274
</simpara></listitem></varlistentry>
275
<varlistentry><term><parameter>overwrite</parameter> :</term>
276
<listitem><simpara> whether to change the variable if it already exists.
277
</simpara></listitem></varlistentry>
278
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> 0 if the operation was successful; otherwise the global
279
variable errno is set to indicate the error and a value
282
</simpara></listitem></varlistentry>
283
</variablelist><para role="since">Since 4.2
286
<title><anchor id="xfce-unsetenv" role="function" condition="since:4.2"/>xfce_unsetenv ()</title>
287
<indexterm role="4.2"><primary>xfce_unsetenv</primary></indexterm><programlisting><link linkend="void">void</link> xfce_unsetenv (const <link linkend="gchar">gchar</link> *name);</programlisting>
289
Deletes all instances of the variables <parameter>name</parameter> from the list of environment
290
variables in the current process.
293
Note that on some systems, the memory used for the variable and its value
294
can't be reclaimed. Furthermore, this function can't be guaranteed to
295
operate in a threadsafe way.</para>
298
</para><variablelist role="params">
299
<varlistentry><term><parameter>name</parameter> :</term>
300
<listitem><simpara> the name of the environment variable to unset, must not contain '='.
301
</simpara></listitem></varlistentry>
302
</variablelist><para role="since">Since 4.2
305
<title><anchor id="xfce-expand-variables" role="function" condition="since:4.2"/>xfce_expand_variables ()</title>
306
<indexterm role="4.2"><primary>xfce_expand_variables</primary></indexterm><programlisting><link linkend="gchar">gchar</link>* xfce_expand_variables (const <link linkend="gchar">gchar</link> *command,
307
<link linkend="gchar">gchar</link> **envp);</programlisting>
309
Expands shell like environment variables and tilde (~/ and ~user/ are both supported)
310
in <parameter>command</parameter>.</para>
313
</para><variablelist role="params">
314
<varlistentry><term><parameter>command</parameter> :</term>
315
<listitem><simpara> Input string.
316
</simpara></listitem></varlistentry>
317
<varlistentry><term><parameter>envp</parameter> :</term>
318
<listitem><simpara> Addition environment variables to take into account. These
319
variables have higher priority than the ones in the process's
321
</simpara></listitem></varlistentry>
322
<varlistentry><term><emphasis>Returns</emphasis> :</term><listitem><simpara> <link linkend="NULL:CAPS"><literal>NULL</literal></link> on error, else the string, which should be freed using
323
<link linkend="g-free"><function>g_free()</function></link> when no longer needed.
325
</simpara></listitem></varlistentry>
326
</variablelist><para role="since">Since 4.2
added
removed
docs/xml/xfce-miscutils.xml
