Manual Reference Pages - MH-SEQUENCE (5)
mh-sequence - sequence specification for nmh message system
Sequence File Format
Sequence File Locking
A sequence (or sequence set) is a symbolic name representing a
message or collection of messages.
nmh has several internally
defined sequences, as well as allowing users to define their own
Message Specification and Pre-Defined Message Sequences
nmh commands accept a msg or msgs specification, where
msg indicates one message and msgs indicates one or more messages.
To designate a message, you may use either its number (e.g., 1, 10, 234)
or one of these reserved message names:
first the first message in the folder
last the last message in the folder
cur the most recently accessed message
prev the message numerically preceding cur
next the message numerically following cur
In commands that take a msg argument, the default is cur.
As a shorthand, . is equivalent to cur.
For example: In a folder containing five messages numbered 5, 10, 94, 177
and 325, first is 5 and last is 325. If cur
is 94, then prev is 10 and next is 177.
The word msgs indicates that one or more messages may be specified.
Such a specification consists of one message designation or of several
message designations, as separate arguments. A message designation consists
either of a message name as defined above, or a message range.
A message range is specified as name1-name2 or
name:n, where name, name1 and name2 are message names,
and n is an integer.
The specification name1-name2 designates all currently existing
messages from name1 to name2 inclusive. The reserved
message name all is a shorthand for the message range
The specification name:n designates up to n messages.
These messages start with name if name is a message number or one of
the reserved names first cur, or next, The
messages end with name if name is prev or last.
The interpretation of n may be overridden by preceding n with a
plus or minus sign; +n always means up to n messages starting with
name, and -n always means up to n messages ending with name.
Substituting = for : (i.e., name=n) will reduce the
selection from a range of up to n messages, to a selection of
just the nth message. So for example, while name:-3
selects the 3 messages ending with name, name=-3 selects
just the 2nd previous message. It is an error if the requested
message does not exist (i.e., there arent enough messages in the
In commands which accept a msgs argument, the default is either
cur or all, depending on which makes more sense
for each command (see the individual man pages for details). Repeated
specifications of the same message have the same effect as a single
specification of the message.
There is also a special reserved message name new
which is used by the
User-Defined Message Sequences
In addition to the reserved (pre-defined) message names given
nmh supports user-defined sequence names. User-defined
sequences allow the
nmh user a tremendous amount of power in dealing
with groups of messages in the same folder by allowing the user to bind
a group of messages to a meaningful symbolic name.
The name used to denote a message sequence must consist of an alphabetic
character followed by zero or more alphanumeric characters, and can not
be one of the reserved message names above. After defining a
sequence, it can be used wherever an
nmh command expects a msg or
Some forms of message ranges are allowed with user-defined sequences.
The specification name:n may be used, and it designates up
to the first n messages (or last n messages for -n) which are
elements of the user-defined sequence name.
The specifications name:next and name:prev may also
be used, and they designate the next or previous message (relative to the
current message) which is an element of the user-defined sequence name.
The specifications name:first and name:last are
equivalent to name:1 and name:-1, respectively. The
specification name:cur is not allowed (use just cur
instead). The syntax of these message range specifications is subject
to change in the future.
Single messages (as opposed to ranges) may also be selected by
substituting = for :, as in name=n. This will reduce
the selection from being a range of up to n messages, to being a
selection of just the nth message. So while seq:5
selects the first 5 messages of seqence seq, seq=5
selects just the 5th message of the sequence. It is
an error if the requested message does not exist (i.e., there arent
at least n messages in the sequence).
User-defined sequence names are specific to each folder. They are
defined using the
Public and Private User-Defined Sequences
There are two varieties of user-defined sequences:
public and private. Public sequences of a folder are accessible to any
nmh user that can read that folder. They are kept in each folder
in the file determined by the mh-sequences profile entry
.mh_sequences). Private sequences are accessible
only to the
nmh user that defined those sequences and are kept in
nmh context file.
In general, the commands that create sequences (such as
mark) will create public sequences if the folder for which
the sequences are being defined is writable by the
For most commands, this can be overridden by using the switches
-private. But if the folder is read-only, or if
the mh-sequences profile entry is defined but empty, then
private sequences will be created instead.
Nmh provides the ability to select all messages not elements of a
user-defined sequence. To do this, the user should define the entry
Sequence-Negation in the
nmh profile file; its value
may be any string. This string is then used to preface an existing
user-defined sequence name. This specification then refers to those
messages not elements of the specified sequence name. For example, if
the profile entry is:
then anytime an
nmh command is given notfoo as a msg or
msgs argument, it would substitute all messages that are not elements
of the sequence foo.
Obviously, the user should beware of defining sequences with names that
begin with the value of the Sequence-Negation profile entry.
The Previous Sequence
Nmh provides the ability to remember the msgs or msg argument
last given to an
nmh command. The entry Previous-Sequence
should be defined in the
nmh profile; its value should be a sequence
name or multiple sequence names, as separate arguments. If this entry
is defined, when when an
nmh command finishes, it will define the
sequence(s) named in the value of this entry to be those messages that
were specified to the command. Hence, a profile entry of
nmh command that accepts a msg or msgs argument to
define the sequence pseq as those messages when it finishes.
Note: there can be a performance penalty in using the
Previous-Sequence facility. If it is used,
nmh programs have to write the sequence information to the
.mh_sequences file for the folder each time they run. If the
Previous-Sequence profile entry is not included, only
mark will write to the
The Unseen Sequence
Finally, many users like to indicate which messages have not been
previously seen by them. The commands
flist honor the profile entry
Unseen-Sequence to support this activity. This entry
.mh_profile should be defined as one or more sequence
names, as separate arguments. If there is a value for
Unseen-Sequence in the profile, then whenever new messages
are placed in a folder (using
rcvstore), the new messages will also be added to all the sequences named in this
profile entry. For example, a profile entry of
inc to add new messages to the sequence unseen.
Unlike the behavior of the Previous-Sequence entry in the
profile, however, the sequence(s) will
not be zeroed by
prev displays a message, that message will be removed from
any sequences named by the Unseen-Sequence entry in the
Sequence File Format
The sequence file format is based on the RFC-5322 message format. Each line
of the sequence file corresponds to one sequence. The line starts with the
sequence name followed by a :, then followed by a space-separated list of message numbers
that correspond to messages that are part of the named sequence. A contiguous
range of messages can be represented as lownum-highnum.
Sample sequence file
work: 3 6 8 22-33 46
unseen: 47 49-51 54
Nmh commands that modify the sequence file will silently remove sequences for
nonexistant messages when the sequence file is updated. The exception to
this is the cur sequence, which is allowed to point to a
Sequence File Locking
The datalocking profile entry controls the type of locking used
when reading and writing sequence files. The locking mechanisms supported
are detailed in
This protects sequence file integrity when multiple
nmh commands are run simultaneously.
Nmh commands that modify the sequence file use transactional locks; the lock
is held from the time the sequence file is read until it it written out.
This ensures that modifications to the sequence file will not be lost
if multiple commands are run simultaneously. Long-running
nmh commands, such as
pick, will release the sequence lock during the bulk of their runtime and reread
the sequence file after their processing is complete to reduce lock
Note: Currently transactional locks are
only supported for public sequences; private sequences will not get corrupted, but
the possibility exists that two
nmh commands run simultaneously that add messages to a private sequence could result in
one commands messages not appearing on the requested sequence.
^$HOME/.mh_profile~^The user profile
^<mh-dir>/context~^The user context
^<folder>/.mh_sequences~^File for public sequences
^mh-sequences:~^Name of file to store public sequences
^Sequence-Negation:~^To designate messages not in a sequence
^Previous-Sequence:~^The last message specification given
^Unseen-Sequence:~^Those messages not yet seen by the user
|nmh-1.6 ||MH-SEQUENCE (5) ||June 11, 2013 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.