New module 'system-quote'.

[gnulib.git] / lib / system-quote.h

diff --git a/lib/system-quote.h b/lib/system-quote.h
new file mode 100644 (file)
index 0000000..c2c50c5
--- /dev/null
+++ b/lib/system-quote.h
@@ -0,0 +1,82 @@
+/* Quoting for a system command.
+   Copyright (C) 2001-2012 Free Software Foundation, Inc.
+   Written by Bruno Haible <bruno@clisp.org>, 2012.
+
+   This program is free software: you can redistribute it and/or modify
+   it under the terms of the GNU General Public License as published by
+   the Free Software Foundation; either version 3 of the License, or
+   (at your option) any later version.
+
+   This program is distributed in the hope that it will be useful,
+   but WITHOUT ANY WARRANTY; without even the implied warranty of
+   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+   GNU General Public License for more details.
+
+   You should have received a copy of the GNU General Public License
+   along with this program.  If not, see <http://www.gnu.org/licenses/>.  */
+
+#ifndef _SYSTEM_QUOTE_H
+#define _SYSTEM_QUOTE_H
+
+/* When passing a command the system's command interpreter, we must quote the
+   program name and arguments, since
+     - Unix shells interpret characters like " ", "'", "<", ">", "$" etc. in a
+       special way,
+     - Windows CreateProcess() interprets characters like ' ', '\t', '\\', '"'
+       etc. (but not '<' and '>') in a special way,
+     - Windows cmd.exe also interprets characters like '<', '>', '&', '%', etc.
+       in a special way.  Note that it is impossible to pass arguments that
+       contain newlines or carriage return characters to programs through
+       cmd.exe.  */
+
+#include <stddef.h>
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/* Identifier for the kind of interpreter of the command.  */
+enum system_command_interpreter
+{
+  /* The interpreter used by the system() and popen() functions.
+     This is equivalent to SCI_POSIX_SH on Unix platforms and
+     SCI_WINDOWS_CMD on native Windows platforms.  */
+  SCI_SYSTEM                    = 0
+  /* The POSIX /bin/sh.  */
+  , SCI_POSIX_SH                = 1
+#if (defined _WIN32 || defined __WIN32__) && ! defined __CYGWIN__
+  /* The native Windows CreateProcess() function.  */
+  , SCI_WINDOWS_CREATEPROCESS   = 2
+  /* The native Windows cmd.exe interpreter.  */
+  , SCI_WINDOWS_CMD             = 3
+#endif
+};
+
+/* Returns the number of bytes needed for the quoted string.  */
+extern size_t
+       system_quote_length (enum system_command_interpreter interpreter,
+                            const char *string);
+
+/* Copies the quoted string to p and returns the incremented p.
+   There must be room for shell_quote_length (string) + 1 bytes at p.  */
+extern char *
+       system_quote_copy (char *p,
+                          enum system_command_interpreter interpreter,
+                          const char *string);
+
+/* Returns the freshly allocated quoted string.  */
+extern char *
+       system_quote (enum system_command_interpreter interpreter,
+                     const char *string);
+
+/* Returns a freshly allocated string containing all argument strings, quoted,
+   separated through spaces.  */
+extern char *
+       system_quote_argv (enum system_command_interpreter interpreter,
+                          char * const *argv);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* _SYSTEM_QUOTE_H */