From fa7732e09244f5cb5c11e40636a08ea2f31e330c Mon Sep 17 00:00:00 2001 From: "H. Peter Anvin (Intel)" Date: Sat, 27 Jun 2020 16:40:52 -0700 Subject: doc: editorial cleanups Clean up the language of a few sections, add a few examples, and better document %pragma limit. Signed-off-by: H. Peter Anvin (Intel) --- doc/nasmdoc.src | 52 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 37 insertions(+), 15 deletions(-) diff --git a/doc/nasmdoc.src b/doc/nasmdoc.src index 8d815396..d19f24c7 100644 --- a/doc/nasmdoc.src +++ b/doc/nasmdoc.src @@ -923,10 +923,13 @@ shown in \k{opt-pragma} is the same as running this: \S{opt-limit} The \i\c{--limit-X} Option -This option allows user to setup various maximum values for these: +This option allows user to setup various maximum values after which +NASM will terminate with a fatal error rather than consume arbitrary +amount of compute time. Each limit can be set to a positive number or +\c{unlimited}. \b\c{--limit-passes}: Number of maximum allowed passes. Default is -effectively unlimited. +\c{unlimited}. \b\c{--limit-stalled-passes}: Maximum number of allowed unfinished passes. Default is 1000. @@ -946,13 +949,18 @@ under \c{%rep}. Default is 1000000. \b\c{--limit-eval}: This number sets the boundary condition of allowed expression length. Default is 8192 on most systems. -\b\c{--limit-lines}: Total number of source lines as allowed to be +\b\c{--limit-lines}: Total number of source lines allowed to be processed. Default is 2000000000. -In example, running this limits the maximum line count to be 1000. +For example, set the maximum line count to 1000: \c nasm --limit-lines 1000 +Limits can also be set via the directive \c{%pragma limit}, for +example: + +\c %pragma limit lines 1000 + \S{opt-keep-all} The \i\c{--keep-all} Option @@ -2492,23 +2500,37 @@ includes backwards compatibility aliases defined by NASM itself. To disable aliases without undefining them, use the \c{%aliases off} directive. -To check whether an alias is defined, use \c{%ifdefalias}. +To check whether an alias is defined, regardless of the existence of +the aliased macro, use \c{%ifdefalias}. -This +For example: +\c %defalias OLD NEW +\c ; OLD and NEW both undefined +\c %define NEW 123 +\c ; OLD and NEW both 123 +\c %undef OLD +\c ; OLD and NEW both undefined +\c %define OLD 456 +\c ; OLD and NEW both 456 +\c %undefalias OLD +\c ; OLD undefined, NEW defined to 456 \S{cond-comma} \i{Conditional Comma Operator}: \i\c{%,} -As of version 2.15, NASM has conditional comma operator \c{%,} that expands to a -comma unless followed by a null expansion, which allows suppressing the comma before an -empty argument. For example, all the expressions below are valid: +As of version 2.15, NASM has a conditional comma operator \c{%,} that +expands to a comma \e{unless} followed by a null expansion, which +allows suppressing the comma before an empty argument. This is +especially useful with greedy single-line macros. + +For example, all the expressions below are valid: \c %define greedy(a,b,c+) a + 66 %, b * 3 %, c \c -\c db greedy(1,2) -\c db greedy(1,2,3) -\c db greedy(1,2,3,4) -\c db greedy(1,2,3,4,5) +\c db greedy(1,2) ; db 1 + 66, 2 * 3 +\c db greedy(1,2,3) ; db 1 + 66, 2 * 3, 3 +\c db greedy(1,2,3,4) ; db 1 + 66, 2 * 3, 3, 4 +\c db greedy(1,2,3,4,5) ; db 1 + 66, 2 * 3, 3, 4, 5 \H{strlen} \i{String Manipulation in Macros} @@ -3402,8 +3424,8 @@ infinite loop in the preprocessor, which (on multitasking or multi-user systems) would typically cause all the system memory to be gradually used up and other applications to start crashing. -Note a maximum repeat count is limited by 62 bit number, though it -is hardly possible that you ever need anything bigger. +Note the maximum repeat count is limited to the value specified by the +\c{--limit-rep} option or \c{%pragma limit rep}, see \k{opt-limit}. \H{files} Source Files and Dependencies -- cgit v1.2.1