addons/SystemCall/source/callsystem.h

   1 #ifndef CALLSYSTEM_INCLUDED
   2 #define CALLSYSTEM_INCLUDED
   3 /*
   4   callsystem    - system() on steorids
   5
   6   features:
   7    - asynchonous running of a child process
   8    - setup of the environment
   9    - substitution of environment variables
  10    - connect all 3 standard streams to pipes, null devices, or files
  11    - pathname handling
  12    - #!shebang interpreter handling on any OS
  13
  14   ALL IN A PORTABLE WAY!
  15
  16   Pathnames:
  17     /   seperates a path,
  18     :   is used as device identifier when the path starts with / ("/C:" becomes "C:\")
  19     .   is the current directory
  20     ..  is the parent directory
  21     ~   is the users home directory
  22
  23   Environment variables:
  24     only ${KEY} syntax is substituted in one pass, trying to substitute a non existing env var yields an error
  25  */
  26
  27 /*
  28   first abstraction of a few types and loading OS specific headers
  29 */
  30
  31 #include <assert.h>
  32 #include <stdio.h>
  33 #include <errno.h>
  34 #include <string.h>
  35 #include <stdlib.h>
  36 #include <signal.h>
  37
  38 //#define unix 1
  39 #if !defined(unix) && defined(__unix__) || defined(__NetBSD__)
  40 #define unix
  41 #endif
  42
  43 #if defined(__APPLE__)
  44         #define unix 1
  45         #include <sys/unistd.h>
  46 #endif
  47
  48 #if defined(unix)
  49         #define _GNU_SOURCE
  50         #include <sys/time.h>
  51         #include <sys/resource.h>
  52         #include <unistd.h>
  53         #include <fcntl.h>
  54         #include <sys/types.h>
  55         #include <sys/stat.h>
  56         #include <sys/wait.h>
  57 #elif defined(WIN32)
  58         #include <process.h>
  59 #else
  60         #error "system not supported!"
  61 #endif
  62
  63
  64 #ifdef unix
  65 /*
  66   opaque process identifier type and value for an illegal pid
  67  */
  68 typedef pid_t callsystem_pid_t;
  69 #define CALLSYSTEM_ILG_PID 0
  70
  71 /*
  72   opaque file descriptors and values for illegal, std and potable null fd's
  73   fd's are always used as pairs (two element array)
  74    [0] is the used for reading
  75    [1] is used for writing
  76    either side might be CALLSYSTEM_ILG_FD for non-pipes, callsystem cares for closing the aprobiate sides
  77 */
  78 typedef int callsystem_fd_t;
  79 /* this is never an fd */
  80 #define CALLSYSTEM_ILG_FD -1
  81
  82 #elif defined(WIN32)
  83 #include <windows.h>
  84 typedef HANDLE callsystem_pid_t;
  85 #define CALLSYSTEM_ILG_PID NULL
  86 typedef HANDLE callsystem_fd_t;
  87 #define CALLSYSTEM_ILG_FD INVALID_HANDLE_VALUE
  88 #else
  89 #error "system unsupported"
  90 #endif
  91
  92
  93 \f
  94 /*
  95   INVOKING AND CONTROLLING CHILD PROGRAMS
  96  */
  97
  98 int
  99 callsystem(const char * cmd,
 100            char * argv[],
 101            char * env[],
 102            callsystem_fd_t in[2],
 103            callsystem_fd_t out[2],
 104            callsystem_fd_t err[2],
 105            const char * wd,
 106            const int pri,
 107            callsystem_pid_t * const child);
 108
 109 int
 110 callsystem_running(callsystem_pid_t * pid);
 111
 112 int
 113 callsystem_finished(callsystem_pid_t * pid);
 114
 115 int
 116 callsystem_terminate(callsystem_pid_t *);
 117
 118 int
 119 callsystem_abort(callsystem_pid_t *);
 120
 121 \f
 122 /*
 123   HANDLING FILE DESCRIPTORS AND PIPES
 124  */
 125
 126 int
 127 callsystem_pipe(callsystem_fd_t pipe[2]);
 128
 129 int
 130 callsystem_null(callsystem_fd_t null[2]);
 131
 132
 133 enum callsystem_filemode{
 134   CALLSYSTEM_MODE_READ,
 135   CALLSYSTEM_MODE_WRITE,
 136   CALLSYSTEM_MODE_CREATE,
 137   CALLSYSTEM_MODE_APPEND,
 138   CALLSYSTEM_MODE_OVERWRITE,
 139   CALLSYSTEM_MODE_BINARY=8
 140 };
 141
 142 int
 143 callsystem_open(const char * filename,
 144                 enum callsystem_filemode mode,
 145                 callsystem_fd_t fd[2]);
 146
 147 /* want sockets too? prolly not in the domain of this thing */
 148
 149 int
 150 callsystem_close(callsystem_fd_t fds[2]);
 151
 152 /*
 153   create a std C FILE stream to a underlying filedescriptor
 154 */
 155 FILE *
 156 callsystem_fdopen(callsystem_fd_t fds[2], enum callsystem_filemode mode);
 157
 158
 159 \f
 160 /*
 161   ENVIRONMENT SETUP
 162  */
 163
 164 int
 165 callsystem_setenv(char ** env[], const char * key, const char * value);
 166
 167 const char *
 168 callsystem_getenv(char ** env[], const  char * key);
 169
 170 int
 171 callsystem_unsetenv(char ** env[], const char * key);
 172
 173 int
 174 callsystem_exportenv(char ** env[], const char * key);
 175
 176 int
 177 callsystem_exportdefaults(char ** env[]);
 178
 179 char *
 180 callsystem_env_subst(char ** envp[], const char * str);
 181
 182 void
 183 callsystem_env_clear(char ** env[]);
 184
 185
 186
 187 \f
 188 /*
 189   SETUP OF THE ARGV
 190  */
 191
 192 int
 193 callsystem_argv_pushback(char ** argv[], const char * const arg);
 194
 195 int
 196 callsystem_argv_pushfront(char ** argv[], const char * const arg);
 197
 198 void
 199 callsystem_argv_clear(char ** argv[]);
 200
 201 \f
 202 /*
 203   PORTABLE PATHNAME HANDLING
 204  */
 205
 206 /*
 207   planned:
 208   callsystem_canonalize_path_to_host()
 209   callsystem_canonalize_path_to_unix()
 210
 211   convert unix like filenames to OS specific filenames (and back)
 212
 213   checks that relative filenames do not leave their top directory
 214
 215   for win32:
 216    "/Letter:/" becomes "Letter:\"
 217    "/foo/" becomes "\foo\"
 218
 219    needs much to worked out (UNC?)
 220
 221    callsystem_is_pathname()
 222     check if some string could be a legal pathname on the actual host
 223  */
 224
 225
 226
 227 #endif