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