lock_file.c: close(2) file descriptor on failure, avoiding leak.

[nmh] / man / mhlist.man

diff --git a/man/mhlist.man b/man/mhlist.man
index f6e752eff37721ef717a123c524e198e420d3078..da1ce8008953b6c8e2da864d081433363714f49c 100644 (file)
--- a/man/mhlist.man
+++ b/man/mhlist.man
@@ -1,13 +1,15 @@
-.TH MHLIST %manext1% "February 12, 2013" "%nmhversion%"
-.\"
+.TH MHLIST %manext1% 2015-02-06 "%nmhversion%"
+.

 .\" %nmhwarning%
 .\" %nmhwarning%

-.\"
+.

 .SH NAME
 .SH NAME

-mhlist \- list information about MIME messages
+mhlist \- list information about nmh MIME messages

 .SH SYNOPSIS
 .HP 5
 .na
 .B mhlist
 .SH SYNOPSIS
 .HP 5
 .na
 .B mhlist

+.RB [ \-help ]
+.RB [ \-version ]

 .RI [ +folder ]
 .RI [ msgs ]
 .RB [ \-file
 .RI [ +folder ]
 .RI [ msgs ]
 .RB [ \-file


@@ -18,6 +20,10 @@ mhlist \- list information about MIME messages
 .RB [ \-type
 .IR content ]
 \&...
 .RB [ \-type
 .IR content ]
 \&...

+.RB [ \-prefer
+.IR content ]
+\&...
+.RB [ \-noprefer ]

 .RB [ \-headers " | " \-noheaders ]
 .RB [ \-realsize " | " \-norealsize ]
 .RB [ \-rcache
 .RB [ \-headers " | " \-noheaders ]
 .RB [ \-realsize " | " \-norealsize ]
 .RB [ \-rcache


@@ -25,88 +31,111 @@ mhlist \- list information about MIME messages
 .RB [ \-wcache
 .IR policy ]
 .RB [ \-check " | " \-nocheck ]
 .RB [ \-wcache
 .IR policy ]
 .RB [ \-check " | " \-nocheck ]

+.RB [ \-changecur " | " \-nochangecur ]

 .RB [ \-verbose " | " \-noverbose ]
 .RB [ \-verbose " | " \-noverbose ]

-.RB [ \-version ]
-.RB [ \-help ]
+.RB [ \-disposition " | " \-nodisposition ]

 .ad
 .SH DESCRIPTION
 The
 .B mhlist
 .ad
 .SH DESCRIPTION
 The
 .B mhlist

-command allows you to list information (essentially
-a table of contents) about the various parts of a collection of
-MIME (multi-media) messages.
+command allows you to list information (a table of contents, essentially)
+about the various parts of a collection of MIME (multi-media) messages.

 .PP
 .B mhlist
 .PP
 .B mhlist

-manipulates MIME (multi-media messages) as specified
-in RFC\-2045 to RFC\-2049 (See
+manipulates MIME messages as specified in RFC 2045 to RFC 2049 (See

 .IR mhbuild (1)).
 .PP
 The
 .B \-headers
 .IR mhbuild (1)).
 .PP
 The
 .B \-headers

-switch indicates that a one-line banner should be
-displayed above the listing.
+switch indicates that a one-line banner should be displayed above the
+listing (the default).

 .PP
 The
 .B \-realsize
 switch tells
 .B mhlist
 .PP
 The
 .B \-realsize
 switch tells
 .B mhlist

-to evaluate the
-\*(lqnative\*(rq (decoded) format of each content prior to listing.
-This provides an accurate count at the expense of a small delay.
+to evaluate the \*(lqnative\*(rq (decoded) format of each content prior
+to listing.  This provides an accurate count at the expense of a small delay.
+In either case, sizes will be expressed using SI prefix abbreviations
+(K/M/G/T), which are based on factors of 1000.

 .PP
 If the
 .B \-verbose
 .PP
 If the
 .B \-verbose

-switch is present, then the listing will show
-any \*(lqextra\*(rq information that is present in the message,
-such as comments in the \*(lqContent-Type\*(rq header.
+switch is present, then the listing will show any \*(lqextra\*(rq
+information that is present in the message, such as comments in the
+\*(lqContent-Type\*(rq header.
+.PP
+If the
+.B \-disposition
+switch is present, then the listing will show any relevant information from
+the \*(lqContent-Disposition\*(rq header.

 .PP
 The option
 .B \-file
 .I file
 directs
 .B mhlist
 .PP
 The option
 .B \-file
 .I file
 directs
 .B mhlist

-to use the specified
-file as the source message, rather than a message from a folder.
-If you specify this file as \*(lq-\*(rq, then
+to use the specified file as the source message, rather than a message
+from a folder.  If you specify this file as \*(lq-\*(rq, then

 .B mhlist
 .B mhlist

-will
-accept the source message on the standard input.  Note that the
+will accept the source message on the standard input.  Note that the

 file, or input from standard input should be a validly formatted
 message, just like any other
 .B nmh
 message.  It should
 file, or input from standard input should be a validly formatted
 message, just like any other
 .B nmh
 message.  It should

-.B NOT
-be in mail drop format (to convert a file in mail drop format to
-a folder of
+.I not
+be in mail drop format (to convert a file in
+mail drop format to a folder of

 .B nmh
 messages, see
 .IR inc (1)).
 .PP
 By default,
 .B mhlist
 .B nmh
 messages, see
 .IR inc (1)).
 .PP
 By default,
 .B mhlist

-will list information about the entire
-message (all of its parts).  By using the
-.B \-part
+will list information about the entire message (all of its parts).
+By using the
+.BR \-part ,
+.BR \-type ,

 and
 and

-.B \-type
-switches, you may limit the scope of this command to particular
-subparts (of a multipart content) and/or particular content types.
-.PP
-A part specification consists of a series of numbers separated by dots.
-For example, in a multipart content containing three parts, these
-would be named as 1, 2, and 3, respectively.  If part 2 was also a
-multipart content containing two parts, these would be named as 2.1 and
-2.2, respectively.  Note that the
+.B \-prefer
+switches, you may limit and reorder the set of parts to be listed,
+based on part number and/or content type.
+.PP
+A part specification consists of a series of numbers separated by
+dots.  For example, in a multipart content containing three parts,
+these would be named as 1, 2, and 3, respectively.  If part 2 was also
+a multipart content containing two parts, these would be named as 2.1
+and 2.2, respectively.  Note that the

 .B \-part
 .B \-part

-switch is effective for only
-messages containing a multipart content.  If a message has some other
-kind of content, or if the part is itself another multipart content, the
+switch is effective only for messages containing a multipart content.
+If a message has some other kind of content, or if the part is itself
+another multipart content, the

 .B \-part
 switch will not prevent the content from being acted upon.
 .PP
 .B \-part
 switch will not prevent the content from being acted upon.
 .PP

+The
+.B \-type
+switch can also be used to restrict (or, when used in conjunction with
+.BR \-part ,
+to further restrict) the selection of parts according to content type.
+One or more
+.B \-type
+switches part will only select the first match from a multipart/alternative,
+even if there is more than one subpart that matches (one of) the given
+content type(s).
+.PP
+Using either
+.B \-part
+or
+.B -type
+switches alone will cause either to select the part(s) they match.
+Using them together will select only the part(s) matched by both
+(sets of) switches.  In other words, the result is the intersection,
+and not the union, of their separate match results.
+.PP

 A content specification consists of a content type and a subtype.
 The initial list of \*(lqstandard\*(rq content types and subtypes can
 A content specification consists of a content type and a subtype.
 The initial list of \*(lqstandard\*(rq content types and subtypes can

-be found in RFC\-2046.
+be found in RFC 2046.

 .PP
 A list of commonly used contents is briefly reproduced here:
 .PP
 .PP
 A list of commonly used contents is briefly reproduced here:
 .PP


@@ -132,32 +161,59 @@ name of the content, e.g., \*(lqaudio\*(rq.  To specify a specific
 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
 Note that regardless of the values given to the
 .B \-type
 subtype, separate the two with a slash, e.g., \*(lqaudio/basic\*(rq.
 Note that regardless of the values given to the
 .B \-type

-switch, a
-multipart content (of any subtype listed above) is always acted upon.
-Further note that if the
+switch, a multipart content (of any subtype listed above) is always
+acted upon.  Further note that if the

 .B \-type
 .B \-type

-switch is used, and it is desirable to
-act on a message/external-body content, then the
+switch is used, and it is desirable to act on a message/external-body
+content, then the

 .B \-type
 .B \-type

-switch must
-be used twice: once for message/external-body and once for the content
-externally referenced.
+switch must be used twice: once for message/external-body and once
+for the content externally referenced.
+.PP
+By default, the parts of a multipart/alternative part are listed in
+the reverse order of their placement in the message.  The listing,
+therefore, is in decreasing order of preference, as defined in RFC
+2046.  The
+.B \-prefer
+switch can be used (one or more times, in order of ascending
+preference) to let MH know which content types from a
+multipart/alternative MIME part are preferred by the user, in order to
+override the default preference order.  Thus, when viewed by
+.BR mhlist ,
+the ordering of multipart/alternative parts will appear to change when
+invoked with or without various
+.B \-prefer
+switches.
+The
+.B \-noprefer
+switch will cancel any previous
+.B \-prefer
+switches.
+The
+.B \-prefer
+and
+.B \-noprefer
+switches are functionally most important for
+.BR mhshow ,
+but are also implemented in
+.B mhlist
+and
+.B mhstore
+to make common part numbering possible across all three programs.

 .SS "Checking the Contents"
 The
 .B \-check
 switch tells
 .B mhlist
 .SS "Checking the Contents"
 The
 .B \-check
 switch tells
 .B mhlist

-to check each content for an
-integrity checksum.  If a content has such a checksum (specified as a
-Content-MD5 header field), then
+to check each content for an integrity checksum.  If a content has
+such a checksum (specified as a Content-MD5 header field), then

 .B mhlist
 .B mhlist

-will attempt to verify the
-integrity of the content.
+will attempt to verify the integrity of the content.

 .SH FILES
 .fc ^ ~
 .nf
 .SH FILES
 .fc ^ ~
 .nf

-.ta \w'%etcdir%/ExtraBigFileName  'u
-^$HOME/\&.mh\(ruprofile~^The user profile
+.ta \w'%nmhetcdir%/ExtraBigFileName  'u
+^$HOME/.mh_profile~^The user profile

 .fi
 .SH "PROFILE COMPONENTS"
 .fc ^ ~
 .fi
 .SH "PROFILE COMPONENTS"
 .fc ^ ~


@@ -180,8 +236,12 @@ integrity of the content.
 .RB ` \-realsize '
 .RB ` \-rcache\ ask '
 .RB ` \-wcache\ ask '
 .RB ` \-realsize '
 .RB ` \-rcache\ ask '
 .RB ` \-wcache\ ask '

+.RB ` \-changecur '

 .RB ` \-noverbose '
 .RB ` \-noverbose '

+.RB ` \-nodisposition '

 .fi
 .SH CONTEXT
 If a folder is given, it will become the current folder.  The last
 .fi
 .SH CONTEXT
 If a folder is given, it will become the current folder.  The last

-message selected will become the current message.
+message selected will become the current message, unless the
+.B \-nochangecur
+option is specified.