manual/gnumaniak/original/man1/gprof.1

   1 .\" You may copy, distribute and modify under the terms of the LDP General
   2 .\" Public License as specified in the LICENSE file that comes with the
   3 .\" gnumaniak distribution
   4 .\"
   5 .\" The author kindly requests that no comments regarding the "better"
   6 .\" suitability or up-to-date notices of any info documentation alternative
   7 .\" is added without contacting him first.
   8 .\"
   9 .\" (C) 2000 Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>
  10 .\"
  11 .\"     gprof man page
  12 .\"     man pages are NOT obsolete!
  13 .\"     <ragnar@ragnar-hojland.com>
  14 .TH GASP 1 "November 2000" "gprof 2.10.1"
  15 .SH NAME
  16 \fBgprof\fR \- GNU Profiler
  17 .SH SYNOPSIS
  18 .B gprof
  19 .RB [ \-abchilsTvwxyzDLT ]
  20 .RB [ \-efnpqACEFJNOPQZ [ \fINAME\fR ]]
  21 .RB [ "\-I \fIDIRS\fR" ]
  22 .RB [ \-d [ \fINUMBER\fR ]]
  23 .RB [ "\-k \fIFROM\fB/\fITO\fR" ]]
  24 .RB [ "\-m \fIMIN_COUNT\fR" ]
  25 .RB [ "\-t \fITABLE_LENGHT\fR" ]
  26
  27
  28 .RB [ \-\-unreasonable ]
  29 .I INFILE...
  30
  31 .B gasp
  32 .RB [ \-hv ]
  33 .RB [ \-\-help ]
  34 .RB [ \-\-version ]
  35 .SH DESCRIPTION
  36 .B gasp
  37 preprocesses each \fIINFILE\fR argument and concatenates the results to
  38 standard output, for direct consumption by \fBas\fR(1).
  39
  40 Since \fBas\fR is targeted to assemble the output generated by other
  41 programs, it doesn't have common facilities such as macros or conditionals
  42 that are generally useful when writing assembler by hand.  \fBgasp\fR
  43 provides this missing functionality.
  44 .SH OPTIONS
  45 .TP
  46 .B \-a, \-\-alternate
  47 Use alternative macro syntax.
  48 .TP
  49 .B \-c \fICHAR\fB, \-\-commentchar \fICHAR
  50 Use \fICHAR\fR as the comment character.  The default comment character
  51 is `\fB!\fR'.
  52 .TP
  53 .B \-d, \-\-debug
  54 Show debugging statistics about the string buffers that \fBgasp\fR allocates
  55 internally. For each defined buffersize \fIS\fR, it shows the number of
  56 strings \fIN\fR that it allocated, in the format
  57 .sp
  58 .nf
  59    strings size \fIS\fR : \fIN\fR
  60 .fi
  61 .sp
  62 These statistics are written to stderr, when done preprocessing.
  63 .TP
  64 .B \-o \fIOUTFILE\fB, \-\-output \fIOUTFILE
  65 Write the output generated by \fBgasp\fR to \fIOUTFILE\fR.  The default is
  66 to write to standard output.
  67 .TP
  68 .B \-p, \-\-print
  69 Print commented line numbers.  Ignored unless \fB\-s\fR is specified.
  70 .TP
  71 .B \-s, \-\-copysource
  72 Print commented source lines.
  73 .TP
  74 .B \-u, \-\-unreasonable
  75 Allow unlimited ("unreasonable") nested expansions.  Since you can define
  76 \fBgasp\fR macros inside other macro definitions, the preprocessor normally
  77 includes a sanity check.  If you require more than 1000 nested expansions,
  78 \fBgasp\fR normally exits with an error message.  Use this option to turn
  79 off this check, allowing unlimited nested expansions.
  80 .TP
  81 .B \-M, \-\-mri
  82 Enter MRI compatibility mode, required to use the Microtec Research ASM68K
  83 assembler syntax and pseudo ops.
  84 .TP
  85 .B \-D\fINAME\fB=\fIVALUE
  86 Define the preprocessor constant \fINAME\fR, with value \fIVALUE\fR.
  87 .TP
  88 .B \-I\fIPATH
  89 Add \fIPATH\fR to the include path list.
  90 .TP
  91 .B "\-h, \-\-help"
  92 Print a usage message on standard output and exit successfully.
  93 .TP
  94 .B "\-v, \-\-version"
  95 Print version information on standard output then exit successfully.
  96 .SH PREPROCESSOR COMMANDS
  97 Commands are case-insensitive, and each extends for a line divided in three
  98 fields:  an optional label, the command itself, and optional argument(s) to
  99 the command.
 100 .SS Conditionals
 101 These directives allow you to include or exclude portions of assembly
 102 depending on how a pair of strings or absolute expressions compare.  Max
 103 conditional nesting is 100.
 104 .TP
 105 .B .AIF \fIARG1 CMP ARG2
 106 .PD 0
 107 .TP
 108 .B .AIF \fB"\fIARG1\fB"\fI CMP \fB"\fIARG2\fB"
 109 .sp
 110 Available \fICMP\fR comparision operators available with strings and absolute
 111 expressions:
 112 .sp
 113 .RS
 114 .TP
 115 .B EQ
 116 Are \fIARG1\fR and \fIARG2\fR equal?
 117 .TP
 118 .B NE
 119 Are \fIARG1\fR and \fIARG2\fR different?
 120 .PP
 121 .sp
 122 Available \fICMP\fR comparision operators available with absolute
 123 expressions only:
 124 .sp
 125 .TP
 126 .B LT
 127 Is \fIARG1\fR less than \fIARG2?\fR
 128 .TP
 129 .B LE
 130 Is \fIARG1\fR less than or equal to \fIARG2\fR
 131 .TP
 132 .B GT
 133 Is \fIARG1\fR greater than \fIARG2\fR?
 134 .TP
 135 .B GE
 136 Is \fIARG1\fR greater than or equal to \fIARG2\fR?
 137 .RE
 138 .PD 1
 139 .TP
 140 .B .AELSE
 141 Marks the start of assembly code to be included if the condition
 142 fails.  Optional, and only allowed within a conditional (between
 143 \fB.AIF\fR and \fB.AENDI\fR)
 144 .TP
 145 .B .AENDI
 146 Marks the end of an \fB.AIF\fR conditional block.
 147 .PP
 148 .SS Loops
 149 These directives allow you repeat portions of code.
 150 .TP
 151 .B .AREPEAT \fIEXPR
 152 .PD 0
 153 .TP
 154 .B .AENDR
 155 .PD 1
 156 .br
 157 Repeats the assemby code between the \fB.AREPEAT\fR and \fB.AENDR\fR macros
 158 as many times as specified by the absolute expression \fIEXPR\fR.
 159 .TP
 160 .B .AWHILE \fIARG1 CMP ARG2
 161 .PD 0
 162 .TP
 163 .B .AENDW
 164 .PD 1
 165 .br
 166 Repeats the assembly code between the \fB.AWHILE\fR and \fB.AENDW\fR macros
 167 as long as the \fICMP\fR conditional comparision holds true.  The format for
 168 \fICMP\fR is the same as for \fB.AIF\fR.
 169 .TP
 170 .B .EXITM
 171 Break out of the loop.
 172 .SS Variables
 173 Variables can represent strings, registers or the results of expressions.
 174 There are two kinds of variables:
 175
 176 \fB\(bu\fR\ Variables defined with \fB.EQU\fR or \fB.ASSIGN\fR.  To evaluate
 177 this kind of variable in your assembly output, simply mention its name.
 178 These variabes are only evaluated when writing the assembly output, so they
 179 shouldn't be used in conditional expressions or \fB.AWHILE\fR loops.
 180 .sp
 181 .nf
 182    foo  .EQU   FLIP-64
 183    bar: .EQU   FLIP-64
 184    mov.l  foo, r0
 185 .fi
 186 .sp
 187 \fB\(bu\fR\ Variables for use during preprocessing, defined with
 188 .BR ".ASSIGNC" " or " ".ASSIGNA" .
 189 To evaluate this kind of variable, use the prefix `\fB\e&\fR'.
 190 .sp
 191 .nf
 192    opcit  .ASSIGNA  47
 193    .AWHILE \e&opcit GT 0
 194    .AENDW
 195 .fi
 196 .sp
 197 Macro arguments are treated almost the same way, but to evaluate them you
 198 use the prefix `\fB\e\fR' instead.
 199 .TP
 200 .B \fIPVAR\fB .EQU \fIEXPR
 201 Assign preprocessor variable PVAR the value of the expression
 202 EXPR.  No restrictions on redefinition.
 203 .TP
 204 .B \fIPVAR\fB .ASSIGN \fIEXPR
 205 Like \fB.EQU\fR, but you may not redefine \fIPVAR\fB.
 206 .TP
 207 .B \fIPVAR\fB .ASSIGNA \fIAEXPR
 208 Define a variable with a numeric value, for use during
 209 preprocessing.  \fIAEXPR\fR must be an absolute
 210 expression.  No restrictions on redefinition.
 211 .TP
 212 .B \fIPVAR\fB .ASSIGNC "\fISTR\fR"
 213 Define a variable with a string value, for use during
 214 preprocessing.  No restrictions on redefinition.
 215 .TP
 216 .B \fIPVAR\fB .REG (\fIREGISTER\fB)
 217 Define a variable that represents a register.  In particular, \fIREGISTER\fR
 218 is \fBnot evaluated\fR as an expression. No restrictions on redefinition.
 219 .PP
 220 All these directives accept the variable name in the "label"
 221 position, that is at the left margin.  You may specify a colon after
 222 the variable name if you wish, as in `bar' above.
 223 .SS Macro Definition
 224 The directives \fB.MACRO\fR and \fB.ENDM\fR allow you to define your own
 225 macros that generate assembly output.
 226 .TP
 227 .B .MACRO \fINAME
 228 .PD 0
 229 .TP
 230 .B .MACRO \fINAME \fR[\fBARG\fR[\fB=\fIDEFAULT_VALUE\fR]\fB, ...\fR]
 231 .PD 1
 232 Begin the definition of a macro called \fINAME\fR.  If your macro
 233 definition requires arguments, specify their names after the macro
 234 name, separated by commas or spaces.
 235
 236 When you call a macro, you can specify the argument
 237 values either by position, or by keyword.  For example, `SUM 9, 17' is
 238 equivalent to `SUM TO=17, FROM=9'.  Macro arguments are preprocessor
 239 variables similar to the variables you define with
 240 .BR .ASSIGNA " or " .ASSIGNC ", "
 241 so you can use them in conditionals or loop control.  The only
 242 difference is the prefix you write to evaluate
 243 the variable: for a macro argument use `\fB\eARG\fR', but for a
 244 preprocessor variable use `\fB\e&VAR\fR'.
 245 .TP
 246 .B \fINAME\fB .MACRO
 247 .PD 0
 248 .TP
 249 .B \fINAME\fB .MACRO ( \fR[\fBARG\fR[\fB=\fIDEFAULT_VALUE\fR]\fB, ...\fR]\fB )
 250 .PD 1
 251 An alternative form of introducing a macro definition: specify the
 252 macro name in the label position, and any arguments
 253 between parentheses after the name.
 254 .TP
 255 .B .ENDM
 256 Mark the end of a macro definition.
 257 .TP
 258 .B .EXITM
 259 Exit early from the current macro definition, or macro loop.
 260 .TP
 261 .B \e@
 262 This pseudo-variable represents the number of macros \fBgasp\fR  has
 263 executed.  You may use this variable only within a macro definition.
 264 .TP
 265 .B LOCAL \fINAME\fR[\fB, \fINAME...\fR]
 266 Generate an unique string for each \fINAME\fR argument, and replace any
 267 instances of \fINAME\fR in macro expansions.
 268
 269 This allows you to write macros that define symbols without fear of conflict
 270 between macro expansions, since the strings are different for each expansion.
 271
 272 Only available if you specify \fB\-\-alternate\fB.
 273 .SS Data
 274 These directives allow you to specify working areas of memory.
 275 The directives that initialize memory are:
 276 .TP
 277 .B .DATA \fIEXPR\fR[\fB, \fIEXPR...\fR]
 278 .PD 0
 279 .TP
 280 .B .DATA.B \fIEXPR\fR[\fB, \fIEXPR...\fR]
 281 .TP
 282 .B .DATA.W \fIEXPR\fR[\fB, \fIEXPR...\fR]
 283 .TP
 284 .B .DATA.L \fIEXPR\fR[\fB, \fIEXPR...\fR]
 285 .PD 1
 286 Evaluate arithmetic \fIEXPR\fR expressions, and emit the corresponding
 287 \fBas\fR directive (labelled with \fBLAB\fR).  The unqualified \fB.DATA\fR
 288 emits \fB.long\fR; \fB.DATA.B\fR emits \fB.byte\fR; \fB.DATA.W\fR emits
 289 \fB.short\fR; and \fB.DATA.L\fR emits \fB.long\fR.
 290
 291 For example, `foo .DATA 1,2,3' emits `foo: .long 1,2,3'.
 292 .TP
 293 .B .DATAB \fIREPEAT\fB, \fIEXPR
 294 .PD 0
 295 .TP
 296 .B .DATAB.B \fIREPEAT\fB, \fIEXPR
 297 .TP
 298 .B .DATAB.W \fIREPEAT\fB, \fIEXPR
 299 .TP
 300 .B .DATAB.L \fIREPEAT\fB, \fIEXPR
 301 .PD 1
 302 Emit \fIREPEAT\fR copies of the value of the expression \fIEXPR\fR
 303 (using the \fBas\fR directive \fB.fill\fR), being \fIREPEAT\fR an absolute
 304 expression with an absolute value.  \fB.DATAB.B\fR repeats one-byte
 305 values; \fB.DATAB.W\fR repeats two-byte values; and \fB.DATAB.L\fR repeats
 306 four-byte values.  \fB.DATAB\fR without a suffix repeats four-byte
 307 values, just like \fB.DATAB.L\fR.
 308 .TP
 309 .B .SDATA\ "\fISTR\fB"\fI...
 310 String data.  Emits a concatenation of bytes (no end of string marks are
 311 added, unlike in \fB.SDATAZ\fR) of each \fISTR\fR argument given, and
 312 optionally separated by commas.
 313 .TP
 314 .B .SDATAB \fIREPEAT\fB,\ "\fISTR\fB"\fI...
 315 Repeated string data.  \fIREPEAT\fR specifies how many
 316 copies of the concatenation of every \fISTR\fR argument are emitted.
 317 .TP
 318 .B .SDATAZ\ "\fISTR\fR"\fI...
 319 Zero-terminated string data.  Like \fB.SDATA\fR, except that
 320 a zero byte is written at the end of the string.
 321 .TP
 322 .B .SDATAC\ "\fISTR\fR"\fI...
 323 Count-prefixed string data.  Like \fB.SDATA\fR, but precede the string with
 324 a leading one-byte count.  For example, `.SDATAC "HI"' generates `.byte
 325 2,72,73'.  Since the count field is only one byte, you can only use
 326 \fB.SDATAC\fR for strings less than 256 bytes in length.
 327 .PP
 328 Use the
 329 .BR .RES ", " .SRES ", " .SRESC ", and " .SRESZ
 330 directives to reserve memory and leave it uninitialized.  \fBgasp\fR
 331 resolves these directives to appropriate calls of the GNU \fBas .space\fR
 332 directive.
 333 .TP
 334 .B .RES \fICOUNT
 335 .PD 0
 336 .TP
 337 .B .RES.B \fICOUNT
 338 .TP
 339 .B .RES.W \fICOUNT
 340 .TP
 341 .B .RES.L \fICOUNT
 342 .PD 1
 343 Reserve room for \fICOUNT\fR uninitialized elements of data.  The suffix
 344 specifies the size of each element: \fB.RES.B\fR reserves \fICOUNT\fR bytes,
 345 .B .RES.W
 346 reserves \fBCOUNT\fR pairs of bytes, and
 347 .B .RES.L
 348 reserves
 349 \fICOUNT\fR quartets.
 350 .B .RES
 351 without a suffix is equivalent to
 352 .B .RES.L
 353 .TP
 354 .B .SRES \fICOUNT
 355 .PD 0
 356 .TP
 357 .B .SRES.B \fICOUNT
 358 .TP
 359 .B .SRES.W \fICOUNT
 360 .TP
 361 .B .SRES.L \fICOUNT
 362 .PD 1
 363 .B .SRES
 364 is a synonym for
 365 .BR .RES .
 366 .TP
 367 .B .SRESC \fICOUNT
 368 .PD 0
 369 .TP
 370 .B .SRESC.B \fICOUNT
 371 .TP
 372 .B .SRESC.W \fICOUNT
 373 .TP
 374 .B .SRESC.L \fICOUNT
 375 .PD 1
 376 Like \fB.SRES\fR, but reserves space for `\fICOUNT\fR+1' elements.
 377 .TP
 378 .B .SRESZ \fICOUNT
 379 .PD 0
 380 .TP
 381 .B .SRESZ.B \fICOUNT
 382 .TP
 383 .B .SRESZ.W \fICOUNT
 384 .TP
 385 .B .SRESZ.L \fICOUNT
 386 .PD 1
 387 .B .SRESZ
 388 is a synonym for
 389 .BR .SRESC .
 390 .SS Listings
 391 These directives control \fBas\fR listing directives.
 392 .TP
 393 .B .PRINT LIST
 394 .PD 0
 395 .TP
 396 .B .PRINT NOLIST
 397 .PD 1
 398 Emits \fB.list\fR or \fB.nolist\fR, according to its argument.
 399 .TP
 400 .B .FORM LIN=\fILN
 401 .PD 0
 402 .TP
 403 .B .FORM COL=\fICOLS
 404 .TP
 405 .B .FORM LIN=\fILN\fB COL=\fICOLS\fR
 406 .PD 1
 407 Specify the page size for assembly listings, of \fILN\fR lines and
 408 \fICOLS\fR columns (default: 60x132).  You may specify either, or both.
 409 Any values you may have specified in previous instances of \fB.FORM\fR do
 410 not carry over as defaults.  Emits the
 411 .B .psizef
 412 GNU \fBas\fR directive.
 413 .TP
 414 .B .HEADING \fISTRING
 415 Specify \fISTRING\fR as the title of your assembly listings.  Emits
 416 `\fB.title "\fISTRING\fB"\fR'.
 417 .TP
 418 .B .PAGE
 419 Force a new page in the listing.  Emits \fB.eject\fR.
 420 .SH MISCELLANEOUS COMMANDS
 421 .TP
 422 .B .ALTERNATE
 423 Use the alternate macro syntax henceforth in the assembly.
 424 .TP
 425 .B .ORG
 426 This command is recognized, but not yet implemented.  \fBgasp\fR
 427 generates an error message for programs that use \fB.ORG\fR.
 428 .TP
 429 .B .RADIX \fIS\fR
 430 Specify the default radix for numbers without an explicitly encoded base
 431 (default: \fBD\fR). \fIS\fR is a case-insensitive letter:
 432 .RS
 433 .TP
 434 .B .RADIX B
 435 Base 2.
 436 .TP
 437 .B .RADIX Q
 438 Base 8.
 439 .TP
 440 .B .RADIX D
 441 Base 10.
 442 .TP
 443 .B .RADIX H
 444 Base 16.
 445 .RE
 446 .TP
 447 .B .EXPORT \fINAME
 448 .PD 0
 449 .TP
 450 .B .GLOBAL \fINAME
 451 .PD 1
 452 Declare \fINAME\fR global (emits \fB.global \fINAME\fR).
 453 .TP
 454 .B .PROGRAM
 455 Ignored.
 456 .TP
 457 .B .END
 458 Mark end of each preprocessor file.  A warning is issued if the end of file
 459 is reached without seeing this command.
 460 .TP
 461 .B .INCLUDE "\fISTR\fB"
 462 Preprocess the filename \fISTR\fR as if its contents appeared
 463 where the \fB.INCLUDE\fR directive does.  Maximum include depth is 30.
 464 .TP
 465 .B .ALIGN \fISIZE
 466 Evaluate the absolute expression \fISIZE\fR, and emit
 467 \fB.align \fIevaluated_expression\fR.
 468 .SH GASP SYNTAX
 469 Whitespace (blanks or tabs; not newlines) is partially significant, in that
 470 it delimits up to three fields in a line.  The amount of whitespace does
 471 not matter.
 472
 473 \fB\(bu\fR\ First field, an optional "label", must be flush left in a line
 474 (with no leading whitespace) if it appears at all, with an optional colon
 475 after the label name.
 476
 477 \fB\(bu\fR\ Second field, which must appear after some whitespace,
 478 contains a \fBgasp\fR or \fBas\fR directive.
 479
 480 \fB\(bu\fR\ Further fields on a line are arguments to the directive,
 481 separated by either commas or whitespace.
 482 .SS Special syntactic markers
 483 \fBgasp\fR recognizes a few special markers: to delimit comments, to
 484 continue a statement on the next line, to separate symbols from other
 485 characters, and to copy text to the output literally  (One other
 486 special marker, `\fB\@f\fR', works only within macro definitions)
 487
 488 The trailing part of any source line may be a comment.  A
 489 comment begins with the first unquoted comment character (`\fB!\fR' by
 490 default), or an escaped or doubled comment character (`\fB\e!\fR' or
 491 `\fB!!\fR' by default), and extends to the end of a line.  The two kinds of
 492 comment markers lead to slightly different treatment:
 493 .RS
 494 .TP
 495 .B !
 496 A single, un-escaped comment character generates an assembly
 497 comment in the \fBgasp\fR output.  \fBgasp\fR evaluates any preprocessor
 498 variables (macro arguments, or variables defined with
 499 .BR .ASSIGNA " or " .ASSIGNC )
 500 present.  For example, a macro that begins like this
 501 .sp
 502 .nf
 503    .MACRO  SUM FROM=0, TO=9
 504    ! \eFROM \eTO
 505 .fi
 506 .sp
 507 issues as the first line of output a comment that records the values you
 508 used to call the macro.
 509 .TP
 510 .B \e!
 511 .PD 0
 512 .TP
 513 .B !!
 514 .PD 1
 515 Either an escaped comment character, or a double comment character,
 516 marks a \fBgasp\fR source comment.  \fBgasp\fR does not copy such comments to
 517 the assembly output.
 518 .RE
 519
 520 To continue a statement on the next line of the file, begin the
 521 second line with the character `\fB+\fR'.
 522 Occasionally you may want to prevent \fBgasp\fR from preprocessing some
 523 particular bit of text.  To \fBcopy literally\fR from the \fBgasp\fR source to
 524 its output, place `\fB\e(\fR' before the string to copy, and `\fB)\fR' at the end.
 525 For example, write `\e(\e!)' if you need the characters `\fB\e!\fR' in your
 526 assembly output.
 527
 528 To separate a preprocessor variable from text to appear
 529 immediately after its value, write a single quote ('\fB'\fR').  For example,
 530 `.SDATA "\P'1"' writes a string built by concatenating the value of `P'
 531 and the digit `1'  (You cannot achieve this by writing just `\eP1',
 532 since `P1' is itself a valid name for a preprocessor variable)
 533 .SS String and numeric constants
 534 There are two ways of writing string constants: as literal
 535 text, and by numeric byte value.  Specify a string literal between
 536 double quotes (\fB"\fISTR\fB"\fR).  Specify an individual numeric byte value as
 537 an absolute expression between angle brackets (\fB<\fIEXPR\fB>\fR).  Directives
 538 that output strings allow you to specify any number of either kind of
 539 value, in whatever order is convenient, and concatenate the result.
 540
 541 You can write numeric constants either in a specific base, or in
 542 whatever base is currently selected by the last \fB.RADIX\fR directive.
 543
 544 To write a number in a specific base, use the pattern `\fIS\fB'\fIDDD\fR': a
 545 base specifier character \fIS\fR, followed by a single quote followed by
 546 digits \fIDDD\fR.  The base specifier character matches those you can specify
 547 with \fB.RADIX\fR.
 548 .SS Symbols
 549 Valid symbols start with any alphabetic character, `\fB_\fR' or `\fB$\fR',
 550 and continue with any of them or with digits.
 551 .SS Arithmetic Expressions
 552 There are two kinds of expressions, depending on their result:
 553 absolute expressions, which resolve to a constant (that is, they do
 554 not involve any values unknown to \fBgasp\fR), and relocatable expressions,
 555 which must reduce to the form
 556 .sp
 557 .nf
 558    \fIADDSYM\fB+\fICONST\fB-\fISUBSYM
 559 .fi
 560 .sp
 561 where \fIADDSYM\fR and \fISUBSYM\fR are assembly symbols of unknown value, and
 562 \fICONST\fR is a constant.
 563
 564 Arithmetic for \fBgasp\fR expressions follows very similar rules to C.
 565 You can use parentheses to change precedence; otherwise, arithmetic
 566 primitives have decreasing precedence in the order of the following
 567 list.
 568
 569 \fB\(bu\fR\ 1. Single-argument `+' (identity), `-' (arithmetic opposite), or `~'
 570 (bitwise negation).  The argument must be an absolute expression.
 571
 572 \fB\(bu\fR\ 2. `*' (multiplication) and `/' (division).  Both
 573 arguments must be absolute expressions.
 574
 575 \fB\(bu\fR\ 3. `+' (addition) and `-' (subtraction).  At least one argument must
 576 be absolute.
 577
 578 \fB\(bu\fR\ 4. `&' (bitwise and).  Both arguments must be absolute.
 579
 580 \fB\(bu\fR\ 5. `|' (bitwise or) and `~' (bitwise exclusive or; `^' in C).
 581 Both arguments must be absolute.
 582 .SS String Primitives
 583 You can use these primitives to manipulate strings (in the argument
 584 field of \fBgasp\fR statements):
 585 .TP
 586 .B .LEN("\fISTR\fB")
 587 Calculate the length of string \fB"\fISTR\fB"\fR, as an absolute expression.
 588 For example, `.RES.B .LEN("sample")' reserves six bytes of memory.
 589 .TP
 590 .B .INSTR("\fISTR\fB", "\fISEG\fB", \fIIX\fB)
 591 Search for the first occurrence of \fISEG\fR after position \fIIX\fR of
 592 \fISTR\fR.  The result is -1 if \fISEG\fR does not occur in \fISTR\fR after
 593 position \fIIX\fR.
 594 .TP
 595 .B .SUBSTR("\fISTR\fB", \fISTART\fB, \fILEN\fB)
 596 The substring of \fISTR\fR beginning at byte number \fISTART\fR and
 597 extending for \fILEN\fR bytes.
 598 .SH ALTERNATE MACRO SYNTAX
 599 When the \fB\-\-alternate\fR option is specified, an alternate macro sytax
 600 is used by \fBgasp\fR.  This syntax reminiscent of the syntax of Phar Lap
 601 macro assembler, but it is not meant to be a full emulation of Phar Lap or
 602 similar assemblers.  In particular, \fBgasp\fR does not support directives
 603 such as DB and IRP.
 604
 605 \fB\(bu\fR\ You can use preprocessor directives without a leading `\fB.\fR'
 606 dot.  For example, you can write `SDATA' with the same effect as .SDATA'.
 607
 608 \fB\(bu\fR\ LOCAL is available.
 609
 610 \fB\(bu\fR\ You can write strings delimited like "STRING", 'STRING', or <STRING>
 611
 612 \fB\(bu\fR\ To include any single character literally in a string (even if the
 613 character would otherwise have some special meaning), you can
 614 prefix the character with `\fB!\fR'.  For example, `"hello !"world!"".
 615
 616 \fB\(bu\fR\ You can write \fB%\fIEXPR\fR to evaluate the expression
 617 \fIEXPR\fR and use the result as a string.
 618
 619 .SH EXAMPLES
 620 If we feed \fBfasp\fR with this
 621 .sp
 622 .nf
 623            .MACRO  saveregs from=8 to=14
 624    count   .ASSIGNA \efrom
 625            ! save r\efrom..r\eto
 626            .AWHILE  \e&count LE \eto
 627            mov     r\e&count,@-sp
 628    count   .ASSIGNA  \e&count + 1
 629            .AENDW
 630            .ENDM
 631
 632            saveregs from=12
 633
 634    bar:    mov     #H'dead+10,r0
 635    foo     .SDATAC "hello"<10>
 636            .END
 637 .fi
 638 .sp
 639 it generates this GNU \fBas\fR code:
 640 .sp
 641 .nf
 642            ! save r12..r14
 643            mov     r12,@-sp
 644            mov     r13,@-sp
 645            mov     r14,@-sp
 646
 647    bar:    mov     #57005+10,r0
 648    foo:    .byte   6,104,101,108,108,111,10
 649 .fi
 650 .SH SEE ALSO
 651  \fBas\fR(1)
 652 .SH NOTES
 653 Report bugs to <bug-gnu-utils@gnu.org> and <hjl@lucon.org>
 654 .br
 655 Man page by Ragnar Hojland Espinosa <ragnar@ragnar-hojland.com>