run-command: introduce capture_command helper

Something as simple as reading the stdout from a command
turns out to be rather hard to do right. Doing:

cmd.out = -1;
run_command(&cmd);
strbuf_read(&buf, cmd.out, 0);

can result in deadlock if the child process produces a large
amount of output. What happens is:

1. The parent spawns the child with its stdout connected
to a pipe, of which the parent is the sole reader.

2. The parent calls wait(), blocking until the child exits.

3. The child writes to stdout. If it writes more data than
the OS pipe buffer can hold, the write() call will
block.

This is a deadlock; the parent is waiting for the child to
exit, and the child is waiting for the parent to call
read().

So we might try instead:

start_command(&cmd);
strbuf_read(&buf, cmd.out, 0);
finish_command(&cmd);

But that is not quite right either. We are examining cmd.out
and running finish_command whether start_command succeeded
or not, which is wrong. Moreover, these snippets do not do
any error handling. If our read() fails, we must make sure
to still call finish_command (to reap the child process).
And both snippets failed to close the cmd.out descriptor,
which they must do (provided start_command succeeded).

Let's introduce a run-command helper that can make this a
bit simpler for callers to get right.

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/run-command.c b/run-command.c
index 0b432cc9713251b4d116bedf52ae1f51bd9d80cf..65ecbe31d7a61b20f42fd40eaf72d422c0c57a99 100644 (file)
--- a/run-command.c
+++ b/run-command.c
@@ -833,3 +833,19 @@ int run_hook_le(const char *const *env, const char *name, ...)
 
        return ret;
 }
 
        return ret;
 }

+
+int capture_command(struct child_process *cmd, struct strbuf *buf, size_t hint)
+{
+       cmd->out = -1;
+       if (start_command(cmd) < 0)
+               return -1;
+
+       if (strbuf_read(buf, cmd->out, hint) < 0) {
+               close(cmd->out);
+               finish_command(cmd); /* throw away exit code */
+               return -1;
+       }
+
+       close(cmd->out);
+       return finish_command(cmd);
+}

diff --git a/run-command.h b/run-command.h
index d6868dc8c868a61fb1ccc6230f43048dd9838a24..263b9662adeba011adcd018f77b7ccbbcd53e94a 100644 (file)
--- a/run-command.h
+++ b/run-command.h
@@ -71,6 +71,19 @@ int run_command_v_opt(const char **argv, int opt);
  */
 int run_command_v_opt_cd_env(const char **argv, int opt, const char *dir, const char *const *env);
 
  */
 int run_command_v_opt_cd_env(const char **argv, int opt, const char *dir, const char *const *env);
 

+/**
+ * Execute the given command, capturing its stdout in the given strbuf.
+ * Returns -1 if starting the command fails or reading fails, and otherwise
+ * returns the exit code of the command. The output collected in the
+ * buffer is kept even if the command returns a non-zero exit. The hint field
+ * gives a starting size for the strbuf allocation.
+ *
+ * The fields of "cmd" should be set up as they would for a normal run_command
+ * invocation. But note that there is no need to set cmd->out; the function
+ * sets it up for the caller.
+ */
+int capture_command(struct child_process *cmd, struct strbuf *buf, size_t hint);
+

 /*
  * The purpose of the following functions is to feed a pipe by running
  * a function asynchronously and providing output that the caller reads.
 /*
  * The purpose of the following functions is to feed a pipe by running
  * a function asynchronously and providing output that the caller reads.