POSIX V11.0 (en)

&pagelevel(4)&pagelevel

The nl command reads lines from a file or the standard input and writes them on the standard output with line numbering.

nl views the text it reads in terms of logical pages. A logical page consists of a header, a body, and a footer section. Empty sections are valid.

The start of a header, body, and footer of a logical page is normally signaled by an input line containing nothing but one of the following strings:

`\:\:\:`	for start of header
`\:\:`	for start of body
`\:`	for start of footer

If the input text does not contain any delimiter characters, nl assumes that the text being read is in a single logical page body.

Line numbering is reset at the start of a logical page (exception: option -p). Different line numbering options are independently available for header, body, and footer (e.g. no numbering of header and footer lines, while numbering blank lines only in the body).

Syntax

nl[ option]...[ file]

No option specified

nl numbers all logical page body lines that contain printable text, but not header and footer lines.

Line numbering is reset to 1 at the start of each logical page.

Within a logical page, nl numbers lines in increments of 1.

Each line number may be up to 6 positions long and is output right justified without leading zeros. A tab is used to separate line numbers from text.

option

The options must be entered individually, i.e. separated from other options by blanks.

The name of the file may be specified before, between, or after the options. The position of the file name in the command line has no effect on the operation of the nl command.

Selecting the lines to be numbered

-b type

(b -body) Specifies which logical page body lines are to be numbered.

type can be any of: a, n, preg_expr, or t.

a

All lines are numbered.

n

No lines are numbered.

preg_expr

Numbers all lines containing strings that match the given reg_expr.

reg_expr is a simple regular expression (see Tables and Dirctories, Regular POSIX shell expressions).

If the specified regular expression contains shell metacharacters, it must be enclosed in single quotes: p'reg_expr'.

t

All lines with printable text are numbered.

-b not specified:
Only the lines with printable text are numbered. Option -b with the t argument is thus the default.

-f type

(f- footer)

Specifies which logical page footer lines are to be numbered.

type may be: a, n, preg_expr, or t.

-f not specified:
Logical page footer lines are not numbered. Option -f with the n argument is thus the default.

-h type

(h - header)

Specifies which logical page header lines are to be numbered.

type may be: a, n, preg_expr, or t.

-h not specified:
Logical page header lines are not numbered. Option -h with the n argument is thus the default.

Restarting line numbering

-p

Line numbering is not restarted at logical page delimiters.

-v startnum

Line numbering is restarted at startnum at the start of each logical page.
startnum may be any number greater than or equal to 0.

-v not specified:
The line counter is reset to 1 at the start of each logical page.

Defining the increment

-i incr

incr is the increment value used to number logical page lines.

-i not specified:
The default increment is 1.

Defining the output format

-n format

format is the line numbering format.

The recognized values are: ln, rn, or rz.

ln

Prints line numbers left justified, suppressing leading zeros.

rn

Prints line numbers right justified, suppressing leading zeros.

rz

Prints line numbers right justified, but with leading zeros.

-n not specified:
Line numbers are printed right justified, without leading zeros. In other words, the -n option with argument rn is the default.

-s sep

Defines sep as the separator between line numbers and the corresponding text lines. sep may be one or more characters.

-s not specified:
By default, line numbers and text lines are separated by a tab character.

-w n

Defines n as the number of positions for line numbers.
The maximum value for n is 100. If you specify a higher value, a value of 100 is assumed.

-w not specified:
Individual line numbers may be up to 6 positions long.

Numbering blank lines

-l n

nl treats n consecutive blank lines as a single blank line.

Example

$ nl -b a -l 2

results in only every second blank line being numbered when there are several consecutive blank lines (none of the header and footer lines are numbered).

-l not specified:
Each blank line is interpreted as one full line (n = 1).

Defining delimiters for header, body and footer

-d x[y]

Changes the delimiter characters that specify the start of a header, body or footer section from \: to the string xy.

If a backslash (\) is to be specified for x or y, it must be escaped by single quotes or a second backslash, e.g. -d’\*’ or -d\\*.

y not specified:
The start of a header, body or footer section is identified by the string x: instead of \:, i.e.
the second character retains its default value.

file

Name of the input file.

file not specified:
nl reads from standard input.

Locale

The following environment variables affect the execution of nl:

LANG

Provide a default value for the internationalization variables that are unset or null. If LANG is unset of null, the corresponding value from the implementation-specific default locale will be used. If any of the internationalization variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

If set to a non-empty string value, override the values of all the other internationalization variables.

LC_COLLATE

Determine the locale for the behavior of ranges, equivalence classes and multicharacter collating elements within regular expressions.

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- as opposed to multi-byte characters in arguments and input files), the behavior of character classes within regular expressions, and for deciding which characters are in a certain character class for the -b, -f and -h options.

LC_MESSAGES

Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.

NLSPATH

Determine the location of message catalogs for the processing of LC_MESSAGES.

Example

The file poems has the following contents:

\:\:\:
Taken from: Do you love me?
\:\:
The trouble with you
's you've lost a screw
I'm sorry it's you
but there's nothing to do
There'll be no abatements
there are no replacements
don't make a to-do
just say toodle-oo
I'm sorry I can't help you
you'd cost too much to redo
you'll have to be abolished
report to be demolished
\:
Ronald Laing
\:\:\:
Limerick
\:\:
A limerick packs laughs anatomical
into space that is short and economical;
But the good ones I've seen
so seldom are clean,
And the clean ones so seldom are comical.
\:
Author unknown

Call nl without options

$ nl poems

Taken from: Do you love me?

1 The trouble with you

2 's you've lost a screw

3 I'm sorry it's you
4 but there's nothing to do

5 There'll be no abatements

6 there are no replacements

7 don't make a to-do

8 just say toodle-oo

9 I'm sorry I can't help you
10 you'd cost too much to redo

11 you'll have to be abolished

12 report to be demolished

Ronald Laing

Limerick

1 A limerick packs laughs anatomical

2 into space that is short and economical;
3 But the good ones I've seen

4 so seldom are clean,

5 And the clean ones so seldom are comical.

Author unknown

Number lines in increments of 10

$ nl -v10 -i10 poems

Taken from: Do you love me?

10 The trouble with you

20 's you've lost a screw

30 I'm sorry it's you
40 but there's nothing to do

50 There'll be no abatements

60 there are no replacements

70 don't make a to-do

80 just say toodle-oo

90 I'm sorry I can't help you
100 you'd cost too much to redo

110 you'll have to be abolished

120 report to be demolished

Ronald Laing

Limerick

10 A limerick packs laughs anatomical

20 into space that is short and economical;
30 But the good ones I've seen

40 so seldom are clean,

50 And the clean ones so seldom are comical.