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