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