This manual page is part of the POSIX Programmer's Manual. The Linux implementation of this interface

Application Usage

       In  using the -ddelim option, care should be taken to escape characters that have special meaning to the
       command interpreter.

Asynchronous Events

       Default.

Consequences Of Errors

       Default.

       Thefollowingsectionsareinformative.

Copyright

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1-2017, Standard
       for  Information  Technology  --  Portable  Operating  System  Interface  (POSIX),  The  Open  Group Base
       Specifications Issue 7, 2018 Edition, Copyright (C) 2018 by the Institute of Electrical  and  Electronics
       Engineers, Inc and The Open Group.  In the event of any discrepancy between this version and the original
       IEEE  and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document.
       The original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are most likely to have  been  introduced
       during   the   conversion  of  the  source  files  to  man  page  format.  To  report  such  errors,  see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group                                   2017                                            NL(1POSIX)

Description

The nl utility shall read lines from the named file or the standard input if no file is named and shall
reproduce the lines to standard output. Lines shall be numbered on the left. Additional functionality may
be provided in accordance with the command options in effect.

The nl utility views the text it reads in terms of logical pages. Line numbering shall be reset at the
start of each logical page. A logical page consists of a header, a body, and a footer section. Empty
sections are valid. Different line numbering options are independently available for header, body, and
footer (for example, no numbering of header and footer lines while numbering blank lines only in the
body).

The starts of logical page sections shall be signaled by input lines containing nothing but the following
delimiter characters:
┌────────────┬────────────┐
│ Line │ Startof │
├────────────┼────────────┤
│ \:\:\: │ Header │
│ \:\: │ Body │
│ \: │ Footer │
└────────────┴────────────┘

Unless otherwise specified, nl shall assume the text being read is in a single logical page body.

Environment Variables

       The following environment variables shall affect the execution of nl:

       LANG      Provide a default value for the internationalization variables that are unset or null. (See the
                 Base Definitions volume of POSIX.1‐2017, Section8.2, InternationalizationVariables  for  the
                 precedence   of   internationalization  variables  used  to  determine  the  values  of  locale
                 categories.)

       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 multi-character
                 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-byte  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 character class graph (for the -bt, -ft, and -ht 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.

Examples

       The command:

           nl -v 10 -i 10 -d \!+ file1

       numbers file1 starting at line number 10 with an increment of 10. The logical  page  delimiter  is  "!+".
       Note  that  the  '!'   has  to  be escaped when using csh as a command interpreter because of its history
       substitution syntax.  For ksh and sh the escape is not necessary, but does not do any harm.

Exit Status

       The following exit values shall be returned:

        0    Successful completion.

       >0    An error occurred.

Extended Description

       None.

Future Directions

       None.

Input Files

       The input file shall be a text file.

Name

       nl — line numbering filter

Operands

       The following operand shall be supported:

       file      A pathname of a text file to be line-numbered.

Options

The nl utility shall conform to the Base Definitions volume of POSIX.1‐2017, Section12.2, UtilitySyntaxGuidelines. Only one file can be named.

The following options shall be supported:

-btype Specify which logical page body lines shall be numbered. Recognized types and their meaning
are:

a Number all lines.

t Number only non-empty lines.

n No line numbering.

pstring Number only lines that contain the basic regular expression specified in string.

The default type for logical page body shall be t (text lines numbered).

-ddelim Specify the delimiter characters that indicate the start of a logical page section. These can
be changed from the default characters "\:" to two user-specified characters. If only one
character is entered, the second character shall remain the default character ':'.

-ftype Specify the same as btype except for footer. The default for logical page footer shall be n
(no lines numbered).

-htype Specify the same as btype except for header. The default type for logical page header shall be
n (no lines numbered).

-iincr Specify the increment value used to number logical page lines. The default shall be 1.

-lnum Specify the number of blank lines to be considered as one. For example, -l2 results in only
the second adjacent blank line being numbered (if the appropriate -ha, -ba, or -fa option is
set). The default shall be 1.

-nformat Specify the line numbering format. Recognized values are: ln, left justified, leading zeros
suppressed; rn, right justified, leading zeros suppressed; rz, right justified, leading zeros
kept. The default format shall be rn (right justified).

-p Specify that numbering should not be restarted at logical page delimiters.

-ssep Specify the characters used in separating the line number and the corresponding text line. The
default sep shall be a <tab>.

-vstartnum
Specify the initial value used to number logical page lines. The default shall be 1.

-wwidth Specify the number of characters to be used for the line number. The default width shall be 6.

Output Files

       None.

Prolog

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

Rationale

       None.

Stderr

       The standard error shall be used only for diagnostic messages.

Stdin

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

Stdout

       The standard output shall be a text file in the following format:

           "%s%s%s", <linenumber>, <separator>, <inputline>

       where <linenumber> is one of the following numeric formats:

       %6d       When the rn format is used (the default; see -n).

       %06d      When the rz format is used.

       %-6d      When the ln format is used.

       <empty>   When line numbers are suppressed for a portion of the page; the <separator> is also suppressed.

       In the preceding list, the number 6 is the default width; the -w option can change this value.

Synopsis

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