CVSROOT: /sources/m4
Module name: m4
Branch: branch-1_4
Changes by: Eric Blake <ericb> 06/06/30 15:06:54
Index: doc/m4.texinfo
===================================================================
RCS file: /sources/m4/m4/doc/m4.texinfo,v
retrieving revision 1.1.1.1.2.27
retrieving revision 1.1.1.1.2.28
diff -u -b -r1.1.1.1.2.27 -r1.1.1.1.2.28
--- doc/m4.texinfo 30 Jun 2006 03:38:49 -0000 1.1.1.1.2.27
+++ doc/m4.texinfo 30 Jun 2006 15:06:53 -0000 1.1.1.1.2.28
@@ -127,7 +127,7 @@
* Text handling:: Macros for text handling
* Arithmetic:: Macros for doing arithmetic
-* UNIX commands:: Macros for running UNIX commands
+* Shell commands:: Macros for running shell commands
* Miscellaneous:: Miscellaneous builtin macros
* Frozen files:: Fast loading of frozen states
@@ -222,8 +222,9 @@
* Incr:: Decrement and increment operators
* Eval:: Evaluating integer expressions
-Running UNIX commands
+Running shell commands
+* Platform macros:: Determining the platform
* Syscmd:: Executing simple commands
* Esyscmd:: Reading the output of commands
* Sysval:: Exit codes
@@ -271,7 +272,7 @@
input to the output, expanding macros as it goes. Macros are either
builtin or user-defined, and can take any number of arguments.
Besides just doing macro expansion, @code{m4} has builtin functions
-for including named files, running UNIX commands, doing integer
+for including named files, running shell commands, doing integer
arithmetic, manipulating text in various ways, recursion, [EMAIL PROTECTED]
@code{m4} can be used either as a front-end to a compiler, or as a
macro processor in its own right.
@@ -2230,7 +2231,7 @@
@comment ignore
@example
-define(a, `errprint(`Hello')')dnl
+define(`a', `errprint(`Hello')')dnl
changeword(`@@\([_a-zA-Z0-9]*\)')
@result{}
@@a
@@ -3007,7 +3008,7 @@
The macro @code{format} is recognized only with parameters.
[EMAIL PROTECTED] Arithmetic, UNIX commands, Text handling, Top
[EMAIL PROTECTED] Arithmetic, Shell commands, Text handling, Top
@chapter Macros for doing arithmetic
@cindex arithmetic
@@ -3193,24 +3194,91 @@
The builtin macro @code{eval} is recognized only when given arguments.
[EMAIL PROTECTED] UNIX commands, Miscellaneous, Arithmetic, Top
[EMAIL PROTECTED] Running UNIX commands
[EMAIL PROTECTED] Shell commands, Miscellaneous, Arithmetic, Top
[EMAIL PROTECTED] Running shell commands
@cindex executing UNIX commands
@cindex running UNIX commands
@cindex UNIX commands, running
@cindex commands, running UNIX
-There are a few builtin macros in @code{m4} that allow you to run UNIX
[EMAIL PROTECTED] executing shell commands
[EMAIL PROTECTED] running shell commands
[EMAIL PROTECTED] shell commands, running
[EMAIL PROTECTED] commands, running shell
+There are a few builtin macros in @code{m4} that allow you to run shell
commands from within @code{m4}.
+Note that the definition of a valid shell command is system dependent.
+On UNIX systems, this is the typical @code{/bin/sh}. But on other
+systems, such as native Windows, the shell has a different syntax of
+commands that it understands. Some examples in this chapter assume
[EMAIL PROTECTED]/bin/sh}, and also demonstrate how to quit early with a known
+exit value if this is not the case.
+
@menu
+* Platform macros:: Determining the platform
* Syscmd:: Executing simple commands
* Esyscmd:: Reading the output of commands
* Sysval:: Exit codes
* Maketemp:: Making names for temporary files
@end menu
[EMAIL PROTECTED] Syscmd, Esyscmd, UNIX commands, UNIX commands
[EMAIL PROTECTED] Platform macros, Syscmd, Shell commands, Shell commands
[EMAIL PROTECTED] Determining the platform
+
[EMAIL PROTECTED] platform macros
+Sometimes it is desirable for an input file to know which
+platform @code{m4} is running on. GNU @code{m4} provides several
+macros that are predefined to expand to the empty string; checking for
+their existence will confirm platform details.
+
[EMAIL PROTECTED] ignore
[EMAIL PROTECTED]
+__gnu__
+__unix__
+unix
+__windows__
+windows
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] gnu
+When GNU extensions are in effect (that is, when you did not use the
[EMAIL PROTECTED] option), GNU @code{m4} will define the macro @code{__gnu__} to
+expand to the empty string.
+
[EMAIL PROTECTED]
+__gnu__
[EMAIL PROTECTED]
+ifdef(`__gnu__', `Extensions are active')
[EMAIL PROTECTED] are active
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] unix
[EMAIL PROTECTED] platform macro
+On UNIX systems, GNU @code{m4} without the @samp{-G} option will define
+the macro @code{__unix__}, otherwise the macro @code{unix}. Both will
+expand to the empty string.
+
[EMAIL PROTECTED] windows
+On native Windows systems, GNU @code{m4} without the @samp{-G} option
+will define the macro @code{__windows__}, otherwise the macro
[EMAIL PROTECTED] Both will expand to the empty string.
+
+If GNU @code{m4} does not provide a platform macro for your system,
+please report that as a bug.
+
[EMAIL PROTECTED]
+define(`provided', `0')
[EMAIL PROTECTED]
+ifdef(`__gnu__', `define(`provided', incr(provided))')
[EMAIL PROTECTED]
+ifdef(`__windows__', `define(`provided', incr(provided))')
[EMAIL PROTECTED]
+provided
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] Syscmd, Esyscmd, Platform macros, Shell commands
@section Executing simple commands
@findex syscmd
@@ -3233,14 +3301,25 @@
The default standard input, output and error of @var{shell-command} are
the same as those of @code{m4}.
[EMAIL PROTECTED]
+define(`foo', `FOO')
[EMAIL PROTECTED]
+syscmd(`echo foo')
[EMAIL PROTECTED]
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
+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.
[EMAIL PROTECTED] Esyscmd, Sysval, Syscmd, UNIX commands
[EMAIL PROTECTED] Esyscmd, Sysval, Syscmd, Shell commands
@section Reading the output of commands
@findex esyscmd
@cindex GNU extensions
-If you want @code{m4} to read the output of a UNIX command, use
+If you want @code{m4} to read the output of a shell command, use
@code{esyscmd}:
@comment ignore
@@ -3258,28 +3337,29 @@
is not a part of the expansion: it will appear along with the error
output of @code{m4}.
-Assume you are positioned into the @file{checks} directory of GNU
[EMAIL PROTECTED] distribution, then:
-
@example
-define(`vice', `esyscmd(`grep Vice ../COPYING')')
+define(`foo, `FOO')
@result{}
-vice
[EMAIL PROTECTED] Ty Coon, President of Vice
+esyscmd(`echo foo')
[EMAIL PROTECTED]
@result{}
@end example
-Note how the expansion of @code{esyscmd} has a trailing newline.
+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.
The builtin macro @code{esyscmd} is recognized only when given
arguments.
[EMAIL PROTECTED] Sysval, Maketemp, Esyscmd, UNIX commands
[EMAIL PROTECTED] Sysval, Maketemp, Esyscmd, Shell commands
@section Exit codes
@cindex exit code from UNIX commands
@cindex UNIX commands, exit code from
@cindex commands, exit code from UNIX
[EMAIL PROTECTED] exit code from shell commands
[EMAIL PROTECTED] shell commands, exit code from
[EMAIL PROTECTED] commands, exit code from shell
@findex sysval
To see whether a shell command succeeded, use @code{sysval}:
@@ -3297,6 +3377,10 @@
@result{}
ifelse(sysval, `0', `zero', `non-zero')
@result{}non-zero
+syscmd
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
syscmd(`exit 2')
@result{}
sysval
@@ -3305,9 +3389,49 @@
@result{}
sysval
@result{}0
+esyscmd(`false')
[EMAIL PROTECTED]
+ifelse(sysval, `0', `zero', `non-zero')
[EMAIL PROTECTED]
+esyscmd
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
+esyscmd(`exit 2')
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
+esyscmd(`true')
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
[EMAIL PROTECTED] example
+
[EMAIL PROTECTED] results in 127 if there was a problem executing the
+command, for example, if the system-imposed argument length is exceeded,
+or if there were not enough resources to fork. It is not possible to
+distinguish between failed execution and successful execution that had
+an exit status of 127.
+
+On UNIX platforms, where it is possible to detect when command execution
+is terminated by a signal, rather than a normal exit, the result is the
+signal number shifted left by eight bits.
+
[EMAIL PROTECTED]
+dnl This test assumes kill is a shell builtin, and that signals are
+dnl recognizable.
+ifdef(`__unix__', , `m4exit(`77')')dnl
+syscmd(`kill -1 $$')
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
+esyscmd(`kill -9 $$')
[EMAIL PROTECTED]
+sysval
[EMAIL PROTECTED]
@end example
[EMAIL PROTECTED] Maketemp, , Sysval, UNIX commands
[EMAIL PROTECTED] Maketemp, , Sysval, Shell commands
@section Making names for temporary files
@cindex temporary filenames
@@ -3344,6 +3468,9 @@
@c This test makes sure maketemp gets testsuite coverage, but is
@c somewhat complex for use in the manual.
@example
+dnl This test assumes /tmp is a valid directory name, which is not true
+dnl for native Windows.
+ifdef(`__unix__', , `m4exit(`77')')dnl
define(`file1', maketemp(`/tmp/fooXXXXXX'))dnl
define(`file2', maketemp(`/tmp/fooXXXXXX'))dnl
ifelse(file1, file2, `same', `different')
@@ -3358,7 +3485,7 @@
The builtin macro @code{maketemp} is recognized only when given
arguments.
[EMAIL PROTECTED] Miscellaneous, Frozen files, UNIX commands, Top
[EMAIL PROTECTED] Miscellaneous, Frozen files, Shell commands, Top
@chapter Miscellaneous builtin macros
This chapter describes various builtins, that do not really belong in
@@ -3884,16 +4011,6 @@
for the GNU @code{m4} user to hang himself! Rescanning hangs may be
avoided through careful programming, a little like for endless loops
in traditional programming languages.
-
[EMAIL PROTECTED]
[EMAIL PROTECTED] gnu
-GNU @code{m4} without @samp{-G} option will define the macro
[EMAIL PROTECTED] to expand to the empty string.
-
[EMAIL PROTECTED] unix
-On UNIX systems, GNU @code{m4} without the @samp{-G} option will define
-the macro @code{__unix__}, otherwise the macro @code{unix}. Both will
-expand to the empty string.
@end itemize
@node Concept index, Macro index, Compatibility, Top
