Add changes file for bug40642.

[tor.git] / src / lib / process / process_win32.c

/* Copyright (c) 2003, Roger Dingledine
 * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
 * Copyright (c) 2007-2021, The Tor Project, Inc. */
/* See LICENSE for licensing information */

/**
 * \file process_win32.c
 * \brief Module for working with Windows processes.
 **/

#define PROCESS_WIN32_PRIVATE
#include "lib/intmath/cmp.h"
#include "lib/buf/buffers.h"
#include "lib/net/buffers_net.h"
#include "lib/container/smartlist.h"
#include "lib/log/log.h"
#include "lib/log/util_bug.h"
#include "lib/log/win32err.h"
#include "lib/process/process.h"
#include "lib/process/process_win32.h"
#include "lib/process/env.h"

#ifdef HAVE_SYS_TIME_H
#include <sys/time.h>
#endif

#ifdef HAVE_STRING_H
#include <string.h>
#endif

#ifdef _WIN32

/** The size of our intermediate buffers. */
#define BUFFER_SIZE (1024)

/** Timer that ticks once a second and calls the process_win32_timer_callback()
 * function. */
static periodic_timer_t *periodic_timer;

/** Structure to represent the state around the pipe HANDLE.
 *
 * This structure is used to store state about a given HANDLE, including
 * whether we have reached end of file, its intermediate buffers, and how much
 * data that is available in the intermediate buffer. */
struct process_win32_handle_t {
  /** Standard out pipe handle. */
  HANDLE pipe;

  /** True iff we have reached EOF from the pipe. */
  bool reached_eof;

  /** How much data is available in buffer. */
  size_t data_available;

  /** Intermediate buffer for ReadFileEx() and WriteFileEx(). */
  char buffer[BUFFER_SIZE];

  /** Overlapped structure for ReadFileEx() and WriteFileEx(). */
  OVERLAPPED overlapped;

  /** Are we waiting for another I/O operation to complete? */
  bool busy;
};

/** Structure to represent the Windows specific implementation details of this
 * Process backend.
 *
 * This structure is attached to <b>process_t</b> (see process.h) and is
 * reachable from <b>process_t</b> via the <b>process_get_win32_process()</b>
 * method. */
struct process_win32_t {
  /** Standard in state. */
  process_win32_handle_t stdin_handle;

  /** Standard out state. */
  process_win32_handle_t stdout_handle;

  /** Standard error state. */
  process_win32_handle_t stderr_handle;

  /** Process Information. */
  PROCESS_INFORMATION process_information;
};

/** Create a new <b>process_win32_t</b>.
 *
 * This function constructs a new <b>process_win32_t</b> and initializes the
 * default values. */
process_win32_t *
process_win32_new(void)
{
  process_win32_t *win32_process;
  win32_process = tor_malloc_zero(sizeof(process_win32_t));

  win32_process->stdin_handle.pipe = INVALID_HANDLE_VALUE;
  win32_process->stdout_handle.pipe = INVALID_HANDLE_VALUE;
  win32_process->stderr_handle.pipe = INVALID_HANDLE_VALUE;

  return win32_process;
}

/** Free a given <b>process_win32_t</b>.
 *
 * This function deinitializes and frees up the resources allocated for the
 * given <b>process_win32_t</b>. */
void
process_win32_free_(process_win32_t *win32_process)
{
  if (! win32_process)
    return;

  /* Cleanup our handles. */
  process_win32_cleanup_handle(&win32_process->stdin_handle);
  process_win32_cleanup_handle(&win32_process->stdout_handle);
  process_win32_cleanup_handle(&win32_process->stderr_handle);

  tor_free(win32_process);
}

/** Initialize the Windows backend of the Process subsystem. */
void
process_win32_init(void)
{
  /* We don't start the periodic timer here because it makes no sense to have
   * the timer running until we have some processes that benefits from the
   * timer timer ticks. */
}

/** Deinitialize the Windows backend of the Process subsystem. */
void
process_win32_deinit(void)
{
  /* Stop our timer, but only if it's running. */
  if (process_win32_timer_running())
    process_win32_timer_stop();
}

/** Execute the given process. This function is responsible for setting up
 * named pipes for I/O between the child process and the Tor process. Returns
 * <b>PROCESS_STATUS_RUNNING</b> upon success. */
