<refentry id="gnome-gnome-exec">
<refmeta>
<refentrytitle>gnome-exec</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>GNOME Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>gnome-exec</refname><refpurpose>Execution of programs from GNOME applications</refpurpose>
</refnamediv>

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

#include &lt;gnome.h&gt;


int         <link linkend="gnome-execute-async">gnome_execute_async</link>             (const char *dir,
                                             int argc,
                                             char *const argv[]);
int         <link linkend="gnome-execute-async-fds">gnome_execute_async_fds</link>         (const char *dir,
                                             int argc,
                                             char *const argv[],
                                             <link linkend="gboolean">gboolean</link> close_fds);
int         <link linkend="gnome-execute-async-with-env">gnome_execute_async_with_env</link>    (const char *dir,
                                             int argc,
                                             char *const argv[],
                                             int envc,
                                             char *const envv[]);
int         <link linkend="gnome-execute-async-with-env-fds">gnome_execute_async_with_env_fds</link>
                                            (const char *dir,
                                             int argc,
                                             char *const argv[],
                                             int envc,
                                             char *const envv[],
                                             <link linkend="gboolean">gboolean</link> close_fds);
int         <link linkend="gnome-execute-shell">gnome_execute_shell</link>             (const char *dir,
                                             const char *commandline);
int         <link linkend="gnome-execute-shell-fds">gnome_execute_shell_fds</link>         (const char *dir,
                                             const char *commandline,
                                             <link linkend="gboolean">gboolean</link> close_fds);
</synopsis>
</refsynopsisdiv>





<refsect1>
<title>Description</title>
<para>
The gnome-execute family of functions are provided to simplify
execution of programs from withing GNOME applications.  These routines
are required to avoid passing opened file descriptors to a child
process (like the X11 sockets and CORBA sockets).  They will also make
sure to terminate properly.</para>

<para>The range of possibilities goes from the most simple use to the
most specialized ones.</para>
</refsect1>

<refsect1>
<title>Details</title>
<refsect2>
<title><anchor id="gnome-execute-async">gnome_execute_async ()</title>
<programlisting>int         gnome_execute_async             (const char *dir,
                                             int argc,
                                             char *const argv[]);</programlisting>
<para>
Like <link linkend="gnome-execute-async-with-env">gnome_execute_async_with_env</link>(), but doesn't add anything to
child's environment.</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 in which child should be execd, or NULL for current
directory
</entry></row>
<row><entry align="right"><parameter>argc</parameter>&nbsp;:</entry>
<entry> Number of arguments
</entry></row>
<row><entry align="right"><parameter>argv</parameter>&nbsp;:</entry>
<entry> Argument vector to exec child
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> process id of child, or <literal>-1</literal> on error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-execute-async-fds">gnome_execute_async_fds ()</title>
<programlisting>int         gnome_execute_async_fds         (const char *dir,
                                             int argc,
                                             char *const argv[],
                                             <link linkend="gboolean">gboolean</link> close_fds);</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 in which child should be execd, or NULL for current
directory
</entry></row>
<row><entry align="right"><parameter>argc</parameter>&nbsp;:</entry>
<entry> Number of arguments
</entry></row>
<row><entry align="right"><parameter>argv</parameter>&nbsp;:</entry>
<entry> Argument vector to exec child
</entry></row>
<row><entry align="right"><parameter>close_fds</parameter>&nbsp;:</entry>
<entry> 
Like <link linkend="gnome-execute-async-with-env-fds">gnome_execute_async_with_env_fds</link>(), but doesn't add anything to
child's environment.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> process id of child, or <literal>-1</literal> on error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-execute-async-with-env">gnome_execute_async_with_env ()</title>
<programlisting>int         gnome_execute_async_with_env    (const char *dir,
                                             int argc,
                                             char *const argv[],
                                             int envc,
                                             char *const envv[]);</programlisting>
