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