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