logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

m4.1p (24299B)


  1. '\" et
  2. .TH M4 "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. m4 \(em macro processor
  12. .SH SYNOPSIS
  13. .LP
  14. .nf
  15. m4 \fB[\fR-s\fB] [\fR-D \fIname\fB[\fR=\fIval\fB]]\fR...\fB [\fR-U \fIname\fB]\fR... \fIfile\fR...
  16. .fi
  17. .SH DESCRIPTION
  18. The
  19. .IR m4
  20. utility is a macro processor that shall read one or more text files,
  21. process them according to their included macro statements, and write
  22. the results to standard output.
  23. .SH OPTIONS
  24. The
  25. .IR m4
  26. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  27. .IR "Section 12.2" ", " "Utility Syntax Guidelines",
  28. except that the order of the
  29. .BR \-D
  30. and
  31. .BR \-U
  32. options shall be significant, and options can be interspersed with
  33. operands.
  34. .P
  35. The following options shall be supported:
  36. .IP "\fB\-s\fP" 10
  37. Enable line synchronization output for the
  38. .IR c99
  39. preprocessor phase (that is,
  40. .BR #line
  41. directives).
  42. .IP "\fB\-D\ \fIname\fB[\fR=\fIval\fB]\fR" 10
  43. .br
  44. Define
  45. .IR name
  46. to
  47. .IR val
  48. or to null if =\c
  49. .IR val
  50. is omitted.
  51. .IP "\fB\-U\ \fIname\fR" 10
  52. Undefine
  53. .IR name .
  54. .SH OPERANDS
  55. The following operand shall be supported:
  56. .IP "\fIfile\fR" 10
  57. A pathname of a text file to be processed. If no
  58. .IR file
  59. is given, or if it is
  60. .BR '\-' ,
  61. the standard input shall be read.
  62. .SH STDIN
  63. The standard input shall be a text file that is used if no
  64. .IR file
  65. operand is given, or if it is
  66. .BR '\-' .
  67. .SH "INPUT FILES"
  68. The input file named by the
  69. .IR file
  70. operand shall be a text file.
  71. .SH "ENVIRONMENT VARIABLES"
  72. The following environment variables shall affect the execution of
  73. .IR m4 :
  74. .IP "\fILANG\fP" 10
  75. Provide a default value for the internationalization variables that are
  76. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  77. .IR "Section 8.2" ", " "Internationalization Variables"
  78. for the precedence of internationalization variables used to determine
  79. the values of locale categories.)
  80. .IP "\fILC_ALL\fP" 10
  81. If set to a non-empty string value, override the values of all the
  82. other internationalization variables.
  83. .IP "\fILC_CTYPE\fP" 10
  84. Determine the locale for the interpretation of sequences of bytes of
  85. text data as characters (for example, single-byte as opposed to
  86. multi-byte characters in arguments and input files).
  87. .IP "\fILC_MESSAGES\fP" 10
  88. .br
  89. Determine the locale that should be used to affect the format and
  90. contents of diagnostic messages written to standard error.
  91. .IP "\fINLSPATH\fP" 10
  92. Determine the location of message catalogs for the processing of
  93. .IR LC_MESSAGES .
  94. .SH "ASYNCHRONOUS EVENTS"
  95. Default.
  96. .SH STDOUT
  97. The standard output shall be the same as the input files, after being
  98. processed for macro expansion.
  99. .SH STDERR
  100. The standard error shall be used to display strings with the
  101. .BR errprint
  102. macro, macro tracing enabled by the
  103. .BR traceon
  104. macro, the defined text for macros written by the
  105. .BR dumpdef
  106. macro, or for diagnostic messages.
  107. .SH "OUTPUT FILES"
  108. None.
  109. .SH "EXTENDED DESCRIPTION"
  110. The
  111. .IR m4
  112. utility shall compare each token from the input against the set of
  113. built-in and user-defined macros. If the token matches the name of a
  114. macro, then the token shall be replaced by the macro's defining text, if
  115. any, and rescanned for matching macro names. Once no portion of the
  116. token matches the name of a macro, it shall be written to standard
  117. output. Macros may have arguments, in which case the arguments shall
  118. be substituted into the defining text before it is rescanned.
  119. .P
  120. Macro calls have the form:
  121. .sp
  122. .RS 4
  123. .nf
  124. \fIname\fR(\fIarg1\fR, \fIarg2\fR, ..., \fIargn\fR)
  125. .fi
  126. .P
  127. .RE
  128. .P
  129. Macro names shall consist of letters, digits, and underscores, where
  130. the first character is not a digit. Tokens not of this form shall not
  131. be treated as macros.
  132. .P
  133. The application shall ensure that the
  134. <left-parenthesis>
  135. immediately follows the name of the macro. If a token matching the name
  136. of a macro is not followed by a
  137. <left-parenthesis>,
  138. it is handled as a use of that macro without arguments.
  139. .P
  140. If a macro name is followed by a
  141. <left-parenthesis>,
  142. its arguments are the
  143. <comma>-separated
  144. tokens between the
  145. <left-parenthesis>
  146. and the matching
  147. <right-parenthesis>.
  148. Unquoted white-space characters preceding each argument shall be
  149. ignored. All other characters, including trailing white-space characters,
  150. are retained.
  151. <comma>
  152. characters enclosed between
  153. <left-parenthesis>
  154. and
  155. <right-parenthesis>
  156. characters do not delimit arguments.
  157. .P
  158. Arguments are positionally defined and referenced. The string
  159. .BR \(dq$1\(dq
  160. in the defining text shall be replaced by the first argument. Systems
  161. shall support at least nine arguments; only the first nine can be
  162. referenced, using the strings
  163. .BR \(dq$1\(dq
  164. to
  165. .BR \(dq$9\(dq ,
  166. inclusive. The string
  167. .BR \(dq$0\(dq
  168. is replaced with the name of the macro. The string
  169. .BR \(dq$#\(dq
  170. is replaced by the number of arguments as a string. The string
  171. .BR \(dq$*\(dq
  172. is replaced by a list of all of the arguments, separated by
  173. <comma>
  174. characters. The string
  175. .BR \(dq$@\(dq
  176. is replaced by a list of all of the arguments separated by
  177. <comma>
  178. characters, and each argument is quoted using the current left and right
  179. quoting strings. The string
  180. .BR \(dq${\(dq
  181. produces unspecified behavior.
  182. .P
  183. If fewer arguments are supplied than are in the macro definition, the
  184. omitted arguments are taken to be null. It is not an error if more
  185. arguments are supplied than are in the macro definition.
  186. .P
  187. No special meaning is given to any characters enclosed between matching
  188. left and right quoting strings, but the quoting strings are themselves
  189. discarded. By default, the left quoting string consists of a grave accent
  190. (backquote) and the right quoting string consists of an acute accent
  191. (single-quote); see also the
  192. .BR changequote
  193. macro.
  194. .P
  195. Comments are written but not scanned for matching macro names; by
  196. default, the begin-comment string consists of the
  197. <number-sign>
  198. character and the end-comment string consists of a
  199. <newline>.
  200. See also the
  201. .BR changecom
  202. and
  203. .BR dnl
  204. macros.
  205. .P
  206. The
  207. .IR m4
  208. utility shall make available the following built-in macros. They can be
  209. redefined, but once this is done the original meaning is lost. Their
  210. values shall be null unless otherwise stated. In the descriptions
  211. below, the term
  212. .IR "defining text"
  213. refers to the value of the macro: the second argument to the
  214. .BR define
  215. macro, among other things. Except for the first argument to the
  216. .BR eval
  217. macro, all numeric arguments to built-in macros shall be interpreted as
  218. decimal values. The string values produced as the defining text of the
  219. .BR decr ,
  220. .BR divnum ,
  221. .BR incr ,
  222. .BR index ,
  223. .BR len ,
  224. and
  225. .BR sysval
  226. built-in macros shall be in the form of a decimal-constant as defined
  227. in the C language.
  228. .IP "\fBchangecom\fR" 10
  229. The
  230. .BR changecom
  231. macro shall set the begin-comment and end-comment strings. With no
  232. arguments, the comment mechanism shall be disabled. With a single non-null
  233. argument, that argument shall become the begin-comment and the
  234. <newline>
  235. shall become the end-comment string. With two non-null arguments,
  236. the first argument shall become the begin-comment string and the second
  237. argument shall become the end-comment string. The behavior is unspecified
  238. if either argument is provided but null. Systems shall support comment
  239. strings of at least five characters.
  240. .IP "\fBchangequote\fR" 10
  241. The
  242. .BR changequote
  243. macro shall set the begin-quote and end-quote strings. With no
  244. arguments, the quote strings shall be set to the default values (that
  245. is, \fR`\|'\fP). The behavior is unspecified if there is a single argument
  246. or either argument is null. With two non-null arguments, the first
  247. argument shall become the begin-quote string and the second argument
  248. shall become the end-quote string. Systems shall support quote strings
  249. of at least five characters.
  250. .IP "\fBdecr\fR" 10
  251. The defining text of the
  252. .BR decr
  253. macro shall be its first argument decremented by 1. It shall be an
  254. error to specify an argument containing any non-numeric characters.
  255. The behavior is unspecified if
  256. .BR decr
  257. is not immediately followed by a
  258. <left-parenthesis>.
  259. .IP "\fBdefine\fR" 10
  260. The second argument shall become the defining text of the macro
  261. whose name is the first argument. It is unspecified whether the
  262. .BR define
  263. macro deletes all prior definitions of the macro named by its first
  264. argument or preserves all but the current definition of the macro.
  265. The behavior is unspecified if
  266. .BR define
  267. is not immediately followed by a
  268. <left-parenthesis>.
  269. .IP "\fBdefn\fR" 10
  270. The defining text of the
  271. .BR defn
  272. macro shall be the quoted definition (using the current quoting
  273. strings) of its arguments. The behavior is unspecified if
  274. .BR defn
  275. is not immediately followed by a
  276. <left-parenthesis>.
  277. .IP "\fBdivert\fR" 10
  278. The
  279. .IR m4
  280. utility maintains nine temporary buffers, numbered 1 to 9, inclusive.
  281. When the last of the input has been processed, any output that has been
  282. placed in these buffers shall be written to standard output in
  283. buffer-numerical order. The
  284. .BR divert
  285. macro shall divert future output to the buffer specified by its
  286. argument. Specifying no argument or an argument of 0 shall resume the
  287. normal output process. Output diverted to a stream with a negative
  288. number shall be discarded. Behavior is implementation-defined if
  289. a stream number larger than 9 is specified. It shall be an error to
  290. specify an argument containing any non-numeric characters.
  291. .IP "\fBdivnum\fR" 10
  292. The defining text of the
  293. .BR divnum
  294. macro shall be the number of the current output stream as a string.
  295. .IP "\fBdnl\fR" 10
  296. The
  297. .BR dnl
  298. macro shall cause
  299. .IR m4
  300. to discard all input characters up to and including the next
  301. <newline>.
  302. .IP "\fBdumpdef\fR" 10
  303. The
  304. .BR dumpdef
  305. macro shall write the defined text to standard error for each of the
  306. macros specified as arguments, or, if no arguments are specified, for
  307. all macros.
  308. .IP "\fBerrprint\fR" 10
  309. The
  310. .BR errprint
  311. macro shall write its arguments to standard error. The behavior
  312. is unspecified if
  313. .BR errprint
  314. is not immediately followed by a
  315. <left-parenthesis>.
  316. .IP "\fBeval\fR" 10
  317. The
  318. .BR eval
  319. macro shall evaluate its first argument as an arithmetic expression,
  320. using signed integer arithmetic with at least 32-bit precision. At least
  321. the following C-language operators shall be supported, with precedence,
  322. associativity, and behavior as described in
  323. .IR "Section 1.1.2.1" ", " "Arithmetic Precision and Operations":
  324. .RS 10
  325. .sp
  326. .RS 4
  327. .nf
  328. ()
  329. unary +
  330. unary -
  331. \&\(ti
  332. .P
  333. \&!
  334. binary *
  335. /
  336. %
  337. binary +
  338. binary -
  339. <<
  340. >>
  341. <
  342. <=
  343. >
  344. >=
  345. =\|=
  346. !=
  347. binary &
  348. \&\(ha
  349. |
  350. &&
  351. ||
  352. .fi
  353. .P
  354. .RE
  355. .P
  356. Systems shall support octal and hexadecimal numbers as in the ISO\ C standard.
  357. The second argument, if specified, shall set the radix for the result;
  358. if the argument is blank or unspecified, the default is 10. Behavior is
  359. unspecified if the radix falls outside the range 2 to 36, inclusive. The
  360. third argument, if specified, sets the minimum number of digits in the
  361. result. Behavior is unspecified if the third argument is less than
  362. zero. It shall be an error to specify the second or third argument
  363. containing any non-numeric characters. The behavior is unspecified if
  364. .BR eval
  365. is not immediately followed by a
  366. <left-parenthesis>.
  367. .RE
  368. .IP "\fBifdef\fR" 10
  369. If the first argument to the
  370. .BR ifdef
  371. macro is defined, the defining text shall be the second argument.
  372. Otherwise, the defining text shall be the third argument, if specified,
  373. or the null string, if not. The behavior is unspecified if
  374. .BR ifdef
  375. is not immediately followed by a
  376. <left-parenthesis>.
  377. .IP "\fBifelse\fR" 10
  378. The
  379. .BR ifelse
  380. macro takes three or more arguments. If the first two arguments compare
  381. as equal strings (after macro expansion of both arguments), the
  382. defining text shall be the third argument. If the first two arguments
  383. do not compare as equal strings and there are three arguments, the
  384. defining text shall be null. If the first two arguments do not compare
  385. as equal strings and there are four or five arguments, the defining
  386. text shall be the fourth argument. If the first two arguments do not
  387. compare as equal strings and there are six or more arguments, the first
  388. three arguments shall be discarded and processing shall restart with
  389. the remaining arguments. The behavior is unspecified if
  390. .BR ifelse
  391. is not immediately followed by a
  392. <left-parenthesis>.
  393. .IP "\fBinclude\fR" 10
  394. The defining text for the
  395. .BR include
  396. macro shall be the contents of the file named by the first argument. It
  397. shall be an error if the file cannot be read. The behavior is unspecified if
  398. .BR include
  399. is not immediately followed by a
  400. <left-parenthesis>.
  401. .IP "\fBincr\fR" 10
  402. The defining text of the
  403. .BR incr
  404. macro shall be its first argument incremented by 1. It shall be an
  405. error to specify an argument containing any non-numeric characters.
  406. The behavior is unspecified if
  407. .BR incr
  408. is not immediately followed by a
  409. <left-parenthesis>.
  410. .IP "\fBindex\fR" 10
  411. The defining text of the
  412. .BR index
  413. macro shall be the first character position (as a string) in the first
  414. argument where a string matching the second argument begins (zero
  415. origin), or \-1 if the second argument does not occur.
  416. The behavior is unspecified if
  417. .BR index
  418. is not immediately followed by a
  419. <left-parenthesis>.
  420. .IP "\fBlen\fR" 10
  421. The defining text of the
  422. .BR len
  423. macro shall be the length (as a string) of the first argument.
  424. The behavior is unspecified if
  425. .BR len
  426. is not immediately followed by a
  427. <left-parenthesis>.
  428. .IP "\fBm4exit\fR" 10
  429. Exit from the
  430. .IR m4
  431. utility. If the first argument is specified, it shall be the exit
  432. code. If no argument is specified, the exit code shall be zero. It
  433. shall be an error to specify an argument containing any non-numeric
  434. characters. If the first argument is zero or no argument is specified,
  435. and an error has previously occurred (for example, a
  436. .IR file
  437. operand that could not be opened), it is unspecified whether the exit
  438. status is zero or non-zero.
  439. .IP "\fBm4wrap\fR" 10
  440. The first argument shall be processed when EOF is reached. If the
  441. .BR m4wrap
  442. macro is used multiple times, the arguments specified shall be
  443. processed in the order in which the
  444. .BR m4wrap
  445. macros were processed. The behavior is unspecified if
  446. .BR m4wrap
  447. is not immediately followed by a
  448. <left-parenthesis>.
  449. .IP "\fBmaketemp\fR" 10
  450. The defining text shall be the first argument, with any trailing
  451. .BR 'X'
  452. characters replaced with the current process ID as a string.
  453. The behavior is unspecified if
  454. .BR maketemp
  455. is not immediately followed by a
  456. <left-parenthesis>.
  457. .IP "\fBmkstemp\fR" 10
  458. The defining text shall be as if it were the resulting pathname after
  459. a successful call to the
  460. \fImkstemp\fR()
  461. function defined in the System Interfaces volume of POSIX.1\(hy2017 called with the first argument to the
  462. macro invocation. If a file is created, that file shall be closed.
  463. If a file could not be created, the
  464. .IR m4
  465. utility shall write a diagnostic message to standard error and shall
  466. continue processing input but its final exit status shall be non-zero;
  467. the defining text of the macro shall be the empty string. The behavior
  468. is unspecified if
  469. .BR mkstemp
  470. is not immediately followed by a
  471. <left-parenthesis>.
  472. .IP "\fBpopdef\fR" 10
  473. The
  474. .BR popdef
  475. macro shall delete the current definition of its arguments, replacing
  476. that definition with the previous one. If there is no previous
  477. definition, the macro is undefined. The behavior is unspecified if
  478. .BR popdef
  479. is not immediately followed by a
  480. <left-parenthesis>.
  481. .IP "\fBpushdef\fR" 10
  482. The
  483. .BR pushdef
  484. macro shall be equivalent to the
  485. .BR define
  486. macro with the exception that it shall preserve any current definition
  487. for future retrieval using the
  488. .BR popdef
  489. macro. The behavior is unspecified if
  490. .BR pushdef
  491. is not immediately followed by a
  492. <left-parenthesis>.
  493. .IP "\fBshift\fR" 10
  494. The defining text for the
  495. .BR shift
  496. macro shall be a comma-separated list of its arguments except the first
  497. one. Each argument shall be quoted using the current quoting strings.
  498. The behavior is unspecified if
  499. .BR shift
  500. is not immediately followed by a
  501. <left-parenthesis>.
  502. .IP "\fBsinclude\fR" 10
  503. The
  504. .BR sinclude
  505. macro shall be equivalent to the
  506. .BR include
  507. macro, except that it shall not be an error if the file is inaccessible.
  508. The behavior is unspecified if
  509. .BR sinclude
  510. is not immediately followed by a
  511. <left-parenthesis>.
  512. .IP "\fBsubstr\fR" 10
  513. The defining text for the
  514. .BR substr
  515. macro shall be the substring of the first argument beginning at the
  516. zero-offset character position specified by the second argument. The
  517. third argument, if specified, shall be the number of characters to
  518. select; if not specified, the characters from the starting point to the
  519. end of the first argument shall become the defining text. It shall not
  520. be an error to specify a starting point beyond the end of the first
  521. argument and the defining text shall be null. It shall be an error to
  522. specify an argument containing any non-numeric characters.
  523. The behavior is unspecified if
  524. .BR substr
  525. is not immediately followed by a
  526. <left-parenthesis>.
  527. .IP "\fBsyscmd\fR" 10
  528. The
  529. .BR syscmd
  530. macro shall interpret its first argument as a shell command line. The
  531. defining text shall be the string result of that command. The string
  532. result shall not be rescanned for macros while setting the defining
  533. text. No output redirection shall be performed by the
  534. .IR m4
  535. utility. The exit status value from the command can be retrieved using
  536. the
  537. .BR sysval
  538. macro. The behavior is unspecified if
  539. .BR syscmd
  540. is not immediately followed by a
  541. <left-parenthesis>.
  542. .IP "\fBsysval\fR" 10
  543. The defining text of the
  544. .BR sysval
  545. macro shall be the exit value of the utility last invoked by the
  546. .BR syscmd
  547. macro (as a string).
  548. .IP "\fBtraceon\fR" 10
  549. The
  550. .BR traceon
  551. macro shall enable tracing for the macros specified as arguments, or,
  552. if no arguments are specified, for all macros. The trace output shall
  553. be written to standard error in an unspecified format.
  554. .IP "\fBtraceoff\fR" 10
  555. The
  556. .BR traceoff
  557. macro shall disable tracing for the macros specified as arguments, or,
  558. if no arguments are specified, for all macros.
  559. .IP "\fBtranslit\fR" 10
  560. The defining text of the
  561. .BR translit
  562. macro shall be the first argument with every character that occurs in
  563. the second argument replaced with the corresponding character from the
  564. third argument. If no replacement character is specified for some
  565. source character because the second argument is longer than the third
  566. argument, that character shall be deleted from the first argument in
  567. .BR translit 's
  568. defining text. The behavior is unspecified if the
  569. .BR '\-'
  570. character appears within the second or third argument anywhere besides
  571. the first or last character. The behavior is unspecified if the same
  572. character appears more than once in the second argument. The behavior
  573. is unspecified if
  574. .BR translit
  575. is not immediately followed by a
  576. <left-parenthesis>.
  577. .IP "\fBundefine\fR" 10
  578. The
  579. .BR undefine
  580. macro shall delete all definitions (including those preserved using the
  581. .BR pushdef
  582. macro) of the macros named by its arguments. The behavior is unspecified if
  583. .BR undefine
  584. is not immediately followed by a
  585. <left-parenthesis>.
  586. .IP "\fBundivert\fR" 10
  587. The
  588. .BR undivert
  589. macro shall cause immediate output of any text in temporary buffers
  590. named as arguments, or all temporary buffers if no arguments are
  591. specified. Buffers can be undiverted into other temporary buffers.
  592. Undiverting shall discard the contents of the temporary buffer. The
  593. behavior is unspecified if an argument contains any non-numeric
  594. characters.
  595. .SH "EXIT STATUS"
  596. The following exit values shall be returned:
  597. .IP "\00" 6
  598. Successful completion.
  599. .IP >0 6
  600. An error occurred
  601. .P
  602. If the
  603. .BR m4exit
  604. macro is used, the exit value can be specified by the input file.
  605. .SH "CONSEQUENCES OF ERRORS"
  606. Default.
  607. .LP
  608. .IR "The following sections are informative."
  609. .SH "APPLICATION USAGE"
  610. The
  611. .BR defn
  612. macro is useful for renaming macros, especially built-ins.
  613. .P
  614. Since
  615. .BR eval
  616. defers to the ISO\ C standard, some operations have undefined behavior. In some
  617. implementations, division or remainder by zero cause a fatal signal,
  618. even if the division occurs on the short-circuited branch of
  619. .BR \(dq&&\(dq
  620. or
  621. .BR \(dq||\(dq .
  622. Any operation that overflows in signed arithmetic produces undefined
  623. behavior. Likewise, using the
  624. .BR shift
  625. operators with a shift amount that is not positive and smaller
  626. than the precision is undefined, as is shifting a negative number to
  627. the right. Historically, not all implementations obeyed C-language
  628. precedence rules:
  629. .BR '\(ti'
  630. and
  631. .BR '!'
  632. were lower than
  633. .BR '==' ;
  634. .BR '=='
  635. and
  636. .BR '!='
  637. were not lower than
  638. .BR '<' ;
  639. and
  640. .BR '|'
  641. was not lower than
  642. .BR '\(ha' ;
  643. the liberal use of
  644. .BR \(dq()\(dq
  645. can force the desired precedence even with these non-compliant
  646. implementations. Furthermore, some traditional implementations treated
  647. .BR '\(ha'
  648. as an exponentiation operator, although most implementations now use
  649. .BR \(dq**\(dq
  650. as an extension for this purpose.
  651. .P
  652. When a macro has been multiply defined via the
  653. .BR pushdef
  654. macro, it is unspecified whether the
  655. .BR define
  656. macro will alter only the most recent definition (as though by
  657. .BR popdef
  658. and
  659. .BR pushdef ),
  660. or replace the entire stack of definitions with a single definition
  661. (as though by
  662. .BR undefine
  663. and
  664. .BR pushdef ).
  665. An application desiring particular behavior for the
  666. .BR define
  667. macro in this case can redefine it accordingly.
  668. .P
  669. Applications should use the
  670. .BR mkstemp
  671. macro instead of the obsolescent
  672. .BR maketemp
  673. macro for creating temporary files.
  674. .SH EXAMPLES
  675. If the file
  676. .BR m4src
  677. contains the lines:
  678. .sp
  679. .RS 4
  680. .nf
  681. The value of `VER\(aq is "VER".
  682. ifdef(`VER\(aq, ``VER\(aq\(aq is defined to be VER., VER is not defined.)
  683. ifelse(VER, 1, ``VER\(aq\(aq is `VER\(aq.)
  684. ifelse(VER, 2, ``VER\(aq\(aq is `VER\(aq., ``VER\(aq\(aq is not 2.)
  685. end
  686. .fi
  687. .P
  688. .RE
  689. .P
  690. then the command
  691. .sp
  692. .RS 4
  693. .nf
  694. m4 m4src
  695. .fi
  696. .P
  697. .RE
  698. .P
  699. or the command:
  700. .sp
  701. .RS 4
  702. .nf
  703. m4 -U VER m4src
  704. .fi
  705. .P
  706. .RE
  707. .P
  708. produces the output:
  709. .sp
  710. .RS 4
  711. .nf
  712. The value of VER is "VER".
  713. VER is not defined.
  714. .P
  715. VER is not 2.
  716. end
  717. .fi
  718. .P
  719. .RE
  720. .P
  721. The command:
  722. .sp
  723. .RS 4
  724. .nf
  725. m4 -D VER m4src
  726. .fi
  727. .P
  728. .RE
  729. .P
  730. produces the output:
  731. .sp
  732. .RS 4
  733. .nf
  734. The value of VER is "".
  735. VER is defined to be .
  736. .P
  737. VER is not 2.
  738. end
  739. .fi
  740. .P
  741. .RE
  742. .P
  743. The command:
  744. .sp
  745. .RS 4
  746. .nf
  747. m4 -D VER=1 m4src
  748. .fi
  749. .P
  750. .RE
  751. .P
  752. produces the output:
  753. .sp
  754. .RS 4
  755. .nf
  756. The value of VER is "1".
  757. VER is defined to be 1.
  758. VER is 1.
  759. VER is not 2.
  760. end
  761. .fi
  762. .P
  763. .RE
  764. .P
  765. The command:
  766. .sp
  767. .RS 4
  768. .nf
  769. m4 -D VER=2 m4src
  770. .fi
  771. .P
  772. .RE
  773. .P
  774. produces the output:
  775. .sp
  776. .RS 4
  777. .nf
  778. The value of VER is "2".
  779. VER is defined to be 2.
  780. .P
  781. VER is 2.
  782. end
  783. .fi
  784. .P
  785. .RE
  786. .SH RATIONALE
  787. Historic System V-based behavior treated
  788. .BR \(dq${\(dq
  789. in a macro definition as two literal characters. However, this sequence
  790. is left unspecified so that implementations may offer extensions
  791. such as
  792. .BR \(dq${11}\(dq
  793. meaning the eleventh positional parameter. Macros can still be defined with
  794. appropriate uses of nested quoting to result in a literal
  795. .BR \(dq${\(dq
  796. in the output after rescanning removes the nested quotes.
  797. .P
  798. In the
  799. .BR translit
  800. built-in, historic System V-based behavior treated
  801. .BR '\-'
  802. as a literal; GNU behavior treats it as a range. This version of
  803. the standard allows either behavior.
  804. .SH "FUTURE DIRECTIONS"
  805. None.
  806. .SH "SEE ALSO"
  807. .IR "\fIc99\fR\^"
  808. .P
  809. The Base Definitions volume of POSIX.1\(hy2017,
  810. .IR "Chapter 8" ", " "Environment Variables",
  811. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  812. .\"
  813. .SH COPYRIGHT
  814. Portions of this text are reprinted and reproduced in electronic form
  815. from IEEE Std 1003.1-2017, Standard for Information Technology
  816. -- Portable Operating System Interface (POSIX), The Open Group Base
  817. Specifications Issue 7, 2018 Edition,
  818. Copyright (C) 2018 by the Institute of
  819. Electrical and Electronics Engineers, Inc and The Open Group.
  820. In the event of any discrepancy between this version and the original IEEE and
  821. The Open Group Standard, the original IEEE and The Open Group Standard
  822. is the referee document. The original Standard can be obtained online at
  823. http://www.opengroup.org/unix/online.html .
  824. .PP
  825. Any typographical or formatting errors that appear
  826. in this page are most likely
  827. to have been introduced during the conversion of the source files to
  828. man page format. To report such errors, see
  829. https://www.kernel.org/doc/man-pages/reporting_bugs.html .