process_status_t
process_win32_exec(process_t *process)
{
  tor_assert(process);

  process_win32_t *win32_process = process_get_win32_process(process);

  HANDLE stdout_pipe_read = NULL;
  HANDLE stdout_pipe_write = NULL;
  HANDLE stderr_pipe_read = NULL;
  HANDLE stderr_pipe_write = NULL;
  HANDLE stdin_pipe_read = NULL;
  HANDLE stdin_pipe_write = NULL;
  BOOL ret = FALSE;

  /* Setup our security attributes. */
  SECURITY_ATTRIBUTES security_attributes;
  security_attributes.nLength = sizeof(security_attributes);
  security_attributes.bInheritHandle = TRUE;
  /* FIXME: should we set explicit security attributes?
   * (See Ticket #2046, comment 5) */
  security_attributes.lpSecurityDescriptor = NULL;

  /* Create our standard out pipe. */
  if (! process_win32_create_pipe(&stdout_pipe_read,
                                  &stdout_pipe_write,
                                  &security_attributes,
                                  PROCESS_WIN32_PIPE_TYPE_READER)) {
    return PROCESS_STATUS_ERROR;
  }

  /* Create our standard error pipe. */
  if (! process_win32_create_pipe(&stderr_pipe_read,
                                  &stderr_pipe_write,
                                  &security_attributes,
                                  PROCESS_WIN32_PIPE_TYPE_READER)) {
    return PROCESS_STATUS_ERROR;
  }

  /* Create out standard in pipe. */
  if (! process_win32_create_pipe(&stdin_pipe_read,
                                  &stdin_pipe_write,
                                  &security_attributes,
                                  PROCESS_WIN32_PIPE_TYPE_WRITER)) {
    return PROCESS_STATUS_ERROR;
  }

  /* Configure startup info for our child process. */
  STARTUPINFOA startup_info;

  memset(&startup_info, 0, sizeof(startup_info));
  startup_info.cb = sizeof(startup_info);
  startup_info.hStdError = stderr_pipe_write;
  startup_info.hStdOutput = stdout_pipe_write;
  startup_info.hStdInput = stdin_pipe_read;
  startup_info.dwFlags |= STARTF_USESTDHANDLES;

  /* Create the env value for our new process. */
  process_environment_t *env = process_get_environment(process);

  /* Create the argv value for our new process. */
  char **argv = process_get_argv(process);

  /* Windows expects argv to be a whitespace delimited string, so join argv up
   */
  char *joined_argv = tor_join_win_cmdline((const char **)argv);

  /* Create the child process */
  ret = CreateProcessA(NULL,
                       joined_argv,
                       NULL,
                       NULL,
                       TRUE,
                       CREATE_NO_WINDOW,
                       env->windows_environment_block[0] == '\0' ?
                         NULL : env->windows_environment_block,
                       NULL,
                       &startup_info,
                       &win32_process->process_information);

  tor_free(argv);
  tor_free(joined_argv);
  process_environment_free(env);

  if (! ret) {
    log_warn(LD_PROCESS, "CreateProcessA() failed: %s",
      format_win32_error(GetLastError()));

    /* Cleanup our handles. */
    CloseHandle(stdout_pipe_read);
    CloseHandle(stdout_pipe_write);
    CloseHandle(stderr_pipe_read);
    CloseHandle(stderr_pipe_write);
    CloseHandle(stdin_pipe_read);
    CloseHandle(stdin_pipe_write);

    /* In the Unix backend, we do not get an error in the Tor process when a
     * child process fails to spawn its target executable since we need to
     * first do the fork() call in the Tor process and then the child process
     * is responsible for doing the call to execve().
     *
     * This means that the user of the process_exec() API must check for
     * whether it returns PROCESS_STATUS_ERROR, which will rarely happen on
     * Unix, but will happen for error cases on Windows where it does not
     * happen on Unix. For example: when the target executable does not exist
     * on the file system.
     *
     * To have somewhat feature compatibility between the Unix and the Windows
     * backend, we here notify the process_t owner that the process have exited
     * (even though it never managed to run) to ensure that the exit callback
     * is executed.
     */
    process_notify_event_exit(process, 0);

    return PROCESS_STATUS_ERROR;
  }

  /* TODO: Should we close hProcess and hThread in
   * process_handle->process_information? */
  win32_process->stdout_handle.pipe = stdout_pipe_read;
  win32_process->stderr_handle.pipe = stderr_pipe_read;
  win32_process->stdin_handle.pipe = stdin_pipe_write;

  /* Close our ends of the pipes that is now owned by the child process. */
  CloseHandle(stdout_pipe_write);
  CloseHandle(stderr_pipe_write);
  CloseHandle(stdin_pipe_read);

  /* Used by the callback functions from ReadFileEx() and WriteFileEx() such
   * that we can figure out which process_t that was responsible for the event.
   *
   * Warning, here be dragons:
   *
   *   MSDN says that the hEvent member of the overlapped structure is unused
   *   for ReadFileEx() and WriteFileEx, which allows us to store a pointer to
   *   our process state there.
   */
  win32_process->stdout_handle.overlapped.hEvent = (HANDLE)process;
  win32_process->stderr_handle.overlapped.hEvent = (HANDLE)process;
  win32_process->stdin_handle.overlapped.hEvent = (HANDLE)process;

  /* Start our timer if it is not already running. */
  if (! process_win32_timer_running())
    process_win32_timer_start();

  /* We use Windows Extended I/O functions, so our completion callbacks are
   * called automatically for us when there is data to read. Because of this
   * we start the read of standard out and error right away. */
  process_notify_event_stdout(process);
  process_notify_event_stderr(process);

  return PROCESS_STATUS_RUNNING;
}

