lib/system-quote.h

   1 /* Quoting for a system command.
   2    Copyright (C) 2001-2012 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 <http://www.gnu.org/licenses/>.  */
  17
  18 #ifndef _SYSTEM_QUOTE_H
  19 #define _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 #include <stddef.h>
  35
  36 #ifdef __cplusplus
  37 extern "C" {
  38 #endif
  39
  40 /* Identifier for the kind of interpreter of the command.  */
  41 enum system_command_interpreter
  42 {
  43   /* The interpreter used by the system() and popen() functions.
  44      This is equivalent to SCI_POSIX_SH on Unix platforms and
  45      SCI_WINDOWS_CMD on native Windows platforms.  */
  46   SCI_SYSTEM                    = 0
  47   /* The POSIX /bin/sh.  */
  48   , SCI_POSIX_SH                = 1
  49 #if (defined _WIN32 || defined __WIN32__) && ! defined __CYGWIN__
  50   /* The native Windows CreateProcess() function.  */
  51   , SCI_WINDOWS_CREATEPROCESS   = 2
  52   /* The native Windows cmd.exe interpreter.  */
  53   , SCI_WINDOWS_CMD             = 3
  54 #endif
  55 };
  56
  57 /* Returns the number of bytes needed for the quoted string.  */
  58 extern size_t
  59        system_quote_length (enum system_command_interpreter interpreter,
  60                             const char *string);
  61
  62 /* Copies the quoted string to p and returns the incremented p.
  63    There must be room for system_quote_length (string) + 1 bytes at p.  */
  64 extern char *
  65        system_quote_copy (char *p,
  66                           enum system_command_interpreter interpreter,
  67                           const char *string);
  68
  69 /* Returns the freshly allocated quoted string.  */
  70 extern char *
  71        system_quote (enum system_command_interpreter interpreter,
  72                      const char *string);
  73
  74 /* Returns a freshly allocated string containing all argument strings, quoted,
  75    separated through spaces.  */
  76 extern char *
  77        system_quote_argv (enum system_command_interpreter interpreter,
  78                           char * const *argv);
  79
  80 #ifdef __cplusplus
  81 }
  82 #endif
  83
  84 #endif /* _SYSTEM_QUOTE_H */