lib/windows-spawn.h

   1 /* Auxiliary functions for the creation of subprocesses.  Native Windows API.
   2    Copyright (C) 2001, 2003-2024 Free Software Foundation, Inc.
   3    Written by Bruno Haible <bruno@clisp.org>, 2003.
   4
   5    This file is free software: you can redistribute it and/or modify
   6    it under the terms of the GNU Lesser General Public License as
   7    published by the Free Software Foundation; either version 2.1 of the
   8    License, or (at your option) any later version.
   9
  10    This file 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 Lesser General Public License for more details.
  14
  15    You should have received a copy of the GNU Lesser 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 /* This file uses _GL_ATTRIBUTE_MALLOC.  */
  22 #if !_GL_CONFIG_H_INCLUDED
  23  #error "Please include config.h first."
  24 #endif
  25
  26 #include <stdint.h>
  27 #include <stdlib.h>
  28
  29 /* Get declarations of the native Windows API functions.  */
  30 #define WIN32_LEAN_AND_MEAN
  31 #include <windows.h>
  32
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38
  39 /* Prepares an argument vector before calling spawn().
  40
  41    Note that spawn() does not by itself call the command interpreter
  42      (getenv ("COMSPEC") != NULL ? getenv ("COMSPEC") :
  43       ({ OSVERSIONINFO v; v.dwOSVersionInfoSize = sizeof(OSVERSIONINFO);
  44          GetVersionEx(&v);
  45          v.dwPlatformId == VER_PLATFORM_WIN32_NT;
  46       }) ? "cmd.exe" : "command.com").
  47    Instead it simply concatenates the arguments, separated by ' ', and calls
  48    CreateProcess().  We must quote the arguments since Windows CreateProcess()
  49    interprets characters like ' ', '\t', '\\', '"' (but not '<' and '>') in a
  50    special way:
  51    - Space and tab are interpreted as delimiters. They are not treated as
  52      delimiters if they are surrounded by double quotes: "...".
  53    - Unescaped double quotes are removed from the input. Their only effect is
  54      that within double quotes, space and tab are treated like normal
  55      characters.
  56    - Backslashes not followed by double quotes are not special.
  57    - But 2*n+1 backslashes followed by a double quote become
  58      n backslashes followed by a double quote (n >= 0):
  59        \" -> "
  60        \\\" -> \"
  61        \\\\\" -> \\"
  62    - '*', '?' characters may get expanded through wildcard expansion in the
  63      callee: By default, in the callee, the initialization code before main()
  64      takes the result of GetCommandLine(), wildcard-expands it, and passes it
  65      to main(). The exceptions to this rule are:
  66        - programs that inspect GetCommandLine() and ignore argv,
  67        - mingw programs that have a global variable 'int _CRT_glob = 0;',
  68        - Cygwin programs, when invoked from a Cygwin program.
  69
  70    prepare_spawn creates and returns a new argument vector, where the arguments
  71    are appropriately quoted and an additional argument "sh.exe" has been added
  72    at the beginning.  The new argument vector is freshly allocated.  The memory
  73    for all its elements is allocated within *MEM_TO_FREE, which is freshly
  74    allocated as well.  In case of memory allocation failure, NULL is returned,
  75    with errno set.
  76  */
  77 extern const char ** prepare_spawn (const char * const *argv,
  78                                     char **mem_to_free);
  79
  80 /* Composes the command to be passed to CreateProcess().
  81    ARGV must contain appropriately quoted arguments, as returned by
  82    prepare_spawn.
  83    Returns a freshly allocated string.  In case of memory allocation failure,
  84    NULL is returned, with errno set.  */
  85 extern char * compose_command (const char * const *argv)
  86   _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE;
  87
  88 /* Composes the block of memory that contains the environment variables.
  89    ENVP must contain an environment (a NULL-terminated array of string of the
  90    form VARIABLE=VALUE).
  91    NEW_PATH must be a string of the form PATH=VALUE, or NULL if the PATH
  92    environment variable from this process is suitable for the child process.
  93    Returns a freshly allocated block of memory.  In case of memory allocation
  94    failure, NULL is returned, with errno set.  */
  95 extern char * compose_envblock (const char * const *envp, const char *new_PATH)
  96   _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE;
  97
  98
  99 /* An inheritable handle with some additional information.  */
 100 struct IHANDLE
 101 {
 102   /* Either INVALID_HANDLE_VALUE or an inheritable handle.  */
 103   HANDLE handle;
 104   /* Only relevant if handle != INVALID_HANDLE_VALUE.
 105      It is a bit mask consisting of:
 106        - 32 for O_APPEND.
 107        - KEEP_OPEN_IN_CHILD if the handle is scheduled to be preserved in the
 108          child process.
 109        - KEEP_OPEN_IN_PARENT if the handle is shared with (and needs to be kept
 110          open in) the parent process.
 111        - DELAYED_DUP2_OLDFD if there is a delayed dup2 (oldfd, newfd) and
 112          this IHANDLE is at position oldfd.
 113        - DELAYED_DUP2_NEWFD if there is a delayed dup2 (oldfd, newfd) and
 114          this IHANDLE is at position newfd.
 115      Note that DELAYED_DUP2_OLDFD and DELAYED_DUP2_NEWFD cannot be set in the
 116      same IHANDLE.  */
 117   unsigned short flags;
 118   #define KEEP_OPEN_IN_CHILD 0x100
 119   #define KEEP_OPEN_IN_PARENT 0x200
 120   #define DELAYED_DUP2_OLDFD 0x400
 121   #define DELAYED_DUP2_NEWFD 0x800
 122   /* Only relevant if handle != INVALID_HANDLE_VALUE and flags contains
 123      either DELAYED_DUP2_OLDFD or DELAYED_DUP2_NEWFD.
 124      It is the other fd of the delayed dup2 (oldfd, newfd), i.e.
 125        - for DELAYED_DUP2_OLDFD, the newfd,
 126        - for DELAYED_DUP2_NEWFD, the oldfd.  */
 127   int linked_fd;
 128 };
 129
 130 /* This struct keeps track of which handles to potentially pass to a subprocess,
 131    and with which flags.  All of the handles here are inheritable.
 132    Regarding handle inheritance, see
 133    <https://docs.microsoft.com/en-us/windows/win32/sysinfo/handle-inheritance>.
 134    Whether a handle is actually scheduled for being preserved in the child
 135    process is determined by the KEEP_OPEN_IN_CHILD bit in the flags.  */
 136 struct inheritable_handles
 137 {
 138   /* The number of occupied entries in the two arrays below.
 139      3 <= count <= allocated.  */
 140   size_t count;
 141   /* The number of allocated entries in the two arrays below.  */
 142   size_t allocated;
 143   /* ih[0..count-1] are the occupied entries.  */
 144   struct IHANDLE *ih;
 145 };
 146
 147 /* Initializes a set of inheritable handles, filling in all or part of the
 148    file descriptors of the current process.
 149    If DUPLICATE is true, the handles stored are those of all file descriptors,
 150    and we use DuplicateHandle to make sure that they are all inheritable.
 151    If DUPLICATE is false, the handles stored are only the inheritables ones;
 152    this is a shortcut for spawnpvech().
 153    Returns 0 upon success.  In case of failure, -1 is returned, with errno set.
 154  */
 155 extern int init_inheritable_handles (struct inheritable_handles *inh_handles,
 156                                      bool duplicate);
 157
 158 /* Fills a set of inheritable handles into a STARTUPINFO for CreateProcess().
 159    Returns 0 upon success.  In case of failure, -1 is returned, with errno set.
 160  */
 161 extern int compose_handles_block (const struct inheritable_handles *inh_handles,
 162                                   STARTUPINFOA *sinfo);
 163
 164 /* Frees the memory held by a set of inheritable handles.  */
 165 extern void free_inheritable_handles (struct inheritable_handles *inh_handles);
 166
 167
 168 /* Converts a CreateProcess() error code (retrieved through GetLastError()) to
 169    an errno value.  */
 170 extern int convert_CreateProcess_error (DWORD error);
 171
 172
 173 /* Creates a subprocess.
 174    MODE is either P_WAIT or P_NOWAIT.
 175    PROGNAME is the program to invoke.
 176    ARGV is the NULL-terminated array of arguments, ARGV[0] being PROGNAME by
 177    convention.
 178    ENVP is the NULL-terminated set of environment variable assignments, or NULL
 179    to inherit the initial environ variable assignments from the caller and
 180    ignore all calls to putenv(), setenv(), unsetenv() done in the caller.
 181    DLL_DIRS is, on Windows platforms, a NULL-terminated list of directories
 182    that contain DLLs needed to execute the program, or NULL if none is needed.
 183    On other platforms, always pass NULL.
 184    CURRDIR is the directory in which to start the program, or NULL to inherit
 185    the working directory from the caller.
 186    STDIN_HANDLE, STDOUT_HANDLE, STDERR_HANDLE are the handles to use for the
 187    first three file descriptors in the callee process.
 188    Returns
 189      - 0 for success (if MODE is P_WAIT), or
 190      - a handle that be passed to _cwait (on Windows) or waitpid (on OS/2), or
 191      - -1 upon error, with errno set.
 192  */
 193 extern intptr_t spawnpvech (int mode,
 194                             const char *progname, const char * const *argv,
 195                             const char * const *envp,
 196                             const char * const *dll_dirs,
 197                             const char *currdir,
 198                             HANDLE stdin_handle, HANDLE stdout_handle,
 199                             HANDLE stderr_handle);
 200
 201
 202 #ifdef __cplusplus
 203 }
 204 #endif
 205
 206 #endif /* _WINDOWS_SPAWN_H */