Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/09/15 03:37:54

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.43
retrieving revision 1.44
diff -u -b -r1.43 -r1.44
--- doc/m4.texinfo      7 Sep 2006 23:53:04 -0000       1.43
+++ doc/m4.texinfo      15 Sep 2006 03:37:53 -0000      1.44
@@ -463,6 +463,14 @@
 When this option is not given, @acronym{GNU} M4 uses emacs compatible
 regular expressions.  @xref{Changeresyntax}, for more details on the
 format and meaning of @var{RESYNTAX-SPEC}.
+
address@hidden --safer
+Cripple the builtins @code{maketemp} (@pxref{Maketemp}),
address@hidden (@pxref{Debug Output}), @code{syscmd} (@pxref{Syscmd}),
+and @code{esyscmd} (@pxref{Esyscmd}), since they can perform potentially
+unsafe actions.  An attempt to use these macros will result in an error.
+This option is intended to make it safer to preprocess an input file of
+unknown origin.
 @end table
 
 On platforms that support dynamic libraries, there are some options
@@ -2699,13 +2707,30 @@
 @samp{-o} option to @code{m4}, or with the builtin macro @code{debugfile}:
 
 @deffn {Builtin (gnu)} debugfile
address@hidden {Builtin (gnu)} debugfile @w{(opt @var{filename})}
-Send all further debug and trace output to @var{filename}.  If
address@hidden is empty, debug and trace output are discarded and if
address@hidden is called without any arguments, debug and trace output
-are sent to the standard error output.
address@hidden {Builtin (gnu)} debugfile @w{(opt @var{file})}
+Send all further debug and trace output to @var{file}, opened in append
+mode.  If @var{file} is the empty string, debug and trace output are
+discarded and if @code{debugfile} is called without any arguments, debug
+and trace output are sent to the standard error output.
+
+When the @option{--safer} option (@pxref{Invoking m4}) is in effect,
address@hidden must be empty or omitted, since otherwise an input file
+could cause the modification of arbitrary files.
 @end deffn
 
