lib/windows-spawn.h

   1 /* Auxiliary functions for the creation of subprocesses.  Native Windows API.
   2    Copyright (C) 2001, 2003-2020 Free Software Foundation, Inc.
   3    Written by Bruno Haible <bruno@clisp.org>, 2003.
   4
   5    This program is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU General Public License as published by
   7    the Free Software Foundation; either version 3 of the License, or
   8    (at your option) any later version.
   9
  10    This program is distributed in the hope that it will be useful,
  11    but WITHOUT ANY WARRANTY; without even the implied warranty of
  12    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13    GNU General Public License for more details.
  14
  15    You should have received a copy of the GNU General Public License
  16    along with this program.  If not, see <https://www.gnu.org/licenses/>.  */
  17
  18 #ifndef _WINDOWS_SPAWN_H
  19 #define _WINDOWS_SPAWN_H
  20
  21 #include <stdint.h>
  22
  23 /* Get declarations of the native Windows API functions.  */
  24 #define WIN32_LEAN_AND_MEAN
  25 #include <windows.h>
  26
  27 /* Prepares an argument vector before calling spawn().
  28    Note that spawn() does not by itself call the command interpreter
  29      (getenv ("COMSPEC") != NULL ? getenv ("COMSPEC") :
  30       ({ OSVERSIONINFO v; v.dwOSVersionInfoSize = sizeof(OSVERSIONINFO);
  31          GetVersionEx(&v);
  32          v.dwPlatformId == VER_PLATFORM_WIN32_NT;
  33       }) ? "cmd.exe" : "command.com").
  34    Instead it simply concatenates the arguments, separated by ' ', and calls
  35    CreateProcess().  We must quote the arguments since Windows CreateProcess()
  36    interprets characters like ' ', '\t', '\\', '"' (but not '<' and '>') in a
  37    special way:
  38    - Space and tab are interpreted as delimiters. They are not treated as
  39      delimiters if they are surrounded by double quotes: "...".
  40    - Unescaped double quotes are removed from the input. Their only effect is
  41      that within double quotes, space and tab are treated like normal
  42      characters.
  43    - Backslashes not followed by double quotes are not special.
  44    - But 2*n+1 backslashes followed by a double quote become
  45      n backslashes followed by a double quote (n >= 0):
  46        \" -> "
  47        \\\" -> \"
  48        \\\\\" -> \\"
  49    - '*', '?' characters may get expanded through wildcard expansion in the
  50      callee: By default, in the callee, the initialization code before main()
  51      takes the result of GetCommandLine(), wildcard-expands it, and passes it
  52      to main(). The exceptions to this rule are:
  53        - programs that inspect GetCommandLine() and ignore argv,
  54        - mingw programs that have a global variable 'int _CRT_glob = 0;',
  55        - Cygwin programs, when invoked from a Cygwin program.
  56  */
  57 extern char ** prepare_spawn (char **argv);
  58
  59 /* Creates a subprocess.
  60    MODE is either P_WAIT or P_NOWAIT.
  61    PROGNAME is the program to invoke.
  62    ARGV is the NULL-terminated array of arguments, ARGV[0] being PROGNAME by
  63    convention.
  64    ENVP is the NULL-terminated set of environment variable assignments, or NULL
  65    to inherit the initial environ variable assignments from the caller and
  66    ignore all calls to putenv(), setenv(), unsetenv() done in the caller.
  67    CURRDIR is the directory in which to start the program, or NULL to inherit
  68    the working directory from the caller.
  69    STDIN_HANDLE, STDOUT_HANDLE, STDERR_HANDLE are the handles to use for the
  70    first three file descriptors in the callee process.
  71    Returns
  72      - 0 for success (if MODE is P_WAIT), or
  73      - a handle that be passed to _cwait (on Windows) or waitpid (on OS/2), or
  74      - -1 upon error, with errno set.
  75  */
  76 extern intptr_t spawnpvech (int mode,
  77                             const char *progname, const char * const *argv,
  78                             const char * const *envp,
  79                             const char *currdir,
  80                             HANDLE stdin_handle, HANDLE stdout_handle,
  81                             HANDLE stderr_handle);
  82
  83 #endif /* _WINDOWS_SPAWN_H */