Changes to m4/doc/m4.texinfo,v

[Eric Blake]

CVSROOT:        /sources/m4
Module name:    m4
Changes by:     Eric Blake <ericb>      06/10/21 22:15:52

Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.70
retrieving revision 1.71
diff -u -b -r1.70 -r1.71
--- doc/m4.texinfo      21 Oct 2006 15:23:56 -0000      1.70
+++ doc/m4.texinfo      21 Oct 2006 22:15:52 -0000      1.71
@@ -260,6 +260,7 @@
 * Esyscmd::                     Reading the output of commands
 * Sysval::                      Exit status
 * Mkstemp::                     Making temporary files
+* Mkdtemp::                     Making temporary directories
 
 Miscellaneous builtin macros
 
@@ -646,11 +647,11 @@
 
 @item --safer
 Cripple the builtins @code{maketemp}, @code{mkstemp} (@pxref{Mkstemp}),
address@hidden (@pxref{Debugfile}), @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.
address@hidden (@pxref{Mkdtemp}), @code{debugfile} (@pxref{Debugfile}),
address@hidden (@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
 
 @node Dynamic loading features
@@ -2078,6 +2079,7 @@
 
 The expansion of @code{renamesyms} is void.
 The macro @code{renamesyms} is recognized only with parameters.
+This macro was added in M4 2.0.
 @end deffn
 
 Here is an example that performs the same renaming as the
@@ -2302,6 +2304,7 @@
 
 When given arguments, @code{m4symbols} returns the sorted subset of the
 @var{names} currently defined, and silently ignores the rest.
+This macro was added in M4 2.0.
 @end deffn
 
 @example
@@ -5147,6 +5150,7 @@
 * Esyscmd::                     Reading the output of commands
 * Sysval::                      Exit status
 * Mkstemp::                     Making temporary files
+* Mkdtemp::                     Making temporary directories
 @end menu
 
 @node Platform macros
@@ -5403,6 +5407,81 @@
 @result{}foo??????
 @end example
 
address@hidden Mkdtemp
address@hidden Making temporary directories
+
address@hidden temporary directory
address@hidden directories, temporary
address@hidden @acronym{GNU} extensions
+Commands specified to @code{syscmd} or @code{esyscmd} might need a
+temporary directory, for holding multiple temporary files; such a
+directory can be created with @code{mkdtemp}:
+
address@hidden {Builtin (gnu)} mkdtemp (@var{template})
+Expands to a name of a new, empty directory, made from the string
address@hidden, which should end with the string @samp{XXXXXX}.  The six
address@hidden characters are then replaced with random characters matching
+the regular expression @samp{[a-zA-Z0-9._-]}, in order to make the name
+unique.  If fewer than six @samp{X} characters are found at the end of
address@hidden, the result will be longer than the template.  The
+created directory will have access permissions as if by @kbd{chmod
+=rwx,go=}, meaning that the current umask of the @code{m4} process is
+taken into account, and at most only the current user can read, write,
+and search the directory.
+
+The expansion is void and an error issued if a temporary directory could
+not be created.
+
+When the @option{--safer} option (@pxref{Operation modes, Invoking m4})
+is in effect, @code{mkdtemp} results in an error, since otherwise an
+input file could perform a mild denial-of-service attack by filling up a
+disk with multiple directories.
+
+The macro @code{mkdtemp} is recognized only with parameters.
+This macro was added in M4 2.0.
address@hidden deffn
+
+If you try this next example, you will most likely get different output
+for the directory names, since the replacement characters are randomly
+chosen:
+
address@hidden ignore
address@hidden
+$ @kbd{m4}
+mkdtemp(`/tmp/fooXXXXXX')
address@hidden/tmp/foo2h89Vo
+mkdtemp(`dir)
address@hidden
address@hidden example
+
address@hidden options: --safer
address@hidden status: 1
address@hidden
+$ @kbd{m4 --safer}
+mkdtemp(`/tmp/fooXXXXXX')
address@hidden:stdin:1: mkdtemp: disabled by --safer
address@hidden
address@hidden example
+
+Multiple calls with the same template will generate multiple
+directories.
+
address@hidden
+$ @kbd{m4}
+syscmd(`echo foo??????')dnl
address@hidden
+define(`dir1', mkdtemp(`fooXXXXXX'))dnl
+ifelse(esyscmd(`echo foo??????'), `foo??????', `no dir', `created')
address@hidden
+define(`dir2', mkdtemp(`fooXXXXXX'))dnl
+ifelse(dir1, dir2, `same', `different directories')
address@hidden directories
+syscmd(`rmdir 'dir1 dir2)
address@hidden
+sysval
address@hidden
address@hidden example
+
 @node Miscellaneous
 @chapter Miscellaneous builtin macros