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.1 (15234B)


  1. .\" @(#) $OpenBSD: m4.1,v 1.68 2022/06/14 21:31:45 naddy Exp $
  2. .\"
  3. .\" Copyright (c) 1989, 1993
  4. .\" The Regents of the University of California. All rights reserved.
  5. .\"
  6. .\" This code is derived from software contributed to Berkeley by
  7. .\" Ozan Yigit at York University.
  8. .\"
  9. .\" Redistribution and use in source and binary forms, with or without
  10. .\" modification, are permitted provided that the following conditions
  11. .\" are met:
  12. .\" 1. Redistributions of source code must retain the above copyright
  13. .\" notice, this list of conditions and the following disclaimer.
  14. .\" 2. Redistributions in binary form must reproduce the above copyright
  15. .\" notice, this list of conditions and the following disclaimer in the
  16. .\" documentation and/or other materials provided with the distribution.
  17. .\" 3. Neither the name of the University nor the names of its contributors
  18. .\" may be used to endorse or promote products derived from this software
  19. .\" without specific prior written permission.
  20. .\"
  21. .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  22. .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  23. .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  24. .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  25. .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  26. .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  27. .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  28. .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  29. .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  30. .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  31. .\" SUCH DAMAGE.
  32. .\"
  33. .Dd $Mdocdate: June 14 2022 $
  34. .Dt M4 1
  35. .Os
  36. .Sh NAME
  37. .Nm m4
  38. .Nd macro language processor
  39. .Sh SYNOPSIS
  40. .Nm
  41. .Op Fl EgPs
  42. .Oo
  43. .Sm off
  44. .Fl D Ar name Op No = Ar value
  45. .Sm on
  46. .Oc
  47. .Op Fl d Ar flags
  48. .Op Fl I Ar dirname
  49. .Op Fl o Ar filename
  50. .Op Fl t Ar macro
  51. .Op Fl U Ns Ar name
  52. .Op Ar
  53. .Sh DESCRIPTION
  54. The
  55. .Nm
  56. utility is a macro processor that can be used as a front end to any
  57. language (e.g., C, ratfor, fortran, lex, and yacc).
  58. If no input files are given,
  59. .Nm
  60. reads from the standard input,
  61. otherwise files specified on the command line are
  62. processed in the given order.
  63. Input files can be regular files, files in the m4 include paths, or a
  64. single dash
  65. .Pq Sq - ,
  66. denoting standard input.
  67. .Nm
  68. writes
  69. the processed text to the standard output, unless told otherwise.
  70. .Pp
  71. Macro calls have the form name(argument1[, argument2, ..., argumentN]).
  72. .Pp
  73. There cannot be any space following the macro name and the open
  74. parenthesis
  75. .Pq Sq \&( .
  76. If the macro name is not followed by an open
  77. parenthesis, it is processed with no arguments.
  78. .Pp
  79. Macro names consist of a leading alphabetic or underscore
  80. possibly followed by alphanumeric or underscore characters, e.g.,
  81. valid macro names match the pattern
  82. .Dq [a-zA-Z_][a-zA-Z0-9_]* .
  83. .Pp
  84. In arguments to macros, leading unquoted space, tab, and newline
  85. .Pq Sq \en
  86. characters are ignored.
  87. To quote strings, use left and right single quotes
  88. .Pq e.g., \(ga this is a string with a leading space\(aq .
  89. You can change the quote characters with the
  90. .Ic changequote
  91. built-in macro.
  92. .Pp
  93. Most built-ins don't make any sense without arguments, and hence are not
  94. recognized as special when not followed by an open parenthesis.
  95. .Pp
  96. The options are as follows:
  97. .Bl -tag -width Ds
  98. .It Fl D Ns Ar name Ns Op = Ns Ar value
  99. Define the symbol
  100. .Ar name
  101. to have some value (or
  102. .Dv NULL ) .
  103. .It Fl d Ar "flags"
  104. Set trace flags.
  105. .Ar flags
  106. may hold the following:
  107. .Bl -tag -width Ds
  108. .It Ar a
  109. print macro arguments.
  110. .It Ar c
  111. print macro expansion over several lines.
  112. .It Ar e
  113. print result of macro expansion.
  114. .It Ar f
  115. print filename location.
  116. .It Ar l
  117. print line number.
  118. .It Ar q
  119. quote arguments and expansion with the current quotes.
  120. .It Ar t
  121. start with all macros traced.
  122. .It Ar x
  123. number macro expansions.
  124. .It Ar V
  125. turn on all options.
  126. .El
  127. .Pp
  128. By default, trace is set to
  129. .Qq eq .
  130. .It Fl E
  131. Set warnings to be fatal.
  132. When a single
  133. .Fl E
  134. flag is specified, if warnings are issued, execution continues but
  135. .Nm
  136. will exit with a non-zero exit status.
  137. When multiple
  138. .Fl E
  139. flags are specified, execution will halt upon issuing the first warning and
  140. .Nm
  141. will exit with a non-zero exit status.
  142. This behaviour matches GNU-m4 1.4.9 and later.
  143. .It Fl g
  144. Activate GNU-m4 compatibility mode.
  145. In this mode, translit handles simple character
  146. ranges (e.g., a-z), regular expressions mimic emacs behavior,
  147. multiple m4wrap calls are handled as a stack,
  148. the number of diversions is unlimited,
  149. empty names for macro definitions are allowed,
  150. and eval understands
  151. .Sq 0rbase:value
  152. numbers.
  153. .It Fl I Ar "dirname"
  154. Add directory
  155. .Ar dirname
  156. to the include path.
  157. .It Fl o Ar filename
  158. Send trace output to
  159. .Ar filename .
  160. .It Fl P
  161. Prefix all built-in macros with
  162. .Sq m4_ .
  163. For example, instead of writing
  164. .Ic define ,
  165. use
  166. .Ic m4_define .
  167. .It Fl s
  168. Output line synchronization directives, suitable for
  169. .Xr cpp 1 .
  170. .It Fl t Ar macro
  171. Turn tracing on for
  172. .Ar macro .
  173. .It Fl "U" Ns Ar "name"
  174. Undefine the symbol
  175. .Ar name .
  176. .El
  177. .Sh SYNTAX
  178. .Nm
  179. provides the following built-in macros.
  180. They may be redefined, losing their original meaning.
  181. Return values are null unless otherwise stated.
  182. .Bl -tag -width changequote
  183. .It Fn builtin name
  184. Calls a built-in by its
  185. .Fa name ,
  186. overriding possible redefinitions.
  187. .It Fn changecom startcomment endcomment
  188. Changes the start comment and end comment sequences.
  189. Comment sequences may be up to five characters long.
  190. The default values are the hash sign
  191. and the newline character.
  192. .Bd -literal -offset indent
  193. # This is a comment
  194. .Ed
  195. .Pp
  196. With no arguments, comments are turned off.
  197. With one single argument, the end comment sequence is set
  198. to the newline character.
  199. .It Fn changequote beginquote endquote
  200. Defines the open quote and close quote sequences.
  201. Quote sequences may be up to five characters long.
  202. The default values are the backquote character and the quote
  203. character.
  204. .Bd -literal -offset indent
  205. `Here is a quoted string'
  206. .Ed
  207. .Pp
  208. With no arguments, the default quotes are restored.
  209. With one single argument, the close quote sequence is set
  210. to the newline character.
  211. .It Fn decr arg
  212. Decrements the argument
  213. .Fa arg
  214. by 1.
  215. The argument
  216. .Fa arg
  217. must be a valid numeric string.
  218. .It Fn define name value
  219. Define a new macro named by the first argument
  220. .Fa name
  221. to have the
  222. value of the second argument
  223. .Fa value .
  224. Each occurrence of
  225. .Sq $n
  226. (where
  227. .Ar n
  228. is 0 through 9) is replaced by the
  229. .Ar n Ns 'th
  230. argument.
  231. .Sq $0
  232. is the name of the calling macro.
  233. Undefined arguments are replaced by a null string.
  234. .Sq $#
  235. is replaced by the number of arguments;
  236. .Sq $*
  237. is replaced by all arguments comma separated;
  238. .Sq $@
  239. is the same as
  240. .Sq $*
  241. but all arguments are quoted against further expansion.
  242. .It Fn defn name ...
  243. Returns the quoted definition for each argument.
  244. This can be used to rename
  245. macro definitions (even for built-in macros).
  246. .It Fn divert num
  247. There are 10 output queues (numbered 0-9).
  248. At the end of processing
  249. .Nm
  250. concatenates all the queues in numerical order to produce the
  251. final output.
  252. Initially the output queue is 0.
  253. The divert
  254. macro allows you to select a new output queue (an invalid argument
  255. passed to divert causes output to be discarded).
  256. .It Ic divnum
  257. Returns the current output queue number.
  258. .It Ic dnl
  259. Discard input characters up to and including the next newline.
  260. .It Fn dumpdef name ...
  261. Prints the names and definitions for the named items, or for everything
  262. if no arguments are passed.
  263. .It Fn errprint msg
  264. Prints the first argument on the standard error output stream.
  265. .It Fn esyscmd cmd
  266. Passes its first argument to a shell and returns the shell's standard output.
  267. Note that the shell shares its standard input and standard error with
  268. .Nm .
  269. .It Fn eval expr[,radix[,minimum]]
  270. Computes the first argument as an arithmetic expression using 32-bit
  271. arithmetic.
  272. Operators are the standard C ternary, arithmetic, logical,
  273. shift, relational, bitwise, and parentheses operators.
  274. You can specify
  275. octal, decimal, and hexadecimal numbers as in C.
  276. The optional second argument
  277. .Fa radix
  278. specifies the radix for the result and the optional third argument
  279. .Fa minimum
  280. specifies the minimum number of digits in the result.
  281. .It Fn expr expr
  282. This is an alias for
  283. .Ic eval .
  284. .It Fn format formatstring arg1 ...
  285. Returns
  286. .Fa formatstring
  287. with escape sequences substituted with
  288. .Fa arg1
  289. and following arguments, in a way similar to
  290. .Xr printf 3 .
  291. This built-in is only available in GNU-m4 compatibility mode, and the only
  292. parameters implemented are there for autoconf compatibility:
  293. left-padding flag, an optional field width, a maximum field width,
  294. *-specified field widths, and the %s and %c data type.
  295. .It Fn ifdef name yes no
  296. If the macro named by the first argument is defined then return the second
  297. argument, otherwise the third.
  298. If there is no third argument, the value is
  299. .Dv NULL .
  300. The word
  301. .Qq unix
  302. is predefined.
  303. .It Fn ifelse a b yes ...
  304. If the first argument
  305. .Fa a
  306. matches the second argument
  307. .Fa b
  308. then
  309. .Fn ifelse
  310. returns
  311. the third argument
  312. .Fa yes .
  313. If the match fails the three arguments are
  314. discarded and the next three arguments are used until there is
  315. zero or one arguments left, either this last argument or
  316. .Dv NULL
  317. is returned if no other matches were found.
  318. .It Fn include name
  319. Returns the contents of the file specified in the first argument.
  320. If the file is not found as is, look through the include path:
  321. first the directories specified with
  322. .Fl I
  323. on the command line, then the environment variable
  324. .Ev M4PATH ,
  325. as a colon-separated list of directories.
  326. Include aborts with an error message if the file cannot be included.
  327. .It Fn incr arg
  328. Increments the argument by 1.
  329. The argument must be a valid numeric string.
  330. .It Fn index string substring
  331. Returns the index of the second argument in the first argument (e.g.,
  332. .Ic index(the quick brown fox jumped, fox)
  333. returns 16).
  334. If the second
  335. argument is not found, index returns \-1.
  336. .It Fn indir macro arg1 ...
  337. Indirectly calls the macro whose name is passed as the first argument,
  338. with the remaining arguments passed as first, ... arguments.
  339. .It Fn len arg
  340. Returns the number of characters in the first argument.
  341. Extra arguments
  342. are ignored.
  343. .It Fn m4exit code
  344. Immediately exits with the return value specified by the first argument,
  345. 0 if none.
  346. .It Fn m4wrap todo
  347. Allows you to define what happens at the final
  348. .Dv EOF ,
  349. usually for cleanup purposes (e.g.,
  350. .Ic m4wrap("cleanup(tempfile)")
  351. causes the macro cleanup to be
  352. invoked after all other processing is done).
  353. .Pp
  354. Multiple calls to
  355. .Fn m4wrap
  356. get inserted in sequence at the final
  357. .Dv EOF .
  358. .It Fn maketemp template
  359. Like
  360. .Ic mkstemp .
  361. .It Fn mkstemp template
  362. Invokes
  363. .Xr mkstemp 3
  364. on the first argument, and returns the modified string.
  365. This can be used to create unique
  366. temporary file names.
  367. .It Fn paste file
  368. Includes the contents of the file specified by the first argument without
  369. any macro processing.
  370. Aborts with an error message if the file cannot be
  371. included.
  372. .It Fn patsubst string regexp replacement
  373. Substitutes a regular expression in a string with a replacement string.
  374. Usual substitution patterns apply: an ampersand
  375. .Pq Sq \&&
  376. is replaced by the string matching the regular expression.
  377. The string
  378. .Sq \e# ,
  379. where
  380. .Sq #
  381. is a digit, is replaced by the corresponding back-reference.
  382. .It Fn popdef arg ...
  383. Restores the
  384. .Ic pushdef Ns ed
  385. definition for each argument.
  386. .It Fn pushdef macro def
  387. Takes the same arguments as
  388. .Ic define ,
  389. but it saves the definition on a
  390. stack for later retrieval by
  391. .Fn popdef .
  392. .It Fn regexp string regexp replacement
  393. Finds a regular expression in a string.
  394. If no further arguments are given,
  395. it returns the first match position or \-1 if no match.
  396. If a third argument
  397. is provided, it returns the replacement string, with sub-patterns replaced.
  398. .It Fn shift arg1 ...
  399. Returns all but the first argument, the remaining arguments are
  400. quoted and pushed back with commas in between.
  401. The quoting
  402. nullifies the effect of the extra scan that will subsequently be
  403. performed.
  404. .It Fn sinclude file
  405. Similar to
  406. .Ic include ,
  407. except it ignores any errors.
  408. .It Fn spaste file
  409. Similar to
  410. .Fn paste ,
  411. except it ignores any errors.
  412. .It Fn substr string offset length
  413. Returns a substring of the first argument starting at the offset specified
  414. by the second argument and the length specified by the third argument.
  415. If no third argument is present, it returns the rest of the string.
  416. .It Fn syscmd cmd
  417. Passes the first argument to the shell.
  418. Nothing is returned.
  419. .It Ic sysval
  420. Returns the return value from the last
  421. .Ic syscmd .
  422. .It Fn traceon arg ...
  423. Enables tracing of macro expansions for the given arguments, or for all
  424. macros if no argument is given.
  425. .It Fn traceoff arg ...
  426. Disables tracing of macro expansions for the given arguments, or for all
  427. macros if no argument is given.
  428. .It Fn translit string mapfrom mapto
  429. Transliterate the characters in the first argument from the set
  430. given by the second argument to the set given by the third.
  431. You cannot use
  432. .Xr tr 1
  433. style abbreviations.
  434. .It Fn undefine name1 ...
  435. Removes the definition for the macros specified by its arguments.
  436. .It Fn undivert arg ...
  437. Flushes the named output queues (or all queues if no arguments).
  438. .It Ic unix
  439. A pre-defined macro for testing the OS platform.
  440. .It Ic __line__
  441. Returns the current file's line number.
  442. .It Ic __file__
  443. Returns the current file's name.
  444. .El
  445. .Sh EXIT STATUS
  446. .Ex -std m4
  447. .Pp
  448. But note that the
  449. .Ic m4exit
  450. macro can modify the exit status, as can the
  451. .Fl E
  452. flag.
  453. .Sh SEE ALSO
  454. .Rs
  455. .\" 4.4BSD PSD:17
  456. .%A B. W. Kernighan
  457. .%A D. M. Ritchie
  458. .%I AT&T Bell Laboratories
  459. .%T The M4 Macro Processor
  460. .%R Computing Science Technical Report
  461. .%N 59
  462. .%D July 1977
  463. .Re
  464. .Sh STANDARDS
  465. The
  466. .Nm
  467. utility is compliant with the
  468. .St -p1003.1-2008
  469. specification.
  470. .Pp
  471. The flags
  472. .Op Fl dEgIPot
  473. and the macros
  474. .Ic builtin ,
  475. .Ic esyscmd ,
  476. .Ic expr ,
  477. .Ic format ,
  478. .Ic indir ,
  479. .Ic paste ,
  480. .Ic patsubst ,
  481. .Ic regexp ,
  482. .Ic spaste ,
  483. .Ic unix ,
  484. .Ic __line__ ,
  485. and
  486. .Ic __file__
  487. are extensions to that specification.
  488. .Pp
  489. .Ic maketemp
  490. is not supposed to be a synonym for
  491. .Ic mkstemp ,
  492. but instead to be an insecure temporary file name creation function.
  493. It is marked by
  494. .St -p1003.1-2008
  495. as being obsolescent and should not be used if portability is a concern.
  496. .Pp
  497. The output format of
  498. .Ic traceon
  499. and
  500. .Ic dumpdef
  501. are not specified in any standard,
  502. are likely to change and should not be relied upon.
  503. The current format of tracing is closely modelled on
  504. .Nm gnu-m4 ,
  505. to allow
  506. .Nm autoconf
  507. to work.
  508. .Pp
  509. The built-ins
  510. .Ic pushdef
  511. and
  512. .Ic popdef
  513. handle macro definitions as a stack.
  514. However,
  515. .Ic define
  516. interacts with the stack in an undefined way.
  517. In this implementation,
  518. .Ic define
  519. replaces the top-most definition only.
  520. Other implementations may erase all definitions on the stack instead.
  521. .Pp
  522. All built-ins do expand without arguments in many other
  523. .Nm .
  524. .Pp
  525. Many other
  526. .Nm
  527. have dire size limitations with respect to buffer sizes.
  528. .Sh AUTHORS
  529. .An -nosplit
  530. .An Ozan Yigit Aq Mt oz@sis.yorku.ca
  531. and
  532. .An Richard A. O'Keefe Aq Mt ok@goanna.cs.rmit.OZ.AU .
  533. .Pp
  534. GNU-m4 compatibility extensions by
  535. .An Marc Espie Aq Mt espie@openbsd.org .