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