/** Terminate the given process. Returns true on success, otherwise false. */
bool
process_win32_terminate(process_t *process)
{
  tor_assert(process);

  process_win32_t *win32_process = process_get_win32_process(process);

  /* Terminate our process. */
  BOOL ret;

  ret = TerminateProcess(win32_process->process_information.hProcess, 0);

  if (! ret) {
    log_warn(LD_PROCESS, "TerminateProcess() failed: %s",
             format_win32_error(GetLastError()));
    return false;
  }

  /* Cleanup our handles. */
  process_win32_cleanup_handle(&win32_process->stdin_handle);
  process_win32_cleanup_handle(&win32_process->stdout_handle);
  process_win32_cleanup_handle(&win32_process->stderr_handle);

  return true;
}

/** Returns the unique process identifier for the given <b>process</b>. */
process_pid_t
process_win32_get_pid(process_t *process)
{
  tor_assert(process);

  process_win32_t *win32_process = process_get_win32_process(process);
  return (process_pid_t)win32_process->process_information.dwProcessId;
}

/** Schedule an async write of the data found in <b>buffer</b> for the given
 * process.  This function runs an async write operation of the content of
 * buffer, if we are not already waiting for a pending I/O request. Returns the
 * number of bytes that Windows will hopefully write for us in the background.
 * */
int
process_win32_write(struct process_t *process, buf_t *buffer)
{
  tor_assert(process);
  tor_assert(buffer);

  process_win32_t *win32_process = process_get_win32_process(process);
  BOOL ret = FALSE;
  DWORD error_code = 0;
  const size_t buffer_size = buf_datalen(buffer);

  /* Windows is still writing our buffer. */
  if (win32_process->stdin_handle.busy)
    return 0;

  /* Nothing for us to do right now. */
  if (buffer_size == 0)
    return 0;

  /* We have reached end of file already? */
  if (BUG(win32_process->stdin_handle.reached_eof))
    return 0;

  /* Figure out how much data we should read. */
  const size_t write_size = MIN(buffer_size,
                                sizeof(win32_process->stdin_handle.buffer));

  /* Read data from the process_t buffer into our intermediate buffer. */
  buf_get_bytes(buffer, win32_process->stdin_handle.buffer, write_size);

  /* Because of the slightly weird API for WriteFileEx() we must set this to 0
   * before we call WriteFileEx() because WriteFileEx() does not reset the last
   * error itself when it's successful. See comment below after the call to
   * GetLastError(). */
  SetLastError(0);

  /* Schedule our write. */
  ret = WriteFileEx(win32_process->stdin_handle.pipe,
                    win32_process->stdin_handle.buffer,
                    write_size,
                    &win32_process->stdin_handle.overlapped,
                    process_win32_stdin_write_done);

  if (! ret) {
    error_code = GetLastError();

    /* No need to log at warning level for these two. */
    if (error_code == ERROR_HANDLE_EOF || error_code == ERROR_BROKEN_PIPE) {
      log_debug(LD_PROCESS, "WriteFileEx() returned EOF from pipe: %s",
                format_win32_error(error_code));
    } else {
      log_warn(LD_PROCESS, "WriteFileEx() failed: %s",
               format_win32_error(error_code));
    }

    win32_process->stdin_handle.reached_eof = true;
    return 0;
  }

  /* Here be dragons: According to MSDN's documentation for WriteFileEx() we
   * should check GetLastError() after a call to WriteFileEx() even though the
   * `ret` return value was successful. If everything is good, GetLastError()
   * returns `ERROR_SUCCESS` and nothing happens.
   *
   * XXX(ahf): I have not managed to trigger this code while stress-testing
   * this code. */
  error_code = GetLastError();

  if (error_code != ERROR_SUCCESS) {
    /* LCOV_EXCL_START */
    log_warn(LD_PROCESS, "WriteFileEx() failed after returning success: %s",
             format_win32_error(error_code));
    win32_process->stdin_handle.reached_eof = true;
    return 0;
    /* LCOV_EXCL_STOP */
  }

  /* This cast should be safe since our buffer can maximum be BUFFER_SIZE
   * large. */
  return (int)write_size;
}

