diff options
Diffstat (limited to 'man1p/nl.1p')
| -rw-r--r-- | man1p/nl.1p | 285 |
1 files changed, 285 insertions, 0 deletions
diff --git a/man1p/nl.1p b/man1p/nl.1p new file mode 100644 index 000000000..5a76eb1c6 --- /dev/null +++ b/man1p/nl.1p @@ -0,0 +1,285 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "NL" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" nl +.SH NAME +nl \- line numbering filter +.SH SYNOPSIS +.LP +\fBnl\fP \fB[\fP\fB-p\fP\fB][\fP\fB-b\fP \fItype\fP\fB][\fP\fB-d\fP +\fIdelim\fP\fB][\fP\fB-f\fP \fItype\fP\fB][\fP\fB-h\fP \fItype\fP\fB][\fP\fB-i\fP +\fIincr\fP\fB][\fP\fB-l\fP +\fInum\fP\fB][\fP\fB-n\fP \fIformat\fP\fB] +.br +\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-s\fP \fIsep\fP\fB][\fP\fB-v\fP +\fIstartnum\fP\fB][\fP\fB-w\fP \fIwidth\fP\fB][\fP\fIfile\fP\fB]\fP\fB\fP +.SH DESCRIPTION +.LP +The \fInl\fP utility shall read lines from the named \fIfile\fP or +the standard input if no \fIfile\fP 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. +.LP +The \fInl\fP 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). +.LP +The starts of logical page sections shall be signaled by input lines +containing nothing but the following delimiter +characters: +.TS C +center; l l. +\fBLine\fP \fBStart of\fP +\\:\\:\\: Header +\\:\\: Body +\\: Footer +.TE +.LP +Unless otherwise specified, \fInl\fP shall assume the text being read +is in a single logical page body. +.SH OPTIONS +.LP +The \fInl\fP utility shall conform to the Base Definitions volume +of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines. +Only one file can be named. +.LP +The following options shall be supported: +.TP 7 +\fB-b\ \fP \fItype\fP +Specify which logical page body lines shall be numbered. Recognized +\fItypes\fP and their meaning are: +.TP 7 +\fBa\fP +.RS +Number all lines. +.RE +.TP 7 +\fBt\fP +.RS +Number only non-empty lines. +.RE +.TP 7 +\fBn\fP +.RS +No line numbering. +.RE +.TP 7 +\fBp\fP\fIstring\fP +.RS +Number only lines that contain the basic regular expression specified +in \fIstring\fP. +.RE +.sp +.LP +The default \fItype\fP for logical page body shall be \fBt\fP (text +lines numbered). +.TP 7 +\fB-d\ \fP \fIdelim\fP +Specify the delimiter characters that indicate the start of a logical +page section. These can be changed from the default +characters \fB"\\:"\fP to two user-specified characters. If only one +character is entered, the second character shall remain the +default character \fB':'\fP . +.TP 7 +\fB-f\ \fP \fItype\fP +Specify the same as \fBb\fP \fItype\fP except for footer. The default +for logical page footer shall be \fBn\fP (no lines +numbered). +.TP 7 +\fB-h\ \fP \fItype\fP +Specify the same as \fBb\fP \fItype\fP except for header. The default +\fItype\fP for logical page header shall be \fBn\fP +(no lines numbered). +.TP 7 +\fB-i\ \fP \fIincr\fP +Specify the increment value used to number logical page lines. The +default shall be 1. +.TP 7 +\fB-l\ \fP \fInum\fP +Specify the number of blank lines to be considered as one. For example, +\fB-l\ 2\fP results in only the second adjacent +blank line being numbered (if the appropriate \fB-h\ a\fP, \fB-b\ a\fP, +or \fB-f\ a\fP option is set). The default +shall be 1. +.TP 7 +\fB-n\ \fP \fIformat\fP +Specify the line numbering format. Recognized values are: \fBln\fP, +left justified, leading zeros suppressed; \fBrn\fP, right +justified, leading zeros suppressed; \fBrz\fP, right justified, leading +zeros kept. The default \fIformat\fP shall be \fBrn\fP +(right justified). +.TP 7 +\fB-p\fP +Specify that numbering should not be restarted at logical page delimiters. +.TP 7 +\fB-s\ \fP \fIsep\fP +Specify the characters used in separating the line number and the +corresponding text line. The default \fIsep\fP shall be a +<tab>. +.TP 7 +\fB-v\ \fP \fIstartnum\fP +Specify the initial value used to number logical page lines. The default +shall be 1. +.TP 7 +\fB-w\ \fP \fIwidth\fP +Specify the number of characters to be used for the line number. The +default \fIwidth\fP shall be 6. +.sp +.SH OPERANDS +.LP +The following operand shall be supported: +.TP 7 +\fIfile\fP +A pathname of a text file to be line-numbered. +.sp +.SH STDIN +.LP +The standard input is a text file that is used if no \fIfile\fP operand +is given. +.SH INPUT FILES +.LP +The input file named by the \fIfile\fP operand is a text file. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fInl\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_COLLATE\fP +.sp +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular +expressions. +.TP 7 +\fILC_CTYPE\fP +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 \fBgraph\fP (for +the \fB-b\ t\fP, \fB-f\ t\fP, and \fB-h\ t\fP +options). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The standard output shall be a text file in the following format: +.sp +.RS +.nf + +\fB"%s%s%s", <\fP\fIline number\fP\fB>, <\fP\fIseparator\fP\fB>, <\fP\fIinput line\fP\fB> +\fP +.fi +.RE +.LP +where <\fIline\ number\fP> is one of the following numeric formats: +.TP 7 +\fB%6d\fP +When the \fBrn\fP format is used (the default; see \fB-n\fP). +.TP 7 +\fB%06d\fP +When the \fBrz\fP format is used. +.TP 7 +\fB%-6d\fP +When the \fBln\fP format is used. +.TP 7 +<empty> +When line numbers are suppressed for a portion of the page; the <\fIseparator\fP> +is also suppressed. +.sp +.LP +In the preceding list, the number 6 is the default width; the \fB-w\fP +option can change this value. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +In using the \fB-d\fP \fIdelim\fP option, care should be taken to +escape characters that have special meaning to the command +interpreter. +.SH EXAMPLES +.LP +The command: +.sp +.RS +.nf + +\fBnl -v 10 -i 10 -d \\!+ file1 +\fP +.fi +.RE +.LP +numbers \fIfile1\fP starting at line number 10 with an increment of +10. The logical page delimiter is \fB"!+"\fP . Note that +the \fB'!'\fP has to be escaped when using \fIcsh\fP as a command +interpreter because of its history substitution syntax. For +\fIksh\fP and \fIsh\fP the escape is not necessary, but does not do +any harm. +.SH RATIONALE +.LP +None. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIpr\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 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 . |