.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "MORE" P 2003 POSIX
.\" more 
.SH NAME
more \- display files on a page-by-page basis
.SH SYNOPSIS
.LP
\fBmore\fP \fB[\fP\fB-ceisu\fP\fB][\fP\fB-n\fP \fInumber\fP\fB][\fP\fB-p\fP
\fIcommand\fP\fB][\fP\fB-t\fP \fItagstring\fP\fB][\fP\fIfile\fP \fB...\fP\fB]\fP\fB\fP
.SH DESCRIPTION
.LP
The \fImore\fP utility shall read files and either write them to the
terminal on a page-by-page basis or filter them to
standard output. If standard output is not a terminal device, all
input files shall be copied to standard output in their entirety,
without modification, except as specified for the \fB-s\fP option.
If standard output is a terminal device, the files shall be
written a number of lines (one screenful) at a time under the control
of user commands. See the EXTENDED DESCRIPTION section.
.LP
Certain block-mode terminals do not have all the capabilities necessary
to support the complete \fImore\fP definition; they are
incapable of accepting commands that are not terminated with a <newline>.
Implementations that support such terminals shall
provide an operating mode to \fImore\fP in which all commands can
be terminated with a <newline> on those terminals. This
mode:
.IP " *" 3
Shall be documented in the system documentation
.LP
.IP " *" 3
Shall, at invocation, inform the user of the terminal deficiency that
requires the <newline> usage and provide
instructions on how this warning can be suppressed in future invocations
.LP
.IP " *" 3
Shall not be required for implementations supporting only fully capable
terminals
.LP
.IP " *" 3
Shall not affect commands already requiring <newline>s
.LP
.IP " *" 3
Shall not affect users on the capable terminals from using \fImore\fP
as described in this volume of
IEEE\ Std\ 1003.1-2001
.LP
.SH OPTIONS
.LP
The \fImore\fP utility shall conform to the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
.LP
The following options shall be supported:
.TP 7
\fB-c\fP
If a screen is to be written that has no lines in common with the
current screen, or \fImore\fP is writing its first screen,
\fImore\fP shall not scroll the screen, but instead shall redraw each
line of the screen in turn, from the top of the screen to
the bottom. In addition, if \fImore\fP is writing its first screen,
the screen shall be cleared. This option may be silently
ignored on devices with insufficient terminal capabilities.
.TP 7
\fB-e\fP
By default, \fImore\fP shall exit immediately after writing the last
line of the last file in the argument list. If the
\fB-e\fP option is specified: 
.RS
.IP " 1." 4
If there is only a single file in the argument list and that file
was completely displayed on a single screen, \fImore\fP shall
exit immediately after writing the last line of that file.
.LP
.IP " 2." 4
Otherwise, \fImore\fP shall exit only after reaching end-of-file on
the last file in the argument list twice without an
intervening operation. See the EXTENDED DESCRIPTION section.
.LP
.RE
.TP 7
\fB-i\fP
Perform pattern matching in searches without regard to case; see the
Base Definitions volume of IEEE\ Std\ 1003.1-2001,
Section 9.2, Regular Expression General Requirements.
.TP 7
\fB-n\ \fP \fInumber\fP
Specify the number of lines per screenful. The \fInumber\fP argument
is a positive decimal integer. The \fB-n\fP option shall
override any values obtained from any other source.
.TP 7
\fB-p\ \fP \fIcommand\fP
Each time a screen from a new file is displayed or redisplayed (including
as a result of \fImore\fP commands; for example,
\fB:p\fP), execute the \fImore\fP command(s) in the command arguments
in the order specified, as if entered by the user after the
first screen has been displayed. No intermediate results shall be
displayed (that is, if the command is a movement to a screen
different from the normal first screen, only the screen resulting
from the command shall be displayed.) If any of the commands fail
for any reason, an informational message to this effect shall be written,
and no further commands specified using the \fB-p\fP
option shall be executed for this file.
.TP 7
\fB-s\fP
Behave as if consecutive empty lines were a single empty line.
.TP 7
\fB-t\ \fP \fItagstring\fP
Write the screenful of the file containing the tag named by the \fItagstring\fP
argument. See the \fIctags\fP utility. The tags feature represented
by \fB-t\fP \fItagstring\fP and the \fB:t\fP command is
optional. It shall be provided on any system that also provides a
conforming implementation of \fIctags\fP; otherwise, the use of \fB-t\fP
produces undefined results. 
.LP
The filename resulting from the \fB-t\fP option shall be logically
added as a prefix to the list of command line files, as if
specified by the user. If the tag named by the \fItagstring\fP argument
is not found, it shall be an error, and \fImore\fP shall
take no further action.
.LP
If the tag specifies a line number, the first line of the display
shall contain the beginning of that line. If the tag specifies
a pattern, the first line of the display shall contain the beginning
of the matching text from the first line of the file that
contains that pattern. If the line does not exist in the file or matching
text is not found, an informational message to this
effect shall be displayed, and \fImore\fP shall display the default
screen as if \fB-t\fP had not been specified.
.LP
If both the \fB-t\fP \fItagstring\fP and \fB-p\fP \fIcommand\fP options
are given, the \fB-t\fP \fItagstring\fP shall be
processed first; that is, the file and starting line for the display
shall be as specified by \fB-t\fP, and then the \fB-p\fP
\fImore\fP command shall be executed. If the line (matching text)
specified by the \fB-t\fP command does not exist (is not
found), no \fB-p\fP \fImore\fP command shall be executed for this
file at any time.
.TP 7
\fB-u\fP
Treat a <backspace> as a printable control character, displayed as
an implementation-defined character sequence (see the
EXTENDED DESCRIPTION section), suppressing backspacing and the special
handling that produces underlined or standout mode text on
some terminal types. Also, do not ignore a <carriage-return> at the
end of a line.
.sp
.SH OPERANDS
.LP
The following operand shall be supported:
.TP 7
\fIfile\fP
A pathname of an input file. If no \fIfile\fP operands are specified,
the standard input shall be used. If a \fIfile\fP is
\fB'-'\fP , the standard input shall be read at that point in the
sequence.
.sp
.SH STDIN
.LP
The standard input shall be used only if no \fIfile\fP operands are
specified, or if a \fIfile\fP operand is \fB'-'\fP
\&.
.SH INPUT FILES
.LP
The input files being examined shall be text files. If standard output
is a terminal, standard error shall be used to read
commands from the user. If standard output is a terminal, standard
error is not readable, and command input is needed, \fImore\fP
may attempt to obtain user commands from the controlling terminal
(for example, \fB/dev/tty\fP); otherwise, \fImore\fP shall
terminate with an error indicating that it was unable to read user
commands. If standard output is not a terminal, no error shall
result if standard error cannot be opened for reading.
.SH ENVIRONMENT VARIABLES
.LP
The following environment variables shall affect the execution of
\fImore\fP:
.TP 7
\fICOLUMNS\fP
Override the system-selected horizontal display line size. See the
Base Definitions volume of IEEE\ Std\ 1003.1-2001,
Chapter 8, Environment Variables for valid values and results when
it is unset or
null.
.TP 7
\fIEDITOR\fP
Used by the \fBv\fP command to select an editor. See the EXTENDED
DESCRIPTION section.
.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) and
the behavior of character classes within regular
expressions.
.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 and
informative messages written to standard output.
.TP 7
\fINLSPATH\fP
Determine the location of message catalogs for the processing of \fILC_MESSAGES
\&.\fP 
.TP 7
\fILINES\fP
Override the system-selected vertical screen size, used as the number
of lines in a screenful. See the Base Definitions volume
of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment Variables for valid
values and
results when it is unset or null. The \fB-n\fP option shall take precedence
over the \fILINES\fP variable for determining the
number of lines in a screenful.
.TP 7
\fIMORE\fP
Determine a string containing options described in the OPTIONS section
preceded with hyphens and <blank>-separated as on
the command line. Any command line options shall be processed after
those in the \fIMORE\fP variable, as if the command line were:
.sp
.RS
.nf