/** This function is called from the Process subsystem whenever the Windows
 * backend says it has data ready. This function also ensures that we are
 * starting a new background read from the standard output of the child process
 * and asks Windows to call process_win32_stdout_read_done() when that
 * operation is finished. Returns the number of bytes moved into <b>buffer</b>.
 * */
int
process_win32_read_stdout(struct process_t *process, buf_t *buffer)
{
  tor_assert(process);
  tor_assert(buffer);

  process_win32_t *win32_process = process_get_win32_process(process);

  return process_win32_read_from_handle(&win32_process->stdout_handle,
                                        buffer,
                                        process_win32_stdout_read_done);
}

/** This function is called from the Process subsystem whenever the Windows
 * backend says it has data ready. This function also ensures that we are
 * starting a new background read from the standard error of the child process
 * and asks Windows to call process_win32_stderr_read_done() when that
 * operation is finished. Returns the number of bytes moved into <b>buffer</b>.
 * */
int
process_win32_read_stderr(struct process_t *process, buf_t *buffer)
{
  tor_assert(process);
  tor_assert(buffer);

  process_win32_t *win32_process = process_get_win32_process(process);

  return process_win32_read_from_handle(&win32_process->stderr_handle,
                                        buffer,
                                        process_win32_stderr_read_done);
}

/** This function is responsible for moving the Tor process into what Microsoft
 * calls an "alertable" state. Once the process is in an alertable state the
 * Windows kernel will notify us when our background I/O requests have finished
 * and the callbacks will be executed. */
void
process_win32_trigger_completion_callbacks(void)
{
  DWORD ret;

  /* The call to SleepEx(dwMilliseconds, dwAlertable) makes the process sleep
   * for dwMilliseconds and if dwAlertable is set to TRUE it will also cause
   * the process to enter alertable state, where the Windows kernel will notify
   * us about completed I/O requests from ReadFileEx() and WriteFileEX(), which
   * will cause our completion callbacks to be executed.
   *
   * This function returns 0 if the time interval expired or WAIT_IO_COMPLETION
   * if one or more I/O callbacks were executed. */
  ret = SleepEx(0, TRUE);

  /* Warn us if the function returned something we did not anticipate. */
  if (ret != 0 && ret != WAIT_IO_COMPLETION) {
    log_warn(LD_PROCESS, "SleepEx() returned %lu", ret);
  }
}

/** Start the periodic timer which is responsible for checking whether
 * processes are still alive and to make sure that the Tor process is
 * periodically being moved into an alertable state. */
void
process_win32_timer_start(void)
{
  /* Make sure we never start our timer if it's already running. */
  if (BUG(process_win32_timer_running()))
    return;

  /* Wake up once a second. */
  static const struct timeval interval = {1, 0};

  log_info(LD_PROCESS, "Starting Windows Process I/O timer");
  periodic_timer = periodic_timer_new(tor_libevent_get_base(),
                                      &interval,
                                      process_win32_timer_callback,
                                      NULL);
}

/** Stops the periodic timer. */
void
process_win32_timer_stop(void)
{
  if (BUG(periodic_timer == NULL))
    return;

  log_info(LD_PROCESS, "Stopping Windows Process I/O timer");
  periodic_timer_free(periodic_timer);
}

/** Returns true iff the periodic timer is running. */
bool
process_win32_timer_running(void)
{
  return periodic_timer != NULL;
}

/** This function is called whenever the periodic_timer ticks. The function is
 * responsible for moving the Tor process into an alertable state once a second
 * and checking for whether our child processes have terminated since the last
 * tick. */
STATIC void
process_win32_timer_callback(periodic_timer_t *timer, void *data)
{
  tor_assert(timer == periodic_timer);
  tor_assert(data == NULL);

  /* Move the process into an alertable state. */
  process_win32_trigger_completion_callbacks();

  /* Check if our processes are still alive. */

  /* Since the call to process_win32_timer_test_process() might call
   * process_notify_event_exit() which again might call process_free() which
   * updates the list of processes returned by process_get_all_processes() it
   * is important here that we make sure to not touch the list of processes if
   * the call to process_win32_timer_test_process() returns true. */
  bool done;

  do {
    const smartlist_t *processes = process_get_all_processes();
    done = true;

    SMARTLIST_FOREACH_BEGIN(processes, process_t *, process) {
      /* If process_win32_timer_test_process() returns true, it means that
       * smartlist_remove() might have been called on the list returned by
       * process_get_all_processes(). We start the loop over again until we
       * have a successful run over the entire list where the list was not
       * modified. */
      if (process_win32_timer_test_process(process)) {
        done = false;
        break;
      }
    } SMARTLIST_FOREACH_END(process);
  } while (! done);
}

