# nl

## 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.
    


## NAME



           nl — line numbering filter
    


## SYNOPSIS



           nl **[** -p**] [** -b _type_**] [** -d _delim_**] [** -f _type_**] [** -h _type_**] [** -i _incr_**] [** -l _num_**]**
               **[** -n _format_**] [** -s _sep_**] [** -v _startnum_**] [** -w _width_**] [**_file_**]**
    


## 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** │  **Start of** │
                              ├────────────┼────────────┤
                              │ \:\:\:     │ Header     │
                              │ \:\:       │ Body       │
                              │ \:         │ Footer     │
                              └────────────┴────────────┘
    
           Unless otherwise specified, _nl_ shall assume the text being read is
           in a single logical page body.
    


## OPTIONS



           The _nl_ utility shall conform to the Base Definitions volume of
           POSIX.1‐2017, _Section 12.2_ , _Utility Syntax Guidelines_.  Only one
           file can be named.
    
           The following options shall be supported:
    
           **-b** _type_   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.
    
                     **p** _string_ 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).
    
           **-d** _delim_  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 **':'**.
    
           **-f** _type_   Specify the same as **b** _type_ except for footer. The
                     default for logical page footer shall be **n**(no lines
                     numbered).
    
           **-h** _type_   Specify the same as **b** _type_ except for header. The
                     default _type_ for logical page header shall be **n**(no
                     lines numbered).
    
           **-i** _incr_   Specify the increment value used to number logical page
                     lines. The default shall be 1.
    
           **-l** _num_    Specify the number of blank lines to be considered as
                     one. For example, **-l 2** results in only the second
                     adjacent blank line being numbered (if the appropriate
                     **-h a** , **-b a** , or **-f a** option is set). The default shall be
                     1.
    
           **-n** _format_ 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.
    
           **-s** _sep_    Specify the characters used in separating the line
                     number and the corresponding text line. The default _sep_
                     shall be a <tab>.
    
           **-v** _startnum_
                     Specify the initial value used to number logical page
                     lines. The default shall be 1.
    
           **-w** _width_  Specify the number of characters to be used for the line
                     number. The default _width_ shall be 6.
    


## OPERANDS



           The following operand shall be supported:
    
           _file_      A pathname of a text file to be line-numbered.
    


## 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.
    


## INPUT FILES



           The input file shall be a text file.
    


## 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, _Section 8.2_ ,
                     _Internationalization Variables_ 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
                     **-b t** , **-f t** , and **-h t** 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_.
    


## ASYNCHRONOUS EVENTS



           Default.
    


## STDOUT



           The standard output shall be a text file in the following format:
    
               "%s%s%s", <_line number_ >, <_separator_ >, <_input line_ >
    
           where <_line number_ > 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.
    


## STDERR



           The standard error shall be used only for diagnostic messages.
    


## OUTPUT FILES



           None.
    


## EXTENDED DESCRIPTION



           None.
    


## EXIT STATUS



           The following exit values shall be returned:
    
            0    Successful completion.
    
           >0    An error occurred.
    


## CONSEQUENCES OF ERRORS



           Default.
    
           _The following sections are informative._
    


## APPLICATION USAGE



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


## 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.
    


## RATIONALE



           None.
    


## FUTURE DIRECTIONS



           None.
    


* * *