← Back to branch summary

~xubuntu-dev/libxfce4util/maverick

« back to all changes in this revision

Viewing changes to docs/xml/xfce-miscutils.xml

  • Committer: Lionel Le Folgoc
  • Date: 2010-05-23 18:00:15 UTC
  • Revision ID: mrpouit@ubuntu.com-20100523180015-0ddtdmn4xstvm2y8
* Merge from debian testing, remaining Ubuntu changes:
  - debian/control: use our Vcs-* fields.
  - debian/patches:
    + xubuntu_desktop-x-ubuntu-gettext.patch: display translations for
      "X-Ubuntu-Gettext-Domain" desktop files
    + series:
      . don't apply 01_add-desktop-base-in-config-dirs.patch
      . refreshed.
* New upstream release.
* debian/control:
  - bump standards version to 3.8.4.
  - add build-dep on intltool. 
  - drop quilt and chrpath build-deps.
  - bump debhelper build-deps for overrides.
* debian/rules:
  - switch to debhelper 7.
* switch to 3.0 (quilt) source format.
* debian/watch edited to track Xfce archive reorganisation.

Show diffs side-by-side

added added

removed removed

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