1NL(1P)                     POSIX Programmer's Manual                    NL(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       nl — line numbering filter
13

SYNOPSIS

15       nl [-p] [-b type] [-d delim] [-f type] [-h type] [-i incr] [-l num]
16           [-n format] [-s sep] [-v startnum] [-w width] [file]
17

DESCRIPTION

19       The nl utility shall read lines from the named  file  or  the  standard
20       input  if  no  file  is named and shall reproduce the lines to standard
21       output. Lines shall be numbered on the left.  Additional  functionality
22       may be provided in accordance with the command options in effect.
23
24       The  nl utility views the text it reads in terms of logical pages. Line
25       numbering shall be reset at the start of each logical page.  A  logical
26       page consists of a header, a body, and a footer section. Empty sections
27       are valid. Different line numbering options are independently available
28       for  header,  body, and footer (for example, no numbering of header and
29       footer lines while numbering blank lines only in the body).
30
31       The starts of logical page sections shall be signaled  by  input  lines
32       containing nothing but the following delimiter characters:
33
34                              ┌───────────┬────────────┐
35Line    Start of  
36                              ├───────────┼────────────┤
37                              │\:\:\:     │ Header     │
38                              │\:\:       │ Body       │
39                              │\:         │ Footer     │
40                              └───────────┴────────────┘
41       Unless otherwise specified, nl shall assume the text being read is in a
42       single logical page body.
43

OPTIONS

45       The nl  utility  shall  conform  to  the  Base  Definitions  volume  of
46       POSIX.1‐2017,  Section  12.2, Utility Syntax Guidelines.  Only one file
47       can be named.
48
49       The following options shall be supported:
50
51       -b type   Specify which logical page body lines shall be numbered. Rec‐
52                 ognized types and their meaning are:
53
54                 a       Number all lines.
55
56                 t       Number only non-empty lines.
57
58                 n       No line numbering.
59
60                 pstring Number  only  lines  that  contain  the basic regular
61                         expression specified in string.
62
63                 The default type for logical page body shall be t (text lines
64                 numbered).
65
66       -d delim  Specify the delimiter characters that indicate the start of a
67                 logical page section. These can be changed from  the  default
68                 characters "\:" to two user-specified characters. If only one
69                 character is entered, the second character shall  remain  the
70                 default character ':'.
71
72       -f type   Specify the same as b type except for footer. The default for
73                 logical page footer shall be n (no lines numbered).
74
75       -h type   Specify the same as b type except  for  header.  The  default
76                 type for logical page header shall be n (no lines numbered).
77
78       -i incr   Specify  the  increment  value  used  to  number logical page
79                 lines. The default shall be 1.
80
81       -l num    Specify the number of blank lines to be  considered  as  one.
82                 For  example,  -l 2 results in only the second adjacent blank
83                 line being numbered (if the appropriate -h a, -b a,  or  -f a
84                 option is set). The default shall be 1.
85
86       -n format Specify the line numbering format. Recognized values are: ln,
87                 left justified, leading zeros suppressed;  rn,  right  justi‐
88                 fied,  leading zeros suppressed; rz, right justified, leading
89                 zeros kept. The default format shall be rn (right justified).
90
91       -p        Specify that numbering should not  be  restarted  at  logical
92                 page delimiters.
93
94       -s sep    Specify the characters used in separating the line number and
95                 the corresponding text line.  The  default  sep  shall  be  a
96                 <tab>.
97
98       -v startnum
99                 Specify  the initial value used to number logical page lines.
100                 The default shall be 1.
101
102       -w width  Specify the number of characters to be used for the line num‐
103                 ber. The default width shall be 6.
104

OPERANDS

106       The following operand shall be supported:
107
108       file      A pathname of a text file to be line-numbered.
109

STDIN

111       The  standard  input shall be used if no file operand is specified, and
112       shall be used if the file operand is '-' and the implementation  treats
113       the '-' as meaning standard input.  Otherwise, the standard input shall
114       not be used.  See the INPUT FILES section.
115

