Add utility functions for invoking a subprocess (ros2#491)

This new function and associated functions provide a cross-platform
mechanism for invoking a command as a subprocess of the currently
running process.

Signed-off-by: Scott K Logan <logans@cottsay.net>

Author: cottsay

include/rcutils/process.h

@@ -22,8 +22,24 @@ extern "C"
 {
 #endif
 
+#if defined _WIN32 || defined __CYGWIN__
+// When building with MSVC 19.28.29333.0 on Windows 10 (as of 2020-11-11),
+// there appears to be a problem with winbase.h (which is included by
+// Windows.h). In particular, warnings of the form:
+//
+// warning C5105: macro expansion producing 'defined' has undefined behavior
+//
+// See https://developercommunity.visualstudio.com/content/problem/695656/wdk-and-sdk-are-not-compatible-with-experimentalpr.html
+// for more information. For now disable that warning when including windows.h
+#pragma warning(push)
+#pragma warning(disable : 5105)
+#include <Windows.h>
+#pragma warning(pop)
+#endif
+
 #include "rcutils/allocator.h"
 #include "rcutils/macros.h"
+#include "rcutils/types/string_array.h"
 #include "rcutils/visibility_control.h"
 
 /// Retrieve the current process ID.
@@ -54,6 +70,65 @@ RCUTILS_PUBLIC
 RCUTILS_WARN_UNUSED
 char * rcutils_get_executable_name(rcutils_allocator_t allocator);
 
+/// Information about a subprocess created by this process
+typedef struct rcutils_process_s
+{
+#if defined _WIN32 || defined __CYGWIN__
+  /// The open handle to the process.
+  HANDLE handle;
+#endif
+
+  /// The process ID of the process.
+  int pid;
+
+  /// The allocator used to allocate and free memory for the process.
+  rcutils_allocator_t allocator;
+} rcutils_process_t;
+
+/// Execute a command as a new subprocess.
+/**
+ * This function runs a command by creating a new subprocess of the currently
+ * running process.
+ *
+ * \param[in] args the command line arguments to be run
+ * \param[in] allocator the allocator to use
+ * \return The successfully created subprocess, or
+ * \return NULL on failure.
+ */
+RCUTILS_PUBLIC
+RCUTILS_WARN_UNUSED
+rcutils_process_t *
+rcutils_start_process(
+  const rcutils_string_array_t * args,
+  rcutils_allocator_t * allocator);
+
+/// Release resources allocated when a subprocess was created.
+/**
+ * Closes, cleans up, and deallocates resources which were allocated by
+ * rcutils_start_process(), including the rcutils_process_t itself.
+ * \param[in] process the process to be closed and deallocated
+ */
+RCUTILS_PUBLIC
+void rcutils_process_close(rcutils_process_t * process);
+
+/// Blocks until the given subprocess has been has exited.
+/**
+ * Wait for a subprocess to terminate, and optionally retrieve the exit code
+ * from that process.
+ * Upon successful invocation of this function, subsequent calls will produce
+ * undefined behavior. It should typically be followed by a call to
+ * rcutils_process_close().
+ * \param[in] process The process to wait for
+ * \param[out] status The exit code from that process
+ * \return #RCUTILS_RET_OK if the process exited, or
+ * \return #RCUTILS_RET_INVALID_ARGUMENT if the process argument is invalid
+ * \return #RCUTILS_RET_ERROR if an unexpected error occurs.
+ */
+RCUTILS_PUBLIC
+RCUTILS_WARN_UNUSED
+rcutils_ret_t
+rcutils_process_wait(const rcutils_process_t * process, int * status);
+
 #ifdef __cplusplus
 }
 #endif

src/process.c

@@ -36,11 +36,13 @@ extern "C"
 #pragma warning(pop)
 #else
 #include <libgen.h>
+#include <sys/wait.h>
 #include <unistd.h>
 #endif
 
 #include "rcutils/allocator.h"
 #include "rcutils/error_handling.h"
+#include "rcutils/join.h"
 #include "rcutils/process.h"
 #include "rcutils/strdup.h"
 
@@ -111,6 +113,147 @@ char * rcutils_get_executable_name(rcutils_allocator_t allocator)
   return executable_name;
 }
 
