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