glib-spawning-processes.html

最新gtk中文资料集

<td>
<code class="function">execv()</code> returned <code class="literal">EINVAL</code>.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="G-SPAWN-ERROR-ISDIR:CAPS"></a><code class="literal">G_SPAWN_ERROR_ISDIR</code></span></p></td>
<td>
<code class="function">execv()</code> returned <code class="literal">EISDIR</code>.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="G-SPAWN-ERROR-LIBBAD:CAPS"></a><code class="literal">G_SPAWN_ERROR_LIBBAD</code></span></p></td>
<td>
<code class="function">execv()</code> returned <code class="literal">ELIBBAD</code>.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="G-SPAWN-ERROR-FAILED:CAPS"></a><code class="literal">G_SPAWN_ERROR_FAILED</code></span></p></td>
<td>Some other fatal failure, <code class="literal">error-&gt;message</code> should explain.

</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3098671"></a><h3>
<a name="G-SPAWN-ERROR:CAPS"></a>G_SPAWN_ERROR</h3>
<a class="indexterm" name="id3098684"></a><pre class="programlisting">#define G_SPAWN_ERROR g_spawn_error_quark ()
</pre>
<p>
Error domain for spawning processes. Errors in this domain will
be from the <a class="link" href="glib-Spawning-Processes.html#GSpawnError"><span class="type">GSpawnError</span></a> enumeration. See <a class="link" href="glib-Error-Reporting.html#GError"><span class="type">GError</span></a> for information on
error domains.
</p>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3098717"></a><h3>
<a name="GSpawnFlags"></a>enum GSpawnFlags</h3>
<a class="indexterm" name="id3098730"></a><pre class="programlisting">typedef enum
{
  G_SPAWN_LEAVE_DESCRIPTORS_OPEN = 1 &lt;&lt; 0,
  G_SPAWN_DO_NOT_REAP_CHILD      = 1 &lt;&lt; 1,
  /* look for argv[0] in the path i.e. use execvp() */
  G_SPAWN_SEARCH_PATH            = 1 &lt;&lt; 2,
  /* Dump output to /dev/null */
  G_SPAWN_STDOUT_TO_DEV_NULL     = 1 &lt;&lt; 3,
  G_SPAWN_STDERR_TO_DEV_NULL     = 1 &lt;&lt; 4,
  G_SPAWN_CHILD_INHERITS_STDIN   = 1 &lt;&lt; 5,
  G_SPAWN_FILE_AND_ARGV_ZERO     = 1 &lt;&lt; 6
} GSpawnFlags;
</pre>
<p>
Flags passed to <a class="link" href="glib-Spawning-Processes.html#g-spawn-sync"><code class="function">g_spawn_sync()</code></a>, <a class="link" href="glib-Spawning-Processes.html#g-spawn-async"><code class="function">g_spawn_async()</code></a> and <a class="link" href="glib-Spawning-Processes.html#g-spawn-async-with-pipes"><code class="function">g_spawn_async_with_pipes()</code></a>.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody>
<tr>
<td><p><span class="term"><a name="G-SPAWN-LEAVE-DESCRIPTORS-OPEN:CAPS"></a><code class="literal">G_SPAWN_LEAVE_DESCRIPTORS_OPEN</code></span></p></td>
<td>the parent's open file descriptors will be 
 inherited by the child; otherwise all descriptors except stdin/stdout/stderr 
 will be closed before calling <code class="function">exec()</code> in the child.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="G-SPAWN-DO-NOT-REAP-CHILD:CAPS"></a><code class="literal">G_SPAWN_DO_NOT_REAP_CHILD</code></span></p></td>
<td>the child will not be automatically reaped; you 
  must use <a class="link" href="glib-The-Main-Event-Loop.html#g-child-watch-add"><code class="function">g_child_watch_add()</code></a> yourself (or call <code class="function">waitpid()</code> 
  or handle <code class="literal">SIGCHLD</code> yourself), or the child will become a zombie.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="G-SPAWN-SEARCH-PATH:CAPS"></a><code class="literal">G_SPAWN_SEARCH_PATH</code></span></p></td>
<td>
<code class="literal">argv[0]</code> need not be an absolute path, 
  it will be looked for in the user's <code class="envar">PATH</code>.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="G-SPAWN-STDOUT-TO-DEV-NULL:CAPS"></a><code class="literal">G_SPAWN_STDOUT_TO_DEV_NULL</code></span></p></td>
<td>the child's standard output will be discarded, 
  instead of going to the same location as the parent's standard output.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="G-SPAWN-STDERR-TO-DEV-NULL:CAPS"></a><code class="literal">G_SPAWN_STDERR_TO_DEV_NULL</code></span></p></td>
