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