/** Test whether a given process is still alive. Notify the Process subsystem
 * if our process have died. Returns true iff the given process have
 * terminated. */
STATIC bool
process_win32_timer_test_process(process_t *process)
{
  tor_assert(process);

  /* No need to look at processes that don't claim they are running. */
  if (process_get_status(process) != PROCESS_STATUS_RUNNING)
    return false;

  process_win32_t *win32_process = process_get_win32_process(process);
  BOOL ret = FALSE;
  DWORD exit_code = 0;

  /* Sometimes the Windows kernel won't give us the EOF/Broken Pipe error
   * message until some time after the process have actually terminated. We
   * make sure that our ReadFileEx() calls for the process have *all* returned
   * and both standard out and error have been marked as EOF before we try to
   * see if the process terminated.
   *
   * This ensures that we *never* call the exit callback of the `process_t`,
   * which potentially ends up calling `process_free()` on our `process_t`,
   * before all data have been received from the process.
   *
   * We do NOT have a check here for whether standard in reached EOF since
   * standard in's WriteFileEx() function is only called on-demand when we have
   * something to write and is thus usually not awaiting to finish any
   * operations. If we WriteFileEx() to a file that has terminated we'll simply
   * get an error from ReadFileEx() or its completion routine and move on with
   * life.  */
  if (! win32_process->stdout_handle.reached_eof)
    return false;

  if (! win32_process->stderr_handle.reached_eof)
    return false;

  /* We start by testing whether our process is still running. */
  ret = GetExitCodeProcess(win32_process->process_information.hProcess,
                           &exit_code);

  if (! ret) {
    log_warn(LD_PROCESS, "GetExitCodeProcess() failed: %s",
             format_win32_error(GetLastError()));
    return false;
  }

  /* Notify our process_t that our process have terminated. Since our
   * exit_callback might decide to process_free() our process handle it is very
   * important that we do not touch the process_t after the call to
   * process_notify_event_exit(). */
  if (exit_code != STILL_ACTIVE) {
    process_notify_event_exit(process, exit_code);
    return true;
  }

  return false;
}

/** Create a new overlapped named pipe. This function creates a new connected,
 * named, pipe in <b>*read_pipe</b> and <b>*write_pipe</b> if the function is
 * successful. Returns true on success, false on failure. */
STATIC bool
process_win32_create_pipe(HANDLE *read_pipe,
                          HANDLE *write_pipe,
                          SECURITY_ATTRIBUTES *attributes,
                          process_win32_pipe_type_t pipe_type)
{
  tor_assert(read_pipe);
  tor_assert(write_pipe);
  tor_assert(attributes);

  BOOL ret = FALSE;

  /* Buffer size. */
  const size_t size = 4096;

  /* Our additional read/write modes that depends on which pipe type we are
   * creating. */
  DWORD read_mode = 0;
  DWORD write_mode = 0;

  /* Generate the unique pipe name. */
  char pipe_name[MAX_PATH];
  static DWORD process_id = 0;
  static DWORD counter = 0;

  if (process_id == 0)
    process_id = GetCurrentProcessId();

  tor_snprintf(pipe_name, sizeof(pipe_name),
               "\\\\.\\Pipe\\Tor-Process-Pipe-%lu-%lu",
               process_id, counter++);

  /* Only one of our handles can be overlapped. */
  switch (pipe_type) {
  case PROCESS_WIN32_PIPE_TYPE_READER:
    read_mode = FILE_FLAG_OVERLAPPED;
    break;
  case PROCESS_WIN32_PIPE_TYPE_WRITER:
    write_mode = FILE_FLAG_OVERLAPPED;
    break;
  default:
    /* LCOV_EXCL_START */
    tor_assert_nonfatal_unreached_once();
    /* LCOV_EXCL_STOP */
  }

  /* Setup our read and write handles. */
  HANDLE read_handle;
  HANDLE write_handle;

  /* Create our named pipe. */
  read_handle = CreateNamedPipeA(pipe_name,
                                 (PIPE_ACCESS_INBOUND|read_mode),
                                 (PIPE_TYPE_BYTE|PIPE_WAIT),
                                 1,
                                 size,
                                 size,
                                 1000,
                                 attributes);

  if (read_handle == INVALID_HANDLE_VALUE) {
    log_warn(LD_PROCESS, "CreateNamedPipeA() failed: %s",
             format_win32_error(GetLastError()));
    return false;
  }

  /* Create our file in the pipe namespace. */
  write_handle = CreateFileA(pipe_name,
                             GENERIC_WRITE,
                             0,
                             attributes,
                             OPEN_EXISTING,
                             (FILE_ATTRIBUTE_NORMAL|write_mode),
                             NULL);

  if (write_handle == INVALID_HANDLE_VALUE) {
    log_warn(LD_PROCESS, "CreateFileA() failed: %s",
             format_win32_error(GetLastError()));

    CloseHandle(read_handle);

    return false;
  }

  /* Set the inherit flag for our pipe. */
  switch (pipe_type) {
  case PROCESS_WIN32_PIPE_TYPE_READER:
    ret = SetHandleInformation(read_handle, HANDLE_FLAG_INHERIT, 0);
    break;
  case PROCESS_WIN32_PIPE_TYPE_WRITER:
    ret = SetHandleInformation(write_handle, HANDLE_FLAG_INHERIT, 0);
    break;
  default:
    /* LCOV_EXCL_START */
    tor_assert_nonfatal_unreached_once();
    /* LCOV_EXCL_STOP */
  }

  if (! ret) {
    log_warn(LD_PROCESS, "SetHandleInformation() failed: %s",
             format_win32_error(GetLastError()));

    CloseHandle(read_handle);
    CloseHandle(write_handle);

    return false;
  }

  /* Everything is good. */
  *read_pipe = read_handle;
  *write_pipe = write_handle;

  return true;
}