\fBmore $MORE\fP \fIoptions operands\fP
.fi
.RE
.LP
The \fIMORE\fP variable shall take precedence over the \fITERM\fP
and \fILINES\fP variables for determining the number of
lines in a screenful.
.TP 7
\fITERM\fP
Determine the name of the terminal type. If this variable is unset
or null, an unspecified default terminal type is used.
.sp
.SH ASYNCHRONOUS EVENTS
.LP
Default.
.SH STDOUT
.LP
The standard output shall be used to write the contents of the input
files.
.SH STDERR
.LP
The standard error shall be used for diagnostic messages and user
commands (see the INPUT FILES section), and, if standard
output is a terminal device, to write a prompting string. The prompting
string shall appear on the screen line below the last line
of the file displayed in the current screenful. The prompt shall contain
the name of the file currently being examined and shall
contain an end-of-file indication and the name of the next file, if
any, when prompting at the end-of-file. If an error or
informational message is displayed, it is unspecified whether it is
contained in the prompt. If it is not contained in the prompt,
it shall be displayed and then the user shall be prompted for a continuation
character, at which point another message or the user
prompt may be displayed. The prompt is otherwise unspecified. It is
unspecified whether informational messages are written for
other user commands.
.SH OUTPUT FILES
.LP
None.
.SH EXTENDED DESCRIPTION
.LP
The following section describes the behavior of \fImore\fP when the
standard output is a terminal device. If the standard
output is not a terminal device, no options other than \fB-s\fP shall
have any effect, and all input files shall be copied to
standard output otherwise unmodified, at which time \fImore\fP shall
exit without further action.
.LP
The number of lines available per screen shall be determined by the
\fB-n\fP option, if present, or by examining values in the
environment (see the ENVIRONMENT VARIABLES section). If neither method
yields a number, an unspecified number of lines shall be
used.
.LP
The maximum number of lines written shall be one less than this number,
because the screen line after the last line written
shall be used to write a user prompt and user input. If the number
of lines in the screen is less than two, the results are
undefined. It is unspecified whether user input is permitted to be
longer than the remainder of the single line where the prompt
has been written.
.LP
The number of columns available per line shall be determined by examining
values in the environment (see the ENVIRONMENT
VARIABLES section), with a default value as described in the Base
Definitions volume of IEEE\ Std\ 1003.1-2001, Chapter 8, Environment
Variables.
.LP
Lines that are longer than the display shall be folded; the length
at which folding occurs is unspecified, but should be
appropriate for the output device. Folding may occur between glyphs
of single characters that take up multiple display columns.
.LP
When standard output is a terminal and \fB-u\fP is not specified,
\fImore\fP shall treat <backspace>s and
<carriage-return>s specially:
.IP " *" 3
A character, followed first by a sequence of \fIn\fP <backspace>s
(where \fIn\fP is the same as the number of column
positions that the character occupies), then by \fIn\fP underscore
characters ( \fB'_'\fP ), shall cause that character to be
written as underlined text, if the terminal type supports that. The
\fIn\fP underscore characters, followed first by \fIn\fP
<backspace>s, then any character with \fIn\fP column positions, shall
also cause that character to be written as underlined
text, if the terminal type supports that.
.LP
.IP " *" 3
A sequence of \fIn\fP <backspace>s (where \fIn\fP is the same as the
number of column positions that the previous
character occupies) that appears between two identical printable characters
shall cause the first of those two characters to be
written as emboldened text (that is, visually brighter, standout mode,
or inverse-video mode), if the terminal type supports that,
and the second to be discarded. Immediately subsequent occurrences
of <backspace>/ character pairs for that same character
shall also be discarded. (For example, the sequence \fB"a\\ba\\ba\\ba"\fP
is interpreted as a single emboldened \fB'a'\fP .)
.LP
.IP " *" 3
The \fImore\fP utility shall logically discard all other <backspace>s
from the line as well as the character which
precedes them, if any.
.LP
.IP " *" 3
A <carriage-return> at the end of a line shall be ignored, rather
than being written as a non-printable character, as
described in the next paragraph.
.LP
.LP
It is implementation-defined how other non-printable characters are
written. Implementations should use the same format that
they use for the \fIex\fP \fBprint\fP command; see the OPTIONS section
within the \fIed\fP utility. It is unspecified whether a multi-column
character shall be separated if it crosses a
display line boundary; it shall not be discarded. The behavior is
unspecified if the number of columns on the display is less than
the number of columns any single character in the line being displayed
would occupy.
.LP
When each new file is displayed (or redisplayed), \fImore\fP shall
write the first screen of the file. Once the initial screen
has been written, \fImore\fP shall prompt for a user command. If the
execution of the user command results in a screen that has
lines in common with the current screen, and the device has sufficient
terminal capabilities, \fImore\fP shall scroll the screen;
otherwise, it is unspecified whether the screen is scrolled or redrawn.
.LP
For all files but the last (including standard input if no file was
specified, and for the last file as well, if the \fB-e\fP
option was not specified), when \fImore\fP has written the last line
in the file, \fImore\fP shall prompt for a user command.
This prompt shall contain the name of the next file as well as an
indication that \fImore\fP has reached end-of-file. If the user
command is \fBf\fP, <control>-F, <space>, \fBj\fP, <newline>, \fBd\fP,
<control>-D, or \fBs\fP,
\fImore\fP shall display the next file. Otherwise, if displaying the
last file, \fImore\fP shall exit. Otherwise, \fImore\fP
shall execute the user command specified.
.LP
Several of the commands described in this section display a previous
screen from the input stream. In the case that text is
being taken from a non-rewindable stream, such as a pipe, it is implementation-defined
how much backwards motion is supported. If a
command cannot be executed because of a limitation on backwards motion,
an error message to this effect shall be displayed, the
current screen shall not change, and the user shall be prompted for
another command.
.LP
If a command cannot be performed because there are insufficient lines
to display, \fImore\fP shall alert the terminal. If a
command cannot be performed because there are insufficient lines to
display or a \fB/\fP command fails: if the input is the
standard input, the last screen in the file may be displayed; otherwise,
the current file and screen shall not change, and the user
shall be prompted for another command.
.LP
The interactive commands in the following sections shall be supported.
Some commands can be preceded by a decimal integer,
called \fIcount\fP in the following descriptions. If not specified
with the command, \fIcount\fP shall default to 1. In the
following descriptions, \fIpattern\fP is a basic regular expression,
as described in the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, Section 9.3, Basic Regular Expressions. The
term "examine" is historical usage meaning "open the file for viewing'';
for example, \fImore\fP \fBfoo\fP would be expressed
as examining file \fBfoo\fP.
.LP
In the following descriptions, unless otherwise specified, \fIline\fP
is a line in the \fImore\fP display, not a line from the
file being examined.
.LP
In the following descriptions, the \fIcurrent position\fP refers to
two things:
.IP " 1." 4
The position of the current line on the screen
.LP
.IP " 2." 4
The line number (in the file) of the current line on the screen
.LP
.LP
Usually, the line on the screen corresponding to the current position
is the third line on the screen. If this is not possible
(there are fewer than three lines to display or this is the first
page of the file, or it is the last page of the file), then the
current position is either the first or last line on the screen as
described later.
.SS Help
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBh
\fP
.fi
.RE
.sp
.LP
Write a summary of these commands and other implementation-defined
commands. The behavior shall be as if the \fImore\fP utility
were executed with the \fB-e\fP option on a file that contained the
summary information. The user shall be prompted as described
earlier in this section when end-of-file is reached. If the user command
is one of those specified to continue to the next file,
\fImore\fP shall return to the file and screen state from which the
\fBh\fP command was executed.
.SS Scroll Forward One Screenful
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fBf
\fP\fB[\fP\fIcount\fP\fB]\fP\fB<control>-F
\fP
.fi
.RE
.sp
.LP
Scroll forward \fIcount\fP lines, with a default of one screenful.
If \fIcount\fP is more than the screen size, only the final
screenful shall be written.
.SS Scroll Backward One Screenful
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fBb
\fP\fB[\fP\fIcount\fP\fB]\fP\fB<control>-B
\fP
.fi
.RE
.sp
.LP
Scroll backward \fIcount\fP lines, with a default of one screenful
(see the \fB-n\fP option). If \fIcount\fP is more than the
screen size, only the final screenful shall be written.
.SS Scroll Forward One Line
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fB<space>
\fP\fB[\fP\fIcount\fP\fB]\fP\fBj
\fP\fB[\fP\fIcount\fP\fB]\fP\fB<newline>
\fP
.fi
.RE
.sp
.LP
Scroll forward \fIcount\fP lines. The default \fIcount\fP for the
<space> shall be one screenful; for \fBj\fP and
<newline>, one line. The entire \fIcount\fP lines shall be written,
even if \fIcount\fP is more than the screen size.
.SS Scroll Backward One Line
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fBk
\fP
.fi
.RE
.sp
.LP
Scroll backward \fIcount\fP lines. The entire \fIcount\fP lines shall
be written, even if \fIcount\fP is more than the screen
size.
.SS Scroll Forward One Half Screenful
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fBd
\fP\fB[\fP\fIcount\fP\fB]\fP\fB<control>-D
\fP
.fi
.RE
.sp
.LP
Scroll forward \fIcount\fP lines, with a default of one half of the
screen size. If \fIcount\fP is specified, it shall become
the new default for subsequent \fBd\fP, <control>-D, and \fBu\fP commands.
.SS Skip Forward One Line
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fBs
\fP
.fi
.RE
.sp
.LP
Display the screenful beginning with the line \fIcount\fP lines after
the last line on the current screen. If \fIcount\fP
would cause the current position to be such that less than one screenful
would be written, the last screenful in the file shall be
written.
.SS Scroll Backward One Half Screenful
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fBu
\fP\fB[\fP\fIcount\fP\fB]\fP\fB<control>-U
\fP
.fi
.RE
.sp
.LP
Scroll backward \fIcount\fP lines, with a default of one half of the
screen size. If \fIcount\fP is specified, it shall become
the new default for subsequent \fBd\fP, <control>-D, \fBu\fP, and
<control>-U commands. The entire \fIcount\fP lines
shall be written, even if \fIcount\fP is more than the screen size.
.SS Go to Beginning of File
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fBg
\fP
.fi
.RE
.sp
.LP
Display the screenful beginning with line \fIcount\fP.
.SS Go to End-of-File
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fBG
\fP
.fi
.RE
.sp
.LP
If \fIcount\fP is specified, display the screenful beginning with
the line \fIcount\fP. Otherwise, display the last screenful
of the file.
.SS Refresh the Screen
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBr
<control>-L
\fP
.fi
.RE
.sp
.LP
Refresh the screen.
.SS Discard and Refresh
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBR
\fP
.fi
.RE
.sp
.LP
Refresh the screen, discarding any buffered input. If the current
file is non-seekable, buffered input shall not be discarded
and the \fBR\fP command shall be equivalent to the \fBr\fP command.
.SS Mark Position
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBm\fP\fIletter\fP
.fi
.RE
.sp
.LP
Mark the current position with the letter named by \fIletter\fP, where
\fIletter\fP represents the name of one of the
lowercase letters of the portable character set. When a new file is
examined, all marks may be lost.
.SS Return to Mark
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB'\fP\fIletter\fP
.fi
.RE
.sp
.LP
Return to the position that was previously marked with the letter
named by \fIletter\fP, making that line the current
position.
.SS Return to Previous Position
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB''
\fP
.fi
.RE
.sp
.LP
Return to the position from which the last large movement command
was executed (where a "large movement" is defined as any
movement of more than a screenful of lines). If no such movements
have been made, return to the beginning of the file.
.SS Search Forward for Pattern
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fB/\fP\fB[\fP\fB!\fP\fB]\fP\fIpattern\fP\fB<newline>
\fP
.fi
.RE
.sp
.LP
Display the screenful beginning with the \fIcount\fPth line containing
the pattern. The search shall start after the first line
currently displayed. The null regular expression ( \fB'/'\fP followed
by a <newline>) shall repeat the search using the
previous regular expression, with a default \fIcount\fP. If the character
\fB'!'\fP is included, the matching lines shall be
those that do not contain the \fIpattern\fP. If no match is found
for the \fIpattern\fP, a message to that effect shall be
displayed.
.SS Search Backward for Pattern
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fB?\fP\fB[\fP\fB!\fP\fB]\fP\fIpattern\fP\fB<newline>
\fP
.fi
.RE
.sp
.LP
Display the screenful beginning with the \fIcount\fPth previous line
containing the pattern. The search shall start on the last
line before the first line currently displayed. The null regular expression
( \fB'?'\fP followed by a <newline>) shall
repeat the search using the previous regular expression, with a default
\fIcount\fP. If the character \fB'!'\fP is included,
matching lines shall be those that do not contain the \fIpattern\fP.
If no match is found for the \fIpattern\fP, a message to
that effect shall be displayed.
.SS Repeat Search
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fBn
\fP
.fi
.RE
.sp
.LP
Repeat the previous search for \fIcount\fPth line containing the last
\fIpattern\fP (or not containing the last
\fIpattern\fP, if the previous search was \fB"/!"\fP or \fB"?!"\fP
).
.SS Repeat Search in Reverse
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fBN
\fP
.fi
.RE
.sp
.LP
Repeat the search in the opposite direction of the previous search
for the \fIcount\fPth line containing the last
\fIpattern\fP (or not containing the last \fIpattern\fP, if the previous
search was \fB"/!"\fP or \fB"?!"\fP ).
.SS Examine New File
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB:e\fP \fB[\fP\fIfilename\fP\fB]\fP\fB<newline>
\fP
.fi
.RE
.sp
.LP
Examine a new file. If the \fIfilename\fP argument is not specified,
the current file (see the \fB:n\fP and \fB:p\fP commands
below) shall be re-examined. The \fIfilename\fP shall be subjected
to the process of shell word expansions (see \fIWord Expansions\fP
); if more than a single pathname results, the effects are unspecified.
If
\fIfilename\fP is a number sign ( \fB'#'\fP ), the previously examined
file shall be re-examined. If \fIfilename\fP is not
accessible for any reason (including that it is a non-seekable file),
an error message to this effect shall be displayed and the
current file and screen shall not change.
.SS Examine Next File
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fB:n
\fP
.fi
.RE
.sp
.LP
Examine the next file. If a number \fIcount\fP is specified, the \fIcount\fPth
next file shall be examined. If \fIfilename\fP
refers to a non-seekable file, the results are unspecified.
.SS Examine Previous File
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB[\fP\fIcount\fP\fB]\fP\fB:p
\fP
.fi
.RE
.sp
.LP
Examine the previous file. If a number \fIcount\fP is specified, the
\fIcount\fPth previous file shall be examined. If
\fIfilename\fP refers to a non-seekable file, the results are unspecified.
.SS Go to Tag
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB:t\fP \fItagstring\fP\fB<newline>
\fP
.fi
.RE
.sp
.LP
If the file containing the tag named by the \fItagstring\fP argument
is not the current file, examine the file, as if the
\fB:e\fP command was executed with that file as the argument. Otherwise,
or in addition, display the screenful beginning with the
tag, as described for the \fB-t\fP option (see the OPTIONS section).
If the \fIctags\fP
utility is not supported by the system, the use of \fB:t\fP produces
undefined results.
.SS Invoke Editor
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBv
\fP
.fi
.RE
.sp
.LP
Invoke an editor to edit the current file being examined. If standard
input is being examined, the results are unspecified. The
name of the editor shall be taken from the environment variable \fIEDITOR
,\fP or shall default to \fIvi\fP. If the last pathname component
in \fIEDITOR\fP is either \fIvi\fP or \fIex\fP, the editor shall be
invoked with a \fB-c\fP
\fIlinenumber\fP command line argument, where \fIlinenumber\fP is
the line number of the file line containing the display line
currently displayed as the first line of the screen. It is implementation-defined
whether line-setting options are passed to
editors other than \fIvi\fP and \fIex\fP.
.LP
When the editor exits, \fImore\fP shall resume with the same file
and screen as when the editor was invoked.
.SS Display Position
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fB=
<control>-G
\fP
.fi
.RE
.sp
.LP
Write a message for which the information references the first byte
of the line after the last line of the file on the screen.
This message shall include the name of the file currently being examined,
its number relative to the total number of files there
are to examine, the line number in the file, the byte number and the
total bytes in the file, and what percentage of the file
precedes the current position. If \fImore\fP is reading from standard
input, or the file is shorter than a single screen, the line
number, the byte number, the total bytes, and the percentage need
not be written.
.SS Quit
.TP 7
\fISynopsis\fP:
.sp
.RS
.nf

