system-quote.h

   1 /* Quoting for a system command.
   2    Copyright (C) 2001-2022 Free Software Foundation, Inc.
   3    Written by Bruno Haible <bruno@clisp.org>, 2012.
   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 LIBQUOTE_SYSTEM_QUOTE_H
  19 #define LIBQUOTE_SYSTEM_QUOTE_H
  20
  21 /* When passing a command the system's command interpreter, we must quote the
  22    program name and arguments, since
  23      - Unix shells interpret characters like " ", "'", "<", ">", "$", '*', '?'
  24        etc. in a special way,
  25      - Windows CreateProcess() interprets characters like ' ', '\t', '\\', '"'
  26        etc. (but not '<' and '>') in a special way,
  27      - Windows cmd.exe also interprets characters like '<', '>', '&', '%', etc.
  28        in a special way.  Note that it is impossible to pass arguments that
  29        contain newlines or carriage return characters to programs through
  30        cmd.exe.
  31      - Windows programs usually perform wildcard expansion when they receive
  32        arguments that contain unquoted '*', '?' characters.
  33
  34   With this module, you can build a command that will invoke a program with
  35   specific strings as arguments.
  36
  37   Note: If you want wildcard expansion to happen, you have to first do wildcard
  38   expansion through the 'glob' module, then quote the resulting strings through
  39   this module, and then invoke the system's command interpreter.
  40
  41   Limitations:
  42     - When invoking native Windows programs on Windows Vista or newer,
  43       wildcard expansion will occur in the invoked program nevertheless.
  44     - On native Windows, for SCI_SYSTEM and SCI_WINDOWS_CMD, newlines and
  45       carriage return characters are not supported.  Their undesired effect
  46       is to truncate the entire command line.  */
  47
  48 #include <stdlib.h>
  49
  50 #ifdef __cplusplus
  51 extern "C" {
  52 #endif
  53
  54 /* Identifier for the kind of interpreter of the command.  */
  55 enum system_command_interpreter
  56 {
  57   /* The interpreter used by the system() and popen() functions.
  58      This is equivalent to SCI_POSIX_SH on Unix platforms and
  59      SCI_WINDOWS_CMD on native Windows platforms.  */
  60   SCI_SYSTEM                    = 0
  61   /* The POSIX /bin/sh.  */
  62   , SCI_POSIX_SH                = 1
  63 #if defined (_WIN32) && !defined (__CYGWIN__)
  64   /* The native Windows CreateProcess() function.  */
  65   , SCI_WINDOWS_CREATEPROCESS   = 2
  66   /* The native Windows cmd.exe interpreter.  */
  67   , SCI_WINDOWS_CMD             = 3
  68 #endif
  69 };
  70
  71 /* Returns the number of bytes needed for the quoted string.  */
  72 extern size_t system_quote_length (enum system_command_interpreter interpreter,
  73                                    const char *string);
  74
  75 /* Copies the quoted string to p and returns the incremented p.
  76    There must be room for system_quote_length (string) + 1 bytes at p.  */
  77 extern char *system_quote_copy (char *restrict p,
  78                                 enum system_command_interpreter interpreter,
  79                                 const char *string);
  80
  81 /* Returns the freshly allocated quoted string.  */
  82 extern char *system_quote (enum system_command_interpreter interpreter,
  83                            const char *string);
  84 //TODO  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE
  85 //  _GL_ATTRIBUTE_RETURNS_NONNULL;
  86
  87 /* Returns a freshly allocated string containing all argument strings, quoted,
  88    separated through spaces.  */
  89 extern char *system_quote_argv (enum system_command_interpreter interpreter,
  90                                 char *const *argv);
  91 //TODO  _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE
  92 //  _GL_ATTRIBUTE_RETURNS_NONNULL;
  93
  94 #ifdef __cplusplus
  95 }
  96 #endif
  97
  98 #endif /* LIBQUOTE_SYSTEM_QUOTE_H */