<td>the child's standard error will be discarded.
</td>
</tr>
<tr>
<td><p><span class="term"><a name="G-SPAWN-CHILD-INHERITS-STDIN:CAPS"></a><code class="literal">G_SPAWN_CHILD_INHERITS_STDIN</code></span></p></td>
<td>the child will inherit the parent's standard 
  input (by default, the child's standard input is attached to 
  <code class="filename">/dev/null</code>).
</td>
</tr>
<tr>
<td><p><span class="term"><a name="G-SPAWN-FILE-AND-ARGV-ZERO:CAPS"></a><code class="literal">G_SPAWN_FILE_AND_ARGV_ZERO</code></span></p></td>
<td>the first element of <code class="literal">argv</code> is 
  the file to execute, while the remaining elements are the actual argument 
  vector to pass to the file. Normally <a class="link" href="glib-Spawning-Processes.html#g-spawn-async-with-pipes"><code class="function">g_spawn_async_with_pipes()</code></a> uses 
  <code class="literal">argv[0]</code> as the file to execute, and passes all of 
  <code class="literal">argv</code> to the child.

</td>
</tr>
</tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3099047"></a><h3>
<a name="GSpawnChildSetupFunc"></a>GSpawnChildSetupFunc ()</h3>
<a class="indexterm" name="id3099060"></a><pre class="programlisting">void                (*GSpawnChildSetupFunc)             (<a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> user_data);</pre>
<p>
Specifies the type of the setup function passed to <a class="link" href="glib-Spawning-Processes.html#g-spawn-async"><code class="function">g_spawn_async()</code></a>,
<a class="link" href="glib-Spawning-Processes.html#g-spawn-sync"><code class="function">g_spawn_sync()</code></a> and <a class="link" href="glib-Spawning-Processes.html#g-spawn-async-with-pipes"><code class="function">g_spawn_async_with_pipes()</code></a>. On POSIX platforms it
is called in the child after GLib has performed all the setup it plans
to perform but before calling <code class="function">exec()</code>. On POSIX actions taken in this 
function will thus only affect the child, not the parent.
</p>
<p>
Note that POSIX allows only async-signal-safe functions (see signal(7)) 
to be called in the child between <code class="function">fork()</code> and <code class="function">exec()</code>, which drastically 
limits the usefulness of child setup functions.  
</p>
<p>
Also note that modifying the environment from 
</p>
<p>
On Windows the function is called in the parent. Its usefulness on
Windows is thus questionable. In many cases executing the child setup
function in the parent can have ill effects, and you should be very
careful when porting software to Windows that uses child setup
functions.
</p>
<div class="variablelist"><table border="0">
<col align="left" valign="top">
<tbody><tr>
<td><p><span class="term"><em class="parameter"><code>user_data</code></em>&#160;:</span></p></td>
<td>user data to pass to the function.


</td>
</tr></tbody>
</table></div>
</div>
<hr>
<div class="refsect2" lang="en">
<a name="id3099194"></a><h3>
<a name="g-spawn-async-with-pipes"></a>g_spawn_async_with_pipes ()</h3>
<a class="indexterm" name="id3099206"></a><pre class="programlisting"><a class="link" href="glib-Basic-Types.html#gboolean">gboolean</a>            g_spawn_async_with_pipes            (const <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> *working_directory,
                                                         <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> **argv,
                                                         <a class="link" href="glib-Basic-Types.html#gchar">gchar</a> **envp,
                                                         <a class="link" href="glib-Spawning-Processes.html#GSpawnFlags">GSpawnFlags</a> flags,
                                                         <a class="link" href="glib-Spawning-Processes.html#GSpawnChildSetupFunc">GSpawnChildSetupFunc</a> child_setup,
                                                         <a class="link" href="glib-Basic-Types.html#gpointer">gpointer</a> user_data,
                                                         <a class="link" href="glib-The-Main-Event-Loop.html#GPid">GPid</a> *child_pid,
                                                         <a class="link" href="glib-Basic-Types.html#gint">gint</a> *standard_input,
                                                         <a class="link" href="glib-Basic-Types.html#gint">gint</a> *standard_output,
                                                         <a class="link" href="glib-Basic-Types.html#gint">gint</a> *standard_error,
                                                         <a class="link" href="glib-Error-Reporting.html#GError">GError</a> **error);</pre>
