lib/system-quote.h

   1 /* Quoting for a system command.
   2    Copyright (C) 2001-2024 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 _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   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
  49 /* This file uses _GL_ATTRIBUTE_MALLOC, _GL_ATTRIBUTE_RETURNS_NONNULL.  */
  50 #if !_GL_CONFIG_H_INCLUDED
  51  #error "Please include config.h first."
  52 #endif
  53
  54 #include <stdlib.h>
  55
  56 #ifdef __cplusplus
  57 extern "C" {
  58 #endif
  59
  60 /* Identifier for the kind of interpreter of the command.  */
  61 enum system_command_interpreter
  62 {
  63   /* The interpreter used by the system() and popen() functions.
  64      This is equivalent to SCI_POSIX_SH on Unix platforms and
  65      SCI_WINDOWS_CMD on native Windows platforms.  */
  66   SCI_SYSTEM                    = 0
  67   /* The POSIX /bin/sh.  */
  68   , SCI_POSIX_SH                = 1
  69 #if defined _WIN32 && ! defined __CYGWIN__
  70   /* The native Windows CreateProcess() function.  */
  71   , SCI_WINDOWS_CREATEPROCESS   = 2
  72   /* The native Windows cmd.exe interpreter.  */
  73   , SCI_WINDOWS_CMD             = 3
  74 #endif
  75 };
  76
  77 /* Returns the number of bytes needed for the quoted string.  */
  78 extern size_t
  79        system_quote_length (enum system_command_interpreter interpreter,
  80                             const char *string);
  81
  82 /* Copies the quoted string to p and returns the incremented p.
  83    There must be room for system_quote_length (string) + 1 bytes at p.  */
  84 extern char *
  85        system_quote_copy (char *restrict p,
  86                           enum system_command_interpreter interpreter,
  87                           const char *string);
  88
  89 /* Returns the freshly allocated quoted string.  */
  90 extern char *
  91        system_quote (enum system_command_interpreter interpreter,
  92                      const char *string)
  93   _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE
  94   _GL_ATTRIBUTE_RETURNS_NONNULL;
  95
  96 /* Returns a freshly allocated string containing all argument strings, quoted,
  97    separated through spaces.  */
  98 extern char *
  99        system_quote_argv (enum system_command_interpreter interpreter,
 100                           char * const *argv)
 101   _GL_ATTRIBUTE_MALLOC _GL_ATTRIBUTE_DEALLOC_FREE
 102   _GL_ATTRIBUTE_RETURNS_NONNULL;
 103
 104 #ifdef __cplusplus
 105 }
 106 #endif
 107
 108 #endif /* _SYSTEM_QUOTE_H */