<para>
This function forks and executes some program in the background.
On error, returns <literal>-1</literal>; in this case, errno should hold a useful
value.  Searches the path to find the child.  Environment settings
in <parameter>envv</parameter> are added to the existing environment -- they do not
completely replace it.  This function closes all fds besides 0, 1,
and 2 for the child</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 in which child should be execd, or NULL for current
directory
</entry></row>
<row><entry align="right"><parameter>argc</parameter>&nbsp;:</entry>
<entry> Number of arguments
</entry></row>
<row><entry align="right"><parameter>argv</parameter>&nbsp;:</entry>
<entry> Argument vector to exec child
</entry></row>
<row><entry align="right"><parameter>envc</parameter>&nbsp;:</entry>
<entry> Number of environment slots
</entry></row>
<row><entry align="right"><parameter>envv</parameter>&nbsp;:</entry>
<entry> Environment vector
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the process id, or <literal>-1</literal> on error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-execute-async-with-env-fds">gnome_execute_async_with_env_fds ()</title>
<programlisting>int         gnome_execute_async_with_env_fds
                                            (const char *dir,
                                             int argc,
                                             char *const argv[],
                                             int envc,
                                             char *const envv[],
                                             <link linkend="gboolean">gboolean</link> close_fds);</programlisting>
<para>
Like <link linkend="gnome-execute-async-with-env">gnome_execute_async_with_env</link>() but has a flag to decide whether or not  * to close fd's</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 in which child should be execd, or NULL for current
directory
</entry></row>
<row><entry align="right"><parameter>argc</parameter>&nbsp;:</entry>
<entry> Number of arguments
</entry></row>
<row><entry align="right"><parameter>argv</parameter>&nbsp;:</entry>
<entry> Argument vector to exec child
</entry></row>
<row><entry align="right"><parameter>envc</parameter>&nbsp;:</entry>
<entry> Number of environment slots
</entry></row>
<row><entry align="right"><parameter>envv</parameter>&nbsp;:</entry>
<entry> Environment vector
</entry></row>
<row><entry align="right"><parameter>close_fds</parameter>&nbsp;:</entry>
<entry> If TRUE will close all fds but 0,1, and 2
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> the process id, or <literal>-1</literal> on error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-execute-shell">gnome_execute_shell ()</title>
<programlisting>int         gnome_execute_shell             (const char *dir,
                                             const char *commandline);</programlisting>
<para>
Like <link linkend="gnome-execute-async-with-env">gnome_execute_async_with_env</link>(), but uses the user's shell to
run the desired program.  Note that the pid of the shell is
returned, not the pid of the user's program.</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 in which child should be execd, or NULL for current
directory
</entry></row>
<row><entry align="right"><parameter>commandline</parameter>&nbsp;:</entry>
<entry> Shell command to execute
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> process id of shell, or <literal>-1</literal> on error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>
<refsect2>
<title><anchor id="gnome-execute-shell-fds">gnome_execute_shell_fds ()</title>
<programlisting>int         gnome_execute_shell_fds         (const char *dir,
                                             const char *commandline,
                                             <link linkend="gboolean">gboolean</link> close_fds);</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 in which child should be execd, or NULL for current
directory
</entry></row>
<row><entry align="right"><parameter>commandline</parameter>&nbsp;:</entry>
<entry> Shell command to execute
</entry></row>
<row><entry align="right"><parameter>close_fds</parameter>&nbsp;:</entry>
<entry> Like close_fds in <link linkend="gnome-execute-async-with-env-fds">gnome_execute_async_with_env_fds</link>()
Like <link linkend="gnome-execute-async-with-env-fds">gnome_execute_async_with_env_fds</link>(), but uses the user's shell to
run the desired program.  Note that the pid of the shell is
returned, not the pid of the user's program.
</entry></row>
<row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> process id of shell, or <literal>-1</literal> on error.
</entry></row>
</tbody></tgroup></informaltable></refsect2>

</refsect1>




</refentry>