nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 /* GIO - GLib Input, Output and Streaming Library
2 *
3 * Copyright © 2012, 2013 Red Hat, Inc.
4 * Copyright © 2012, 2013 Canonical Limited
5 *
6 * This program is free software: you can redistribute it and/or modify
7 * it under the terms of the GNU Lesser General Public License as published
8 * by the Free Software Foundation; either version 2 of the licence or (at
9 * your option) any later version.
10 *
11 * See the included COPYING file for more information.
12 *
13 * Authors: Colin Walters <walters@verbum.org>
14 * Ryan Lortie <desrt@desrt.ca>
15 */
16  
17 /**
18 * SECTION:gsubprocess
19 * @title: GSubprocess
20 * @short_description: Child processes
21 * @include: gio/gio.h
22 * @see_also: #GSubprocessLauncher
23 *
24 * #GSubprocess allows the creation of and interaction with child
25 * processes.
26 *
27 * Processes can be communicated with using standard GIO-style APIs (ie:
28 * #GInputStream, #GOutputStream). There are GIO-style APIs to wait for
29 * process termination (ie: cancellable and with an asynchronous
30 * variant).
31 *
32 * There is an API to force a process to terminate, as well as a
33 * race-free API for sending UNIX signals to a subprocess.
34 *
35 * One major advantage that GIO brings over the core GLib library is
36 * comprehensive API for asynchronous I/O, such
37 * g_output_stream_splice_async(). This makes GSubprocess
38 * significantly more powerful and flexible than equivalent APIs in
39 * some other languages such as the `subprocess.py`
40 * included with Python. For example, using #GSubprocess one could
41 * create two child processes, reading standard output from the first,
42 * processing it, and writing to the input stream of the second, all
43 * without blocking the main loop.
44 *
45 * A powerful g_subprocess_communicate() API is provided similar to the
46 * `communicate()` method of `subprocess.py`. This enables very easy
47 * interaction with a subprocess that has been opened with pipes.
48 *
49 * #GSubprocess defaults to tight control over the file descriptors open
50 * in the child process, avoiding dangling-fd issues that are caused by
51 * a simple fork()/exec(). The only open file descriptors in the
52 * spawned process are ones that were explicitly specified by the
53 * #GSubprocess API (unless %G_SUBPROCESS_FLAGS_INHERIT_FDS was
54 * specified).
55 *
56 * #GSubprocess will quickly reap all child processes as they exit,
57 * avoiding "zombie processes" remaining around for long periods of
58 * time. g_subprocess_wait() can be used to wait for this to happen,
59 * but it will happen even without the call being explicitly made.
60 *
61 * As a matter of principle, #GSubprocess has no API that accepts
62 * shell-style space-separated strings. It will, however, match the
63 * typical shell behaviour of searching the PATH for executables that do
64 * not contain a directory separator in their name.
65 *
66 * #GSubprocess attempts to have a very simple API for most uses (ie:
67 * spawning a subprocess with arguments and support for most typical
68 * kinds of input and output redirection). See g_subprocess_new(). The
69 * #GSubprocessLauncher API is provided for more complicated cases
70 * (advanced types of redirection, environment variable manipulation,
71 * change of working directory, child setup functions, etc).
72 *
73 * A typical use of #GSubprocess will involve calling
74 * g_subprocess_new(), followed by g_subprocess_wait_async() or
75 * g_subprocess_wait(). After the process exits, the status can be
76 * checked using functions such as g_subprocess_get_if_exited() (which
77 * are similar to the familiar WIFEXITED-style POSIX macros).
78 *
79 * Since: 2.40
80 **/
81  
82 #include "config.h"
83  
84 #include "gsubprocess.h"
85 #include "gsubprocesslauncher-private.h"
86 #include "gasyncresult.h"
87 #include "giostream.h"
88 #include "gmemoryinputstream.h"
89 #include "glibintl.h"
90 #include "glib-private.h"
91  
92 #include <string.h>
93 #ifdef G_OS_UNIX
94 #include <gio/gunixoutputstream.h>
95 #include <gio/gfiledescriptorbased.h>
96 #include <gio/gunixinputstream.h>
97 #include <gstdio.h>
98 #include <glib-unix.h>
99 #include <fcntl.h>
100 #endif
101 #ifdef G_OS_WIN32
102 #include <windows.h>
103 #include <io.h>
104 #include "giowin32-priv.h"
105 #endif
106  
107 #ifndef O_BINARY
108 #define O_BINARY 0
109 #endif
110  
111 #ifndef O_CLOEXEC
112 #define O_CLOEXEC 0
113 #else
114 #define HAVE_O_CLOEXEC 1
115 #endif
116  
117 #define COMMUNICATE_READ_SIZE 4096
118  
119 /* A GSubprocess can have two possible states: running and not.
120 *
121 * These two states are reflected by the value of 'pid'. If it is
122 * non-zero then the process is running, with that pid.
123 *
124 * When a GSubprocess is first created with g_object_new() it is not
125 * running. When it is finalized, it is also not running.
126 *
127 * During initable_init(), if the g_spawn() is successful then we
128 * immediately register a child watch and take an extra ref on the
129 * subprocess. That reference doesn't drop until the child has quit,
130 * which is why finalize can only happen in the non-running state. In
131 * the event that the g_spawn() failed we will still be finalizing a
132 * non-running GSubprocess (before returning from g_subprocess_new())
133 * with NULL.
134 *
135 * We make extensive use of the glib worker thread to guarantee
136 * race-free operation. As with all child watches, glib calls waitpid()
137 * in the worker thread. It reports the child exiting to us via the
138 * worker thread (which means that we can do synchronous waits without
139 * running a separate loop). We also send signals to the child process
140 * via the worker thread so that we don't race with waitpid() and
141 * accidentally send a signal to an already-reaped child.
142 */
143 static void initable_iface_init (GInitableIface *initable_iface);
144  
145 typedef GObjectClass GSubprocessClass;
146  
147 struct _GSubprocess
148 {
149 GObject parent;
150  
151 /* only used during construction */
152 GSubprocessLauncher *launcher;
153 GSubprocessFlags flags;
154 gchar **argv;
155  
156 /* state tracking variables */
157 gchar identifier[24];
158 int status;
159 GPid pid;
160  
161 /* list of GTask */
162 GMutex pending_waits_lock;
163 GSList *pending_waits;
164  
165 /* These are the streams created if a pipe is requested via flags. */
166 GOutputStream *stdin_pipe;
167 GInputStream *stdout_pipe;
168 GInputStream *stderr_pipe;
169 };
170  
171 G_DEFINE_TYPE_WITH_CODE (GSubprocess, g_subprocess, G_TYPE_OBJECT,
172 G_IMPLEMENT_INTERFACE (G_TYPE_INITABLE, initable_iface_init));
173  
174 enum
175 {
176 PROP_0,
177 PROP_FLAGS,
178 PROP_ARGV,
179 N_PROPS
180 };
181  
182 #ifdef G_OS_UNIX
183 typedef struct
184 {
185 gint fds[3];
186 GSpawnChildSetupFunc child_setup_func;
187 gpointer child_setup_data;
188 GArray *basic_fd_assignments;
189 GArray *needdup_fd_assignments;
190 } ChildData;
191  
192 static void
193 unset_cloexec (int fd)
194 {
195 int flags;
196 int result;
197  
198 flags = fcntl (fd, F_GETFD, 0);
199  
200 if (flags != -1)
201 {
202 flags &= (~FD_CLOEXEC);
203 do
204 result = fcntl (fd, F_SETFD, flags);
205 while (result == -1 && errno == EINTR);
206 }
207 }
208  
209 static int
210 dupfd_cloexec (int parent_fd)
211 {
212 int fd;
213 #ifdef F_DUPFD_CLOEXEC
214 do
215 fd = fcntl (parent_fd, F_DUPFD_CLOEXEC, 3);
216 while (fd == -1 && errno == EINTR);
217 #else
218 /* OS X Snow Lion and earlier don't have F_DUPFD_CLOEXEC:
219 * https://bugzilla.gnome.org/show_bug.cgi?id=710962
220 */
221 int result, flags;
222 do
223 fd = fcntl (parent_fd, F_DUPFD, 3);
224 while (fd == -1 && errno == EINTR);
225 flags = fcntl (fd, F_GETFD, 0);
226 if (flags != -1)
227 {
228 flags |= FD_CLOEXEC;
229 do
230 result = fcntl (fd, F_SETFD, flags);
231 while (result == -1 && errno == EINTR);
232 }
233 #endif
234 return fd;
235 }
236  
237 /*
238 * Based on code derived from
239 * gnome-terminal:src/terminal-screen.c:terminal_screen_child_setup(),
240 * used under the LGPLv2+ with permission from author.
241 */
242 static void
243 child_setup (gpointer user_data)
244 {
245 ChildData *child_data = user_data;
246 gint i;
247 gint result;
248  
249 /* We're on the child side now. "Rename" the file descriptors in
250 * child_data.fds[] to stdin/stdout/stderr.
251 *
252 * We don't close the originals. It's possible that the originals
253 * should not be closed and if they should be closed then they should
254 * have been created O_CLOEXEC.
255 */
256 for (i = 0; i < 3; i++)
257 if (child_data->fds[i] != -1 && child_data->fds[i] != i)
258 {
259 do
260 result = dup2 (child_data->fds[i], i);
261 while (result == -1 && errno == EINTR);
262 }
263  
264 /* Basic fd assignments we can just unset FD_CLOEXEC */
265 if (child_data->basic_fd_assignments)
266 {
267 for (i = 0; i < child_data->basic_fd_assignments->len; i++)
268 {
269 gint fd = g_array_index (child_data->basic_fd_assignments, int, i);
270  
271 unset_cloexec (fd);
272 }
273 }
274  
275 /* If we're doing remapping fd assignments, we need to handle
276 * the case where the user has specified e.g.:
277 * 5 -> 4, 4 -> 6
278 *
279 * We do this by duping the source fds temporarily.
280 */
281 if (child_data->needdup_fd_assignments)
282 {
283 for (i = 0; i < child_data->needdup_fd_assignments->len; i += 2)
284 {
285 gint parent_fd = g_array_index (child_data->needdup_fd_assignments, int, i);
286 gint new_parent_fd;
287  
288 new_parent_fd = dupfd_cloexec (parent_fd);
289  
290 g_array_index (child_data->needdup_fd_assignments, int, i) = new_parent_fd;
291 }
292 for (i = 0; i < child_data->needdup_fd_assignments->len; i += 2)
293 {
294 gint parent_fd = g_array_index (child_data->needdup_fd_assignments, int, i);
295 gint child_fd = g_array_index (child_data->needdup_fd_assignments, int, i+1);
296  
297 if (parent_fd == child_fd)
298 {
299 unset_cloexec (parent_fd);
300 }
301 else
302 {
303 do
304 result = dup2 (parent_fd, child_fd);
305 while (result == -1 && errno == EINTR);
306 (void) close (parent_fd);
307 }
308 }
309 }
310  
311 if (child_data->child_setup_func)
312 child_data->child_setup_func (child_data->child_setup_data);
313 }
314 #endif
315  
316 static GInputStream *
317 platform_input_stream_from_spawn_fd (gint fd)
318 {
319 if (fd < 0)
320 return NULL;
321  
322 #ifdef G_OS_UNIX
323 return g_unix_input_stream_new (fd, TRUE);
324 #else
325 return g_win32_input_stream_new_from_fd (fd, TRUE);
326 #endif
327 }
328  
329 static GOutputStream *
330 platform_output_stream_from_spawn_fd (gint fd)
331 {
332 if (fd < 0)
333 return NULL;
334  
335 #ifdef G_OS_UNIX
336 return g_unix_output_stream_new (fd, TRUE);
337 #else
338 return g_win32_output_stream_new_from_fd (fd, TRUE);
339 #endif
340 }
341  
342 #ifdef G_OS_UNIX
343 static gint
344 unix_open_file (const char *filename,
345 gint mode,
346 GError **error)
347 {
348 gint my_fd;
349  
350 my_fd = g_open (filename, mode | O_BINARY | O_CLOEXEC, 0666);
351  
352 /* If we return -1 we should also set the error */
353 if (my_fd < 0)
354 {
355 gint saved_errno = errno;
356 char *display_name;
357  
358 display_name = g_filename_display_name (filename);
359 g_set_error (error, G_IO_ERROR, g_io_error_from_errno (saved_errno),
360 _("Error opening file '%s': %s"), display_name,
361 g_strerror (saved_errno));
362 g_free (display_name);
363 /* fall through... */
364 }
365 #ifndef HAVE_O_CLOEXEC
366 else
367 fcntl (my_fd, F_SETFD, FD_CLOEXEC);
368 #endif
369  
370 return my_fd;
371 }
372 #endif
373  
374 static void
375 g_subprocess_set_property (GObject *object,
376 guint prop_id,
377 const GValue *value,
378 GParamSpec *pspec)
379 {
380 GSubprocess *self = G_SUBPROCESS (object);
381  
382 switch (prop_id)
383 {
384 case PROP_FLAGS:
385 self->flags = g_value_get_flags (value);
386 break;
387  
388 case PROP_ARGV:
389 self->argv = g_value_dup_boxed (value);
390 break;
391  
392 default:
393 g_assert_not_reached ();
394 }
395 }
396  
397 static gboolean
398 g_subprocess_exited (GPid pid,
399 gint status,
400 gpointer user_data)
401 {
402 GSubprocess *self = user_data;
403 GSList *tasks;
404  
405 g_assert (self->pid == pid);
406  
407 g_mutex_lock (&self->pending_waits_lock);
408 self->status = status;
409 tasks = self->pending_waits;
410 self->pending_waits = NULL;
411 self->pid = 0;
412 g_mutex_unlock (&self->pending_waits_lock);
413  
414 /* Signal anyone in g_subprocess_wait_async() to wake up now */
415 while (tasks)
416 {
417 g_task_return_boolean (tasks->data, TRUE);
418 g_object_unref (tasks->data);
419 tasks = g_slist_delete_link (tasks, tasks);
420 }
421  
422 g_spawn_close_pid (pid);
423  
424 return FALSE;
425 }
426  
427 static gboolean
428 initable_init (GInitable *initable,
429 GCancellable *cancellable,
430 GError **error)
431 {
432 GSubprocess *self = G_SUBPROCESS (initable);
433 #ifdef G_OS_UNIX
434 ChildData child_data = { { -1, -1, -1 }, 0 };
435 #endif
436 gint *pipe_ptrs[3] = { NULL, NULL, NULL };
437 gint pipe_fds[3] = { -1, -1, -1 };
438 gint close_fds[3] = { -1, -1, -1 };
439 GSpawnFlags spawn_flags = 0;
440 gboolean success = FALSE;
441 gint i;
442  
443 /* this is a programmer error */
444 if (!self->argv || !self->argv[0] || !self->argv[0][0])
445 return FALSE;
446  
447 if (g_cancellable_set_error_if_cancelled (cancellable, error))
448 return FALSE;
449  
450 /* We must setup the three fds that will end up in the child as stdin,
451 * stdout and stderr.
452 *
453 * First, stdin.
454 */
455 if (self->flags & G_SUBPROCESS_FLAGS_STDIN_INHERIT)
456 spawn_flags |= G_SPAWN_CHILD_INHERITS_STDIN;
457 else if (self->flags & G_SUBPROCESS_FLAGS_STDIN_PIPE)
458 pipe_ptrs[0] = &pipe_fds[0];
459 #ifdef G_OS_UNIX
460 else if (self->launcher)
461 {
462 if (self->launcher->stdin_fd != -1)
463 child_data.fds[0] = self->launcher->stdin_fd;
464 else if (self->launcher->stdin_path != NULL)
465 {
466 child_data.fds[0] = close_fds[0] = unix_open_file (self->launcher->stdin_path, O_RDONLY, error);
467 if (child_data.fds[0] == -1)
468 goto out;
469 }
470 }
471 #endif
472  
473 /* Next, stdout. */
474 if (self->flags & G_SUBPROCESS_FLAGS_STDOUT_SILENCE)
475 spawn_flags |= G_SPAWN_STDOUT_TO_DEV_NULL;
476 else if (self->flags & G_SUBPROCESS_FLAGS_STDOUT_PIPE)
477 pipe_ptrs[1] = &pipe_fds[1];
478 #ifdef G_OS_UNIX
479 else if (self->launcher)
480 {
481 if (self->launcher->stdout_fd != -1)
482 child_data.fds[1] = self->launcher->stdout_fd;
483 else if (self->launcher->stdout_path != NULL)
484 {
485 child_data.fds[1] = close_fds[1] = unix_open_file (self->launcher->stdout_path, O_CREAT | O_WRONLY, error);
486 if (child_data.fds[1] == -1)
487 goto out;
488 }
489 }
490 #endif
491  
492 /* Finally, stderr. */
493 if (self->flags & G_SUBPROCESS_FLAGS_STDERR_SILENCE)
494 spawn_flags |= G_SPAWN_STDERR_TO_DEV_NULL;
495 else if (self->flags & G_SUBPROCESS_FLAGS_STDERR_PIPE)
496 pipe_ptrs[2] = &pipe_fds[2];
497 #ifdef G_OS_UNIX
498 else if (self->flags & G_SUBPROCESS_FLAGS_STDERR_MERGE)
499 /* This will work because stderr gets setup after stdout. */
500 child_data.fds[2] = 1;
501 else if (self->launcher)
502 {
503 if (self->launcher->stderr_fd != -1)
504 child_data.fds[2] = self->launcher->stderr_fd;
505 else if (self->launcher->stderr_path != NULL)
506 {
507 child_data.fds[2] = close_fds[2] = unix_open_file (self->launcher->stderr_path, O_CREAT | O_WRONLY, error);
508 if (child_data.fds[2] == -1)
509 goto out;
510 }
511 }
512 #endif
513  
514 #ifdef G_OS_UNIX
515 if (self->launcher)
516 {
517 child_data.basic_fd_assignments = self->launcher->basic_fd_assignments;
518 child_data.needdup_fd_assignments = self->launcher->needdup_fd_assignments;
519 }
520 #endif
521  
522 /* argv0 has no '/' in it? We better do a PATH lookup. */
523 if (strchr (self->argv[0], G_DIR_SEPARATOR) == NULL)
524 {
525 if (self->launcher && self->launcher->path_from_envp)
526 spawn_flags |= G_SPAWN_SEARCH_PATH_FROM_ENVP;
527 else
528 spawn_flags |= G_SPAWN_SEARCH_PATH;
529 }
530  
531 if (self->flags & G_SUBPROCESS_FLAGS_INHERIT_FDS)
532 spawn_flags |= G_SPAWN_LEAVE_DESCRIPTORS_OPEN;
533  
534 spawn_flags |= G_SPAWN_DO_NOT_REAP_CHILD;
535 spawn_flags |= G_SPAWN_CLOEXEC_PIPES;
536  
537 #ifdef G_OS_UNIX
538 child_data.child_setup_func = self->launcher ? self->launcher->child_setup_func : NULL;
539 child_data.child_setup_data = self->launcher ? self->launcher->child_setup_user_data : NULL;
540 #endif
541  
542 success = g_spawn_async_with_pipes (self->launcher ? self->launcher->cwd : NULL,
543 self->argv,
544 self->launcher ? self->launcher->envp : NULL,
545 spawn_flags,
546 #ifdef G_OS_UNIX
547 child_setup, &child_data,
548 #else
549 NULL, NULL,
550 #endif
551 &self->pid,
552 pipe_ptrs[0], pipe_ptrs[1], pipe_ptrs[2],
553 error);
554 g_assert (success == (self->pid != 0));
555  
556 {
557 guint64 identifier;
558 gint s;
559  
560 #ifdef G_OS_WIN32
561 identifier = (guint64) GetProcessId (self->pid);
562 #else
563 identifier = (guint64) self->pid;
564 #endif
565  
566 s = g_snprintf (self->identifier, sizeof self->identifier, "%"G_GUINT64_FORMAT, identifier);
567 g_assert (0 < s && s < sizeof self->identifier);
568 }
569  
570 /* Start attempting to reap the child immediately */
571 if (success)
572 {
573 GMainContext *worker_context;
574 GSource *source;
575  
576 worker_context = GLIB_PRIVATE_CALL (g_get_worker_context) ();
577 source = g_child_watch_source_new (self->pid);
578 g_source_set_callback (source, (GSourceFunc) g_subprocess_exited, g_object_ref (self), g_object_unref);
579 g_source_attach (source, worker_context);
580 g_source_unref (source);
581 }
582  
583 #ifdef G_OS_UNIX
584 out:
585 #endif
586 /* we don't need this past init... */
587 self->launcher = NULL;
588  
589 for (i = 0; i < 3; i++)
590 if (close_fds[i] != -1)
591 close (close_fds[i]);
592  
593 self->stdin_pipe = platform_output_stream_from_spawn_fd (pipe_fds[0]);
594 self->stdout_pipe = platform_input_stream_from_spawn_fd (pipe_fds[1]);
595 self->stderr_pipe = platform_input_stream_from_spawn_fd (pipe_fds[2]);
596  
597 return success;
598 }
599  
600 static void
601 g_subprocess_finalize (GObject *object)
602 {
603 GSubprocess *self = G_SUBPROCESS (object);
604  
605 g_assert (self->pending_waits == NULL);
606 g_assert (self->pid == 0);
607  
608 g_clear_object (&self->stdin_pipe);
609 g_clear_object (&self->stdout_pipe);
610 g_clear_object (&self->stderr_pipe);
611 g_strfreev (self->argv);
612  
613 g_mutex_clear (&self->pending_waits_lock);
614  
615 G_OBJECT_CLASS (g_subprocess_parent_class)->finalize (object);
616 }
617  
618 static void
619 g_subprocess_init (GSubprocess *self)
620 {
621 g_mutex_init (&self->pending_waits_lock);
622 }
623  
624 static void
625 initable_iface_init (GInitableIface *initable_iface)
626 {
627 initable_iface->init = initable_init;
628 }
629  
630 static void
631 g_subprocess_class_init (GSubprocessClass *class)
632 {
633 GObjectClass *gobject_class = G_OBJECT_CLASS (class);
634  
635 gobject_class->finalize = g_subprocess_finalize;
636 gobject_class->set_property = g_subprocess_set_property;
637  
638 g_object_class_install_property (gobject_class, PROP_FLAGS,
639 g_param_spec_flags ("flags", P_("Flags"), P_("Subprocess flags"),
640 G_TYPE_SUBPROCESS_FLAGS, 0, G_PARAM_WRITABLE |
641 G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
642 g_object_class_install_property (gobject_class, PROP_ARGV,
643 g_param_spec_boxed ("argv", P_("Arguments"), P_("Argument vector"),
644 G_TYPE_STRV, G_PARAM_WRITABLE |
645 G_PARAM_CONSTRUCT_ONLY | G_PARAM_STATIC_STRINGS));
646 }
647  
648 /**
649 * g_subprocess_new: (skip)
650 * @flags: flags that define the behaviour of the subprocess
651 * @error: (allow-none): return location for an error, or %NULL
652 * @argv0: first commandline argument to pass to the subprocess
653 * @...: more commandline arguments, followed by %NULL
654 *
655 * Create a new process with the given flags and varargs argument
656 * list. By default, matching the g_spawn_async() defaults, the
657 * child's stdin will be set to the system null device, and
658 * stdout/stderr will be inherited from the parent. You can use
659 * @flags to control this behavior.
660 *
661 * The argument list must be terminated with %NULL.
662 *
663 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
664 * will be set)
665 *
666 * Since: 2.40
667 */
668 GSubprocess *
669 g_subprocess_new (GSubprocessFlags flags,
670 GError **error,
671 const gchar *argv0,
672 ...)
673 {
674 GSubprocess *result;
675 GPtrArray *args;
676 const gchar *arg;
677 va_list ap;
678  
679 g_return_val_if_fail (argv0 != NULL && argv0[0] != '\0', NULL);
680 g_return_val_if_fail (error == NULL || *error == NULL, NULL);
681  
682 args = g_ptr_array_new ();
683  
684 va_start (ap, argv0);
685 g_ptr_array_add (args, (gchar *) argv0);
686 while ((arg = va_arg (ap, const gchar *)))
687 g_ptr_array_add (args, (gchar *) arg);
688 g_ptr_array_add (args, NULL);
689 va_end (ap);
690  
691 result = g_subprocess_newv ((const gchar * const *) args->pdata, flags, error);
692  
693 g_ptr_array_free (args, TRUE);
694  
695 return result;
696 }
697  
698 /**
699 * g_subprocess_newv: (rename-to g_subprocess_new)
700 * @argv: (array zero-terminated=1) (element-type utf8): commandline arguments for the subprocess
701 * @flags: flags that define the behaviour of the subprocess
702 * @error: (allow-none): return location for an error, or %NULL
703 *
704 * Create a new process with the given flags and argument list.
705 *
706 * The argument list is expected to be %NULL-terminated.
707 *
708 * Returns: A newly created #GSubprocess, or %NULL on error (and @error
709 * will be set)
710 *
711 * Since: 2.40
712 */
713 GSubprocess *
714 g_subprocess_newv (const gchar * const *argv,
715 GSubprocessFlags flags,
716 GError **error)
717 {
718 g_return_val_if_fail (argv != NULL && argv[0] != NULL && argv[0][0] != '\0', NULL);
719  
720 return g_initable_new (G_TYPE_SUBPROCESS, NULL, error,
721 "argv", argv,
722 "flags", flags,
723 NULL);
724 }
725  
726 /**
727 * g_subprocess_get_identifier:
728 * @subprocess: a #GSubprocess
729 *
730 * On UNIX, returns the process ID as a decimal string.
731 * On Windows, returns the result of GetProcessId() also as a string.
732 */
733 const gchar *
734 g_subprocess_get_identifier (GSubprocess *subprocess)
735 {
736 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), NULL);
737  
738 if (subprocess->pid)
739 return subprocess->identifier;
740 else
741 return NULL;
742 }
743  
744 /**
745 * g_subprocess_get_stdin_pipe:
746 * @subprocess: a #GSubprocess
747 *
748 * Gets the #GOutputStream that you can write to in order to give data
749 * to the stdin of @subprocess.
750 *
751 * The process must have been created with
752 * %G_SUBPROCESS_FLAGS_STDIN_PIPE.
753 *
754 * Returns: (transfer none): the stdout pipe
755 *
756 * Since: 2.40
757 **/
758 GOutputStream *
759 g_subprocess_get_stdin_pipe (GSubprocess *subprocess)
760 {
761 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), NULL);
762 g_return_val_if_fail (subprocess->stdin_pipe, NULL);
763  
764 return subprocess->stdin_pipe;
765 }
766  
767 /**
768 * g_subprocess_get_stdout_pipe:
769 * @subprocess: a #GSubprocess
770 *
771 * Gets the #GInputStream from which to read the stdout output of
772 * @subprocess.
773 *
774 * The process must have been created with
775 * %G_SUBPROCESS_FLAGS_STDOUT_PIPE.
776 *
777 * Returns: (transfer none): the stdout pipe
778 *
779 * Since: 2.40
780 **/
781 GInputStream *
782 g_subprocess_get_stdout_pipe (GSubprocess *subprocess)
783 {
784 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), NULL);
785 g_return_val_if_fail (subprocess->stdout_pipe, NULL);
786  
787 return subprocess->stdout_pipe;
788 }
789  
790 /**
791 * g_subprocess_get_stderr_pipe:
792 * @subprocess: a #GSubprocess
793 *
794 * Gets the #GInputStream from which to read the stderr output of
795 * @subprocess.
796 *
797 * The process must have been created with
798 * %G_SUBPROCESS_FLAGS_STDERR_PIPE.
799 *
800 * Returns: (transfer none): the stderr pipe
801 *
802 * Since: 2.40
803 **/
804 GInputStream *
805 g_subprocess_get_stderr_pipe (GSubprocess *subprocess)
806 {
807 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), NULL);
808 g_return_val_if_fail (subprocess->stderr_pipe, NULL);
809  
810 return subprocess->stderr_pipe;
811 }
812  
813 static void
814 g_subprocess_wait_cancelled (GCancellable *cancellable,
815 gpointer user_data)
816 {
817 GTask *task = user_data;
818 GSubprocess *self;
819  
820 self = g_task_get_source_object (task);
821  
822 g_mutex_lock (&self->pending_waits_lock);
823 self->pending_waits = g_slist_remove (self->pending_waits, task);
824 g_mutex_unlock (&self->pending_waits_lock);
825  
826 g_task_return_boolean (task, FALSE);
827 g_object_unref (task);
828 }
829  
830 /**
831 * g_subprocess_wait_async:
832 * @subprocess: a #GSubprocess
833 * @cancellable: a #GCancellable, or %NULL
834 * @callback: a #GAsyncReadyCallback to call when the operation is complete
835 * @user_data: user_data for @callback
836 *
837 * Wait for the subprocess to terminate.
838 *
839 * This is the asynchronous version of g_subprocess_wait().
840 *
841 * Since: 2.40
842 */
843 void
844 g_subprocess_wait_async (GSubprocess *subprocess,
845 GCancellable *cancellable,
846 GAsyncReadyCallback callback,
847 gpointer user_data)
848 {
849 GTask *task;
850  
851 task = g_task_new (subprocess, cancellable, callback, user_data);
852  
853 g_mutex_lock (&subprocess->pending_waits_lock);
854 if (subprocess->pid)
855 {
856 /* Only bother with cancellable if we're putting it in the list.
857 * If not, it's going to dispatch immediately anyway and we will
858 * see the cancellation in the _finish().
859 */
860 if (cancellable)
861 g_signal_connect_object (cancellable, "cancelled", G_CALLBACK (g_subprocess_wait_cancelled), task, 0);
862  
863 subprocess->pending_waits = g_slist_prepend (subprocess->pending_waits, task);
864 task = NULL;
865 }
866 g_mutex_unlock (&subprocess->pending_waits_lock);
867  
868 /* If we still have task then it's because did_exit is already TRUE */
869 if (task != NULL)
870 {
871 g_task_return_boolean (task, TRUE);
872 g_object_unref (task);
873 }
874 }
875  
876 /**
877 * g_subprocess_wait_finish:
878 * @subprocess: a #GSubprocess
879 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
880 * @error: a pointer to a %NULL #GError, or %NULL
881 *
882 * Collects the result of a previous call to
883 * g_subprocess_wait_async().
884 *
885 * Returns: %TRUE if successful, or %FALSE with @error set
886 *
887 * Since: 2.40
888 */
889 gboolean
890 g_subprocess_wait_finish (GSubprocess *subprocess,
891 GAsyncResult *result,
892 GError **error)
893 {
894 return g_task_propagate_boolean (G_TASK (result), error);
895 }
896  
897 /* Some generic helpers for emulating synchronous operations using async
898 * operations.
899 */
900 static void
901 g_subprocess_sync_setup (void)
902 {
903 g_main_context_push_thread_default (g_main_context_new ());
904 }
905  
906 static void
907 g_subprocess_sync_done (GObject *source_object,
908 GAsyncResult *result,
909 gpointer user_data)
910 {
911 GAsyncResult **result_ptr = user_data;
912  
913 *result_ptr = g_object_ref (result);
914 }
915  
916 static void
917 g_subprocess_sync_complete (GAsyncResult **result)
918 {
919 GMainContext *context = g_main_context_get_thread_default ();
920  
921 while (!*result)
922 g_main_context_iteration (context, TRUE);
923  
924 g_main_context_pop_thread_default (context);
925 g_main_context_unref (context);
926 }
927  
928 /**
929 * g_subprocess_wait:
930 * @subprocess: a #GSubprocess
931 * @cancellable: a #GCancellable
932 * @error: a #GError
933 *
934 * Synchronously wait for the subprocess to terminate.
935 *
936 * After the process terminates you can query its exit status with
937 * functions such as g_subprocess_get_if_exited() and
938 * g_subprocess_get_exit_status().
939 *
940 * This function does not fail in the case of the subprocess having
941 * abnormal termination. See g_subprocess_wait_check() for that.
942 *
943 * Cancelling @cancellable doesn't kill the subprocess. Call
944 * g_subprocess_force_exit() if it is desirable.
945 *
946 * Returns: %TRUE on success, %FALSE if @cancellable was cancelled
947 *
948 * Since: 2.40
949 */
950 gboolean
951 g_subprocess_wait (GSubprocess *subprocess,
952 GCancellable *cancellable,
953 GError **error)
954 {
955 GAsyncResult *result = NULL;
956 gboolean success;
957  
958 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), FALSE);
959  
960 /* Synchronous waits are actually the 'more difficult' case because we
961 * need to deal with the possibility of cancellation. That more or
962 * less implies that we need a main context (to dispatch either of the
963 * possible reasons for the operation ending).
964 *
965 * So we make one and then do this async...
966 */
967  
968 if (g_cancellable_set_error_if_cancelled (cancellable, error))
969 return FALSE;
970  
971 /* We can shortcut in the case that the process already quit (but only
972 * after we checked the cancellable).
973 */
974 if (subprocess->pid == 0)
975 return TRUE;
976  
977 /* Otherwise, we need to do this the long way... */
978 g_subprocess_sync_setup ();
979 g_subprocess_wait_async (subprocess, cancellable, g_subprocess_sync_done, &result);
980 g_subprocess_sync_complete (&result);
981 success = g_subprocess_wait_finish (subprocess, result, error);
982 g_object_unref (result);
983  
984 return success;
985 }
986  
987 /**
988 * g_subprocess_wait_check:
989 * @subprocess: a #GSubprocess
990 * @cancellable: a #GCancellable
991 * @error: a #GError
992 *
993 * Combines g_subprocess_wait() with g_spawn_check_exit_status().
994 *
995 * Returns: %TRUE on success, %FALSE if process exited abnormally, or
996 * @cancellable was cancelled
997 *
998 * Since: 2.40
999 */
1000 gboolean
1001 g_subprocess_wait_check (GSubprocess *subprocess,
1002 GCancellable *cancellable,
1003 GError **error)
1004 {
1005 return g_subprocess_wait (subprocess, cancellable, error) &&
1006 g_spawn_check_exit_status (subprocess->status, error);
1007 }
1008  
1009 /**
1010 * g_subprocess_wait_check_async:
1011 * @subprocess: a #GSubprocess
1012 * @cancellable: a #GCancellable, or %NULL
1013 * @callback: a #GAsyncReadyCallback to call when the operation is complete
1014 * @user_data: user_data for @callback
1015 *
1016 * Combines g_subprocess_wait_async() with g_spawn_check_exit_status().
1017 *
1018 * This is the asynchronous version of g_subprocess_wait_check().
1019 *
1020 * Since: 2.40
1021 */
1022 void
1023 g_subprocess_wait_check_async (GSubprocess *subprocess,
1024 GCancellable *cancellable,
1025 GAsyncReadyCallback callback,
1026 gpointer user_data)
1027 {
1028 g_subprocess_wait_async (subprocess, cancellable, callback, user_data);
1029 }
1030  
1031 /**
1032 * g_subprocess_wait_check_finish:
1033 * @subprocess: a #GSubprocess
1034 * @result: the #GAsyncResult passed to your #GAsyncReadyCallback
1035 * @error: a pointer to a %NULL #GError, or %NULL
1036 *
1037 * Collects the result of a previous call to
1038 * g_subprocess_wait_check_async().
1039 *
1040 * Returns: %TRUE if successful, or %FALSE with @error set
1041 *
1042 * Since: 2.40
1043 */
1044 gboolean
1045 g_subprocess_wait_check_finish (GSubprocess *subprocess,
1046 GAsyncResult *result,
1047 GError **error)
1048 {
1049 return g_subprocess_wait_finish (subprocess, result, error) &&
1050 g_spawn_check_exit_status (subprocess->status, error);
1051 }
1052  
1053 #ifdef G_OS_UNIX
1054 typedef struct
1055 {
1056 GSubprocess *subprocess;
1057 gint signalnum;
1058 } SignalRecord;
1059  
1060 static gboolean
1061 g_subprocess_actually_send_signal (gpointer user_data)
1062 {
1063 SignalRecord *signal_record = user_data;
1064  
1065 /* The pid is set to zero from the worker thread as well, so we don't
1066 * need to take a lock in order to prevent it from changing under us.
1067 */
1068 if (signal_record->subprocess->pid)
1069 kill (signal_record->subprocess->pid, signal_record->signalnum);
1070  
1071 g_object_unref (signal_record->subprocess);
1072  
1073 g_slice_free (SignalRecord, signal_record);
1074  
1075 return FALSE;
1076 }
1077  
1078 static void
1079 g_subprocess_dispatch_signal (GSubprocess *subprocess,
1080 gint signalnum)
1081 {
1082 SignalRecord signal_record = { g_object_ref (subprocess), signalnum };
1083  
1084 g_return_if_fail (G_IS_SUBPROCESS (subprocess));
1085  
1086 /* This MUST be a lower priority than the priority that the child
1087 * watch source uses in initable_init().
1088 *
1089 * Reaping processes, reporting the results back to GSubprocess and
1090 * sending signals is all done in the glib worker thread. We cannot
1091 * have a kill() done after the reap and before the report without
1092 * risking killing a process that's no longer there so the kill()
1093 * needs to have the lower priority.
1094 *
1095 * G_PRIORITY_HIGH_IDLE is lower priority than G_PRIORITY_DEFAULT.
1096 */
1097 g_main_context_invoke_full (GLIB_PRIVATE_CALL (g_get_worker_context) (),
1098 G_PRIORITY_HIGH_IDLE,
1099 g_subprocess_actually_send_signal,
1100 g_slice_dup (SignalRecord, &signal_record),
1101 NULL);
1102 }
1103  
1104 /**
1105 * g_subprocess_send_signal:
1106 * @subprocess: a #GSubprocess
1107 * @signal_num: the signal number to send
1108 *
1109 * Sends the UNIX signal @signal_num to the subprocess, if it is still
1110 * running.
1111 *
1112 * This API is race-free. If the subprocess has terminated, it will not
1113 * be signalled.
1114 *
1115 * This API is not available on Windows.
1116 *
1117 * Since: 2.40
1118 **/
1119 void
1120 g_subprocess_send_signal (GSubprocess *subprocess,
1121 gint signal_num)
1122 {
1123 g_return_if_fail (G_IS_SUBPROCESS (subprocess));
1124  
1125 g_subprocess_dispatch_signal (subprocess, signal_num);
1126 }
1127 #endif
1128  
1129 /**
1130 * g_subprocess_force_exit:
1131 * @subprocess: a #GSubprocess
1132 *
1133 * Use an operating-system specific method to attempt an immediate,
1134 * forceful termination of the process. There is no mechanism to
1135 * determine whether or not the request itself was successful;
1136 * however, you can use g_subprocess_wait() to monitor the status of
1137 * the process after calling this function.
1138 *
1139 * On Unix, this function sends %SIGKILL.
1140 *
1141 * Since: 2.40
1142 **/
1143 void
1144 g_subprocess_force_exit (GSubprocess *subprocess)
1145 {
1146 g_return_if_fail (G_IS_SUBPROCESS (subprocess));
1147  
1148 #ifdef G_OS_UNIX
1149 g_subprocess_dispatch_signal (subprocess, SIGKILL);
1150 #else
1151 TerminateProcess (subprocess->pid, 1);
1152 #endif
1153 }
1154  
1155 /**
1156 * g_subprocess_get_status:
1157 * @subprocess: a #GSubprocess
1158 *
1159 * Gets the raw status code of the process, as from waitpid().
1160 *
1161 * This value has no particular meaning, but it can be used with the
1162 * macros defined by the system headers such as WIFEXITED. It can also
1163 * be used with g_spawn_check_exit_status().
1164 *
1165 * It is more likely that you want to use g_subprocess_get_if_exited()
1166 * followed by g_subprocess_get_exit_status().
1167 *
1168 * It is an error to call this function before g_subprocess_wait() has
1169 * returned.
1170 *
1171 * Returns: the (meaningless) waitpid() exit status from the kernel
1172 *
1173 * Since: 2.40
1174 **/
1175 gint
1176 g_subprocess_get_status (GSubprocess *subprocess)
1177 {
1178 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), FALSE);
1179 g_return_val_if_fail (subprocess->pid == 0, FALSE);
1180  
1181 return subprocess->status;
1182 }
1183  
1184 /**
1185 * g_subprocess_get_successful:
1186 * @subprocess: a #GSubprocess
1187 *
1188 * Checks if the process was "successful". A process is considered
1189 * successful if it exited cleanly with an exit status of 0, either by
1190 * way of the exit() system call or return from main().
1191 *
1192 * It is an error to call this function before g_subprocess_wait() has
1193 * returned.
1194 *
1195 * Returns: %TRUE if the process exited cleanly with a exit status of 0
1196 *
1197 * Since: 2.40
1198 **/
1199 gboolean
1200 g_subprocess_get_successful (GSubprocess *subprocess)
1201 {
1202 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), FALSE);
1203 g_return_val_if_fail (subprocess->pid == 0, FALSE);
1204  
1205 #ifdef G_OS_UNIX
1206 return WIFEXITED (subprocess->status) && WEXITSTATUS (subprocess->status) == 0;
1207 #else
1208 return subprocess->status == 0;
1209 #endif
1210 }
1211  
1212 /**
1213 * g_subprocess_get_if_exited:
1214 * @subprocess: a #GSubprocess
1215 *
1216 * Check if the given subprocess exited normally (ie: by way of exit()
1217 * or return from main()).
1218 *
1219 * This is equivalent to the system WIFEXITED macro.
1220 *
1221 * It is an error to call this function before g_subprocess_wait() has
1222 * returned.
1223 *
1224 * Returns: %TRUE if the case of a normal exit
1225 *
1226 * Since: 2.40
1227 **/
1228 gboolean
1229 g_subprocess_get_if_exited (GSubprocess *subprocess)
1230 {
1231 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), FALSE);
1232 g_return_val_if_fail (subprocess->pid == 0, FALSE);
1233  
1234 #ifdef G_OS_UNIX
1235 return WIFEXITED (subprocess->status);
1236 #else
1237 return TRUE;
1238 #endif
1239 }
1240  
1241 /**
1242 * g_subprocess_get_exit_status:
1243 * @subprocess: a #GSubprocess
1244 *
1245 * Check the exit status of the subprocess, given that it exited
1246 * normally. This is the value passed to the exit() system call or the
1247 * return value from main.
1248 *
1249 * This is equivalent to the system WEXITSTATUS macro.
1250 *
1251 * It is an error to call this function before g_subprocess_wait() and
1252 * unless g_subprocess_get_if_exited() returned %TRUE.
1253 *
1254 * Returns: the exit status
1255 *
1256 * Since: 2.40
1257 **/
1258 gint
1259 g_subprocess_get_exit_status (GSubprocess *subprocess)
1260 {
1261 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), 1);
1262 g_return_val_if_fail (subprocess->pid == 0, 1);
1263  
1264 #ifdef G_OS_UNIX
1265 g_return_val_if_fail (WIFEXITED (subprocess->status), 1);
1266  
1267 return WEXITSTATUS (subprocess->status);
1268 #else
1269 return subprocess->status;
1270 #endif
1271 }
1272  
1273 /**
1274 * g_subprocess_get_if_signaled:
1275 * @subprocess: a #GSubprocess
1276 *
1277 * Check if the given subprocess terminated in response to a signal.
1278 *
1279 * This is equivalent to the system WIFSIGNALED macro.
1280 *
1281 * It is an error to call this function before g_subprocess_wait() has
1282 * returned.
1283 *
1284 * Returns: %TRUE if the case of termination due to a signal
1285 *
1286 * Since: 2.40
1287 **/
1288 gboolean
1289 g_subprocess_get_if_signaled (GSubprocess *subprocess)
1290 {
1291 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), FALSE);
1292 g_return_val_if_fail (subprocess->pid == 0, FALSE);
1293  
1294 #ifdef G_OS_UNIX
1295 return WIFSIGNALED (subprocess->status);
1296 #else
1297 return FALSE;
1298 #endif
1299 }
1300  
1301 /**
1302 * g_subprocess_get_term_sig:
1303 * @subprocess: a #GSubprocess
1304 *
1305 * Get the signal number that caused the subprocess to terminate, given
1306 * that it terminated due to a signal.
1307 *
1308 * This is equivalent to the system WTERMSIG macro.
1309 *
1310 * It is an error to call this function before g_subprocess_wait() and
1311 * unless g_subprocess_get_if_signaled() returned %TRUE.
1312 *
1313 * Returns: the signal causing termination
1314 *
1315 * Since: 2.40
1316 **/
1317 gint
1318 g_subprocess_get_term_sig (GSubprocess *subprocess)
1319 {
1320 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), 0);
1321 g_return_val_if_fail (subprocess->pid == 0, 0);
1322  
1323 #ifdef G_OS_UNIX
1324 g_return_val_if_fail (WIFSIGNALED (subprocess->status), 0);
1325  
1326 return WTERMSIG (subprocess->status);
1327 #else
1328 g_critical ("g_subprocess_get_term_sig() called on Windows, where "
1329 "g_subprocess_get_if_signaled() always returns FALSE...");
1330 return 0;
1331 #endif
1332 }
1333  
1334 /*< private >*/
1335 void
1336 g_subprocess_set_launcher (GSubprocess *subprocess,
1337 GSubprocessLauncher *launcher)
1338 {
1339 subprocess->launcher = launcher;
1340 }
1341  
1342  
1343 /* g_subprocess_communicate implementation below:
1344 *
1345 * This is a tough problem. We have to watch 5 things at the same time:
1346 *
1347 * - writing to stdin made progress
1348 * - reading from stdout made progress
1349 * - reading from stderr made progress
1350 * - process terminated
1351 * - cancellable being cancelled by caller
1352 *
1353 * We use a GMainContext for all of these (either as async function
1354 * calls or as a GSource (in the case of the cancellable). That way at
1355 * least we don't have to worry about threading.
1356 *
1357 * For the sync case we use the usual trick of creating a private main
1358 * context and iterating it until completion.
1359 *
1360 * It's very possible that the process will dump a lot of data to stdout
1361 * just before it quits, so we can easily have data to read from stdout
1362 * and see the process has terminated at the same time. We want to make
1363 * sure that we read all of the data from the pipes first, though, so we
1364 * do IO operations at a higher priority than the wait operation (which
1365 * is at G_IO_PRIORITY_DEFAULT). Even in the case that we have to do
1366 * multiple reads to get this data, the pipe() will always be polling
1367 * as ready and with the async result for the read at a higher priority,
1368 * the main context will not dispatch the completion for the wait().
1369 *
1370 * We keep our own private GCancellable. In the event that any of the
1371 * above suffers from an error condition (including the user cancelling
1372 * their cancellable) we immediately dispatch the GTask with the error
1373 * result and fire our cancellable to cleanup any pending operations.
1374 * In the case that the error is that the user's cancellable was fired,
1375 * it's vaguely wasteful to report an error because GTask will handle
1376 * this automatically, so we just return FALSE.
1377 *
1378 * We let each pending sub-operation take a ref on the GTask of the
1379 * communicate operation. We have to be careful that we don't report
1380 * the task completion more than once, though, so we keep a flag for
1381 * that.
1382 */
1383 typedef struct
1384 {
1385 const gchar *stdin_data;
1386 gsize stdin_length;
1387 gsize stdin_offset;
1388  
1389 gboolean add_nul;
1390  
1391 GInputStream *stdin_buf;
1392 GMemoryOutputStream *stdout_buf;
1393 GMemoryOutputStream *stderr_buf;
1394  
1395 GCancellable *cancellable;
1396 GSource *cancellable_source;
1397  
1398 guint outstanding_ops;
1399 gboolean reported_error;
1400 } CommunicateState;
1401  
1402 static void
1403 g_subprocess_communicate_made_progress (GObject *source_object,
1404 GAsyncResult *result,
1405 gpointer user_data)
1406 {
1407 CommunicateState *state;
1408 GSubprocess *subprocess;
1409 GError *error = NULL;
1410 gpointer source;
1411 GTask *task;
1412  
1413 g_assert (source_object != NULL);
1414  
1415 task = user_data;
1416 subprocess = g_task_get_source_object (task);
1417 state = g_task_get_task_data (task);
1418 source = source_object;
1419  
1420 state->outstanding_ops--;
1421  
1422 if (source == subprocess->stdin_pipe ||
1423 source == state->stdout_buf ||
1424 source == state->stderr_buf)
1425 {
1426 if (g_output_stream_splice_finish ((GOutputStream*) source, result, &error) == -1)
1427 goto out;
1428  
1429 if (source == state->stdout_buf ||
1430 source == state->stderr_buf)
1431 {
1432 /* This is a memory stream, so it can't be cancelled or return
1433 * an error really.
1434 */
1435 if (state->add_nul)
1436 {
1437 gsize bytes_written;
1438 if (!g_output_stream_write_all (source, "\0", 1, &bytes_written,
1439 NULL, &error))
1440 goto out;
1441 }
1442 if (!g_output_stream_close (source, NULL, &error))
1443 goto out;
1444 }
1445 }
1446 else if (source == subprocess)
1447 {
1448 (void) g_subprocess_wait_finish (subprocess, result, &error);
1449 }
1450 else
1451 g_assert_not_reached ();
1452  
1453 out:
1454 if (error)
1455 {
1456 /* Only report the first error we see.
1457 *
1458 * We might be seeing an error as a result of the cancellation
1459 * done when the process quits.
1460 */
1461 if (!state->reported_error)
1462 {
1463 state->reported_error = TRUE;
1464 g_cancellable_cancel (state->cancellable);
1465 g_task_return_error (task, error);
1466 }
1467 else
1468 g_error_free (error);
1469 }
1470 else if (state->outstanding_ops == 0)
1471 {
1472 g_task_return_boolean (task, TRUE);
1473 }
1474  
1475 /* And drop the original ref */
1476 g_object_unref (task);
1477 }
1478  
1479 static gboolean
1480 g_subprocess_communicate_cancelled (gpointer user_data)
1481 {
1482 CommunicateState *state = user_data;
1483  
1484 g_cancellable_cancel (state->cancellable);
1485  
1486 return FALSE;
1487 }
1488  
1489 static void
1490 g_subprocess_communicate_state_free (gpointer data)
1491 {
1492 CommunicateState *state = data;
1493  
1494 g_clear_object (&state->cancellable);
1495 g_clear_object (&state->stdin_buf);
1496 g_clear_object (&state->stdout_buf);
1497 g_clear_object (&state->stderr_buf);
1498  
1499 if (state->cancellable_source)
1500 {
1501 if (!g_source_is_destroyed (state->cancellable_source))
1502 g_source_destroy (state->cancellable_source);
1503 g_source_unref (state->cancellable_source);
1504 }
1505  
1506 g_slice_free (CommunicateState, state);
1507 }
1508  
1509 static CommunicateState *
1510 g_subprocess_communicate_internal (GSubprocess *subprocess,
1511 gboolean add_nul,
1512 GBytes *stdin_buf,
1513 GCancellable *cancellable,
1514 GAsyncReadyCallback callback,
1515 gpointer user_data)
1516 {
1517 CommunicateState *state;
1518 GTask *task;
1519  
1520 task = g_task_new (subprocess, cancellable, callback, user_data);
1521 state = g_slice_new0 (CommunicateState);
1522 g_task_set_task_data (task, state, g_subprocess_communicate_state_free);
1523  
1524 state->cancellable = g_cancellable_new ();
1525 state->add_nul = add_nul;
1526  
1527 if (cancellable)
1528 {
1529 state->cancellable_source = g_cancellable_source_new (cancellable);
1530 /* No ref held here, but we unref the source from state's free function */
1531 g_source_set_callback (state->cancellable_source, g_subprocess_communicate_cancelled, state, NULL);
1532 g_source_attach (state->cancellable_source, g_main_context_get_thread_default ());
1533 }
1534  
1535 if (subprocess->stdin_pipe)
1536 {
1537 g_assert (stdin_buf != NULL);
1538 state->stdin_buf = g_memory_input_stream_new_from_bytes (stdin_buf);
1539 g_output_stream_splice_async (subprocess->stdin_pipe, (GInputStream*)state->stdin_buf,
1540 G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE | G_OUTPUT_STREAM_SPLICE_CLOSE_TARGET,
1541 G_PRIORITY_DEFAULT, state->cancellable,
1542 g_subprocess_communicate_made_progress, g_object_ref (task));
1543 state->outstanding_ops++;
1544 }
1545  
1546 if (subprocess->stdout_pipe)
1547 {
1548 state->stdout_buf = (GMemoryOutputStream*)g_memory_output_stream_new_resizable ();
1549 g_output_stream_splice_async ((GOutputStream*)state->stdout_buf, subprocess->stdout_pipe,
1550 G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE,
1551 G_PRIORITY_DEFAULT, state->cancellable,
1552 g_subprocess_communicate_made_progress, g_object_ref (task));
1553 state->outstanding_ops++;
1554 }
1555  
1556 if (subprocess->stderr_pipe)
1557 {
1558 state->stderr_buf = (GMemoryOutputStream*)g_memory_output_stream_new_resizable ();
1559 g_output_stream_splice_async ((GOutputStream*)state->stderr_buf, subprocess->stderr_pipe,
1560 G_OUTPUT_STREAM_SPLICE_CLOSE_SOURCE,
1561 G_PRIORITY_DEFAULT, state->cancellable,
1562 g_subprocess_communicate_made_progress, g_object_ref (task));
1563 state->outstanding_ops++;
1564 }
1565  
1566 g_subprocess_wait_async (subprocess, state->cancellable,
1567 g_subprocess_communicate_made_progress, g_object_ref (task));
1568 state->outstanding_ops++;
1569  
1570 g_object_unref (task);
1571 return state;
1572 }
1573  
1574 /**
1575 * g_subprocess_communicate:
1576 * @subprocess: a #GSubprocess
1577 * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL
1578 * @cancellable: a #GCancellable
1579 * @stdout_buf: (out): data read from the subprocess stdout
1580 * @stderr_buf: (out): data read from the subprocess stderr
1581 * @error: a pointer to a %NULL #GError pointer, or %NULL
1582 *
1583 * Communicate with the subprocess until it terminates, and all input
1584 * and output has been completed.
1585 *
1586 * If @stdin_buf is given, the subprocess must have been created with
1587 * %G_SUBPROCESS_FLAGS_STDIN_PIPE. The given data is fed to the
1588 * stdin of the subprocess and the pipe is closed (ie: EOF).
1589 *
1590 * At the same time (as not to cause blocking when dealing with large
1591 * amounts of data), if %G_SUBPROCESS_FLAGS_STDOUT_PIPE or
1592 * %G_SUBPROCESS_FLAGS_STDERR_PIPE were used, reads from those
1593 * streams. The data that was read is returned in @stdout and/or
1594 * the @stderr.
1595 *
1596 * If the subprocess was created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
1597 * @stdout_buf will contain the data read from stdout. Otherwise, for
1598 * subprocesses not created with %G_SUBPROCESS_FLAGS_STDOUT_PIPE,
1599 * @stdout_buf will be set to %NULL. Similar provisions apply to
1600 * @stderr_buf and %G_SUBPROCESS_FLAGS_STDERR_PIPE.
1601 *
1602 * As usual, any output variable may be given as %NULL to ignore it.
1603 *
1604 * If you desire the stdout and stderr data to be interleaved, create
1605 * the subprocess with %G_SUBPROCESS_FLAGS_STDOUT_PIPE and
1606 * %G_SUBPROCESS_FLAGS_STDERR_MERGE. The merged result will be returned
1607 * in @stdout_buf and @stderr_buf will be set to %NULL.
1608 *
1609 * In case of any error (including cancellation), %FALSE will be
1610 * returned with @error set. Some or all of the stdin data may have
1611 * been written. Any stdout or stderr data that has been read will be
1612 * discarded. None of the out variables (aside from @error) will have
1613 * been set to anything in particular and should not be inspected.
1614 *
1615 * In the case that %TRUE is returned, the subprocess has exited and the
1616 * exit status inspection APIs (eg: g_subprocess_get_if_exited(),
1617 * g_subprocess_get_exit_status()) may be used.
1618 *
1619 * You should not attempt to use any of the subprocess pipes after
1620 * starting this function, since they may be left in strange states,
1621 * even if the operation was cancelled. You should especially not
1622 * attempt to interact with the pipes while the operation is in progress
1623 * (either from another thread or if using the asynchronous version).
1624 *
1625 * Returns: %TRUE if successful
1626 *
1627 * Since: 2.40
1628 **/
1629 gboolean
1630 g_subprocess_communicate (GSubprocess *subprocess,
1631 GBytes *stdin_buf,
1632 GCancellable *cancellable,
1633 GBytes **stdout_buf,
1634 GBytes **stderr_buf,
1635 GError **error)
1636 {
1637 GAsyncResult *result = NULL;
1638 gboolean success;
1639  
1640 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), FALSE);
1641 g_return_val_if_fail (stdin_buf == NULL || (subprocess->flags & G_SUBPROCESS_FLAGS_STDIN_PIPE), FALSE);
1642 g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
1643 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1644  
1645 g_subprocess_sync_setup ();
1646 g_subprocess_communicate_internal (subprocess, FALSE, stdin_buf, cancellable,
1647 g_subprocess_sync_done, &result);
1648 g_subprocess_sync_complete (&result);
1649 success = g_subprocess_communicate_finish (subprocess, result, stdout_buf, stderr_buf, error);
1650 g_object_unref (result);
1651  
1652 return success;
1653 }
1654  
1655 /**
1656 * g_subprocess_communicate_async:
1657 * @subprocess: Self
1658 * @stdin_buf: (allow-none): Input data, or %NULL
1659 * @cancellable: (allow-none): Cancellable
1660 * @callback: Callback
1661 * @user_data: User data
1662 *
1663 * Asynchronous version of g_subprocess_communicate(). Complete
1664 * invocation with g_subprocess_communicate_finish().
1665 */
1666 void
1667 g_subprocess_communicate_async (GSubprocess *subprocess,
1668 GBytes *stdin_buf,
1669 GCancellable *cancellable,
1670 GAsyncReadyCallback callback,
1671 gpointer user_data)
1672 {
1673 g_return_if_fail (G_IS_SUBPROCESS (subprocess));
1674 g_return_if_fail (stdin_buf == NULL || (subprocess->flags & G_SUBPROCESS_FLAGS_STDIN_PIPE));
1675 g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
1676  
1677 g_subprocess_communicate_internal (subprocess, FALSE, stdin_buf, cancellable, callback, user_data);
1678 }
1679  
1680 /**
1681 * g_subprocess_communicate_finish:
1682 * @subprocess: Self
1683 * @result: Result
1684 * @stdout_buf: (out): Return location for stdout data
1685 * @stderr_buf: (out): Return location for stderr data
1686 * @error: Error
1687 *
1688 * Complete an invocation of g_subprocess_communicate_async().
1689 */
1690 gboolean
1691 g_subprocess_communicate_finish (GSubprocess *subprocess,
1692 GAsyncResult *result,
1693 GBytes **stdout_buf,
1694 GBytes **stderr_buf,
1695 GError **error)
1696 {
1697 gboolean success;
1698 CommunicateState *state;
1699  
1700 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), FALSE);
1701 g_return_val_if_fail (g_task_is_valid (result, subprocess), FALSE);
1702 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1703  
1704 g_object_ref (result);
1705  
1706 state = g_task_get_task_data ((GTask*)result);
1707 success = g_task_propagate_boolean ((GTask*)result, error);
1708  
1709 if (success)
1710 {
1711 if (stdout_buf)
1712 *stdout_buf = g_memory_output_stream_steal_as_bytes (state->stdout_buf);
1713 if (stderr_buf)
1714 *stderr_buf = g_memory_output_stream_steal_as_bytes (state->stderr_buf);
1715 }
1716  
1717 g_object_unref (result);
1718 return success;
1719 }
1720  
1721 /**
1722 * g_subprocess_communicate_utf8:
1723 * @subprocess: a #GSubprocess
1724 * @stdin_buf: (allow-none): data to send to the stdin of the subprocess, or %NULL
1725 * @cancellable: a #GCancellable
1726 * @stdout_buf: (out): data read from the subprocess stdout
1727 * @stderr_buf: (out): data read from the subprocess stderr
1728 * @error: a pointer to a %NULL #GError pointer, or %NULL
1729 *
1730 * Like g_subprocess_communicate(), but validates the output of the
1731 * process as UTF-8, and returns it as a regular NUL terminated string.
1732 */
1733 gboolean
1734 g_subprocess_communicate_utf8 (GSubprocess *subprocess,
1735 const char *stdin_buf,
1736 GCancellable *cancellable,
1737 char **stdout_buf,
1738 char **stderr_buf,
1739 GError **error)
1740 {
1741 GAsyncResult *result = NULL;
1742 gboolean success;
1743 GBytes *stdin_bytes;
1744 size_t stdin_buf_len = 0;
1745  
1746 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), FALSE);
1747 g_return_val_if_fail (stdin_buf == NULL || (subprocess->flags & G_SUBPROCESS_FLAGS_STDIN_PIPE), FALSE);
1748 g_return_val_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable), FALSE);
1749 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1750  
1751 if (stdin_buf != NULL)
1752 stdin_buf_len = strlen (stdin_buf);
1753 stdin_bytes = g_bytes_new (stdin_buf, stdin_buf_len);
1754  
1755 g_subprocess_sync_setup ();
1756 g_subprocess_communicate_internal (subprocess, TRUE, stdin_bytes, cancellable,
1757 g_subprocess_sync_done, &result);
1758 g_subprocess_sync_complete (&result);
1759 success = g_subprocess_communicate_utf8_finish (subprocess, result, stdout_buf, stderr_buf, error);
1760 g_object_unref (result);
1761  
1762 g_bytes_unref (stdin_bytes);
1763 return success;
1764 }
1765  
1766 /**
1767 * g_subprocess_communicate_utf8_async:
1768 * @subprocess: Self
1769 * @stdin_buf: (allow-none): Input data, or %NULL
1770 * @cancellable: Cancellable
1771 * @callback: Callback
1772 * @user_data: User data
1773 *
1774 * Asynchronous version of g_subprocess_communicate_utf8(). Complete
1775 * invocation with g_subprocess_communicate_utf8_finish().
1776 */
1777 void
1778 g_subprocess_communicate_utf8_async (GSubprocess *subprocess,
1779 const char *stdin_buf,
1780 GCancellable *cancellable,
1781 GAsyncReadyCallback callback,
1782 gpointer user_data)
1783 {
1784 GBytes *stdin_bytes;
1785 size_t stdin_buf_len = 0;
1786  
1787 g_return_if_fail (G_IS_SUBPROCESS (subprocess));
1788 g_return_if_fail (stdin_buf == NULL || (subprocess->flags & G_SUBPROCESS_FLAGS_STDIN_PIPE));
1789 g_return_if_fail (cancellable == NULL || G_IS_CANCELLABLE (cancellable));
1790  
1791 if (stdin_buf != NULL)
1792 stdin_buf_len = strlen (stdin_buf);
1793 stdin_bytes = g_bytes_new (stdin_buf, stdin_buf_len);
1794  
1795 g_subprocess_communicate_internal (subprocess, TRUE, stdin_bytes, cancellable, callback, user_data);
1796  
1797 g_bytes_unref (stdin_bytes);
1798 }
1799  
1800 static gboolean
1801 communicate_result_validate_utf8 (const char *stream_name,
1802 char **return_location,
1803 GMemoryOutputStream *buffer,
1804 GError **error)
1805 {
1806 if (return_location == NULL)
1807 return TRUE;
1808  
1809 if (buffer)
1810 {
1811 const char *end;
1812 *return_location = g_memory_output_stream_steal_data (buffer);
1813 if (!g_utf8_validate (*return_location, -1, &end))
1814 {
1815 g_free (*return_location);
1816 g_set_error (error, G_IO_ERROR, G_IO_ERROR_FAILED,
1817 "Invalid UTF-8 in child %s at offset %lu",
1818 stream_name,
1819 (unsigned long) (end - *return_location));
1820 return FALSE;
1821 }
1822 }
1823 else
1824 *return_location = NULL;
1825  
1826 return TRUE;
1827 }
1828  
1829 /**
1830 * g_subprocess_communicate_utf8_finish:
1831 * @subprocess: Self
1832 * @result: Result
1833 * @stdout_buf: (out): Return location for stdout data
1834 * @stderr_buf: (out): Return location for stderr data
1835 * @error: Error
1836 *
1837 * Complete an invocation of g_subprocess_communicate_utf8_async().
1838 */
1839 gboolean
1840 g_subprocess_communicate_utf8_finish (GSubprocess *subprocess,
1841 GAsyncResult *result,
1842 char **stdout_buf,
1843 char **stderr_buf,
1844 GError **error)
1845 {
1846 gboolean ret = FALSE;
1847 CommunicateState *state;
1848  
1849 g_return_val_if_fail (G_IS_SUBPROCESS (subprocess), FALSE);
1850 g_return_val_if_fail (g_task_is_valid (result, subprocess), FALSE);
1851 g_return_val_if_fail (error == NULL || *error == NULL, FALSE);
1852  
1853 g_object_ref (result);
1854  
1855 state = g_task_get_task_data ((GTask*)result);
1856 if (!g_task_propagate_boolean ((GTask*)result, error))
1857 goto out;
1858  
1859 /* TODO - validate UTF-8 while streaming, rather than all at once.
1860 */
1861 if (!communicate_result_validate_utf8 ("stdout", stdout_buf,
1862 state->stdout_buf,
1863 error))
1864 goto out;
1865 if (!communicate_result_validate_utf8 ("stderr", stderr_buf,
1866 state->stderr_buf,
1867 error))
1868 goto out;
1869  
1870 ret = TRUE;
1871 out:
1872 g_object_unref (result);
1873 return ret;
1874 }