/** Cleanup a given <b>handle</b>. */
STATIC void
process_win32_cleanup_handle(process_win32_handle_t *handle)
{
  tor_assert(handle);

#if 0
  BOOL ret;
  DWORD error_code;

  /* Cancel any pending I/O requests: This means that instead of getting
   * ERROR_BROKEN_PIPE we get ERROR_OPERATION_ABORTED, but it doesn't seem
   * like this is needed. */
  ret = CancelIo(handle->pipe);

  if (! ret) {
    error_code = GetLastError();

    /* There was no pending I/O requests for our handle. */
    if (error_code != ERROR_NOT_FOUND) {
      log_warn(LD_PROCESS, "CancelIo() failed: %s",
               format_win32_error(error_code));
    }
  }
#endif /* 0 */

  /* Close our handle. */
  if (handle->pipe != INVALID_HANDLE_VALUE) {
    CloseHandle(handle->pipe);
    handle->pipe = INVALID_HANDLE_VALUE;
    handle->reached_eof = true;
  }
}

/** This function is called when ReadFileEx() completes its background read
 * from the child process's standard output. We notify the Process subsystem if
 * there is data available for it to read from us. */
STATIC VOID WINAPI
process_win32_stdout_read_done(DWORD error_code,
                               DWORD byte_count,
                               LPOVERLAPPED overlapped)
{
  tor_assert(overlapped);
  tor_assert(overlapped->hEvent);

  /* Extract our process_t from the hEvent member of OVERLAPPED. */
  process_t *process = (process_t *)overlapped->hEvent;
  process_win32_t *win32_process = process_get_win32_process(process);

  if (process_win32_handle_read_completion(&win32_process->stdout_handle,
                                           error_code,
                                           byte_count)) {
    /* Schedule our next read. */
    process_notify_event_stdout(process);
  }
}

/** This function is called when ReadFileEx() completes its background read
 * from the child process's standard error. We notify the Process subsystem if
 * there is data available for it to read from us. */
STATIC VOID WINAPI
process_win32_stderr_read_done(DWORD error_code,
                               DWORD byte_count,
                               LPOVERLAPPED overlapped)
{
  tor_assert(overlapped);
  tor_assert(overlapped->hEvent);

  /* Extract our process_t from the hEvent member of OVERLAPPED. */
  process_t *process = (process_t *)overlapped->hEvent;
  process_win32_t *win32_process = process_get_win32_process(process);

  if (process_win32_handle_read_completion(&win32_process->stderr_handle,
                                           error_code,
                                           byte_count)) {
    /* Schedule our next read. */
    process_notify_event_stderr(process);
  }
}

/** This function is called when WriteFileEx() completes its background write
 * to the child process's standard input. We notify the Process subsystem that
 * it can write data to us again. */