<p>
Executes a child program asynchronously (your program will not
block waiting for the child to exit). The child program is
specified by the only argument that must be provided, <em class="parameter"><code>argv</code></em>. <em class="parameter"><code>argv</code></em>
should be a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>-terminated array of strings, to be passed as the
argument vector for the child. The first string in <em class="parameter"><code>argv</code></em> is of
course the name of the program to execute. By default, the name of
the program must be a full path; the <code class="envar">PATH</code> shell variable 
will only be searched if you pass the <a class="link" href="glib-Spawning-Processes.html#G-SPAWN-SEARCH-PATH:CAPS"><code class="literal">G_SPAWN_SEARCH_PATH</code></a> flag.
</p>
<p>
On Windows, note that all the string or string vector arguments to
this function and the other g_spawn*() functions are in UTF-8, the
GLib file name encoding. Unicode characters that are not part of
the system codepage passed in these arguments will be correctly
available in the spawned program only if it uses wide character API
to retrieve its command line. For C programs built with Microsoft's
tools it is enough to make the program have a <code class="function">wmain()</code> instead of
<code class="function">main()</code>. <code class="function">wmain()</code> has a wide character argument vector as parameter.
</p>
<p>
At least currently, mingw doesn't support <code class="function">wmain()</code>, so if you use
mingw to develop the spawned program, it will have to call the
undocumented function <code class="function">__wgetmainargs()</code> to get the wide character
argument vector and environment. See gspawn-win32-helper.c in the
GLib sources or init.c in the mingw runtime sources for a prototype
for that function. Alternatively, you can retrieve the Win32 system
level wide character command line passed to the spawned program
using the <code class="function">GetCommandLineW()</code> function.
</p>
<p>
On Windows the low-level child process creation API
<code class="function"><code class="function">CreateProcess()</code></code> doesn't use argument vectors,
but a command line. The C runtime library's
<code class="function">spawn*()</code> family of functions (which
<a class="link" href="glib-Spawning-Processes.html#g-spawn-async-with-pipes"><code class="function">g_spawn_async_with_pipes()</code></a> eventually calls) paste the argument
vector elements together into a command line, and the C runtime startup code
does a corresponding reconstruction of an argument vector from the
command line, to be passed to <code class="function">main()</code>. Complications arise when you have
argument vector elements that contain spaces of double quotes. The
<code class="function">spawn*()</code> functions don't do any quoting or
escaping, but on the other hand the startup code does do unquoting
and unescaping in order to enable receiving arguments with embedded
spaces or double quotes. To work around this asymmetry,
<a class="link" href="glib-Spawning-Processes.html#g-spawn-async-with-pipes"><code class="function">g_spawn_async_with_pipes()</code></a> will do quoting and escaping on argument
vector elements that need it before calling the C runtime
<code class="function">spawn()</code> function.
</p>
<p>
<em class="parameter"><code>envp</code></em> is a <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>-terminated array of strings, where each string
has the form <code class="literal">KEY=VALUE</code>. This will become
the child's environment. If <em class="parameter"><code>envp</code></em> is <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>, the child inherits its
parent's environment.
</p>
<p>
<em class="parameter"><code>flags</code></em> should be the bitwise OR of any flags you want to affect the
function's behaviour. The <a class="link" href="glib-Spawning-Processes.html#G-SPAWN-DO-NOT-REAP-CHILD:CAPS"><code class="literal">G_SPAWN_DO_NOT_REAP_CHILD</code></a> means that 
the child will not automatically be reaped; you must use a
<span class="type">GChildWatch</span> source to be notified about the death of the child 
process. Eventually you must call <a class="link" href="glib-Spawning-Processes.html#g-spawn-close-pid"><code class="function">g_spawn_close_pid()</code></a> on the
<em class="parameter"><code>child_pid</code></em>, in order to free resources which may be associated
with the child process. (On Unix, using a <span class="type">GChildWatch</span> source is
equivalent to calling <code class="function">waitpid()</code> or handling the <code class="literal">SIGCHLD</code> signal 
manually. On Windows, calling <a class="link" href="glib-Spawning-Processes.html#g-spawn-close-pid"><code class="function">g_spawn_close_pid()</code></a> is equivalent
to calling <code class="function">CloseHandle()</code> on the process handle returned in 
<em class="parameter"><code>child_pid</code></em>).
</p>
<p>
<a class="link" href="glib-Spawning-Processes.html#G-SPAWN-LEAVE-DESCRIPTORS-OPEN:CAPS"><code class="literal">G_SPAWN_LEAVE_DESCRIPTORS_OPEN</code></a> means that the parent's open file
descriptors will be inherited by the child; otherwise all
descriptors except stdin/stdout/stderr will be closed before
calling <code class="function">exec()</code> in the child. <a class="link" href="glib-Spawning-Processes.html#G-SPAWN-SEARCH-PATH:CAPS"><code class="literal">G_SPAWN_SEARCH_PATH</code></a> 
means that <code class="literal">argv[0]</code> need not be an absolute path, it
will be looked for in the user's <code class="envar">PATH</code>. 
<a class="link" href="glib-Spawning-Processes.html#G-SPAWN-STDOUT-TO-DEV-NULL:CAPS"><code class="literal">G_SPAWN_STDOUT_TO_DEV_NULL</code></a> means that the child's standard output will 
be discarded, instead of going to the same location as the parent's 
standard output. If you use this flag, <em class="parameter"><code>standard_output</code></em> must be <a class="link" href="glib-Standard-Macros.html#NULL:CAPS"><code class="literal">NULL</code></a>.