\fBq
:q
ZZ
\fP
.fi
.RE
.sp
.LP
Exit \fImore\fP.
.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
If an error is encountered accessing a file when using the \fB:n\fP
command, \fImore\fP shall attempt to examine the next file
in the argument list, but the final exit status shall be affected.
If an error is encountered accessing a file via the \fB:p\fP
command, \fImore\fP shall attempt to examine the previous file in
the argument list, but the final exit status shall be affected.
If an error is encountered accessing a file via the \fB:e\fP command,
\fImore\fP shall remain in the current file and the final
exit status shall not be affected.
.LP
\fIThe following sections are informative.\fP
.SH APPLICATION USAGE
.LP
When the standard output is not a terminal, only the \fB-s\fP filter-modification
option is effective. This is based on
historical practice. For example, a typical implementation of \fIman\fP
pipes its output
through \fImore\fP \fB-s\fP to squeeze excess white space for terminal
users. When \fIman\fP
is piped to \fIlp\fP, however, it is undesirable for this squeezing
to happen.
.SH EXAMPLES
.LP
The \fB-p\fP allows arbitrary commands to be executed at the start
of each file. Examples are:
.TP 7
\fImore\ \fP \fB-p\ G\ \fP \fIfile1\ file2\fP
.sp
Examine each file starting with its last screenful.
.TP 7
\fImore\ \fP \fB-p\ \fP 100\ \fIfile1\ file2\fP
.sp
Examine each file starting with line 100 in the current position (usually
the third line, so line 98 would be the first line
written).
.TP 7
\fImore\ \fP \fB-p\ \fP /100\ \fIfile1\ file2\fP
.sp
Examine each file starting with the first line containing the string
\fB"100"\fP in the current position
.sp
.SH RATIONALE
.LP
The \fImore\fP utility, available in BSD and BSD-derived systems,
was chosen as the prototype for the POSIX file display
program since it is more widely available than either the public-domain
program \fIless\fP or than \fIpg\fP, a pager provided in
System V. The 4.4 BSD \fImore\fP is the model for the features selected;
it is almost fully upwards-compatible from the 4.3 BSD
version in wide use and has become more amenable for \fIvi\fP users.
Several features
originally derived from various file editors, found in both \fIless\fP
and \fIpg\fP, have been added to this volume of
IEEE\ Std\ 1003.1-2001 as they have proved extremely popular with
users.
.LP
There are inconsistencies between \fImore\fP and \fIvi\fP that result
from historical
practice. For example, the single-character commands \fBh\fP, \fBf\fP,
\fBb\fP, and <space> are screen movers in
\fImore\fP, but cursor movers in \fIvi\fP. These inconsistencies were
maintained because the
cursor movements are not applicable to \fImore\fP and the powerful
functionality achieved without the use of the control key
justifies the differences.
.LP
The tags interface has been included in a program that is not a text
editor because it promotes another degree of consistent
operation with \fIvi\fP. It is conceivable that the paging environment
of \fImore\fP would be
superior for browsing source code files in some circumstances.
.LP
The operating mode referred to for block-mode terminals effectively
adds a <newline> to each Synopsis line that currently
has none. So, for example, \fBd\fP <newline> would page one screenful.
The mode could be triggered by a command line option,
environment variable, or some other method. The details are not imposed
by this volume of IEEE\ Std\ 1003.1-2001 because
there are so few systems known to support such terminals. Nevertheless,
it was considered that all systems should be able to
support \fImore\fP given the exception cited for this small community
of terminals because, in comparison to \fIvi\fP, the cursor movements
are few and the command set relatively amenable to the optional
<newline>s.
.LP
Some versions of \fImore\fP provide a shell escaping mechanism similar
to the \fIex\fP
\fB!\fP command. The standard developers did not consider that this
was necessary in a paginator, particularly given the wide
acceptance of multiple window terminals and job control features.
(They chose to retain such features in the editors and \fImailx\fP
because the shell interaction also gives an opportunity to modify
the editing buffer,
which is not applicable to \fImore\fP.)
.LP
The \fB-p\fP (position) option replaces the \fB+\fP command because
of the Utility Syntax Guidelines. In early proposals, it
took a \fIpattern\fP argument, but historical \fIless\fP provided
the \fImore\fP general facility of a command. It would have
been desirable to use the same \fB-c\fP as \fIex\fP and \fIvi\fP,
but the letter was already in use.
.LP
The text stating "from a non-rewindable stream ... implementations
may limit the amount of backwards motion supported" would
allow an implementation that permitted no backwards motion beyond
text already on the screen. It was not possible to require a
minimum amount of backwards motion that would be effective for all
conceivable device types. The implementation should allow the
user to back up as far as possible, within device and reasonable memory
allocation constraints.
.LP
Historically, non-printable characters were displayed using the ARPA
standard mappings, which are as follows:
.IP " 1." 4
Printable characters are left alone.
.LP
.IP " 2." 4
Control characters less than \\177 are represented as followed by
the character offset from the \fB'@'\fP character in the
ASCII map; for example, \\007 is represented as \fB'G'\fP .
.LP
.IP " 3." 4
\\177 is represented as followed by \fB'?'\fP .
.LP
.LP
The display of characters having their eighth bit set was less standard.
Existing implementations use hex (0x00), octal (\\000),
and a meta-bit display. (The latter displayed characters with their
eighth bit set as the two characters \fB"M-"\fP , followed
by the seven-bit display as described previously.) The latter probably
has the best claim to historical practice because it was
used with the \fB-v\fP option of 4 BSD and 4 BSD-derived versions
of the \fIcat\fP utility
since 1980.
.LP
No specific display format is required by IEEE\ Std\ 1003.1-2001.
Implementations are encouraged to conform to historic
practice in the absence of any strong reason to diverge.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIShell Command Language\fP , \fIctags\fP , \fIed\fP , \fIex\fP ,
\fIvi\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 .