STATIC VOID WINAPI
process_win32_stdin_write_done(DWORD error_code,
                               DWORD byte_count,
                               LPOVERLAPPED overlapped)
{
  tor_assert(overlapped);
  tor_assert(overlapped->hEvent);

  (void)byte_count;

  process_t *process = (process_t *)overlapped->hEvent;
  process_win32_t *win32_process = process_get_win32_process(process);

  /* Mark our handle as not having any outstanding I/O requests. */
  win32_process->stdin_handle.busy = false;

  /* Check if we have been asked to write to the handle that have been marked
   * as having reached EOF. */
  if (BUG(win32_process->stdin_handle.reached_eof))
    return;

  if (error_code == 0) {
    /** Our data have been successfully written. Clear our state and schedule
     * the next write. */
    win32_process->stdin_handle.data_available = 0;
    memset(win32_process->stdin_handle.buffer, 0,
           sizeof(win32_process->stdin_handle.buffer));

    /* Schedule the next write. */
    process_notify_event_stdin(process);
  } else if (error_code == ERROR_HANDLE_EOF ||
             error_code == ERROR_BROKEN_PIPE) {
    /* Our WriteFileEx() call was successful, but we reached the end of our
     * file.  We mark our handle as having reached EOF and returns. */
    tor_assert(byte_count == 0);

    win32_process->stdin_handle.reached_eof = true;
  } else {
    /* An error happened: We warn the user and mark our handle as having
     * reached EOF */
    log_warn(LD_PROCESS,
             "Error in I/O completion routine from WriteFileEx(): %s",
             format_win32_error(error_code));
    win32_process->stdin_handle.reached_eof = true;
  }
}

/** This function reads data from the given <b>handle</b>'s internal buffer and
 * moves it into the given <b>buffer</b>. Additionally, we start the next
 * ReadFileEx() background operation with the given <b>callback</b> as
 * completion callback. Returns the number of bytes written to the buffer. */
STATIC int
process_win32_read_from_handle(process_win32_handle_t *handle,
                               buf_t *buffer,
                               LPOVERLAPPED_COMPLETION_ROUTINE callback)
{
  tor_assert(handle);
  tor_assert(buffer);
  tor_assert(callback);

  BOOL ret = FALSE;
  int bytes_available = 0;
  DWORD error_code = 0;

  /* We already have a request to read data that isn't complete yet. */
  if (BUG(handle->busy))
    return 0;

  /* Check if we have been asked to read from a handle that have already told
   * us that we have reached the end of the file. */
  if (BUG(handle->reached_eof))
    return 0;

  /* This cast should be safe since our buffer can be at maximum up to
   * BUFFER_SIZE in size. */
  bytes_available = (int)handle->data_available;

  if (handle->data_available > 0) {
    /* Read data from our intermediate buffer into the process_t buffer. */
    buf_add(buffer, handle->buffer, handle->data_available);

    /* Reset our read state. */
    handle->data_available = 0;
    memset(handle->buffer, 0, sizeof(handle->buffer));
  }

  /* Because of the slightly weird API for ReadFileEx() we must set this to 0
   * before we call ReadFileEx() because ReadFileEx() does not reset the last
   * error itself when it's successful. See comment below after the call to
   * GetLastError(). */
  SetLastError(0);

  /* Ask the Windows kernel to read data from our pipe into our buffer and call
   * the callback function when it is done. */
  ret = ReadFileEx(handle->pipe,
                   handle->buffer,
                   sizeof(handle->buffer),
                   &handle->overlapped,
                   callback);

  if (! ret) {
    error_code = GetLastError();

    /* No need to log at warning level for these two. */
    if (error_code == ERROR_HANDLE_EOF || error_code == ERROR_BROKEN_PIPE) {
      log_debug(LD_PROCESS, "ReadFileEx() returned EOF from pipe: %s",
                format_win32_error(error_code));
    } else {
      log_warn(LD_PROCESS, "ReadFileEx() failed: %s",
               format_win32_error(error_code));
    }

    handle->reached_eof = true;
    return bytes_available;
  }

  /* Here be dragons: According to MSDN's documentation for ReadFileEx() we
   * should check GetLastError() after a call to ReadFileEx() even though the
   * `ret` return value was successful. If everything is good, GetLastError()
   * returns `ERROR_SUCCESS` and nothing happens.
   *
   * XXX(ahf): I have not managed to trigger this code while stress-testing
   * this code. */
  error_code = GetLastError();

  if (error_code != ERROR_SUCCESS) {
    /* LCOV_EXCL_START */
    log_warn(LD_PROCESS, "ReadFileEx() failed after returning success: %s",
             format_win32_error(error_code));
    handle->reached_eof = true;
    return bytes_available;
    /* LCOV_EXCL_STOP */
  }

  /* We mark our handle as having a pending I/O request. */
  handle->busy = true;

  return bytes_available;
}

/** This function checks the callback values from ReadFileEx() in
 * <b>error_code</b> and <b>byte_count</b> if we have read data. Returns true
 * iff our caller should request more data from ReadFileEx(). */
