share/man/man1/m4.1

   1 .\"
   2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
   3 .\" permission to reproduce portions of its copyrighted documentation.
   4 .\" Original documentation from The Open Group can be obtained online at
   5 .\" http://www.opengroup.org/bookstore/.
   6 .\"
   7 .\" The Institute of Electrical and Electronics Engineers and The Open
   8 .\" Group, have given us permission to reprint portions of their
   9 .\" documentation.
  10 .\"
  11 .\" In the following statement, the phrase ``this text'' refers to portions
  12 .\" of the system documentation.
  13 .\"
  14 .\" Portions of this text are reprinted and reproduced in electronic form
  15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
  16 .\" Standard for Information Technology -- Portable Operating System
  17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
  18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
  19 .\" Engineers, Inc and The Open Group.  In the event of any discrepancy
  20 .\" between these versions and the original IEEE and The Open Group
  21 .\" Standard, the original IEEE and The Open Group Standard is the referee
  22 .\" document.  The original Standard can be obtained online at
  23 .\" http://www.opengroup.org/unix/online.html.
  24 .\"
  25 .\" This notice shall appear on any product containing this material.
  26 .\"
  27 .\" The contents of this file are subject to the terms of the
  28 .\" Common Development and Distribution License (the "License").
  29 .\" You may not use this file except in compliance with the License.
  30 .\"
  31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
  32 .\" or http://www.opensolaris.org/os/licensing.
  33 .\" See the License for the specific language governing permissions
  34 .\" and limitations under the License.
  35 .\"
  36 .\" When distributing Covered Code, include this CDDL HEADER in each
  37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  38 .\" If applicable, add the following below this CDDL HEADER, with the
  39 .\" fields enclosed by brackets "[]" replaced with your own identifying
  40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
  41 .\"
  42 .\"
  43 .\" Copyright 1989 AT&T
  44 .\" Portions Copyright (c) 1992, X/Open Company Limited All Rights Reserved
  45 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
  46 .\"
  47 .TH M4 1 "Oct 25, 2017"
  48 .SH NAME
  49 m4 \- macro processor
  50 .SH SYNOPSIS
  51 .LP
  52 .nf
  53 \fB/usr/bin/m4\fR [\fB-e\fR] [\fB-s\fR] [\fB-B\fR \fIint\fR] [\fB-H\fR \fIint\fR] [\fB-S\fR \fIint\fR]
  54      [\fB-T\fR \fIint\fR] [\fB-D\fR\fIname\fR [...\fI=val\fR]] [\fB-U\fR \fIname\fR] ... [\fIfile\fR]...
  55 .fi
  56
  57 .SH DESCRIPTION
  58 .sp
  59 .LP
  60 The \fBm4\fR utility is a macro processor intended as a front end for C,
  61 assembler, and other languages. Each of the argument files is processed in
  62 order. If there are no files, or if a file is \fB\(mi\fR, the standard input is
  63 read. The processed text is written on the standard output. \fBNote:\fR
  64 \fBm4\fR cannot include more than nine nested files and writes a diagnostic
  65 message if that number is exceeded.
  66 .SS "Macro Syntax"
  67 .sp
  68 .LP
  69 Macro calls have the form:
  70 .sp
  71 .in +2
  72 .nf
  73 \fIname\fR(\fIarg1\fR,\fIarg2\fR, ..., \fIargn\fR)
  74 .fi
  75 .in -2
  76 .sp
  77
  78 .sp
  79 .LP
  80 The open parenthesis character, \fB(\fR, must immediately follow the name of
  81 the macro. If the name of a defined macro is not followed by a \fB(\fR, it is
  82 deemed to be a call of that macro with no arguments. Potential macro names
  83 consist of alphanumeric characters and underscore (\fB_\fR), where the first
  84 character is not a digit.
  85 .sp
  86 .LP
  87 Leading unquoted blanks, TABs, and \fBNEWLINE\fRs are ignored while collecting
  88 arguments. Left and right single quotes are used to quote strings. The value of
  89 a quoted string is the string stripped of the quotes.
  90 .SS "Macro Processing"
  91 .sp
  92 .LP
  93 When a macro name is recognized, its arguments are collected by searching for a
  94 matching right parenthesis. If fewer arguments are supplied than are in the
  95 macro definition, the trailing arguments are taken to be \fINULL\fR. Macro
  96 evaluation proceeds normally during the collection of the arguments, and any
  97 commas or right parentheses that happen to turn up within the value of a nested
  98 call are as effective as those in the original input text. After argument
  99 collection, the value of the macro is pushed back onto the input stream and
 100 rescanned.
 101 .SH OPTIONS
 102 .sp
 103 .LP
 104 The options and their effects are as follows:
 105 .sp
 106 .ne 2
 107 .na
 108 \fB\fB-B\fR\fIint\fR\fR
 109 .ad
 110 .RS 9n
 111 Changes the size of the push-back and argument collection buffers from the
 112 default of \fB4,096\fR.
 113 .RE
 114
 115 .sp
 116 .ne 2
 117 .na
 118 \fB\fB-e\fR\fR
 119 .ad
 120 .RS 9n
 121 Operates interactively. Interrupts are ignored and the output is unbuffered.
 122 .RE
 123
 124 .sp
 125 .ne 2
 126 .na
 127 \fB\fB-H\fR\fIint\fR\fR
 128 .ad
 129 .RS 9n
 130 Changes the size of the symbol table hash array from the default of \fB199\fR.
 131 The size should be prime.
 132 .RE
 133
 134 .sp
 135 .ne 2
 136 .na
 137 \fB\fB-s\fR\fR
 138 .ad
 139 .RS 9n
 140 Enables line sync output for the C preprocessor (\fB#\fRline .\|.\|.\|)
 141 .RE
 142
 143 .sp
 144 .ne 2
 145 .na
 146 \fB\fB-S\fR\fIint\fR\fR
 147 .ad
 148 .RS 9n
 149 Changes the size of the call stack from the default of \fB100\fRslots. Macros
 150 take three slots, and non-macro arguments take one.
 151 .RE
 152
 153 .sp
 154 .ne 2
 155 .na
 156 \fB\fB-T\fR\fIint\fR\fR
 157 .ad
 158 .RS 9n
 159 Changes the size of the token buffer from the default of \fB512\fRbytes.
 160 .RE
 161
 162 .sp
 163 .LP
 164 To be effective, the above flags must appear before any file names and before
 165 any \fB-D\fR or \fB-U\fR flags:
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fB-D\fR \fIname\fR[\fB=\fR\fBval\fR]\fR
 170 .ad
 171 .RS 17n
 172 Defines \fIname\fR to \fBval\fR or to \fINULL\fR in \fBval\fR's absence.
 173 .RE
 174
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fB-U\fR\fIname\fR\fR
 179 .ad
 180 .RS 17n
 181 Undefines \fIname\fR.
 182 .RE
 183
 184 .SH OPERANDS
 185 .sp
 186 .LP
 187 The following operand is supported:
 188 .sp
 189 .ne 2
 190 .na
 191 \fB\fIfile\fR\fR
 192 .ad
 193 .RS 8n
 194 A path name of a text file to be processed. If no \fIfile\fR is given, or if it
 195 is \(mi, the standard input is read.
 196 .RE
 197
 198 .SH USAGE
 199 .sp
 200 .LP
 201 The \fBm4\fR utility makes available the following built-in macros. These
 202 macros can be redefined, but once this is done the original meaning is lost.
 203 Their values are \fINULL\fR unless otherwise stated.
 204 .sp
 205 .ne 2
 206 .na
 207 \fB\fBchangequote\fR\fR
 208 .ad
 209 .RS 15n
 210 Change quote symbols to the first and second arguments. The symbols can be up
 211 to five characters long. \fBchangequote\fR without arguments restores the
 212 original values (that is, \fB`\|'\fR).
 213 .RE
 214
 215 .sp
 216 .ne 2
 217 .na
 218 \fB\fBchangecom\fR\fR
 219 .ad
 220 .RS 15n
 221 Change left and right comment markers from the default \fB#\fR and
 222 \fBNEWLINE\fR. With no arguments, the comment mechanism is effectively
 223 disabled. With one argument, the left marker becomes the argument and the right
 224 marker becomes \fBNEWLINE\fR. With two arguments, both markers are affected.
 225 Comment markers can be up to five characters long.
 226 .RE
 227
 228 .sp
 229 .ne 2
 230 .na
 231 \fB\fBdecr\fR\fR
 232 .ad
 233 .RS 15n
 234 Returns the value of its argument decremented by 1.
 235 .RE
 236
 237 .sp
 238 .ne 2
 239 .na
 240 \fB\fBdefine\fR\fR
 241 .ad
 242 .RS 15n
 243 The second argument is installed as the value of the macro whose name is the
 244 first argument. Each occurrence of \fB$\fR\fIn\fR in the replacement text,
 245 where \fIn\fR is a digit, is replaced by the \fIn\fR-th argument. Argument 0 is
 246 the name of the macro; missing arguments are replaced by the null string;
 247 \fB$#\fR is replaced by the number of arguments; \fB$*\fR is replaced by a list
 248 of all the arguments separated by commas; \fB$@\fR is like \fB$*\fR, but each
 249 argument is quoted (with the current quotes).
 250 .RE
 251
 252 .sp
 253 .ne 2
 254 .na
 255 \fB\fBdefn\fR\fR
 256 .ad
 257 .RS 15n
 258 Returns the quoted definition of its argument(s). It is useful for renaming
 259 macros, especially built-ins.
 260 .RE
 261
 262 .sp
 263 .ne 2
 264 .na
 265 \fB\fBdivert\fR\fR
 266 .ad
 267 .RS 15n
 268 \fBm4\fR maintains 10 output streams, numbered 0-9. The final output is the
 269 concatenation of the streams in numerical order. Initially stream 0 is the
 270 current stream. The \fBdivert\fR macro changes the current output stream to its
 271 (digit-string) argument. Output diverted to a stream other than 0 through 9 is
 272 discarded.
 273 .RE
 274
 275 .sp
 276 .ne 2
 277 .na
 278 \fB\fBdivnum\fR\fR
 279 .ad
 280 .RS 15n
 281 Returns the value of the current output stream.
 282 .RE
 283
 284 .sp
 285 .ne 2
 286 .na
 287 \fB\fBdnl\fR\fR
 288 .ad
 289 .RS 15n
 290 Reads and discards characters up to and including the next \fBNEWLINE\fR.
 291 .RE
 292
 293 .sp
 294 .ne 2
 295 .na
 296 \fB\fBdumpdef\fR\fR
 297 .ad
 298 .RS 15n
 299 Prints current names and definitions, for the named items, or for all if no
 300 arguments are given.
 301 .RE
 302
 303 .sp
 304 .ne 2
 305 .na
 306 \fB\fBerrprint\fR\fR
 307 .ad
 308 .RS 15n
 309 Prints its argument on the diagnostic output file.
 310 .RE
 311
 312 .sp
 313 .ne 2
 314 .na
 315 \fB\fBifdef\fR\fR
 316 .ad
 317 .RS 15n
 318 If the first argument is defined, the value is the second argument, otherwise
 319 the third. If there is no third argument, the value is \fINULL\fR. The word
 320 \fBunix\fR is predefined.
 321 .RE
 322
 323 .sp
 324 .ne 2
 325 .na
 326 \fB\fBifelse\fR\fR
 327 .ad
 328 .RS 15n
 329 This macro has three or more arguments. If the first argument is the same
 330 string as the second, then the value is the third argument. If not, and if
 331 there are more than four arguments, the process is repeated with arguments 4,
 332 5, 6 and 7. Otherwise, the value is either the fourth string, or, if it is not
 333 present, \fINULL\fR.
 334 .RE
 335
 336 .sp
 337 .ne 2
 338 .na
 339 \fB\fBinclude\fR\fR
 340 .ad
 341 .RS 15n
 342 Returns the contents of the file named in the argument.
 343 .RE
 344
 345 .sp
 346 .ne 2
 347 .na
 348 \fB\fBincr\fR\fR
 349 .ad
 350 .RS 15n
 351 Returns the value of its argument incremented by 1. The value of the argument
 352 is calculated by interpreting an initial digit-string as a decimal number.
 353 .RE
 354
 355 .sp
 356 .ne 2
 357 .na
 358 \fB\fBindex\fR\fR
 359 .ad
 360 .RS 15n
 361 Returns the position in its first argument where the second argument begins
 362 (zero origin), or \(mi1 if the second argument does not occur.
 363 .RE
 364
 365 .sp
 366 .ne 2
 367 .na
 368 \fB\fBlen\fR\fR
 369 .ad
 370 .RS 15n
 371 Returns the number of characters in its argument.
 372 .RE
 373
 374 .sp
 375 .ne 2
 376 .na
 377 \fB\fBm4exit\fR\fR
 378 .ad
 379 .RS 15n
 380 This macro causes immediate exit from \fBm4\fR. Argument 1, if given, is the
 381 exit code; the default is \fB0\fR.
 382 .RE
 383
 384 .sp
 385 .ne 2
 386 .na
 387 \fB\fBm4wrap\fR\fR
 388 .ad
 389 .RS 15n
 390 Argument 1 is pushed back at final \fBEOF\fR. Example:
 391 \fBm4wrap(`cleanup(\|)')\fR
 392 .RE
 393
 394 .sp
 395 .ne 2
 396 .na
 397 \fB\fBmaketemp\fR\fR
 398 .ad
 399 .RS 15n
 400 Fills in a string of "\fBX\fR" characters in its argument with the current
 401 process \fBID\fR.
 402 .RE
 403
 404 .sp
 405 .ne 2
 406 .na
 407 \fB\fBpopdef\fR\fR
 408 .ad
 409 .RS 15n
 410 Removes current definition of its argument(s), exposing the previous one, if
 411 any.
 412 .RE
 413
 414 .sp
 415 .ne 2
 416 .na
 417 \fB\fBpushdef\fR\fR
 418 .ad
 419 .RS 15n
 420 Like \fBdefine\fR, but saves any previous definition.
 421 .RE
 422
 423 .sp
 424 .ne 2
 425 .na
 426 \fB\fBshift\fR\fR
 427 .ad
 428 .RS 15n
 429 Returns all but its first argument. The other arguments are quoted and pushed
 430 back with commas in between. The quoting nullifies the effect of the extra scan
 431 that is subsequently be performed.
 432 .RE
 433
 434 .sp
 435 .ne 2
 436 .na
 437 \fB\fBsinclude\fR\fR
 438 .ad
 439 .RS 15n
 440 This macro is identical to \fBinclude\fR, except that it says nothing if the
 441 file is inaccessible.
 442 .RE
 443
 444 .sp
 445 .ne 2
 446 .na
 447 \fB\fBsubstr\fR\fR
 448 .ad
 449 .RS 15n
 450 Returns a substring of its first argument. The second argument is a zero origin
 451 number selecting the first character; the third argument indicates the length
 452 of the substring. A missing third argument is taken to be large enough to
 453 extend to the end of the first string.
 454 .RE
 455
 456 .sp
 457 .ne 2
 458 .na
 459 \fB\fBsyscmd\fR\fR
 460 .ad
 461 .RS 15n
 462 This macro executes the command given in the first argument. No value is
 463 returned.
 464 .RE
 465
 466 .sp
 467 .ne 2
 468 .na
 469 \fB\fBsysval\fR\fR
 470 .ad
 471 .RS 15n
 472 This macro is the return code from the last call to \fBsyscmd\fR.
 473 .RE
 474
 475 .sp
 476 .ne 2
 477 .na
 478 \fB\fBtranslit\fR\fR
 479 .ad
 480 .RS 15n
 481 Transliterates the characters in its first argument from the set given by the
 482 second argument to the set given by the third. No abbreviations are permitted.
 483 .RE
 484
 485 .sp
 486 .ne 2
 487 .na
 488 \fB\fBtraceon\fR\fR
 489 .ad
 490 .RS 15n
 491 This macro with no arguments, turns on tracing for all macros (including
 492 built-ins). Otherwise, turns on tracing for named macros.
 493 .RE
 494
 495 .sp
 496 .ne 2
 497 .na
 498 \fB\fBtraceoff\fR\fR
 499 .ad
 500 .RS 15n
 501 Turns off trace globally and for any macros specified.
 502 .RE
 503
 504 .sp
 505 .ne 2
 506 .na
 507 \fB\fBundefine\fR\fR
 508 .ad
 509 .RS 15n
 510 Removes the definition of the macro named in its argument.
 511 .RE
 512
 513 .sp
 514 .ne 2
 515 .na
 516 \fB\fBundivert\fR\fR
 517 .ad
 518 .RS 15n
 519 This macro causes immediate output of text from diversions named as arguments,
 520 or all diversions if no argument. Text can be undiverted into another
 521 diversion. Undiverting discards the diverted text.
 522 .RE
 523
 524 .sp
 525 .ne 2
 526 .na
 527 \fB\fBeval\fR\fR
 528 .ad
 529 .RS 8n
 530 Evaluates its argument as an arithmetic expression,  using  32-bit
 531 signed-integer arithmetic. The following operators are supported: parentheses,
 532 unary -, unary +, !, ~, *, /, %, +, -, <<, >>, relationals, bitwise &, |, &&,
 533 and ||. Precedence and associativity are as in C. Octal and hex numbers can
 534 also be specified as in C. The second argument specifies the radix for the
 535 result; the default is 10. The third argument can be used to specify the
 536 minimum number of digits in the result.
 537 .RE
 538
 539 .SH EXAMPLES
 540 .LP
 541 \fBExample 1 \fRExamples of m4 files
 542 .sp
 543 .LP
 544 If the file \fBm4src\fR contains the lines:
 545
 546 .sp
 547 .in +2
 548 .nf
 549 The value of `VER' is "VER".
 550         ifdef(`VER', ``VER'' is defined to be VER., VER is not defined.)
 551         ifelse(VER, 1, ``VER'' is `VER'.)
 552         ifelse(VER, 2, ``VER'' is `VER'., ``VER'' is not 2.)
 553         end
 554 .fi
 555 .in -2
 556 .sp
 557
 558 .sp
 559 .LP
 560 then the command:
 561
 562 .sp
 563 .in +2
 564 .nf
 565 \fBm4 m4src\fR
 566 .fi
 567 .in -2
 568 .sp
 569
 570 .sp
 571 .LP
 572 or the command:
 573
 574 .sp
 575 .in +2
 576 .nf
 577 \fBm4 -U VER m4src\fR
 578 .fi
 579 .in -2
 580 .sp
 581
 582 .sp
 583 .LP
 584 produces the output:
 585
 586 .sp
 587 .in +2
 588 .nf
 589 The value of VER is "VER".
 590         VER is not defined.
 591
 592         VER is not 2.
 593         end
 594 .fi
 595 .in -2
 596 .sp
 597
 598 .sp
 599 .LP
 600 The command:
 601
 602 .sp
 603 .in +2
 604 .nf
 605 \fBm4 -D VER m4src\fR
 606 .fi
 607 .in -2
 608 .sp
 609
 610 .sp
 611 .LP
 612 produces the output:
 613
 614 .sp
 615 .in +2
 616 .nf
 617 The value of VER is "".
 618         VER is defined to be .
 619
 620         VER is not 2.
 621         end
 622 .fi
 623 .in -2
 624 .sp
 625
 626 .sp
 627 .LP
 628 The command:
 629
 630 .sp
 631 .in +2
 632 .nf
 633 \fBm4 -D VER=1 m4src\fR
 634 .fi
 635 .in -2
 636 .sp
 637
 638 .sp
 639 .LP
 640 produces the output:
 641
 642 .sp
 643 .in +2
 644 .nf
 645 The value of VER is "1".
 646        VER is defined to be 1.
 647        VER is 1.
 648        VER is not 2.
 649        end
 650 .fi
 651 .in -2
 652 .sp
 653
 654 .sp
 655 .LP
 656 The command:
 657
 658 .sp
 659 .in +2
 660 .nf
 661 \fBm4 -D VER=2 m4src\fR
 662 .fi
 663 .in -2
 664 .sp
 665
 666 .sp
 667 .LP
 668 produces the output:
 669
 670 .sp
 671 .in +2
 672 .nf
 673 The value of VER is "2".
 674         VER is defined to be 2.
 675
 676         VER is 2.
 677         end
 678 .fi
 679 .in -2
 680 .sp
 681
 682 .SH ENVIRONMENT VARIABLES
 683 .sp
 684 .LP
 685 See \fBenviron\fR(5) for descriptions of the following environment variables
 686 that affect the execution of \fBm4\fR: \fBLANG\fR, \fBLC_ALL\fR,
 687 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 688 .SH EXIT STATUS
 689 .sp
 690 .LP
 691 The following exit values are returned:
 692 .sp
 693 .ne 2
 694 .na
 695 \fB\fB0\fR\fR
 696 .ad
 697 .RS 6n
 698 Successful completion.
 699 .RE
 700
 701 .sp
 702 .ne 2
 703 .na
 704 \fB\fB>0\fR\fR
 705 .ad
 706 .RS 6n
 707 An error occurred
 708 .RE
 709
 710 .sp
 711 .LP
 712 If the \fBm4exit\fR macro is used, the exit value can be specified by the input
 713 file.
 714
 715 .SH ATTRIBUTES
 716 .sp
 717 .LP
 718 See \fBattributes\fR(5) for descriptions of the following attributes:
 719 .SS "\fB/usr/bin/m4\fR"
 720 .sp
 721
 722 .sp
 723 .TS
 724 box;
 725 c | c
 726 l | l .
 727 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 728 _
 729 Interface Stability     Standard
 730 .TE
 731
 732 .SH SEE ALSO
 733 .sp
 734 .LP
 735 \fBas\fR(1), \fBattributes\fR(5), \fBenviron\fR(5), \fBstandards\fR(5)