INPUT FILES

117       The input file shall be a text file.
118

ENVIRONMENT VARIABLES

120       The following environment variables shall affect the execution of nl:
121
122       LANG      Provide a default value for  the  internationalization  vari‐
123                 ables  that are unset or null. (See the Base Definitions vol‐
124                 ume of POSIX.1‐2017, Section 8.2, Internationalization  Vari‐
125                 ables  for  the  precedence of internationalization variables
126                 used to determine the values of locale categories.)
127
128       LC_ALL    If set to a non-empty string value, override  the  values  of
129                 all the other internationalization variables.
130
131       LC_COLLATE
132                 Determine  the locale for the behavior of ranges, equivalence
133                 classes, and multi-character collating elements within  regu‐
134                 lar expressions.
135
136       LC_CTYPE  Determine  the  locale for the interpretation of sequences of
137                 bytes of text data as characters (for example, single-byte as
138                 opposed  to  multi-byte  characters  in  arguments  and input
139                 files), the behavior  of  character  classes  within  regular
140                 expressions, and for deciding which characters are in charac‐
141                 ter class graph (for the -b t, -f t, and -h t options).
142
143       LC_MESSAGES
144                 Determine the locale that should be used to affect the format
145                 and  contents  of  diagnostic  messages  written  to standard
146                 error.
147
148       NLSPATH   Determine the location of message catalogs for the processing
149                 of LC_MESSAGES.
150

ASYNCHRONOUS EVENTS

152       Default.
153

STDOUT

155       The standard output shall be a text file in the following format:
156
157
158           "%s%s%s", <line number>, <separator>, <input line>
159
160       where <line number> is one of the following numeric formats:
161
162       %6d       When the rn format is used (the default; see -n).
163
164       %06d      When the rz format is used.
165
166       %-6d      When the ln format is used.
167
168       <empty>   When  line  numbers are suppressed for a portion of the page;
169                 the <separator> is also suppressed.
170
171       In the preceding list, the number 6 is the default width; the -w option
172       can change this value.
173

STDERR

175       The standard error shall be used only for diagnostic messages.
176

OUTPUT FILES

178       None.
179

EXTENDED DESCRIPTION

181       None.
182

EXIT STATUS

184       The following exit values shall be returned:
185
186        0    Successful completion.
187
188       >0    An error occurred.
189

CONSEQUENCES OF ERRORS

191       Default.
192
193       The following sections are informative.
194

APPLICATION USAGE

196       In using the -d delim option, care should be taken to escape characters
197       that have special meaning to the command interpreter.
198

EXAMPLES

200       The command:
201
202
203           nl -v 10 -i 10 -d \!+ file1
204
205       numbers file1 starting at line number 10 with an increment of  10.  The
206       logical  page  delimiter is "!+".  Note that the '!'  has to be escaped
207       when using csh as a command interpreter because of its history  substi‐
208       tution  syntax.   For  ksh and sh the escape is not necessary, but does
209       not do any harm.
210

RATIONALE

212       None.
213

FUTURE DIRECTIONS

215       None.
216

SEE ALSO

218       pr
219
220       The Base Definitions volume of  POSIX.1‐2017,  Chapter  8,  Environment
221       Variables, Section 12.2, Utility Syntax Guidelines
222
224       Portions  of  this text are reprinted and reproduced in electronic form
225       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
226       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
227       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
228       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
229       event of any discrepancy between this version and the original IEEE and
230       The  Open Group Standard, the original IEEE and The Open Group Standard
231       is the referee document. The original Standard can be  obtained  online
232       at http://www.opengroup.org/unix/online.html .
233
234       Any  typographical  or  formatting  errors that appear in this page are
235       most likely to have been introduced during the conversion of the source
236       files  to  man page format. To report such errors, see https://www.ker
237       nel.org/doc/man-pages/reporting_bugs.html .
238
239
240
241IEEE/The Open Group                  2017                               NL(1P)
Impressum