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 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 specified are described below. 106They may appear before or after the file names. 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 123by default. The extension used for the backup file may be overridden using the 124.Ev SIMPLE_BACKUP_SUFFIX 125environment variable. 126.Pp 127If 128.Ar output-file 129is specified, 130.Nm 131checks to make sure that it is different from 132.Ar input-file . 133.Pp 134The options listed below control the formatting style imposed by 135.Nm . 136.Bl -tag -width Op 137.It Fl bacc , nbacc 138If 139.Fl bacc 140is specified, a blank line is forced around every conditional 141compilation block. 142For example, in front of every #ifdef and after every #endif. 143Other blank lines surrounding such blocks will be swallowed. 144Default: 145.Fl nbacc . 146.It Fl bad , nbad 147If 148.Fl bad 149is specified, a blank line is forced after every block of 150declarations. 151Default: 152.Fl nbad . 153.It Fl badp , nbadp 154This is vaguely similar to 155.Fl bad 156except that it only applies to the first set of declarations 157in a procedure (just after the first `{') and it causes a blank 158line to be generated even if there are no declarations. 159The default is 160.Fl nbadp . 161.It Fl bap , nbap 162If 163.Fl bap 164is specified, a blank line is forced after every procedure body. 165Default: 166.Fl nbap . 167.It Fl bbb , nbbb 168If 169.Fl bbb 170is specified, a blank line is forced before every block comment. 171Default: 172.Fl nbbb . 173.It Fl \&bc , nbc 174If 175.Fl \&bc 176is specified, then a newline is forced after each comma in a declaration. 177.Fl nbc 178turns off this option. 179Default: 180.Fl \&nbc . 181.It Fl \&bl , \&br 182Specifying 183.Fl \&bl 184lines up compound statements like this: 185.Bd -literal -offset indent 186if (...) 187{ 188 code 189} 190.Ed 191.Pp 192Specifying 193.Fl \&br 194(the default) makes them look like this: 195.Bd -literal -offset indent 196if (...) { 197 code 198} 199.Ed 200.It Fl bs , nbs 201Whether a blank should always be inserted after sizeof. 202The default is 203.Fl nbs . 204.It Fl c Ns Ar n 205The column in which comments on code start. 206The default is 33. 207.It Fl cd Ns Ar n 208The column in which comments on declarations start. 209The default is for these comments to start in the same column as those on code. 210.It Fl cdb , ncdb 211Enables (disables) the placement of comment delimiters on blank lines. 212With this option enabled, comments look like this: 213.Bd -literal -offset indent 214 /* 215 * this is a comment 216 */ 217.Ed 218.Pp 219Rather than like this: 220.Bd -literal -offset indent 221 /* this is a comment */ 222.Ed 223.Pp 224This only affects block comments, not comments to the right of code. 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 or 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 default is 254.Fl cli0 . 255.It Fl cs , ncs 256Control whether parenthesized type names in casts are followed by a space or 257not. 258The default is 259.Fl ncs . 260.It Fl d Ns Ar n 261Controls the placement of comments which are not to the right of code. 262For example, 263.Fl \&d\&1 264means that such comments are placed one indentation level to the left of code. 265Specifying the default 266.Fl \&d\&0 267lines up these comments with the code. 268See the section on comment indentation 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 used. 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 columns 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 parentheses in continuation lines. 354With 355.Fl \&lp , 356if a line 357has a left paren which is not closed on that line, then continuation lines 358will be lined up to start at the character position just after the left 359paren. 360For example, here is how a piece of continued code looks with 361.Fl nlp 362in effect: 363.Bd -literal -offset indent 364p1 = first_procedure(second_procedure(p2, p3), 365\ \ third_procedure(p4, p5)); 366.Ed 367.Pp 368With 369.Fl lp 370in effect (the default) the code looks somewhat clearer: 371.Bd -literal -offset indent 372p1\ =\ first_procedure(second_procedure(p2,\ p3), 373\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4,\ p5)); 374.Ed 375.Pp 376Inserting two more newlines we get: 377.Bd -literal -offset indent 378p1\ =\ first_procedure(second_procedure(p2, 379\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p3), 380\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ third_procedure(p4, 381\ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ p5)); 382.Ed 383.It Fl \&lpl , nlpl 384With 385.Fl \&lpl , 386code surrounded by parentheses in continuation lines is lined up even if it 387would extend past the right margin. 388With 389.Fl \&nlpl 390(the default), such a line that would extend past the right margin is moved 391left to keep it within the margin, if that does not require placing it to 392the left of the prevailing indentation level. 393These switches have no effect if 394.Fl nlp 395is selected. 396.It Fl npro 397Causes the profile files, 398.Sq Pa ./.indent.pro 399and 400.Sq Pa ~/.indent.pro , 401to be ignored. 402.It Fl P Ns Ar file 403Read profile from 404.Ar file . 405.It Fl pcs , npcs 406If true 407.Pq Fl pcs 408all procedure calls will have a space inserted between the name and the `('. 409The default is 410.Fl npcs . 411.It Fl psl , npsl 412If true 413.Pq Fl psl 414the names of procedures being defined are placed in 415column 1 \- their types, if any, will be left on the previous lines. 416The default is 417.Fl psl . 418.It Fl \&sc , nsc 419Enables (disables) the placement of asterisks (`*'s) at the left edge of all 420comments. 421The default is 422.Fl sc . 423.It Fl sob , nsob 424If 425.Fl sob 426is specified, indent will swallow optional blank lines. 427You can use this to get rid of blank lines after declarations. 428Default: 429.Fl nsob . 430.It Fl \&st 431Causes 432.Nm 433to take its input from stdin and put its output to stdout. 434.It Fl ta 435Automatically add all identifiers ending in "_t" to the list 436of type keywords. 437.It Fl T Ns Ar typename 438Adds 439.Ar typename 440to the list of type keywords. 441Names accumulate: 442.Fl T 443can be specified more than once. 444You need to specify all the typenames that 445appear in your program that are defined by 446.Ic typedef 447\- nothing will be 448harmed if you miss a few, but the program will not be formatted as nicely as 449it should. 450This sounds like a painful thing to have to do, but it is really 451a symptom of a problem in C: 452.Ic typedef 453causes a syntactic change in the 454language and 455.Nm 456cannot find all 457instances of 458.Ic typedef . 459.It Fl ts Ns Ar n 460Assumed distance between tab stops. 461The default is 8. 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. 468The default is 469.Fl ut . 470.It Fl v , \&nv 471.Fl v 472turns on `verbose' mode; 473.Fl \&nv 474turns it off. 475When in verbose mode, 476.Nm 477reports when it splits one line of input into two or more lines of output, 478and gives some size statistics at completion. 479The default is 480.Fl \&nv . 481.It Fl -version 482Causes 483.Nm 484to print its version number and exit. 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 switches. 500The switches should be separated by spaces, tabs or newlines. 501.Ss Comments 502.Sq Em Box 503.Em comments . 504The 505.Nm 506utility 507assumes that any comment with a dash or star immediately after the start of 508comment (that is, `/*\-' or `/**') is a comment surrounded by a box of stars. 509Each line of such a comment is left unchanged, except that its indentation 510may be adjusted to account for the change in indentation of the first line 511of the comment. 512.Pp 513.Em Straight text . 514All other comments are treated as straight text. 515The 516.Nm 517utility fits as many words (separated by blanks, tabs, or newlines) on a 518line as possible. 519Blank lines break paragraphs. 520.Ss Comment indentation 521If a comment is on a line with code it is started in the `comment column', 522which is set by the 523.Fl c Ns Ns Ar n 524command line parameter. 525Otherwise, the comment is started at 526.Ar n 527indentation levels less than where code is currently being placed, where 528.Ar n 529is specified by the 530.Fl d Ns Ns Ar n 531command line parameter. 532If the code on a line extends past the comment 533column, the comment starts further to the right, and the right margin may be 534automatically extended in extreme cases. 535.Ss Preprocessor lines 536In general, 537.Nm 538leaves preprocessor lines alone. 539The only reformatting that it will do is to straighten up trailing comments. 540It leaves embedded comments alone. 541Conditional compilation 542.Pq Ic #ifdef...#endif 543is recognized and 544.Nm 545attempts to correctly 546compensate for the syntactic peculiarities introduced. 547.Ss C syntax 548The 549.Nm 550utility understands a substantial amount about the syntax of C, but it 551has a `forgiving' parser. 552It attempts to cope with the usual sorts of incomplete and malformed syntax. 553In particular, the use of macros like: 554.Pp 555.Dl #define forever for(;;) 556.Pp 557is handled properly. 558.Sh ENVIRONMENT 559The 560.Nm 561utility uses the 562.Ev HOME 563environment variable. 564.Sh FILES 565.Bl -tag -width ".Pa /usr/share/misc/indent.pro" -compact 566.It Pa ./.indent.pro 567profile file 568.It Pa ~/.indent.pro 569profile file 570.It Pa /usr/share/misc/indent.pro 571example profile 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