src/lib/process/process.h

   1 /* Copyright (c) 2003-2004, Roger Dingledine
   2  * Copyright (c) 2004-2006, Roger Dingledine, Nick Mathewson.
   3  * Copyright (c) 2007-2021, The Tor Project, Inc. */
   4 /* See LICENSE for licensing information */
   5
   6 /**
   7  * \file process.h
   8  * \brief Header for process.c
   9  **/
  10
  11 #ifndef TOR_PROCESS_H
  12 #define TOR_PROCESS_H
  13
  14 #include "orconfig.h"
  15 #include "lib/malloc/malloc.h"
  16 #include "lib/string/printf.h"
  17
  18 #include <stdbool.h>
  19
  20 /** Maximum number of bytes to write to a process' stdin. */
  21 #define PROCESS_MAX_WRITE (1024)
  22
  23 /** Maximum number of bytes to read from a process' stdout/stderr. */
  24 #define PROCESS_MAX_READ  (1024)
  25
  26 typedef enum {
  27   /** The process is not running. */
  28   PROCESS_STATUS_NOT_RUNNING,
  29
  30   /** The process is running. */
  31   PROCESS_STATUS_RUNNING,
  32
  33   /** The process is in an erroneous state. */
  34   PROCESS_STATUS_ERROR
  35 } process_status_t;
  36
  37 const char *process_status_to_string(process_status_t status);
  38
  39 typedef enum {
  40   /** Pass complete newline-terminated lines to the
  41    *  callback (with the LF or CRLF removed). */
  42   PROCESS_PROTOCOL_LINE,
  43
  44   /** Pass the raw response from read() to the callback. */
  45   PROCESS_PROTOCOL_RAW
  46 } process_protocol_t;
  47
  48 const char *process_protocol_to_string(process_protocol_t protocol);
  49
  50 void tor_disable_spawning_background_processes(void);
  51
  52 struct smartlist_t;
  53
  54 struct process_t;
  55 typedef struct process_t process_t;
  56
  57 typedef uint64_t process_exit_code_t;
  58 typedef uint64_t process_pid_t;
  59
  60 typedef void (*process_read_callback_t)(process_t *,
  61                                         const char *,
  62                                         size_t);
  63 typedef bool
  64 (*process_exit_callback_t)(process_t *, process_exit_code_t);
  65
  66 void process_init(void);
  67 void process_free_all(void);
  68 const struct smartlist_t *process_get_all_processes(void);
  69
  70 process_t *process_new(const char *command);
  71 void process_free_(process_t *process);
  72 #define process_free(s) FREE_AND_NULL(process_t, process_free_, (s))
  73
  74 process_status_t process_exec(process_t *process);
  75 bool process_terminate(process_t *process);
  76
  77 process_pid_t process_get_pid(process_t *process);
  78
  79 void process_set_stdout_read_callback(process_t *,
  80                                       process_read_callback_t);
  81 void process_set_stderr_read_callback(process_t *,
  82                                       process_read_callback_t);
  83 void process_set_exit_callback(process_t *,
  84                                process_exit_callback_t);
  85
  86 const char *process_get_command(const process_t *process);
  87
  88 void process_append_argument(process_t *process, const char *argument);
  89 const struct smartlist_t *process_get_arguments(const process_t *process);
  90 char **process_get_argv(const process_t *process);
  91
  92 void process_reset_environment(process_t *process,
  93                                const struct smartlist_t *env);
  94 void process_set_environment(process_t *process,
  95                              const char *key,
  96                              const char *value);
  97
  98 struct process_environment_t;
  99 struct process_environment_t *process_get_environment(const process_t *);
 100
 101 void process_set_protocol(process_t *process, process_protocol_t protocol);
 102 process_protocol_t process_get_protocol(const process_t *process);
 103
 104 void process_set_data(process_t *process, void *data);
 105 void *process_get_data(const process_t *process);
 106
 107 void process_set_status(process_t *process, process_status_t status);
 108 process_status_t process_get_status(const process_t *process);
 109
 110 #ifndef _WIN32
 111 struct process_unix_t;
 112 struct process_unix_t *process_get_unix_process(const process_t *process);
 113 #else
 114 struct process_win32_t;
 115 struct process_win32_t *process_get_win32_process(const process_t *process);
 116 #endif /* !defined(_WIN32) */
 117
 118 void process_write(process_t *process,
 119                    const uint8_t *data, size_t size);
 120 void process_vprintf(process_t *process,
 121                      const char *format, va_list args) CHECK_PRINTF(2, 0);
 122 void process_printf(process_t *process,
 123                     const char *format, ...) CHECK_PRINTF(2, 3);
 124
 125 void process_notify_event_stdout(process_t *process);
 126 void process_notify_event_stderr(process_t *process);
 127 void process_notify_event_stdin(process_t *process);
 128 void process_notify_event_exit(process_t *process,
 129                                process_exit_code_t);
 130
 131 #ifdef PROCESS_PRIVATE
 132 struct buf_t;
 133 MOCK_DECL(STATIC int, process_read_stdout, (process_t *, struct buf_t *));
 134 MOCK_DECL(STATIC int, process_read_stderr, (process_t *, struct buf_t *));
 135 MOCK_DECL(STATIC void, process_write_stdin, (process_t *, struct buf_t *));
 136
 137 STATIC void process_read_data(process_t *process,
 138                               struct buf_t *buffer,
 139                               process_read_callback_t callback);
 140 STATIC void process_read_buffer(process_t *process,
 141                                 struct buf_t *buffer,
 142                                 process_read_callback_t callback);
 143 STATIC void process_read_lines(process_t *process,
 144                                struct buf_t *buffer,
 145                                process_read_callback_t callback);
 146 #endif /* defined(PROCESS_PRIVATE) */
 147
 148 #endif /* !defined(TOR_PROCESS_H) */