NEWS.stable: update

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

diff --git a/lib/system-quote.h b/lib/system-quote.h
index c2c50c5..e078802 100644 (file)
--- a/lib/system-quote.h
+++ b/lib/system-quote.h
@@ -1,5 +1,5 @@
 /* Quoting for a system command.
-   Copyright (C) 2001-2012 Free Software Foundation, Inc.
+   Copyright (C) 2001-2014 Free Software Foundation, Inc.
    Written by Bruno Haible <bruno@clisp.org>, 2012.
 
    This program is free software: you can redistribute it and/or modify
@@ -20,14 +20,31 @@
 
 /* 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,
+     - 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.  */
+       cmd.exe.
+     - Windows programs usually perform wildcard expansion when they receive
+       arguments that contain unquoted '*', '?' characters.
+
+  With this module, you can build a command that will invoke a program with
+  specific strings as arguments.
+
+  Note: If you want wildcard expansion to happen, you have to first do wildcard
+  expansion through the 'glob' module, then quote the resulting strings through
+  this module, and then invoke the system's command interpreter.
+
+  Limitations:
+    - When invoking native Windows programs on Windows Vista or newer,
+      wildcard expansion will occur in the invoked program nevertheless.
+    - On native Windows, for SCI_SYSTEM and SCI_WINDOWS_CMD, newlines and
+      carriage return characters are not supported.  Their undesired effect
+      is to truncate the entire command line.
+ */
 
 #include <stddef.h>
 
@@ -58,7 +75,7 @@ extern size_t
                             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.  */
+   There must be room for system_quote_length (string) + 1 bytes at p.  */
 extern char *
        system_quote_copy (char *p,
                           enum system_command_interpreter interpreter,