usr.bin/indent/indent.1

   1 .\" Copyright (c) 1980, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\" Copyright (c) 1976 Board of Trustees of the University of Illinois.
   4 .\" All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)indent.1    8.1 (Berkeley) 7/1/93
  31 .\" $FreeBSD: head/usr.bin/indent/indent.1 334944 2018-06-11 05:35:57Z pstef $
  32 .\"
  33 .Dd April 23, 2019
  34 .Dt INDENT 1
  35 .Os
  36 .Sh NAME
  37 .Nm indent
  38 .Nd indent and format C program source
  39 .Sh SYNOPSIS
  40 .Nm
  41 .Op Ar input-file Op Ar output-file
  42 .Op Fl bacc | Fl nbacc
  43 .Op Fl bad | Fl nbad
  44 .Op Fl badp | Fl nbadp
  45 .Op Fl bap | Fl nbap
  46 .Op Fl bbb | Fl nbbb
  47 .Op Fl \&bc | Fl nbc
  48 .Op Fl \&bl | Fl \&br
  49 .Op Fl bs | Fl nbs
  50 .Op Fl c Ns Ar n
  51 .Op Fl \&cd Ns Ar n
  52 .Bk -words
  53 .Op Fl cdb | Fl ncdb
  54 .Ek
  55 .Op Fl \&ce | Fl nce
  56 .Op Fl \&ci Ns Ar n
  57 .Op Fl cli Ns Ar n
  58 .Op Fl cs | Fl ncs
  59 .Op Fl d Ns Ar n
  60 .Op Fl \&di Ns Ar n
  61 .Op Fl dj | Fl ndj
  62 .Bk -words
  63 .Op Fl ei | Fl nei
  64 .Op Fl eei | Fl neei
  65 .Ek
  66 .Bk -words
  67 .Op Fl fbs | Fl nfbs
  68 .Op Fl fc1 | Fl nfc1
  69 .Op Fl fcb | Fl nfcb
  70 .Ek
  71 .Op Fl i Ns Ar n
  72 .Op Fl \&ip | Fl nip
  73 .Op Fl l Ns Ar n
  74 .Op Fl \&lc Ns Ar n
  75 .Op Fl \&ldi Ns Ar n
  76 .Op Fl \&lp | Fl nlp
  77 .Op Fl \&lpl | Fl nlpl
  78 .Op Fl npro
  79 .Op Fl P Ns Ar file
  80 .Op Fl pcs | Fl npcs
  81 .Op Fl psl | Fl npsl
  82 .Op Fl \&sc | Fl nsc
  83 .Bk -words
  84 .Op Fl sob | Fl nsob
  85 .Ek
  86 .Op Fl \&st
  87 .Op Fl \&ta
  88 .Op Fl T Ns Ar typename
  89 .Op Fl ts Ns Ar n
  90 .Op Fl U Ns Ar file
  91 .Op Fl ut | Fl nut
  92 .Op Fl v | Fl \&nv
  93 .Op Fl -version
  94 .Sh DESCRIPTION
  95 The
  96 .Nm
  97 utility is a
  98 .Em C
  99 program formatter.
 100 It reformats the
 101 .Em C
 102 program in the
 103 .Ar input-file
 104 according to the switches.
 105 The switches which can be specified are described below.
 106 They may appear before or after the file names.
 107 .Pp
 108 .Sy NOTE :
 109 If you only specify an
 110 .Ar input-file ,
 111 the formatting is
 112 done `in-place', that is, the formatted file is written back into
 113 .Ar input-file
 114 and a backup copy of
 115 .Ar input-file
 116 is written in the current directory.
 117 If
 118 .Ar input-file
 119 is named
 120 .Sq Pa /blah/blah/file ,
 121 the backup file is named
 122 .Sq Pa file.BAK
 123 by default. The extension used for the backup file may be overridden using the
 124 .Ev SIMPLE_BACKUP_SUFFIX
 125 environment variable.
 126 .Pp
 127 If
 128 .Ar output-file
 129 is specified,
 130 .Nm
 131 checks to make sure that it is different from
 132 .Ar input-file .
 133 .Pp
 134 The options listed below control the formatting style imposed by
 135 .Nm .
 136 .Bl -tag -width Op
 137 .It Fl bacc , nbacc
 138 If
 139 .Fl bacc
 140 is specified, a blank line is forced around every conditional
 141 compilation block.
 142 For example, in front of every #ifdef and after every #endif.
 143 Other blank lines surrounding such blocks will be swallowed.
 144 Default:
 145 .Fl nbacc  .
 146 .It Fl bad , nbad
 147 If
 148 .Fl bad
 149 is specified, a blank line is forced after every block of
 150 declarations.
 151 Default:
 152 .Fl nbad .
 153 .It Fl badp , nbadp
 154 This is vaguely similar to
 155 .Fl bad
 156 except that it only applies to the first set of declarations
 157 in a procedure (just after the first `{') and it causes a blank
 158 line to be generated even if there are no declarations.
 159 The default is
 160 .Fl nbadp .
 161 .It Fl bap , nbap
 162 If
 163 .Fl bap
 164 is specified, a blank line is forced after every procedure body.
 165 Default:
 166 .Fl nbap .
 167 .It Fl bbb , nbbb
 168 If
 169 .Fl bbb
 170 is specified, a blank line is forced before every block comment.
 171 Default:
 172 .Fl nbbb .
 173 .It Fl \&bc , nbc
 174 If
 175 .Fl \&bc
 176 is specified, then a newline is forced after each comma in a declaration.
 177 .Fl nbc
 178 turns off this option.
 179 Default:
 180 .Fl \&nbc .
 181 .It Fl \&bl , \&br
 182 Specifying
 183 .Fl \&bl
 184 lines up compound statements like this:
 185 .Bd -literal -offset indent
 186 if (...)
 187 {
 188   code
 189 }
 190 .Ed
 191 .Pp
 192 Specifying
 193 .Fl \&br
 194 (the default) makes them look like this:
 195 .Bd -literal -offset indent
 196 if (...) {
 197   code
 198 }
 199 .Ed
 200 .It Fl bs , nbs
 201 Whether a blank should always be inserted after sizeof.
 202 The default is
 203 .Fl nbs .
 204 .It Fl c Ns Ar n
 205 The column in which comments on code start.
 206 The default is 33.
 207 .It Fl cd Ns Ar n
 208 The column in which comments on declarations start.
 209 The default is for these comments to start in the same column as those on code.
 210 .It Fl cdb , ncdb
 211 Enables (disables) the placement of comment delimiters on blank lines.
 212 With this option enabled, comments look like this:
 213 .Bd -literal -offset indent
 214         /*
 215          * this is a comment
 216          */
 217 .Ed
 218 .Pp
 219 Rather than like this:
 220 .Bd -literal -offset indent
 221         /* this is a comment */
 222 .Ed
 223 .Pp
 224 This only affects block comments, not comments to the right of code.
 225 The default is
 226 .Fl cdb .
 227 .It Fl ce , nce
 228 Enables (disables) forcing of `else's to cuddle up to the immediately preceding
 229 `}'.
 230 The default is
 231 .Fl \&ce .
 232 .It Fl \&ci Ns Ar n
 233 Sets the continuation indent to be
 234 .Ar n .
 235 Continuation
 236 lines will be indented that far from the beginning of the first line of the
 237 statement.
 238 Parenthesized expressions have extra indentation added to
 239 indicate the nesting, unless
 240 .Fl \&lp
 241 is in effect or the continuation indent is exactly half of the main indent.
 242 .Fl \&ci
 243 defaults to the same value as
 244 .Fl i .
 245 .It Fl cli Ns Ar n
 246 Causes case labels to be indented
 247 .Ar n
 248 tab stops to the right of the containing
 249 .Ic switch
 250 statement.
 251 .Fl cli0.5
 252 causes case labels to be indented half a tab stop.
 253 The default is
 254 .Fl cli0 .
 255 .It Fl cs , ncs
 256 Control whether parenthesized type names in casts are followed by a space or
 257 not.
 258 The default is
 259 .Fl ncs .
 260 .It Fl d Ns Ar n
 261 Controls the placement of comments which are not to the right of code.
 262 For example,
 263 .Fl \&d\&1
 264 means that such comments are placed one indentation level to the left of code.
 265 Specifying the default
 266 .Fl \&d\&0
 267 lines up these comments with the code.
 268 See the section on comment indentation below.
 269 .It Fl \&di Ns Ar n
 270 Specifies the indentation, in character positions,
 271 of global variable names and all struct/union member names
 272 relative to the beginning of their type declaration.
 273 The default is
 274 .Fl di16 .
 275 .It Fl dj , ndj
 276 .Fl \&dj
 277 left justifies declarations.
 278 .Fl ndj
 279 indents declarations the same as code.
 280 The default is
 281 .Fl ndj .
 282 .It Fl \&ei , nei
 283 Enables (disables) special
 284 .Ic else-if
 285 processing.
 286 If it is enabled, an
 287 .Ic if
 288 following an
 289 .Ic else
 290 will have the same indentation as the preceding
 291 .Ic \&if
 292 statement.
 293 The default is
 294 .Fl ei .
 295 .It Fl eei , neei
 296 Enables (disables) extra indentation on continuation lines of
 297 the expression part of
 298 .Ic if
 299 and
 300 .Ic while
 301 statements.
 302 These continuation lines will be indented one extra level.
 303 The default is
 304 .Fl neei .
 305 .It Fl fbs , nfbs
 306 Enables (disables) splitting the function declaration and opening brace
 307 across two lines.
 308 The default is
 309 .Fl fbs .
 310 .It Fl fc1 , nfc1
 311 Enables (disables) the formatting of comments that start in column 1.
 312 Often, comments whose leading `/' is in column 1 have been carefully
 313 hand formatted by the programmer.
 314 In such cases,
 315 .Fl nfc1
 316 should be used.
 317 The default is
 318 .Fl fc1 .
 319 .It Fl fcb , nfcb
 320 Enables (disables) the formatting of block comments (ones that begin
 321 with `/*\\n').
 322 Often, block comments have been not so carefully hand formatted by the
 323 programmer, but reformatting that would just change the line breaks is not
 324 wanted.
 325 In such cases,
 326 .Fl nfcb
 327 should be used.
 328 Block comments are then handled like box comments.
 329 The default is
 330 .Fl fcb .
 331 .It Fl i Ns Ar n
 332 The number of columns for one indentation level.
 333 The default is 8.
 334 .It Fl \&ip , nip
 335 Enables (disables) the indentation of parameter declarations from the left
 336 margin.
 337 The default is
 338 .Fl \&ip .
 339 .It Fl l Ns Ar n
 340 Maximum length of an output line.
 341 The default is 78.
 342 .It Fl lc Ns Ar n
 343 Maximum length of an output line in a block comment.
 344 The default is 0, which means to limit block comment lines in accordance with
 345 .Fl l .
 346 .It Fl \&ldi Ns Ar n
 347 Specifies the indentation, in character positions,
 348 of local variable names
 349 relative to the beginning of their type declaration.
 350 The default is for local variable names to be indented
 351 by the same amount as global ones.
 352 .It Fl \&lp , nlp
 353 Lines up code surrounded by parentheses in continuation lines.
 354 With
 355 .Fl \&lp ,
 356 if a line
 357 has a left paren which is not closed on that line, then continuation lines
 358 will be lined up to start at the character position just after the left
 359 paren.
 360 For example, here is how a piece of continued code looks with
 361 .Fl nlp
 362 in effect:
 363 .Bd -literal -offset indent
 364 p1 = first_procedure(second_procedure(p2, p3),
 365 \ \ third_procedure(p4, p5));
 366 .Ed
 367 .Pp
 368 With
 369 .Fl lp
 370 in effect (the default) the code looks somewhat clearer:
 371 .Bd -literal -offset indent
 372 p1\ =\ first_procedure(second_procedure(p2,\ p3),
 373 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,\ p5));
 374 .Ed
 375 .Pp
 376 Inserting two more newlines we get:
 377 .Bd -literal -offset indent
 378 p1\ =\ first_procedure(second_procedure(p2,
 379 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3),
 380 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,
 381 \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5));
 382 .Ed
 383 .It Fl \&lpl , nlpl
 384 With
 385 .Fl \&lpl ,
 386 code surrounded by parentheses in continuation lines is lined up even if it
 387 would extend past the right margin.
 388 With
 389 .Fl \&nlpl
 390 (the default), such a line that would extend past the right margin is moved
 391 left to keep it within the margin, if that does not require placing it to
 392 the left of the prevailing indentation level.
 393 These switches have no effect if
 394 .Fl nlp
 395 is selected.
 396 .It Fl npro
 397 Causes the profile files,
 398 .Sq Pa ./.indent.pro
 399 and
 400 .Sq Pa ~/.indent.pro ,
 401 to be ignored.
 402 .It Fl P Ns Ar file
 403 Read profile from
 404 .Ar file .
 405 .It Fl pcs , npcs
 406 If true
 407 .Pq Fl pcs
 408 all procedure calls will have a space inserted between the name and the `('.
 409 The default is
 410 .Fl npcs .
 411 .It Fl psl , npsl
 412 If true
 413 .Pq Fl psl
 414 the names of procedures being defined are placed in
 415 column 1 \- their types, if any, will be left on the previous lines.
 416 The default is
 417 .Fl psl .
 418 .It Fl \&sc , nsc
 419 Enables (disables) the placement of asterisks (`*'s) at the left edge of all
 420 comments.
 421 The default is
 422 .Fl sc .
 423 .It Fl sob , nsob
 424 If
 425 .Fl sob
 426 is specified, indent will swallow optional blank lines.
 427 You can use this to get rid of blank lines after declarations.
 428 Default:
 429 .Fl nsob .
 430 .It Fl \&st
 431 Causes
 432 .Nm
 433 to take its input from stdin and put its output to stdout.
 434 .It Fl ta
 435 Automatically add all identifiers ending in "_t" to the list
 436 of type keywords.
 437 .It Fl T Ns Ar typename
 438 Adds
 439 .Ar typename
 440 to the list of type keywords.
 441 Names accumulate:
 442 .Fl T
 443 can be specified more than once.
 444 You need to specify all the typenames that
 445 appear in your program that are defined by
 446 .Ic typedef
 447 \- nothing will be
 448 harmed if you miss a few, but the program will not be formatted as nicely as
 449 it should.
 450 This sounds like a painful thing to have to do, but it is really
 451 a symptom of a problem in C:
 452 .Ic typedef
 453 causes a syntactic change in the
 454 language and
 455 .Nm
 456 cannot find all
 457 instances of
 458 .Ic typedef .
 459 .It Fl ts Ns Ar n
 460 Assumed distance between tab stops.
 461 The default is 8.
 462 .It Fl U Ns Ar file
 463 Adds type names from
 464 .Ar file
 465 to the list of type keywords.
 466 .It Fl ut , nut
 467 Enables (disables) the use of tab characters in the output.
 468 The default is
 469 .Fl ut .
 470 .It Fl v , \&nv
 471 .Fl v
 472 turns on `verbose' mode;
 473 .Fl \&nv
 474 turns it off.
 475 When in verbose mode,
 476 .Nm
 477 reports when it splits one line of input into two or more lines of output,
 478 and gives some size statistics at completion.
 479 The default is
 480 .Fl \&nv .
 481 .It Fl -version
 482 Causes
 483 .Nm
 484 to print its version number and exit.
 485 .El
 486 .Pp
 487 You may set up your own `profile' of defaults to
 488 .Nm
 489 by creating a file called
 490 .Pa .indent.pro
 491 in your login directory and/or the current directory and including
 492 whatever switches you like.
 493 A `.indent.pro' in the current directory takes
 494 precedence over the one in your login directory.
 495 If
 496 .Nm
 497 is run and a profile file exists, then it is read to set up the program's
 498 defaults.
 499 Switches on the command line, though, always override profile switches.
 500 The switches should be separated by spaces, tabs or newlines.
 501 .Ss Comments
 502 .Sq Em Box
 503 .Em comments .
 504 The
 505 .Nm
 506 utility
 507 assumes that any comment with a dash or star immediately after the start of
 508 comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars.
 509 Each line of such a comment is left unchanged, except that its indentation
 510 may be adjusted to account for the change in indentation of the first line
 511 of the comment.
 512 .Pp
 513 .Em Straight text .
 514 All other comments are treated as straight text.
 515 The
 516 .Nm
 517 utility fits as many words (separated by blanks, tabs, or newlines) on a
 518 line as possible.
 519 Blank lines break paragraphs.
 520 .Ss Comment indentation
 521 If a comment is on a line with code it is started in the `comment column',
 522 which is set by the
 523 .Fl c Ns Ns Ar n
 524 command line parameter.
 525 Otherwise, the comment is started at
 526 .Ar n
 527 indentation levels less than where code is currently being placed, where
 528 .Ar n
 529 is specified by the
 530 .Fl d Ns Ns Ar n
 531 command line parameter.
 532 If the code on a line extends past the comment
 533 column, the comment starts further to the right, and the right margin may be
 534 automatically extended in extreme cases.
 535 .Ss Preprocessor lines
 536 In general,
 537 .Nm
 538 leaves preprocessor lines alone.
 539 The only reformatting that it will do is to straighten up trailing comments.
 540 It leaves embedded comments alone.
 541 Conditional compilation
 542 .Pq Ic #ifdef...#endif
 543 is recognized and
 544 .Nm
 545 attempts to correctly
 546 compensate for the syntactic peculiarities introduced.
 547 .Ss C syntax
 548 The
 549 .Nm
 550 utility understands a substantial amount about the syntax of C, but it
 551 has a `forgiving' parser.
 552 It attempts to cope with the usual sorts of incomplete and malformed syntax.
 553 In particular, the use of macros like:
 554 .Pp
 555 .Dl #define forever for(;;)
 556 .Pp
 557 is handled properly.
 558 .Sh ENVIRONMENT
 559 The
 560 .Nm
 561 utility uses the
 562 .Ev HOME
 563 environment variable.
 564 .Sh FILES
 565 .Bl -tag -width ".Pa /usr/share/misc/indent.pro" -compact
 566 .It Pa ./.indent.pro
 567 profile file
 568 .It Pa ~/.indent.pro
 569 profile file
 570 .It Pa /usr/share/misc/indent.pro
 571 example profile file
 572 .El
 573 .Sh HISTORY
 574 The
 575 .Nm
 576 command appeared in
 577 .Bx 4.2 .
 578 .Sh BUGS
 579 The
 580 .Nm
 581 utility has even more switches than
 582 .Xr ls 1 .
 583 .Pp
 584 A common mistake is to try to indent all the
 585 .Em C
 586 programs in a directory by typing:
 587 .Pp
 588 .Dl indent *.c
 589 .Pp
 590 This is probably a bug, not a feature.