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