address@hidden options: --safer
address@hidden status: 1
address@hidden
+$ @kbd{m4 --safer}
+debugfile(`foo')
address@hidden:stdin:1: debugfile: disabled by --safer
address@hidden
+debugfile()
address@hidden
+debugfile
address@hidden
address@hidden example
+
 @node Input Control
 @chapter Input control
 
@@ -2859,7 +2884,6 @@
 @result{}# Not a COMMENT anymore
 @end example
 
-
 @node Changeresyntax
 @section Changing the regular expression syntax
 
@@ -2940,7 +2964,6 @@
 @xref{posix-egrep regular expression syntax}, for details.
 @end table
 
-
 @node Changesyntax
 @section Changing the lexical structure of the input
 
@@ -3209,8 +3232,6 @@
 @result{}TEST
 @end example
 
-
-
 There is obviously an overlap with @code{changecom} and
 @code{changequote}.  Comment delimiters and quotes can now be defined in
 two different ways.  To avoid incompatibilities, if the quotes are set
@@ -3280,10 +3301,6 @@
 Debugging output continue to use @kbd{(}, @kbd{,} and @kbd{)} to show
 macro calls.
 
-
-
-
-
 @node M4wrap
 @section Saving text until end of input
 
@@ -3784,7 +3801,6 @@
 @result{}load,gnu,m4
 @end example
 
-
 @node Load
 @section Loading additional modules
 
@@ -3811,7 +3827,6 @@
 @result{}mymodule,load,gnu,m4
 @end example
 
-
 @node Unload
 @section Removing loaded modules
 
@@ -3825,7 +3840,6 @@
 The macro @code{unload} is recognized only with parameters.
 @end deffn
 
-
 @node Standard Modules
 @section Standard bundled modules
 
@@ -3883,7 +3897,6 @@
 
 @end table
 
-
 @node Text handling
 @chapter Macros for text handling
 
@@ -4161,7 +4174,6 @@
 @result{}bab
 @end example
 
-
 @node Format
 @section Formatting strings (printf-like)
 
@@ -4435,6 +4447,10 @@
 The default standard input, output and error of @var{shell-command} are
 the same as those of @code{m4}.
 
+When the @option{--safer} option (@pxref{Invoking m4}) is in effect,
address@hidden results in an error, since otherwise an input file could
+execute arbitrary code.
+
 The builtin macro @code{syscmd} is recognized only when given arguments.
 @end deffn
 
@@ -4449,7 +4465,14 @@
 Note how the expansion of @code{syscmd} keeps the trailing newline of
 the command, as well as using the newline that appeared after the macro.
 
-The builtin macro @code{syscmd} is recognized only when given arguments.
address@hidden options: --safer
address@hidden status: 1
address@hidden
+$ @kbd{m4 --safer}
+syscmd(`echo hi')
address@hidden:stdin:1: syscmd: disabled by --safer
address@hidden
address@hidden example
 
 @node Esyscmd
 @section Reading the output of commands
@@ -4466,7 +4489,6 @@
 is not a part of the expansion: it will appear along with the error
 output of @code{m4}.
 
-
 @example
 define(`foo', `FOO')
 @result{}
@@ -4478,10 +4500,23 @@
 Note how the expansion of @code{esyscmd} keeps the trailing newline of
 the command, as well as using the newline that appeared after the macro.
 
+When the @option{--safer} option (@pxref{Invoking m4}) is in effect,
address@hidden results in an error, since otherwise an input file could
+execute arbitrary code.
+
 The builtin macro @code{esyscmd} is recognized only when given
 arguments.
 @end deffn
 
address@hidden options: --safer
address@hidden status: 1
address@hidden
+$ @kbd{m4 --safer}
+esyscmd(`echo hi')
address@hidden:stdin:1: esyscmd: disabled by --safer
address@hidden
address@hidden example
+
 @node Sysval
 @section Exit status
 
@@ -4506,6 +4541,22 @@
 @result{}0
 @end example
 
+When the @option{--safer} option (@pxref{Invoking m4}) is in effect,
address@hidden will always remain at its default value of zero.
+
address@hidden options: --safer
address@hidden status: 1
address@hidden
+$ @kbd{m4 --safer}
+sysval
address@hidden
+syscmd(`false')
address@hidden:stdin:2: syscmd: disabled by --safer
address@hidden
+sysval
address@hidden
address@hidden example
+
 @node Maketemp
 @section Making temporary files
 
@@ -4528,10 +4579,24 @@
 @result{}/tmp/fooa07346
 @end example
 
+When the @option{--safer} option (@pxref{Invoking m4}) is in effect,
address@hidden results in an error, since otherwise an input file could
+perform a mild denial-of-service attack by filling up a disk with
+multiple empty files.
+
 The builtin macro @code{maketemp} is recognized only when given
 arguments.
 @end deffn
 
address@hidden options: --safer
address@hidden status: 1
address@hidden
+$ @kbd{m4 --safer}
+maketemp(`/tmp/fooXXXXXX')
address@hidden:stdin:1: maketemp: disabled by --safer
address@hidden
address@hidden example
+
 @node Miscellaneous
 @chapter Miscellaneous builtin macros
 
@@ -5020,7 +5085,6 @@
 define the macro @code{__windows__}, which expands to the empty string.
 @end itemize
 
-
 @node  Experiments
 @section Experimental features in @acronym{GNU} M4
 
@@ -5041,7 +5105,6 @@
 The implementation does not seem to slow down @code{m4}, more likely the
 contrary.
 
-
 @section Multiple precision arithmetic
 
 Another experimental feature, which would improve @code{m4} usefulness,
@@ -5057,7 +5120,6 @@
 if you want this feature compiled in.  The current implementation is
 unproven and might go away.  Do not count on it yet.
 
-
 @node Answers
 @chapter Correct version of some examples