1 .\"@ nail.1 - S-nail(1) reference manual.
3 .\" Copyright (c) 2000-2008 Gunnar Ritter, Freiburg i. Br., Germany.
4 .\" Copyright (c) 2012 - 2017 Steffen (Daode) Nurpmeso <steffen@sdaoden.eu>.
6 .\" Copyright (c) 1980, 1990, 1993
7 .\" The Regents of the University of California. All rights reserved.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
12 .\" 1. Redistributions of source code must retain the above copyright
13 .\" notice, this list of conditions and the following disclaimer.
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\" 3. Neither the name of the University nor the names of its contributors
18 .\" may be used to endorse or promote products derived from this software
19 .\" without specific prior written permission.
21 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
22 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
23 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
24 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
25 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
26 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
27 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
28 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
29 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
30 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\"@ S-nail(1): v14.9.0-pre3 / 2016-12-31
36 .ds VV \\%v14.9.0-pre3
46 .\" If not ~/.mailrc, it breaks POSIX compatibility. And adjust main.c.
51 .ds OU [no v15-compat]
52 .ds ID [v15 behaviour may differ]
53 .ds NQ [Only new quoting rules]
64 .Nd send and receive Internet mail
70 .\" Keep in SYNC: ./nail.1:"SYNOPSIS, main()
78 .Op Fl a Ar attachment
81 .Op Fl M Ar type | Fl m Ar file | Fl q Ar file | Fl t
83 .Op Fl S Ar var Ns Op Ns = Ns Ar value
88 .Op Fl Fl \~ Ns Ar mta-option ...
97 .Op Fl S Ar var Ns Op Ns = Ns Ar value
100 .Op Fl Fl \~ Ns Ar mta-option ...
108 .Op Fl L Ar spec-list
109 .Op Fl r Ar from-addr
110 .Op Fl S Ar var Ns Op Ns = Ns Ar value
113 .Op Fl Fl \~ Ns Ar mta-option ...
118 .Mx -toc -tree html pdf ps xhtml
121 .\" .Sh DESCRIPTION {{{
124 .Bd -filled -compact -offset indent
125 .Sy Compatibility note:
126 S-nail (\*(UA) will wrap up into \%S-mailx in v15.0 (circa 2018).
127 Backward incompatibility has to be expected \(en
130 .Sx "Shell-style argument quoting"
131 rules, for example, and shell metacharacters will become meaningful.
132 New and old behaviour is flagged \*(IN and \*(OU, and setting
135 .Sx "INTERNAL VARIABLES" ,
136 will choose new behaviour when applicable.
137 \*(OB flags what will vanish, and enabling
141 enables obsoletion warnings.
145 \*(UA provides a simple and friendly environment for sending and
147 It is intended to provide the functionality of the POSIX
149 command, but is MIME capable and optionally offers extensions for
150 line editing, S/MIME, SMTP and POP3, among others.
151 \*(UA divides incoming mail into its constituent messages and allows
152 the user to deal with them in any order.
156 .Sx "INTERNAL VARIABLES"
157 for manipulating messages and sending mail.
158 It provides the user simple editing capabilities to ease the composition
159 of outgoing messages, and increasingly powerful and reliable
160 non-interactive scripting capabilities.
162 .\" .Ss "Options" {{{
165 .Bl -tag -width ".It Fl BaNg"
168 Explicitly control which of the
170 shall be loaded: if the letter
172 is (case-insensitively) part of the
176 is loaded, likewise the letter
178 controls loading of the user's personal
180 file, whereas the letters
184 explicitly forbid loading of any resource files.
185 This option should be used by scripts: to avoid environmental noise they
188 from any configuration files and create a script-local environment,
189 explicitly setting any of the desired
190 .Sx "INTERNAL VARIABLES"
193 This option overrides
200 command for the given user email
202 after program startup is complete (all resource files are loaded, any
204 setting is being established; only
206 commands have not been evaluated yet).
207 Being a special incarnation of
209 macros for the purpose of bundling longer-lived settings, activating
210 such an email account also switches to the accounts
212 .Sx "primary system mailbox"
217 .It Fl a Ar file Ns Op Ar =input-charset Ns Op Ar #output-charset
220 to the message (for compose mode opportunities refer to
224 .Sx "Filename transformations"
227 will be performed, but shell word expansion is restricted to the tilde
231 not be accessible but contain a
233 character, then anything before the
235 will be used as the filename, anything thereafter as a character set
238 If an input character set is specified,
239 .Mx -ix "character set specification"
240 but no output character set, then the given input character set is fixed
241 as-is, and no conversion will be applied;
242 giving the special string hyphen-minus
244 will be treated as if
246 has been specified (the default).
247 If an output character set has also been given then the conversion will
248 be performed exactly as specified and on-the-fly, not considering the
249 file's type and content.
250 As an exception, if the output character set is specified as hyphen-minus
252 then the default conversion algorithm (see
253 .Sx "Character sets" )
254 is applied (therefore no conversion is performed on-the-fly,
256 will be MIME-classified and its contents will be inspected first).
257 It is an error to specify anything but
259 if no character set conversion is available
261 does not include the term
266 (\*(OB: \*(UA will always use line-buffered output, to gain
267 line-buffered input even in batch mode enable batch mode via
272 Send a blind carbon copy to
274 ess, if the setting of
277 .Sx "INTERNAL VARIABLES" ,
279 The option may be used multiple times.
281 .Sx "On sending mail, and non-interactive mode" .
285 Send carbon copies to the given receiver, if so allowed by
287 May be used multiple times.
292 the internal variable
294 which enables debug messages and disables message delivery,
295 among others; effectively turns almost any operation into a dry-run.
301 and thus discard messages with an empty message part body.
302 This command line option is \*(OB.
306 Just check if mail is present (in the specified or system
308 if yes, return an exit status of zero, a non-zero value otherwise.
309 To restrict the set of mails to consider in this evaluation a message
310 specification can be added with the option
315 Save the message to send in a file named after the local part of the
316 first recipient's address (instead of in
321 Read in the contents of the user's
323 .Sx "secondary mailbox"
325 (or the specified file) for processing;
326 when \*(UA is quit, it writes undeleted messages back to this file
332 argument will undergo some special
333 .Sx "Filename transformations"
338 is not a argument to the flag
340 but is instead taken from the command line after option processing has
344 that starts with a hyphen-minus, prefix with a relative path, as in
345 .Ql ./-hyphenbox.mbox .
349 Display a summary of the
351 of all messages in the specified mailbox or system
354 A configurable summary view is available via the
360 Show a short usage summary.
361 Because of widespread use a
363 argument will have the same effect.
369 to ignore tty interrupt signals.
372 .It Fl L Ar spec-list
373 Display a summary of all
375 of only those messages in the specified mailbox or the system
381 .Sx "Specifying messages"
388 option has been given in addition no header summary is produced,
389 but \*(UA will instead indicate via its exit status whether
395 note that any verbose output is suppressed in this mode and must instead
396 be enabled explicitly (e.g., by using the option
401 Special send mode that will flag standard input with the MIME
405 and use it as the main message body.
406 \*(ID Using this option will bypass processing of
407 .Va message-inject-head ,
410 .Va message-inject-tail .
416 Special send mode that will MIME classify the specified
418 and use it as the main message body.
419 \*(ID Using this option will bypass processing of
420 .Va message-inject-head ,
423 .Va message-inject-tail .
429 inhibit the initial display of message headers when reading mail or
430 editing a mail folder by calling
432 for the internal variable
437 Standard flag that inhibits reading the system wide
442 allows more control over the startup sequence; also see
443 .Sx "Resource files" .
447 Special send mode that will initialize the message body with the
448 contents of the specified
450 which may be standard input
452 only in non-interactive context.
458 Any folder opened will be in read-only mode.
462 .It Fl r Ar from-addr
463 The source address that appears in the
466 header of a message (or in the
469 header if the former contains multiple addresses) is not used for
470 relaying and delegating a message over the wire via SMTP, but instead an
471 envelope will enwrap the message content and provide the necessary
472 information (i.e., the RFC 5321 reverse-path, also used to report, e.g.,
473 delivery errors) to transmit the message to its destination(s).
474 Whereas said headers and internal variables will be used by \*(UA to
475 create the envelope if the builtin SMTP
477 (Mail-Transfer-Agent) is used, a file-based MTA will instead use the
478 identity of the message-originating user.
480 This command line option can be used to specify the reverse-path, to be
481 passed to a file-based
483 when a message is sent, via
484 .Ql -f Ar from-addr .
487 include a user name, then the address components will be separated and
488 the name part will be passed to a file-based
494 is also assigned to the internal variable
496 Many default installations and sites disallow explicit overriding of the
497 user identity which could be adjusted by this option, unless either
499 has been configured accordingly, or the user is member of a group with
500 special privileges, respectively.
502 If an empty string is passed as
504 then the content of the variable
506 (or, if that contains multiple addresses,
508 will be evaluated and used for this purpose whenever the file-based
511 Note that \*(UA by default, without
513 that is, neither passes
517 command line options to a file-based MTA by itself, unless this
518 automatic deduction is enforced by
520 ing the internal variable
521 .Va r-option-implicit .
525 .It Fl S Ar var Ns Op = Ns value
529 iable and, in case of a non-boolean variable which has a value, assign
533 .Sx "INTERNAL VARIABLES"
537 may be overwritten from within resource files,
538 the command line setting will be reestablished after all resource files
539 have been loaded in the order they have been given on the command line.
543 Specify the subject of the message to be sent.
544 Newline (NL) and carriage-return (CR) bytes are invalid and will be
545 normalized to space (SP) characters.
549 The message given (on standard input) is expected to contain, separated
550 from the message body by an empty line, a message header with
555 fields giving its recipients, which will be added to any recipients
556 specified on the command line.
557 If a message subject is specified via
559 then it will be used in favour of one given on the command line.
575 .Ql Mail-Followup-To: ,
576 by default created automatically dependent on message context, will
577 be used if specified (a special address massage will however still occur
579 Any other custom header field (also see
582 is passed through entirely
583 unchanged, and in conjunction with the option
585 it is possible to embed
586 .Sx "COMMAND ESCAPES" .
594 .Sx "primary system mailbox"
597 appropriate privileges presumed; effectively identical to
607 will also show the list of
609 .Ql $ \*(uA -Xversion -Xx .
614 ting the internal variable
616 enables display of some informational context messages.
617 Using it twice increases the level of verbosity.
621 Add the given (or multiple for a multiline argument)
623 to the list of commands to be executed,
624 as a last step of program startup, before normal operation starts.
625 This is the only possibility to execute commands in non-interactive mode
626 when reading startup files is actively prohibited.
627 The commands will be evaluated as a unit, just as via
637 .Sx "COMMAND ESCAPES"
638 in compose mode even in non-interactive use cases.
639 This can be used to, e.g., automatically format the composed message
640 text before sending the message:
641 .Bd -literal -offset indent
642 $ ( echo 'line one. Word. Word2.';\e
643 echo '~| /usr/bin/fmt -tuw66' ) |\e
644 LC_ALL=C \*(uA -d~:/ -Sttycharset=utf-8 bob@exam.ple
649 Enables batch mode: standard input is made line buffered, the complete
650 set of (interactive) commands is available, processing of
651 .Sx "COMMAND ESCAPES"
652 is enabled in compose mode, and diverse
653 .Sx "INTERNAL VARIABLES"
654 are adjusted for batch necessities, exactly as if done via
670 The following prepares an email message in a batched dry run:
671 .Bd -literal -offset indent
672 $ LC_ALL=C printf 'm bob\en~s ubject\enText\en~.\enx\en' |\e
673 LC_ALL=C \*(uA -d#:/ -X'alias bob bob@exam.ple'
678 This flag forces termination of option processing in order to prevent
681 It also forcefully puts \*(UA into send mode, see
682 .Sx "On sending mail, and non-interactive mode" .
690 argument, as well as all receivers established by the command line options
694 are subject to checks established via
697 .Sx "INTERNAL VARIABLES" .
699 .Op Ar mta-option ...
701 arguments that are given at the end of the command line after a
703 separator will be passed through to a file-based
705 (Mail-Transfer-Agent) and persist for an entire (interactive) session
706 \(en if the setting of the internal variable
708 allows their recognition; no such constraints apply to the variable
712 .\" .Ss "A starter" {{{
715 \*(UA is a direct descendant of
717 Mail, a successor of the Research
720 .Dq was there from the start
723 It thus represents the user side of the
725 mail system, whereas the system side (Mail-Transfer-Agent, MTA) was
726 traditionally taken by
728 and most MTAs provide a binary of this name for compatibility purposes.
733 of \*(UA then the system side is not a mandatory precondition for mail
737 Because \*(UA strives for compliance with POSIX
739 it is likely that some configuration settings have to be adjusted before
740 using it is a smooth experience.
743 resource file bends those standard imposed settings of the
744 .Sx "INTERNAL VARIABLES"
745 a bit towards more user friendliness and safety, however, e.g., it
750 in order to suppress the automatic moving of messages to the
752 .Sx "secondary mailbox"
754 that would otherwise occur (see
755 .Sx "Message states" ) ,
758 to not remove empty system (MBOX) mailbox files in order not to mangle
759 file permissions when files eventually get recreated \(en
760 \*(UA will remove all empty (MBOX) mailbox files unless this variable is
763 .Pf ( Ev POSIXLY_CORRECT )
764 mode has been enabled.
765 The file mode creation mask is explicitly managed via
771 in order to synchronize \*(UA with the exit status report of the used
776 to enter interactive startup even if the initial mailbox is empty,
778 to allow editing of headers as well as
780 to not strip down addresses in compose mode, and
782 to include the message that is being responded to when
787 contains some more complete configuration examples.
790 .\" .Ss "On sending mail, and non-interactive mode" {{{
791 .Ss "On sending mail, and non-interactive mode"
793 To send a message to one or more people, using a local or a builtin
795 (Mail-Transfer-Agent) transport to actually deliver the generated mail
796 message, \*(UA can be invoked with arguments which are the names of
797 people to whom the mail will be sent, and the command line options
801 can be used to add (blind) carbon copy receivers:
803 .Bd -literal -offset indent
805 $ \*(uA -s ubject -a ttach.txt bill@exam.ple
807 # But... try it in an isolated dry-run mode (-d) first
808 $ LC_ALL=C \*(uA -d -:/ -Ssendwait \e
809 -b bcc@exam.ple -c cc@exam.ple \e
810 -. '(Lovely) Bob <bob@exam.ple>' eric@exam.ple
813 $ LC_ALL=C \*(uA -d -:/ -Sv15-compat -Ssendwait \e
814 -S mta=smtps://mylogin@exam.ple:465 -Ssmtp-auth=none \e
815 -S from=scriptreply@exam.ple \e
821 If standard input is a terminal rather than the message to be sent,
822 the user is expected to type in the message contents.
823 In this compose mode \*(UA treats lines beginning with the character
825 special \(en these are so-called
826 .Sx "COMMAND ESCAPES" ,
827 which can be used to read in files, process shell commands, add and edit
828 attachments and more; e.g., the command escape
830 will start the text editor to revise the message in its current state,
832 allows editing of the most important message headers, with
834 custom headers can be created (more specifically than with
837 gives an overview of most other available command escapes.
841 at the beginning of an empty line leaves compose mode and causes the
842 message to be sent, whereas typing
845 twice will abort the current letter (saving its contents in the file
856 .Sx "INTERNAL VARIABLES"
857 can be used to alter default behavior.
858 E.g., messages are sent asynchronously, without supervision, unless the
861 is set, therefore send errors will not be recognizable until then.
866 will automatically startup a text editor when compose mode is entered,
868 allows editing of headers additionally to plain body content, whereas
872 will cause the user to be prompted actively for (blind) carbon-copy
873 recipients, respectively, if the given list is empty.
877 hook variables may be set to
879 d macros to automatically adjust some settings dependent
880 on receiver, sender or subject contexts, and via the
881 .Va on-compose-splice-shell
883 .Va on-compose-splice
884 variables, the latter also to be set to a
886 d macro, increasingly powerful mechanisms to perform automated message
887 adjustments are available.
890 Especially for using public mail provider accounts with the SMTP
892 it is often necessary to set
896 (even finer control via
897 .Va smtp-hostname ) ,
898 which (even if empty) also causes creation of
904 is set; saving a copy of sent messages in a
906 mailbox may be desirable \(en as for most mailbox
908 targets the value will undergo
909 .Sx "Filename transformations" .
912 for the purpose of arranging a complete environment of settings that can
913 be switched to with a single command or command line option may be
916 contains example configurations for sending messages via some of the
917 well-known public mail providers and also gives a compact overview on
918 how to setup a secure SSL/TLS environment).
923 sandbox dry-run tests first will prove correctness.
927 .Sx "On URL syntax and credential lookup"
928 will spread light on the different ways of how to specify user email
929 account credentials, the
931 variable chains, and accessing protocol-specific resources,
934 goes into the details of character encoding and how to use them for
935 representing messages and MIME part contents by specifying them in
937 and reading the section
938 .Sx "The mime.types files"
939 should help to understand how the MIME-type of outgoing attachments are
940 classified, and what can be done for fine-tuning.
941 Over the wire an intermediate, configurable
942 .Pf content-transfer-\: Va encoding
943 may be applied to the raw message part data.
946 Message recipients (as specified on the command line or defined in
951 may not only be email addressees but can also be names of mailboxes and
952 even complete shell command pipe specifications.
955 is not set then only network addresses (see
957 for a description of mail addresses) and plain user names (including MTA
958 aliases) may be used, other types will be filtered out, giving a warning
962 can be used to generate standard compliant network addresses.
964 .\" When changing any of the following adjust any RECIPIENTADDRSPEC;
965 .\" grep the latter for the complete picture
969 is set then extended recipient addresses will optionally be accepted:
970 Any name which starts with a vertical bar
972 character specifies a command pipe \(en the command string following the
974 is executed and the message is sent to its standard input;
975 Likewise, any name that starts with the character solidus
977 or the character sequence dot solidus
979 is treated as a file, regardless of the remaining content;
980 likewise a name that solely consists of a hyphen-minus
982 Any other name which contains a commercial at
984 character is treated as a network address;
985 Any other name which starts with a plus sign
987 character specifies a mailbox name;
988 Any other name which contains a solidus
990 character but no exclamation mark
994 character before also specifies a mailbox name;
995 What remains is treated as a network address.
997 .Bd -literal -offset indent
998 $ echo bla | \*(uA -Sexpandaddr -s test ./mbox.mbox
999 $ echo bla | \*(uA -Sexpandaddr -s test '|cat >> ./mbox.mbox'
1000 $ echo safe | LC_ALL=C \e
1001 \*(uA -:/ -Sv15-compat -Ssendwait \e
1002 -Sexpandaddr=fail,-all,+addr,failinvaddr -s test \e
1007 It is possible to create personal distribution lists via the
1009 command, so that, for instance, the user can send mail to
1011 and have it go to a group of people.
1012 These aliases have nothing in common with the system wide aliases that
1013 may be used by the MTA, which are subject to the
1017 and are often tracked in a file
1023 Personal aliases will be expanded by \*(UA before the message is sent,
1024 and are thus a convenient alternative to specifying each addressee by
1025 itself; they correlate with the active set of
1032 .Dl alias cohorts bill jkf mark kridle@ucbcory ~/mail/cohorts.mbox
1035 To avoid environmental noise scripts should
1037 \*(UA from any configuration files and create a script-local
1038 environment, ideally with the command line options
1040 to disable any configuration file in conjunction with repetitions of
1042 to specify variables:
1044 .Bd -literal -offset indent
1045 $ env LC_ALL=C \*(uA -:/ \e
1046 -Sv15-compat -Ssendwait -Sttycharset=utf-8 \e
1047 -Sexpandaddr=fail,-all,failinvaddr \e
1048 -S mta=smtps://mylogin@exam.ple:465 -Ssmtp-auth=login \e
1049 -S from=scriptreply@exam.ple \e
1050 -s 'Subject to go' -a attachment_file \e
1051 -. 'Recipient 1 <rec1@exam.ple>' rec2@exam.ple \e
1056 As shown, scripts can
1058 a locale environment, the above specifies the all-compatible 7-bit clean
1061 but will nonetheless take and send UTF-8 in the message text by using
1063 In interactive mode, which is introduced in the next section, messages
1064 can be sent by calling the
1066 command with a list of recipient addresses \(em the semantics are
1067 completely identical to non-interactive message sending:
1069 .Bd -literal -offset indent
1070 $ \*(uA -d -Squiet -Semptystart
1071 "/var/spool/mail/user": 0 messages
1072 ? mail "Recipient 1 <rec1@exam.ple>", rec2@exam.ple
1073 ? # Will do the right thing (tm)
1074 ? m rec1@exam.ple rec2@exam.ple
1078 .\" .Ss "On reading mail, and interactive mode" {{{
1079 .Ss "On reading mail, and interactive mode"
1081 When invoked without addressees \*(UA enters interactive mode in which
1083 When used like that the user's system
1087 for an in-depth description of the different mailbox types that exist)
1088 is read in and a one line header of each message therein is displayed.
1089 The visual style of this summary of
1091 can be adjusted through the variable
1093 and the possible sorting criterion via
1099 can be performed with the command
1101 If the initially opened mailbox is empty \*(UA will instead exit
1102 immediately (after displaying a message) unless the variable
1111 will give a listing of all available commands and
1113 will give a summary of some common ones.
1114 If the \*(OPal documentation strings are available one can type
1117 and see the actual expansion of
1119 and what its purpose is, i.e., commands can be abbreviated
1120 (note that POSIX defines some abbreviations, so that the alphabetical
1121 order of commands does not necessarily relate to the abbreviations; it is
1122 however possible to define overwrites with
1123 .Ic commandalias ) .
1124 These commands can also produce a more
1129 Messages are given numbers (starting at 1) which uniquely identify
1130 messages; the current message \(en the
1132 \(en will either be the first new message, or the first unread message,
1133 or the first message of the mailbox; the internal variable
1135 will instead cause usage of the last message for this purpose.
1140 ful of header summaries containing the
1144 will display only the summaries of the given messages, defaulting to the
1148 Message content can be displayed with the command
1155 controls whether and when \*(UA will use the configured
1157 for display instead of directly writing to the user terminal
1159 the sole difference to the command
1161 which will always use the
1165 will instead only show the first
1167 of a message (maybe even compressed if
1172 By default the current message
1174 is displayed, but like with many other commands it is possible to give
1175 a fancy message specification (see
1176 .Sx "Specifying messages" ) ,
1179 will display all unread messages,
1184 will type the messages 1 and 5,
1186 will type the messages 1 through 5, and
1190 will display the last and the next message, respectively.
1193 (a more substantial alias for
1195 will display a header summary of the given message specification list
1196 instead of their content, e.g., the following will search for subjects:
1199 .Dl from "'@Some subject to search for'"
1202 In the default setup all header fields of a message will be
1204 d, but fields can be white- or blacklisted for a variety of
1205 applications by using the command
1207 e.g., to restrict display to a very restricted set:
1208 .Ql Ic \:headerpick Cd \:type retain Ar \:from to cc subject .
1209 In order to display all header fields of a message regardless of
1210 currently active ignore or retain lists, use the commands
1214 Note that historically the global
1216 not only adjusts the list of displayed headers, but also sets
1220 Dependent upon the configuration a line editor (see the section
1221 .Sx "On terminal control and line editor" )
1222 aims at making user experience with the many
1225 When reading the system
1231 specified a mailbox explicitly prefixed with the special
1233 modifier (propagating the mailbox to a
1235 .Sx "primary system mailbox" ) ,
1236 then messages which have been read will be moved to a
1238 .Sx "secondary mailbox" ,
1241 file, automatically when the mailbox is left, either by changing the
1242 active mailbox or by quitting \*(UA (also see
1243 .Sx "Message states" )
1244 \(en this automatic moving from a system or primary to the secondary
1245 mailbox is not performed when the variable
1250 After examining a message the user can also
1254 to the sender and all recipients or
1256 exclusively to the sender(s).
1257 Messages can also be
1259 ed (shorter alias is
1261 Note that when replying to or forwarding a message recipient addresses
1262 will be stripped from comments and names unless the internal variable
1265 Deletion causes \*(UA to forget about the message;
1266 This is not irreversible, though, one can
1268 the message by giving its number,
1269 or the \*(UA session can be ended by giving the
1274 To end a mail processing session one may either issue
1276 to cause a full program exit, which possibly includes
1277 automatic moving of read messages to the
1279 .Sx "secondary mailbox"
1281 as well as updating the \*(OPal line editor
1285 instead in order to prevent any of these actions.
1288 .\" .Ss "HTML mail and MIME attachments" {{{
1289 .Ss "HTML mail and MIME attachments"
1291 Messages which are HTML-only get more and more common and of course many
1292 messages come bundled with a bouquet of MIME attachments.
1293 Whereas \*(UA \*(OPally supports a simple HTML-to-text converter to deal
1294 with HTML messages (see
1295 .Sx "The mime.types files" ) ,
1296 it normally cannot deal with any of these itself, but instead programs
1297 need to become registered to deal with specific MIME types or file
1299 These programs may either prepare plain text versions of their input
1300 in order to enable \*(UA to display the content on the terminal,
1301 or display the content themselves, for example in a graphical window.
1304 To install an external handler program for a specific MIME type set an
1306 .Va pipe-TYPE/SUBTYPE
1307 variable; to instead define a handler for a specific file extension set
1310 variable \(en these handlers take precedence.
1311 \*(OPally \*(UA supports mail user agent configuration as defined in
1312 RFC 1524; this mechanism, documented in the section
1313 .Sx "The Mailcap files" ,
1314 will be queried for display or quote handlers if none of the former two
1315 .\" TODO v15-compat "will be" -> "is"
1316 did; it will be the sole source for handlers of other purpose.
1317 A last source for handlers may be the MIME type definition itself, if
1318 the \*(UA specific type-marker extension was used when defining the type
1321 (Many of the builtin MIME types do so by default.)
1325 .Va mime-counter-evidence
1326 can be set to improve dealing with faulty MIME part declarations as are
1327 often seen in real-life messages.
1328 E.g., to display a HTML message inline (that is, converted to a more
1329 fancy plain text representation than the builtin converter is capable to
1330 produce) with either of the text-mode browsers
1334 teach \*(UA about MathML documents and make it display them as plain
1335 text, and to open PDF attachments in an external PDF viewer,
1336 asynchronously and with some other magic attached:
1338 .Bd -literal -offset indent
1339 if [ "$features" !@ +filter-html-tagsoup ]
1340 #set pipe-text/html='elinks -force-html -dump 1'
1341 set pipe-text/html='lynx -stdin -dump -force_html'
1342 # Display HTML as plain text instead
1343 #set pipe-text/html=@
1345 mimetype '@ application/mathml+xml mathml'
1346 wysh set pipe-application/pdf='@&=@ \e
1347 trap "rm -f \e"${MAILX_FILENAME_TEMPORARY}\e"" EXIT;\e
1348 trap "trap \e"\e" INT QUIT TERM; exit 1" INT QUIT TERM;\e
1349 mupdf "${MAILX_FILENAME_TEMPORARY}"'
1353 Note: special care must be taken when using such commands as mail
1354 viruses may be distributed by this method: if messages of type
1355 .Ql application/x-sh
1356 or files with the extension
1358 were blindly filtered through the shell, for example, a message sender
1359 could easily execute arbitrary code on the system \*(UA is running on.
1360 For more on MIME, also in respect to sending of messages, see the
1362 .Sx "The mime.types files" ,
1363 .Sx "The Mailcap files"
1368 .\" .Ss "Mailing lists" {{{
1371 \*(UA offers some support to ease handling of mailing lists.
1374 promotes all given arguments to known mailing lists, and
1376 sets their subscription attribute, creating them first as necessary.
1381 automatically, but only resets the subscription attribute.)
1382 Using the commands without arguments will show (a subset of) all
1383 currently defined mailing lists.
1388 can be used to mark out messages with configured list addresses
1389 in the header display.
1392 \*(OPally mailing lists may also be specified as (extended) regular
1393 expressions, which allows matching of many addresses with a single
1395 However, all fully qualified list addresses are matched via a fast
1396 dictionary, whereas expressions are placed in (a) list(s) which is
1397 (are) matched sequentially.
1399 .Bd -literal -offset indent
1400 set followup-to followup-to-honour=ask-yes reply-to-honour=ask-yes
1401 wysh mlist a1@b1.c1 a2@b2.c2 '.*@lists\e.c3$'
1402 mlsubscribe a4@b4.c4 exact@lists.c3
1407 .Va followup-to-honour
1409 .Ql Mail-\:Followup-\:To:
1410 header is honoured when the message is being replied to (via
1416 controls whether this header is created when sending mails; it will be
1417 created automatically for a couple of reasons, too, like when the
1419 .Dq mailing list specific
1424 is used to respond to a message with its
1425 .Ql Mail-Followup-To:
1429 A difference in between the handling of known and subscribed lists is
1430 that the address of the sender is usually not part of a generated
1431 .Ql Mail-Followup-To:
1432 when addressing the latter, whereas it is for the former kind of lists.
1433 Usually because there are exceptions: say, if multiple lists are
1434 addressed and not all of them are subscribed lists.
1436 For convenience \*(UA will, temporarily, automatically add a list
1437 address that is presented in the
1439 header of a message that is being responded to to the list of known
1441 Shall that header have existed \*(UA will instead, dependent on the
1443 .Va reply-to-honour ,
1446 for this purpose in order to accept a list administrators' wish that
1447 is supposed to have been manifested like that (but only if it provides
1448 a single address which resides on the same domain as what is stated in
1452 .\" .Ss "Resource files" {{{
1453 .Ss "Resource files"
1455 Upon startup \*(UA reads in several resource files:
1457 .Bl -tag -width ".It Pa BaNg"
1460 System wide initialization file.
1461 Reading of this file can be suppressed, either by using the
1463 (and according argument) or
1465 command line options, or by setting the
1468 .Ev MAILX_NO_SYSTEM_RC .
1472 File giving initial commands.
1473 A different file can be chosen by setting the
1477 Reading of this file can be suppressed with the
1479 command line option.
1481 .It Va mailx-extra-rc
1482 Can be used to define an optional startup file to be read after all
1483 other resource files.
1484 It can be used to specify settings that are not understood by other
1486 implementations, for example.
1487 This variable is only honoured when defined in a resource file, e.g.,
1489 .Sx "INTERNAL VARIABLES" .
1493 The content of these files is interpreted as follows:
1496 .Bl -bullet -compact
1498 A lines' leading whitespace is removed.
1500 Empty lines are ignored.
1502 Any other line is interpreted as a command.
1503 It may be spread over multiple input lines if the newline character is
1505 by placing a reverse solidus character
1507 as the last character of the line; whereas any leading whitespace of
1508 follow lines is ignored, trailing whitespace before a escaped newline
1509 remains in the input.
1511 If the line (content) starts with the number sign
1513 then it is a comment-command \(en a real command! \(en and also ignored.
1514 This command is the only form of comment that is understood.
1518 Unless \*(UA is about to enter interactive mode syntax errors that occur
1519 while loading these files are treated as errors and cause program exit.
1520 More files with syntactically equal content can be
1522 The following, saved in a file, would be an examplary content:
1524 .Bd -literal -offset indent
1525 # This line is a comment command. And y\e
1526 es, it is really continued here.
1533 .\" .Ss "Character sets" {{{
1534 .Ss "Character sets"
1536 \*(OP \*(UA detects the character set of the terminal by using
1537 mechanisms that are controlled by the
1542 should give an overview); the \*(UA internal variable
1544 will be set to the detected terminal character set accordingly
1545 and will thus show up in the output of the commands
1551 However, a user supplied
1553 value is not overwritten by this detection mechanism: this
1555 must be used if the detection does not work properly,
1556 and it may be used to adjust the name of the locale character set.
1557 E.g., on BSD systems one may use a locale with the character set
1558 ISO8859-1, which is not a valid name for this character set; to be on
1559 the safe side, one may set
1561 to the correct name, which is ISO-8859-1.
1564 Note that changing the value does not mean much beside that,
1565 since several aspects of the real character set are implied by the
1566 locale environment of the system,
1567 and that stays unaffected by the content of an overwritten
1570 (This is mostly an issue when interactively using \*(UA, though.
1571 It is actually possible to send mail in a completely
1573 locale environment, an option that \*(UA's test-suite uses excessively.)
1576 If no character set conversion capabilities have been compiled into
1579 does not include the term
1583 will be the only supported character set,
1584 it is simply assumed that it can be used to exchange 8-bit messages
1585 (over the wire an intermediate
1586 .Pf content-transfer-\: Va encoding
1588 and the rest of this section does not apply;
1589 it may however still be necessary to explicitly set it if automatic
1590 detection fails, since in that case it defaults to the mentioned
1591 .\" (Keep in SYNC: ./nail.1:"Character sets", ./nail.h:CHARSET_*!)
1595 When reading messages, their text is converted into
1597 as necessary in order to display them on the users terminal.
1598 Unprintable characters and invalid byte sequences are detected
1599 and replaced by proper substitution characters.
1600 Character set mappings for source character sets can be established with
1603 which may be handy to work around faulty character set catalogues (e.g.,
1604 to add a missing LATIN1 to ISO-8859-1 mapping), or to enforce treatment
1605 of one character set as another one (e.g., to interpret LATIN1 as CP1252).
1607 .Va charset-unknown-8bit
1608 to deal with another hairy aspect of message interpretation.
1611 When sending messages all their parts and attachments are classified.
1612 Whereas no character set conversion is performed on those parts which
1613 appear to be binary data,
1614 the character set being used must be declared within the MIME header of
1615 an outgoing text part if it contains characters that do not conform to
1616 the set of characters that are allowed by the email standards.
1617 Permissible values for character sets can be declared using the
1621 which defines a catch-all last-resort fallback character set that is
1622 implicitly appended to the list of character sets in
1626 When replying to a message and the variable
1627 .Va reply-in-same-charset
1628 is set then the character set of the message being replied to is tried
1629 first (after mapping via
1630 .Ic charsetalias ) .
1631 And it is also possible to make \*(UA work even more closely related to
1632 the current locale setting automatically by using the variable
1633 .Va sendcharsets-else-ttycharset ,
1634 please see there for more information.
1637 All the specified character sets are tried in order unless the
1638 conversion of the part or attachment succeeds.
1639 If none of the tried (8-bit) character sets is capable to represent the
1640 content of the part or attachment,
1641 then the message will not be sent and its text will optionally be
1645 In general, if the message
1646 .Dq Cannot convert from a to b
1647 appears, either some characters are not appropriate for the currently
1648 selected (terminal) character set,
1649 or the needed conversion is not supported by the system.
1650 In the first case, it is necessary to set an appropriate
1652 locale and/or the variable
1656 The best results are usually achieved when \*(UA is run in a UTF-8
1657 locale on a UTF-8 capable terminal, in which case the full Unicode
1658 spectrum of characters is available.
1659 In this setup characters from various countries can be displayed,
1660 while it is still possible to use more simple character sets for sending
1661 to retain maximum compatibility with older mail clients.
1664 On the other hand the POSIX standard defines a locale-independent 7-bit
1665 .Dq portable character set
1666 that should be used when overall portability is an issue, the even more
1667 restricted subset named
1668 .Dq portable filename character set
1669 consisting of A-Z, a-z, 0-9, period
1677 .\" .Ss "Message states" {{{
1678 .Ss "Message states"
1680 \*(UA differentiates in between several different message states;
1681 the current state will be reflected in header summary displays if
1683 is configured to do so (via the internal variable
1685 and messages can also be selected and be acted upon depending on their
1687 .Sx "Specifying messages" ) .
1688 When operating on the system
1692 .Sx "primary system mailbox" ,
1693 special actions, like the automatic moving of messages to the
1695 .Sx "secondary mailbox"
1697 may be applied when the mailbox is left (also implicitly via
1698 a successful exit of \*(UA, but not if the special command
1700 is used) \(en however, because this may be irritating to users which
1703 mail-user-agents, the default global
1709 variables in order to suppress this behaviour.
1711 .Bl -hang -width ".It Ql new"
1713 Message has neither been viewed nor moved to any other state.
1714 Such messages are retained even in the
1716 .Sx "primary system mailbox" .
1719 Message has neither been viewed nor moved to any other state, but the
1720 message was present already when the mailbox has been opened last:
1721 Such messages are retained even in the
1723 .Sx "primary system mailbox" .
1726 The message has been processed by one of the following commands:
1745 will always try to automatically
1751 logical message, and may thus mark multiple messages as read, the
1753 command will do so if the internal variable
1758 command is used, messages that are in a
1760 .Sx "primary system mailbox"
1763 state when the mailbox is left will be saved in the
1765 .Sx "secondary mailbox"
1767 unless the internal variable
1772 The message has been processed by one of the following commands:
1778 can be used to access such messages.
1781 The message has been processed by a
1783 command and it will be retained in its current location.
1786 The message has been processed by one of the following commands:
1792 command is used, messages that are in a
1794 .Sx "primary system mailbox"
1797 state when the mailbox is left will be deleted; they will be saved in the
1799 .Sx "secondary mailbox"
1801 when the internal variable
1807 In addition to these message states, flags which otherwise have no
1808 technical meaning in the mail system except allowing special ways of
1809 addressing them when
1810 .Sx "Specifying messages"
1811 can be set on messages.
1812 These flags are saved with messages and are thus persistent, and are
1813 portable between a set of widely used MUAs.
1815 .Bl -hang -width ".It Ic answered"
1817 Mark messages as having been answered.
1819 Mark messages as being a draft.
1821 Mark messages which need special attention.
1825 .\" .Ss "Specifying messages" {{{
1826 .Ss "Specifying messages"
1833 can be given a list of message numbers as arguments to apply to a number
1834 of messages at once.
1837 deletes messages 1 and 2,
1840 will delete the messages 1 through 5.
1841 In sorted or threaded mode (see the
1845 will delete the messages that are located between (and including)
1846 messages 1 through 5 in the sorted/threaded order, as shown in the
1849 The following special message names exist:
1852 .Bl -tag -width ".It Ar BaNg"
1854 The current message, the so-called
1858 The message that was previously the current message.
1861 The parent message of the current message,
1862 that is the message with the Message-ID given in the
1864 field or the last entry of the
1866 field of the current message.
1869 The next previous undeleted message,
1870 or the next previous deleted message for the
1873 In sorted/threaded mode,
1874 the next previous such message in the sorted/threaded order.
1877 The next undeleted message,
1878 or the next deleted message for the
1881 In sorted/threaded mode,
1882 the next such message in the sorted/threaded order.
1885 The first undeleted message,
1886 or the first deleted message for the
1889 In sorted/threaded mode,
1890 the first such message in the sorted/threaded order.
1894 In sorted/threaded mode,
1895 the last message in the sorted/threaded order.
1899 selects the message addressed with
1903 is any other message specification,
1904 and all messages from the thread that begins at it.
1905 Otherwise it is identical to
1910 the thread beginning with the current message is selected.
1915 All messages that were included in the
1916 .Sx "Message list arguments"
1917 of the previous command.
1920 An inclusive range of message numbers.
1921 Selectors that may also be used as endpoints include any of
1926 .Dq any substring matches
1929 header, which will match addresses (too) even if
1931 is set (and POSIX says
1932 .Dq any address as shown in a header summary shall be matchable in this form ) ;
1935 variable is set, only the local part of the address is evaluated
1936 for the comparison, not ignoring case, and the setting of
1938 is completely ignored.
1939 For finer control and match boundaries use the
1943 .It Ar / Ns Ar string
1944 All messages that contain
1946 in the subject field (case ignored).
1953 the string from the previous specification of that type is used again.
1955 .It Xo Op Ar @ Ns Ar name-list Ns
1958 All messages that contain the given case-insensitive search
1960 ession; if the \*(OPal regular expression (see
1962 support is available
1964 will be interpreted as (an extended) one if any of the
1966 (extended) regular expression characters is seen: in this case this
1967 should match strings correctly which are in the locale
1971 .Ar @ Ns Ar name-list
1972 part is missing, the search is restricted to the subject field body,
1975 specifies a comma-separated list of header fields to search, as in
1977 .Dl '@to,from,cc@Someone i ought to know'
1979 In order to search for a string that includes a
1981 (commercial at) character the
1983 is effectively non-optional, but may be given as the empty string.
1984 Some special header fields may be abbreviated:
1998 respectively and case-insensitively.
2003 can be used to search in (all of) the header(s) of the message, and the
2012 can be used to perform full text searches \(en whereas the former
2013 searches only the body, the latter also searches the message header.
2015 This message specification performs full text comparison, but even with
2016 regular expression support it is almost impossible to write a search
2017 expression that savely matches only a specific address domain.
2018 To request that the content of the header is treated as a list of
2019 addresses, and to strip those down to the plain email address which the
2020 search expression is to be matched against, prefix the header name
2021 (abbreviation) with a tilde
2024 .Dl @~f@@a\e.safe\e.domain\e.match$
2027 All messages of state
2031 is one or multiple of the following colon modifiers:
2033 .Bl -tag -compact -width ".It Ar :M"
2038 Old messages (any not in state
2060 messages (cf. the variable
2061 .Va markanswered ) .
2066 \*(OP Messages classified as spam (see
2067 .Sx "Handling spam" . )
2069 \*(OP Messages with unsure spam classification.
2075 \*(OP IMAP-style SEARCH expressions may also be used.
2076 This addressing mode is available with all types of folders;
2077 \*(UA will perform the search locally as necessary.
2078 Strings must be enclosed by double quotes
2080 in their entirety if they contain white space or parentheses;
2081 within the quotes, only reverse solidus
2083 is recognized as an escape character.
2084 All string searches are case-insensitive.
2085 When the description indicates that the
2087 representation of an address field is used,
2088 this means that the search string is checked against both a list
2091 .Bd -literal -offset indent
2092 (\*qname\*q \*qsource\*q \*qlocal-part\*q \*qdomain-part\*q)
2097 and the addresses without real names from the respective header field.
2098 These search expressions can be nested using parentheses, see below for
2102 .Bl -tag -compact -width ".It Ar _n_u"
2103 .It Ar ( criterion )
2104 All messages that satisfy the given
2106 .It Ar ( criterion1 criterion2 ... criterionN )
2107 All messages that satisfy all of the given criteria.
2109 .It Ar ( or criterion1 criterion2 )
2110 All messages that satisfy either
2115 To connect more than two criteria using
2117 specifications have to be nested using additional parentheses,
2119 .Ql (or a (or b c)) ,
2123 .Ql ((a or b) and c) .
2126 operation of independent criteria on the lowest nesting level,
2127 it is possible to achieve similar effects by using three separate
2131 .It Ar ( not criterion )
2132 All messages that do not satisfy
2134 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
2135 All messages that contain
2137 in the envelope representation of the
2140 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
2141 All messages that contain
2143 in the envelope representation of the
2146 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
2147 All messages that contain
2149 in the envelope representation of the
2152 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
2153 All messages that contain
2158 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
2159 All messages that contain
2161 in the envelope representation of the
2164 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
2165 All messages that contain
2170 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
2171 All messages that contain
2174 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
2175 All messages that contain
2177 in their header or body.
2178 .It Ar ( larger size )
2179 All messages that are larger than
2182 .It Ar ( smaller size )
2183 All messages that are smaller than
2187 .It Ar ( before date )
2188 All messages that were received before
2190 which must be in the form
2194 denotes the day of the month as one or two digits,
2196 is the name of the month \(en one of
2197 .Ql Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ,
2200 is the year as four digits, e.g.,
2204 All messages that were received on the specified date.
2205 .It Ar ( since date )
2206 All messages that were received since the specified date.
2207 .It Ar ( sentbefore date )
2208 All messages that were sent on the specified date.
2209 .It Ar ( senton date )
2210 All messages that were sent on the specified date.
2211 .It Ar ( sentsince date )
2212 All messages that were sent since the specified date.
2214 The same criterion as for the previous search.
2215 This specification cannot be used as part of another criterion.
2216 If the previous command line contained more than one independent
2217 criterion then the last of those criteria is used.
2221 .\" .Ss "On URL syntax and credential lookup" {{{
2222 .Ss "On URL syntax and credential lookup"
2224 \*(IN For accessing protocol-specific resources usage of Uniform
2225 Resource Locators (URL, RFC 1738) has become omnipresent.
2226 \*(UA expects and understands URLs in the following form;
2229 denote optional parts, optional either because there also exist other
2230 ways to define the information in question or because support of the
2231 part is protocol-specific (e.g.,
2233 is used by the IMAP protocol but not by POP3);
2238 are specified they must be given in URL percent encoded form (RFC 3986;
2244 .Dl PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
2247 Note that these \*(UA URLs most often do not conform to any real
2248 standard, but instead represent a normalized variant of RFC 1738 \(en
2249 they are not used in data exchange but only meant as a compact,
2250 easy-to-use way of defining and representing information in
2251 a well-known notation.
2254 Many internal variables of \*(UA exist in multiple versions, called
2255 variable chains for the rest of this document: the plain
2260 .Ql variable-USER@HOST .
2267 had been specified in the respective URL, otherwise it refers to the plain
2273 that had been found when doing the user chain lookup as is described
2276 will never be in URL percent encoded form, whether it came from an URL
2277 or not; i.e., variable chain name extensions of
2278 .Sx "INTERNAL VARIABLES"
2279 must not be URL percent encoded.
2282 For example, whether an hypothetical URL
2283 .Ql smtp://hey%3Ayou@our.house
2284 had been given that includes a user, or whether the URL was
2285 .Ql smtp://our.house
2286 and the user had been found differently, to lookup the variable chain
2287 .Va smtp-use-starttls
2288 \*(UA first looks for whether
2289 .Ql smtp-\:use-\:starttls-\:hey:you@our.house
2290 is defined, then whether
2291 .Ql smtp-\:use-\:starttls-\:our.house
2292 exists before finally ending up looking at the plain variable itself.
2295 \*(UA obeys the following logic scheme when dealing with the
2296 necessary credential information of an account:
2302 has been given in the URL the variables
2306 are looked up; if no such variable(s) can be found then \*(UA will,
2307 when enforced by the \*(OPal variables
2308 .Va netrc-lookup-HOST
2315 specific entry which provides a
2317 name: this lookup will only succeed if unambiguous (one possible matching
2320 It is possible to load encrypted
2325 If there is still no
2327 then \*(UA will fall back to the user who is supposed to run \*(UA,
2328 the identity of which has been fixated during \*(UA startup and is
2329 known to be a valid user on the current host.
2332 Authentication: unless otherwise noted this will lookup the
2333 .Va PROTOCOL-auth-USER@HOST , PROTOCOL-auth-HOST , PROTOCOL-auth
2334 variable chain, falling back to a protocol-specific default should this
2340 has been given in the URL, then if the
2342 has been found through the \*(OPal
2344 that may have already provided the password, too.
2345 Otherwise the variable chain
2346 .Va password-USER@HOST , password-HOST , password
2347 is looked up and used if existent.
2349 Afterwards the complete \*(OPal variable chain
2350 .Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
2354 cache is searched for a password only (multiple user accounts for
2355 a single machine may exist as well as a fallback entry without user
2356 but with a password).
2358 If at that point there is still no password available, but the
2359 (protocols') chosen authentication type requires a password, then in
2360 interactive mode the user will be prompted on the terminal.
2365 S/MIME verification works relative to the values found in the
2369 header field(s), which means that the values of
2370 .Va smime-sign , smime-sign-cert , smime-sign-include-certs
2372 .Va smime-sign-message-digest
2373 will not be looked up using the
2377 chains from above but instead use the corresponding values from the
2378 message that is being worked on.
2379 In unusual cases multiple and different
2383 combinations may therefore be involved \(en on the other hand those
2384 unusual cases become possible.
2385 The usual case is as short as:
2388 .Dl set mta=smtp://USER:PASS@HOST smtp-use-starttls \e
2389 .Dl \ \ \ \ smime-sign smime-sign-cert=+smime.pair
2394 contains complete example configurations.
2397 .\" .Ss "On terminal control and line editor" {{{
2398 .Ss "On terminal control and line editor"
2400 \*(OP Terminal control will be realized through one of the standard
2402 libraries, either the
2404 or, alternatively, the
2406 both of which will be initialized to work with the environment variable
2408 Terminal control will enhance or enable interactive usage aspects, e.g.,
2409 .Sx "Coloured display" ,
2410 and extend behaviour of the Mailx-Line-Editor (MLE), which may learn the
2411 byte-sequences of keys like the cursor and function keys, and which will
2412 automatically enter the so-called
2414 alternative screen shall the terminal support it.
2415 The internal variable
2417 can be used to overwrite settings or to learn (correct(ed)) keycodes.
2418 Actual interaction with the chosen library can be disabled completely by
2419 setting the internal variable
2420 .Va termcap-disable ;
2422 will be queried regardless, even if the \*(OPal support for the
2423 libraries has not been enabled at configuration time.
2426 \*(OP The builtin \*(UA Mailx-Line-Editor (MLE) should work in all
2427 environments which comply to the ISO C standard
2429 and will support wide glyphs if possible (the necessary functionality
2430 had been removed from ISO C, but was included in
2432 Prevent usage of a line editor in interactive mode by setting the
2434 .Va line-editor-disable .
2435 Especially if the \*(OPal terminal control support is missing setting
2436 entries in the internal variable
2438 will help shall the MLE misbehave, see there for more.
2439 The MLE can support a little bit of
2445 feature is available then input from line editor prompts will be saved
2446 in a history list that can be searched in and be expanded from.
2447 Such saving can be prevented by prefixing input with any amount of
2449 Aspects of history, like allowed content and maximum size, as well as
2450 whether history shall be saved persistently, can be configured with the
2454 .Va history-gabby-persist
2459 The MLE supports a set of editing and control commands.
2460 By default (as) many (as possible) of these will be assigned to a set of
2461 single-letter control codes, which should work on any terminal (and can
2462 be generated by holding the
2464 key while pressing the key of desire, e.g.,
2468 command is available then the MLE commands can also be accessed freely
2469 by assigning the command name, which is shown in parenthesis in the list
2470 below, to any desired key-sequence, and the MLE will instead and also use
2472 to establish its builtin key bindings
2473 (more of them if the \*(OPal terminal control is available),
2474 an action which can then be suppressed completely by setting
2475 .Va line-editor-no-defaults .
2476 .Sx "Shell-style argument quoting"
2477 notation is used in the following;
2478 combinations not mentioned either cause job control signals or do not
2479 generate a (unique) keycode:
2483 .Bl -tag -compact -width ".It Ql Ba"
2485 Go to the start of the line
2487 .Pf ( Cd mle-go-home ) .
2490 Move the cursor backward one character
2492 .Pf ( Cd mle-go-bwd ) .
2495 Forward delete the character under the cursor;
2496 quits \*(UA if used on the empty line unless the internal variable
2500 .Pf ( Cd mle-del-fwd ) .
2503 Go to the end of the line
2505 .Pf ( Cd mle-go-end ) .
2508 Move the cursor forward one character
2510 .Pf ( Cd mle-go-fwd ) .
2513 Cancel current operation, full reset.
2514 If there is an active history search or tabulator expansion then this
2515 command will first reset that, reverting to the former line content;
2516 thus a second reset is needed for a full reset in this case
2518 .Pf ( Cd mle-reset ) .
2521 Backspace: backward delete one character
2523 .Pf ( Cd mle-del-bwd ) .
2527 Horizontal tabulator:
2528 try to expand the word before the cursor, supporting the usual
2529 .Sx "Filename transformations"
2531 .Pf ( Cd mle-complete ) .
2533 .Cd mle-quote-rndtrip .
2537 commit the current line
2539 .Pf ( Cd mle-commit ) .
2542 Cut all characters from the cursor to the end of the line
2544 .Pf ( Cd mle-snarf-end ) .
2549 .Pf ( Cd mle-repaint ) .
2552 \*(OP Go to the next history entry
2554 .Pf ( Cd mle-hist-fwd ) .
2557 (\*(OPally context-dependent) Invokes the command
2561 \*(OP Go to the previous history entry
2563 .Pf ( Cd mle-hist-bwd ) .
2566 Toggle roundtrip mode shell quotes, where produced,
2569 .Pf ( Cd mle-quote-rndtrip ) .
2570 This setting is temporary, and will be forgotten once the command line
2571 is committed; also see
2575 \*(OP Complete the current line from (the remaining) older history entries
2577 .Pf ( Cd mle-hist-srch-bwd ) .
2580 \*(OP Complete the current line from (the remaining) newer history entries
2582 .Pf ( Cd mle-hist-srch-fwd ) .
2585 Paste the snarf buffer
2587 .Pf ( Cd mle-paste ) .
2595 .Pf ( Cd mle-snarf-line ) .
2598 Prompts for a Unicode character (its hexadecimal number) to be inserted
2600 .Pf ( Cd mle-prompt-char ) .
2601 Note this command needs to be assigned to a single-letter control code
2602 in order to become recognized and executed during input of
2603 a key-sequence (only three single-letter control codes can be used for
2604 that shortcut purpose); this control code is special-treated and cannot
2605 be part of any other sequence, because any occurrence will perform the
2607 function immediately.
2610 Cut the characters from the one preceding the cursor to the preceding
2613 .Pf ( Cd mle-snarf-word-bwd ) .
2616 Move the cursor forward one word boundary
2618 .Pf ( Cd mle-go-word-fwd ) .
2621 Move the cursor backward one word boundary
2623 .Pf ( Cd mle-go-word-bwd ) .
2626 Escape: reset a possibly used multibyte character input state machine
2627 and \*(OPally a lingering, incomplete key binding
2629 .Pf ( Cd mle-cancel ) .
2630 This command needs to be assigned to a single-letter control code in
2631 order to become recognized and executed during input of a key-sequence
2632 (only three single-letter control codes can be used for that shortcut
2634 This control code may also be part of a multi-byte sequence, but if
2635 a sequence is active and the very control code is currently also an
2636 expected input, then it will first be consumed by the active sequence.
2639 (\*(OPally context-dependent) Invokes the command
2643 (\*(OPally context-dependent) Invokes the command
2647 (\*(OPally context-dependent) Invokes the command
2651 Cut the characters from the one after the cursor to the succeeding word
2654 .Pf ( Cd mle-snarf-word-fwd ) .
2665 this will immediately reset a possibly active search etc.
2670 ring the audible bell.
2674 .\" .Ss "Coloured display" {{{
2675 .Ss "Coloured display"
2677 \*(OP \*(UA can be configured to support a coloured display and font
2678 attributes by emitting ANSI / ISO 6429 SGR (select graphic rendition)
2680 Usage of colours and font attributes solely depends upon the
2681 capability of the detected terminal type that is defined by the
2682 environment variable
2684 and which can be fine-tuned by the user via the internal variable
2688 On top of what \*(UA knows about the terminal the boolean variable
2690 defines whether the actually applicable colour and font attribute
2691 sequences should also be generated when output is going to be paged
2692 through the external program defined by the environment variable
2697 This is not enabled by default because different pager programs need
2698 different command line switches or other configuration in order to
2699 support those sequences.
2700 \*(UA however knows about some widely used pagers and in a clean
2701 environment it is often enough to simply set
2703 please refer to that variable for more on this topic.
2708 is set then any active usage of colour and font attribute sequences
2709 is suppressed, but without affecting possibly established
2714 To define and control colours and font attributes a single multiplexer
2715 command family exists:
2717 shows or defines colour mappings for the given colour type (e.g.,
2720 can be used to remove mappings of a given colour type.
2721 Since colours are only available in interactive mode, it may make
2722 sense to conditionalize the colour setup by encapsulating it with
2725 .Bd -literal -offset indent
2726 if terminal && $features =@ +colour
2727 colour iso view-msginfo ft=bold,fg=green
2728 colour iso view-header ft=bold,fg=red "from,subject"
2729 colour iso view-header fg=red
2731 uncolour iso view-header from,subject
2732 colour iso view-header ft=bold,fg=magenta,bg=cyan
2733 colour 256 view-header ft=bold,fg=208,bg=230 subject,from
2734 colour mono view-header ft=bold
2735 colour mono view-header ft=bold,ft=reverse subject,from
2739 .\" }}} (DESCRIPTION)
2742 .\" .Sh COMMANDS {{{
2745 Each command is typed on a line by itself,
2746 and may take arguments following the command word.
2747 An unquoted reverse solidus
2749 at the end of a command line
2751 the newline character: it is discarded and the next line of input is
2752 used as a follow-up line, with all leading whitespace removed;
2753 once the entire command line is completed, the processing that is
2754 documented in the following begins.
2757 Command names may be abbreviated, in which case the first command that
2758 matches the given prefix will be used.
2761 can be used to show the list of all commands, either alphabetically
2762 sorted or in prefix search order (these do not match, also because the
2763 POSIX standard prescribes a set of abbreviations).
2764 \*(OPally the command
2768 when given an argument, will show a documentation string for the
2769 command matching the expanded argument, as in
2771 which should be a shorthand of
2773 with these documentation strings both commands support a more
2775 listing mode which includes the argument type of the command and other
2776 information which applies; a handy suggestion might thus be:
2778 .Bd -literal -offset indent
2780 # Be careful to choose sh(1)ell-style on _entire_ line!
2781 localopts 1;wysh set verbose;ignerr eval "${@}";return ${?}
2783 ? commandalias xv '\ecall __xv'
2787 .\" .Ss "Command modifiers" {{{
2788 .Ss "Command modifiers"
2790 Commands may be prefixed by one or multiple command modifiers.
2794 The modifier reverse solidus
2797 to be placed first, prevents
2799 expansions on the remains of the line, e.g.,
2801 will always evaluate the command
2803 even if an (command)alias of the same name exists.
2805 content may itself contain further command modifiers, including
2806 an initial reverse solidus to prevent further expansions.
2812 indicates that any error generated by the following command should be
2813 ignored by the state machine and not cause a program exit with enabled
2815 or for the standardized exit cases in
2820 .Sx "INTERNAL VARIABLES" ,
2821 will be set to the real exit status of the command regardless.
2824 Some commands support the
2827 modifier: if used, they expect the name of a variable, which can itself
2828 be a variable, i.e., shell expansion is applied, as their first
2829 argument, and will place their computation result in it instead of the
2830 default location (it is usually written to standard output).
2831 The given name will be tested for being a valid
2833 variable name, and may therefore only consist of upper- and lowercase
2834 characters, digits, and the underscore; the hyphen-minus may be used as
2835 a non-portable extension; digits may not be used as first, hyphen-minus
2836 may not be used as last characters.
2837 In addition the name may either not be one of the known
2838 .Sx "INTERNAL VARIABLES" ,
2839 or must otherwise refer to a writable (non-boolean) value variable.
2840 The actual put operation may fail nonetheless, e.g., if the variable
2841 expects a number argument only a number will be accepted.
2842 Any error during these operations causes the command as such to fail,
2843 and the error number
2846 .Va ^ERR Ns -NOTSUP .
2849 Last, but not least, the modifier
2852 can be used for some old and established commands to choose the new
2853 .Sx "Shell-style argument quoting"
2854 rules over the traditional
2855 .Sx "Old-style argument quoting" .
2859 .\" .Ss "Message list arguments" {{{
2860 .Ss "Message list arguments"
2862 Some commands expect arguments that represent messages (actually
2863 their symbolic message numbers), as has been documented above under
2864 .Sx "Specifying messages"
2866 If no explicit message list has been specified, the next message
2867 forward that satisfies the command's requirements will be used,
2868 and if there are no messages forward of the current message,
2869 the search proceeds backwards;
2870 if there are no good messages at all to be found, an error message is
2871 shown and the command is aborted.
2874 .\" .Ss "Old-style argument quoting" {{{
2875 .Ss "Old-style argument quoting"
2877 \*(ID This section documents the old, traditional style of quoting
2878 non-message-list arguments to commands which expect this type of
2879 arguments: whereas still used by the majority of such commands, the new
2880 .Sx "Shell-style argument quoting"
2881 may be available even for those via
2884 .Sx "Command modifiers" .
2885 Nonetheless care must be taken, because only new commands have been
2886 designed with all the capabilities of the new quoting rules in mind,
2887 which can, e.g., generate control characters.
2890 .Bl -bullet -offset indent
2892 An argument can be enclosed between paired double-quotes
2897 any white space, shell word expansion, or reverse solidus characters
2898 (except as described next) within the quotes are treated literally as
2899 part of the argument.
2900 A double-quote will be treated literally within single-quotes and vice
2902 Inside such a quoted string the actually used quote character can be
2903 used nonetheless by escaping it with a reverse solidus
2909 An argument that is not enclosed in quotes, as above, can usually still
2910 contain space characters if those spaces are reverse solidus escaped, as in
2914 A reverse solidus outside of the enclosing quotes is discarded
2915 and the following character is treated literally as part of the argument.
2919 .\" .Ss "Shell-style argument quoting" {{{
2920 .Ss "Shell-style argument quoting"
2922 Commands which don't expect message-list arguments use
2924 ell-style, and therefore POSIX standardized, argument parsing and
2926 \*(ID Most new commands only support these new rules and are flagged
2927 \*(NQ, some elder ones can use them with the command modifier
2929 in the future only this type of argument quoting will remain.
2932 A command line is parsed from left to right and an input token is
2933 completed whenever an unquoted, otherwise ignored, metacharacter is seen.
2934 Metacharacters are vertical bar
2941 .Cm space , tabulator , newline .
2942 The additional metacharacters left and right parenthesis
2944 and less-than and greater-than signs
2948 supports are not used, and are treated as ordinary characters: for one
2949 these characters are a vivid part of email addresses, and it also seems
2950 highly unlikely that their function will become meaningful to \*(UA.
2953 Any unquoted number sign
2955 at the beginning of a new token starts a comment that extends to the end
2956 of the line, and therefore ends argument processing.
2957 An unquoted dollar sign
2959 will cause variable expansion of the given name, which must be a valid
2961 ell-style variable name (see
2963 .Sx "INTERNAL VARIABLES"
2966 (shell) variables can be accessed through this mechanism, brace
2967 enclosing the name is supported (i.e., to subdivide a token).
2970 Whereas the metacharacters
2971 .Cm space , tabulator , newline
2972 only complete an input token, vertical bar
2978 also act as control operators and perform control functions.
2979 For now supported is semicolon
2981 which terminates a single command, therefore sequencing the command line
2982 and making the remainder of the line a subject to reevaluation.
2983 With sequencing, multiple command argument types and quoting rules may
2984 therefore apply to a single line, which can become problematic before
2985 v15: e.g., the first of the following will cause surprising results.
2988 .Dl ? echo one; set verbose; echo verbose=$verbose.
2989 .Dl ? echo one; wysh set verbose; echo verbose=$verbose.
2992 Quoting is a mechanism that will remove the special meaning of
2993 metacharacters and reserved words, and will prevent expansion.
2994 There are four quoting mechanisms: the escape character, single-quotes,
2995 double-quotes and dollar-single-quotes:
2998 .Bl -bullet -offset indent
3000 The literal value of any character can be preserved by preceding it
3001 with the escape character reverse solidus
3005 Arguments which are enclosed in
3006 .Ql 'single-\:quotes'
3007 retain their literal value.
3008 A single-quote cannot occur within single-quotes.
3011 The literal value of all characters enclosed in
3012 .Ql \(dqdouble-\:quotes\(dq
3013 is retained, with the exception of dollar sign
3015 which will cause variable expansion, as above, backquote (grave accent)
3017 (which not yet means anything special), reverse solidus
3019 which will escape any of the characters dollar sign
3021 (to prevent variable expansion), backquote (grave accent)
3025 (to prevent ending the quote) and reverse solidus
3027 (to prevent escaping, i.e., to embed a reverse solidus character as-is),
3028 but has no special meaning otherwise.
3031 Arguments enclosed in
3032 .Ql $'dollar-\:single-\:quotes'
3033 extend normal single quotes in that reverse solidus escape sequences are
3034 expanded as follows:
3036 .Bl -tag -compact -width "Ql \eNNN"
3042 an escape character.
3044 an escape character.
3056 emits a reverse solidus character.
3060 double quote (escaping is optional).
3062 eight-bit byte with the octal value
3064 (one to three octal digits), optionally prefixed by an additional
3066 A 0 byte will suppress further output for the quoted argument.
3068 eight-bit byte with the hexadecimal value
3070 (one or two hexadecimal characters).
3071 A 0 byte will suppress further output for the quoted argument.
3073 the Unicode / ISO-10646 character with the hexadecimal codepoint value
3075 (one to eight hexadecimal digits) \(em note that Unicode defines the
3076 maximum codepoint ever to be supported as
3081 This escape is only supported in locales which support Unicode (see
3082 .Sx "Character sets" ) ,
3083 in other cases the sequence will remain unexpanded unless the given code
3084 point is ASCII compatible or can be represented in the current locale.
3085 The character NUL will suppress further output for the quoted argument.
3089 except it takes only one to four hexadecimal digits.
3091 Emits the non-printable (ASCII and compatible) C0 control codes
3092 0 (NUL) to 31 (US), and 127 (DEL).
3093 Printable representations of ASCII control codes can be created by
3094 mapping them to a different part of the ASCII character set, which is
3095 possible by adding the number 64 for the codes 0 to 31, e.g., 7 (BEL) is
3096 .Ql 7 + 64 = 71 = G .
3097 The real operation is a bitwise logical XOR with 64 (bit 7 set, see
3099 thus also covering code 127 (DEL), which is mapped to 63 (question mark):
3100 .Ql ? vexpr ^ 127 64 .
3102 Whereas historically circumflex notation has often been used for
3103 visualization purposes of control codes, e.g.,
3105 the reverse solidus notation has been standardized:
3107 Some control codes also have standardized (ISO 10646, ISO C) aliases,
3108 as shown above (e.g.,
3112 whenever such an alias exists it will be used for display purposes.
3113 The control code NUL
3115 a non-standard extension) ends argument processing without producing
3118 Non-standard extension: expand the given variable name, as above.
3119 Brace enclosing the name is supported.
3121 Not yet supported, just to raise awareness: Non-standard extension.
3128 .Bd -literal -offset indent
3129 echo 'Quotes '${HOME}' and 'tokens" differ!"# no comment
3130 echo Quotes ${HOME} and tokens differ! # comment
3131 echo Don"'"t you worry$'\ex21' The sun shines on us. $'\eu263A'
3135 .\" .Ss "Raw data arguments for codec commands" {{{
3136 .Ss "Raw data arguments for codec commands"
3138 A special set of commands, which all have the string
3140 in their name, e.g.,
3144 take raw string data as input, which means that the content of the
3145 command input line is passed completely unexpanded and otherwise
3146 unchanged: like this the effect of the actual codec is visible without
3147 any noise of possible shell quoting rules etc., i.e., the user can input
3148 one-to-one the desired or questionable data.
3149 To gain a level of expansion, the entire command line can be
3153 .Bd -literal -offset indent
3154 ? vput shcodec res encode /usr/Sch\[:o]nes Wetter/heute.txt
3156 $'/usr/Sch\eu00F6nes Wetter/heute.txt'
3158 $'/usr/Sch\eu00F6nes Wetter/heute.txt'
3159 ? eval shcodec d $res
3160 /usr/Sch\[:o]nes Wetter/heute.txt
3164 .\" .Ss "Filename transformations" {{{
3165 .Ss "Filename transformations"
3167 Filenames, where expected, and unless documented otherwise, are
3168 subsequently subject to the following filename transformations, in
3171 .Bl -bullet -offset indent
3173 If the given name is a registered
3175 it will be replaced with the expanded shortcut.
3178 The filename is matched against the following patterns or strings:
3180 .Bl -hang -compact -width ".Ar %user"
3182 (Number sign) is expanded to the previous file.
3184 (Percent sign) is replaced by the invoking
3185 .Mx -ix "primary system mailbox"
3186 user's primary system mailbox, which either is the (itself expandable)
3188 if that is set, the standardized absolute pathname indicated by
3190 if that is set, or a builtin compile-time default otherwise.
3192 Expands to the primary system mailbox of
3194 (and never the value of
3196 regardless of its actual setting).
3198 (Ampersand) is replaced with the invoking users
3199 .Mx -ix "secondary mailbox"
3200 secondary mailbox, the
3207 directory (if that variable is set).
3209 Expands to the same value as
3211 but has special meaning when used with, e.g., the command
3213 the file will be treated as a primary system mailbox by, e.g., the
3217 commands, meaning that messages that have been read in the current
3218 session will be moved to the
3220 mailbox instead of simply being flagged as read.
3224 Meta expansions are applied to the resulting filename, as applicable to
3225 the resulting file access protocol (also see
3226 .Sx "On URL syntax and credential lookup" ) .
3227 If the fully expanded filename results in multiple pathnames and the
3228 command is expecting only one file, an error results.
3230 For the file-protocol, a leading tilde
3232 character will be replaced by the expansion of
3234 except when followed by a valid user name, in which case the home
3235 directory of the given user is used instead.
3241 will be replaced by the expansion of the variable, if possible;
3242 .Sx "INTERNAL VARIABLES"
3245 (shell) variables can be accessed through this mechanism, and the usual
3246 escape mechanism has to be applied to prevent interpretation.
3248 In interactive context, in order to allow simple value acceptance (via
3250 arguments will usually be displayed in a properly quoted form, e.g., a file
3251 .Ql diet\e is \ecurd.txt
3253 .Ql 'diet\e is \ecurd.txt' .
3257 .\" .Ss "Commands" {{{
3260 The following commands are available:
3262 .Bl -tag -width ".It Ic BaNg"
3267 command which follows, replacing unescaped exclamation marks with the
3268 previously executed command if the internal variable
3274 The comment-command causes the entire line to be ignored.
3276 this really is a normal command which' purpose is to discard its
3279 indicating special character, which means that, e.g., trailing comments
3280 on a line are not possible.
3284 Goes to the next message in sequence and types it
3290 Display the preceding message, or the n'th previous message if given
3291 a numeric argument n.
3295 Show the current message number (the
3300 Show a brief summary of commands.
3301 \*(OP Given an argument a synopsis for the command in question is
3302 shown instead; commands can be abbreviated in general and this command
3303 can be used to see the full expansion of an abbreviation including the
3304 synopsis, try, e.g.,
3309 and see how the output changes.
3310 This mode also supports a more
3312 output, which will provide the informations documented for
3323 \*(NQ Interprets the remainder of the word as a macro name and passes
3328 is a shorter synonym for
3329 .Ql call Ar mymacro .
3333 .It Ic account , unaccount
3334 (ac, una) Creates, selects or lists (an) account(s).
3335 Accounts are special incarnations of
3337 macros and group commands and variable settings which together usually
3338 arrange the environment for the purpose of creating an email account.
3339 Different to normal macros settings which are covered by
3341 \(en here by default enabled! \(en will not be reverted before the
3346 (case-insensitive) always exists, and all but it can be deleted by the
3347 latter command, and in one operation with the special name
3350 Without arguments a listing of all defined accounts is shown.
3351 With one argument the given account is activated: the system
3353 of that account will be activated (as via
3355 a possibly installed
3357 will be run, and the internal variable
3360 The two argument form is identical to defining a macro as via
3362 .Bd -literal -offset indent
3364 set folder=~/mail inbox=+syste.mbox record=+sent.mbox
3365 set from='(My Name) myname@myisp.example'
3366 set mta=smtp://mylogin@smtp.myisp.example
3372 Perform email address codec transformations on raw-data argument, rather
3373 according to email standards (RFC 5322; \*(ID will furtherly improve).
3377 .Sx "Command modifiers" ) ,
3378 and manages the error number
3380 The first argument must be either
3384 and specifies the operation to perform on the rest of the line.
3385 Decoding will show how a standard-compliant MUA will display the given
3386 argument, which should be a prepared address.
3387 Please be aware that most MUAs have difficulties with the address
3388 standards, and vary wildly when (comments) in parenthesis,
3390 strings, or quoted-pairs, as below, become involved.
3391 \*(ID \*(UA currently does not perform decoding when displaying addresses.
3393 Encoding supports three different modes, lesser automated versions can be
3394 chosen by prefixing one or two plus signs: the standard imposes
3395 a special meaning on some characters, which thus have to be transformed
3396 to so-called quoted-pairs by pairing them with a reverse solidus
3398 in order to remove the special meaning; this might change interpretation
3399 of the entire argument from what has been desired, however!
3400 Specify one plus sign to remark that double quotation marks are not be
3401 turned into quoted-pairs, and two for also leaving any user-specified
3402 reverse solidus alone.
3403 The result will always be valid, if a successful exit status is reported.
3404 \*(ID Addresses need to be specified in between angle brackets
3407 if the construct becomes more difficult, otherwise the current parser
3408 will fail; it is not smart enough to guess right.
3409 .Bd -literal -offset indent
3410 ? addrc enc "Hey, you",<diet@exam.ple>\e out\e there
3411 "\e"Hey, you\e", \e\e out\e\e there" <diet@exam.ple>
3412 ? addrc d "\e"Hey, you\e", \e\e out\e\e there" <diet@exam.ple>
3413 "Hey, you", \e out\e there <diet@exam.ple>
3418 .It Ic alias , unalias
3419 (a, una) Aliases are a method of creating personal distribution lists
3420 that map a single alias name to none to multiple real receivers;
3421 these aliases become expanded after message composing is completed.
3422 The latter command removes the given list of aliases, the special name
3424 will discard all existing aliases.
3425 The former command shows all currently defined aliases when used without
3426 arguments, and with one argument the expansion of the given alias.
3427 With more than one argument, creates or appends to the alias name given
3428 as the first argument the remaining arguments.
3429 Alias names are restricted to alphabetic characters, digits, the
3430 underscore, hyphen-minus, the number sign, colon, commercial at and
3431 period, the last character can also be the dollar sign:
3432 .Ql [[:alnum:]_#:@.-]+$? .
3436 (alt) Manage a list of alternate addresses or names of the active user,
3437 members of which will be removed from recipient lists when replying to
3440 variable is not set).
3441 Without arguments the current set of alternates is displayed, otherwise
3442 the set of alternate names is replaced by the given arguments, and the
3445 is updated accordingly.
3449 .It Ic answered , unanswered
3450 Take a message lists and mark each message as having been answered,
3451 having not been answered, respectively.
3452 Messages will be marked answered when being
3454 to automatically if the
3458 .Sx "Message states" .
3463 .It Ic bind , unbind
3464 \*(OP\*(NQ The bind command extends the MLE (see
3465 .Sx "On terminal control and line editor" )
3466 with freely configurable key bindings.
3467 The latter command removes from the given context the given key binding,
3468 both of which may be specified as a wildcard
3472 will remove all bindings of all contexts.
3473 With one argument the former command shows all key bindings for the
3474 given context, specifying an asterisk
3476 will show the bindings of all contexts; a more verbose listing will be
3477 produced if either of
3482 With two or more arguments a binding is (re)established:
3483 the first argument is the context to which the binding shall apply,
3484 the second argument is a comma-separated list of the
3486 which form the binding, and any remaining arguments form the expansion.
3487 To indicate that a binding shall not be auto-committed, but that the
3488 expansion shall instead be furtherly editable by the user, a commercial at
3490 (that will be removed) can be placed last in the expansion, from which
3491 leading and trailing whitespace will finally be removed.
3492 Reverse solidus cannot be used as the last character of expansion.
3495 Contexts define when a binding applies, i.e., a binding will not be seen
3496 unless the context for which it is defined for is currently active.
3497 This is not true for the shared binding
3499 which is the foundation for all other bindings and as such always
3500 applies, its bindings, however, only apply secondarily.
3501 The available contexts are the shared
3505 context which is used in all not otherwise documented situations, and
3507 which applies to compose mode only.
3511 which form the binding are specified as a comma-separated list of
3512 byte-sequences, where each list entry corresponds to one key(press).
3513 \*(OPally a list entry may, indicated by a leading colon character
3515 also refer to the name of a terminal capability;
3516 several dozen names will be compiled into \*(UA and may be specified
3519 or, if existing, by their
3521 name, regardless of the actually used terminal control library.
3522 It is however possible to use any capability, as long as the name is
3523 resolvable by the control library or defined in the internal variable
3525 Input sequences are not case-normalized, so that an exact match is
3526 required to update or remove a binding.
3529 .Bd -literal -offset indent
3530 bind base $'\eE',d mle-snarf-word-fwd # Esc(ape)
3531 bind base $'\eE',$'\ec?' mle-snarf-word-bwd # Esc, Delete
3532 bind default $'\ecA',:khome,w 'echo An editable binding@'
3533 bind default a,b,c rm -rf / @ # Another editable binding
3534 bind default :kf1 File %
3535 bind compose :kf1 ~e
3539 Note that the entire comma-separated list is first parsed (over) as a
3540 shell-token with whitespace as the field separator, before being parsed
3541 and expanded for real with comma as the field separator, therefore
3542 whitespace needs to be properly quoted, see
3543 .Sx "Shell-style argument quoting" .
3544 Using Unicode reverse solidus escape sequences renders a binding
3545 defunctional if the locale does not support Unicode (see
3546 .Sx "Character sets" ) ,
3547 and using terminal capabilities does so if no terminal control support
3548 is (currently) available.
3551 The following terminal capability names are builtin and can be used in
3553 or (if available) the two-letter
3555 notation regardless of the actually used library.
3556 See the respective manual for a list of capabilities.
3559 can be used to show all the capabilities of
3561 or the given terminal type;
3564 flag will also show supported (non-standard) extensions.
3567 .Bl -tag -compact -width kcuuf_or_kcuuf
3568 .It Cd kbs Ns \0or Cd kb
3570 .It Cd kdch1 Ns \0or Cd kD
3572 .It Cd kDC Ns \0or Cd *4
3573 \(em shifted variant.
3574 .It Cd kel Ns \0or Cd kE
3575 Clear to end of line.
3576 .It Cd kext Ns \0or Cd @9
3578 .It Cd kich1 Ns \0or Cd kI
3580 .It Cd kIC Ns \0or Cd #3
3581 \(em shifted variant.
3582 .It Cd khome Ns \0or Cd kh
3584 .It Cd kHOM Ns \0or Cd #2
3585 \(em shifted variant.
3586 .It Cd kend Ns \0or Cd @7
3588 .It Cd knp Ns \0or Cd kN
3590 .It Cd kpp Ns \0or Cd kP
3592 .It Cd kcub1 Ns \0or Cd kl
3593 Left cursor (with more modifiers: see below).
3594 .It Cd kLFT Ns \0or Cd #4
3595 \(em shifted variant.
3596 .It Cd kcuf1 Ns \0or Cd kr
3597 Right cursor (ditto).
3598 .It Cd kRIT Ns \0or Cd %i
3599 \(em shifted variant.
3600 .It Cd kcud1 Ns \0or Cd kd
3601 Down cursor (ditto).
3603 \(em shifted variant (only terminfo).
3604 .It Cd kcuu1 Ns \0or Cd ku
3607 \(em shifted variant (only terminfo).
3608 .It Cd kf0 Ns \0or Cd k0
3610 Add one for each function key up to
3615 .It Cd kf10 Ns \0or Cd k;
3617 .It Cd kf11 Ns \0or Cd F1
3619 Add one for each function key up to
3627 Some terminals support key-modifier combination extensions, e.g.,
3629 For example, the delete key,
3631 in its shifted variant, the name is mutated to
3633 then a number is appended for the states
3645 .Ql Shift+Alt+Control
3647 The same for the left cursor key,
3649 .Cd KLFT , KLFT3 , KLFT4 , KLFT5 , KLFT6 , KLFT7 , KLFT8 .
3652 Key bindings can be removed with the command
3654 It is advisable to use an initial escape or other control character (e.g.,
3656 for bindings which describe user key combinations (as opposed to purely
3657 terminal capability based ones), in order to avoid ambiguities whether
3658 input belongs to key sequences or not; it also reduces search time.
3661 may help shall keys and sequences be falsely recognized.
3666 \*(NQ Calls the given macro, which must have been created via
3668 Parameters given to macros are implicitly local to the macro's scope, and
3669 may be accessed via the special parameter syntax that is known from the
3676 Positional parameters may be removed by
3678 ing them off the stack.
3679 Macro execution can be terminated at any time by calling
3682 Calling macros recursively will at some time excess the stack size
3683 limit, causing a hard program abortion; if recursively calling a macro
3684 is the last command of the current macro, consider to use the command
3686 which will first release all resources of the current macro before
3687 replacing the current macro with the called one.
3688 Numeric and string operations can be performed via
3692 may be helpful to recreate argument lists.
3693 .Bd -literal -offset indent
3695 echo Parameter 1 of ${#} is ${1}, all: ${*} / ${@}
3698 call exmac Hello macro exmac!
3705 if the given macro has been created via
3707 but doesn't fail nor warn if the macro doesn't exist.
3711 (ch) Change the working directory to
3713 or the given argument.
3719 \*(OP Only applicable to S/MIME signed messages.
3720 Takes a message list and a file name and saves the certificates
3721 contained within the message signatures to the named file in both
3722 human-readable and PEM format.
3723 The certificates can later be used to send encrypted messages to the
3724 respective message senders by setting
3725 .Va smime-encrypt-USER@HOST
3730 .It Ic charsetalias , uncharsetalias
3731 \*(NQ Manage (character set conversion) character set alias mappings,
3732 as documented in the section
3733 .Sx "Character sets" .
3734 Character set aliases are expanded recursively, but no expansion is
3735 performed on values of the user-settable variables, e.g.,
3737 These are effectively no-operations if character set conversion
3738 is not available (i.e., no
3742 Without arguments the list of all currently defined aliases is shown.
3743 Otherwise all given arguments are treated as pairs of character sets and
3744 their desired target alias name, creating new or changing already
3745 existing aliases, as necessary.
3747 The latter deletes all aliases given as arguments, the special argument
3749 will remove all aliases.
3753 (ch) Change the working directory to
3755 or the given argument.
3761 .It Ic collapse , uncollapse
3762 Only applicable to threaded mode.
3763 Takes a message list and makes all replies to these messages invisible
3764 in header summaries, except for
3768 Also when a message with collapsed replies is displayed,
3769 all of these are automatically uncollapsed.
3770 The latter command undoes collapsing.
3775 .It Ic colour , uncolour
3776 \*(OP\*(NQ Manage colour mappings of and for a
3777 .Sx "Coloured display" .
3778 The type of colour is given as the (case-insensitive) first argument,
3779 which must be one of
3781 for 256-colour terminals,
3786 for the standard 8-colour ANSI / ISO 6429 color palette and
3790 for monochrome terminals.
3791 Monochrome terminals cannot deal with colours, but only (some) font
3795 Without further arguments the list of all currently defined mappings
3796 for the given colour type is shown (as a special case giving
3800 will show the mappings of all types).
3801 Otherwise the second argument defines the mappable slot, and the third
3802 argument a (comma-separated list of) colour and font attribute
3803 specification(s), and the optional fourth argument can be used to
3804 specify a precondition: if conditioned mappings exist they are tested in
3805 (creation) order unless a (case-insensitive) match has been found, and
3806 the default mapping (if any has been established) will only be chosen as
3808 The types of precondition available depend on the mappable slot (see
3809 .Sx "Coloured display"
3810 for some examples), the following of which exist:
3813 Mappings prefixed with
3815 are used for the \*(OPal builtin Mailx-Line-Editor (MLE, see
3816 .Sx "On terminal control and line editor" )
3817 and do not support preconditions.
3819 .Bl -tag -compact -width view-partinfo
3821 This mapping is used for the position indicator that is visible when
3822 a line cannot be fully displayed on the screen.
3829 Mappings prefixed with
3831 are used in header summaries, and they all understand the preconditions
3833 (the current message) and
3835 for elder messages (only honoured in conjunction with
3836 .Va datefield-markout-older ) .
3838 .Bl -tag -compact -width view-partinfo
3840 This mapping is used for the
3842 that can be created with the
3846 formats of the variable
3849 For the complete header summary line except the
3851 and the thread structure.
3853 For the thread structure which can be created with the
3855 format of the variable
3860 Mappings prefixed with
3862 are used when displaying messages.
3864 .Bl -tag -compact -width view-partinfo
3866 This mapping is used for so-called
3868 lines, which are MBOX file format specific header lines.
3871 A comma-separated list of headers to which the mapping applies may be
3872 given as a precondition; if the \*(OPal regular expression support is
3873 available then if any of the
3875 (extended) regular expression characters is seen the precondition will
3876 be evaluated as (an extended) one.
3878 For the introductional message info line.
3879 .It Ar view-partinfo
3880 For MIME part info lines.
3884 The following (case-insensitive) colour definitions and font attributes
3885 are understood, multiple of which can be specified in a comma-separated
3895 It is possible (and often applicable) to specify multiple font
3896 attributes for a single mapping.
3899 foreground colour attribute:
3909 To specify a 256-color mode a decimal number colour specification in
3910 the range 0 to 255, inclusive, is supported, and interpreted as follows:
3912 .Bl -tag -compact -width "999 - 999"
3914 the standard ISO 6429 colors, as above.
3916 high intensity variants of the standard colors.
3918 216 colors in tuples of 6.
3920 grayscale from black to white in 24 steps.
3922 .Bd -literal -offset indent
3924 fg() { printf "\e033[38;5;${1}m($1)"; }
3925 bg() { printf "\e033[48;5;${1}m($1)"; }
3927 while [ $i -lt 256 ]; do fg $i; i=$(($i + 1)); done
3928 printf "\e033[0m\en"
3930 while [ $i -lt 256 ]; do bg $i; i=$(($i + 1)); done
3931 printf "\e033[0m\en"
3935 background colour attribute (see
3937 for possible values).
3943 will remove for the given colour type (the special type
3945 selects all) the given mapping; if the optional precondition argument is
3946 given only the exact tuple of mapping and precondition is removed.
3949 will remove all mappings (no precondition allowed), thus
3951 will remove all established mappings.
3956 .It Ic commandalias , uncommandalias
3957 \*(NQ Define or list, and remove, respectively, command aliases.
3958 An (command)alias can be used everywhere a normal command can be used,
3959 but always takes precedence: any arguments that are given to the command
3960 alias are joined onto the alias content, and the resulting string forms
3961 the command line that is, in effect, executed.
3962 The latter command removes all given aliases, the special name
3964 will remove all existing aliases.
3965 When used without arguments the former shows a list of all currently
3966 known aliases, with one argument only the expansion of the given one.
3968 With two or more arguments a command alias is defined or updated: the
3969 first argument is the name under which the remaining command line should
3970 be accessible, the content of which can be just about anything.
3971 An alias may itself expand to another alias, but to avoid expansion loops
3972 further expansion will be prevented if an alias refers to itself or if
3973 an expansion depth limit is reached.
3974 Explicit expansion prevention is available via reverse solidus
3977 .Sx "Command modifiers" .
3978 .Bd -literal -offset indent
3980 \*(uA: `commandalias': no such alias: xx
3981 ? commandalias xx echo hello,
3983 commandalias xx 'echo hello,'
3992 (C) Copy messages to files whose names are derived from the author of
3993 the respective message and do not mark them as being saved;
3994 otherwise identical to
3999 (c) Copy messages to the named file and do not mark them as being saved;
4000 otherwise identical to
4005 Show the name of the current working directory, as reported by
4010 .Sx "Command modifiers" ) .
4011 The return status is tracked via
4016 \*(OP For unencrypted messages this command is identical to
4018 Encrypted messages are first decrypted, if possible, and then copied.
4022 \*(OP For unencrypted messages this command is identical to
4024 Encrypted messages are first decrypted, if possible, and then copied.
4028 .It Ic define , undefine
4029 Without arguments the current list of macros, including their content,
4030 is shown, otherwise a macro is defined, replacing an existing macro of
4032 A macro definition is a sequence of commands in the following form:
4033 .Bd -literal -offset indent
4042 A defined macro can be invoked explicitly by using the
4046 commands, or implicitly if a macro hook is triggered, e.g., a
4048 It is possible to localize adjustments, like creation, deletion and
4050 .Sx "INTERNAL VARIABLES" ,
4053 command; the scope which is localized depends on how (i.e.,
4055 normal macro, folder hook, hook,
4057 switch) the macro is invoked.
4058 Execution of a macro body can be stopped from within by calling
4062 ed macro, given positional parameters can be
4066 The latter command deletes the given macro, the special name
4068 will discard all existing macros.
4069 Creation and deletion of (a) macro(s) can be performed from within
4074 .It Ic delete , undelete
4075 (d, u) Marks the given message list as being or not being
4077 respectively; if no argument has been specified then the usual search
4078 for a visible message is performed, as documented for
4079 .Sx "Message list arguments" ,
4080 showing only the next input prompt if the search fails.
4081 Deleted messages will neither be saved in the
4083 .Sx "secondary mailbox"
4085 nor will they be available for most other commands.
4088 variable is set, the new
4090 or the last message restored, respectively, is automatically
4100 Superseded by the multiplexer
4106 Delete the given messages and automatically
4110 if one exists, regardless of the setting of
4117 up or down by one message when given
4121 argument, respectively.
4125 .It Ic draft , undraft
4126 Take message lists and mark each given message as being draft, or not
4127 being draft, respectively, as documented in the section
4128 .Sx "Message states" .
4132 \*(NQ (ec) Echoes arguments to standard output and writes a trailing
4133 newline, whereas the otherwise identical
4136 .Sx "Shell-style argument quoting"
4138 .Sx "Filename transformations"
4139 are applied to the expanded arguments.
4145 except that is echoes to standard error.
4153 but does not write a trailing newline.
4159 but does not write a trailing newline.
4163 (e) Point the text editor (as defined in
4165 at each message from the given list in turn.
4166 Modified contents are discarded unless the
4173 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
4174 conditional \(em if the condition of a preceding
4176 was false, check the following condition and execute the following block
4177 if it evaluates true.
4182 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
4183 conditional \(em if none of the conditions of the preceding
4187 commands was true, the
4193 (en) Marks the end of an
4194 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
4195 conditional execution block.
4200 \*(NQ \*(UA has a strict notion about which variables are
4201 .Sx "INTERNAL VARIABLES"
4202 and which are managed in the program
4204 Since some of the latter are a vivid part of \*(UAs functioning,
4205 however, they are transparently integrated into the normal handling of
4206 internal variables via
4210 To integrate other environment variables of choice into this
4211 transparent handling, and also to export internal variables into the
4212 process environment where they normally are not, a
4214 needs to become established with this command, as in, e.g.,
4217 .Dl environ link PERL5LIB from TZ
4220 Afterwards changing such variables with
4222 will cause automatic updates of the program environment, and therefore
4223 be inherited by newly created child processes.
4224 Sufficient system support provided (it was in BSD as early as 1987, and
4225 is standardized since Y2K) removing such variables with
4227 will remove them also from the program environment, but in any way
4228 the knowledge they ever have been
4231 Note this implies that
4233 may cause loss of links.
4238 will remove an existing link, but leaves the variables as such intact.
4239 Additionally the subcommands
4243 are provided, which work exactly the same as the documented commands
4247 but (additionally) link the variable(s) with the program environment and
4248 thus immediately export them to, or remove them from (if possible),
4249 respectively, the program environment.
4254 \*(OP Since \*(UA uses the console as a user interface it can happen
4255 that messages scroll by too fast to become recognized.
4256 Optionally an error message ring queue is available which stores
4257 duplicates of any error message and notifies the user in interactive
4258 sessions whenever a new error has occurred.
4259 The queue is finite: if its maximum size is reached any new message
4260 replaces the eldest.
4263 can be used to manage this message queue: if given
4265 or no argument the queue will be displayed and cleared,
4267 will only clear all messages from the queue.
4271 \*(NQ Construct a command by concatenating the arguments, separated with
4272 a single space character, and then evaluate the result.
4273 This command passes through the exit status
4277 of the evaluated command; also see
4279 .Bd -literal -offset indent
4281 # Like this, sh(1)ell-stylish from begin to end: works!
4282 # Result status ends up in $!, then
4283 localopts 1;wysh set verbose;ignerr eval "${@}";return ${?}
4285 commandalias xv '\ecall xverbose'
4298 call yyy '~xxx' "b\e$'\et'u ' "
4306 (ex or x) Exit from \*(UA without changing the active mailbox and skip
4307 any saving of messages in the
4309 .Sx "secondary mailbox"
4311 as well as a possibly tracked line editor history file.
4317 but open the mailbox read-only.
4322 (fi) The file command switches to a new mailbox.
4323 Without arguments it shows status information of the current mailbox.
4324 If an argument is given, it will write out changes (such as deletions)
4325 the user has made, open a new mailbox and update the internal variables
4326 .Va mailbox-resolved
4328 .Va mailbox-display .
4329 .Sx "Filename transformations"
4330 will be applied to the
4335 If the name ends with
4340 it is treated as being compressed with
4345 respectively, and transparently handled through an intermediate
4346 (un)compression step (using a temporary file) with the according
4347 facility, sufficient support provided.
4348 Likewise, if the named file does not exist, but a file with one of the
4349 mentioned compression extensions does, then the name is automatically
4350 expanded and the compressed file is used.
4353 Otherwise, if the name ends with an extension for which
4354 .Va file-hook-load-EXTENSION
4356 .Va file-hook-save-EXTENSION
4357 variables are set, then the given hooks will be used to load and save
4359 and \*(UA will work with an intermediate temporary file.
4361 MBOX files (flat file-based mailboxes) are generally locked during file
4362 operations in order to avoid inconsistencies due to concurrent
4364 \*(OPal Mailbox files which \*(UA treats as the system
4369 .Sx "primary system mailbox" Ns
4370 es in general will also be protected by so-called dotlock files, the
4371 traditional way of mail spool file locking: for any file
4375 will be created for the duration of the synchronization \(em
4376 as necessary a privilege-separated dotlock child process will be used
4377 to accommodate for necessary privilege adjustments in order to create
4378 the dotlock file in the same directory
4379 and with the same user and group identities as the file of interest.
4382 \*(UA by default uses tolerant POSIX rules when reading MBOX database
4383 files, but it will detect invalid message boundaries in this mode and
4384 complain (even more with
4386 if any is seen: in this case
4388 can be used to create a valid MBOX database from the invalid input.
4393 refers to a directory with the subdirectories
4398 then it is treated as a folder in
4400 format; \*(ID the variable
4402 can be used to control the format of yet non-existent folders.
4406 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
4407 .Dl \*(OU protocol://[user@]host[:port][/path]
4410 is taken as an Internet mailbox specification.
4411 The \*(OPally supported protocols are
4415 (POP3 with SSL/TLS encrypted transport).
4418 part is valid only for IMAP; there it defaults to
4420 Also see the section
4421 .Sx "On URL syntax and credential lookup" .
4426 contains special characters, in particular
4430 they must be escaped in URL notation \(en the command
4432 can be used to show the necessary conversion.
4437 .It Ic flag , unflag
4438 Take message lists and mark the messages as being flagged, or not being
4439 flagged, respectively, for urgent/special attention.
4441 .Sx "Message states" .
4450 With no arguments, list the names of the folders in the folder directory.
4451 With an existing folder as an argument,
4452 lists the names of folders below the named folder.
4458 but saves the message in a file named after the local part of the first
4459 recipient's address (instead of in
4466 but saves the message in a file named after the local part of the first
4467 recipient's address (instead of in
4474 but responds to all recipients regardless of the
4479 .It Ic followupsender
4482 but responds to the sender only regardless of the
4498 (f) Takes a list of message specifications and displays a summary of
4499 their message headers, exactly as via
4501 An alias of this command is
4504 .Sx "Specifying messages" .
4510 but saves the message in a file named after the local part of the
4511 recipient's address (instead of in
4516 Takes a message and the address of a recipient
4517 and forwards the message to him.
4518 The text of the original message is included in the new one,
4519 with the value of the
4521 variable preceding it.
4522 To filter the included header fields to the desired subset use the
4524 slot of the white- and blacklisting command
4526 Only the first part of a multipart message is included unless
4527 .Va forward-as-attachment ,
4528 and recipient addresses will be stripped from comments, names etc.
4529 unless the internal variable
4535 \*(OB Superseded by the multiplexer
4540 \*(OB Superseded by the multiplexer
4545 .It Ic ghost , unghost
4548 .Ic uncommandalias .
4552 .It Ic headerpick , unheaderpick
4553 \*(NQ Multiplexer command to manage white- and blacklisting
4554 selections of header fields for a variety of applications.
4555 Without arguments the set of contexts that have settings is displayed.
4556 When given arguments, the first argument is the context to which the
4557 command applies, one of (case-insensitively)
4559 for display purposes (via, e.g.,
4562 for selecting which headers shall be stored persistently when
4568 ing messages (note that MIME related etc. header fields should not be
4569 ignored in order to not destroy usability of the message in this case),
4571 for stripping down messages when
4573 ing message (has no effect if
4574 .Va forward-as-attachment
4577 for defining user-defined set of fields for the command
4581 The current settings of the given context are displayed if only the
4582 first argument is given.
4583 A second argument denotes the type of restriction that is to be chosen,
4584 it may be (a case-insensitive prefix of)
4588 for white- and blacklisting purposes, respectively.
4589 Establishing a whitelist suppresses inspection of the corresponding
4591 If no further argument is given the current settings of the given type
4592 will be displayed, otherwise the remaining arguments specify header
4593 fields, which \*(OPally may be given as regular expressions, to be be
4594 added to the given type.
4595 The special wildcard field (asterisk,
4597 will establish a (fast) shorthand setting which covers all fields.
4599 The latter command always takes three or more arguments and can be used
4600 to remove fields from the given type of list of the given context, the
4603 will remove all fields.
4608 (h) Show the current group of headers, the size of which depends on
4611 and the style of which can be adjusted with the variable
4613 If a message-specification is given the group of headers containing the
4614 first message therein is shown and the message at the top of the screen
4629 the list of history entries;
4632 argument selects and evaluates the respective history entry,
4633 which will become the new history top; a negative number is used as an
4634 offset to the current command, e.g.,
4636 will select the last command, the history top.
4637 The default mode if no arguments are given is
4644 Takes a message list and marks each message therein to be saved in the
4649 .Sx "secondary mailbox"
4651 Does not override the
4654 \*(UA deviates from the POSIX standard with this command, because a
4656 command issued after
4658 will display the following message, not the current one.
4663 (i) Part of the nestable
4664 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
4665 conditional execution construct \(em if the given condition is true then
4666 the encapsulated block is executed.
4667 POSIX only supports the (case-insensitive) conditions
4672 end, all remaining conditions are non-portable extensions; note that
4673 falsely specified conditions cause the execution of the entire
4674 conditional construct until the (matching) closing
4676 command to be suppressed.
4677 The syntax of the nestable
4679 conditional execution construct requires that each condition and syntax
4680 element is surrounded by whitespace.
4682 .Bd -literal -offset indent
4691 The (case-insensitive) condition
4693 erminal will evaluate to true if the standard input is a terminal, i.e.,
4694 in interactive sessions.
4695 Another condition can be any boolean value (see the section
4696 .Sx "INTERNAL VARIABLES"
4697 for textual boolean representations) to mark an enwrapped block as
4700 .Dq always execute .
4701 It is possible to check
4702 .Sx "INTERNAL VARIABLES"
4705 variables for existence or compare their expansion against a user given
4706 value or another variable by using the
4708 .Pf ( Dq variable next )
4709 conditional trigger character;
4710 a variable on the right hand side may be signalled using the same
4712 The variable names may be enclosed in a pair of matching braces.
4715 Integer operators treat the left and right hand side as integral numbers
4716 and compare them arithmetically.
4717 It is an error if any of the operands is not a valid integer, an empty
4718 operand is treated as if it were 0.
4719 Available operators are
4723 (less than or equal to),
4729 (greater than or equal to), and
4734 String operators compare the left and right hand side 8-bit byte-wise,
4735 ignoring case according to the rules of the US-ASCII encoding
4736 (therefore, dependent on the active locale, possibly producing false
4737 results for strings in the locale encoding).
4738 An unset variable is treated as the empty string.
4739 Available operators are
4743 (less than or equal to),
4749 (greater than or equal to),
4753 (is substring of) and
4755 (is not substring of).
4758 When the \*(OPal regular expression support is available, the additional
4764 They treat the right hand side as an extended regular expression that is
4765 matched case-insensitively and according to the active
4767 locale, meaning that strings in the locale encoding should be matched
4771 Conditions can be joined via AND-OR lists (where the AND operator is
4773 and the OR operator is
4775 which have equal precedence and will be evaluated with left
4776 associativity, thus using the same syntax that is known for the
4778 It is also possible to form groups of conditions and lists by enclosing
4779 them in pairs of brackets
4780 .Ql [\ \&.\&.\&.\ ] ,
4781 which may be interlocked within each other, and also be joined via
4785 The results of individual conditions and entire groups may be modified
4786 via unary operators: the unary operator
4788 will reverse the result.
4790 .Bd -literal -offset indent
4794 if [ "$ttycharset" == UTF-8 ] || [ "$ttycharset" == UTF8 ]
4795 echo *ttycharset* is set to UTF-8, case-insensitively
4798 if [ "${t1}" == "${t2}" ]
4799 echo These two variables are equal
4801 # This is a string test, -ge was added for v14.9.0
4802 if [ "$version-major" >= 15 ]
4803 echo Running a new version..
4804 if [ "$features" =@ +regex ]
4805 if [ "$TERM" =~ "^xterm\&.*" ]
4806 echo ..in an X terminal
4809 if [ [ true ] && [ [ "${debug}" != '' ] || \e
4810 [ "$verbose" != '' ] ] ]
4813 if true && [ "$debug" != '' ] || [ "${verbose}" != '' ]
4814 echo Left associativity, as is known from the shell
4816 if ! ! true && ! [ ! "$debug" && ! "$verbose" ]
4817 echo Unary operator support
4827 Superseded by the multiplexer
4832 Shows the names of all available commands, alphabetically sorted.
4833 If given any non-whitespace argument the list will be shown in the order
4834 in which command prefixes are searched.
4835 \*(OP In conjunction with a set variable
4837 additional information will be provided for each command: the argument
4838 type will be indicated, the documentation string will be shown,
4839 and the set of command flags will show up:
4841 .Bl -tag -compact -width ".It Ql BaNg"
4842 .It Ql "vput modifier"
4843 command supports the command modifier
4845 .It Ql "errno in *!*"
4846 the error number is tracked in
4849 commands needs an active mailbox, a
4851 .It Ql "ok: batch or interactive"
4852 command may only be used in interactive or
4855 .It Ql "ok: send mode"
4856 command can be used in send mode.
4857 .It Ql "not ok: compose mode"
4858 command is not available when in compose mode.
4859 .It Ql "not ok: during startup"
4860 command cannot be used during program startup, e.g., while loading
4861 .Sx "Resource files" .
4862 .It Ql "ok: in subprocess"
4863 command is allowed to be used when running in a subprocess instance,
4864 e.g., from within a macro that is called via
4865 .Va on-compose-splice .
4870 This command can be used to localize changes to variables, meaning that
4871 their state will be reverted to the former one once the covered scope
4873 It can only be used inside of macro definition blocks introduced by
4877 and is interpreted as a boolean (string, see
4878 .Sx "INTERNAL VARIABLES" ) ;
4881 of an account is left once it is switched off again.
4882 .Bd -literal -offset indent
4883 define temporary_settings {
4884 set possibly_global_option1
4889 set possibly_global_option2
4898 enables change localization and calls
4900 which explicitly resets localization, then any value changes within
4902 will still be reverted by
4904 \*(ID Once the outermost level, the one which enabled localization
4905 first, is left, but no earlier, all adjustments will be unrolled.
4906 \*(ID Likewise worth knowing, if in this example
4908 changes to a different
4910 which sets some variables that are yet covered by localizations, their
4911 scope will be extended, and in fact leaving the
4913 will (thus) restore settings in (likely) global scope which actually
4914 were defined in a local, private context.
4918 Reply to messages that come in via known
4921 .Pf ( Ic mlsubscribe )
4922 mailing lists, or pretend to do so (see
4923 .Sx "Mailing lists" ) :
4926 functionality this will actively resort and even remove message
4927 recipients in order to generate a message that is supposed to be sent to
4929 For example it will also implicitly generate a
4930 .Ql Mail-Followup-To:
4931 header if that seems useful, regardless of the setting of the variable
4938 but saves the message in a file named after the local part of the first
4939 recipient's address (instead of in
4944 (m) Takes a (list of) recipient address(es) as (an) argument(s),
4945 or asks on standard input if none were given;
4946 then collects the remaining mail content and sends it out.
4950 (mb) The given message list is to be sent to the
4952 .Sx "secondary mailbox"
4954 when \*(UA is quit; this is the default action unless the variable
4957 \*(ID This command can only be used in a
4959 .Sx "primary system mailbox" .
4963 .It Ic mimetype , unmimetype
4964 Without any arguments the content of the MIME type cache will displayed.
4965 Otherwise each argument defines a complete MIME type specification of
4966 a type that shall be added (prepended) to the cache.
4967 In any event MIME type sources are loaded first as necessary \(en
4968 .Va mimetypes-load-control
4969 can be used to fine-tune which sources are actually loaded.
4970 Refer to the section on
4971 .Sx "The mime.types files"
4972 for more on MIME type specifications and this topic in general.
4974 The latter command deleted all specifications of the given MIME type, so
4975 .Ql unmimetype text/plain
4976 will remove all registered specifications for the MIME type
4980 will discard all existing MIME types, just as will
4982 but which also reenables cache initialization via
4983 .Va mimetypes-load-control .
4987 .It Ic mlist , unmlist
4988 The latter command removes all given mailing-lists, the special name
4990 can be used to remove all registered lists.
4991 The former will list all currently defined mailing lists (and their
4992 attributes, if any) when used without arguments; a more verbose listing
4993 will be produced if either of
4998 Otherwise all given arguments will be added and henceforth be recognized
5000 If the \*(OPal regular expression support is available then mailing
5001 lists may also be specified as (extended) regular expressions (see
5007 .It Ic mlsubscribe , unmlsubscribe
5008 The latter command removes the subscription attribute from all given
5009 mailing-lists, the special name
5011 can be used to do so for any registered list.
5012 The former will list all currently defined mailing lists which have
5013 a subscription attribute when used without arguments; a more verbose
5014 listing will be produced if either of
5019 Otherwise this attribute will be set for all given mailing lists,
5020 newly creating them as necessary (as via
5029 but moves the messages to a file named after the local part of the
5030 sender address of the first message (instead of in
5037 but marks the messages for deletion if they were transferred
5044 but also displays header fields which would not pass the
5046 selection, and all MIME parts.
5054 on the given messages, even in non-interactive mode and as long as the
5055 standard output is a terminal.
5061 \*(OP When used without arguments or if
5063 has been given the content of the
5065 cache is shown, loading it first as necessary.
5068 then the cache will only be initialized and
5070 will remove its contents.
5071 Note that \*(UA will try to load the file only once, use
5072 .Ql Ic \&\&netrc Ns \:\0\:clear
5073 to unlock further attempts.
5078 .Sx "On URL syntax and credential lookup" ;
5080 .Sx "The .netrc file"
5081 documents the file format in detail.
5085 Checks for new mail in the current folder without committing any changes
5087 If new mail is present, a message is shown.
5091 the headers of each new message are also shown.
5092 This command is not available for all mailbox types.
5100 Goes to the next message in sequence and types it.
5101 With an argument list, types the next matching message.
5115 If the current folder is accessed via a network connection, a
5117 command is sent, otherwise no operation is performed.
5123 but also displays header fields which would not pass the
5125 selection, and all MIME parts.
5133 on the given messages, even in non-interactive mode and as long as the
5134 standard output is a terminal.
5142 but also pipes header fields which would not pass the
5144 selection, and all parts of MIME
5145 .Ql multipart/alternative
5150 (pi) Takes a message list and a shell command
5151 and pipes the messages through the command.
5152 Without an argument the current message is piped through the command
5159 every message is followed by a formfeed character.
5180 (q) Terminates the session, saving all undeleted, unsaved messages in
5183 .Sx "secondary mailbox"
5185 preserving all messages marked with
5189 or never referenced in the system
5191 and removing all other messages from the
5193 .Sx "primary system mailbox" .
5194 If new mail has arrived during the session,
5196 .Dq You have new mail
5198 If given while editing a mailbox file with the command line option
5200 then the edit file is rewritten.
5201 A return to the shell is effected,
5202 unless the rewrite of edit file fails,
5203 in which case the user can escape with the exit command.
5207 \*(NQ Read a line from standard input, and assign the splitted and
5208 trimmed line data to the given variables.
5209 The variable names are checked by the same rules as documented for
5211 and the same error codes will be seen in
5213 If there are more fields than variables, assign successive fields to the
5214 last given variable.
5215 If there are less fields than variables, assign the empty string to the
5217 \*(ID This command will likely be extended towards more
5219 compatibility: for now splitting always occurs at whitespace, reverse
5220 solidus newline escaping is always supported, and the \*(OPal line
5221 editing features are always available when on an interactive terminal.
5222 .Bd -literal -offset indent
5225 ? echo "<$a> <$b> <$c>"
5241 Removes the named files or directories.
5242 If a name refer to a mailbox, e.g., a Maildir mailbox, then a mailbox
5243 type specific removal will be performed, deleting the complete mailbox.
5244 The user is asked for confirmation in interactive mode.
5248 Takes the name of an existing folder
5249 and the name for the new folder
5250 and renames the first to the second one.
5251 Both folders must be of the same type.
5255 (R) Reply to originator.
5256 Does not reply to other recipients of the original message.
5258 will exchange this command with
5260 Unless the internal variable
5262 is set the recipient address will be stripped from comments, names etc.
5266 (r) Take a message and group-responds to it by addressing the sender
5269 .Va followup-to-honour ,
5272 .Va recipients-in-cc
5273 influence response behaviour.
5276 offers special support for replying to mailing lists.
5277 Unless the internal variable
5279 is set recipient addresses will be stripped from comments, names etc.
5292 but initiates a group-reply regardless of the value of
5299 but responds to the sender only regardless of the value of
5306 but does not add any header lines.
5307 This is not a way to hide the sender's identity,
5308 but useful for sending a message again to the same recipients.
5312 Takes a list of messages and a user name
5313 and sends each message to the named user.
5315 and related header fields are prepended to the new copy of the message.
5333 .It Ic respondsender
5339 (ret) Superseded by the multiplexer
5344 Only available inside the scope of a
5348 this will stop evaluation of any further macro content, and return
5349 execution control to the caller.
5350 The two optional parameters must be specified as positive decimal
5351 numbers and default to the value 0:
5352 the first argument specifies the signed 32-bit return value (stored in
5354 and later extended to signed 64-bit),
5355 the second the signed 32-bit error number (stored in
5359 a non-0 exit status may cause the program to exit.
5365 but saves the messages in a file named after the local part of the
5366 sender of the first message instead of (in
5368 and) taking a filename argument.
5372 (s) Takes a message list and a filename and appends each message in turn
5373 to the end of the file.
5374 If no filename is given, the
5376 .Sx "secondary mailbox"
5379 The filename in quotes, followed by the generated character count
5380 is echoed on the user's terminal.
5383 .Sx "primary system mailbox"
5384 the messages are marked for deletion.
5385 .Sx "Filename transformations"
5390 \*(OB Superseded by the multiplexer
5395 \*(OB Superseded by the multiplexer
5400 \*(OB Superseded by the multiplexer
5405 Takes a message specification (list) and displays a header summary of
5406 all matching messages, as via
5408 This command is an alias of
5411 .Sx "Specifying messages" .
5415 Takes a message list and marks all messages as having been read.
5421 (se, \*(NQ uns) The latter commands will delete all given variables,
5422 the former, when used without arguments, will show all variables which
5423 are currently known to \*(UA; a more verbose listing will be produced if
5430 Otherwise the given variables (and arguments) are set or adjusted.
5431 Arguments are of the form
5433 (no space before or after
5437 if there is no value, i.e., a boolean variable.
5438 Quotation marks may be placed around any part of the assignment
5439 statement to quote blanks or tabs, e.g.,
5441 .Dl set indentprefix='->'
5443 If an argument begins with
5447 the effect is the same as invoking the
5449 command with the remaining part of the variable
5450 .Pf ( Ql unset save ) .
5454 that is known to map to an environment variable will automatically cause
5455 updates in the program environment (unsetting a variable in the
5456 environment requires corresponding system support) \(em use the command
5458 for further environmental control.
5463 .Sx "INTERNAL VARIABLES"
5470 Apply shell quoting rules to the given raw-data arguments.
5474 .Sx "Command modifiers" ) ,
5475 The first argument specifies the operation:
5479 cause shell quoting to be applied to the remains of the line, and
5480 expanded away thereof, respectively.
5481 If the former is prefixed with a plus-sign, the quoted result will not
5482 be roundtrip enabled, and thus can be decoded only in the very same
5483 environment that was used to perform the encode; also see
5484 .Cd mle-quote-rndtrip .
5485 If the coding operation fails the error number
5488 .Va ^ERR Ns -CANCELED ,
5489 and the unmodified input is used as the result; the error number may
5490 change again due to output or result storage errors.
5494 (sh) Invokes an interactive version of the shell.
5498 .It Ic shortcut , unshortcut
5499 Without arguments the list of all currently defined shortcuts is
5501 Otherwise all given arguments are treated as pairs of shortcuts and
5502 their expansions, creating new or changing already existing shortcuts,
5504 The latter command will remove all given shortcuts, the special name
5506 will remove all registered shortcuts.
5510 Only available inside the scope of a
5512 ed macro, this will shift the positional parameters (starting at
5514 by the given number (which must be an unsigned, positive, decimal),
5515 or 1 if no argument has been given.
5516 It is an error if the value exceeds the number of positional parameters.
5517 If the given number is 0, no action is performed, successfully.
5523 but performs neither MIME decoding nor decryption, so that the raw
5524 message text is shown.
5528 (si) Shows the size in characters of each message of the given
5533 \*(NQ Sleep for the specified number of seconds (and optionally
5534 milliseconds), by default interruptably.
5535 If a third argument is given the sleep will be uninterruptible,
5536 otherwise the error number
5540 if the sleep has been interrupted.
5541 The command will fail and the error number will be
5542 .Va ^ERR Ns -OVERFLOW
5543 if the given duration(s) overflow the time datatype, and
5545 if the given durations are no valid integers.
5550 .It Ic sort , unsort
5551 The latter command disables sorted or threaded mode, returns to normal
5552 message order and, if the
5555 displays a header summary.
5556 The former command shows the current sorting criterion when used without
5557 an argument, but creates a sorted representation of the current folder
5558 otherwise, and changes the
5560 command and the addressing modes such that they refer to messages in
5562 Message numbers are the same as in regular mode.
5566 a header summary in the new order is also displayed.
5567 Automatic folder sorting can be enabled by setting the
5569 variable, as in, e.g.,
5570 .Ql set autosort=thread .
5571 Possible sorting criterions are:
5574 .Bl -tag -compact -width "subject"
5576 Sort the messages by their
5578 field, that is by the time they were sent.
5580 Sort messages by the value of their
5582 field, that is by the address of the sender.
5585 variable is set, the sender's real name (if any) is used.
5587 Sort the messages by their size.
5589 \*(OP Sort the message by their spam score, as has been classified by
5592 Sort the messages by their message status.
5594 Sort the messages by their subject.
5596 Create a threaded display.
5598 Sort messages by the value of their
5600 field, that is by the address of the recipient.
5603 variable is set, the recipient's real name (if any) is used.
5609 \*(NQ (so) The source command reads commands from the given file.
5610 .Sx "Filename transformations"
5612 If the given expanded argument ends with a vertical bar
5614 then the argument will instead be interpreted as a shell command and
5615 \*(UA will read the output generated by it.
5616 Interpretation of commands read is stopped when an error is encountered.
5619 cannot be used from within macros that execute as
5620 .Va folder-hook Ns s
5623 i.e., it can only be called from macros that were
5628 \*(NQ The difference to
5630 (beside not supporting pipe syntax aka shell command input) is that
5631 this command will not generate an error nor warn if the given file
5632 argument cannot be opened successfully.
5636 \*(OP Takes a list of messages and clears their
5642 \*(OP Takes a list of messages and causes the
5644 to forget it has ever used them to train its Bayesian filter.
5645 Unless otherwise noted the
5647 flag of the message is inspected to chose whether a message shall be
5655 \*(OP Takes a list of messages and informs the Bayesian filter of the
5659 This also clears the
5661 flag of the messages in question.
5665 \*(OP Takes a list of messages and rates them using the configured
5666 .Va spam-interface ,
5667 without modifying the messages, but setting their
5669 flag as appropriate; because the spam rating headers are lost the rate
5670 will be forgotten once the mailbox is left.
5671 Refer to the manual section
5673 for the complete picture of spam handling in \*(UA.
5677 \*(OP Takes a list of messages and sets their
5683 \*(OP Takes a list of messages and informs the Bayesian filter of the
5689 flag of the messages in question.
5706 slot for white- and blacklisting header fields.
5710 (to) Takes a message list and types out the first
5712 lines of each message on the users' terminal.
5713 Unless a special selection has been established for the
5717 command, the only header fields that are displayed are
5728 It is possible to apply compression to what is displayed by setting
5730 Messages are decrypted and converted to the terminal character set
5735 (tou) Takes a message list and marks the messages for saving in the
5737 .Sx "secondary mailbox"
5739 \*(UA deviates from the POSIX standard with this command,
5742 command will display the following message instead of the current one.
5748 but also displays header fields which would not pass the
5750 selection, and all parts of MIME
5751 .Ql multipart/alternative
5756 (t) Takes a message list and types out each message on the users'
5760 For MIME multipart messages, all parts with a content type of
5764 are shown, the other are hidden except for their headers.
5765 Messages are decrypted and converted to the terminal character set
5810 \*(OB Superseded by the multiplexer
5815 \*(OB Superseded by the multiplexer
5820 Superseded by the multiplexer
5831 .It Ic unmlsubscribe
5842 Takes a message list and marks each message as not having been read.
5846 Superseded by the multiplexer
5851 \*(OB Superseded by the multiplexer
5856 \*(OB Superseded by the multiplexer
5879 Perform URL percent codec operations on the raw-data argument, rather
5880 according to RFC 3986.
5884 .Sx "Command modifiers" ) ,
5885 and manages the error number
5887 This is a character set agnostic and thus locale dependent operation,
5888 and it may decode bytes which are invalid in the current
5890 \*(ID This command does not about URLs beside that.
5892 The first argument specifies the operation:
5896 perform plain URL percent en- and decoding, respectively.
5900 perform a slightly modified operation which should be better for
5901 pathnames: it does not allow a tilde
5903 and will neither accept hyphen-minus
5907 as an initial character.
5908 The remains of the line form the URL data which is to be converted.
5909 If the coding operation fails the error number
5912 .Va ^ERR Ns -CANCELED ,
5913 and the unmodified input is used as the result; the error number may
5914 change again due to output or result storage errors.
5918 \*(NQ Edit the values of or create the given variable(s) in the
5920 Boolean variables cannot be edited, and variables can also not be
5926 \*(NQ This command produces the same output as the listing mode of
5930 ity adjustments, but only for the given variables.
5934 \*(OP Takes a message list and verifies each message.
5935 If a message is not a S/MIME signed message,
5936 verification will fail for it.
5937 The verification process checks if the message was signed using a valid
5939 if the message sender's email address matches one of those contained
5940 within the certificate,
5941 and if the message content has been altered.
5954 \*(NQ Evaluate arguments according to a given operator.
5955 This is a multiplexer command which can be used to perform signed 64-bit
5956 numeric calculations as well as string operations.
5957 It uses polish notation, i.e., the operator is the first argument and
5958 defines the number and type, and the meaning of the remaining arguments.
5959 An empty argument is replaced with a 0 if a number is expected.
5963 .Sx "Command modifiers" ) .
5966 The result that is shown in case of errors is always
5968 for usage errors and numeric operations, and the empty string for string
5970 String operations which fail to provide result data for
5972 errors, e.g., when a search operation failed, also set the
5975 .Va ^ERR Ns -NODATA .
5976 Except when noted than numeric arguments are parsed as signed 64-bit
5977 numbers, and errors will be reported in the error number
5979 as the numeric error
5980 .Va ^ERR Ns -RANGE .
5983 Numeric operations work on one or two signed 64-bit integers.
5984 One integer is expected by assignment (equals sign
5986 which does nothing but parsing the argument, thus detecting validity and
5987 possible overflow conditions, and unary not (tilde
5989 which creates the bitwise complement.
5990 Two integers are used by addition (plus sign
5992 subtraction (hyphen-minus
5994 multiplication (asterisk
5998 and modulo (percent sign
6000 as well as for the bitwise operators logical or (vertical bar
6003 bitwise and (ampersand
6006 bitwise xor (circumflex
6008 the bitwise signed left- and right shifts
6011 as well as for the unsigned right shift
6015 All numeric operators can be suffixed with a commercial at
6019 this will turn the operation into a saturated one, which means that
6020 overflow errors and division and modulo by zero are no longer reported
6021 via the exit status, but the result will linger at the minimum or
6022 maximum possible value, instead of overflowing (or trapping).
6023 This is true also for the argument parse step.
6024 For the bitwise shifts, the saturated maximum is 63.
6025 Any catched overflow will be reported via the error number
6028 .Va ^ERR Ns -OVERFLOW .
6031 String operations that take one argument are
6033 which queries the length of the given argument,
6035 which calculates the Chris Torek hash of the given string, and
6037 which performs the usual
6038 .Sx "Filename transformations" ,
6039 on its argument, as well as
6041 which generates a random string of the given length, or of
6043 bytes (a constant from
6045 if the value 0 is given; the random string will be base64url encoded
6046 according to RFC 4648, and thus be usable as a file name.
6049 String operations with two or more arguments are
6051 which searches in the first for the second argument, and shows the
6052 resulting 0-based offset shall it have been found,
6054 which is identical to
6056 but works case-insensitively according to the rules of the ASCII
6059 will show a substring of its first argument:
6060 the second argument is the 0-based starting offset, the optional third
6061 argument can be used to specify the length of the desired substring,
6062 by default the entire string is used;
6063 this operation tries to work around faulty arguments (set
6065 for error logs), but reports them via the error number
6068 .Va ^ERR Ns -OVERFLOW .
6073 will try to match the first argument with the regular expression given
6074 in the second argument, as does
6076 but which is case-insensitive.
6077 These operators match according to the active
6079 locale and thus should match correctly strings in the locale encoding.
6080 If the optional third argument has been given then instead of showing
6081 the match offset a replacement operation is performed:
6082 the third argument is treated as if specified via dollar-single-quote
6084 .Sx "Shell-style argument quoting" ) ,
6085 and any occurrence of a positional parameter, e.g.,
6087 is replaced by the corresponding match group of the regular expression.
6089 .Bd -literal -offset indent
6090 ? vexpr -@ +1 -9223372036854775808
6091 ? vput vexpr res ir bananarama (.*)nana(.*) '\e${1}au\e$2'
6098 (v) Takes a message list and invokes the display editor on each message.
6099 Modified contents are discarded unless the
6105 (w) For conventional messages the body without all headers is written.
6106 The original message is never marked for deletion in the originating
6108 The output is decrypted and converted to its native format as necessary.
6109 If the output file exists, the text is appended.
6110 If a message is in MIME multipart format its first part is written to
6111 the specified file as for conventional messages, handling of the remains
6112 depends on the execution mode.
6113 No special handling of compressed files is performed.
6115 In interactive mode the user is consecutively asked for the filenames of
6116 the processed parts.
6117 For convience saving of each part may be skipped by giving an empty
6118 value, the same result as writing it to
6120 Shell piping the part content by specifying a leading vertical bar
6122 character for the filename is supported.
6123 Other user input undergoes the usual
6124 .Sx "Filename transformations" ,
6125 and contents of the destination file are overwritten if the file
6128 \*(ID In non-interactive mode any part which does not specify a filename
6129 is ignored, and suspicious parts of filenames of the remaining parts are
6130 URL percent encoded (as via
6132 to prevent injection of malicious character sequences, resulting in
6133 a filename that will be written into the current directory.
6134 Existing files will not be overwritten, instead the part number or
6135 a dot are appended after a number sign
6137 to the name until file creation succeeds (or fails due to other
6142 \*(NQ This command works only inside of a
6144 ed macro: the sole difference to
6146 is that the new macro is executed in place of the current one, which
6147 will not regain control; all resources of the current macro will be
6148 released before control is given to the replacer.
6157 \*(NQ \*(UA presents message headers in
6159 fuls as described under the
6162 Without arguments this command scrolls to the next window of messages,
6163 likewise if the argument is
6167 scrolls to the last,
6169 scrolls to the first, and
6174 A number argument prefixed by
6178 indicates that the window is calculated in relation to the current
6179 position, and a number without a prefix specifies an absolute position.
6185 but scrolls to the next or previous window that contains at least one
6195 .\" .Sh COMMAND ESCAPES {{{
6196 .Sh "COMMAND ESCAPES"
6198 Here is a summary of the command escapes available in compose mode,
6199 which are used to perform special functions when composing messages.
6200 Command escapes are only recognized at the beginning of lines.
6201 The actual escape character can be set via the internal variable
6203 it defaults to the tilde
6207 .Bl -tag -width ".It Ic BaNg"
6210 Insert the string of text in the message prefaced by a single
6212 (If the escape character has been changed,
6213 that character must be doubled
6214 in order to send it at the beginning of a line.)
6217 .It Ic ~! Ar command
6218 Execute the indicated shell
6220 which follows, replacing unescaped exclamation marks with the previously
6221 executed command if the internal variable
6223 is set, then return to the message.
6227 Same effect as typing the end-of-file character.
6230 .It Ic ~: Ar \*(UA-command Ns \0or Ic ~_ Ar \*(UA-command
6231 Execute the given \*(UA command.
6232 Not all commands, however, are allowed.
6236 Write a summary of command escapes.
6239 .It Ic ~< Ar filename
6244 .It Ic ~<! Ar command
6246 is executed using the shell.
6247 Its standard output is inserted into the message.
6250 .It Ic ~@ Op Ar filename...
6251 Append or edit the list of attachments.
6254 arguments is expected (see
6255 .Sx "Shell-style argument quoting" ;
6256 any token-separating commas are ignored), to be
6257 interpreted as documented for the command line option
6259 with the message number exception as below.
6262 arguments the attachment list is edited, entry by entry;
6263 if a filename is left empty, that attachment is deleted from the list;
6264 once the end of the list is reached either new attachments may be
6265 entered or the session can be quit by committing an empty
6268 For each mode, if a given file name solely consists of the number sign
6270 followed by a valid message number of the currently active mailbox, then
6271 the given message is attached as a MIME
6273 part (note the number sign is the comment character and must be quoted).
6277 Inserts the string contained in the
6280 .Ql Ic ~i Ns \0Sign ) .
6285 ting the variable(s) instead!) The escape sequences tabulator
6293 Inserts the string contained in the
6296 .Ql Ic ~i Ns \0sign ) .
6301 ting the variable(s) instead!) The escape sequences tabulator
6308 .It Ic ~b Ar name ...
6309 Add the given names to the list of blind carbon copy recipients.
6312 .It Ic ~c Ar name ...
6313 Add the given names to the list of carbon copy recipients.
6317 Read the file specified by the
6319 variable into the message.
6323 Invoke the text editor on the message collected so far.
6324 After the editing session is finished,
6325 the user may continue appending text to the message.
6328 .It Ic ~F Ar messages
6329 Read the named messages into the message being sent, including all
6330 message headers and MIME parts.
6331 If no messages are specified, read in the current message.
6334 .It Ic ~f Ar messages
6335 Read the named messages into the message being sent.
6336 If no messages are specified, read in the current message.
6337 Strips down the list of header fields according to the
6339 white- and blacklist selection of
6341 For MIME multipart messages,
6342 only the first displayable part is included.
6346 Edit the message header fields
6351 by typing each one in turn and allowing the user to edit the field.
6352 The default values for these fields originate from the
6360 Edit the message header fields
6366 by typing each one in turn and allowing the user to edit the field.
6369 .It Ic ~i Ar variable
6370 Insert the value of the specified variable into the message,
6371 adding a newline character at the end.
6372 The message remains unaltered if the variable is unset or empty.
6377 ting the variable(s) instead!) The escape sequences tabulator
6384 .It Ic ~M Ar messages
6385 Read the named messages into the message being sent,
6388 If no messages are specified, read the current message.
6391 .It Ic ~m Ar messages
6392 Read the named messages into the message being sent,
6395 If no messages are specified, read the current message.
6396 Strips down the list of header fields according to the
6398 white- and blacklist selection of
6400 For MIME multipart messages,
6401 only the first displayable part is included.
6405 Display the message collected so far,
6406 prefaced by the message header fields
6407 and followed by the attachment list, if any.
6411 Abort the message being sent,
6412 copying it to the file specified by the
6419 .It Ic ~R Ar filename
6422 but indent each line that has been read by
6426 .It Ic ~r Ar filename Op Ar HERE-delimiter
6427 Read the named file into the message.
6429 can also be a hyphen-minus
6431 in which case standard input is used, e.g., for pasting purposes.
6432 Only in this latter mode
6434 may be given: if it is data will be read in until the given
6436 is seen on a line by itself, and encountering EOF is an error; the
6438 is a required argument in non-interactive mode;
6439 note that variables expansion is performed on the delimiter.
6443 Cause the named string to become the current subject field.
6444 Newline (NL) and carriage-return (CR) bytes are invalid and will be
6445 normalized to space (SP) characters.
6448 .It Ic ~t Ar name ...
6449 Add the given name(s) to the direct recipient list.
6452 .It Ic ~U Ar messages
6453 Read in the given / current message(s) excluding all headers, indented by
6457 .It Ic ~u Ar messages
6458 Read in the given / current message(s), excluding all headers.
6462 Invoke an alternate editor (defined by the
6464 environment variable) on the message collected so far.
6465 Usually, the alternate editor will be a screen editor.
6466 After the editor is quit,
6467 the user may resume appending text to the end of the message.
6470 .It Ic ~w Ar filename
6471 Write the message onto the named file.
6473 the message is appended to it.
6479 except that the message is not saved at all.
6482 .It Ic ~| Ar command
6483 Pipe the message through the specified filter command.
6484 If the command gives no output or terminates abnormally,
6485 retain the original text of the message.
6488 is often used as a rejustifying filter.
6492 .It Ic ~^ Ar cmd Op Ar subcmd Op Ar arg3 Op Ar arg4
6493 Low-level command ment for scripted message access, i.e., for
6494 .Va on-compose-splice-shell
6496 .Va on-compose-splice .
6497 The used protocol is likely subject to changes, and therefore the
6498 mentioned hooks receive the used protocol version as an initial line.
6499 In general the first field of a response line represents a status code
6500 which specifies whether a command was successful or not, whether result
6501 data is to be expected, and if, the format of the result data.
6502 The status codes are:
6505 .Bl -tag -compact -width _210_
6507 Status ok; the remains of the line are the result.
6509 Status ok; the rest of the line is optionally used for more status.
6510 What follows are lines of result addresses, terminated by an empty line.
6511 The address lines consist of two fields, the first of which is the
6512 plain address, e.g.,
6514 separated by a single ASCII SP space from the second which contains the
6515 unstripped address, even if that is identical to the first field, e.g.,
6516 .Ql (Lovely) Bob <bob@exam.ple> .
6518 Status ok; the rest of the line is optionally used for more status.
6519 What follows are lines of furtherly unspecified string content,
6520 terminated by an empty line.
6521 (All the input, including the empty line, must be consumed before
6522 further commands can be issued.)
6524 Syntax error; invalid command.
6526 Syntax error in parameters or arguments.
6528 Error: an argument fails verification.
6529 For example an invalid address has been specified.
6531 Error: an otherwise valid argument is rendered invalid due to context.
6532 For example, a second address is added to a header which may consist of
6533 a single address only.
6537 If a command indicates failure then the message will have remained
6539 Most commands can fail with
6541 if required arguments are missing (false command usage).
6542 The following commands are supported, and, as usual, case-insensitive:
6545 .Bl -hang -width header
6547 This command allows listing, inspection, and editing of message headers.
6548 The second argument specifies the subcommand to apply, one of:
6551 .Bl -hang -compact -width remove
6553 Without a third argument a list of all yet existing headers is given via
6555 this command is the default command of
6557 if no second argument has been given.
6558 A third argument restricts output to the given header only, which may
6561 if no such field is defined.
6564 Shows the content of the header given as the third argument.
6565 Dependent on the header type this may respond with
6569 any failure results in
6573 This will remove all instances of the header given as the third
6578 if no such header can be found.
6581 Create a new or an additional instance of the header given in the third
6582 argument, with the header body content as given in the fourth argument
6583 (the remains of the line).
6586 if the third argument specifies a free-form header field name that is
6587 invalid, or if body content extraction fails to succeed,
6589 if any extracted address does not pass syntax and/or security checks, and
6591 to indicate prevention of excessing a single-instance header \(em note that
6593 can be appended to (a space separator will be added automatically first).
6595 is returned upon success.
6600 This command allows listing, removal and addition of message attachments.
6601 The second argument specifies the subcommand to apply, one of:
6604 .Bl -hang -compact -width remove
6606 List all attachments via
6610 if no attachments exist.
6611 This command is the default command of
6613 if no second argument has been given.
6616 This will remove the attachment given as the third argument, and report
6620 if no such attachment can be found.
6621 If there exists any path component in the given argument, then an exact
6622 match of the path which has been used to create the attachment is used
6623 directly, but if only the basename of that path matches then all
6624 attachments are traversed to find an exact match first, and the removal
6625 occurs afterwards; if multiple basenames match, a
6628 Message attachments are treated as absolute pathnames.
6630 If no path component exists in the given argument, then all attachments
6631 will be searched for
6633 parameter matches as well as for matches of the basename of the path
6634 which has been used when the attachment has been created; multiple
6639 This will interpret the third argument as a number and remove the
6640 attachment at that list position (counting from one!), reporting
6644 if the argument is not a number or
6646 if no such attachment exists.
6649 Adds the attachment given as the third argument, specified exactly as
6650 documented for the command line option
6652 and supporting the message number extension as documented for
6656 upon success, with the index of the new attachment following,
6658 if the given file cannot be opened,
6660 if an on-the-fly performed character set conversion fails, otherwise
6662 is reported; this is also reported if character set conversion is
6663 requested but not available.
6666 This uses the same search mechanism as described for
6668 and prints any known attributes of the first found attachment via
6672 if no such attachment can be found.
6673 The attributes are written as lines of keyword and value tuples, the
6674 keyword being separated from the rest of the line with an ASCII SP space
6678 This uses the same search mechanism as described for
6680 and is otherwise identical to
6683 .It Ar attribute-set
6684 This uses the same search mechanism as described for
6686 and will assign the attribute given as the fourth argument, which is
6687 expected to be a value tuple of keyword and other data, separated by
6688 a ASCII SP space or TAB tabulator character.
6689 If the value part is empty, then the given attribute is removed, or
6690 reset to a default value if existence of the attribute is crucial.
6693 upon success, with the index of the found attachment following,
6695 for message attachments or if the given keyword is invalid, and
6697 if no such attachment can be found.
6698 The following keywords may be used (case-insensitively):
6700 .Bl -hang -compact -width ".Ql filename"
6702 Sets the filename of the MIME part, i.e., the name that is used for
6703 display and when (suggesting a name for) saving (purposes).
6704 .It Ql content-description
6705 Associate some descriptive information to the attachment's content, used
6706 in favour of the plain filename by some MUAs.
6708 May be used for uniquely identifying MIME entities in several contexts;
6709 this expects a special reference address format as defined in RFC 2045
6712 upon address content verification failure.
6714 Specifies the media type and subtype of the part; managed automatically.
6715 .It Ql content-disposition
6716 Automatically set to the string
6720 .It Ar attribute-set-at
6721 This uses the same search mechanism as described for
6723 and is otherwise identical to
6733 .\" .Sh INTERNAL VARIABLES {{{
6734 .Sh "INTERNAL VARIABLES"
6736 Internal \*(UA variables are controlled via the
6740 commands; prefixing a variable name with the string
6744 has the same effect as using
6750 Creation or editing of variables can be performed in the
6755 will give more insight on the given variable(s), and
6757 when called without arguments, will show a listing of all variables.
6758 Both commands support a more
6761 Some well-known variables will also become inherited from the
6764 implicitly, others can be explicitly imported with the command
6766 and henceforth share said properties.
6769 Two different kind of internal variables exist.
6770 There are boolean variables, which can only be in one of the two states
6774 and value variables with a(n optional) string value.
6775 For the latter proper quoting is necessary upon assignment time, the
6776 introduction of the section
6778 documents the supported quoting rules.
6780 .Bd -literal -offset indent
6781 wysh set one=val\e 1 two="val 2" \e
6782 three='val "3"' four=$'val \e'4\e''; \e
6783 varshow one two three four; \e
6784 unset one two three four
6788 Dependent upon the actual option the string values will be interpreted
6789 as numbers, colour names, normal text etc., but there also exists
6790 a special kind of string value, the
6791 .Dq boolean string ,
6792 which must either be a decimal integer (in which case
6796 and any other value is true) or any of the (case-insensitive) strings
6802 for a false boolean and
6808 for a true boolean; a special kind of boolean string is the
6810 which is a boolean string that can optionally be prefixed with the
6811 (case-insensitive) term
6815 which causes prompting of the user in interactive mode, with the given
6816 boolean as the default value.
6818 .\" .Ss "Initial settings" {{{
6819 .\" (Keep in SYNC: ./nail.h:okeys, ./nail.rc, ./nail.1:"Initial settings")
6820 .Ss "Initial settings"
6822 The standard POSIX 2008/Cor 2-2016 mandates the following initial
6828 .Pf no Va autoprint ,
6842 .Pf no Va ignoreeof ,
6844 .Pf no Va keepsave ,
6846 .Pf no Va outfolder ,
6854 .Pf no Va sendwait ,
6863 Notes: \*(UA does not support the
6865 variable \(en use command line options or
6867 to pass options through to a
6869 And the default global
6871 file, which is loaded unless the
6873 (with according argument) or
6875 command line options have been used, or the
6876 .Ev MAILX_NO_SYSTEM_RC
6877 environment variable is set (see
6878 .Sx "Resource files" )
6879 bends those initial settings a bit, e.g., it sets the variables
6884 to name a few, establishes a default
6886 selection etc., and should thus be taken into account.
6889 .\" .Ss "Variables" {{{
6892 .Bl -tag -width ".It Va BaNg"
6896 \*(RO The exit status of the last command, or the
6901 This status has a meaning in the state machine: in conjunction with
6903 any non-0 exit status will cause a program exit, and in
6905 mode any error while loading (any of the) resource files will have the
6909 .Sx "Command modifiers" ,
6910 can be used to instruct the state machine to ignore errors.
6914 \*(RO The current error number
6915 .Pf ( Xr errno 3 ) ,
6916 which is set after an error occurred; it is also available via
6918 and the error name and documentation string can be queried via
6922 \*(ID This machinery is new and the error number is only really usable
6923 if a command explicitly states that it manages the variable
6925 for others errno will be used in case of errors, or
6927 if that is 0: it thus may or may not reflect the real error.
6928 The error number may be set with the command
6934 \*(RO This is a multiplexer variable which performs dynamic expansion of
6935 the requested state or condition, of which there are:
6938 .Bl -tag -compact -width ".It Va BaNg"
6942 .It Va ^ERR , ^ERRDOC , ^ERRNAME
6943 The number, documentation, and name of the current
6945 respectively, which is usually set after an error occurred.
6946 \*(ID This machinery is new and is usually reliable only if a command
6947 explicitly states that it manages the variable
6949 which is effectively identical to
6951 Each of those variables can be suffixed with a hyphen minus followed by
6952 a name or number, in which case the expansion refers to the given error.
6953 Note this is a direct mapping of (a subset of) the system error values:
6954 .Bd -literal -offset indent
6956 eval echo \e$1: \e$^ERR-$1: \e$^ERRNAME-$1: \e$^ERRDOC-$1
6957 vput vexpr i + "$1" 1
6969 \*(RO Only available inside the scope of a
6971 ed macro, this will expand to all parameters of the macro, separated by
6973 \*(ID The special semantics of the equally named special parameter of the
6975 are not yet supported.
6979 \*(RO Only available inside the scope of a
6981 ed macro, this will expand to all parameters of the macro, separated by
6983 \*(ID The special semantics of the equally named special parameter of the
6985 are not yet supported.
6989 \*(RO Only available inside the scope of a
6991 ed macro, this will expand to the number of positional parameters in
6996 \*(RO Available inside the scope of a
7000 ed macro, this expands to the name of the calling macro, or to the empty
7001 string if the macro is running from top-level.
7002 For the \*(OPal regular expression search and replace operator of
7004 this expands to the entire matching expression.
7008 \*(RO Available inside the scope of a
7012 ed macro, this will access the first positional parameter passed.
7013 All further parameters can be accessed with this syntax, too, e.g.,
7016 etc.; positional parameters can be shifted off the stack by calling
7018 Positional parameters are also accessible in the \*(OPal regular
7019 expression search and replace expression of
7024 \*(RO Is set to the active
7028 .It Va add-file-recipients
7029 \*(BO When file or pipe recipients have been specified,
7030 mention them in the corresponding address fields of the message instead
7031 of silently stripping them from their recipient list.
7032 By default such addressees are not mentioned.
7036 \*(BO Causes only the local part to be evaluated
7037 when comparing addresses.
7041 \*(RO Is set to the list of
7046 \*(BO Causes messages saved in the
7048 .Sx "secondary mailbox"
7050 to be appended to the end rather than prepended.
7051 This should always be set.
7055 \*(BO Causes \*(UA to prompt for the subject of each message sent.
7056 If the user responds with simply a newline,
7057 no subject field will be sent.
7061 \*(BO Causes the prompts for
7065 lists to appear after the message has been edited.
7069 \*(BO If set, \*(UA asks for files to attach at the end of each message,
7070 shall the list be found empty at that time.
7071 An empty line finalizes the list.
7075 \*(BO Causes the user to be prompted for carbon copy recipients
7076 (at the end of each message if
7080 are set) shall the list be found empty (at that time).
7081 An empty line finalizes the list.
7085 \*(BO Causes the user to be prompted for blind carbon copy
7086 recipients (at the end of each message if
7090 are set) shall the list be found empty (at that time).
7091 An empty line finalizes the list.
7095 \*(BO\*(OP Causes the user to be prompted if the message is to be
7096 signed at the end of each message.
7099 variable is ignored when this variable is set.
7103 \*(BO Alternative name for
7108 A sequence of characters to display in the
7112 as shown in the display of
7114 each for one type of messages (see
7115 .Sx "Message states" ) ,
7116 with the default being
7119 .Ql NU\ \ *HMFAT+\-$~
7122 variable is set, in the following order:
7124 .Bl -tag -compact -width ".It Ql _"
7146 start of a collapsed thread.
7148 an uncollapsed thread (TODO ignored for now).
7152 classified as possible spam.
7158 Specifies a list of recipients to which a blind carbon copy of each
7159 outgoing message will be sent automatically.
7163 Specifies a list of recipients to which a carbon copy of each outgoing
7164 message will be sent automatically.
7168 \*(BO Causes threads to be collapsed automatically when threaded mode
7175 \*(BO Enable automatic
7177 ing of a(n existing)
7183 commands, e.g., the message that becomes the new
7185 is shown automatically, as via
7192 \*(BO\*(OB Causes threaded mode (see the
7194 command) to be entered automatically when a folder is opened.
7196 .Ql autosort=thread .
7200 Causes sorted mode (see the
7202 command) to be entered automatically with the value of this variable as
7203 sorting method when a folder is opened, e.g.,
7204 .Ql set autosort=thread .
7208 \*(BO Enables the substitution of all not (reverse-solidus) escaped
7211 characters by the contents of the last executed command for the
7213 shell escape command and
7215 one of the compose mode
7216 .Sx "COMMAND ESCAPES" .
7217 If this variable is not set no reverse solidus stripping is performed.
7220 .It Va batch-exit-on-error
7221 \*(OB\*(BO Predecessor of
7226 \*(OP Terminals generate multi-byte sequences for certain forms of
7227 input, for example for function and other special keys.
7228 Some terminals however do not write these multi-byte sequences as
7229 a whole, but byte-by-byte, and the latter is what \*(UA actually reads.
7230 This variable specifies the timeout in milliseconds that the MLE (see
7231 .Sx "On terminal control and line editor" )
7232 waits for more bytes to arrive unless it considers a sequence
7238 \*(BO Causes automatic display of a header summary after executing a
7240 command, and thus complements the standard variable
7242 which controls header summary display on program startup.
7243 It is only meaningful if
7249 \*(BO Sets some cosmetical features to traditional BSD style;
7250 has the same affect as setting
7252 and all other variables prefixed with
7254 it also changes the behaviour of
7256 (which does not exist in BSD).
7260 \*(BO Changes the letters shown in the first column of a header
7261 summary to traditional BSD style.
7265 \*(BO Changes the display of columns in a header summary to traditional
7270 \*(BO Changes some informational messages to traditional BSD style.
7276 field to appear immediately after the
7278 field in message headers and with the
7280 .Sx "COMMAND ESCAPES" .
7284 The value that should appear in the
7288 MIME header fields when no character set conversion of the message data
7290 This defaults to US-ASCII, and the chosen character set should be
7291 US-ASCII compatible.
7295 \*(OP The default 8-bit character set that is used as an implicit last
7296 member of the variable
7298 This defaults to UTF-8 if character set conversion capabilities are
7299 available, and to ISO-8859-1 otherwise, in which case the only supported
7302 and this variable is effectively ignored.
7303 Refer to the section
7304 .Sx "Character sets"
7305 for the complete picture of character set conversion in \*(UA.
7308 .It Va charset-unknown-8bit
7309 \*(OP RFC 1428 specifies conditions when internet mail gateways shall
7311 the content of a mail message by using a character set with the name
7313 Because of the unclassified nature of this character set \*(UA will not
7314 be capable to convert this character set to any other character set.
7315 If this variable is set any message part which uses the character set
7317 is assumed to really be in the character set given in the value,
7318 otherwise the (final) value of
7320 is used for this purpose.
7322 This variable will also be taken into account if a MIME type (see
7323 .Sx "The mime.types files" )
7324 of a MIME message part that uses the
7326 character set is forcefully treated as text.
7330 The default value for the
7335 .It Va colour-disable
7336 \*(BO\*(OP Forcefully disable usage of colours.
7337 Also see the section
7338 .Sx "Coloured display" .
7342 \*(BO\*(OP Whether colour shall be used for output that is paged through
7344 Note that pagers may need special command line options, e.g.,
7352 in order to support colours.
7353 Often doing manual adjustments is unnecessary since \*(UA may perform
7354 adjustments dependent on the value of the environment variable
7356 (see there for more).
7360 In a(n interactive) terminal session, then if this valued variable is
7361 set it will be used as a threshold to determine how many lines the given
7362 output has to span before it will be displayed via the configured
7366 can be forced by setting this to the value
7368 setting it without a value will deduce the current height of the
7369 terminal screen to compute the treshold (see
7374 \*(ID At the moment this uses the count of lines of the message in wire
7375 format, which, dependent on the
7377 of the message, is unrelated to the number of display lines.
7378 (The software is old and historically the relation was a given thing.)
7382 Define a set of custom headers to be injected into newly composed or
7383 forwarded messages; it is also possible to create custom headers in
7386 which can be automated by setting one of the hooks
7387 .Va on-compose-splice-shell
7389 .Va on-compose-splice .
7390 The value is interpreted as a comma-separated list of custom headers to
7391 be injected, to include commas in the header bodies escape them with
7393 \*(ID Overwriting of automatically managed headers is neither supported
7396 .Dl set customhdr='Hdr1: Body1-1\e, Body1-2, Hdr2: Body2'
7400 Controls the appearance of the
7402 date and time format specification of the
7404 variable, that is used, for example, when viewing the summary of
7406 If unset, then the local receiving date is used and displayed
7407 unformatted, otherwise the message sending
7409 It is possible to assign a
7411 format string and control formatting, but embedding newlines via the
7413 format is not supported, and will result in display errors.
7415 .Ql %Y-%m-%d %H:%M ,
7417 .Va datefield-markout-older .
7420 .It Va datefield-markout-older
7421 Only used in conjunction with
7423 Can be used to create a visible distinction of messages dated more than
7424 a day in the future, or older than six months, a concept comparable to the
7426 option of the POSIX utility
7428 If set to the empty string, then the plain month, day and year of the
7430 will be displayed, but a
7432 format string to control formatting can be assigned.
7438 \*(BO Enables debug messages and obsoletion warnings, disables the
7439 actual delivery of messages and also implies
7445 .It Va disposition-notification-send
7447 .Ql Disposition-Notification-To:
7448 header (RFC 3798) with the message.
7452 .\" TODO .It Va disposition-notification-send-HOST
7454 .\".Va disposition-notification-send
7455 .\" for SMTP accounts on a specific host.
7456 .\" TODO .It Va disposition-notification-send-USER@HOST
7458 .\".Va disposition-notification-send
7459 .\"for a specific account.
7463 \*(BO When dot is set, a period
7465 on a line by itself during message input in (interactive) compose mode
7466 will be treated as end-of-message (in addition to the normal end-of-file
7475 .It Va dotlock-ignore-error
7476 \*(BO\*(OP Synchronization of mailboxes which \*(UA treats as
7478 .Sx "primary system mailbox" Ns
7479 es (see, e.g., the notes on
7480 .Sx "Filename transformations" ,
7481 as well as the documentation of
7483 will be protected with so-called dotlock files\(emthe traditional mail
7484 spool file locking method\(emin addition to system file locking.
7485 Because \*(UA ships with a privilege-separated dotlock creation program
7486 that should always be able to create such a dotlock file there is no
7487 good reason to ignore dotlock file creation errors, and thus these are
7488 fatal unless this variable is set.
7492 \*(BO If this variable is set then the editor is started automatically
7493 when a message is composed in interactive mode, as if the
7495 .Sx "COMMAND ESCAPES"
7499 variable is implied for this automatically spawned editor session.
7503 \*(BO When a message is edited while being composed,
7504 its header is included in the editable text.
7514 fields are accepted within the header, other fields are ignored.
7518 \*(BO When entering interactive mode \*(UA normally writes
7519 .Dq \&No mail for user
7520 and exits immediately if a mailbox is empty or does not exist.
7521 If this variable is set \*(UA starts even with an empty or nonexistent
7522 mailbox (the latter behaviour furtherly depends upon
7529 .Ql Content-Transfer-Encoding
7530 to use in outgoing text messages and message parts, where applicable.
7531 (7-bit clean text messages are sent as-is, without a transfer encoding.)
7534 .Bl -tag -compact -width "_%%_"
7537 8-bit transport effectively causes the raw data be passed through
7538 unchanged, but may cause problems when transferring mail messages over
7539 channels that are not ESMTP (RFC 1869) compliant.
7540 Also, several input data constructs are not allowed by the
7541 specifications and may cause a different transfer-encoding to be used.
7542 .It Ql quoted-printable
7544 Quoted-printable encoding is 7-bit clean and has the property that ASCII
7545 characters are passed through unchanged, so that an english message can
7546 be read as-is; it is also acceptible for other single-byte locales that
7547 share many characters with ASCII, like, e.g., ISO-8859-1.
7548 The encoding will cause a large overhead for messages in other character
7549 sets: e.g., it will require up to twelve (12) bytes to encode a single
7550 UTF-8 character of four (4) bytes.
7552 .Pf (Or\0 Ql b64 . )
7553 The default encoding, it is 7-bit clean and will always be used for
7555 This encoding has a constant input:output ratio of 3:4, regardless of
7556 the character set of the input data it will encode three bytes of input
7557 to four bytes of output.
7558 This transfer-encoding is not human readable without performing
7564 \*(BO Let each command with a non-0 exit status, including every
7568 s a non-0 status, cause a program exit unless prefixed by
7571 .Sx "Command modifiers" ) ;
7572 please refer to the variable
7574 for more on this topic.
7578 If defined, the first character of the value of this variable
7579 gives the character to use in place of tilde
7582 .Sx "COMMAND ESCAPES" .
7583 If set to the empty string, command escapes are disabled.
7587 If not set then file and command pipeline targets are not allowed,
7588 and any such address will be filtered out, giving a warning message.
7589 If set without a value then all possible recipient address
7590 specifications will be accepted \(en see the section
7591 .Sx "On sending mail, and non-interactive mode"
7593 To accept them, but only in interactive mode, or when tilde commands
7594 were enabled explicitly by using one of the command line options
7598 set this to the (case-insensitive) value
7600 (it actually acts like
7601 .Ql restrict,-all,+name,+addr ,
7602 so that care for ordering issues must be taken) .
7604 In fact the value is interpreted as a comma-separated list of values.
7607 then the existence of disallowed specifications is treated as a hard
7608 send error instead of only filtering them out.
7609 The remaining values specify whether a specific type of recipient
7610 address specification is allowed (optionally indicated by a plus sign
7612 prefix) or disallowed (prefixed with a hyphen-minus
7616 addresses all possible address specifications,
7620 command pipeline targets,
7622 plain user names and (MTA) aliases (\*(OB
7624 may be used as an alternative syntax to
7629 These kind of values are interpreted in the given order, so that
7630 .Ql restrict,\:fail,\:+file,\:-all,\:+addr
7631 will cause hard errors for any non-network address recipient address
7632 unless \*(UA is in interactive mode or has been started with the
7636 command line option; in the latter case(s) any address may be used, then.
7638 Historically invalid network addressees are silently stripped off.
7639 To change this and ensure that any encountered invalid email address
7640 instead causes a hard error, ensure the string
7642 is an entry in the above list.
7643 Setting this automatically enables network addressees
7644 (it actually acts like
7645 .Ql failinvaddr,+addr ,
7646 so that care for ordering issues must be taken) .
7650 Unless this variable is set additional
7652 (Mail-Transfer-Agent)
7653 arguments from the command line, as can be given after a
7655 separator, are ignored due to safety reasons.
7656 However, if set to the special (case-insensitive) value
7658 then the presence of additional MTA arguments is treated as a hard
7659 error that causes \*(UA to exit with failure status.
7660 A lesser strict variant is the otherwise identical
7662 which does accept such arguments in interactive mode, or if tilde
7663 commands were enabled explicitly by using one of the command line options
7670 \*(RO String giving a list of features \*(UA, preceded with a plus sign
7672 if the feature is available, and a hyphen-minus
7675 The output of the command
7677 will include this information.
7681 \*(BO This setting reverses the meanings of a set of reply commands,
7682 turning the lowercase variants, which by default address all recipients
7683 included in the header of a message
7684 .Pf ( Ic reply , respond , followup )
7685 into the uppercase variants, which by default address the sender only
7686 .Pf ( Ic Reply , Respond , Followup )
7689 .Ic replysender , respondsender , followupsender
7691 .Ic replyall , respondall , followupall
7692 are not affected by the current setting of
7697 .It Va file-hook-load-EXTENSION , file-hook-save-EXTENSION
7698 It is possible to install file hooks which will be used by the
7700 command in order to be able to transparently handle (through an
7701 intermediate temporary file) files with specific
7703 s: the variable values can include shell snippets and are expected to
7704 write data to standard output / read data from standard input,
7706 \*(ID The variables may not be changed while there is a mailbox
7708 .Bd -literal -offset indent
7709 set file-hook-load-xy='echo >&2 XY-LOAD; gzip -cd' \e
7710 file-hook-save-xy='echo >&2 XY-SAVE; gzip -c' \e
7711 record=+null-sent.xy
7716 The default path under which mailboxes are to be saved:
7717 file names that begin with the plus sign
7719 will have the plus sign replaced with the value of this variable if set,
7720 otherwise the plus sign will remain unchanged when doing
7721 .Sx "Filename transformations" ;
7724 for more on this topic.
7725 The value supports a subset of transformations itself, and if the
7726 non-empty value does not start with a solidus
7730 will be prefixed automatically.
7731 Once the actual value is evaluated first, the internal variable
7733 will be updated for caching purposes.
7737 This variable can be set to the name of a
7739 macro which will be called whenever a
7742 The macro will also be invoked when new mail arrives,
7743 but message lists for commands executed from the macro
7744 only include newly arrived messages then.
7746 are activated by default in a folder hook, causing the covered settings
7747 to be reverted once the folder is left again.
7750 Macro behaviour, including option localization, will change in v15.
7751 One should be aware of that and possibly embed version checks in the
7752 used resource file(s).
7755 .It Va folder-hook-FOLDER
7760 Unlike other folder specifications, the fully expanded name of a folder,
7761 without metacharacters, is used to avoid ambiguities.
7762 However, if the mailbox resides under
7766 specification is tried in addition, e.g., if
7770 (and thus relative to the user's home directory) then
7771 .Pa /home/usr1/mail/sent
7773 .Ql folder-hook-/home/usr1/mail/sent
7774 first, but then followed by
7775 .Ql folder-hook-+sent .
7778 .It Va folder-resolved
7779 \*(RO Set to the fully resolved path of
7781 once that evaluation has occurred; rather internal.
7785 \*(BO Controls whether a
7786 .Ql Mail-Followup-To:
7787 header is generated when sending messages to known mailing lists.
7789 .Va followup-to-honour
7791 .Ic mlist , mlsubscribe , reply
7796 .It Va followup-to-honour
7798 .Ql Mail-Followup-To:
7799 header is honoured when group-replying to a message via
7803 This is a quadoption; if set without a value it defaults to
7813 .It Va forward-as-attachment
7814 \*(BO Original messages are normally sent as inline text with the
7817 and only the first part of a multipart message is included.
7818 With this setting enabled messages are sent as unmodified MIME
7820 attachments with all of their parts included.
7824 The address (or a list of addresses) to put into the
7826 field of the message header, quoting RFC 5322:
7827 the author(s) of the message, that is, the mailbox(es) of the person(s)
7828 or system(s) responsible for the writing of the message.
7831 ing to messages these addresses are handled as if they were in the
7835 If the machine's hostname is not valid at the Internet (for example at
7836 a dialup machine) then either this variable or
7838 (\*(IN and with a defined SMTP protocol in
7841 adds even more fine-tuning capabilities),
7845 contains more than one address,
7848 variable is required (according to the standard RFC 5322).
7850 If a file-based MTA is used, then
7852 (or, if that contains multiple addresses,
7854 can nonetheless be enforced to appear as the envelope sender address at
7855 the MTA protocol level (the RFC 5321 reverse-path), either by using the
7857 command line option (with an empty argument; see there for the complete
7858 picture on this topic), or by setting the internal variable
7859 .Va r-option-implicit .
7863 \*(BO When replying to or forwarding a message \*(UA normally removes
7864 the comment and name parts of email addresses.
7865 If this variable is set such stripping is not performed,
7866 and comments, names etc. are retained.
7870 The string to put before the text of a message with the
7874 .Va forward-as-attachment
7877 .Dq -------- Original Message --------
7878 if unset; No heading is put if it is set to the empty string.
7882 \*(BO Causes the header summary to be written at startup and after
7883 commands that affect the number of messages or the order of messages in
7884 the current folder; enabled by default.
7885 The command line option
7891 complements this and controls header summary display on folder changes.
7896 A format string to use for the summary of
7898 similar to the ones used for
7901 Format specifiers in the given string start with a percent sign
7903 and may be followed by an optional decimal number indicating the field
7904 width \(em if that is negative, the field is to be left-aligned.
7905 Valid format specifiers are:
7908 .Bl -tag -compact -width "_%%_"
7910 A plain percent sign.
7913 a space character but for the current message
7915 for which it expands to
7919 a space character but for the current message
7921 for which it expands to
7924 \*(OP The spam score of the message, as has been classified via the
7927 Shows only a replacement character if there is no spam support.
7929 Message attribute character (status flag); the actual content can be
7933 The date found in the
7935 header of the message when
7937 is set (the default), otherwise the date when the message was received.
7938 Formatting can be controlled by assigning a
7943 The indenting level in threaded mode.
7945 The address of the message sender.
7947 The message thread tree structure.
7948 (Note that this format does not support a field width.)
7950 The number of lines of the message, if available.
7954 The number of octets (bytes) in the message, if available.
7956 Message subject (if any).
7958 Message subject (if any) in double quotes.
7960 Message recipient flags: is the addressee of the message a known or
7961 subscribed mailing list \(en see
7966 The position in threaded/sorted order.
7970 .Ql %>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s ,
7972 .Ql %>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S
7983 .It Va headline-bidi
7984 Bidirectional text requires special treatment when displaying headers,
7985 because numbers (in dates or for file sizes etc.) will not affect the
7986 current text direction, in effect resulting in ugly line layouts when
7987 arabic or other right-to-left text is to be displayed.
7988 On the other hand only a minority of terminals is capable to correctly
7989 handle direction changes, so that user interaction is necessary for
7991 Note that extended host system support is required nonetheless, e.g.,
7992 detection of the terminal character set is one precondition;
7993 and this feature only works in an Unicode (i.e., UTF-8) locale.
7995 In general setting this variable will cause \*(UA to encapsulate text
7996 fields that may occur when displaying
7998 (and some other fields, like dynamic expansions in
8000 with special Unicode control sequences;
8001 it is possible to fine-tune the terminal support level by assigning
8003 no value (or any value other than
8008 will make \*(UA assume that the terminal is capable to properly deal
8009 with Unicode version 6.3, in which case text is embedded in a pair of
8010 U+2068 (FIRST STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE)
8012 In addition no space on the line is reserved for these characters.
8014 Weaker support is chosen by using the value
8016 (Unicode 6.3, but reserve the room of two spaces for writing the control
8017 sequences onto the line).
8022 select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT MARK); the latter
8023 again reserves room for two spaces in addition.
8027 \*(OP If a line editor is available then this can be set to
8028 name the (expandable) path of the location of a permanent history file.
8033 .It Va history-gabby
8034 \*(BO\*(OP Add more entries to the history as is normally done.
8037 .It Va history-gabby-persist
8038 \*(BO\*(OP \*(UA's own MLE will not save the additional
8040 entries in persistent storage unless this variable is set.
8041 On the other hand it will not loose the knowledge of whether
8042 a persistent entry was gabby or not.
8048 \*(OP Setting this variable imposes a limit on the number of concurrent
8050 If set to the value 0 then no further history entries will be added, and
8051 loading and incorporation of the
8053 upon program startup can also be suppressed by doing this.
8054 Runtime changes will not be reflected, but will affect the number of
8055 entries saved to permanent storage.
8059 \*(BO This setting controls whether messages are held in the system
8061 and it is set by default.
8065 Use this string as hostname when expanding local addresses instead of
8066 the value obtained from
8070 It is used, e.g., in
8074 fields, as well as when generating
8076 MIME part related unique ID fields.
8077 Setting it to the empty string will cause the normal hostname to be
8078 used, but nonetheless enables creation of said ID fields.
8079 \*(IN in conjunction with the builtin SMTP
8082 also influences the results:
8083 one should produce some test messages with the desired combination of
8092 \*(BO\*(OP Can be used to turn off the automatic conversion of domain
8093 names according to the rules of IDNA (internationalized domain names
8095 Since the IDNA code assumes that domain names are specified with the
8097 character set, an UTF-8 locale charset is required to represent all
8098 possible international domain names (before conversion, that is).
8102 \*(BO Ignore interrupt signals from the terminal while entering
8103 messages; instead echo them as
8105 characters and discard the current line.
8109 \*(BO Ignore end-of-file conditions
8110 .Pf ( Ql control-D )
8111 in compose mode on message input and in interactive command input.
8112 If set an interactive command input session can only be left by
8113 explicitly using one of the commands
8117 and message input in compose mode can only be terminated by entering
8120 on a line by itself or by using the
8122 .Sx "COMMAND ESCAPES" ;
8124 overrides a setting of
8129 If this is set to a non-empty string it will specify the users
8131 .Sx "primary system mailbox" ,
8134 and the system-dependent default, and (thus) be used to replace
8137 .Sx "Filename transformations" ;
8140 for more on this topic.
8141 The value supports a subset of transformations itself.
8149 .Sx "COMMAND ESCAPES"
8152 option for indenting messages,
8153 in place of the normal tabulator character
8155 which is the default.
8156 Be sure to quote the value if it contains spaces or tabs.
8160 \*(BO If set, an empty
8162 .Sx "primary system mailbox"
8163 file is not removed.
8164 Note that, in conjunction with
8167 .Ev POSIXLY_CORRECT )
8168 any empty file will be removed unless this variable is set.
8169 This may improve the interoperability with other mail user agents
8170 when using a common folder directory, and prevents malicious users
8171 from creating fake mailboxes in a world-writable spool directory.
8172 \*(ID Only local regular (MBOX) files are covered, Maildir or other
8173 mailbox types will never be removed, even if empty.
8176 .It Va keep-content-length
8177 \*(BO When (editing messages and) writing MBOX mailbox files \*(UA can
8182 header fields that some MUAs generate by setting this variable.
8183 Since \*(UA does neither use nor update these non-standardized header
8184 fields (which in itself shows one of their conceptual problems),
8185 stripping them should increase interoperability in between MUAs that
8186 work with with same mailbox files.
8187 Note that, if this is not set but
8188 .Va writebackedited ,
8189 as below, is, a possibly performed automatic stripping of these header
8190 fields already marks the message as being modified.
8194 \*(BO When a message is saved it is usually discarded from the
8195 originating folder when \*(UA is quit.
8196 This setting causes all saved message to be retained.
8199 .It Va line-editor-disable
8200 \*(BO Turn off any enhanced line editing capabilities (see
8201 .Sx "On terminal control and line editor"
8205 .It Va line-editor-no-defaults
8206 \*(BO\*(OP Do not establish any default key binding.
8209 .It Va mailbox-display
8210 \*(RO The name of the current mailbox
8212 possibly abbreviated for display purposes.
8215 .It Va mailbox-resolved
8216 \*(RO The fully resolved path of the current mailbox.
8219 .It Va mailx-extra-rc
8220 An additional startup file that is loaded as the last of the
8221 .Sx "Resource files" .
8222 Use this file for commands that are not understood by other POSIX
8224 implementations, i.e., mostly anything which is not covered by
8225 .Sx "Initial settings" .
8229 \*(BO When a message is replied to and this variable is set,
8230 it is marked as having been
8233 .Sx "Message states" .
8237 \*(BO If this is set then when opening MBOX mailbox files \*(UA will not
8238 use the tolerant POSIX rules for detecting message boundaries (so-called
8240 lines), as it does by default for compatibility reasons, but the more
8241 strict rules that have been defined in RFC 4155.
8242 When saving to MBOX mailboxes this indicates when so-called
8244 quoting is to be applied \(em note this is never necessary for any
8245 message newly generated by \*(UA, it only applies to messages generated
8246 by buggy or malicious MUAs.
8247 (\*(UA will use a proper
8251 lines cannot be misinterpreted as message boundaries.)
8253 This should not be set normally, but may be handy when \*(UA complains
8254 about having seen invalid
8256 lines when opening a MBOX: in this case temporarily setting this
8257 variable, re-opening the mailbox in question, unsetting this variable
8258 again and then invoking
8259 .Ql copy * SOME-FILE
8260 will perform proper, POSIX-compliant
8262 quoting for all detected messages, resulting in a valid MBOX mailbox.
8266 \*(BO Internal development variable.
8269 .It Va message-id-disable
8270 \*(BO By setting this variable the generation of
8272 can be completely suppressed, effectively leaving this task up to the
8274 (Mail-Transfer-Agent) or the SMTP server.
8275 (According to RFC 5321 a SMTP server is not required to add this
8276 field by itself, so it should be ensured that it accepts messages without
8278 This variable also affects automatic generation of
8283 .It Va message-inject-head
8284 A string to put at the beginning of each new message.
8285 The escape sequences tabulator
8292 .It Va message-inject-tail
8293 A string to put at the end of each new message.
8294 The escape sequences tabulator
8302 \*(BO Usually, when an
8304 expansion contains the sender, the sender is removed from the expansion.
8305 Setting this option suppresses these removals.
8310 option to be passed through to the
8312 (Mail-Transfer-Agent); though most of the modern MTAs no longer document
8313 this flag, no MTA is known which does not support it (for historical
8317 .It Va mime-allow-text-controls
8318 \*(BO When sending messages, each part of the message is MIME-inspected
8319 in order to classify the
8322 .Ql Content-Transfer-Encoding:
8325 that is required to send this part over mail transport, i.e.,
8326 a computation rather similar to what the
8328 command produces when used with the
8332 This classification however treats text files which are encoded in
8333 UTF-16 (seen for HTML files) and similar character sets as binary
8334 octet-streams, forcefully changing any
8339 .Ql application/octet-stream :
8340 If that actually happens a yet unset charset MIME parameter is set to
8342 effectively making it impossible for the receiving MUA to automatically
8343 interpret the contents of the part.
8345 If this variable is set, and the data was unambiguously identified as
8346 text data at first glance (by a
8350 file extension), then the original
8352 will not be overwritten.
8355 .It Va mime-alternative-favour-rich
8356 \*(BO If this variable is set then rich MIME alternative parts (e.g.,
8357 HTML) will be preferred in favour of included plain text versions when
8358 displaying messages, provided that a handler exists which produces
8359 output that can be (re)integrated into \*(UA's normal visual display.
8360 (E.g., at the time of this writing some newsletters ship their full
8361 content only in the rich HTML part, whereas the plain text part only
8362 contains topic subjects.)
8365 .It Va mime-counter-evidence
8368 field is used to decide how to handle MIME parts.
8369 Some MUAs however do not use
8371 or a similar mechanism to correctly classify content, but simply specify
8372 .Ql application/octet-stream ,
8373 even for plain text attachments like
8375 If this variable is set then \*(UA will try to classify such MIME
8376 message parts on its own, if possible, for example via a possibly
8377 existing attachment filename.
8378 A non-empty value may also be given, in which case a number is expected,
8379 actually a carrier of bits.
8380 Creating the bit-carrying number is a simple addition:
8381 .Bd -literal -offset indent
8382 ? !echo Value should be set to $((2 + 4 + 8))
8383 Value should be set to 14
8386 .Bl -bullet -compact
8388 If bit two is set (2) then the detected
8390 content-type will be carried along with the message and be used for
8392 .Va pipe-TYPE/SUBTYPE
8393 is responsible for the MIME part, shall that question arise;
8394 when displaying such a MIME part the part-info will indicate the
8395 overridden content-type by showing a plus sign
8398 If bit three is set (4) then the counter-evidence is always produced
8399 and a positive result will be used as the MIME type, even forcefully
8400 overriding the parts given MIME type.
8402 If bit four is set (8) then as a last resort the actual content of
8403 .Ql application/octet-stream
8404 parts will be inspected, so that data which looks like plain text can be
8409 .It Va mimetypes-load-control
8410 Can be used to control which of the
8412 databases are loaded by \*(UA, as furtherly described in the section
8413 .Sx "The mime.types files" .
8416 is part of the option value, then the user's personal
8418 file will be loaded (if it exists); likewise the letter
8420 controls loading of the system wide
8421 .Pa /etc/mime.types ;
8422 directives found in the user file take precedence, letter matching is
8424 If this variable is not set \*(UA will try to load both files.
8425 Incorporation of the \*(UA-builtin MIME types cannot be suppressed,
8426 but they will be matched last (the order can be listed via
8429 More sources can be specified by using a different syntax: if the
8430 value string contains an equals sign
8432 then it is instead parsed as a comma-separated list of the described
8435 pairs; the given filenames will be expanded and loaded, and their
8436 content may use the extended syntax that is described in the section
8437 .Sx "The mime.types files" .
8438 Directives found in such files always take precedence (are prepended to
8439 the MIME type cache).
8444 To choose an alternate Mail-Transfer-Agent, set this option to either
8445 the full pathname of an executable (optionally prefixed with a
8447 protocol indicator), or \*(OPally a SMTP protocol URL, e.g., \*(IN
8449 .Dl smtps?://[user[:password]@]server[:port]
8452 .Ql [smtp://]server[:port] . )
8453 The default has been chosen at compie time.
8454 All supported data transfers are executed in child processes, which
8455 run asynchronously, and without supervision, unless either the
8460 If such a child receives a TERM signal, it will abort and
8467 For a file-based MTA it may be necessary to set
8469 in in order to choose the right target of a modern
8472 It will be passed command line arguments from several possible sources:
8475 if set, from the command line if given and the variable
8478 Argument processing of the MTA will be terminated with a
8483 The otherwise occurring implicit usage of the following MTA command
8484 line arguments can be disabled by setting the boolean variable
8485 .Va mta-no-default-arguments
8486 (which will also disable passing
8490 (for not treating a line with only a dot
8492 character as the end of input),
8500 variable is set); in conjunction with the
8502 command line option \*(UA will also (not) pass
8508 \*(OP \*(UA can send mail over SMTP network connections to a single
8509 defined SMTP smarthost, the access URL of which has to be assigned to
8511 To use this mode it is helpful to read
8512 .Sx "On URL syntax and credential lookup" .
8513 It may be necessary to set the
8515 variable in order to use a specific combination of
8520 with some mail providers.
8523 .Bl -bullet -compact
8525 The plain SMTP protocol (RFC 5321) that normally lives on the
8526 server port 25 and requires setting the
8527 .Va smtp-use-starttls
8528 variable to enter a SSL/TLS encrypted session state.
8529 Assign a value like \*(IN
8530 .Ql smtp://[user[:password]@]server[:port]
8532 .Ql smtp://server[:port] )
8533 to choose this protocol.
8535 The so-called SMTPS which is supposed to live on server port 465
8536 and is automatically SSL/TLS secured.
8537 Unfortunately it never became a standardized protocol and may thus not
8538 be supported by your hosts network service database
8539 \(en in fact the port number has already been reassigned to other
8542 SMTPS is nonetheless a commonly offered protocol and thus can be
8543 chosen by assigning a value like \*(IN
8544 .Ql smtps://[user[:password]@]server[:port]
8546 .Ql smtps://server[:port] ) ;
8547 due to the mentioned problems it is usually necessary to explicitly
8552 Finally there is the SUBMISSION protocol (RFC 6409), which usually
8553 lives on server port 587 and is practically identically to the SMTP
8554 protocol from \*(UA's point of view beside that; it requires setting the
8555 .Va smtp-use-starttls
8556 variable to enter a SSL/TLS secured session state.
8557 Assign a value like \*(IN
8558 .Ql submission://[user[:password]@]server[:port]
8560 .Ql submission://server[:port] ) .
8565 .It Va mta-arguments
8566 Arguments to pass through to a file-based
8568 can be given via this variable, which is parsed according to
8569 .Sx "Shell-style argument quoting"
8570 into an array of arguments, and which will be joined onto MTA options
8571 from other sources, and then passed individually to the MTA:
8573 .Dl wysh set mta-arguments='-t -X \&"/tmp/my log\&"'
8576 .It Va mta-no-default-arguments
8577 \*(BO Unless this variable is set \*(UA will pass some well known
8578 standard command line options to a file-based
8580 (Mail-Transfer-Agent), see there for more.
8584 Many systems use a so-called
8586 environment to ensure compatibility with
8588 This works by inspecting the name that was used to invoke the mail
8590 If this variable is set then the mailwrapper (the program that is
8591 actually executed when calling the file-based
8593 will treat its contents as that name.
8598 .It Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
8599 \*(BO\*(IN\*(OP Used to control usage of the users
8601 file for lookup of account credentials, as documented in the section
8602 .Sx "On URL syntax and credential lookup"
8606 .Sx "The .netrc file"
8607 documents the file format.
8619 then \*(UA will read the output of a shell pipe instead of the users
8621 file if this variable is set (to the desired shell command).
8622 This can be used to, e.g., store
8626 .Dl set netrc-pipe='gpg -qd ~/.netrc.pgp'
8630 If this variable has the value
8632 newly created local folders will be in Maildir format.
8636 Checks for new mail in the current folder each time the prompt is shown.
8637 A Maildir folder must be re-scanned to determine if new mail has arrived.
8638 If this variable is set to the special value
8640 then a Maildir folder will not be rescanned completely, but only
8641 timestamp changes are detected.
8645 .It Va on-compose-splice-shell , on-compose-splice
8646 These hooks run once the normal compose mode is finished, but before the
8647 .Va on-compose-leave
8648 macro hook is called, the
8651 Both hooks will be executed in a subprocess, with their input and output
8652 connected to \*(UA such that they can act as if they would be an
8654 The difference in between them is that the former is a
8656 command, whereas the latter is a normal \*(UA macro, but which is
8657 restricted to a small set of commands (the
8661 will indicate said capability), just enough for the purpose of
8662 controlling the real \*(UA instance sufficiently.
8664 are enabled for these hooks (in the parent process), causing any setting
8665 to be forgotten after the message has been sent.
8667 During execution of these hooks \*(UA will temporarily forget whether it
8668 has been started in interactive mode, (a restricted set of)
8669 .Sx "COMMAND ESCAPES"
8670 will always be available, and for guaranteed reproduceabilities sake
8672 will be set to its default.
8673 The compose mode command
8675 has been especially designed for scriptability (via these hooks).
8676 The first line the hook will read on its standard input is the protocol
8677 version of said command escape, currently
8679 backward incompatible protocol changes are to be expected in the
8680 future, and it is advisable to make use of the protocol version.
8681 Care must be taken to avoid deadlocks because of unexpected control
8682 flow: if both involved processes wait for more input to happen at the
8683 same time, or one doesn't expect more input but the other is stuck
8684 waiting for consumption of its output.
8685 .Bd -literal -offset indent
8686 wysh set on-compose-splice-shell=$'\e
8688 printf "hello $version! Headers: ";\e
8689 echo \e'~^header list\e';\e
8690 read status result;\e
8691 echo "status=$status result=$result";\e
8694 set on-compose-splice=ocsm
8697 echo Splice protocol version is $ver
8698 echo '~^h l'; read hl; vput vexpr es substr "${hl}" 0 1
8700 echoerr 'Cannot read header list'; echo '~x'
8702 if [ "$hl" !@ ' cc' ]
8703 echo '~^h i cc Diet is your <mirr.or>'; read es;\e
8704 vput vexpr es substr "${es}" 0 1
8706 echoerr 'Cannot insert Cc: header'; echo '~x'
8714 .It Va on-compose-enter , on-compose-leave
8715 Macro hooks which will be executed before compose mode is entered, and
8716 after composing has been finished (but before the
8718 is injected, etc.), respectively.
8720 are enabled for these hooks, causing any setting to be forgotten after
8721 the message has been sent.
8722 The following (read-only) variables will be set temporarily during
8723 execution of the macros:
8725 .Bl -tag -compact -width ".It Va compose_subject"
8728 .It Va compose-sender
8730 .It Va compose-to , compose-cc , compose-bcc
8731 The list of receiver addresses as a space-separated list.
8732 .It Va compose-subject
8738 \*(BO Causes the filename given in the
8741 and the sender-based filenames for the
8745 commands to be interpreted relative to the directory given in the
8747 variable rather than to the current directory,
8748 unless it is set to an absolute pathname.
8752 \*(BO If set, each message feed through the command given for
8754 is followed by a formfeed character
8758 .It Va password-USER@HOST , password-HOST , password
8759 \*(IN Variable chain that sets a password, which is used in case none has
8760 been given in the protocol and account-specific URL;
8761 as a last resort \*(UA will ask for a password on the user's terminal if
8762 the authentication method requires a password.
8763 Specifying passwords in a startup file is generally a security risk;
8764 the file should be readable by the invoking user only.
8766 .It Va password-USER@HOST
8767 \*(OU (see the chain above for \*(IN)
8768 Set the password for
8772 If no such variable is defined for a host,
8773 the user will be asked for a password on standard input.
8774 Specifying passwords in a startup file is generally a security risk;
8775 the file should be readable by the invoking user only.
8779 \*(BO Send messages to the
8781 command without performing MIME and character set conversions.
8785 .It Va pipe-TYPE/SUBTYPE
8786 When a MIME message part of type
8788 (case-insensitive) is displayed or quoted,
8789 its text is filtered through the value of this variable interpreted as
8793 forces interpretation of the message part as plain text, e.g.,
8794 .Ql set pipe-application/xml=@
8795 will henceforth display XML
8797 (The same could also be achieved by adding a MIME type marker with the
8800 And \*(OPally MIME type handlers may be defined via
8801 .Sx "The Mailcap files"
8802 \(em corresponding flag strings are shown in parenthesis below.)
8807 can in fact be used to adjust usage and behaviour of a following shell
8808 command specification by appending trigger characters to it, e.g., the
8809 following hypothetical command specification could be used:
8810 .Bd -literal -offset indent
8811 set pipe-X/Y='@*!++=@vim ${MAILX_FILENAME_TEMPORARY}'
8815 .Bl -tag -compact -width ".It Ql __"
8817 Simply by using the special
8819 prefix the MIME type (shell command) handler will only be invoked to
8820 display or convert the MIME part if the message is addressed directly
8821 and alone by itself.
8822 Use this trigger to disable this and always invoke the handler
8823 .Pf ( Cd x-mailx-always ) .
8826 If set the handler will not be invoked when a message is to be quoted,
8827 but only when it will be displayed
8828 .Pf ( Cd x-mailx-noquote ) .
8831 The command will be run asynchronously, i.e., without blocking \*(UA,
8832 which may be a handy way to display a, e.g., PDF file while also
8833 continuing to read the mail message
8834 .Pf ( Cd x-mailx-async ) .
8835 Asynchronous execution implies
8839 The command must be run on an interactive terminal, \*(UA will
8840 temporarily release the terminal to it
8841 .Pf ( Cd needsterminal ) .
8842 This flag is mutual exclusive with
8844 will only be used in interactive mode and implies
8848 Request creation of a zero-sized temporary file, the absolute pathname
8849 of which will be made accessible via the environment variable
8850 .Ev MAILX_FILENAME_TEMPORARY
8851 .Pf ( Cd x-mailx-tmpfile ) .
8852 If this trigger is given twice then the file will be unlinked
8853 automatically by \*(UA when the command loop is entered again at latest
8854 .Pf ( Cd x-mailx-tmpfile-unlink ) .
8855 (Do not use this for asynchronous handlers.)
8858 Normally the MIME part content is passed to the handler via standard
8859 input; if this flag is set then the data will instead be written into
8860 .Ev MAILX_FILENAME_TEMPORARY
8861 .Pf ( Cd x-mailx-tmpfile-fill ) ,
8862 the creation of which is implied; note however that in order to cause
8863 deletion of the temporary file you still have to use two plus signs
8868 To avoid ambiguities with normal shell command content you can use
8869 another commercial at to forcefully terminate interpretation of
8870 remaining characters.
8871 (Any character not in this list will have the same effect.)
8875 Some information about the MIME part to be displayed is embedded into
8876 the environment of the shell command:
8879 .Bl -tag -compact -width ".It Ev _AIL__ILENAME__ENERATED"
8881 .It Ev MAILX_CONTENT
8882 The MIME content-type of the part, if known, the empty string otherwise.
8885 .It Ev MAILX_CONTENT_EVIDENCE
8887 .Va mime-counter-evidence
8888 includes the carry-around-bit (2), then this will be set to the detected
8889 MIME content-type; not only then identical to
8890 .Ev \&\&MAILX_CONTENT
8894 .It Ev MAILX_FILENAME
8895 The filename, if any is set, the empty string otherwise.
8898 .It Ev MAILX_FILENAME_GENERATED
8902 .It Ev MAILX_FILENAME_TEMPORARY
8903 If temporary file creation has been requested through the command prefix
8904 this variable will be set and contain the absolute pathname of the
8910 .It Va pipe-EXTENSION
8911 This is identical to
8912 .Va pipe-TYPE/SUBTYPE
8915 (normalized to lowercase using character mappings of the ASCII charset)
8916 names a file extension, e.g.,
8918 Handlers registered using this method take precedence.
8921 .It Va pop3-auth-USER@HOST , pop3-auth-HOST , pop3-auth
8922 \*(OP\*(IN Variable chain that sets the POP3 authentication method.
8923 The only possible value as of now is
8925 which is thus the default.
8928 .Mx Va pop3-bulk-load
8929 .It Va pop3-bulk-load-USER@HOST , pop3-bulk-load-HOST , pop3-bulk-load
8930 \*(BO\*(OP When accessing a POP3 server \*(UA loads the headers of
8931 the messages, and only requests the message bodies on user request.
8932 For the POP3 protocol this means that the message headers will be
8934 If this variable is set then \*(UA will download only complete messages
8935 from the given POP3 server(s) instead.
8937 .Mx Va pop3-keepalive
8938 .It Va pop3-keepalive-USER@HOST , pop3-keepalive-HOST , pop3-keepalive
8939 \*(OP POP3 servers close the connection after a period of inactivity;
8940 the standard requires this to be at least 10 minutes,
8941 but practical experience may vary.
8942 Setting this variable to a numeric value greater than
8946 command to be sent each value seconds if no other operation is performed.
8949 .It Va pop3-no-apop-USER@HOST , pop3-no-apop-HOST , pop3-no-apop
8950 \*(BO\*(OP Unless this variable is set the
8952 authentication method will be used when connecting to a POP3 server that
8956 is that the password is not sent in clear text over the wire and that
8957 only a single packet is sent for the user/password tuple.
8959 .Va pop3-no-apop-HOST
8962 .Mx Va pop3-use-starttls
8963 .It Va pop3-use-starttls-USER@HOST , pop3-use-starttls-HOST , pop3-use-starttls
8964 \*(BO\*(OP Causes \*(UA to issue a
8966 command to make an unencrypted POP3 session SSL/TLS encrypted.
8967 This functionality is not supported by all servers,
8968 and is not used if the session is already encrypted by the POP3S method.
8970 .Va pop3-use-starttls-HOST
8976 \*(BO This flag enables POSIX mode, which changes behaviour of \*(UA
8977 where that deviates from standardized behaviour.
8978 It will be set implicitly before the
8979 .Sx "Resource files"
8980 are loaded if the environment variable
8982 is set, and adjusting any of those two will be reflected by the other
8984 The following behaviour is covered and enforced by this mechanism:
8987 .Bl -bullet -compact
8989 In non-interactive mode, any error encountered while loading resource
8990 files during program startup will cause a program exit, whereas in
8991 interactive mode such errors will stop loading of the currently loaded
8992 (stack of) file(s, i.e., recursively).
8993 These exits can be circumvented on a per-command base by using
8996 .Sx "Command modifiers" ,
8997 for each command which shall be allowed to fail.
9002 is extended to cover any empty mailbox, not only empty
9004 .Sx "primary system mailbox" Ns
9005 es: they will be removed when they are left in empty state otherwise.
9010 .It Va print-alternatives
9011 \*(BO When a MIME message part of type
9012 .Ql multipart/alternative
9013 is displayed and it contains a subpart of type
9015 other parts are normally discarded.
9016 Setting this variable causes all subparts to be displayed,
9017 just as if the surrounding part was of type
9018 .Ql multipart/mixed .
9022 The string used as a prompt in interactive mode.
9023 Whenever the variable is evaluated the value is expanded as via
9024 dollar-single-quote expansion (see
9025 .Sx "Shell-style argument quoting" ) .
9026 This (post-assignment, i.e., second) expansion can be used to embed
9027 status information, for example
9032 .Va mailbox-display .
9034 In order to embed characters which should not be counted when
9035 calculating the visual width of the resulting string, enclose the
9036 characters of interest in a pair of reverse solidus escaped brackets:
9038 a slot for coloured prompts is also available with the \*(OPal command
9040 Prompting may be prevented by setting this to the null string
9042 .Ql set noprompt ) .
9046 This string is used for secondary prompts, but is otherwise identical to
9053 \*(BO Suppresses the printing of the version when first invoked.
9057 If set, \*(UA starts a replying message with the original message
9058 prefixed by the value of the variable
9060 Normally, a heading consisting of
9061 .Dq Fromheaderfield wrote:
9062 is put before the quotation.
9067 variable, this heading is omitted.
9070 is assigned, only the headers selected by the
9073 selection are put above the message body,
9076 acts like an automatic
9078 .Sx "COMMAND ESCAPES"
9082 is assigned, all headers are put above the message body and all MIME
9083 parts are included, making
9085 act like an automatic
9088 .Va quote-as-attachment .
9091 .It Va quote-as-attachment
9092 \*(BO Add the original message in its entirety as a
9094 MIME attachment when replying to a message.
9095 Note this works regardless of the setting of
9100 \*(OP Can be set in addition to
9102 Setting this turns on a more fancy quotation algorithm in that leading
9103 quotation characters are compressed and overlong lines are folded.
9105 can be set to either one or two (space separated) numeric values,
9106 which are interpreted as the maximum (goal) and the minimum line length,
9107 respectively, in a spirit rather equal to the
9109 program, but line-, not paragraph-based.
9110 If not set explicitly the minimum will reflect the goal algorithmically.
9111 The goal cannot be smaller than the length of
9113 plus some additional pad.
9114 Necessary adjustments take place silently.
9117 .It Va r-option-implicit
9118 \*(BO Setting this option evaluates the contents of
9120 (or, if that contains multiple addresses,
9122 and passes the results onto the used (file-based) MTA as described for the
9124 option (empty argument case).
9127 .It Va recipients-in-cc
9128 \*(BO On group replies, specify only the sender of the original mail in
9130 and mention the other recipients in the secondary
9132 By default all recipients of the original mail will be addressed via
9137 If defined, gives the pathname of the folder used to record all outgoing
9139 If not defined, then outgoing mail is not saved.
9140 When saving to this folder fails the message is not sent,
9141 but instead saved to
9145 .It Va record-resent
9146 \*(BO If both this variable and the
9153 commands save messages to the
9155 folder as it is normally only done for newly composed messages.
9158 .It Va reply-in-same-charset
9159 \*(BO If this variable is set \*(UA first tries to use the same
9160 character set of the original message for replies.
9161 If this fails, the mechanism described in
9162 .Sx "Character sets"
9163 is evaluated as usual.
9166 .It Va reply-strings
9167 Can be set to a comma-separated list of (case-insensitive according to
9168 ASCII rules) strings which shall be recognized in addition to the
9171 reply message indicators \(en builtin are
9173 which is mandated by RFC 5322, as well as the german
9178 which often has been seen in the wild;
9179 I.e., the separating colon has to be specified explicitly.
9183 A list of addresses to put into the
9185 field of the message header.
9186 Members of this list are handled as if they were in the
9191 .It Va reply-to-honour
9194 header is honoured when replying to a message via
9198 This is a quadoption; if set without a value it defaults to
9202 .It Va rfc822-body-from_
9203 \*(BO This variable can be used to force displaying a so-called
9205 line for messages that are embedded into an envelope mail via the
9207 MIME mechanism, for more visual convenience.
9211 \*(BO Enable saving of (partial) messages in
9213 upon interrupt or delivery error.
9217 The number of lines that represents a
9226 line display and scrolling via
9228 If this variable is not set \*(UA falls back to a calculation based upon
9229 the detected terminal window size and the baud rate: the faster the
9230 terminal, the more will be shown.
9231 Overall screen dimensions and pager usage is influenced by the
9232 environment variables
9240 .It Va searchheaders
9241 \*(BO Expand message-list specifiers in the form
9243 to all messages containing the substring
9247 The string search is case insensitive.
9251 \*(OP A comma-separated list of character set names that can be used in
9252 outgoing internet mail.
9253 The value of the variable
9255 is automatically appended to this list of character sets.
9256 If no character set conversion capabilities are compiled into \*(UA then
9257 the only supported charset is
9260 .Va sendcharsets-else-ttycharset
9261 and refer to the section
9262 .Sx "Character sets"
9263 for the complete picture of character set conversion in \*(UA.
9266 .It Va sendcharsets-else-ttycharset
9267 \*(BO\*(OP If this variable is set, but
9269 is not, then \*(UA acts as if
9271 had been set to the value of the variable
9273 In effect this combination passes through the message data in the
9274 character set of the current locale (given that
9276 has not been set manually), i.e., without converting it to the
9278 fallback character set.
9279 Thus, mail message text will be in ISO-8859-1 encoding when send from
9280 within a ISO-8859-1 locale, and in UTF-8 encoding when send from within
9282 If no character set conversion capabilities are available in \*(UA then
9283 the only supported character set is
9288 An address that is put into the
9290 field of outgoing messages, quoting RFC 5322: the mailbox of the agent
9291 responsible for the actual transmission of the message.
9292 This field should normally not be used unless the
9294 field contains more than one address, on which case it is required.
9297 address is handled as if it were in the
9301 .Va r-option-implicit .
9305 \*(OB Predecessor of
9309 .It Va sendmail-arguments
9310 \*(OB Predecessor of
9314 .It Va sendmail-no-default-arguments
9315 \*(OB\*(BO Predecessor of
9316 .Va mta-no-default-arguments .
9319 .It Va sendmail-progname
9320 \*(OB Predecessor of
9325 \*(BO When sending a message wait until the
9327 (including the builtin SMTP one) exits before accepting further commands.
9329 with this variable set errors reported by the MTA will be recognizable!
9330 If the MTA returns a non-zero exit status,
9331 the exit status of \*(UA will also be non-zero.
9335 \*(BO This setting causes \*(UA to start at the last message
9336 instead of the first one when opening a mail folder.
9340 \*(BO Causes \*(UA to use the sender's real name instead of the plain
9341 address in the header field summary and in message specifications.
9345 \*(BO Causes the recipient of the message to be shown in the header
9346 summary if the message was sent by the user.
9350 The string to expand
9353 .Sx "COMMAND ESCAPES" ) .
9357 The string to expand
9360 .Sx "COMMAND ESCAPES" ) .
9364 Must correspond to the name of a readable file if set.
9365 The file's content is then appended to each singlepart message
9366 and to the first part of each multipart message.
9367 Be warned that there is no possibility to edit the signature for an
9371 .It Va skipemptybody
9372 \*(BO If an outgoing message does not contain any text in its first or
9373 only message part, do not send it but discard it silently (see also the
9379 .It Va smime-ca-dir , smime-ca-file
9380 \*(OP Specify the location of trusted CA certificates in PEM (Privacy
9381 Enhanced Mail) format as a directory and a file, respectively, for the
9382 purpose of verification of S/MIME signed messages.
9383 It is possible to set both, the file will be loaded immediately, the
9384 directory will be searched whenever no match has yet been found.
9385 The set of CA certificates which are built into the SSL/TLS library can
9386 be explicitly turned off by setting
9387 .Va smime-ca-no-defaults ,
9388 and further fine-tuning is possible via
9389 .Va smime-ca-flags .
9392 .It Va smime-ca-flags
9393 \*(OP Can be used to fine-tune behaviour of the X509 CA certificate
9394 storage, and the certificate verification that is used.
9395 The actual values and their meanings are documented for
9399 .It Va smime-ca-no-defaults
9400 \*(BO\*(OP Do not load the default CA locations that are built into the
9401 used to SSL/TLS library to verify S/MIME signed messages.
9404 .It Va smime-cipher-USER@HOST , smime-cipher
9405 \*(OP Specifies the cipher to use when generating S/MIME encrypted
9406 messages (for the specified account).
9407 RFC 5751 mandates a default of
9410 Possible values are (case-insensitive and) in decreasing cipher strength:
9418 (DES EDE3 CBC, 168 bits; default if
9420 is not available) and
9424 The actually available cipher algorithms depend on the cryptographic
9425 library that \*(UA uses.
9426 \*(OP Support for more cipher algorithms may be available through
9427 dynamic loading via, e.g.,
9428 .Xr EVP_get_cipherbyname 3
9429 (OpenSSL) if \*(UA has been compiled to support this.
9432 .It Va smime-crl-dir
9433 \*(OP Specifies a directory that contains files with CRLs in PEM format
9434 to use when verifying S/MIME messages.
9437 .It Va smime-crl-file
9438 \*(OP Specifies a file that contains a CRL in PEM format to use when
9439 verifying S/MIME messages.
9442 .It Va smime-encrypt-USER@HOST
9443 \*(OP If this variable is set, messages send to the given receiver are
9444 encrypted before sending.
9445 The value of the variable must be set to the name of a file that
9446 contains a certificate in PEM format.
9448 If a message is sent to multiple recipients,
9449 each of them for whom a corresponding variable is set will receive an
9450 individually encrypted message;
9451 other recipients will continue to receive the message in plain text
9453 .Va smime-force-encryption
9455 It is recommended to sign encrypted messages, i.e., to also set the
9460 .It Va smime-force-encryption
9461 \*(BO\*(OP Causes \*(UA to refuse sending unencrypted messages.
9465 \*(BO\*(OP S/MIME sign outgoing messages with the user's private key
9466 and include the user's certificate as a MIME attachment.
9467 Signing a message enables a recipient to verify that the sender used
9468 a valid certificate,
9469 that the email addresses in the certificate match those in the message
9470 header and that the message content has not been altered.
9471 It does not change the message text,
9472 and people will be able to read the message as usual.
9474 .Va smime-sign-cert , smime-sign-include-certs
9476 .Va smime-sign-message-digest .
9478 .Mx Va smime-sign-cert
9479 .It Va smime-sign-cert-USER@HOST , smime-sign-cert
9480 \*(OP Points to a file in PEM format.
9481 For the purpose of signing and decryption this file needs to contain the
9482 user's private key, followed by his certificate.
9486 is always derived from the value of
9488 (or, if that contains multiple addresses,
9490 For the purpose of encryption the recipient's public encryption key
9491 (certificate) is expected; the command
9493 can be used to save certificates of signed messages (the section
9494 .Sx "Signed and encrypted messages with S/MIME"
9495 gives some details).
9496 This mode of operation is usually driven by the specialized form.
9498 When decrypting messages the account is derived from the recipient
9503 of the message, which are searched for addresses for which such
9505 \*(UA always uses the first address that matches,
9506 so if the same message is sent to more than one of the user's addresses
9507 using different encryption keys, decryption might fail.
9509 For signing and decryption purposes it is possible to use encrypted
9510 keys, and the pseudo-host(s)
9511 .Ql USER@HOST.smime-cert-key
9514 .Ql USER@HOST.smime-cert-cert
9515 for the certificate stored in the same file)
9516 will be used for performing any necessary password lookup,
9517 therefore the lookup can be automatized via the mechanisms described in
9518 .Sx "On URL syntax and credential lookup" .
9519 For example, the hypothetical address
9521 could be driven with a private key / certificate pair path defined in
9522 .Va \&\&smime-sign-cert-bob@exam.ple ,
9523 and needed passwords would then be looked up via the pseudo hosts
9524 .Ql bob@exam.ple.smime-cert-key
9526 .Ql bob@exam.ple.smime-cert-cert ) .
9527 To include intermediate certificates, use
9528 .Va smime-sign-include-certs .
9530 .Mx Va smime-sign-include-certs
9531 .It Va smime-sign-include-certs-USER@HOST , smime-sign-include-certs
9532 \*(OP If used, this is supposed to a consist of a comma-separated list
9533 of files, each of which containing a single certificate in PEM format to
9534 be included in the S/MIME message in addition to the
9537 This can be used to include intermediate certificates of the certificate
9538 authority, in order to allow the receiver's S/MIME implementation to
9539 perform a verification of the entire certificate chain, starting from
9540 a local root certificate, over the intermediate certificates, down to the
9541 .Va smime-sign-cert .
9542 Even though top level certificates may also be included in the chain,
9543 they won't be used for the verification on the receiver's side.
9545 For the purpose of the mechanisms involved here,
9547 refers to the content of the internal variable
9549 (or, if that contains multiple addresses,
9552 .Ql USER@HOST.smime-include-certs
9553 will be used for performing password lookups for these certificates,
9554 shall they have been given one, therefore the lookup can be automatized
9555 via the mechanisms described in
9556 .Sx "On URL syntax and credential lookup" .
9558 .Mx Va smime-sign-message-digest
9559 .It Va smime-sign-message-digest-USER@HOST , smime-sign-message-digest
9560 \*(OP Specifies the message digest to use when signing S/MIME messages.
9561 RFC 5751 mandates a default of
9563 Possible values are (case-insensitive and) in decreasing cipher strength:
9571 The actually available message digest algorithms depend on the
9572 cryptographic library that \*(UA uses.
9573 \*(OP Support for more message digest algorithms may be available
9574 through dynamic loading via, e.g.,
9575 .Xr EVP_get_digestbyname 3
9576 (OpenSSL) if \*(UA has been compiled to support this.
9577 Remember that for this
9579 refers to the variable
9581 (or, if that contains multiple addresses,
9586 \*(OB\*(OP To use the builtin SMTP transport, specify a SMTP URL in
9588 \*(ID For compatibility reasons a set
9590 is used in preference of
9594 .It Va smtp-auth-USER@HOST , smtp-auth-HOST , smtp-auth
9595 \*(OP Variable chain that controls the SMTP
9597 authentication method, possible values are
9603 as well as the \*(OPal methods
9609 method does not need any user credentials,
9611 requires a user name and all other methods require a user name and
9619 .Va smtp-auth-password
9621 .Va smtp-auth-user ) .
9626 .Va smtp-auth-USER@HOST :
9627 may override dependent on sender address in the variable
9630 .It Va smtp-auth-password
9631 \*(OP\*(OU Sets the global fallback password for SMTP authentication.
9632 If the authentication method requires a password, but neither
9633 .Va smtp-auth-password
9635 .Va smtp-auth-password-USER@HOST
9637 \*(UA will ask for a password on the user's terminal.
9639 .It Va smtp-auth-password-USER@HOST
9641 .Va smtp-auth-password
9642 for specific values of sender addresses, dependent upon the variable
9645 .It Va smtp-auth-user
9646 \*(OP\*(OU Sets the global fallback user name for SMTP authentication.
9647 If the authentication method requires a user name, but neither
9650 .Va smtp-auth-user-USER@HOST
9652 \*(UA will ask for a user name on the user's terminal.
9654 .It Va smtp-auth-user-USER@HOST
9657 for specific values of sender addresses, dependent upon the variable
9661 .It Va smtp-hostname
9662 \*(OP\*(IN Normally \*(UA uses the variable
9664 to derive the necessary
9666 information in order to issue a
9673 can be used to use the
9675 from the SMTP account
9682 from the content of this variable (or, if that is the empty string,
9684 or the local hostname as a last resort).
9685 This often allows using an address that is itself valid but hosted by
9686 a provider other than which (in
9688 is about to send the message.
9689 Setting this variable also influences generated
9695 .Mx Va smtp-use-starttls
9696 .It Va smtp-use-starttls-USER@HOST , smtp-use-starttls-HOST , smtp-use-starttls
9697 \*(BO\*(OP Causes \*(UA to issue a
9699 command to make an SMTP
9701 session SSL/TLS encrypted, i.e., to enable transport layer security.
9705 .It Va spam-interface
9706 \*(OP In order to use any of the spam-related commands (like, e.g.,
9708 the desired spam interface must be defined by setting this variable.
9709 Please refer to the manual section
9711 for the complete picture of spam handling in \*(UA.
9712 All or none of the following interfaces may be available:
9714 .Bl -tag -width ".It Ql _ilte_"
9720 .Pf ( Lk http://spamassassin.apache.org SpamAssassin )
9722 Different to the generic filter interface \*(UA will automatically add
9723 the correct arguments for a given command and has the necessary
9724 knowledge to parse the program's output.
9727 will have been compiled into the \*(UA binary if
9732 Shall it be necessary to define a specific connection type (rather than
9733 using a configuration file for that), the variable
9735 can be used as in, e.g.,
9736 .Ql -d server.example.com -p 783 .
9737 It is also possible to specify a per-user configuration via
9739 Note that this interface does not inspect the
9741 flag of a message for the command
9745 generic spam filter support via freely configurable hooks.
9746 This interface is meant for programs like
9748 and requires according behaviour in respect to the hooks' exit
9749 status for at least the command
9752 meaning a message is spam,
9756 for unsure and any other return value indicating a hard error);
9757 since the hooks can include shell code snippets diverting behaviour
9758 can be intercepted as necessary.
9760 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
9763 .Va spamfilter-spam ;
9766 contains examples for some programs.
9767 The process environment of the hooks will have the variable
9768 .Ev MAILX_FILENAME_GENERATED
9770 Note that spam score support for
9772 is not supported unless the \*(OPtional regular expression support is
9774 .Va spamfilter-rate-scanscore
9781 \*(OP Messages that exceed this size will not be passed through to the
9783 .Va spam-interface .
9784 If unset or 0, the default of 420000 bytes is used.
9787 .It Va spamc-command
9788 \*(OP The path to the
9792 .Va spam-interface .
9793 Note that the path is not expanded, but used
9795 A fallback path will have been compiled into the \*(UA binary if the
9796 executable had been found during compilation.
9799 .It Va spamc-arguments
9800 \*(OP Even though \*(UA deals with most arguments for the
9803 automatically, it may at least sometimes be desirable to specify
9804 connection-related ones via this variable, e.g.,
9805 .Ql -d server.example.com -p 783 .
9809 \*(OP Specify a username for per-user configuration files for the
9811 .Va spam-interface .
9812 If this is set to the empty string then \*(UA will use the name of the
9821 .It Va spamfilter-ham , spamfilter-noham , \
9822 spamfilter-nospam , spamfilter-rate , spamfilter-spam
9823 \*(OP Command and argument hooks for the
9825 .Va spam-interface .
9828 contains examples for some programs.
9831 .It Va spamfilter-rate-scanscore
9832 \*(OP Because of the generic nature of the
9835 spam scores are not supported for it by default, but if the \*(OPnal
9836 regular expression support is available then setting this variable can
9837 be used to overcome this restriction.
9838 It is interpreted as follows: first a number (digits) is parsed that
9839 must be followed by a semicolon
9841 and an extended regular expression.
9842 Then the latter is used to parse the first output line of the
9844 hook, and, in case the evaluation is successful, the group that has been
9845 specified via the number is interpreted as a floating point scan score.
9849 .It Va ssl-ca-dir , ssl-ca-file
9850 \*(OP Specify the location of trusted CA certificates in PEM (Privacy
9851 Enhanced Mail) format as a directory and a file, respectively, for the
9852 purpose of verification of SSL/TLS server certificates.
9853 It is possible to set both, the file will be loaded immediately, the
9854 directory will be searched whenever no match has yet been found.
9855 The set of CA certificates which are built into the SSL/TLS library can
9856 be explicitly turned off by setting
9857 .Va ssl-ca-no-defaults ,
9858 and further fine-tuning is possible via
9861 .Xr SSL_CTX_load_verify_locations 3
9862 for more information.
9867 \*(OP Can be used to fine-tune behaviour of the X509 CA certificate
9868 storage, and the certificate verification that is used (also see
9870 The value is expected to consist of a comma-separated list of
9871 configuration directives, with any intervening whitespace being ignored.
9872 The directives directly map to flags that can be passed to
9873 .Xr X509_STORE_set_flags 3 ,
9874 which are usually defined in a file
9875 .Pa openssl/x509_vfy.h ,
9876 and the availability of which depends on the used SSL/TLS library
9877 version: a directive without mapping is ignored (error log subject to
9879 Directives currently understood (case-insensitively) include:
9882 .Bl -tag -compact -width ".It Cd BaNg"
9883 .It Cd no-alt-chains
9884 If the initial chain is not trusted, do not attempt to build an
9886 Setting this flag will make OpenSSL certificate verification match that
9887 of older OpenSSL versions, before automatic building and checking of
9888 alternative chains has been implemented; also see
9890 .It Cd no-check-time
9891 Do not check certificate/CRL validity against current time.
9892 .It Cd partial-chain
9893 By default partial, incomplete chains which cannot be verified up to the
9894 chain top, a self-signed root certificate, will not verify.
9895 With this flag set, a chain succeeds to verify if at least one signing
9896 certificate of the chain is in any of the configured trusted stores of
9898 The OpenSSL manual page
9899 .Xr SSL_CTX_load_verify_locations 3
9900 gives some advise how to manage your own trusted store of CA certificates.
9902 Disable workarounds for broken certificates.
9903 .It Cd trusted-first
9904 Try building a chain using issuers in the trusted store first to avoid
9905 problems with server-sent legacy intermediate certificates.
9906 Newer versions of OpenSSL support alternative chain checking and enable
9907 it by default, resulting in the same behaviour; also see
9913 .It Va ssl-ca-no-defaults
9914 \*(BO\*(OP Do not load the default CA locations that are built into the
9915 used to SSL/TLS library to verify SSL/TLS server certificates.
9918 .It Va ssl-cert-USER@HOST , ssl-cert-HOST , ssl-cert
9919 \*(OP Variable chain that sets the file name for a SSL/TLS client
9920 certificate required by some servers.
9921 This is a direct interface to the
9925 function of the OpenSSL library, if available.
9927 .Mx Va ssl-cipher-list
9928 .It Va ssl-cipher-list-USER@HOST , ssl-cipher-list-HOST , ssl-cipher-list
9929 \*(OP Specifies a list of ciphers for SSL/TLS connections.
9930 This is a direct interface to the
9934 function of the OpenSSL library, if available; see
9936 for more information.
9937 By default \*(UA does not set a list of ciphers, in effect using a
9939 specific cipher (protocol standards ship with a list of acceptable
9940 ciphers), possibly cramped to what the actually used SSL/TLS library
9941 supports \(en the manual section
9942 .Sx "An example configuration"
9943 also contains a SSL/TLS use case.
9946 .It Va ssl-config-file
9947 \*(OP If this variable is set \*(UA will call
9948 .Xr CONF_modules_load_file 3
9949 to allow OpenSSL to be configured according to the host system wide
9951 If a non-empty value is given then this will be used to specify the
9952 configuration file to be used instead of the global OpenSSL default;
9953 note that in this case it is an error if the file cannot be loaded.
9954 The application name will always be passed as
9959 .It Va ssl-crl-dir , ssl-crl-file
9960 \*(OP Specify a directory / a file, respectively that contains a CRL in
9961 PEM format to use when verifying SSL/TLS server certificates.
9964 .It Va ssl-key-USER@HOST , ssl-key-HOST , ssl-key
9965 \*(OP Variable chain that sets the file name for the private key of
9966 a SSL/TLS client certificate.
9967 If unset, the name of the certificate file is used.
9968 The file is expected to be in PEM format.
9969 This is a direct interface to the
9973 function of the OpenSSL library, if available.
9976 .It Va ssl-method-USER@HOST , ssl-method-HOST , ssl-method
9977 \*(OB\*(OP Please use the newer and more flexible
9979 instead: if both values are set,
9981 will take precedence!
9982 Can be set to the following values, the actually used
9984 specification to which it is mapped is shown in parenthesis:
9986 .Pf ( Ql -ALL, TLSv1.2 ) ,
9988 .Pf ( Ql -ALL, TLSv1.1 ) ,
9990 .Pf ( Ql -ALL, TLSv1 )
9993 .Pf ( Ql -ALL, SSLv3 ) ;
9998 and thus includes the SSLv3 protocol.
9999 Note that SSLv2 is no longer supported at all.
10001 .Mx Va ssl-protocol
10002 .It Va ssl-protocol-USER@HOST , ssl-protocol-HOST , ssl-protocol
10003 \*(OP Specify the used SSL/TLS protocol.
10004 This is a direct interface to the
10008 function of the OpenSSL library, if available;
10009 otherwise an \*(UA internal parser is used which understands the
10010 following subset of (case-insensitive) command strings:
10016 as well as the special value
10018 Multiple specifications may be given via a comma-separated list which
10019 ignores any whitespace.
10022 plus sign prefix will enable a protocol, a
10024 hyphen-minus prefix will disable it, so that
10026 will enable only the TLSv1.2 protocol.
10028 It depends upon the used TLS/SSL library which protocols are actually
10029 supported and which protocols are used if
10031 is not set, but note that SSLv2 is no longer supported at all and
10033 Especially for older protocols explicitly securing
10034 .Va ssl-cipher-list
10035 may be worthwile, see
10036 .Sx "An example configuration" .
10039 .It Va ssl-rand-egd
10040 \*(OP Gives the pathname to an entropy daemon socket, see
10042 Not all SSL/TLS libraries support this.
10045 .It Va ssl-rand-file
10046 \*(OP Gives the filename to a file with random entropy data, see
10047 .Xr RAND_load_file 3 .
10048 If this variable is not set, or set to the empty string, or if the
10049 .Sx "Filename transformations"
10051 .Xr RAND_file_name 3
10052 will be used to create the filename if, and only if,
10054 documents that the SSL PRNG is not yet sufficiently seeded.
10055 If \*(UA successfully seeded the SSL PRNG then it will update the file
10056 .Pf ( Xr RAND_write_file 3 ) .
10057 This variable is only used if
10059 is not set (or not supported by the SSL/TLS library).
10062 .It Va ssl-verify-USER@HOST , ssl-verify-HOST , ssl-verify
10063 \*(OP Variable chain that sets the action to be performed if an error
10064 occurs during SSL/TLS server certificate validation against the
10065 specified or default trust stores
10068 or the SSL/TLS library builtin defaults (unless usage disallowed via
10069 .Va ssl-ca-no-defaults ) ,
10070 and as fine-tuned via
10072 Valid (case-insensitive) values are
10074 (fail and close connection immediately),
10076 (ask whether to continue on standard input),
10078 (show a warning and continue),
10080 (do not perform validation).
10086 If only set without an assigned value, then this setting inhibits the
10092 header fields that include obvious references to \*(UA.
10093 There are two pitfalls associated with this:
10094 First, the message id of outgoing messages is not known anymore.
10095 Second, an expert may still use the remaining information in the header
10096 to track down the originating mail user agent.
10097 If set to the value
10103 suppression does not occur.
10108 (\*(OP) This specifies a comma-separated list of
10113 .Sx "On terminal control and line editor" ,
10114 escape commas with reverse solidus) to be used to overwrite or define
10116 Note that this variable will only be queried once at program startup and
10117 can thus only be specified in resource files or on the command line.
10120 String capabilities form
10122 pairs and are expected unless noted otherwise.
10123 Numerics have to be notated as
10125 where the number is expected in normal decimal notation.
10126 Finally, booleans do not have any value but indicate a true or false
10127 state simply by being defined or not; this indeed means that \*(UA
10128 does not support undefining an existing boolean.
10129 String capability values will undergo some expansions before use:
10130 for one notations like
10133 .Ql control-LETTER ,
10134 and for clarification purposes
10136 can be used to specify
10138 (the control notation
10140 could lead to misreadings when a left bracket follows, which it does for
10141 the standard CSI sequence);
10142 finally three letter octal sequences, as in
10145 To specify that a terminal supports 256-colours, and to define sequences
10146 that home the cursor and produce an audible bell, one might write:
10148 .Bd -literal -offset indent
10149 set termcap='Co#256,home=\eE[H,bel=^G'
10153 The following terminal capabilities are or may be meaningful for the
10154 operation of the builtin line editor or \*(UA in general:
10157 .Bl -tag -compact -width yay
10159 .It Cd colors Ns \0or Cd Co
10161 numeric capability specifying the maximum number of colours.
10162 Note that \*(UA does not actually care about the terminal beside that,
10163 but always emits ANSI / ISO 6429 escape sequences.
10166 .It Cd rmcup Ns \0or Cd te Ns \0/ Cd smcup Ns \0or Cd ti
10169 .Cd enter_ca_mode ,
10170 respectively: exit and enter the alternative screen
10172 effectively turning \*(UA into a fullscreen application.
10173 To disable that, set (at least) one to the empty string.
10175 .It Cd smkx Ns \0or Cd ks Ns \0/ Cd rmkx Ns \0or Cd ke
10179 respectively: enable and disable the keypad.
10180 This is always enabled if available, because it seems even keyboards
10181 without keypads generate other key codes for, e.g., cursor keys in that
10182 case, and only if enabled we see the codes that we are interested in.
10184 .It Cd ed Ns \0or Cd cd
10188 .It Cd clear Ns \0or Cd cl
10190 clear the screen and home cursor.
10191 (Will be simulated via
10196 .It Cd home Ns \0or Cd ho
10201 .It Cd el Ns \0or Cd ce
10203 clear to the end of line.
10204 (Will be simulated via
10206 plus repetitions of space characters.)
10208 .It Cd hpa Ns \0or Cd ch
10209 .Cd column_address :
10210 move the cursor (to the given column parameter) in the current row.
10211 (Will be simulated via
10217 .Cd carriage_return :
10218 move to the first column in the current row.
10219 The default builtin fallback is
10222 .It Cd cub1 Ns \0or Cd le
10224 move the cursor left one space (non-destructively).
10225 The default builtin fallback is
10228 .It Cd cuf1 Ns \0or Cd nd
10230 move the cursor right one space (non-destructively).
10231 The default builtin fallback is
10233 which is used by most terminals.
10241 Many more capabilities which describe key-sequences are documented for
10245 .It Va termcap-disable
10246 \*(OP Disable any interaction with a terminal control library.
10247 If set only some generic fallback builtins and possibly the content of
10249 describe the terminal to \*(UA.
10251 that this variable will only be queried once at program startup and can
10252 thus only be specified in resource files or on the command line.
10256 If defined, gives the number of lines of a message to be displayed
10259 if unset, the first five lines are printed, if set to 0 the variable
10262 If the value is negative then its absolute value will be used for
10263 unsigned right shifting (see
10271 \*(BO If set then the
10273 command series will strip adjacent empty lines and quotations.
10277 The character set of the terminal \*(UA operates on,
10278 and the one and only supported character set that \*(UA can use if no
10279 character set conversion capabilities have been compiled into it,
10280 in which case it defaults to ISO-8859-1 unless it can deduce a value
10283 locale environment.
10284 It defaults to UTF-8 if conversion is available.
10285 Refer to the section
10286 .Sx "Character sets"
10287 for the complete picture about character sets.
10290 .It Va typescript-mode
10291 \*(BO A special multiplex variable that disables all variables and
10292 settings which result in behaviour that interferes with running \*(UA in
10295 .Va colour-disable ,
10296 .Va line-editor-disable
10297 and (before startup completed only)
10298 .Va termcap-disable .
10299 Unsetting it does not restore the former state of the covered settings.
10303 For a safety-by-default policy \*(UA sets its process
10307 but this variable can be used to override that:
10308 set it to an empty value to do not change the (current) setting,
10309 otherwise the process file mode creation mask is updated to the new value.
10310 Child processes inherit the process file mode creation mask.
10313 .It Va user-HOST , user
10314 \*(IN Variable chain that sets a global fallback user name, which is
10315 used in case none has been given in the protocol and account-specific
10317 This variable defaults to the name of the user who runs \*(UA.
10321 \*(BO Setting this enables upward compatibility with \*(UA
10322 version 15.0 in respect to which configuration options are available and
10323 how they are handled.
10324 This manual uses \*(IN and \*(OU to refer to the new and the old way of
10325 doing things, respectively.
10329 \*(BO This setting, also controllable via the command line option
10331 causes \*(UA to be more verbose, e.g., it will display obsoletion
10332 warnings and SSL/TLS certificate chains.
10333 Even though marked \*(BO this option may be set twice in order to
10334 increase the level of verbosity even more, in which case even details of
10335 the actual message delivery and protocol conversations are shown.
10338 is sufficient to disable verbosity as such.
10344 .It Va version , version-major , version-minor , version-update
10345 \*(RO \*(UA version information: the first variable contains a string
10346 containing the complete version identification, the latter three contain
10347 only digits: the major, minor and update version numbers.
10348 The output of the command
10350 will include this information.
10353 .It Va writebackedited
10354 If this variable is set messages modified using the
10358 commands are written back to the current folder when it is quit;
10359 it is only honoured for writable folders in MBOX format, though.
10360 Note that the editor will be pointed to the raw message content in that
10361 case, i.e., neither MIME decoding nor decryption will have been
10362 performed, and proper RFC 4155
10364 quoting of newly added or edited content is also left as an excercise to
10367 .\" }}} (Variables)
10368 .\" }}} (INTERNAL VARIABLES)
10371 .\" .Sh ENVIRONMENT {{{
10375 .Dq environment variable
10376 should be considered an indication that these variables are either
10377 standardized as vivid parts of process environments, or that they are
10378 commonly found in there.
10379 The process environment is inherited from the
10381 once \*(UA is started, and unless otherwise explicitly noted handling of
10382 the following variables transparently integrates into that of the
10383 .Sx "INTERNAL VARIABLES"
10384 from \*(UA's point of view.
10385 This means that, e.g., they can be managed via
10389 causing automatic program environment updates (to be inherited by
10390 newly created child processes).
10393 In order to transparently integrate other environment variables equally
10394 they need to be imported (linked) with the command
10396 This command can also be used to set and unset non-integrated
10397 environment variables from scratch, sufficient system support provided.
10398 The following example, applicable to a POSIX shell, sets the
10400 environment variable for \*(UA only, and beforehand exports the
10402 in order to affect any further processing in the running shell:
10404 .Bd -literal -offset indent
10405 $ EDITOR="vim -u ${HOME}/.vimrc"
10407 $ COLUMNS=80 \*(uA -R
10410 .Bl -tag -width ".It Ev BaNg"
10413 The user's preferred width in column positions for the terminal screen
10415 Queried and used once on program startup, actively managed for child
10416 processes and the MLE (see
10417 .Sx "On terminal control and line editor" )
10418 in interactive mode thereafter.
10422 The name of the (mailbox)
10424 to use for saving aborted messages if
10426 is set; this defaults to
10433 is set no output will be generated, otherwise the contents of the file
10438 Pathname of the text editor to use in the
10442 .Sx "COMMAND ESCAPES" .
10443 A default editor is used if this value is not defined.
10447 The user's home directory.
10448 This variable is only used when it resides in the process environment.
10455 .It Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
10459 .Sx "Character sets" .
10463 The user's preferred number of lines on a page or the vertical screen
10464 or window size in lines.
10465 Queried and used once on program startup, actively managed for child
10466 processes in interactive mode thereafter.
10470 Pathname of the directory lister to use in the
10472 command when operating on local mailboxes.
10475 (path search through
10480 Upon startup \*(UA will actively ensure that this variable refers to the
10481 name of the user who runs \*(UA, in order to be able to pass a verified
10482 name to any newly created child process.
10486 Is used as the users
10488 .Sx "primary system mailbox"
10492 This is assumed to be an absolute pathname.
10496 \*(OP Overrides the default path search for
10497 .Sx "The Mailcap files" ,
10498 which is defined in the standard RFC 1524 as
10499 .Ql ~/.mailcap:\:/etc/mailcap:\:/usr/etc/mailcap:\:/usr/local/etc/mailcap .
10500 .\" TODO we should have a mailcaps-default virtual RDONLY option!
10501 (\*(UA makes it a configuration option, however.)
10502 Note this is not a search path, but a path search.
10506 Is used as a startup file instead of
10509 When \*(UA scripts are invoked on behalf of other users,
10510 either this variable should be set to
10514 command line option should be used in order to avoid side-effects from
10515 reading their configuration files.
10516 This variable is only used when it resides in the process environment.
10519 .It Ev MAILX_NO_SYSTEM_RC
10520 If this variable is set then reading of
10522 at startup is inhibited, i.e., the same effect is achieved as if \*(UA
10523 had been started up with the option
10525 (and according argument) or
10527 This variable is only used when it resides in the process environment.
10531 The name of the users
10533 .Sx "secondary mailbox"
10535 A logical subset of the special
10536 .Sx "Filename transformations"
10540 The fallback default is
10545 Traditionally this MBOX is used as the file to save messages from the
10547 .Sx "primary system mailbox"
10548 that have been read.
10550 .Sx "Message states" .
10554 \*(IN\*(OP This variable overrides the default location of the user's
10560 Pathname of the program to use for backing the command
10564 variable enforces usage of a pager for output.
10565 The default paginator is
10567 (path search through
10570 \*(UA inspects the contents of this variable: if its contains the string
10572 then a non-existing environment variable
10579 dependent on whether terminal control support is available and whether
10580 that supports full (alternative) screen mode or not (also see
10581 .Sx "On terminal control and line editor" ) .
10585 will optionally be set to
10592 A colon-separated list of directories that is searched by the shell when
10593 looking for commands, e.g.,
10594 .Ql /bin:/usr/bin:/usr/local/bin .
10597 .It Ev POSIXLY_CORRECT
10598 This variable is automatically looked for upon startup, see
10604 The shell to use for the commands
10609 .Sx "COMMAND ESCAPES"
10610 and when starting subprocesses.
10611 A default shell is used if this environment variable is not defined.
10614 .It Ev SOURCE_DATE_EPOCH
10615 If set, this specifies a time in seconds since the Unix epoch
10616 (1970-01-01) to be used in place of the current time.
10617 This is for the sake of reproduceability of tests, to be used during
10618 development or by software packagers.
10622 \*(OP The terminal type for which output is to be prepared.
10623 For extended colour and font control please refer to
10624 .Sx "Coloured display" ,
10625 and for terminal management in general to
10626 .Sx "On terminal control and line editor" .
10630 Used as directory for temporary files instead of
10633 This variable is only used when it resides in the process environment,
10634 but \*(UA will ensure at startup that this environment variable is
10635 updated to contain a usable temporary directory.
10641 (see there), but this variable is not standardized, should therefore not
10642 be used, and is only corrected if already set.
10646 Pathname of the text editor to use in the
10650 .Sx "COMMAND ESCAPES" .
10658 .Bl -tag -width ".It Pa BaNg"
10660 File giving initial commands.
10663 System wide initialization file.
10667 \*(OP Personal MIME type handler definition file, see
10668 .Sx "The Mailcap files" .
10669 (RFC 1524 location, the actual path is a configuration option.)
10672 .It Pa /etc/mailcap
10673 \*(OP System wide MIME type handler definition file, see
10674 .Sx "The Mailcap files" .
10675 (RFC 1524 location, the actual path is a configuration option.)
10678 .It Pa ~/.mime.types
10679 Personal MIME types, see
10680 .Sx "The mime.types files" .
10683 .It Pa /etc/mime.types
10684 System wide MIME types, see
10685 .Sx "The mime.types files" .
10689 \*(IN\*(OP The default location of the users
10691 file \(en the section
10692 .Sx "The .netrc file"
10693 documents the file format.
10696 .\" .Ss "The mime.types files" {{{
10697 .Ss "The mime.types files"
10699 When sending messages \*(UA tries to determine the content type of all
10701 When displaying message content or attachments \*(UA uses the content
10702 type to decide whether it can directly display data or whether it needs
10703 to deal with content handlers.
10704 It learns about M(ultipurpose) I(nternet) M(ail) E(xtensions) types and
10705 how to treat them by reading
10707 files, the loading of which can be controlled by setting the variable
10708 .Va mimetypes-load-control .
10711 can also be used to deal with MIME types.)
10713 files have the following syntax:
10716 .Dl type/subtype extension [extension ...]
10721 are strings describing the file contents, and one or multiple
10723 s, separated by whitespace, name the part of a filename starting after
10724 the last dot (of interest).
10725 Comments may be introduced anywhere on a line with a number sign
10727 causing the remaining line to be discarded.
10729 \*(UA also supports an extended, non-portable syntax in specially
10730 crafted files, which can be loaded via the alternative value syntax of
10731 .Va mimetypes-load-control
10732 and prepends an optional
10736 .Dl [type-marker ]type/subtype extension [extension ...]
10739 The following type markers are supported:
10742 .Bl -tag -compact -width ".It Ar _n_u"
10744 Treat message parts with this content as plain text.
10749 Treat message parts with this content as HTML tagsoup.
10750 If the \*(OPal HTML-tagsoup-to-text converter is not available treat
10751 the content as plain text instead.
10755 but instead of falling back to plain text require an explicit content
10756 handler to be defined.
10761 for sending messages:
10763 .Va mime-allow-text-controls ,
10764 .Va mimetypes-load-control .
10765 For reading etc. messages:
10766 .Sx "HTML mail and MIME attachments" ,
10767 .Sx "The Mailcap files" ,
10769 .Va mime-counter-evidence ,
10770 .Va mimetypes-load-control ,
10771 .Va pipe-TYPE/SUBTYPE ,
10772 .Va pipe-EXTENSION .
10775 .\" .Ss "The Mailcap files" {{{
10776 .Ss "The Mailcap files"
10778 .\" TODO MAILCAP DISABLED
10779 .Sy This feature is not available in v14.9.0, sorry!
10781 .Dq User Agent Configuration Mechanism
10782 which \*(UA \*(OPally supports.
10783 It defines a file format to be used to inform mail user agent programs
10784 about the locally-installed facilities for handling various data
10785 formats, i.e., about commands and how they can be used to display, edit
10786 etc. MIME part contents, as well as a default path search that includes
10787 multiple possible locations of
10791 environment variable that can be used to overwrite that (repeating here
10792 that it is not a search path, but instead a path search specification).
10793 Any existing files will be loaded in sequence, appending any content to
10794 the list of MIME type handler directives.
10798 files consist of a set of newline separated entries.
10799 Comment lines start with a number sign
10801 (in the first column!) and are ignored.
10802 Empty lines are also ignored.
10803 All other lines form individual entries that must adhere to the syntax
10805 To extend a single entry (not comment) its line can be continued on
10806 follow lines if newline characters are
10808 by preceding them with the reverse solidus character
10810 The standard does not specify how leading whitespace of follow lines
10811 is to be treated, therefore \*(UA retains it.
10815 entries consist of a number of semicolon
10817 separated fields, and the reverse solidus
10819 character can be used to escape any following character including
10820 semicolon and itself.
10821 The first two fields are mandatory and must occur in the specified
10822 order, the remaining fields are optional and may appear in any order.
10823 Leading and trailing whitespace of content is ignored (removed).
10826 The first field defines the MIME
10828 the entry is about to handle (case-insensitively, and no reverse solidus
10829 escaping is possible in this field).
10830 If the subtype is specified as an asterisk
10832 the entry is meant to match all subtypes of the named type, e.g.,
10834 would match any audio type.
10835 The second field defines the shell command which shall be used to
10837 MIME parts of the given type; it is implicitly called the
10844 shell commands message (MIME part) data is passed via standard input
10845 unless the given shell command includes one or more instances of the
10848 in which case these instances will be replaced with a temporary filename
10849 and the data will have been stored in the file that is being pointed to.
10852 shell commands data is assumed to be generated on standard output unless
10853 the given command includes (one ore multiple)
10855 In any case any given
10857 format is replaced with a(n already) properly quoted filename.
10858 Note that when a command makes use of a temporary file via
10860 then \*(UA will remove it again, as if the
10861 .Cd x-mailx-tmpfile ,
10862 .Cd x-mailx-tmpfile-fill
10864 .Cd x-mailx-tmpfile-unlink
10865 flags had been set; see below for more.
10868 The optional fields either define a shell command or an attribute (flag)
10869 value, the latter being a single word and the former being a keyword
10870 naming the field followed by an equals sign
10872 succeeded by a shell command, and as usual for any
10874 content any whitespace surrounding the equals sign will be removed, too.
10875 Optional fields include the following:
10878 .Bl -tag -width ".It Cd BaNg"
10880 A program that can be used to compose a new body or body part in the
10882 (Currently unused.)
10884 .It Cd composetyped
10887 field, but is to be used when the composing program needs to specify the
10889 header field to be applied to the composed data.
10890 (Currently unused.)
10893 A program that can be used to edit a body or body part in the given
10895 (Currently unused.)
10898 A program that can be used to print a message or body part in the given
10900 (Currently unused.)
10903 Specifies a program to be run to test some condition, e.g., the machine
10904 architecture, or the window system in use, to determine whether or not
10905 this mailcap entry applies.
10906 If the test fails, a subsequent mailcap entry should be sought; also see
10907 .Cd x-mailx-test-once .
10909 .It Cd needsterminal
10910 This flag field indicates that the given shell command must be run on
10911 an interactive terminal.
10912 \*(UA will temporarily release the terminal to the given command in
10913 interactive mode, in non-interactive mode this entry will be entirely
10914 ignored; this flag implies
10915 .Cd x-mailx-noquote .
10917 .It Cd copiousoutput
10918 A flag field which indicates that the output of the
10920 command will be an extended stream of textual output that can be
10921 (re)integrated into \*(UA's normal visual display.
10922 It is mutually exclusive with
10925 .Cd x-mailx-always .
10927 .It Cd textualnewlines
10928 A flag field which indicates that this type of data is line-oriented and
10929 that, if encoded in
10931 all newlines should be converted to canonical form (CRLF) before
10932 encoding, and will be in that form after decoding.
10933 (Currently unused.)
10935 .It Cd nametemplate
10936 This field gives a file name format, in which
10938 will be replaced by a random string, the joined combination of which
10939 will be used as the filename denoted by
10940 .Ev MAILX_FILENAME_TEMPORARY .
10941 One could specify that a GIF file being passed to an image viewer should
10942 have a name ending in
10945 .Ql nametemplate=%s.gif .
10946 Note that \*(UA ignores the name template unless that solely specifies
10947 a filename suffix that consists of (ASCII) alphabetic and numeric
10948 characters, the underscore and dot only.
10951 Names a file, in X11 bitmap (xbm) format, which points to an appropriate
10952 icon to be used to visually denote the presence of this kind of data.
10953 This field is not used by \*(UA.
10956 A textual description that describes this type of data.
10958 .It Cd x-mailx-always
10959 Extension flag field that denotes that the given
10961 command shall be executed even if multiple messages will be displayed
10963 Normally messages which require external viewers that produce output
10964 which does not integrate into \*(UA's visual display (i.e., do not have
10966 set) have to be addressed directly and individually.
10967 (To avoid cases where, e.g., a thousand PDF viewer instances are spawned
10970 .It Cd x-mailx-even-if-not-interactive
10971 An extension flag test field \(em by default handlers without
10973 are entirely ignored in non-interactive mode, but if this flag is set
10974 then their use will be considered.
10975 It is an error if this flag is set for commands that use the flag
10976 .Cd needsterminal .
10978 .It Cd x-mailx-noquote
10979 An extension flag field that indicates that even a
10982 command shall not be used to generate message quotes
10983 (as it would be by default).
10985 .It Cd x-mailx-async
10986 Extension flag field that denotes that the given
10988 command shall be executed asynchronously, without blocking \*(UA.
10989 Cannot be used in conjunction with
10990 .Cd needsterminal .
10992 .It Cd x-mailx-test-once
10993 Extension flag which denotes whether the given
10995 command shall be evaluated once only and the (boolean) result be cached.
10996 This is handy if some global unchanging condition is to be queried, like
10997 .Dq running under the X Window System .
10999 .It Cd x-mailx-tmpfile
11000 Extension flag field that requests creation of a zero-sized temporary
11001 file, the name of which is to be placed in the environment variable
11002 .Ev MAILX_FILENAME_TEMPORARY .
11003 It is an error to use this flag with commands that include a
11007 .It Cd x-mailx-tmpfile-fill
11008 Normally the MIME part content is passed to the handler via standard
11009 input; if this flag is set then the data will instead be written into
11011 .Cd x-mailx-tmpfile .
11012 In order to cause deletion of the temporary file you will have to set
11013 .Cd x-mailx-tmpfile-unlink
11015 It is an error to use this flag with commands that include a
11019 .It Cd x-mailx-tmpfile-unlink
11020 Extension flag field that requests that the temporary file shall be
11021 deleted automatically when the command loop is entered again at latest.
11022 (Do not use this for asynchronous handlers.)
11023 It is an error to use this flag with commands that include a
11025 format, or without also setting
11026 .Cd x-mailx-tmpfile
11028 .Cd x-mailx-tmpfile-fill .
11030 .It Cd x-mailx-tmpfile-keep
11033 implies the three tmpfile related flags above, but if you want, e.g.,
11035 and deal with the temporary file yourself, you can add in this flag to
11037 .Cd x-mailx-tmpfile-unlink .
11042 The standard includes the possibility to define any number of additional
11043 entry fields, prefixed by
11045 Flag fields apply to the entire
11047 entry \(em in some unusual cases, this may not be desirable, but
11048 differentiation can be accomplished via separate entries, taking
11049 advantage of the fact that subsequent entries are searched if an earlier
11050 one does not provide enough information.
11053 command needs to specify the
11057 command shall not, the following will help out the latter (with enabled
11061 level \*(UA will show information about handler evaluation):
11063 .Bd -literal -offset indent
11064 application/postscript; ps-to-terminal %s; needsterminal
11065 application/postscript; ps-to-terminal %s; compose=idraw %s
11069 In fields any occurrence of the format string
11071 will be replaced by the
11074 Named parameters from the
11076 field may be placed in the command execution line using
11078 followed by the parameter name and a closing
11081 The entire parameter should appear as a single command line argument,
11082 regardless of embedded spaces; thus:
11084 .Bd -literal -offset indent
11086 Content-type: multipart/mixed; boundary=42
11089 multipart/*; /usr/local/bin/showmulti \e
11090 %t %{boundary} ; composetyped = /usr/local/bin/makemulti
11092 # Executed shell command
11093 /usr/local/bin/showmulti multipart/mixed 42
11097 .\" TODO v15: Mailcap: %n,%F
11098 Note that \*(UA does not support handlers for multipart MIME parts as
11099 shown in this example (as of today).
11100 \*(UA does not support the additional formats
11104 An example file, also showing how to properly deal with the expansion of
11106 which includes any quotes that are necessary to make it a valid shell
11107 argument by itself and thus will cause undesired behaviour when placed
11108 in additional user-provided quotes:
11110 .Bd -literal -offset indent
11112 text/richtext; richtext %s; copiousoutput
11114 text/x-perl; perl -cWT %s
11116 application/pdf; \e
11118 trap "rm -f ${infile}" EXIT\e; \e
11119 trap "exit 75" INT QUIT TERM\e; \e
11121 x-mailx-async; x-mailx-tmpfile-keep
11123 application/*; echo "This is \e"%t\e" but \e
11124 is 50 \e% Greek to me" \e; < %s head -c 1024 | cat -vET; \e
11125 copiousoutput; x-mailx-noquote
11130 .Sx "HTML mail and MIME attachments" ,
11131 .Sx "The mime.types files" ,
11134 .Va mime-counter-evidence ,
11135 .Va pipe-TYPE/SUBTYPE ,
11136 .Va pipe-EXTENSION .
11139 .\" .Ss "The .netrc file" {{{
11140 .Ss "The .netrc file"
11144 file contains user credentials for machine accounts.
11145 The default location in the user's
11147 directory may be overridden by the
11149 environment variable.
11150 The file consists of space, tabulator or newline separated tokens.
11151 \*(UA implements a parser that supports a superset of the original BSD
11152 syntax, but users should nonetheless be aware of portability glitches
11153 of that file format, shall their
11155 be usable across multiple programs and platforms:
11158 .Bl -bullet -compact
11160 BSD does not support single, but only double quotation marks, e.g.,
11161 .Ql password="pass with spaces" .
11163 BSD (only?) supports escaping of single characters via a reverse solidus
11164 (e.g., a space can be escaped via
11166 in- as well as outside of a quoted string.
11168 BSD does not require a final quotation mark of the last user input token.
11170 The original BSD (Berknet) parser also supported a format which allowed
11171 tokens to be separated with commas \(en whereas at least Hewlett-Packard
11172 still seems to support this syntax, \*(UA does not!
11174 As a non-portable extension some widely-used programs support
11175 shell-style comments: if an input line starts, after any amount of
11176 whitespace, with a number sign
11178 then the rest of the line is ignored.
11180 Whereas other programs may require that the
11182 file is accessible by only the user if it contains a
11184 token for any other
11188 \*(UA will always require these strict permissions.
11192 Of the following list of supported tokens \*(UA only uses (and caches)
11197 At runtime the command
11199 can be used to control \*(UA's
11203 .Bl -tag -width ".It Cd BaNg"
11204 .It Cd machine Ar name
11205 The hostname of the entries' machine, lowercase-normalized by \*(UA
11207 Any further file content, until either end-of-file or the occurrence
11212 first-class token is bound (only related) to the machine
11215 As an extension that should not be the cause of any worries
11216 \*(UA supports a single wildcard prefix for
11218 .Bd -literal -offset indent
11219 machine *.example.com login USER password PASS
11220 machine pop3.example.com login USER password PASS
11221 machine smtp.example.com login USER password PASS
11227 .Ql pop3.example.com ,
11231 .Ql local.smtp.example.com .
11232 Note that in the example neither
11233 .Ql pop3.example.com
11235 .Ql smtp.example.com
11236 will be matched by the wildcard, since the exact matches take
11237 precedence (it is however faster to specify it the other way around).
11240 This is the same as
11242 except that it is a fallback entry that is used shall none of the
11243 specified machines match; only one default token may be specified,
11244 and it must be the last first-class token.
11246 .It Cd login Ar name
11247 The user name on the remote machine.
11249 .It Cd password Ar string
11250 The user's password on the remote machine.
11252 .It Cd account Ar string
11253 Supply an additional account password.
11254 This is merely for FTP purposes.
11256 .It Cd macdef Ar name
11258 A macro is defined with the specified
11260 it is formed from all lines beginning with the next line and continuing
11261 until a blank line is (consecutive newline characters are) encountered.
11264 entries cannot be utilized by multiple machines, too, but must be
11265 defined following the
11267 they are intended to be used with.)
11270 exists, it is automatically run as the last step of the login process.
11271 This is merely for FTP purposes.
11278 .\" .Sh EXAMPLES {{{
11281 .\" .Ss "An example configuration" {{{
11282 .Ss "An example configuration"
11284 .Bd -literal -offset indent
11285 # This example assumes v15.0 compatibility mode
11288 # Request strict transport security checks!
11289 set ssl-verify=strict
11291 # Where are the up-to-date SSL certificates?
11292 # (Since we manage up-to-date ones explicitly, do not use any,
11293 # possibly outdated, default certificates shipped with OpenSSL)
11294 #set ssl-ca-dir=/etc/ssl/certs
11295 set ssl-ca-file=/etc/ssl/certs/ca-certificates.crt
11296 set ssl-ca-no-defaults
11297 #set ssl-ca-flags=partial-chain
11298 wysh set smime-ca-file="${ssl-ca-file}" \e
11299 smime-ca-no-defaults #smime-ca-flags="${ssl-ca-flags}"
11301 # Do not use protocols older than TLS v1.2.
11302 # Change this only when the remote server does not support it:
11303 # maybe use ssl-protocol-HOST (or -USER@HOST) syntax to define
11304 # such explicit exceptions, then, e.g.
11305 # set ssl-protocol-exam.ple='-ALL,+TLSv1.1'
11306 set ssl-protocol='-ALL,+TLSv1.2'
11308 # Explicitly define the list of ciphers, which may improve security,
11309 # especially with protocols older than TLS v1.2. See ciphers(1).
11310 # Including "@STRENGTH" will sort the final list by algorithm strength.
11311 # In reality it is possibly best to only use ssl-cipher-list-HOST
11312 # (or -USER@HOST), as necessary, again..
11313 set ssl-cipher-list=TLSv1.2:!aNULL:!eNULL:@STRENGTH
11314 # TLSv1.2:!aNULL:!eNULL:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:\e
11315 DHE-RSA-AES256-SHA:@STRENGTH
11316 # ALL:!aNULL:!eNULL:!MEDIUM:!LOW:!MD5:!RC4:!EXPORT:@STRENGTH
11318 # Essential setting: select allowed character sets
11319 set sendcharsets=utf-8,iso-8859-1
11321 # A very kind option: when replying to a message, first try to
11322 # use the same encoding that the original poster used herself!
11323 set reply-in-same-charset
11325 # When replying to or forwarding a message the comment and name
11326 # parts of email addresses are removed unless this variable is set
11329 # When sending messages, wait until the Mail-Transfer-Agent finishs.
11330 # Only like this you will be able to see errors reported through the
11331 # exit status of the MTA (including the builtin SMTP one)!
11334 # Only use builtin MIME types, no mime.types(5) files
11335 set mimetypes-load-control
11337 # Default directory where we act in (relative to $HOME)
11339 # A leading "+" (often) means: under *folder*
11340 # *record* is used to save copies of sent messages
11341 set MBOX=+mbox.mbox record=+sent.mbox DEAD=+dead.txt
11343 # Make "file mymbox" and "file myrec" go to..
11344 shortcut mymbox %:+mbox.mbox myrec +sent.mbox
11346 # Not really optional, e.g., for S/MIME
11347 set from='Your Name <address@exam.ple>'
11349 # It may be necessary to set hostname and/or smtp-hostname
11350 # if the "SERVER" of mta and "domain" of from do not match.
11351 # The `urlencode' command can be used to encode USER and PASS
11352 set mta=(smtps?|submission)://[USER[:PASS]@]SERVER[:PORT] \e
11353 smtp-auth=login/plain... \e
11356 # Never refuse to start into interactive mode, and more
11358 colour-pager crt= \e
11359 followup-to followup-to-honour=ask-yes \e
11360 history-file=+.\*(uAhist history-size=-1 history-gabby \e
11361 mime-counter-evidence=0xE \e
11362 prompt='?\e?!\e![\e${account}#\e${mailbox-display}]? ' \e
11363 reply-to-honour=ask-yes \e
11366 # Only include the selected header fields when typing messages
11367 headerpick type retain from_ date from to cc subject \e
11368 message-id mail-followup-to reply-to
11369 # ...when forwarding messages
11370 headerpick forward retain subject date from to cc
11371 # ...when saving message, etc.
11372 #headerpick save ignore ^Original-.*$ ^X-.*$
11374 # Some mailing lists
11375 mlist '@xyz-editor\e.xyz$' '@xyzf\e.xyz$'
11376 mlsubscribe '^xfans@xfans\e.xyz$'
11378 # A real life example of a very huge free mail provider
11379 # Instead of directly placing content inside `account',
11380 # we `define' a macro: like that we can switch "accounts"
11381 # from within *on-compose-splice*, for example!
11383 set folder=~/spool/XooglX inbox=+syste.mbox sent=+sent
11384 set from='Your Name <address@examp.ple>'
11385 set mta=smtp://USER:PASS@smtp.gmXil.com smtp-use-starttls
11391 # Here is a pretty large one which does not allow sending mails
11392 # if there is a domain name mismatch on the SMTP protocol level,
11393 # which would bite us if the value of from does not match, e.g.,
11394 # for people who have a sXXXXeforge project and want to speak
11395 # with the mailing list under their project account (in from),
11396 # still sending the message through their normal mail provider
11398 set folder=~/spool/XandeX inbox=+syste.mbox sent=+sent
11399 set from='Your Name <address@exam.ple>'
11400 set mta=smtps://USER:PASS@smtp.yaXXex.ru:465 \e
11401 hostname=yaXXex.com smtp-hostname=
11407 # Create some new commands so that, e.g., `ls /tmp' will..
11408 commandalias lls '!ls ${LS_COLOR_FLAG} -aFlrS'
11409 commandalias llS '!ls ${LS_COLOR_FLAG} -aFlS'
11410 commandalias ls '!ls ${LS_COLOR_FLAG} -aFrS'
11411 commandalias lS '!ls ${LS_COLOR_FLAG} -aFS'
11412 commandalias lla '!ls ${LS_COLOR_FLAG} -aFlr'
11413 commandalias llA '!ls ${LS_COLOR_FLAG} -aFl'
11414 commandalias la '!ls ${LS_COLOR_FLAG} -aFr'
11415 commandalias lA '!ls ${LS_COLOR_FLAG} -aF'
11416 commandalias ll '!ls ${LS_COLOR_FLAG} -aFltr'
11417 commandalias lL '!ls ${LS_COLOR_FLAG} -aFlt'
11418 commandalias l '!ls ${LS_COLOR_FLAG} -aFtr'
11419 commandalias L '!ls ${LS_COLOR_FLAG} -aFt'
11421 # We do not support gpg(1) directly yet. But simple --clearsign'd
11422 # message parts can be dealt with as follows:
11425 wysh set pipe-text/plain=$'@*#++=@\e
11426 < "${MAILX_FILENAME_TEMPORARY}" awk \e
11427 -v TMPFILE="${MAILX_FILENAME_TEMPORARY}" \e'\e
11429 /^-----BEGIN PGP SIGNED MESSAGE-----/,/^$/ {\e
11432 print "--- GPG --verify ---";\e
11433 system("gpg --verify " TMPFILE " 2>&1");\e
11434 print "--- GPG --verify ---";\e
11438 /^-----BEGIN PGP SIGNATURE-----/,\e
11439 /^-----END PGP SIGNATURE-----/{\e
11446 commandalias V '\e'call V
11449 !printf 'Key IDs to gpg --recv-keys: ';\e
11451 gpg --recv-keys ${keyids};
11453 commandalias RK call RK
11457 When storing passwords in
11459 appropriate permissions should be set on this file with
11460 .Ql $ chmod 0600 \*(ur .
11463 is available user credentials can be stored in the central
11465 file instead; e.g., here is a different version of the example account
11466 that sets up SMTP and POP3:
11468 .Bd -literal -offset indent
11470 set folder=~/spool/XandeX inbox=+syste.mbox sent=+sent
11471 set from='Your Name <address@exam.ple>'
11473 # Load an encrypted ~/.netrc by uncommenting the next line
11474 #set netrc-pipe='gpg -qd ~/.netrc.pgp'
11476 set mta=smtps://smtp.yXXXXx.ru:465 \e
11477 smtp-hostname= hostname=yXXXXx.com
11478 set pop3-keepalive=240 pop3-no-apop-pop.yXXXXx.ru
11479 commandalias xp fi pop3s://pop.yXXXXx.ru
11491 .Bd -literal -offset indent
11492 machine *.yXXXXx.ru login USER password PASS
11496 This configuration should now work just fine:
11499 .Dl $ echo text | \*(uA -dvv -AXandeX -s Subject user@exam.ple
11502 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
11503 .Ss "Signed and encrypted messages with S/MIME"
11505 \*(OP S/MIME provides two central mechanisms:
11506 message signing and message encryption.
11507 A signed message contains some data in addition to the regular text.
11508 The data can be used to verify that the message was sent using a valid
11509 certificate, that the sender's address in the message header matches
11510 that in the certificate, and that the message text has not been altered.
11511 Signing a message does not change its regular text;
11512 it can be read regardless of whether the recipient's software is able to
11516 It is thus usually possible to sign all outgoing messages if so desired.
11517 Encryption, in contrast, makes the message text invisible for all people
11518 except those who have access to the secret decryption key.
11519 To encrypt a message, the specific recipient's public encryption key
11521 It is therefore not possible to send encrypted mail to people unless their
11522 key has been retrieved from either previous communication or public key
11524 A message should always be signed before it is encrypted.
11525 Otherwise, it is still possible that the encrypted message text is
11529 A central concept to S/MIME is that of the certification authority (CA).
11530 A CA is a trusted institution that issues certificates.
11531 For each of these certificates it can be verified that it really
11532 originates from the CA, provided that the CA's own certificate is
11534 A set of CA certificates is usually delivered with OpenSSL and installed
11536 If you trust the source of your OpenSSL software installation,
11537 this offers reasonable security for S/MIME on the Internet.
11539 .Va smime-ca-no-defaults
11540 to avoid using the default certificate and point
11544 to a trusted pool of certificates.
11545 In general, a certificate cannot be more secure than the method its CA
11546 certificate has been retrieved with.
11549 The first thing you need for participating in S/MIME message exchange is
11550 your personal certificate, including a private key.
11551 The certificate contains public information, in particular your name and
11552 your email address(es), and the public key that is used by others to
11553 encrypt messages for you,
11554 and to verify signed messages they supposedly received from you.
11555 The certificate is included in each signed message you send.
11556 The private key must be kept secret.
11557 It is used to decrypt messages that were previously encrypted with your
11558 public key, and to sign messages.
11561 For personal use it is recommended that you get a S/MIME certificate
11562 from one of the major CAs on the Internet using your WWW browser.
11563 Many CAs offer such certificates for free.
11565 .Lk https://www.CAcert.org
11566 which issues client and server certificates to members of their
11567 community for free; their root certificate
11568 .Pf ( Lk https://\:www.cacert.org/\:certs/\:root.crt )
11569 is often not in the default set of trusted CA root certificates, though,
11570 which means you will have to download their root certificate separately
11571 and ensure it is part of our S/MIME certificate validation chain by
11574 or as a vivid member of the
11575 .Va smime-ca-file .
11576 But let us take a step-by-step tour on how to setup S/MIME with
11577 a certificate from CAcert.org despite this situation!
11580 First of all you will have to become a member of the CAcert.org
11581 community, simply by registrating yourself via the web interface.
11582 Once you are, create and verify all email addresses you want to be able
11583 to create signed and encrypted messages for/with using the corresponding
11584 entries of the web interface.
11585 Now ready to create S/MIME certificates, so let us create a new
11586 .Dq client certificate ,
11587 ensure to include all email addresses that should be covered by the
11588 certificate in the following web form, and also to use your name as the
11592 Create a private key and a certificate request on your local computer
11593 (please see the manual pages of the used commands for more in-depth
11594 knowledge on what the used arguments etc. do):
11597 .Dl openssl req -nodes -newkey rsa:4096 -keyout key.pem -out creq.pem
11600 Afterwards copy-and-paste the content of
11602 into the certificate-request (CSR) field of the web form on the
11603 CAcert.org website (you may need to unfold some
11604 .Dq advanced options
11605 to see the corresponding text field).
11606 This last step will ensure that your private key (which never left your
11607 box) and the certificate belong together (through the public key that
11608 will find its way into the certificate via the certificate-request).
11609 You are now ready and can create your CAcert certified certificate.
11610 Download and store or copy-and-paste it as
11615 In order to use your new S/MIME setup a combined private key/public key
11616 (certificate) file has to be created:
11619 .Dl cat key.pem pub.crt > ME@HERE.com.paired
11622 This is the file \*(UA will work with.
11623 If you have created your private key with a passphrase then \*(UA will
11624 ask you for it whenever a message is signed or decrypted.
11625 Set the following variables to henceforth use S/MIME (setting
11627 is of interest for verification only):
11629 .Bd -literal -offset indent
11630 set smime-ca-file=ALL-TRUSTED-ROOT-CERTS-HERE \e
11631 smime-sign-cert=ME@HERE.com.paired \e
11632 smime-sign-message-digest=SHA256 \e
11637 From each signed message you send, the recipient can fetch your
11638 certificate and use it to send encrypted mail back to you.
11639 Accordingly if somebody sends you a signed message, you can do the same,
11642 command to check the validity of the certificate.
11645 Variables of interest for S/MIME signing:
11647 .Va smime-ca-file ,
11648 .Va smime-ca-flags ,
11649 .Va smime-ca-no-defaults ,
11650 .Va smime-crl-dir ,
11651 .Va smime-crl-file ,
11653 .Va smime-sign-cert ,
11654 .Va smime-sign-include-certs
11656 .Va smime-sign-message-digest .
11659 After it has been verified save the certificate via
11661 and tell \*(UA that it should use it for encryption for further
11662 communication with that somebody:
11664 .Bd -literal -offset indent
11666 set smime-encrypt-USER@HOST=FILENAME \e
11667 smime-cipher-USER@HOST=AES256
11671 Additional variables of interest for S/MIME en- and decryption:
11674 .Va smime-encrypt-USER@HOST .
11677 You should carefully consider if you prefer to store encrypted messages
11679 If you do, anybody who has access to your mail folders can read them,
11680 but if you do not, you might be unable to read them yourself later if
11681 you happen to lose your private key.
11684 command saves messages in decrypted form, while the
11688 commands leave them encrypted.
11691 Note that neither S/MIME signing nor encryption applies to message
11692 subjects or other header fields yet.
11693 Thus they may not contain sensitive information for encrypted messages,
11694 and cannot be trusted even if the message content has been verified.
11695 When sending signed messages,
11696 it is recommended to repeat any important header information in the
11700 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
11701 .Ss "Using CRLs with S/MIME or SSL/TLS"
11703 \*(OP Certification authorities (CAs) issue certificate revocation
11704 lists (CRLs) on a regular basis.
11705 These lists contain the serial numbers of certificates that have been
11706 declared invalid after they have been issued.
11707 Such usually happens because the private key for the certificate has
11709 because the owner of the certificate has left the organization that is
11710 mentioned in the certificate, etc.
11711 To seriously use S/MIME or SSL/TLS verification,
11712 an up-to-date CRL is required for each trusted CA.
11713 There is otherwise no method to distinguish between valid and
11714 invalidated certificates.
11715 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
11716 the Internet, so they have to be retrieved by some external mechanism.
11719 \*(UA accepts CRLs in PEM format only;
11720 CRLs in DER format must be converted, like, e.\|g.:
11723 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
11726 To tell \*(UA about the CRLs, a directory that contains all CRL files
11727 (and no other files) must be created.
11732 variables, respectively, must then be set to point to that directory.
11733 After that, \*(UA requires a CRL to be present for each CA that is used
11734 to verify a certificate.
11737 .\" .Ss "Handling spam" {{{
11738 .Ss "Handling spam"
11740 \*(OP \*(UA can make use of several spam interfaces for the purpose of
11741 identification of, and, in general, dealing with spam messages.
11742 A precondition of most commands in order to function is that the
11744 variable is set to one of the supported interfaces.
11745 Once messages have been identified as spam their (volatile)
11747 state can be prompted: the
11751 message specifications will address respective messages and their
11753 entries will be used when displaying the
11755 in the header display.
11760 rates the given messages and sets their
11763 If the spam interface offers spam scores those can also be displayed in
11764 the header display by including the
11774 will interact with the Bayesian filter of the chosen interface and learn
11775 the given messages as
11779 respectively; the last command can be used to cause
11781 of messages; it adheres to their current
11783 state and thus reverts previous teachings.
11788 will simply set and clear, respectively, the mentioned volatile
11790 message flag, without any interface interaction.
11799 requires a running instance of the
11801 server in order to function, started with the option
11803 shall Bayesian filter learning be possible.
11805 .Bd -literal -offset indent
11806 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
11807 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \e
11808 --daemonize [--local] [--allow-tell]
11812 Thereafter \*(UA can make use of these interfaces:
11814 .Bd -literal -offset indent
11815 $ \*(uA -Sspam-interface=spamc -Sspam-maxsize=500000 \e
11816 -Sspamc-command=/usr/local/bin/spamc \e
11817 -Sspamc-arguments="-U /tmp/.spamsock" -Sspamc-user=
11819 $ \*(uA -Sspam-interface=spamc -Sspam-maxsize=500000 \e
11820 -Sspamc-command=/usr/local/bin/spamc \e
11821 -Sspamc-arguments="-d localhost -p 2142" -Sspamc-user=
11825 Using the generic filter approach allows usage of programs like
11827 Here is an example, requiring it to be accessible via
11830 .Bd -literal -offset indent
11831 $ \*(uA -Sspam-interface=filter -Sspam-maxsize=500000 \e
11832 -Sspamfilter-ham="bogofilter -n" \e
11833 -Sspamfilter-noham="bogofilter -N" \e
11834 -Sspamfilter-nospam="bogofilter -S" \e
11835 -Sspamfilter-rate="bogofilter -TTu 2>/dev/null" \e
11836 -Sspamfilter-spam="bogofilter -s" \e
11837 -Sspamfilter-rate-scanscore="1;^(.+)$"
11841 Because messages must exist on local storage in order to be scored (or
11842 used for Bayesian filter training), it is possibly a good idea to
11843 perform the local spam check last:
11845 .Bd -literal -offset indent
11846 define spamdelhook {
11848 spamset (header x-dcc-brand-metrics "bulk")
11849 # Server-side spamassassin(1)
11850 spamset (header x-spam-flag "YES")
11851 del :s # TODO we HAVE to be able to do `spamrate :u ! :sS'
11852 move :S +maybe-spam
11855 move :S +maybe-spam
11857 set folder-hook-FOLDER=spamdelhook
11861 See also the documentation for the variables
11862 .Va spam-interface , spam-maxsize ,
11863 .Va spamc-command , spamc-arguments , spamc-user ,
11864 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
11867 .Va spamfilter-rate-scanscore .
11875 In general it is a good idea to turn on
11881 twice) if something does not work well.
11882 Very often a diagnostic message can be produced that leads to the
11883 problems' solution.
11885 .\" .Ss "\*(UA shortly hangs on startup" {{{
11886 .Ss "\*(UA shortly hangs on startup"
11888 This can have two reasons, one is the necessity to wait for a file lock
11889 and cannot be helped, the other being that \*(UA calls the function
11891 in order to query the nodename of the box (sometimes the real one is
11892 needed instead of the one represented by the internal variable
11894 One may have varying success by ensuring that the real hostname and
11898 or, more generally, that the name service is properly setup \(en
11901 return the expected value?
11902 Does this local hostname has a domain suffix?
11903 RFC 6762 standardized the link-local top-level domain
11905 try again after adding an (additional) entry with this extension.
11908 .\" .Ss "\*(UA exits quick, and output is cleared away" {{{
11909 .Ss "\*(UA exits quick, and output is cleared away"
11911 When this happens even with
11913 set, then this most likely indicates a problem with the creation of
11914 so-called dotlock files: setting
11915 .Va dotlock-ignore-error
11916 should overcome this situation.
11917 This only avoids symptoms, it does not address the problem, though.
11918 Since the output is cleared away \*(UA has support for
11919 .Sx "On terminal control and line editor" ,
11920 and switches to the
11922 which causes the output clearance: by doing
11923 .Ql set termcap='smcup='
11924 this mode can be suppressed, and by setting
11926 (twice) the actual problem should be reported.
11929 .\" .Ss "I cannot login to Google mail aka GMail" {{{
11930 .Ss "I cannot login to Google mail aka GMail"
11932 Since 2014 some free service providers classify programs as
11934 unless they use a special authentification method (OAuth 2.0) which
11935 was not standardized for non-HTTP protocol authentication token query
11936 until August 2015 (RFC 7628).
11939 Different to Kerberos / GSSAPI, which is developed since the mid of the
11940 1980s, where a user can easily create a local authentication ticket for
11941 her- and himself with the locally installed
11943 program, that protocol has no such local part but instead requires
11944 a world-wide-web query to create or fetch a token; since there is no
11945 local cache this query would have to be performed whenever \*(UA is
11946 invoked (in interactive sessions situation may differ).
11949 \*(UA does not support OAuth.
11950 Because of this it is necessary to declare \*(UA a
11951 .Dq less secure app
11952 (on the providers account web page) in order to read and send mail.
11953 However, it also seems possible to take the following steps instead:
11958 give the provider the number of a mobile phone,
11961 .Dq 2-Step Verification ,
11963 create an application specific password (16 characters), and
11965 use that special password instead of the real Google account password in
11966 \*(UA (for more on that see the section
11967 .Sx "On URL syntax and credential lookup" ) .
11971 .\" .Ss "Not \(dqdefunctional\(dq, but the editor key does not work" {{{
11972 .Ss "Not \(dqdefunctional\(dq, but the editor key does not work"
11974 It can happen that the terminal library (see
11975 .Sx "On terminal control and line editor",
11978 reports different codes than the terminal really sends, in which case
11979 \*(UA will tell that a key binding is functional, but will not be able to
11980 recognize it because the received data does not match anything expected.
11985 ings will show the byte sequences that are expected.
11988 To overcome the situation, use, e.g., the program
11990 in conjunction with the command line option
11992 if available, to see the byte sequences which are actually produced
11993 by keypresses, and use the variable
11995 to make \*(UA aware of them.
11996 E.g., the terminal this is typed on produces some false sequences, here
11997 an example showing the shifted home key:
11999 .Bd -literal -offset indent
12002 # 1B 5B=[ 31=1 3B=; 32=2 48=H
12007 ? \*(uA -v -Stermcap='kHOM=\eE[H'
12016 .\" .Sh "SEE ALSO" {{{
12026 .Xr spamassassin 1 ,
12035 .Xr mailwrapper 8 ,
12040 .\" .Sh HISTORY {{{
12043 M. Douglas McIlroy writes in his article
12044 .Dq A Research UNIX Reader: Annotated Excerpts \
12045 from the Programmer's Manual, 1971-1986
12048 command already appeared in First Edition
12052 .Bd -ragged -offset indent
12053 Electronic mail was there from the start.
12054 Never satisfied with its exact behavior, everybody touched it at one
12055 time or another: to assure the safety of simultaneous access, to improve
12056 privacy, to survive crashes, to exploit uucp, to screen out foreign
12057 freeloaders, or whatever.
12058 Not until v7 did the interface change (Thompson).
12059 Later, as mail became global in its reach, Dave Presotto took charge and
12060 brought order to communications with a grab-bag of external networks
12066 Mail was written in 1978 by Kurt Shoens and developed as part of the
12069 distribution until 1995.
12070 Mail has then seen further development in open source
12072 variants, noticeably by Christos Zoulas in
12074 Based upon this Nail, later Heirloom Mailx, was developed by Gunnar
12075 Ritter in the years 2000 until 2008.
12076 Since 2012 S-nail is maintained by Steffen (Daode) Nurpmeso.
12077 This man page is derived from
12078 .Dq The Mail Reference Manual
12079 that was originally written by Kurt Shoens.
12085 .An "Kurt Shoens" ,
12086 .An "Edward Wang" ,
12087 .An "Keith Bostic" ,
12088 .An "Christos Zoulas" ,
12089 .An "Gunnar Ritter" ,
12090 .An "Steffen Nurpmeso" Aq Mt s-nail-users@lists.sourceforge.net
12092 .Mt s-mailx@sdaoden.eu ) .
12095 .\" .Sh CAVEATS {{{
12098 \*(ID Interrupting an operation via
12102 from anywhere else but a command prompt is very problematic and likely
12103 to leave the program in an undefined state: many library functions
12104 cannot deal with the
12106 that this software (still) performs; even though efforts have been taken
12107 to address this, no sooner but in v15 it will have been worked out:
12108 interruptions have not been disabled in order to allow forceful breakage
12109 of hanging network connections, for example (all this is unrelated to
12113 The SMTP and POP3 protocol support of \*(UA is very basic.
12114 Also, if it fails to contact its upstream SMTP server, it will not make
12115 further attempts to transfer the message at a later time (setting
12120 If this is a concern, it might be better to set up a local SMTP server
12121 that is capable of message queuing.
12127 After deleting some message of a POP3 mailbox the header summary falsely
12128 claims that there are no messages to display, one needs to perform
12129 a scroll or dot movement to restore proper state.
12131 In threaded display a power user may encounter crashes very
12132 occasionally (this is may and very).
12136 in the source repository lists future directions.