m4-commit
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Changes to m4/doc/m4.texinfo,v [branch-1_4]


From: Eric Blake
Subject: Changes to m4/doc/m4.texinfo,v [branch-1_4]
Date: Fri, 30 Jun 2006 15:06:56 +0000

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, address@hidden
 @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.
 
address@hidden Arithmetic, UNIX commands, Text handling, Top
address@hidden 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.
 
address@hidden UNIX commands, Miscellaneous, Arithmetic, Top
address@hidden Running UNIX commands
address@hidden Shell commands, Miscellaneous, Arithmetic, Top
address@hidden 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
address@hidden executing shell commands
address@hidden running shell commands
address@hidden shell commands, running
address@hidden 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
address@hidden/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
 
address@hidden Syscmd, Esyscmd, UNIX commands, UNIX commands
address@hidden Platform macros, Syscmd, Shell commands, Shell commands
address@hidden Determining the platform
+
address@hidden 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.
+
address@hidden ignore
address@hidden
+__gnu__
+__unix__
+unix
+__windows__
+windows
address@hidden example
+
address@hidden gnu
+When GNU extensions are in effect (that is, when you did not use the
address@hidden option), GNU @code{m4} will define the macro @code{__gnu__} to
+expand to the empty string.
+
address@hidden
+__gnu__
address@hidden
+ifdef(`__gnu__', `Extensions are active')
address@hidden are active
address@hidden example
+
address@hidden unix
address@hidden 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.
+
address@hidden windows
+On native Windows systems, GNU @code{m4} without the @samp{-G} option
+will define the macro @code{__windows__}, otherwise the macro
address@hidden  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.
+
address@hidden
+define(`provided', `0')
address@hidden
+ifdef(`__gnu__', `define(`provided', incr(provided))')
address@hidden
+ifdef(`__windows__', `define(`provided', incr(provided))')
address@hidden
+provided
address@hidden
address@hidden example
+
address@hidden 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}.
 
address@hidden
+define(`foo', `FOO')
address@hidden
+syscmd(`echo foo')
address@hidden
address@hidden
address@hidden 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.
 
address@hidden Esyscmd, Sysval, Syscmd, UNIX commands
address@hidden 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
address@hidden distribution, then:
-
 @example
-define(`vice', `esyscmd(`grep Vice ../COPYING')')
+define(`foo, `FOO')
 @result{}
-vice
address@hidden  Ty Coon, President of Vice
+esyscmd(`echo foo')
address@hidden
 @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.
 
address@hidden Sysval, Maketemp, Esyscmd, UNIX commands
address@hidden 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
address@hidden exit code from shell commands
address@hidden shell commands, exit code from
address@hidden 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
address@hidden
+sysval
address@hidden
 syscmd(`exit 2')
 @result{}
 sysval
@@ -3305,9 +3389,49 @@
 @result{}
 sysval
 @result{}0
+esyscmd(`false')
address@hidden
+ifelse(sysval, `0', `zero', `non-zero')
address@hidden
+esyscmd
address@hidden
+sysval
address@hidden
+esyscmd(`exit 2')
address@hidden
+sysval
address@hidden
+esyscmd(`true')
address@hidden
+sysval
address@hidden
address@hidden example
+
address@hidden 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.
+
address@hidden
+dnl This test assumes kill is a shell builtin, and that signals are
+dnl recognizable.
+ifdef(`__unix__', , `m4exit(`77')')dnl
+syscmd(`kill -1 $$')
address@hidden
+sysval
address@hidden
+esyscmd(`kill -9 $$')
address@hidden
+sysval
address@hidden
 @end example
 
address@hidden Maketemp,  , Sysval, UNIX commands
address@hidden 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.
 
address@hidden Miscellaneous, Frozen files, UNIX commands, Top
address@hidden 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.
-
address@hidden
address@hidden gnu
-GNU @code{m4} without @samp{-G} option will define the macro
address@hidden to expand to the empty string.
-
address@hidden 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




reply via email to

[Prev in Thread] Current Thread [Next in Thread]