1
/* -*- mode: C; c-file-style: "gnu"; indent-tabs-mode: nil; -*- */
3
/* GIO - GLib Input, Output and Streaming Library
5
* Copyright © 2012 Red Hat, Inc.
6
* Copyright © 2012 Canonical Limited
8
* This program is free software: you can redistribute it and/or modify
9
* it under the terms of the GNU Lesser General Public License as published
10
* by the Free Software Foundation; either version 2 of the licence or (at
11
* your option) any later version.
13
* See the included COPYING file for more information.
15
* Authors: Colin Walters <walters@verbum.org>
16
* Ryan Lortie <desrt@desrt.ca>
21
#define _GSYSTEM_NO_LOCAL_ALLOC
22
#include "libgsystem.h"
24
#if GLIB_CHECK_VERSION(2,34,0)
27
* SECTION:gssubprocess
28
* @title: GSSubprocess
29
* @short_description: Create child processes and monitor their status
31
* This class wraps the lower-level g_spawn_async_with_pipes() API,
32
* providing a more modern GIO-style API, such as returning
33
* #GInputStream objects for child output pipes.
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 <literal>subprocess.py</literal>
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.
50
#include "gsystem-subprocess.h"
51
#include "gsystem-subprocess-context-private.h"
55
#include <gio/gunixoutputstream.h>
56
#include <gio/gfiledescriptorbased.h>
57
#include <gio/gunixinputstream.h>
58
#include <glib-unix.h>
62
#define _WIN32_WINNT 0x0500
64
#include "giowin32-priv.h"
71
static void initable_iface_init (GInitableIface *initable_iface);
73
typedef GObjectClass GSSubprocessClass;
77
gs_subprocess_unix_queue_waitpid (GSSubprocess *self);
84
GSSubprocessContext *context;
88
guint reaped_child : 1;
91
/* These are the streams created if a pipe is requested via flags. */
92
GOutputStream *stdin_pipe;
93
GInputStream *stdout_pipe;
94
GInputStream *stderr_pipe;
97
G_DEFINE_TYPE_WITH_CODE (GSSubprocess, gs_subprocess, G_TYPE_OBJECT,
98
G_IMPLEMENT_INTERFACE (G_TYPE_INITABLE, initable_iface_init));
107
static GParamSpec *gs_subprocess_pspecs[N_PROPS];
110
gs_subprocess_init (GSSubprocess *self)
115
gs_subprocess_finalize (GObject *object)
117
GSSubprocess *self = GS_SUBPROCESS (object);
122
/* Here we need to actually call waitpid() to clean up the
123
* zombie. In case the child hasn't actually exited, defer this
124
* cleanup to the worker thread.
126
if (!self->reaped_child)
127
gs_subprocess_unix_queue_waitpid (self);
129
g_spawn_close_pid (self->pid);
132
g_clear_object (&self->stdin_pipe);
133
g_clear_object (&self->stdout_pipe);
134
g_clear_object (&self->stderr_pipe);
136
if (G_OBJECT_CLASS (gs_subprocess_parent_class)->finalize != NULL)
137
G_OBJECT_CLASS (gs_subprocess_parent_class)->finalize (object);
141
gs_subprocess_set_property (GObject *object,
146
GSSubprocess *self = GS_SUBPROCESS (object);
151
self->context = g_value_dup_object (value);
155
g_assert_not_reached ();
160
gs_subprocess_get_property (GObject *object,
165
GSSubprocess *self = GS_SUBPROCESS (object);
170
g_value_set_object (value, self->context);
174
g_assert_not_reached ();
179
gs_subprocess_class_init (GSSubprocessClass *class)
181
GObjectClass *gobject_class = G_OBJECT_CLASS (class);
183
gobject_class->finalize = gs_subprocess_finalize;
184
gobject_class->get_property = gs_subprocess_get_property;
185
gobject_class->set_property = gs_subprocess_set_property;
188
* GSSubprocess:context:
193
gs_subprocess_pspecs[PROP_CONTEXT] = g_param_spec_object ("context", "Context", "Subprocess options", GS_TYPE_SUBPROCESS_CONTEXT,
194
G_PARAM_READWRITE | G_PARAM_CONSTRUCT_ONLY |
195
G_PARAM_STATIC_STRINGS);
197
g_object_class_install_properties (gobject_class, N_PROPS, gs_subprocess_pspecs);
203
gs_subprocess_unix_waitpid_dummy (gpointer data)
209
gs_subprocess_unix_queue_waitpid (GSSubprocess *self)
211
GMainContext *worker_context;
212
GSource *waitpid_source;
214
#ifdef GLIB_COMPILATION
215
worker_context = GLIB_PRIVATE_CALL (g_get_worker_context) ();
217
worker_context = g_main_context_get_thread_default ();
219
waitpid_source = g_child_watch_source_new (self->pid);
220
g_source_set_callback (waitpid_source, gs_subprocess_unix_waitpid_dummy, NULL, NULL);
221
g_source_attach (waitpid_source, worker_context);
222
g_source_unref (waitpid_source);
227
static GInputStream *
228
platform_input_stream_from_spawn_fd (gint fd)
234
return g_unix_input_stream_new (fd, TRUE);
236
return g_win32_input_stream_new_from_fd (fd, TRUE);
240
static GOutputStream *
241
platform_output_stream_from_spawn_fd (gint fd)
247
return g_unix_output_stream_new (fd, TRUE);
249
return g_win32_output_stream_new_from_fd (fd, TRUE);
255
unix_open_file (const char *filename,
262
my_fd = open (filename, mode | O_BINARY | O_CLOEXEC, 0666);
263
while (my_fd == -1 && errno == EINTR);
265
/* If we return -1 we should also set the error */
268
gint saved_errno = errno;
271
display_name = g_filename_display_name (filename);
272
g_set_error (error, G_IO_ERROR, g_io_error_from_errno (saved_errno),
273
"Error opening file '%s': %s", display_name,
274
g_strerror (saved_errno));
275
g_free (display_name);
276
/* fall through... */
287
GSpawnChildSetupFunc child_setup_func;
288
gpointer child_setup_data;
292
child_setup (gpointer user_data)
294
ChildData *child_data = user_data;
298
/* We're on the child side now. "Rename" the file descriptors in
299
* child_data.fds[] to stdin/stdout/stderr.
301
* We don't close the originals. It's possible that the originals
302
* should not be closed and if they should be closed then they should
303
* have been created O_CLOEXEC.
305
for (i = 0; i < 3; i++)
307
if (child_data->fds[i] != -1 && child_data->fds[i] != (int) i)
310
result = dup2 (child_data->fds[i], i);
311
while (G_UNLIKELY (result == -1 && errno == EINTR));
315
/* Unset the CLOEXEC flag for the child *should* inherit */
316
for (i = 0; i < child_data->inherit_fds->len; i++)
318
int fd = g_array_index (child_data->inherit_fds, int, i);
322
flags = fcntl (fd, F_GETFL);
323
while (G_UNLIKELY (flags == -1 && errno == EINTR));
325
flags &= ~FD_CLOEXEC;
328
result = fcntl (fd, F_SETFD, flags);
329
while (G_UNLIKELY (result == -1 && errno == EINTR));
332
if (child_data->child_setup_func)
333
child_data->child_setup_func (child_data->child_setup_data);
337
initable_init (GInitable *initable,
338
GCancellable *cancellable,
341
GSSubprocess *self = GS_SUBPROCESS (initable);
342
ChildData child_data = { { -1, -1, -1 } };
343
gint *pipe_ptrs[3] = { NULL, NULL, NULL };
344
gint pipe_fds[3] = { -1, -1, -1 };
345
gint close_fds[3] = { -1, -1, -1 };
346
GSpawnFlags spawn_flags = 0;
347
gboolean success = FALSE;
350
if (g_cancellable_set_error_if_cancelled (cancellable, error))
353
/* We must setup the three fds that will end up in the child as stdin,
359
if (self->context->stdin_fd != -1)
360
child_data.fds[0] = self->context->stdin_fd;
361
else if (self->context->stdin_path != NULL)
363
child_data.fds[0] = close_fds[0] = unix_open_file (self->context->stdin_path,
365
if (child_data.fds[0] == -1)
370
if (self->context->stdin_disposition == GS_SUBPROCESS_STREAM_DISPOSITION_NULL)
372
else if (self->context->stdin_disposition == GS_SUBPROCESS_STREAM_DISPOSITION_INHERIT)
373
spawn_flags |= G_SPAWN_CHILD_INHERITS_STDIN;
374
else if (self->context->stdin_disposition == GS_SUBPROCESS_STREAM_DISPOSITION_PIPE)
375
pipe_ptrs[0] = &pipe_fds[0];
377
g_assert_not_reached ();
381
if (self->context->stdout_fd != -1)
382
child_data.fds[1] = self->context->stdout_fd;
383
else if (self->context->stdout_path != NULL)
385
child_data.fds[1] = close_fds[1] = unix_open_file (self->context->stdout_path,
386
O_CREAT | O_WRONLY, error);
387
if (child_data.fds[1] == -1)
392
if (self->context->stdout_disposition == GS_SUBPROCESS_STREAM_DISPOSITION_NULL)
393
spawn_flags |= G_SPAWN_STDOUT_TO_DEV_NULL;
394
else if (self->context->stdout_disposition == GS_SUBPROCESS_STREAM_DISPOSITION_INHERIT)
396
else if (self->context->stdout_disposition == GS_SUBPROCESS_STREAM_DISPOSITION_PIPE)
397
pipe_ptrs[1] = &pipe_fds[1];
399
g_assert_not_reached ();
401
/* Finally, stderr. */
403
if (self->context->stderr_fd != -1)
404
child_data.fds[2] = self->context->stderr_fd;
405
else if (self->context->stderr_path != NULL)
407
child_data.fds[2] = close_fds[2] = unix_open_file (self->context->stderr_path,
408
O_CREAT | O_WRONLY, error);
409
if (child_data.fds[2] == -1)
414
if (self->context->stderr_disposition == GS_SUBPROCESS_STREAM_DISPOSITION_NULL)
415
spawn_flags |= G_SPAWN_STDERR_TO_DEV_NULL;
416
else if (self->context->stderr_disposition == GS_SUBPROCESS_STREAM_DISPOSITION_INHERIT)
418
else if (self->context->stderr_disposition == GS_SUBPROCESS_STREAM_DISPOSITION_PIPE)
419
pipe_ptrs[2] = &pipe_fds[2];
420
else if (self->context->stderr_disposition == GS_SUBPROCESS_STREAM_DISPOSITION_STDERR_MERGE)
421
/* This will work because stderr gets setup after stdout. */
422
child_data.fds[2] = 1;
424
g_assert_not_reached ();
426
child_data.inherit_fds = self->context->inherit_fds;
428
if (self->context->keep_descriptors)
429
spawn_flags |= G_SPAWN_LEAVE_DESCRIPTORS_OPEN;
431
if (self->context->search_path)
432
spawn_flags |= G_SPAWN_SEARCH_PATH;
433
else if (self->context->search_path_from_envp)
434
spawn_flags |= G_SPAWN_SEARCH_PATH_FROM_ENVP;
435
else if (!g_path_is_absolute (((gchar**)self->context->argv)[0]))
436
spawn_flags |= G_SPAWN_SEARCH_PATH;
438
if (self->context->has_argv0)
439
spawn_flags |= G_SPAWN_FILE_AND_ARGV_ZERO;
441
spawn_flags |= G_SPAWN_DO_NOT_REAP_CHILD;
442
#ifdef GLIB_COMPILATION
443
spawn_flags |= G_SPAWN_CLOEXEC_PIPES;
446
child_data.child_setup_func = self->context->child_setup_func;
447
child_data.child_setup_data = self->context->child_setup_data;
448
success = g_spawn_async_with_pipes (self->context->cwd,
449
(char**)self->context->argv,
452
child_setup, &child_data,
454
pipe_ptrs[0], pipe_ptrs[1], pipe_ptrs[2],
457
self->pid_valid = TRUE;
460
for (i = 0; i < 3; i++)
461
if (close_fds[i] != -1)
462
close (close_fds[i]);
464
for (i = 0; i < self->context->postfork_close_fds->len; i++)
465
(void) close (g_array_index (self->context->postfork_close_fds, int, i));
467
self->stdin_pipe = platform_output_stream_from_spawn_fd (pipe_fds[0]);
468
self->stdout_pipe = platform_input_stream_from_spawn_fd (pipe_fds[1]);
469
self->stderr_pipe = platform_input_stream_from_spawn_fd (pipe_fds[2]);
475
initable_iface_init (GInitableIface *initable_iface)
477
initable_iface->init = initable_init;
483
* Create a new process, using the parameters specified by
484
* GSSubprocessContext.
486
* Returns: (transfer full): A newly created %GSSubprocess, or %NULL on error (and @error will be set)
491
gs_subprocess_new (GSSubprocessContext *context,
492
GCancellable *cancellable,
495
return g_initable_new (GS_TYPE_SUBPROCESS,
502
* gs_subprocess_get_pid:
503
* @self: a #GSSubprocess
505
* The identifier for this child process; it is valid as long as the
506
* process @self is referenced. In particular, do
507
* <emphasis>not</emphasis> call g_spawn_close_pid() on this value;
508
* that is handled internally.
510
* On some Unix versions, it is possible for there to be a race
511
* condition where waitpid() may have been called to collect the child
512
* before any watches (such as that installed by
513
* gs_subprocess_add_watch()) have fired. If you are planning to use
514
* native functions such as kill() on the pid, your program should
515
* gracefully handle an %ESRCH result to mitigate this.
517
* If you want to request process termination, using the high level
518
* gs_subprocess_request_exit() and gs_subprocess_force_exit() API is
521
* Returns: Operating-system specific identifier for child process
526
gs_subprocess_get_pid (GSSubprocess *self)
528
g_return_val_if_fail (GS_IS_SUBPROCESS (self), 0);
534
* gs_subprocess_get_stdin_pipe:
536
* Returns: (transfer none): Pipe
539
gs_subprocess_get_stdin_pipe (GSSubprocess *self)
541
g_return_val_if_fail (GS_IS_SUBPROCESS (self), NULL);
542
g_return_val_if_fail (self->stdin_pipe, NULL);
544
return self->stdin_pipe;
548
* gs_subprocess_get_stdout_pipe:
550
* Returns: (transfer none): Pipe
553
gs_subprocess_get_stdout_pipe (GSSubprocess *self)
555
g_return_val_if_fail (GS_IS_SUBPROCESS (self), NULL);
556
g_return_val_if_fail (self->stdout_pipe, NULL);
558
return self->stdout_pipe;
562
* gs_subprocess_get_stderr_pipe:
564
* Returns: (transfer none): Pipe
567
gs_subprocess_get_stderr_pipe (GSSubprocess *self)
569
g_return_val_if_fail (GS_IS_SUBPROCESS (self), NULL);
570
g_return_val_if_fail (self->stderr_pipe, NULL);
572
return self->stderr_pipe;
577
GCancellable *cancellable;
578
GSimpleAsyncResult *result;
579
} GSSubprocessWatchData;
582
gs_subprocess_on_child_exited (GPid pid,
586
GSSubprocessWatchData *data = user_data;
587
GError *error = NULL;
589
if (g_cancellable_set_error_if_cancelled (data->cancellable, &error))
591
g_simple_async_result_take_error (data->result, error);
595
data->self->reaped_child = TRUE;
597
g_simple_async_result_set_op_res_gssize (data->result, status_code);
600
g_simple_async_result_complete (data->result);
602
g_object_unref (data->result);
603
g_object_unref (data->self);
610
* gs_subprocess_wait:
611
* @self: a #GSSubprocess
612
* @cancellable: a #GCancellable
613
* @callback: Invoked when process exits, or @cancellable is cancelled
614
* @user_data: Data for @callback
616
* Start an asynchronous wait for the subprocess @self to exit.
621
gs_subprocess_wait (GSSubprocess *self,
622
GCancellable *cancellable,
623
GAsyncReadyCallback callback,
627
GSSubprocessWatchData *data;
629
data = g_new0 (GSSubprocessWatchData, 1);
631
data->self = g_object_ref (self);
632
data->result = g_simple_async_result_new ((GObject*)self, callback, user_data,
635
source = g_child_watch_source_new (self->pid);
637
g_source_set_callback (source, (GSourceFunc)gs_subprocess_on_child_exited,
641
GSource *cancellable_source;
643
data->cancellable = g_object_ref (cancellable);
645
cancellable_source = g_cancellable_source_new (cancellable);
646
g_source_add_child_source (source, cancellable_source);
647
g_source_unref (cancellable_source);
650
g_source_attach (source, g_main_context_get_thread_default ());
651
g_source_unref (source);
655
* gs_subprocess_wait_finish:
656
* @self: a #GSSubprocess
657
* @result: a #GAsyncResult
658
* @out_exit_status: (out): Exit status of the process encoded in platform-specific way
661
* The exit status of the process will be stored in @out_exit_status.
662
* See the documentation of g_spawn_check_exit_status() for more
665
* Note that @error is not set if the process exits abnormally; you
666
* must use g_spawn_check_exit_status() for that.
671
gs_subprocess_wait_finish (GSSubprocess *self,
672
GAsyncResult *result,
673
int *out_exit_status,
676
GSimpleAsyncResult *simple;
678
simple = G_SIMPLE_ASYNC_RESULT (result);
680
if (g_simple_async_result_propagate_error (simple, error))
683
*out_exit_status = g_simple_async_result_get_op_res_gssize (simple);
690
gint *exit_status_ptr;
691
gboolean caught_error;
693
} GSSubprocessSyncWaitData;
696
gs_subprocess_on_sync_wait_complete (GObject *object,
697
GAsyncResult *result,
700
GSSubprocessSyncWaitData *data = user_data;
702
if (!gs_subprocess_wait_finish ((GSSubprocess*)object, result,
703
data->exit_status_ptr, data->error))
704
data->caught_error = TRUE;
706
g_main_loop_quit (data->loop);
710
* gs_subprocess_wait_sync:
711
* @self: a #GSSubprocess
712
* @out_exit_status: (out): Platform-specific exit code
713
* @cancellable: a #GCancellable
716
* Synchronously wait for the subprocess to terminate, returning the
717
* status code in @out_exit_status. See the documentation of
718
* g_spawn_check_exit_status() for how to interpret it. Note that if
719
* @error is set, then @out_exit_status will be left uninitialized.
721
* Returns: %TRUE on success, %FALSE if @cancellable was cancelled
726
gs_subprocess_wait_sync (GSSubprocess *self,
727
int *out_exit_status,
728
GCancellable *cancellable,
731
gboolean ret = FALSE;
732
gboolean pushed_thread_default = FALSE;
733
GMainContext *context = NULL;
734
GSSubprocessSyncWaitData data;
736
memset (&data, 0, sizeof (data));
738
g_return_val_if_fail (GS_IS_SUBPROCESS (self), FALSE);
740
if (g_cancellable_set_error_if_cancelled (cancellable, error))
743
context = g_main_context_new ();
744
g_main_context_push_thread_default (context);
745
pushed_thread_default = TRUE;
747
data.exit_status_ptr = out_exit_status;
748
data.loop = g_main_loop_new (context, TRUE);
751
gs_subprocess_wait (self, cancellable,
752
gs_subprocess_on_sync_wait_complete, &data);
754
g_main_loop_run (data.loop);
756
if (data.caught_error)
761
if (pushed_thread_default)
762
g_main_context_pop_thread_default (context);
764
g_main_context_unref (context);
766
g_main_loop_unref (data.loop);
772
* gs_subprocess_wait_sync_check:
773
* @self: a #GSSubprocess
774
* @cancellable: a #GCancellable
777
* Combines gs_subprocess_wait_sync() with g_spawn_check_exit_status().
779
* Returns: %TRUE on success, %FALSE if process exited abnormally, or @cancellable was cancelled
784
gs_subprocess_wait_sync_check (GSSubprocess *self,
785
GCancellable *cancellable,
788
gboolean ret = FALSE;
791
if (!gs_subprocess_wait_sync (self, &exit_status, cancellable, error))
794
if (!g_spawn_check_exit_status (exit_status, error))
803
* gs_subprocess_request_exit:
804
* @self: a #GSSubprocess
806
* This API uses an operating-system specific mechanism to request
807
* that the subprocess gracefully exit. This API is not available on
808
* all operating systems; for those not supported, it will do nothing
809
* and return %FALSE. Portable code should handle this situation
810
* gracefully. For example, if you are communicating via input or
811
* output pipe with the child, many programs will automatically exit
812
* when one of their standard input or output are closed.
814
* On Unix, this API sends %SIGTERM.
816
* A %TRUE return value does <emphasis>not</emphasis> mean the
817
* subprocess has exited, merely that an exit request was initiated.
818
* You can use gs_subprocess_add_watch() to monitor the status of the
819
* process after calling this function.
821
* This function returns %TRUE if the process has already exited.
823
* Returns: %TRUE if the operation is supported, %FALSE otherwise.
828
gs_subprocess_request_exit (GSSubprocess *self)
830
g_return_val_if_fail (GS_IS_SUBPROCESS (self), FALSE);
833
(void) kill (self->pid, SIGTERM);
841
* gs_subprocess_force_exit:
842
* @self: a #GSSubprocess
844
* Use an operating-system specific method to attempt an immediate,
845
* forceful termination of the process. There is no mechanism to
846
* determine whether or not the request itself was successful;
847
* however, you can use gs_subprocess_wait() to monitor the status of
848
* the process after calling this function.
850
* On Unix, this function sends %SIGKILL.
853
gs_subprocess_force_exit (GSSubprocess *self)
855
g_return_if_fail (GS_IS_SUBPROCESS (self));
857
#if !defined(GLIB_COMPIATION)
861
ret = kill (self->pid, SIGKILL);
862
while (ret == -1 && errno == EINTR);
864
#elif defined(G_OS_UNIX)
865
GLIB_PRIVATE_CALL (g_main_send_signal) (self->pid, SIGKILL);
867
TerminateProcess (self->pid, 1);
872
gs_subprocess_new_simple_argl (GSSubprocessStreamDisposition stdout_disposition,
873
GSSubprocessStreamDisposition stderr_disposition,
874
GCancellable *cancellable,
876
const gchar *first_arg,
880
GSSubprocess *result;
881
GSSubprocessContext *context;
883
va_start (args, first_arg);
884
context = gs_subprocess_context_newa (first_arg, args);
886
result = gs_subprocess_new (context, cancellable, error);
887
g_object_unref (context);
893
* gs_subprocess_new_simple_argv:
894
* @argv: (array zero-terminated=1) (element-type utf8): Argument array
895
* @stdout_disposition: Where to redirect stdout
896
* @stderr_disposition: Where to redirect stdout
899
* Create a new subprocess using the provided argument array and
900
* stream dispositions.
903
gs_subprocess_new_simple_argv (gchar **argv,
904
GSSubprocessStreamDisposition stdout_disposition,
905
GSSubprocessStreamDisposition stderr_disposition,
906
GCancellable *cancellable,
909
GSSubprocessContext *context;
910
GSSubprocess *result;
912
context = gs_subprocess_context_new (argv);
913
gs_subprocess_context_set_stdout_disposition (context, stdout_disposition);
914
gs_subprocess_context_set_stderr_disposition (context, stderr_disposition);
916
result = gs_subprocess_new (context, cancellable, error);
917
g_object_unref (context);
923
* gs_subprocess_simple_run_sync:
924
* @cwd: Current working directory
925
* @stdin_disposition: What to do with standard input
926
* @cancellable: a #GCancellable
928
* @first_arg: First argument
929
* @...: Remaining arguments, %NULL terminated
931
* Run a process synchronously, throw an error if it fails.
934
gs_subprocess_simple_run_sync (const char *cwd,
935
GSSubprocessStreamDisposition stdin_disposition,
936
GCancellable *cancellable,
938
const char *first_arg,
941
gboolean ret = FALSE;
943
GSSubprocess *proc = NULL;
944
GSSubprocessContext *context = NULL;
946
va_start (args, first_arg);
947
context = gs_subprocess_context_newa (first_arg, args);
949
gs_subprocess_context_set_stdin_disposition (context, stdin_disposition);
950
gs_subprocess_context_set_cwd (context, cwd);
951
proc = gs_subprocess_new (context, cancellable, error);
955
if (!gs_subprocess_wait_sync_check (proc, cancellable, error))
960
g_object_unref (context);
962
g_object_unref (proc);