STATIC bool
process_win32_handle_read_completion(process_win32_handle_t *handle,
                                     DWORD error_code,
                                     DWORD byte_count)
{
  tor_assert(handle);

  /* Mark our handle as not having any outstanding I/O requests. */
  handle->busy = false;

  if (error_code == 0) {
    /* Our ReadFileEx() call was successful and there is data for us. */

    /* This cast should be safe since byte_count should never be larger than
     * BUFFER_SIZE. */
    tor_assert(byte_count <= BUFFER_SIZE);
    handle->data_available = (size_t)byte_count;

    /* Tell our caller to schedule the next read. */
    return true;
  } else if (error_code == ERROR_HANDLE_EOF ||
             error_code == ERROR_BROKEN_PIPE) {
    /* Our ReadFileEx() finished, but we reached the end of our file.  We mark
     * our handle as having reached EOF and returns. */
    tor_assert(byte_count == 0);

    handle->reached_eof = true;
  } else {
    /* An error happened: We warn the user and mark our handle as having
     * reached EOF */
    log_warn(LD_PROCESS,
             "Error in I/O completion routine from ReadFileEx(): %s",
             format_win32_error(error_code));

    handle->reached_eof = true;
  }

  /* Our caller should NOT schedule the next read. */
  return false;
}

/** Format a single argument for being put on a Windows command line.
 * Returns a newly allocated string */
STATIC char *
format_win_cmdline_argument(const char *arg)
{
  char *formatted_arg;
  char need_quotes;
  const char *c;
  int i;
  int bs_counter = 0;
  /* Backslash we can point to when one is inserted into the string */
  const char backslash = '\\';

  /* Smartlist of *char */
  smartlist_t *arg_chars;
  arg_chars = smartlist_new();

  /* Quote string if it contains whitespace or is empty */
  need_quotes = (strchr(arg, ' ') || strchr(arg, '\t') || '\0' == arg[0]);

  /* Build up smartlist of *chars */
  for (c=arg; *c != '\0'; c++) {
    if ('"' == *c) {
      /* Double up backslashes preceding a quote */
      for (i=0; i<(bs_counter*2); i++)
        smartlist_add(arg_chars, (void*)&backslash);
      bs_counter = 0;
      /* Escape the quote */
      smartlist_add(arg_chars, (void*)&backslash);
      smartlist_add(arg_chars, (void*)c);
    } else if ('\\' == *c) {
      /* Count backslashes until we know whether to double up */
      bs_counter++;
    } else {
      /* Don't double up slashes preceding a non-quote */
      for (i=0; i<bs_counter; i++)
        smartlist_add(arg_chars, (void*)&backslash);
      bs_counter = 0;
      smartlist_add(arg_chars, (void*)c);
    }
  }
  /* Don't double up trailing backslashes */
  for (i=0; i<bs_counter; i++)
    smartlist_add(arg_chars, (void*)&backslash);

  /* Allocate space for argument, quotes (if needed), and terminator */
  const size_t formatted_arg_len = smartlist_len(arg_chars) +
    (need_quotes ? 2 : 0) + 1;
  formatted_arg = tor_malloc_zero(formatted_arg_len);

  /* Add leading quote */
  i=0;
  if (need_quotes)
    formatted_arg[i++] = '"';

  /* Add characters */
  SMARTLIST_FOREACH(arg_chars, char*, ch,
  {
    formatted_arg[i++] = *ch;
  });

  /* Add trailing quote */
  if (need_quotes)
    formatted_arg[i++] = '"';
  formatted_arg[i] = '\0';

  smartlist_free(arg_chars);
  return formatted_arg;
}

/** Format a command line for use on Windows, which takes the command as a
 * string rather than string array. Follows the rules from "Parsing C++
 * Command-Line Arguments" in MSDN. Algorithm based on list2cmdline in the
 * Python subprocess module. Returns a newly allocated string */
STATIC char *
tor_join_win_cmdline(const char *argv[])
{
  smartlist_t *argv_list;
  char *joined_argv;
  int i;

  /* Format each argument and put the result in a smartlist */
  argv_list = smartlist_new();
  for (i=0; argv[i] != NULL; i++) {
    smartlist_add(argv_list, (void *)format_win_cmdline_argument(argv[i]));
  }

  /* Join the arguments with whitespace */
  joined_argv = smartlist_join_strings(argv_list, " ", 0, NULL);

  /* Free the newly allocated arguments, and the smartlist */
  SMARTLIST_FOREACH(argv_list, char *, arg,
  {
    tor_free(arg);
  });
  smartlist_free(argv_list);

  return joined_argv;
}

#endif /* defined(_WIN32) */