1.\" 2.\" Copyright (c) 1999 The NetBSD Foundation, Inc. 3.\" All rights reserved. 4.\" 5.\" This code is derived from software contributed to The NetBSD Foundation 6.\" by Klaus Klein. 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.\" 17.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 18.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 21.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd July 24, 2022 30.Dt NL 1 31.Os 32.Sh NAME 33.Nm nl 34.Nd line numbering filter 35.Sh SYNOPSIS 36.Nm 37.Op Fl p 38.Bk -words 39.Op Fl b Ar type 40.Ek 41.Bk -words 42.Op Fl d Ar delim 43.Ek 44.Bk -words 45.Op Fl f Ar type 46.Ek 47.Bk -words 48.Op Fl h Ar type 49.Ek 50.Bk -words 51.Op Fl i Ar incr 52.Ek 53.Bk -words 54.Op Fl l Ar num 55.Ek 56.Bk -words 57.Op Fl n Ar format 58.Ek 59.Bk -words 60.Op Fl s Ar sep 61.Ek 62.Bk -words 63.Op Fl v Ar startnum 64.Ek 65.Bk -words 66.Op Fl w Ar width 67.Ek 68.Op Ar file 69.Sh DESCRIPTION 70The 71.Nm 72utility reads lines from the named 73.Ar file , 74applies a configurable line numbering filter operation, 75and writes the result to the standard output. 76If 77.Ar file 78is a single dash 79.Pq Sq Fl 80or absent, 81.Nm 82reads from the standard input. 83.Pp 84The 85.Nm 86utility treats the text it reads in terms of logical pages. 87Unless specified otherwise, line numbering is reset at the start of each 88logical page. 89A logical page consists of a header, a body and a footer 90section; empty sections are valid. 91Different line numbering options are 92independently available for header, body and footer sections. 93.Pp 94The starts of logical page sections are signalled by input lines containing 95nothing but one of the following sequences of delimiter characters: 96.Bl -column "\e:\e:\e:" "Start of" -offset indent 97.Em "Line Start of" 98.It "\e:\e:\e: header" 99.It "\e:\e: body" 100.It "\e: footer" 101.El 102.Pp 103If the input does not contain any logical page section signalling directives, 104the text being read is assumed to consist of a single logical page body. 105.Pp 106The following options are available: 107.Bl -tag -width ".Fl v Ar startnum" 108.It Fl b Ar type 109Specify the logical page body lines to be numbered. 110Recognized 111.Ar type 112arguments are: 113.Bl -tag -width indent 114.It Cm a 115Number all lines. 116.It Cm t 117Number only non-empty lines. 118.It Cm n 119No line numbering. 120.It Cm p Ns Ar expr 121Number only those lines that contain the basic regular expression specified 122by 123.Ar expr . 124.El 125.Pp 126The default 127.Ar type 128for logical page body lines is 129.Cm t . 130.It Fl d Ar delim 131Specify the delimiter characters used to indicate the start of a logical 132page section in the input file. 133At most two characters may be specified; 134if only one character is specified, the first character is replaced and the 135second character remains unchanged. 136The default 137.Ar delim 138characters are 139.Dq Li \e: . 140.It Fl f Ar type 141Specify the same as 142.Fl b Ar type 143except for logical page footer lines. 144The default 145.Ar type 146for logical page footer lines is 147.Cm n . 148.It Fl h Ar type 149Specify the same as 150.Fl b Ar type 151except for logical page header lines. 152The default 153.Ar type 154for logical page header lines is 155.Cm n . 156.It Fl i Ar incr 157Specify the increment value used to number logical page lines. 158The default 159.Ar incr 160value is 1. 161.It Fl l Ar num 162If numbering of all lines is specified for the current logical section 163using the corresponding 164.Fl b Cm a , 165.Fl f Cm a 166or 167.Fl h Cm a 168option, 169specify the number of adjacent blank lines to be considered as one. 170For example, 171.Fl l 1722 results in only the second adjacent blank line being numbered. 173The default 174.Ar num 175value is 1. 176.It Fl n Ar format 177Specify the line numbering output format. 178Recognized 179.Ar format 180arguments are: 181.Bl -tag -width indent -compact 182.It Cm ln 183Left justified. 184.It Cm rn 185Right justified, leading zeros suppressed. 186.It Cm rz 187Right justified, leading zeros kept. 188.El 189.Pp 190The default 191.Ar format 192is 193.Cm rn . 194.It Fl p 195Specify that line numbering should not be restarted at logical page delimiters. 196.It Fl s Ar sep 197Specify the characters used in separating the line number and the corresponding 198text line. 199The default 200.Ar sep 201setting is a single tab character. 202.It Fl v Ar startnum 203Specify the initial value used to number logical page lines; see also the 204description of the 205.Fl p 206option. 207The default 208.Ar startnum 209value is 1. 210.It Fl w Ar width 211Specify the number of characters to be occupied by the line number; 212in case the 213.Ar width 214is insufficient to hold the line number, it will be truncated to its 215.Ar width 216least significant digits. 217The default 218.Ar width 219is 6. 220.El 221.Sh ENVIRONMENT 222The 223.Ev LANG , LC_ALL , LC_CTYPE 224and 225.Ev LC_COLLATE 226environment variables affect the execution of 227.Nm 228as described in 229.Xr environ 7 . 230.Sh EXIT STATUS 231.Ex -std 232.Sh EXAMPLES 233Number all non-blank lines: 234.Bd -literal -offset indent 235$ echo -e "This is\\n\\n\\na simple text" | nl 236 1 This is 237 238 239 2 a simple text 240.Ed 241.Pp 242Number all lines including blank ones, with right justified line numbers with 243leading zeroes, starting at 2, with increment of 2 and a custom multi-character 244separator: 245.Bd -literal -offset indent 246$ echo -e "This\\nis\\nan\\n\\n\\nexample" | nl -ba -n rz -i2 -s "->" -v2 247000002->This 248000004->is 249000006->an 250000008-> 251000010-> 252000012->example 253.Ed 254.Pp 255Number lines matching regular expression for an 256.Em i 257.No followed by either 258.Em m 259.No or 260.Em n 261.Bd -literal -offset indent 262$ echo -e "This is\\na simple text\\nwith multiple\\nlines" | nl -bp'i[mn]' 263 This is 264 1 a simple text 265 with multiple 266 2 lines 267.Ed 268.Sh SEE ALSO 269.Xr jot 1 , 270.Xr pr 1 271.Sh STANDARDS 272The 273.Nm 274utility conforms to 275.St -p1003.1-2001 . 276.Sh HISTORY 277The 278.Nm 279utility first appeared in 280.At III . 281.Sh BUGS 282Input lines are limited to 283.Dv LINE_MAX 284(2048) bytes in length. 285