+rcutils_process_t *
+rcutils_start_process(
+  const rcutils_string_array_t * args,
+  rcutils_allocator_t * allocator)
+{
+  RCUTILS_CHECK_ARGUMENT_FOR_NULL(args, NULL);
+  RCUTILS_CHECK_ARGUMENT_FOR_NULL(allocator, NULL);
+  if (args->size < 1) {
+    RCUTILS_SET_ERROR_MSG("args list is empty");
+    return NULL;
+  }
+  RCUTILS_CHECK_ALLOCATOR_WITH_MSG(
+    allocator, "allocator is invalid", return NULL);
+
+  rcutils_process_t * process = allocator->zero_allocate(
+    1, sizeof(rcutils_process_t), allocator->state);
+  if (NULL == process) {
+    return NULL;
+  }
+  process->allocator = *allocator;
+
+#if defined _WIN32 || defined __CYGWIN__
+  LPSTR cmd = rcutils_join(args, " ", *allocator);
+  if (NULL == cmd) {
+    rcutils_process_close(process);
+    return NULL;
+  }
+
+  STARTUPINFO start_info = {sizeof(start_info)};
+  PROCESS_INFORMATION process_info = {0};
+  if (!CreateProcess(
+          NULL, cmd, NULL, NULL, TRUE, 0,
+          NULL, NULL, &start_info, &process_info))
+  {
+    RCUTILS_SET_ERROR_MSG_WITH_FORMAT_STRING("Failed to create process: %lu", GetLastError());
+    allocator->deallocate(cmd, &allocator->state);
+    rcutils_process_close(process);
+    return NULL;
+  }
+
+  allocator->deallocate(cmd, &allocator->state);
+
+  CloseHandle(process_info.hThread);
+
+  process->handle = process_info.hProcess;
+  process->pid = process_info.dwProcessId;
+
+  return process;
+#else
+  char **argv = allocator->zero_allocate(args->size + 1, sizeof(*argv), &allocator->state);
+  if (NULL == argv) {
+    return NULL;
+  }
+  memcpy(argv, args->data, args->size * sizeof(*argv));
+
+  process->pid = fork();
+  if (-1 == process->pid) {
+    int error = errno;
+    RCUTILS_SET_ERROR_MSG_WITH_FORMAT_STRING(
+      "Failed to fork process: %d (%s)", error, strerror(error));
+    allocator->deallocate(argv, &allocator->state);
+    rcutils_process_close(process);
+    return NULL;
+  } else if (0 != process->pid) {
+    allocator->deallocate(argv, &allocator->state);
+    return process;
+  }
+
+  (void)execvp(argv[0], argv);
+
+  int error = errno;
+  RCUTILS_SAFE_FWRITE_TO_STDERR_WITH_FORMAT_STRING(
+    "Failed to execute process: %d (%s)", error, strerror(error));
+  allocator->deallocate(argv, &allocator->state);
+  exit(127);
+#endif
+}
+
+void
+rcutils_process_close(rcutils_process_t * process)
+{
+  if (NULL == process) {
+    return;
+  }
+
+  rcutils_allocator_t allocator = process->allocator;
+  RCUTILS_CHECK_ALLOCATOR_WITH_MSG(
+    &allocator, "allocator is invalid", return );
+
+#if defined _WIN32 || defined __CYGWIN__
+  CloseHandle(process->handle);
+#endif
+
+  allocator.deallocate(process, allocator.state);
+}
+
+rcutils_ret_t
+rcutils_process_wait(const rcutils_process_t * process, int * exit_code)
+{
+  RCUTILS_CHECK_ARGUMENT_FOR_NULL(process, RCUTILS_RET_INVALID_ARGUMENT);
+
+#if defined _WIN32 || defined __CYGWIN__
+  DWORD status;
+
+  if (WAIT_FAILED == WaitForSingleObject(process->handle, INFINITE)) {
+    return RCUTILS_RET_ERROR;
+  }
+
+  if (NULL != exit_code) {
+    if (!GetExitCodeProcess(process->handle, &status)) {
+      return RCUTILS_RET_ERROR;
+    }
+    *exit_code = status;
+  }
+#else
+  int status;
+
+  int ret = waitpid(process->pid, &status, 0);
+  if (-1 == ret) {
+    int error = errno;
+    RCUTILS_SAFE_FWRITE_TO_STDERR_WITH_FORMAT_STRING(
+      "Failed to wait for process %d: %d (%s)", process->pid, error, strerror(error));
+    return RCUTILS_RET_ERROR;
+  }
+
+  if (NULL != exit_code) {
+    if (WIFSIGNALED(status)) {
+      *exit_code = -WTERMSIG(status);
+    } else if (WIFEXITED(status)) {
+      *exit_code = WEXITSTATUS(status);
+    } else if (WIFSTOPPED(status)) {
+      *exit_code = -WSTOPSIG(status);
+    } else {
+      return RCUTILS_RET_ERROR;
+    }
+  }
+#endif
+
+  return RCUTILS_RET_OK;
+}
+
 #ifdef __cplusplus
 }
 #endif

test/test_process.cpp

@@ -42,3 +42,42 @@ TEST(TestProcess, test_get_executable_name) {
   EXPECT_STREQ("test_process", exec_name);
   allocator.deallocate(exec_name, allocator.state);
 }
+
+TEST(TestProcess, test_process_creation) {
+  rcutils_allocator_t allocator = rcutils_get_default_allocator();
+  rcutils_allocator_t bad_allocator = rcutils_get_zero_initialized_allocator();
+  rcutils_allocator_t time_bomb_allocator = get_time_bomb_allocator();
+  rcutils_string_array_t args = rcutils_get_zero_initialized_string_array();
+  rcutils_process_t * process = NULL;
+  rcutils_ret_t ret = RCUTILS_RET_OK;
+  int exit_code = 42;
+
+  ret = rcutils_string_array_init(&args, 1, &allocator);
+  ASSERT_EQ(RCUTILS_RET_OK, ret);
+  args.data[0] = strdup("whoami");
+
+  EXPECT_EQ(nullptr, rcutils_start_process(NULL, &allocator));
+  rcutils_reset_error();
+
+  EXPECT_EQ(nullptr, rcutils_start_process(&args, NULL));
+  rcutils_reset_error();
+
+  EXPECT_EQ(nullptr, rcutils_start_process(&args, &bad_allocator));
+  rcutils_reset_error();
+
+  set_time_bomb_allocator_calloc_count(time_bomb_allocator, 0);
+  set_time_bomb_allocator_malloc_count(time_bomb_allocator, 0);
+  EXPECT_EQ(nullptr, rcutils_start_process(&args, &time_bomb_allocator));
+
+  process = rcutils_start_process(&args, &allocator);
+  EXPECT_NE(nullptr, process);
+
+  ret = rcutils_process_wait(process, &exit_code);
+  EXPECT_EQ(RCUTILS_RET_OK, ret);
+  EXPECT_EQ(0, exit_code);
+
+  rcutils_process_close(process);
+
+  ret = rcutils_string_array_fini(&args);
+  ASSERT_EQ(RCUTILS_RET_OK, ret);
+}