1  /* Quoting for a system command.
       2     Copyright (C) 2001-2023 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 */