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 (or the specified file) for processing;
324 when \*(UA is quit, it writes undeleted messages back to this file
330 argument will undergo some special
331 .Sx "Filename transformations"
336 is not a argument to the flag
338 but is instead taken from the command line after option processing has
342 that starts with a hyphen-minus, prefix with a relative path, as in
343 .Ql ./-hyphenbox.mbox .
347 Display a summary of the
349 of all messages in the specified mailbox or system
352 A configurable summary view is available via the
358 Show a short usage summary.
359 Because of widespread use a
361 argument will have the same effect.
367 to ignore tty interrupt signals.
370 .It Fl L Ar spec-list
371 Display a summary of all
373 of only those messages in the specified mailbox or the system
379 .Sx "Specifying messages"
386 option has been given in addition no header summary is produced,
387 but \*(UA will instead indicate via its exit status whether
393 note that any verbose output is suppressed in this mode and must instead
394 be enabled explicitly (e.g., by using the option
399 Special send mode that will flag standard input with the MIME
403 and use it as the main message body.
404 \*(ID Using this option will bypass processing of
405 .Va message-inject-head ,
408 .Va message-inject-tail .
414 Special send mode that will MIME classify the specified
416 and use it as the main message body.
417 \*(ID Using this option will bypass processing of
418 .Va message-inject-head ,
421 .Va message-inject-tail .
427 inhibit the initial display of message headers when reading mail or
428 editing a mail folder by calling
430 for the internal variable
435 Standard flag that inhibits reading the system wide
440 allows more control over the startup sequence; also see
441 .Sx "Resource files" .
445 Special send mode that will initialize the message body with the
446 contents of the specified
448 which may be standard input
450 only in non-interactive context.
456 Any folder opened will be in read-only mode.
460 .It Fl r Ar from-addr
461 The source address that appears in the
464 header of a message (or in the
467 header if the former contains multiple addresses) is not used for
468 relaying and delegating a message over the wire via SMTP, but instead an
469 envelope will enwrap the message content and provide the necessary
470 information (i.e., the RFC 5321 reverse-path, also used to report, e.g.,
471 delivery errors) to transmit the message to its destination(s).
472 Whereas said headers and internal variables will be used by \*(UA to
473 create the envelope if the builtin SMTP
475 (Mail-Transfer-Agent) is used, a file-based MTA will instead use the
476 identity of the message-originating user.
478 This command line option can be used to specify the reverse-path, to be
479 passed to a file-based
481 when a message is sent, via
482 .Ql -f Ar from-addr .
485 include a user name, then the address components will be separated and
486 the name part will be passed to a file-based
492 is also assigned to the internal variable
494 Many default installations and sites disallow explicit overriding of the
495 user identity which could be adjusted by this option, unless either
497 has been configured accordingly, or the user is member of a group with
498 special privileges, respectively.
500 If an empty string is passed as
502 then the content of the variable
504 (or, if that contains multiple addresses,
506 will be evaluated and used for this purpose whenever the file-based
509 Note that \*(UA by default, without
511 that is, neither passes
515 command line options to a file-based MTA by itself, unless this
516 automatic deduction is enforced by
518 ing the internal variable
519 .Va r-option-implicit .
523 .It Fl S Ar var Ns Op = Ns value
527 iable and, in case of a non-boolean variable which has a value, assign
531 .Sx "INTERNAL VARIABLES"
535 may be overwritten from within resource files,
536 the command line setting will be reestablished after all resource files
541 Specify the subject of the message to be sent.
542 Newline (NL) and carriage-return (CR) bytes are invalid and will be
543 normalized to space (SP) characters.
547 The message given (on standard input) is expected to contain, separated
548 from the message body by an empty line, a message header with
553 fields giving its recipients, which will be added to any recipients
554 specified on the command line.
555 If a message subject is specified via
557 then it will be used in favour of one given on the command line.
573 .Ql Mail-Followup-To: ,
574 by default created automatically dependent on message context, will
575 be used if specified (a special address massage will however still occur
577 Any other custom header field (also see
580 is passed through entirely
581 unchanged, and in conjunction with the option
583 it is possible to embed
584 .Sx "COMMAND ESCAPES" .
592 .Sx "primary system mailbox"
595 appropriate privileges presumed; effectively identical to
605 will also show the list of
607 .Ql $ \*(uA -Xversion -Xx .
612 ting the internal variable
614 enables display of some informational context messages.
615 Using it twice increases the level of verbosity.
619 Add the given (or multiple for a multiline argument)
621 to the list of commands to be executed,
622 as a last step of program startup, before normal operation starts.
623 This is the only possibility to execute commands in non-interactive mode
624 when reading startup files is actively prohibited.
625 The commands will be evaluated as a unit, just as via
627 but different to that errors won't stop evaluation.
631 .Va batch-exit-on-error .
636 .Sx "COMMAND ESCAPES"
637 even if not in interactive mode.
638 This can be used to, e.g., automatically format the composed message
639 text before sending the message:
640 .Bd -literal -offset indent
641 $ ( echo 'line one. Word. Word2.'; \e
642 echo '~| /usr/bin/fmt -tuw66' ) |\e
643 LC_ALL=C \*(uA -:/ -Sttycharset=utf-8 -d~ bob@exam.ple
649 In batch mode the full set of commands is available, just like in
650 interactive mode, standard input is made line buffered, and diverse
651 .Sx "INTERNAL VARIABLES"
652 are adjusted for batch necessities, e.g., it
668 .Sx "COMMAND ESCAPES"
669 is enabled in compose mode.
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
752 that would otherwise occur (see
753 .Sx "Message states" ) ,
756 to not remove empty system (MBOX) mailbox files in order not to mangle
757 file permissions when files eventually get recreated \(en
758 \*(UA will remove all empty (MBOX) mailbox files unless this variable is
761 .Pf ( Ev POSIXLY_CORRECT )
762 mode has been enabled.
763 The file mode creation mask is explicitly managed via
769 in order to synchronize \*(UA with the exit status report of the used
774 to enter interactive startup even if the initial mailbox is empty,
776 to allow editing of headers as well as
778 to not strip down addresses in compose mode, and
780 to include the message that is being responded to when
785 contains some more complete configuration examples.
788 .\" .Ss "On sending mail, and non-interactive mode" {{{
789 .Ss "On sending mail, and non-interactive mode"
791 To send a message to one or more people, using a local or a builtin
793 (Mail-Transfer-Agent) transport to actually deliver the generated mail
794 message, \*(UA can be invoked with arguments which are the names of
795 people to whom the mail will be sent, and the command line options
799 can be used to add (blind) carbon copy receivers:
801 .Bd -literal -offset indent
803 $ \*(uA -s ubject -a ttach.txt bill@exam.ple
805 # But... try it in an isolated dry-run mode (-d) first
806 $ LC_ALL=C \*(uA -d -:/ -Ssendwait \e
807 -b bcc@exam.ple -c cc@exam.ple \e
808 -. '(Lovely) Bob <bob@exam.ple>' eric@exam.ple
811 $ LC_ALL=C \*(uA -d -:/ -Sv15-compat -Ssendwait \e
812 -S 'mta=smtps://mylogin@exam.ple:465' -Ssmtp-auth=login \e
813 -S 'from=scriptreply@exam.ple' \e
819 If standard input is a terminal rather than the message to be sent,
820 the user is expected to type in the message contents.
821 In this compose mode \*(UA treats lines beginning with the character
823 special \(en these are so-called
824 .Sx "COMMAND ESCAPES" ,
825 which can be used to read in files, process shell commands, add and edit
826 attachments and more; e.g., the command escape
828 will start the text editor to revise the message in its current state,
830 allows editing of the most important message headers, with
832 custom headers can be created (more specifically than with
835 gives an overview of most other available command escapes.
839 at the beginning of an empty line leaves compose mode and causes the
840 message to be sent, whereas typing
843 twice will abort the current letter (saving its contents in the file
849 Messages are sent asynchronously, without supervision, unless the variable
851 is set, therefore send errors are not recognizable until then.
857 .Sx "INTERNAL VARIABLES"
858 can be used to alter default behavior; e.g.,
863 will automatically startup a text editor when compose mode is entered,
865 allows editing of headers additionally to plain body content,
867 will cause the user to be prompted actively for carbon-copy recipients
870 will allow leaving compose mode by writing a line consisting solely of
876 hook variables may be set to
878 d macros to automatically adjust some settings dependent
879 on receiver, sender or subject contexts, and via the
880 .Va on-compose-done-shell
883 variables, the latter also to be set to a
885 d macro, increasingly powerful mechanisms to perform automated message
886 adjustments are available.
889 Especially for using public mail provider accounts with the SMTP
891 it is often necessary to set
895 (even finer control via
896 .Va smtp-hostname ) ,
897 which also causes creation of
901 header fields (even if empty) unless
903 is set; saving a copy of sent messages in a
905 mailbox may be desirable \(en as for most mailbox
907 targets the value will undergo
908 .Sx "Filename transformations" .
911 for the purpose of arranging a complete environment of settings that can
912 be switched to with a single command or command line option may be
915 contains example configurations for sending messages via some of the
916 well-known public mail providers and also gives a compact overview on
917 how to setup a secure SSL/TLS environment).
922 sandbox dry-run tests first will prove correctness.
926 .Sx "On URL syntax and credential lookup"
927 will spread light on the different ways of how to specify user email
928 account credentials, the
930 variable chains, and accessing protocol-specific resources,
933 goes into the details of character encoding and how to use them for
934 representing messages and MIME part contents by specifying them in
936 and reading the section
937 .Sx "The mime.types files"
938 should help to understand how the MIME-type of outgoing attachments are
939 classified, and what can be done for fine-tuning.
940 Over the wire an intermediate, configurable
941 .Pf content-transfer-\: Va encoding
942 may be applied to the raw message part data.
945 Message recipients (as specified on the command line or defined in
950 may not only be email addressees but can also be names of mailboxes and
951 even complete shell command pipe specifications.
954 is not set then only network addresses (see
956 for a description of mail addresses) and plain user names (including MTA
957 aliases) may be used, other types will be filtered out, giving a warning
961 can be used to generate standard compliant network addresses.
963 .\" When changing any of the following adjust any RECIPIENTADDRSPEC;
964 .\" grep the latter for the complete picture
968 is set then extended recipient addresses will optionally be accepted:
969 Any name which starts with a vertical bar
971 character specifies a command pipe \(en the command string following the
973 is executed and the message is sent to its standard input;
974 Likewise, any name that starts with the character solidus
976 or the character sequence dot solidus
978 is treated as a file, regardless of the remaining content;
979 likewise a name that solely consists of a hyphen-minus
981 Any other name which contains a commercial at
983 character is treated as a network address;
984 Any other name which starts with a plus sign
986 character specifies a mailbox name;
987 Any other name which contains a solidus
989 character but no exclamation mark
993 character before also specifies a mailbox name;
994 What remains is treated as a network address.
996 .Bd -literal -offset indent
997 $ echo bla | \*(uA -Sexpandaddr -s test ./mbox.mbox
998 $ echo bla | \*(uA -Sexpandaddr -s test '|cat >> ./mbox.mbox'
999 $ echo safe | LC_ALL=C \e
1000 \*(uA -:/ -Sv15-compat -Ssendwait -Snosave \e
1001 -Sexpandaddr=fail,-all,+addr,failinvaddr -s test \e
1006 It is possible to create personal distribution lists via the
1008 command, so that, for instance, the user can send mail to
1010 and have it go to a group of people.
1011 These aliases have nothing in common with the system wide aliases that
1012 may be used by the MTA, which are subject to the
1016 and are often tracked in a file
1022 Personal aliases will be expanded by \*(UA before the message is sent,
1023 and are thus a convenient alternative to specifying each addressee by
1024 itself; they correlate with the active set of
1031 .Dl alias cohorts bill jkf mark kridle@ucbcory ~/mail/cohorts.mbox
1034 To avoid environmental noise scripts should
1036 \*(UA from any configuration files and create a script-local
1037 environment, ideally with the command line options
1039 to disable any configuration file in conjunction with repetitions of
1041 to specify variables:
1043 .Bd -literal -offset indent
1044 $ env LC_ALL=C \*(uA -:/ \e
1045 -Sv15-compat -Ssendwait -Snosave -Sttycharset=utf-8 \e
1046 -Sexpandaddr=fail,-all,failinvaddr \e
1047 -S 'mta=smtps://mylogin@exam.ple:465' -Ssmtp-auth=login \e
1048 -S 'from=scriptreply@exam.ple' \e
1049 -s 'subject' -a attachment_file \e
1050 -. "Recipient 1 <rec1@exam.ple>" rec2@exam.ple \e
1055 As shown, scripts can
1057 a locale environment, the above specifies the all-compatible 7-bit clean
1060 but will nonetheless take and send UTF-8 in the message text by using
1062 In interactive mode, which is introduced in the next section, messages
1063 can be sent by calling the
1065 command with a list of recipient addresses \(em the semantics are
1066 completely identical to non-interactive message sending:
1068 .Bd -literal -offset indent
1069 $ \*(uA -d -Squiet -Semptystart
1070 "/var/spool/mail/user": 0 messages
1071 ? mail "Recipient 1 <rec1@exam.ple>", rec2@exam.ple
1072 ? # Will do the right thing (tm)
1073 ? m rec1@exam.ple rec2@exam.ple
1077 .\" .Ss "On reading mail, and interactive mode" {{{
1078 .Ss "On reading mail, and interactive mode"
1080 When invoked without addressees \*(UA enters interactive mode in which
1082 When used like that the user's system
1086 for an in-depth description of the different mailbox types that exist)
1087 is read in and a one line header of each message therein is displayed.
1088 The visual style of this summary of
1090 can be adjusted through the variable
1092 and the possible sorting criterion via
1098 can be performed with the command
1100 If the initially opened mailbox is empty \*(UA will instead exit
1101 immediately (after displaying a message) unless the variable
1110 will give a listing of all available commands and
1112 will give a summary of some common ones.
1113 If the \*(OPal documentation strings are available one can type
1116 and see the actual expansion of
1118 and what its purpose is, i.e., commands can be abbreviated
1119 (note that POSIX defines some abbreviations, so that the alphabetical
1120 order of commands does not necessarily relate to the abbreviations; it is
1121 possible to define overwrites with the
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 add 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
1279 as well as updating the \*(OPal line editor
1283 instead in order to prevent any of these actions.
1286 .\" .Ss "HTML mail and MIME attachments" {{{
1287 .Ss "HTML mail and MIME attachments"
1289 Messages which are HTML-only get more and more common and of course many
1290 messages come bundled with a bouquet of MIME attachments.
1291 Whereas \*(UA \*(OPally supports a simple HTML-to-text converter to deal
1292 with HTML messages (see
1293 .Sx "The mime.types files" ) ,
1294 it normally cannot deal with any of these itself, but instead programs
1295 need to become registered to deal with specific MIME types or file
1297 These programs may either prepare plain text versions of their input
1298 in order to enable \*(UA to display the content on the terminal,
1299 or display the content themselves, for example in a graphical window.
1302 To install an external handler program for a specific MIME type set an
1304 .Va pipe-TYPE/SUBTYPE
1305 variable; to instead define a handler for a specific file extension set
1308 variable \(en these handlers take precedence.
1309 \*(OPally \*(UA supports mail user agent configuration as defined in
1310 RFC 1524; this mechanism, documented in the section
1311 .Sx "The Mailcap files" ,
1312 will be queried for display or quote handlers if none of the former two
1313 .\" TODO v15-compat "will be" -> "is"
1314 did; it will be the sole source for handlers of other purpose.
1315 A last source for handlers may be the MIME type definition itself, if
1316 the \*(UA specific type-marker extension was used when defining the type
1319 (Many of the builtin MIME types do so by default.)
1323 .Va mime-counter-evidence
1324 can be set to improve dealing with faulty MIME part declarations as are
1325 often seen in real-life messages.
1326 E.g., to display a HTML message inline (that is, converted to a more
1327 fancy plain text representation than the builtin converter is capable to
1328 produce) with either of the text-mode browsers
1332 teach \*(UA about MathML documents and make it display them as plain
1333 text, and to open PDF attachments in an external PDF viewer,
1334 asynchronously and with some other magic attached:
1336 .Bd -literal -offset indent
1337 if [ "$features" !@ +filter-html-tagsoup ]
1338 #set pipe-text/html='elinks -force-html -dump 1'
1339 set pipe-text/html='lynx -stdin -dump -force_html'
1340 # Display HTML as plain text instead
1341 #set pipe-text/html=@
1343 mimetype '@ application/mathml+xml mathml'
1344 wysh set pipe-application/pdf='@&=@ \e
1345 trap "rm -f \e"${MAILX_FILENAME_TEMPORARY}\e"" EXIT;\e
1346 trap "trap \e"\e" INT QUIT TERM; exit 1" INT QUIT TERM;\e
1347 mupdf "${MAILX_FILENAME_TEMPORARY}"'
1351 Note: special care must be taken when using such commands as mail
1352 viruses may be distributed by this method: if messages of type
1353 .Ql application/x-sh
1354 or files with the extension
1356 were blindly filtered through the shell, for example, a message sender
1357 could easily execute arbitrary code on the system \*(UA is running on.
1358 For more on MIME, also in respect to sending of messages, see the
1360 .Sx "The mime.types files" ,
1361 .Sx "The Mailcap files"
1366 .\" .Ss "Mailing lists" {{{
1369 \*(UA offers some support to ease handling of mailing lists.
1372 promotes all given arguments to known mailing lists, and
1374 sets their subscription attribute, creating them first as necessary.
1379 automatically, but only resets the subscription attribute.)
1380 Using the commands without arguments will show (a subset of) all
1381 currently defined mailing lists.
1386 can be used to mark out messages with configured list addresses
1387 in the header display.
1390 \*(OPally mailing lists may also be specified as (extended) regular
1391 expressions, which allows matching of many addresses with a single
1393 However, all fully qualified list addresses are matched via a fast
1394 dictionary, whereas expressions are placed in (a) list(s) which is
1395 (are) matched sequentially.
1397 .Bd -literal -offset indent
1398 set followup-to followup-to-honour=ask-yes reply-to-honour=ask-yes
1399 wysh mlist a1@b1.c1 a2@b2.c2 '.*@lists\e.c3$'
1400 mlsubscribe a4@b4.c4 exact@lists.c3
1405 .Va followup-to-honour
1407 .Ql Mail-\:Followup-\:To:
1408 header is honoured when the message is being replied to (via
1414 controls whether this header is created when sending mails; it will be
1415 created automatically for a couple of reasons, too, like when the
1417 .Dq mailing list specific
1422 is used to respond to a message with its
1423 .Ql Mail-Followup-To:
1427 A difference in between the handling of known and subscribed lists is
1428 that the address of the sender is usually not part of a generated
1429 .Ql Mail-Followup-To:
1430 when addressing the latter, whereas it is for the former kind of lists.
1431 Usually because there are exceptions: say, if multiple lists are
1432 addressed and not all of them are subscribed lists.
1434 For convenience \*(UA will, temporarily, automatically add a list
1435 address that is presented in the
1437 header of a message that is being responded to to the list of known
1439 Shall that header have existed \*(UA will instead, dependent on the
1441 .Va reply-to-honour ,
1444 for this purpose in order to accept a list administrators' wish that
1445 is supposed to have been manifested like that (but only if it provides
1446 a single address which resides on the same domain as what is stated in
1450 .\" .Ss "Resource files" {{{
1451 .Ss "Resource files"
1453 Upon startup \*(UA reads in several resource files:
1455 .Bl -tag -width ".It Pa BaNg"
1458 System wide initialization file.
1459 Reading of this file can be suppressed, either by using the
1461 (and according argument) or
1463 command line options, or by setting the
1466 .Ev MAILX_NO_SYSTEM_RC .
1470 File giving initial commands.
1471 A different file can be chosen by setting the
1475 Reading of this file can be suppressed with the
1477 command line option.
1479 .It Va mailx-extra-rc
1480 Can be used to define an optional startup file to be read after all
1481 other resource files.
1482 It can be used to specify settings that are not understood by other
1484 implementations, for example.
1485 This variable is only honoured when defined in a resource file, e.g.,
1487 .Sx "INTERNAL VARIABLES" .
1491 The content of these files is interpreted as follows:
1494 .Bl -bullet -compact
1496 A lines' leading whitespace is removed.
1498 Empty lines are ignored.
1500 Any other line is interpreted as a command.
1501 It may be spread over multiple input lines if the newline character is
1503 by placing a reverse solidus character
1505 as the last character of the line; whereas any leading whitespace of
1506 follow lines is ignored, trailing whitespace before a escaped newline
1507 remains in the input.
1509 If the line (content) starts with the number sign
1511 then it is a comment-command \(en a real command! \(en and also ignored.
1512 This command is the only form of comment that is understood.
1516 Unless \*(UA is about to enter interactive mode syntax errors that occur
1517 while loading these files are treated as errors and cause program exit.
1518 More files with syntactically equal content can be
1520 The following, saved in a file, would be an examplary content:
1522 .Bd -literal -offset indent
1523 # This line is a comment command. And y\e
1524 es, it is really continued here.
1531 .\" .Ss "Character sets" {{{
1532 .Ss "Character sets"
1534 \*(OP \*(UA detects the character set of the terminal by using
1535 mechanisms that are controlled by the
1540 should give an overview); the \*(UA internal variable
1542 will be set to the detected terminal character set accordingly
1543 and will thus show up in the output of the commands
1549 However, a user supplied
1551 value is not overwritten by this detection mechanism: this
1553 must be used if the detection does not work properly,
1554 and it may be used to adjust the name of the locale character set.
1555 E.g., on BSD systems one may use a locale with the character set
1556 ISO8859-1, which is not a valid name for this character set; to be on
1557 the safe side, one may set
1559 to the correct name, which is ISO-8859-1.
1562 Note that changing the value does not mean much beside that,
1563 since several aspects of the real character set are implied by the
1564 locale environment of the system,
1565 and that stays unaffected by the content of an overwritten
1568 (This is mostly an issue when interactively using \*(UA, though.
1569 It is actually possible to send mail in a completely
1571 locale environment, an option that \*(UA's test-suite uses excessively.)
1574 If no character set conversion capabilities have been compiled into
1577 does not include the term
1581 will be the only supported character set,
1582 it is simply assumed that it can be used to exchange 8-bit messages
1583 (over the wire an intermediate
1584 .Pf content-transfer-\: Va encoding
1586 and the rest of this section does not apply;
1587 it may however still be necessary to explicitly set it if automatic
1588 detection fails, since in that case it defaults to the mentioned
1589 .\" (Keep in SYNC: ./nail.1:"Character sets", ./nail.h:CHARSET_*!)
1593 When reading messages, their text is converted into
1595 as necessary in order to display them on the users terminal.
1596 Unprintable characters and invalid byte sequences are detected
1597 and replaced by proper substitution characters (unless the variable
1599 was set once \*(UA was started).
1601 .Va charset-unknown-8bit
1602 to deal with another hairy aspect of message interpretation.
1605 When sending messages all their parts and attachments are classified.
1606 Whereas no character set conversion is performed on those parts which
1607 appear to be binary data,
1608 the character set being used must be declared within the MIME header of
1609 an outgoing text part if it contains characters that do not conform to
1610 the set of characters that are allowed by the email standards.
1611 Permissible values for character sets can be declared using the
1615 which defines a catch-all last-resort fallback character set that is
1616 implicitly appended to the list of character-sets in
1620 When replying to a message and the variable
1621 .Va reply-in-same-charset
1622 is set then the character set of the message being replied to is tried
1624 And it is also possible to make \*(UA work even more closely related to
1625 the current locale setting automatically by using the variable
1626 .Va sendcharsets-else-ttycharset ,
1627 please see there for more information.
1630 All the specified character sets are tried in order unless the
1631 conversion of the part or attachment succeeds.
1632 If none of the tried (8-bit) character sets is capable to represent the
1633 content of the part or attachment,
1634 then the message will not be sent and its text will optionally be
1638 In general, if the message
1639 .Dq Cannot convert from a to b
1640 appears, either some characters are not appropriate for the currently
1641 selected (terminal) character set,
1642 or the needed conversion is not supported by the system.
1643 In the first case, it is necessary to set an appropriate
1645 locale and/or the variable
1649 The best results are usually achieved when \*(UA is run in a UTF-8
1650 locale on a UTF-8 capable terminal, in which case the full Unicode
1651 spectrum of characters is available.
1652 In this setup characters from various countries can be displayed,
1653 while it is still possible to use more simple character sets for sending
1654 to retain maximum compatibility with older mail clients.
1657 On the other hand the POSIX standard defines a locale-independent 7-bit
1658 .Dq portable character set
1659 that should be used when overall portability is an issue, the even more
1660 restricted subset named
1661 .Dq portable filename character set
1662 consisting of A-Z, a-z, 0-9, period
1670 .\" .Ss "Message states" {{{
1671 .Ss "Message states"
1673 \*(UA differentiates in between several different message states;
1674 the current state will be reflected in header summary displays if
1676 is configured to do so (via the internal variable
1678 and messages can also be selected and be acted upon depending on their
1680 .Sx "Specifying messages" ) .
1681 When operating on the system
1685 .Sx "primary system mailbox" ,
1686 special actions, like the automatic moving of messages to the
1688 .Sx "secondary mailbox"
1690 may be applied when the mailbox is left (also implicitly via
1691 a successful exit of \*(UA, but not if the special command
1693 is used) \(en however, because this may be irritating to users which
1696 mail-user-agents, the default global
1702 variables in order to suppress this behaviour.
1704 .Bl -hang -width ".It Ql new"
1706 Message has neither been viewed nor moved to any other state.
1707 Such messages are retained even in the
1709 .Sx "primary system mailbox" .
1712 Message has neither been viewed nor moved to any other state, but the
1713 message was present already when the mailbox has been opened last:
1714 Such messages are retained even in the
1716 .Sx "primary system mailbox" .
1719 The message has been processed by one of the following commands:
1738 will always try to automatically
1744 logical message, and may thus mark multiple messages as read, the
1746 command will do so if the internal variable
1751 command is used, messages that are in a
1753 .Sx "primary system mailbox"
1756 state when the mailbox is left will be saved in
1758 unless the internal variable
1763 The message has been processed by one of the following commands:
1769 can be used to access such messages.
1772 The message has been processed by a
1774 command and it will be retained in its current location.
1777 The message has been processed by one of the following commands:
1783 command is used, messages that are in a
1785 .Sx "primary system mailbox"
1788 state when the mailbox is left will be deleted; they will be saved in
1790 when the internal variable
1796 In addition to these message states, flags which otherwise have no
1797 technical meaning in the mail system except allowing special ways of
1798 addressing them when
1799 .Sx "Specifying messages"
1800 can be set on messages.
1801 These flags are saved with messages and are thus persistent, and are
1802 portable between a set of widely used MUAs.
1804 .Bl -hang -width ".It Ic answered"
1806 Mark messages as having been answered.
1808 Mark messages as being a draft.
1810 Mark messages which need special attention.
1814 .\" .Ss "Specifying messages" {{{
1815 .Ss "Specifying messages"
1822 can be given a list of message numbers as arguments to apply to a number
1823 of messages at once.
1826 deletes messages 1 and 2,
1829 will delete the messages 1 through 5.
1830 In sorted or threaded mode (see the
1834 will delete the messages that are located between (and including)
1835 messages 1 through 5 in the sorted/threaded order, as shown in the
1838 The following special message names exist:
1841 .Bl -tag -width ".It Ar BaNg"
1843 The current message, the so-called
1847 The message that was previously the current message.
1850 The parent message of the current message,
1851 that is the message with the Message-ID given in the
1853 field or the last entry of the
1855 field of the current message.
1858 The next previous undeleted message,
1859 or the next previous deleted message for the
1862 In sorted/threaded mode,
1863 the next previous such message in the sorted/threaded order.
1866 The next undeleted message,
1867 or the next deleted message for the
1870 In sorted/threaded mode,
1871 the next such message in the sorted/threaded order.
1874 The first undeleted message,
1875 or the first deleted message for the
1878 In sorted/threaded mode,
1879 the first such message in the sorted/threaded order.
1883 In sorted/threaded mode,
1884 the last message in the sorted/threaded order.
1888 selects the message addressed with
1892 is any other message specification,
1893 and all messages from the thread that begins at it.
1894 Otherwise it is identical to
1899 the thread beginning with the current message is selected.
1904 All messages that were included in the
1905 .Sx "Message list arguments"
1906 of the previous command.
1909 An inclusive range of message numbers.
1910 Selectors that may also be used as endpoints include any of
1915 .Dq any substring matches
1918 header, which will match addresses (too) even if
1920 is set (and POSIX says
1921 .Dq any address as shown in a header summary shall be matchable in this form ) ;
1924 variable is set, only the local part of the address is evaluated
1925 for the comparison, not ignoring case, and the setting of
1927 is completely ignored.
1928 For finer control and match boundaries use the
1932 .It Ar / Ns Ar string
1933 All messages that contain
1935 in the subject field (case ignored).
1942 the string from the previous specification of that type is used again.
1944 .It Xo Op Ar @ Ns Ar name-list Ns
1947 All messages that contain the given case-insensitive search
1949 ession; if the \*(OPal regular expression (see
1951 support is available
1953 will be interpreted as (an extended) one if any of the
1955 (extended) regular expression characters is seen: in this case this
1956 should match strings correctly which are in the locale
1960 .Ar @ Ns Ar name-list
1961 part is missing, the search is restricted to the subject field body,
1964 specifies a comma-separated list of header fields to search, as in
1966 .Dl '@to,from,cc@Someone i ought to know'
1968 In order to search for a string that includes a
1970 (commercial at) character the
1972 is effectively non-optional, but may be given as the empty string.
1973 Some special header fields may be abbreviated:
1987 respectively and case-insensitively.
1992 can be used to search in (all of) the header(s) of the message, and the
2001 can be used to perform full text searches \(en whereas the former
2002 searches only the body, the latter also searches the message header.
2004 This message specification performs full text comparison, but even with
2005 regular expression support it is almost impossible to write a search
2006 expression that savely matches only a specific address domain.
2007 To request that the content of the header is treated as a list of
2008 addresses, and to strip those down to the plain email address which the
2009 search expression is to be matched against, prefix the header name
2010 (abbreviation) with a tilde
2013 .Dl @~f@@a\e.safe\e.domain\e.match$
2016 All messages of state
2020 is one or multiple of the following colon modifiers:
2022 .Bl -tag -compact -width ".It Ar :M"
2027 Old messages (any not in state
2049 messages (cf. the variable
2050 .Va markanswered ) .
2055 \*(OP Messages classified as spam (see
2056 .Sx "Handling spam" . )
2058 \*(OP Messages with unsure spam classification.
2064 \*(OP IMAP-style SEARCH expressions may also be used.
2065 This addressing mode is available with all types of folders;
2066 \*(UA will perform the search locally as necessary.
2067 Strings must be enclosed by double quotes
2069 in their entirety if they contain white space or parentheses;
2070 within the quotes, only reverse solidus
2072 is recognized as an escape character.
2073 All string searches are case-insensitive.
2074 When the description indicates that the
2076 representation of an address field is used,
2077 this means that the search string is checked against both a list
2080 .Bd -literal -offset indent
2081 (\*qname\*q \*qsource\*q \*qlocal-part\*q \*qdomain-part\*q)
2086 and the addresses without real names from the respective header field.
2087 These search expressions can be nested using parentheses, see below for
2091 .Bl -tag -compact -width ".It Ar _n_u"
2092 .It Ar ( criterion )
2093 All messages that satisfy the given
2095 .It Ar ( criterion1 criterion2 ... criterionN )
2096 All messages that satisfy all of the given criteria.
2098 .It Ar ( or criterion1 criterion2 )
2099 All messages that satisfy either
2104 To connect more than two criteria using
2106 specifications have to be nested using additional parentheses,
2108 .Ql (or a (or b c)) ,
2112 .Ql ((a or b) and c) .
2115 operation of independent criteria on the lowest nesting level,
2116 it is possible to achieve similar effects by using three separate
2120 .It Ar ( not criterion )
2121 All messages that do not satisfy
2123 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
2124 All messages that contain
2126 in the envelope representation of the
2129 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
2130 All messages that contain
2132 in the envelope representation of the
2135 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
2136 All messages that contain
2138 in the envelope representation of the
2141 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
2142 All messages that contain
2147 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
2148 All messages that contain
2150 in the envelope representation of the
2153 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
2154 All messages that contain
2159 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
2160 All messages that contain
2163 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
2164 All messages that contain
2166 in their header or body.
2167 .It Ar ( larger size )
2168 All messages that are larger than
2171 .It Ar ( smaller size )
2172 All messages that are smaller than
2176 .It Ar ( before date )
2177 All messages that were received before
2179 which must be in the form
2183 denotes the day of the month as one or two digits,
2185 is the name of the month \(en one of
2186 .Ql Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ,
2189 is the year as four digits, e.g.,
2193 All messages that were received on the specified date.
2194 .It Ar ( since date )
2195 All messages that were received since the specified date.
2196 .It Ar ( sentbefore date )
2197 All messages that were sent on the specified date.
2198 .It Ar ( senton date )
2199 All messages that were sent on the specified date.
2200 .It Ar ( sentsince date )
2201 All messages that were sent since the specified date.
2203 The same criterion as for the previous search.
2204 This specification cannot be used as part of another criterion.
2205 If the previous command line contained more than one independent
2206 criterion then the last of those criteria is used.
2210 .\" .Ss "On URL syntax and credential lookup" {{{
2211 .Ss "On URL syntax and credential lookup"
2213 \*(IN For accessing protocol-specific resources usage of Uniform
2214 Resource Locators (URL, RFC 1738) has become omnipresent.
2215 \*(UA expects and understands URLs in the following form;
2218 denote optional parts, optional either because there also exist other
2219 ways to define the information in question or because support of the
2220 part is protocol-specific (e.g.,
2222 is used by the IMAP protocol but not by POP3);
2227 are specified they must be given in URL percent encoded form (RFC 3986;
2233 .Dl PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
2236 Note that these \*(UA URLs most often do not conform to any real
2237 standard, but instead represent a normalized variant of RFC 1738 \(en
2238 they are not used in data exchange but only meant as a compact,
2239 easy-to-use way of defining and representing information in
2240 a well-known notation.
2243 Many internal variables of \*(UA exist in multiple versions, called
2244 variable chains for the rest of this document: the plain
2249 .Ql variable-USER@HOST .
2256 had been specified in the respective URL, otherwise it refers to the plain
2262 that had been found when doing the user chain lookup as is described
2265 will never be in URL percent encoded form, whether it came from an URL
2266 or not; i.e., variable chain name extensions of
2267 .Sx "INTERNAL VARIABLES"
2268 must not be URL percent encoded.
2271 For example, whether an hypothetical URL
2272 .Ql smtp://hey%3Ayou@our.house
2273 had been given that includes a user, or whether the URL was
2274 .Ql smtp://our.house
2275 and the user had been found differently, to lookup the variable chain
2276 .Va smtp-use-starttls
2277 \*(UA first looks for whether
2278 .Ql smtp-\:use-\:starttls-\:hey:you@our.house
2279 is defined, then whether
2280 .Ql smtp-\:use-\:starttls-\:our.house
2281 exists before finally ending up looking at the plain variable itself.
2284 \*(UA obeys the following logic scheme when dealing with the
2285 necessary credential information of an account:
2291 has been given in the URL the variables
2295 are looked up; if no such variable(s) can be found then \*(UA will,
2296 when enforced by the \*(OPal variables
2297 .Va netrc-lookup-HOST
2304 specific entry which provides a
2306 name: this lookup will only succeed if unambiguous (one possible matching
2309 It is possible to load encrypted
2314 If there is still no
2316 then \*(UA will fall back to the user who is supposed to run \*(UA,
2317 the identity of which has been fixated during \*(UA startup and is
2318 known to be a valid user on the current host.
2321 Authentication: unless otherwise noted this will lookup the
2322 .Va PROTOCOL-auth-USER@HOST , PROTOCOL-auth-HOST , PROTOCOL-auth
2323 variable chain, falling back to a protocol-specific default should this
2329 has been given in the URL, then if the
2331 has been found through the \*(OPal
2333 that may have already provided the password, too.
2334 Otherwise the variable chain
2335 .Va password-USER@HOST , password-HOST , password
2336 is looked up and used if existent.
2338 Afterwards the complete \*(OPal variable chain
2339 .Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
2343 cache is searched for a password only (multiple user accounts for
2344 a single machine may exist as well as a fallback entry without user
2345 but with a password).
2347 If at that point there is still no password available, but the
2348 (protocols') chosen authentication type requires a password, then in
2349 interactive mode the user will be prompted on the terminal.
2354 S/MIME verification works relative to the values found in the
2358 header field(s), which means that the values of
2359 .Va smime-sign , smime-sign-cert , smime-sign-include-certs
2361 .Va smime-sign-message-digest
2362 will not be looked up using the
2366 chains from above but instead use the corresponding values from the
2367 message that is being worked on.
2368 In unusual cases multiple and different
2372 combinations may therefore be involved \(en on the other hand those
2373 unusual cases become possible.
2374 The usual case is as short as:
2377 .Dl set mta=smtp://USER:PASS@HOST smtp-use-starttls \e
2378 .Dl \ \ \ \ smime-sign smime-sign-cert=+smime.pair
2383 contains complete example configurations.
2386 .\" .Ss "On terminal control and line editor" {{{
2387 .Ss "On terminal control and line editor"
2389 \*(OP Terminal control will be realized through one of the standard
2391 libraries, either the
2393 or, alternatively, the
2395 both of which will be initialized to work with the environment variable
2397 Terminal control will enhance or enable interactive usage aspects, e.g.,
2398 .Sx "Coloured display" ,
2399 and extend behaviour of the Mailx-Line-Editor (MLE), which may learn the
2400 byte-sequences of keys like the cursor and function keys, and which will
2401 automatically enter the so-called
2403 alternative screen shall the terminal support it.
2404 The internal variable
2406 can be used to overwrite settings or to learn (correct(ed)) keycodes.
2407 Actual interaction with the chosen library can be disabled completely by
2408 setting the internal variable
2409 .Va termcap-disable ;
2411 will be queried regardless, even if the \*(OPal support for the
2412 libraries has not been enabled at configuration time.
2415 \*(OP The builtin \*(UA Mailx-Line-Editor (MLE) should work in all
2416 environments which comply to the ISO C standard
2418 and will support wide glyphs if possible (the necessary functionality
2419 had been removed from ISO C, but was included in
2421 Prevent usage of a line editor in interactive mode by setting the
2423 .Va line-editor-disable .
2424 Especially if the \*(OPal terminal control support is missing setting
2425 entries in the internal variable
2427 will help shall the MLE misbehave, see there for more.
2428 The MLE can support a little bit of
2434 feature is available then input from line editor prompts will be saved
2435 in a history list that can be searched in and be expanded from.
2436 Such saving can be prevented by prefixing input with any amount of
2438 Aspects of history, like allowed content and maximum size, as well as
2439 whether history shall be saved persistently, can be configured with the
2443 .Va history-gabby-persist
2448 The MLE supports a set of editing and control commands.
2449 By default (as) many (as possible) of these will be assigned to a set of
2450 single-letter control codes, which should work on any terminal (and can
2451 be generated by holding the
2453 key while pressing the key of desire, e.g.,
2457 command is available then the MLE commands can also be accessed freely
2458 by assigning the command name, which is shown in parenthesis in the list
2459 below, to any desired key-sequence, and the MLE will instead and also use
2461 to establish its builtin key bindings
2462 (more of them if the \*(OPal terminal control is available),
2463 an action which can then be suppressed completely by setting
2464 .Va line-editor-no-defaults .
2465 .Sx "Shell-style argument quoting"
2466 notation is used in the following;
2467 combinations not mentioned either cause job control signals or do not
2468 generate a (unique) keycode:
2472 .Bl -tag -compact -width ".It Ql Ba"
2474 Go to the start of the line
2476 .Pf ( Cd mle-go-home ) .
2479 Move the cursor backward one character
2481 .Pf ( Cd mle-go-bwd ) .
2484 Forward delete the character under the cursor;
2485 quits \*(UA if used on the empty line unless the internal variable
2489 .Pf ( Cd mle-del-fwd ) .
2492 Go to the end of the line
2494 .Pf ( Cd mle-go-end ) .
2497 Move the cursor forward one character
2499 .Pf ( Cd mle-go-fwd ) .
2502 Cancel current operation, full reset.
2503 If there is an active history search or tabulator expansion then this
2504 command will first reset that, reverting to the former line content;
2505 thus a second reset is needed for a full reset in this case
2507 .Pf ( Cd mle-reset ) .
2510 Backspace: backward delete one character
2512 .Pf ( Cd mle-del-bwd ) .
2516 Horizontal tabulator:
2517 try to expand the word before the cursor, supporting the usual
2518 .Sx "Filename transformations"
2520 .Pf ( Cd mle-complete ) .
2522 .Cd mle-quote-rndtrip .
2526 commit the current line
2528 .Pf ( Cd mle-commit ) .
2531 Cut all characters from the cursor to the end of the line
2533 .Pf ( Cd mle-snarf-end ) .
2538 .Pf ( Cd mle-repaint ) .
2541 \*(OP Go to the next history entry
2543 .Pf ( Cd mle-hist-fwd ) .
2546 (\*(OPally context-dependent) Invokes the command
2550 \*(OP Go to the previous history entry
2552 .Pf ( Cd mle-hist-bwd ) .
2555 Toggle roundtrip mode shell quotes, where produced,
2558 .Pf ( Cd mle-quote-rndtrip ) .
2559 This setting is temporary, and will be forgotten once the command line
2563 \*(OP Complete the current line from (the remaining) older history entries
2565 .Pf ( Cd mle-hist-srch-bwd ) .
2568 \*(OP Complete the current line from (the remaining) newer history entries
2570 .Pf ( Cd mle-hist-srch-fwd ) .
2573 Paste the snarf buffer
2575 .Pf ( Cd mle-paste ) .
2583 .Pf ( Cd mle-snarf-line ) .
2586 Prompts for a Unicode character (its hexadecimal number) to be inserted
2588 .Pf ( Cd mle-prompt-char ) .
2589 Note this command needs to be assigned to a single-letter control code
2590 in order to become recognized and executed during input of
2591 a key-sequence (only three single-letter control codes can be used for
2592 that shortcut purpose); this control code is special-treated and cannot
2593 be part of any other sequence, because any occurrence will perform the
2595 function immediately.
2598 Cut the characters from the one preceding the cursor to the preceding
2601 .Pf ( Cd mle-snarf-word-bwd ) .
2604 Move the cursor forward one word boundary
2606 .Pf ( Cd mle-go-word-fwd ) .
2609 Move the cursor backward one word boundary
2611 .Pf ( Cd mle-go-word-bwd ) .
2614 Escape: reset a possibly used multibyte character input state machine
2615 and \*(OPally a lingering, incomplete key binding
2617 .Pf ( Cd mle-cancel ) .
2618 This command needs to be assigned to a single-letter control code in
2619 order to become recognized and executed during input of a key-sequence
2620 (only three single-letter control codes can be used for that shortcut
2622 This control code may also be part of a multi-byte sequence, but if
2623 a sequence is active and the very control code is currently also an
2624 expected input, then it will first be consumed by the active sequence.
2627 (\*(OPally context-dependent) Invokes the command
2631 (\*(OPally context-dependent) Invokes the command
2635 (\*(OPally context-dependent) Invokes the command
2639 Cut the characters from the one after the cursor to the succeeding word
2642 .Pf ( Cd mle-snarf-word-fwd ) .
2653 this will immediately reset a possibly active search etc.
2658 ring the audible bell.
2662 .\" .Ss "Coloured display" {{{
2663 .Ss "Coloured display"
2665 \*(OP \*(UA can be configured to support a coloured display and font
2666 attributes by emitting ANSI / ISO 6429 SGR (select graphic rendition)
2668 Usage of colours and font attributes solely depends upon the
2669 capability of the detected terminal type that is defined by the
2670 environment variable
2672 and which can be fine-tuned by the user via the internal variable
2676 On top of what \*(UA knows about the terminal the boolean variable
2678 defines whether the actually applicable colour and font attribute
2679 sequences should also be generated when output is going to be paged
2680 through the external program defined by the environment variable
2685 This is not enabled by default because different pager programs need
2686 different command line switches or other configuration in order to
2687 support those sequences.
2688 \*(UA however knows about some widely used pagers and in a clean
2689 environment it is often enough to simply set
2691 please refer to that variable for more on this topic.
2696 is set then any active usage of colour and font attribute sequences
2697 is suppressed, but without affecting possibly established
2702 To define and control colours and font attributes a single multiplexer
2703 command family exists:
2705 shows or defines colour mappings for the given colour type (e.g.,
2708 can be used to remove mappings of a given colour type.
2709 Since colours are only available in interactive mode, it may make
2710 sense to conditionalize the colour setup by encapsulating it with
2713 .Bd -literal -offset indent
2714 if terminal && $features =@ +colour
2715 colour iso view-msginfo ft=bold,fg=green
2716 colour iso view-header ft=bold,fg=red "from,subject"
2717 colour iso view-header fg=red
2719 uncolour iso view-header from,subject
2720 colour iso view-header ft=bold,fg=magenta,bg=cyan
2721 colour 256 view-header ft=bold,fg=208,bg=230 subject,from
2722 colour mono view-header ft=bold
2723 colour mono view-header ft=bold,ft=reverse subject,from
2727 .\" }}} (DESCRIPTION)
2730 .\" .Sh COMMANDS {{{
2733 Each command is typed on a line by itself,
2734 and may take arguments following the command word.
2735 An unquoted reverse solidus
2737 at the end of a command line
2739 the newline character: it is discarded and the next line of input is
2740 used as a follow-up line, with all leading whitespace removed;
2741 once the entire command line is completed, the processing that is
2742 documented in the following begins.
2745 Command names may be abbreviated, in which case the first command that
2746 matches the given prefix will be used.
2749 can be used to show the list of all commands, either alphabetically
2750 sorted or in prefix search order (these do not match, also because the
2751 POSIX standard prescribes a set of abbreviations).
2752 \*(OPally the command
2756 when given an argument, will show a documentation string for the
2757 command matching the expanded argument, as in
2759 which should be a shorthand of
2761 Both commands support a more
2763 listing mode which includes the argument type of the command,
2764 and other information which applies; a handy suggestion might be:
2766 .Bd -literal -offset indent
2768 # Be careful to choose sh(1)ell-style on _entire_ line!
2769 # Result status ends up in $!
2770 localopts 1;wysh set verbose;ignerr eval "${@}";return ${?}
2772 ? ghost xv '\ecall __xv'
2776 .\" .Ss "Command modifiers" {{{
2777 .Ss "Command modifiers"
2779 Commands may be prefixed by one or multiple command modifiers.
2784 The modifier reverse solidus
2787 to be placed first, prevents
2789 expansions on the remains of the line, e.g.,
2791 will always evaluate the command
2793 even if a ghost of the same name exists.
2795 content may itself contain further command modifiers, including
2796 an initial reverse solidus to prevent further expansions.
2802 indicates that any error generated by the following command should be
2803 ignored by the state machine, via, e.g.,
2804 .Va batch-exit-on-error .
2807 .Sx "INTERNAL VARIABLES" ,
2808 will be set to the real exit status of the command regardless.
2811 Some commands support the
2814 modifier: if used, they expect the name of a variable, which can itself
2815 be a variable, i.e., shell expansion is applied, as their first
2816 argument, and will place their computation result in it instead of the
2817 default location (it is usually written to standard output).
2818 The given name will be tested for being a valid
2820 variable name, and may therefore only consist of upper- and lowercase
2821 characters, digits, and the underscore; the hyphen-minus may be used as
2822 a non-portable extension.
2823 In addition the name may either not be one of the known
2824 .Sx "INTERNAL VARIABLES" ,
2825 or must otherwise refer to a writable (non-boolean) value variable.
2826 It is a hard error that is tracked in
2828 if any of these tests fail.
2829 The actual put operation may fail nonetheless, e.g., if the variable
2830 expects a number argument only a number will be accepted.
2831 Some commands may report this as a hard failure in
2833 but most will use the soft exit status
2835 to indicate these failures.
2838 Last, but not least, the modifier
2841 can be used for some old and established commands to choose the new
2842 .Sx "Shell-style argument quoting"
2843 rules over the traditional
2844 .Sx "Old-style argument quoting" .
2848 .\" .Ss "Message list arguments" {{{
2849 .Ss "Message list arguments"
2851 Some commands expect arguments that represent messages (actually
2852 their symbolic message numbers), as has been documented above under
2853 .Sx "Specifying messages"
2855 If no explicit message list has been specified, the next message
2856 forward that satisfies the command's requirements will be used,
2857 and if there are no messages forward of the current message,
2858 the search proceeds backwards;
2859 if there are no good messages at all to be found, an error message is
2860 shown and the command is aborted.
2863 .\" .Ss "Old-style argument quoting" {{{
2864 .Ss "Old-style argument quoting"
2866 \*(ID This section documents the old, traditional style of quoting
2867 non-message-list arguments to commands which expect this type of
2868 arguments: whereas still used by the majority of such commands, the new
2869 .Sx "Shell-style argument quoting"
2870 may be available even for those via
2873 .Sx "Command modifiers" .
2874 Nonetheless care must be taken, because only new commands have been
2875 designed with all the capabilities of the new quoting rules in mind,
2876 which can, e.g., generate control characters.
2879 .Bl -bullet -offset indent
2881 An argument can be enclosed between paired double-quotes
2886 any white space, shell word expansion, or reverse solidus characters
2887 (except as described next) within the quotes are treated literally as
2888 part of the argument.
2889 A double-quote will be treated literally within single-quotes and vice
2891 Inside such a quoted string the actually used quote character can be
2892 used nonetheless by escaping it with a reverse solidus
2898 An argument that is not enclosed in quotes, as above, can usually still
2899 contain space characters if those spaces are reverse solidus escaped, as in
2903 A reverse solidus outside of the enclosing quotes is discarded
2904 and the following character is treated literally as part of the argument.
2908 .\" .Ss "Shell-style argument quoting" {{{
2909 .Ss "Shell-style argument quoting"
2911 Commands which don't expect message-list arguments use
2913 ell-style, and therefore POSIX standardized, argument parsing and
2915 \*(ID Most new commands only support these new rules and are flagged
2916 \*(NQ, some elder ones can use them with the command modifier
2918 in the future only this type of argument quoting will remain.
2921 A command line is parsed from left to right and an input token is
2922 completed whenever an unquoted, otherwise ignored, metacharacter is seen.
2923 Metacharacters are vertical bar
2930 .Cm space , tabulator , newline .
2931 The additional metacharacters left and right parenthesis
2933 and less-than and greater-than signs
2937 supports are not used, and are treated as ordinary characters: for one
2938 these characters are a vivid part of email addresses, and it also seems
2939 highly unlikely that their function will become meaningful to \*(UA.
2942 Any unquoted number sign
2944 at the beginning of new token starts a comment that extends to the end
2945 of the line, and therefore ends argument processing.
2946 An unquoted dollar sign
2948 will cause variable expansion of the given name:
2949 .Sx "INTERNAL VARIABLES"
2952 (shell) variables can be accessed through this mechanism, brace
2953 enclosing the name is supported (i.e., to subdivide a token).
2956 Whereas the metacharacters
2957 .Cm space , tabulator , newline
2958 only complete an input token, vertical bar
2964 also act as control operators and perform control functions.
2965 For now supported is semicolon
2967 which terminates a single command, therefore sequencing the command line
2968 and making the remainder of the line a subject to reevaluation.
2969 With sequencing, multiple command argument types and quoting rules may
2970 therefore apply to a single line, which can become problematic before
2971 v15: e.g., the first of the following will cause surprising results.
2974 .Dl ? echo one; set verbose; echo verbose=$verbose.
2975 .Dl ? echo one; wysh set verbose; echo verbose=$verbose.
2978 Quoting is a mechanism that will remove the special meaning of
2979 metacharacters and reserved words, and will prevent expansion.
2980 There are four quoting mechanisms: the escape character, single-quotes,
2981 double-quotes and dollar-single-quotes:
2984 .Bl -bullet -offset indent
2986 The literal value of any character can be preserved by preceding it
2987 with the escape character reverse solidus
2991 Arguments which are enclosed in
2992 .Ql 'single-\:quotes'
2993 retain their literal value.
2994 A single-quote cannot occur within single-quotes.
2997 The literal value of all characters enclosed in
2998 .Ql \(dqdouble-\:quotes\(dq
2999 is retained, with the exception of dollar sign
3001 which will cause variable expansion, as above, backquote (grave accent)
3003 (which not yet means anything special), reverse solidus
3005 which will escape any of the characters dollar sign
3007 (to prevent variable expansion), backquote (grave accent)
3011 (to prevent ending the quote) and reverse solidus
3013 (to prevent escaping, i.e., to embed a reverse solidus character as-is),
3014 but has no special meaning otherwise.
3017 Arguments enclosed in
3018 .Ql $'dollar-\:single-\:quotes'
3019 extend normal single quotes in that reverse solidus escape sequences are
3020 expanded as follows:
3022 .Bl -tag -compact -width "Ql \eNNN"
3028 an escape character.
3030 an escape character.
3042 emits a reverse solidus character.
3046 double quote (escaping is optional).
3048 eight-bit byte with the octal value
3050 (one to three octal digits), optionally prefixed by an additional
3052 A 0 byte will suppress further output for the quoted argument.
3054 eight-bit byte with the hexadecimal value
3056 (one or two hexadecimal characters).
3057 A 0 byte will suppress further output for the quoted argument.
3059 the Unicode / ISO-10646 character with the hexadecimal codepoint value
3061 (one to eight hexadecimal digits) \(em note that Unicode defines the
3062 maximum codepoint ever to be supported as
3067 This escape is only supported in locales which support Unicode (see
3068 .Sx "Character sets" ) ,
3069 in other cases the sequence will remain unexpanded unless the given code
3070 point is ASCII compatible or can be represented in the current locale.
3071 The character NUL will suppress further output for the quoted argument.
3075 except it takes only one to four hexadecimal digits.
3077 Emits the non-printable (ASCII and compatible) C0 control codes
3078 0 (NUL) to 31 (US), and 127 (DEL).
3079 Printable representations of ASCII control codes can be created by
3080 mapping them to a different part of the ASCII character set, which is
3081 possible by adding the number 64 for the codes 0 to 31, e.g., 7 (BEL) is
3082 .Ql 7 + 64 = 71 = G .
3083 The real operation is a bitwise logical XOR with 64 (bit 7 set, see
3085 thus also covering code 127 (DEL), which is mapped to 63 (question mark):
3086 .Ql ? vexpr ^ 127 64 .
3088 Whereas historically circumflex notation has often been used for
3089 visualization purposes of control codes, e.g.,
3091 the reverse solidus notation has been standardized:
3093 Some control codes also have standardized (ISO 10646, ISO C) aliases,
3094 as shown above (e.g.,
3098 whenever such an alias exists it will be used for display purposes.
3099 The control code NUL
3101 a non-standard extension) ends argument processing without producing
3104 Non-standard extension: expand the given variable name, as above.
3105 Brace enclosing the name is supported.
3107 Not yet supported, just to raise awareness: Non-standard extension.
3114 .Bd -literal -offset indent
3115 echo 'Quotes '${HOME}' and 'tokens" differ!"# no comment
3116 echo Quotes ${HOME} and tokens differ! # comment
3117 echo Don"'"t you worry$'\ex21' The sun shines on us. $'\eu263A'
3121 .\" .Ss "Filename transformations" {{{
3122 .Ss "Filename transformations"
3124 Filenames, where expected, and unless documented otherwise, are
3125 subsequently subject to the following filename transformations, in
3128 .Bl -bullet -offset indent
3130 If the given name is a registered
3132 it will be replaced with the expanded shortcut.
3135 The filename is matched against the following patterns or strings:
3137 .Bl -hang -compact -width ".Ar %user"
3139 (Number sign) is expanded to the previous file.
3141 (Percent sign) is replaced by the invoking
3142 .Mx -ix "primary system mailbox"
3143 user's primary system mailbox, which either is the (itself expandable)
3145 if that is set, the standardized absolute pathname indicated by
3147 if that is set, or a builtin compile-time default otherwise.
3149 Expands to the primary system mailbox of
3151 (and never the value of
3153 regardless of its actual setting).
3155 (Ampersand) is replaced with the invoking users
3156 .Mx -ix "secondary mailbox"
3157 secondary mailbox, the
3164 directory (if that variable is set).
3166 Expands to the same value as
3168 but has special meaning when used with, e.g., the command
3170 the file will be treated as a primary system mailbox by, e.g., the
3174 commands, meaning that messages that have been read in the current
3175 session will be moved to the
3177 mailbox instead of simply being flagged as read.
3181 Meta expansions are applied to the resulting filename, as applicable to
3182 the resulting file access protocol (also see
3183 .Sx "On URL syntax and credential lookup" ) .
3184 If the fully expanded filename results in multiple pathnames and the
3185 command is expecting only one file, an error results.
3187 For the file-protocol, a leading tilde
3189 character will be replaced by the expansion of
3191 except when followed by a valid user name, in which case the home
3192 directory of the given user is used instead.
3198 will be replaced by the expansion of the variable, if possible;
3199 .Sx "INTERNAL VARIABLES"
3202 (shell) variables can be accessed through this mechanism, and the usual
3203 escape mechanism has to be applied to prevent interpretation.
3205 In interactive context, in order to allow simple value acceptance (via
3207 arguments will usually be displayed in a properly quoted form, e.g., a file
3208 .Ql diet\e is \ecurd.txt
3210 .Ql 'diet\e is \ecurd.txt' .
3214 .\" .Ss "Commands" {{{
3217 The following commands are available:
3219 .Bl -tag -width ".It Ic BaNg"
3224 command which follows, replacing unescaped exclamation marks with the
3225 previously executed command if the internal variable
3231 The comment-command causes the entire line to be ignored.
3233 this really is a normal command which' purpose is to discard its
3236 indicating special character, which means that, e.g., trailing comments
3237 on a line are not possible.
3241 Goes to the next message in sequence and types it
3247 Display the preceding message, or the n'th previous message if given
3248 a numeric argument n.
3252 Show the current message number (the
3257 Show a brief summary of commands.
3258 \*(OP Given an argument a synopsis for the command in question is
3259 shown instead; commands can be abbreviated in general and this command
3260 can be used to see the full expansion of an abbreviation including the
3261 synopsis, try, e.g.,
3266 and see how the output changes.
3267 This mode also supports a more
3269 output, which will provide the informations documented for
3280 \*(NQ Interprets the remainder of the word as a macro name and passes
3285 is a shorter synonym for
3286 .Ql call Ar mymacro .
3290 (ac) Creates, selects or lists (an) account(s).
3291 Accounts are special incarnations of
3293 macros and group commands and variable settings which together usually
3294 arrange the environment for the purpose of creating an email account.
3295 Different to normal macros settings which are covered by
3297 \(en here by default enabled! \(en will not be reverted before the
3302 (case-insensitive) always exists, and all but it can be deleted via
3305 Without arguments a listing of all defined accounts is shown.
3306 With one argument the given account is activated: the system
3308 of that account will be activated (as via
3310 a possibly installed
3312 will be run, and the internal variable
3315 The two argument form is identical to defining a macro as via
3317 .Bd -literal -offset indent
3319 set folder=~/mail inbox=+syste.mbox record=+sent.mbox
3320 set from='myname@myisp.example (My Name)'
3321 set mta=smtp://mylogin@smtp.myisp.example
3327 \*(NQ Interprets the given arguments as an email address specification,
3328 formats it as induced by email standards, and then shows the result.
3332 .Sx "Command modifiers" ) .
3333 The return status is tracked via
3335 \*(ID This will improve further.
3339 (a) Aliases are a method of creating personal distribution lists that
3340 map a single alias name to none to multiple real receivers;
3341 these aliases become expanded after message composing is completed; to
3342 delete aliases, use the command
3344 With no arguments the command shows all currently defined aliases.
3345 With one argument, shows the expansion of the given alias.
3346 With more than one argument, creates or appends to the alias name given
3347 as the first argument the remaining arguments.
3348 Alias names are restricted to alphabetic characters, digits, the
3349 underscore, hyphen-minus, the number sign, colon, commercial at and
3350 period, the last character can also be the dollar sign:
3351 .Ql [[:alnum:]_#:@.-]+$? .
3355 (alt) Manage a list of alternate addresses or names of the active user,
3356 members of which will be removed from recipient lists when replying to
3359 variable is not set).
3360 Without arguments the current set of alternates is displayed, otherwise
3361 the set of alternate names is replaced by the given arguments, and the
3364 is updated accordingly.
3368 Takes a message list and marks each message as having been answered.
3369 Messages will be marked answered when being
3371 to automatically if the
3375 .Sx "Message states" .
3380 \*(OP\*(NQ The bind command extends the MLE (see
3381 .Sx "On terminal control and line editor" )
3382 with freely configurable key bindings.
3383 With one argument all bindings for the given context are shown,
3384 specifying an asterisk
3386 will show the bindings of all contexts; a more verbose listing will be
3387 produced if either of
3392 With two or more arguments a binding is (re)established:
3393 the first argument is the context to which the binding shall apply,
3394 the second argument is a comma-separated list of the
3396 which form the binding, and any remaining arguments form the expansion.
3397 To indicate that a binding shall not be auto-committed, but that the
3398 expansion shall instead be furtherly editable by the user, a commercial at
3400 (that will be removed) can be placed last in the expansion, from which
3401 leading and trailing whitespace will finally be removed.
3402 Reverse solidus cannot be used as the last character of expansion.
3405 Contexts define when a binding applies, i.e., a binding will not be seen
3406 unless the context for which it is defined for is currently active.
3407 This is not true for the shared binding
3409 which is the foundation for all other bindings and as such always
3410 applies, its bindings, however, only apply secondarily.
3411 The available contexts are the shared
3415 context which is used in all not otherwise documented situations, and
3417 which applies to compose mode only.
3421 which form the binding are specified as a comma-separated list of
3422 byte-sequences, where each list entry corresponds to one key(press).
3423 \*(OPally a list entry may, indicated by a leading colon character
3425 also refer to the name of a terminal capability;
3426 several dozen names will be compiled into \*(UA and may be specified
3429 or, if existing, by their
3431 name, regardless of the actually used terminal control library.
3432 It is however possible to use any capability, as long as the name is
3433 resolvable by the control library or defined in the internal variable
3435 Input sequences are not case-normalized, so that an exact match is
3436 required to update or remove a binding.
3439 .Bd -literal -offset indent
3440 bind base $'\eE',d mle-snarf-word-fwd # Esc(ape)
3441 bind base $'\eE',$'\ec?' mle-snarf-word-bwd # Esc, Delete
3442 bind default $'\ecA',:khome,w 'echo An editable binding@'
3443 bind default a,b,c rm -rf / @ # Another editable binding
3444 bind default :kf1 File %
3445 bind compose :kf1 ~e
3449 Note that the entire comma-separated list is first parsed (over) as a
3450 shell-token with whitespace as the field separator, before being parsed
3451 and expanded for real with comma as the field separator, therefore
3452 whitespace needs to be properly quoted, see
3453 .Sx "Shell-style argument quoting" .
3454 Using Unicode reverse solidus escape sequences renders a binding
3455 defunctional if the locale does not support Unicode (see
3456 .Sx "Character sets" ) ,
3457 and using terminal capabilities does so if no terminal control support
3458 is (currently) available.
3461 The following terminal capability names are builtin and can be used in
3463 or (if available) the two-letter
3465 notation regardless of the actually used library.
3466 See the respective manual for a list of capabilities.
3469 can be used to show all the capabilities of
3471 or the given terminal type;
3474 flag will also show supported (non-standard) extensions.
3477 .Bl -tag -compact -width kcuuf_or_kcuuf
3478 .It Cd kbs Ns \0or Cd kb
3480 .It Cd kdch1 Ns \0or Cd kD
3482 .It Cd kDC Ns \0or Cd *4
3483 \(em shifted variant.
3484 .It Cd kel Ns \0or Cd kE
3485 Clear to end of line.
3486 .It Cd kext Ns \0or Cd @9
3488 .It Cd kich1 Ns \0or Cd kI
3490 .It Cd kIC Ns \0or Cd #3
3491 \(em shifted variant.
3492 .It Cd khome Ns \0or Cd kh
3494 .It Cd kHOM Ns \0or Cd #2
3495 \(em shifted variant.
3496 .It Cd kend Ns \0or Cd @7
3498 .It Cd knp Ns \0or Cd kN
3500 .It Cd kpp Ns \0or Cd kP
3502 .It Cd kcub1 Ns \0or Cd kl
3503 Left cursor (with more modifiers: see below).
3504 .It Cd kLFT Ns \0or Cd #4
3505 \(em shifted variant.
3506 .It Cd kcuf1 Ns \0or Cd kr
3507 Right cursor (ditto).
3508 .It Cd kRIT Ns \0or Cd %i
3509 \(em shifted variant.
3510 .It Cd kcud1 Ns \0or Cd kd
3511 Down cursor (ditto).
3513 \(em shifted variant (only terminfo).
3514 .It Cd kcuu1 Ns \0or Cd ku
3517 \(em shifted variant (only terminfo).
3518 .It Cd kf0 Ns \0or Cd k0
3520 Add one for each function key up to
3525 .It Cd kf10 Ns \0or Cd k;
3527 .It Cd kf11 Ns \0or Cd F1
3529 Add one for each function key up to
3537 Some terminals support key-modifier combination extensions, e.g.,
3539 For example, the delete key,
3541 in its shifted variant, the name is mutated to
3543 then a number is appended for the states
3555 .Ql Shift+Alt+Control
3557 The same for the left cursor key,
3559 .Cd KLFT , KLFT3 , KLFT4 , KLFT5 , KLFT6 , KLFT7 , KLFT8 .
3562 Key bindings can be removed with the command
3564 It is advisable to use an initial escape or other control character (e.g.,
3566 for bindings which describe user key combinations (as opposed to purely
3567 terminal capability based ones), in order to avoid ambiguities whether
3568 input belongs to key sequences or not; it also reduces search time.
3571 may help shall keys and sequences be falsely recognized.
3576 \*(NQ Calls the given macro, which must have been created via
3578 Parameters given to macros are implicitly local to the macro's scope, and
3579 may be accessed via the special parameter syntax that is known from the
3586 Positional parameters may be removed by
3588 ing them off the stack.
3589 Macro execution can be terminated at any time by calling
3591 Numeric and string operations can be performed via
3595 may be helpful to recreate argument lists.
3596 .Bd -literal -offset indent
3598 echo Parameter 1 of ${#} is ${1}, all: ${*} / ${@}
3601 call exmac Hello macro exmac!
3608 if the given macro has been created via
3610 but doesn't fail nor warn if the macro doesn't exist.
3614 (ch) Change the working directory to
3616 or the given argument.
3622 \*(OP Only applicable to S/MIME signed messages.
3623 Takes a message list and a file name and saves the certificates
3624 contained within the message signatures to the named file in both
3625 human-readable and PEM format.
3626 The certificates can later be used to send encrypted messages to the
3627 respective message senders by setting
3628 .Va smime-encrypt-USER@HOST
3633 (ch) Change the working directory to
3635 or the given argument.
3641 Only applicable to threaded mode.
3642 Takes a message list and makes all replies to these messages invisible
3643 in header summaries, unless they are in state
3649 \*(OP\*(NQ Manage colour mappings of and for a
3650 .Sx "Coloured display" .
3651 The type of colour is given as the (case-insensitive) first argument,
3652 which must be one of
3654 for 256-colour terminals,
3659 for the standard 8-colour ANSI / ISO 6429 color palette and
3663 for monochrome terminals.
3664 Monochrome terminals cannot deal with colours, but only (some) font
3668 Without further arguments the list of all currently defined mappings
3669 for the given colour type is shown (as a special case giving
3673 will show the mappings of all types).
3674 Otherwise the second argument defines the mappable slot, and the third
3675 argument a (comma-separated list of) colour and font attribute
3676 specification(s), and the optional fourth argument can be used to
3677 specify a precondition: if conditioned mappings exist they are tested in
3678 (creation) order unless a (case-insensitive) match has been found, and
3679 the default mapping (if any has been established) will only be chosen as
3681 The types of precondition available depend on the mappable slot (see
3682 .Sx "Coloured display"
3683 for some examples), the following of which exist:
3686 Mappings prefixed with
3688 are used for the \*(OPal builtin Mailx-Line-Editor (MLE, see
3689 .Sx "On terminal control and line editor" )
3690 and do not support preconditions.
3692 .Bl -tag -compact -width view-partinfo
3694 This mapping is used for the position indicator that is visible when
3695 a line cannot be fully displayed on the screen.
3702 Mappings prefixed with
3704 are used in header summaries, and they all understand the preconditions
3706 (the current message) and
3708 for elder messages (only honoured in conjunction with
3709 .Va datefield-markout-older ) .
3711 .Bl -tag -compact -width view-partinfo
3713 This mapping is used for the
3715 that can be created with the
3719 formats of the variable
3722 For the complete header summary line except the
3724 and the thread structure.
3726 For the thread structure which can be created with the
3728 format of the variable
3733 Mappings prefixed with
3735 are used when displaying messages.
3737 .Bl -tag -compact -width view-partinfo
3739 This mapping is used for so-called
3741 lines, which are MBOX file format specific header lines.
3744 A comma-separated list of headers to which the mapping applies may be
3745 given as a precondition; if the \*(OPal regular expression support is
3746 available then if any of the
3748 (extended) regular expression characters is seen the precondition will
3749 be evaluated as (an extended) one.
3751 For the introductional message info line.
3752 .It Ar view-partinfo
3753 For MIME part info lines.
3757 The following (case-insensitive) colour definitions and font attributes
3758 are understood, multiple of which can be specified in a comma-separated
3768 It is possible (and often applicable) to specify multiple font
3769 attributes for a single mapping.
3772 foreground colour attribute:
3782 To specify a 256-color mode a decimal number colour specification in
3783 the range 0 to 255, inclusive, is supported, and interpreted as follows:
3785 .Bl -tag -compact -width "999 - 999"
3787 the standard ISO 6429 colors, as above.
3789 high intensity variants of the standard colors.
3791 216 colors in tuples of 6.
3793 grayscale from black to white in 24 steps.
3795 .Bd -literal -offset indent
3797 fg() { printf "\e033[38;5;${1}m($1)"; }
3798 bg() { printf "\e033[48;5;${1}m($1)"; }
3800 while [ $i -lt 256 ]; do fg $i; i=$(($i + 1)); done
3801 printf "\e033[0m\en"
3803 while [ $i -lt 256 ]; do bg $i; i=$(($i + 1)); done
3804 printf "\e033[0m\en"
3808 background colour attribute (see
3810 for possible values).
3814 Mappings may be removed with the command
3816 For a generic overview see the section
3817 .Sx "Coloured display" .
3822 (C) Copy messages to files whose names are derived from the author of
3823 the respective message and do not mark them as being saved;
3824 otherwise identical to
3829 (c) Copy messages to the named file and do not mark them as being saved;
3830 otherwise identical to
3835 Show the name of the current working directory, as reported by
3840 .Sx "Command modifiers" ) .
3841 The return status is tracked via
3846 \*(OP For unencrypted messages this command is identical to
3848 Encrypted messages are first decrypted, if possible, and then copied.
3852 \*(OP For unencrypted messages this command is identical to
3854 Encrypted messages are first decrypted, if possible, and then copied.
3858 Without arguments the current list of macros, including their content,
3859 is shown, otherwise a macro is defined.
3860 A macro definition is a sequence of commands in the following form:
3861 .Bd -literal -offset indent
3870 A defined macro can be invoked explicitly by using the
3874 commands, or implicitly if a macro hook is triggered, e.g., a
3876 It is possible to localize adjustments, like creation, deletion and
3878 .Sx "INTERNAL VARIABLES" ,
3881 command; the scope which is localized depends on how (i.e.,
3883 normal macro, folder hook, hook,
3885 switch) the macro is invoked.
3886 Execution of a macro body can be stopped from within by calling
3890 ed macro, given positional parameters can be
3893 Macros can be deleted via
3898 (d) Marks the given message list as
3900 Deleted messages will neither be saved in
3902 nor will they be available for most other commands.
3905 variable is set, automatically
3918 Superseded by the multiplexer
3924 Delete the given messages and automatically
3928 if one exists, regardless of the setting of
3935 up or down by one message when given
3939 argument, respectively.
3943 Takes a message list and marks each given message as a draft.
3945 .Sx "Message states" .
3949 \*(NQ (ec) Echoes arguments to standard output and writes a trailing
3950 newline, whereas the otherwise identical
3953 .Sx "Shell-style argument quoting"
3955 .Sx "Filename transformations"
3956 are applied to the expanded arguments.
3962 except that is echoes to standard error.
3970 but does not write a trailing newline.
3976 but does not write a trailing newline.
3980 (e) Point the text editor (as defined in
3982 at each message from the given list in turn.
3983 Modified contents are discarded unless the
3990 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
3991 conditional \(em if the condition of a preceding
3993 was false, check the following condition and execute the following block
3994 if it evaluates true.
3999 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
4000 conditional \(em if none of the conditions of the preceding
4004 commands was true, the
4010 (en) Marks the end of an
4011 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
4012 conditional execution block.
4017 \*(NQ \*(UA has a strict notion about which variables are
4018 .Sx "INTERNAL VARIABLES"
4019 and which are managed in the program
4021 Since some of the latter are a vivid part of \*(UAs functioning,
4022 however, they are transparently integrated into the normal handling of
4023 internal variables via
4027 To integrate other environment variables of choice into this
4028 transparent handling, and also to export internal variables into the
4029 process environment where they normally are not, a
4031 needs to become established with this command, as in, e.g.,
4034 .Dl environ link PERL5LIB from TZ
4037 Afterwards changing such variables with
4039 will cause automatic updates of the program environment, and therefore
4040 be inherited by newly created child processes.
4041 Sufficient system support provided (it was in BSD as early as 1987, and
4042 is standardized since Y2K) removing such variables with
4044 will remove them also from the program environment, but in any way
4045 the knowledge they ever have been
4048 Note this implies that
4050 may cause loss of links.
4055 will remove an existing link, but leaves the variables as such intact.
4056 Additionally the subcommands
4060 are provided, which work exactly the same as the documented commands
4064 but (additionally) link the variable(s) with the program environment and
4065 thus immediately export them to, or remove them from (if possible),
4066 respectively, the program environment.
4071 \*(OP Since \*(UA uses the console as a user interface it can happen
4072 that messages scroll by too fast to become recognized.
4073 Optionally an error message ring queue is available which stores
4074 duplicates of any error message and notifies the user in interactive
4075 sessions whenever a new error has occurred.
4076 The queue is finite: if its maximum size is reached any new message
4077 replaces the eldest.
4080 can be used to manage this message queue: if given
4082 or no argument the queue will be displayed and cleared,
4084 will only clear all messages from the queue.
4088 \*(NQ Construct a command by concatenating the arguments, separated with
4089 a single space character, and then evaluate the result.
4090 This command passes through the status of the evaluated command.
4093 .Bd -literal -offset indent
4095 # Like this, sh(1)ell-stylish from begin to end: works!
4096 # Result status ends up in $!, then
4097 localopts 1;wysh set verbose;ignerr eval "${@}";return ${?}
4099 ghost xv '\ecall xverbose'
4112 call yyy '~xxx' "b\e$'\et'u ' "
4120 (ex or x) Exit from \*(UA without changing the active mailbox and skip
4121 any saving of messages in
4123 as well as a possibly tracked line editor history file.
4129 but open the mailbox read-only.
4134 (fi) The file command switches to a new mailbox.
4135 Without arguments it shows status information of the current mailbox.
4136 If an argument is given, it will write out changes (such as deletions)
4137 the user has made and open a new mailbox.
4138 .Sx "Filename transformations"
4139 will be applied to the
4144 If the name ends with
4149 it is treated as being compressed with
4154 respectively, and transparently handled through an intermediate
4155 (un)compression step (using a temporary file) with the according
4156 facility, sufficient support provided.
4157 Likewise, if the named file does not exist, but a file with one of the
4158 mentioned compression extensions does, then the name is automatically
4159 expanded and the compressed file is used.
4162 Otherwise, if the name ends with an extension for which
4163 .Va file-hook-load-EXTENSION
4165 .Va file-hook-save-EXTENSION
4166 variables are set, then the given hooks will be used to load and save
4168 and \*(UA will work with an intermediate temporary file.
4170 MBOX files (flat file-based mailboxes) are generally locked during file
4171 operations in order to avoid inconsistencies due to concurrent
4173 \*(OPal Mailbox files which \*(UA treats as the system
4178 .Sx "primary system mailbox" Ns
4179 es in general will also be protected by so-called dotlock files, the
4180 traditional way of mail spool file locking: for any file
4184 will be created for the duration of the synchronization \(em
4185 as necessary a privilege-separated dotlock child process will be used
4186 to accommodate for necessary privilege adjustments in order to create
4187 the dotlock file in the same directory
4188 and with the same user and group identities as the file of interest.
4191 \*(UA by default uses tolerant POSIX rules when reading MBOX database
4192 files, but it will detect invalid message boundaries in this mode and
4193 complain (even more with
4195 if any is seen: in this case
4197 can be used to create a valid MBOX database from the invalid input.
4202 refers to a directory with the subdirectories
4207 then it is treated as a folder in
4209 format; \*(ID the variable
4211 can be used to control the format of yet non-existent folders.
4215 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
4216 .Dl \*(OU protocol://[user@]host[:port][/path]
4219 is taken as an Internet mailbox specification.
4220 The \*(OPally supported protocols are
4224 (POP3 with SSL/TLS encrypted transport).
4227 part is valid only for IMAP; there it defaults to
4229 Also see the section
4230 .Sx "On URL syntax and credential lookup" .
4235 contains special characters, in particular
4239 they must be escaped in URL notation \(en the command
4241 can be used to show the necessary conversion.
4246 Takes a message list and marks the messages as flagged for
4247 urgent/special attention.
4249 .Sx "Message states" .
4258 With no arguments, list the names of the folders in the folder directory.
4259 With an existing folder as an argument,
4260 lists the names of folders below the named folder.
4266 but saves the message in a file named after the local part of the first
4267 recipient's address (instead of in
4274 but saves the message in a file named after the local part of the first
4275 recipient's address (instead of in
4282 but responds to all recipients regardless of the
4287 .It Ic followupsender
4290 but responds to the sender only regardless of the
4306 (f) Takes a list of message specifications and displays a summary of
4307 their message headers, exactly as via
4309 An alias of this command is
4312 .Sx "Specifying messages" .
4318 but saves the message in a file named after the local part of the
4319 recipient's address (instead of in
4324 Takes a message and the address of a recipient
4325 and forwards the message to him.
4326 The text of the original message is included in the new one,
4327 with the value of the
4329 variable preceding it.
4330 To filter the included header fields to the desired subset use the
4332 slot of the white- and blacklisting command
4334 Only the first part of a multipart message is included unless
4335 .Va forward-as-attachment ,
4336 and recipient addresses will be stripped from comments, names etc.
4337 unless the internal variable
4343 \*(OB Superseded by the multiplexer
4348 \*(OB Superseded by the multiplexer
4353 Define or list command aliases, so-called ghosts.
4354 A ghost can be used everywhere a normal command can be used, but always
4355 takes precedence: any arguments that are given to the command alias are
4356 joined onto the alias content, and the resulting string forms the
4357 command line that is, in effect, executed.
4358 Command ghosts can be removed with
4360 Without arguments a list of all currently known aliases is shown.
4361 With one argument the expansion of the given alias is shown.
4363 With two or more arguments a command alias is defined or updated: the
4364 first argument is the name under which the remaining command line should
4365 be accessible, the content of which can be just about anything.
4366 A ghost may itself expand to another ghost, but to avoid expansion loops
4367 further expansion will be prevented if a ghost refers to itself or if an
4368 expansion depth limit is reached.
4369 Explicit expansion prevention is available via reverse solidus
4372 .Sx "Command modifiers" .
4373 .Bd -literal -offset indent
4375 \*(uA: `ghost': no such alias: xx
4378 ghost xx "echo hello,"
4388 \*(NQ Multiplexer command to establish white- and blacklisting
4389 selections of header fields for a variety of applications.
4390 Without arguments the set of contexts that have settings is displayed.
4391 When given arguments, the first argument is the context to which the
4392 command applies, one of (case-insensitively)
4394 for display purposes (via, e.g.,
4397 for selecting which headers shall be stored persistently when
4403 ing messages (note that MIME related etc. header fields should not be
4404 ignored in order to not destroy usability of the message in this case),
4406 for stripping down messages when
4408 ing message (has no effect if
4409 .Va forward-as-attachment
4412 for defining user-defined set of fields for the command
4416 The current settings of the given context are displayed if only the
4417 first argument is given.
4418 A second argument denotes the type of restriction that is to be chosen,
4419 it may be (a case-insensitive prefix of)
4423 for white- and blacklisting purposes, respectively.
4424 Establishing a whitelist suppresses inspection of the corresponding
4426 If no further argument is given the current settings of the given type
4430 With four or more arguments the third denotes the action to be applied,
4435 for addition of fields, and
4439 for removal of fields from the given type of the given context.
4440 The fourth, and any following arguments are expected to specify the
4441 fields of desire, or \*(OPally, regular expression matches ought to
4443 The special wildcard field (asterisk,
4445 will establish a (fast) shorthand setting which covers all fields, or
4446 remove all fields in one operation, respectively.
4451 (h) Show the current group of headers, the size of which depends on
4454 and the style of which can be adjusted with the variable
4456 If a message-specification is given the group of headers containing the
4457 first message therein is shown and the message at the top of the screen
4472 the list of history entries;
4475 argument selects and evaluates the respective history entry,
4476 which will become the new history top; a negative number is used as an
4477 offset to the current command, e.g.,
4479 will select the last command, the history top.
4480 The default mode if no arguments are given is
4487 Takes a message list and marks each message therein to be saved in the
4492 Does not override the
4495 \*(UA deviates from the POSIX standard with this command, because a
4497 command issued after
4499 will display the following message, not the current one.
4504 (i) Part of the nestable
4505 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
4506 conditional execution construct \(em if the given condition is true then
4507 the encapsulated block is executed.
4508 POSIX only supports the (case-insensitive) conditions
4513 end, all remaining conditions are non-portable extensions; note that
4514 falsely specified conditions cause the execution of the entire
4515 conditional construct until the (matching) closing
4517 command to be suppressed.
4518 The syntax of the nestable
4520 conditional execution construct requires that each condition and syntax
4521 element is surrounded by whitespace.
4523 .Bd -literal -offset indent
4532 The (case-insensitive) condition
4534 erminal will evaluate to true if the standard input is a terminal, i.e.,
4535 in interactive sessions.
4536 Another condition can be any boolean value (see the section
4537 .Sx "INTERNAL VARIABLES"
4538 for textual boolean representations) to mark an enwrapped block as
4541 .Dq always execute .
4542 It is possible to check
4543 .Sx "INTERNAL VARIABLES"
4546 variables for existence or compare their expansion against a user given
4547 value or another variable by using the
4549 .Pf ( Dq variable next )
4550 conditional trigger character;
4551 a variable on the right hand side may be signalled using the same
4553 The variable names may be enclosed in a pair of matching braces.
4556 The available comparison operators are
4560 (less than or equal to),
4566 (greater than or equal to),
4570 (is substring of) and
4572 (is not substring of).
4573 The values of the left and right hand side are treated as strings and
4574 are compared 8-bit byte-wise, ignoring case according to the rules of
4575 the US-ASCII encoding (therefore, dependent on the active locale,
4576 possibly producing false results for strings in the locale encoding).
4577 Except for the substring checks the comparison will instead be performed
4578 arithmetically if both, the user given value as well as the variable
4579 content, can be parsed as numbers (integers).
4580 An unset variable is treated as the empty string.
4583 When the \*(OPal regular expression support is available, the additional
4589 They treat the right hand side as an extended regular expression that is
4590 matched case-insensitively and according to the active
4592 locale, meaning that strings in the locale encoding should be matched
4596 Conditions can be joined via AND-OR lists (where the AND operator is
4598 and the OR operator is
4600 which have equal precedence and will be evaluated with left
4601 associativity, thus using the same syntax that is known for the
4603 It is also possible to form groups of conditions and lists by enclosing
4604 them in pairs of brackets
4605 .Ql [\ \&.\&.\&.\ ] ,
4606 which may be interlocked within each other, and also be joined via
4610 The results of individual conditions and entire groups may be modified
4611 via unary operators: the unary operator
4613 will reverse the result.
4615 .Bd -literal -offset indent
4619 if [ "$ttycharset" == UTF-8 ] || [ "$ttycharset" == UTF8 ]
4620 echo *ttycharset* is set to UTF-8, case-insensitively
4623 if [ "${t1}" == "${t2}" ]
4624 echo These two variables are equal
4626 if [ "$version-major" >= 15 ]
4627 echo Running a new version..
4628 if [ "$features" =@ +regex ]
4629 if [ "$TERM" =~ "^xterm\&.*" ]
4630 echo ..in an X terminal
4633 if [ [ true ] && [ [ "${debug}" != '' ] || \e
4634 [ "$verbose" != '' ] ] ]
4637 if true && [ "$debug" != '' ] || [ "${verbose}" != '' ]
4638 echo Left associativity, as is known from the shell
4640 if ! ! true && ! [ ! "$debug" && ! "$verbose" ]
4641 echo Unary operator support
4651 Superseded by the multiplexer
4656 Shows the names of all available commands, alphabetically sorted.
4657 If given any non-whitespace argument the list will be shown in the order
4658 in which command prefixes are searched.
4659 In conjunction with a set variable
4661 additional information will be provided for each command: the argument
4662 type will be indicated, the \*(OPal documentation string will be shown,
4663 and the set of command flags will show up:
4665 .Bl -tag -compact -width ".It Ql BaNg"
4666 .It Ql "vput modifier"
4667 command supports the command modifier
4669 .It Ql "status in *!*"
4670 the soft exit status is tracked in
4673 commands needs an active mailbox, a
4675 .It Ql "ok: batch or interactive"
4676 command may only be used in interactive or
4679 .It Ql "ok: send mode"
4680 command can be used in send mode.
4681 .It Ql "not ok: compose mode"
4682 command is not available when in compose-mode.
4683 .It Ql "not ok: during startup"
4684 command cannot be used during program startup, e.g., while loading
4685 .Sx "Resource files" .
4686 .It Ql "ok: in subprocess"
4687 command is allowed to be used when running in a subprocess instance,
4688 e.g., from within a macro that is called via
4689 .Va on-compose-done .
4694 This command can be used to localize changes to variables, meaning that
4695 their state will be reverted to the former one once the covered scope
4697 It can only be used inside of macro definition blocks introduced by
4701 and is interpreted as a boolean (string, see
4702 .Sx "INTERNAL VARIABLES" ) ;
4705 of an account is left once it is switched off again.
4706 .Bd -literal -offset indent
4707 define temporary_settings {
4708 set possibly_global_option1
4713 set possibly_global_option2
4722 enables change localization and calls
4724 which explicitly resets localization, then any value changes within
4726 will still be reverted by
4728 \*(ID Once the outermost level, the one which enabled localization
4729 first, is left, but no earlier, all adjustments will be unrolled.
4730 \*(ID Likewise worth knowing, if in this example
4732 changes to a different
4734 which sets some variables that are yet covered by localizations, their
4735 scope will be extended, and in fact leaving the
4737 will (thus) restore settings in (likely) global scope which actually
4738 were defined in a local, private context.
4742 Reply to messages that come in via known
4745 .Pf ( Ic mlsubscribe )
4746 mailing lists, or pretend to do so (see
4747 .Sx "Mailing lists" ) :
4750 functionality this will actively resort and even remove message
4751 recipients in order to generate a message that is supposed to be sent to
4753 For example it will also implicitly generate a
4754 .Ql Mail-Followup-To:
4755 header if that seems useful, regardless of the setting of the variable
4762 but saves the message in a file named after the local part of the first
4763 recipient's address (instead of in
4768 (m) Takes a (list of) recipient address(es) as (an) argument(s),
4769 or asks on standard input if none were given;
4770 then collects the remaining mail content and sends it out.
4774 (mb) The given message list is to be sent to
4776 when \*(UA is quit; this is the default action unless the variable
4779 \*(ID This command can only be used in a
4781 .Sx "primary system mailbox" .
4785 Without any arguments the content of the MIME type cache will displayed.
4786 Otherwise each argument defines a complete MIME type specification of
4787 a type that shall be added (prepended) to the cache.
4788 In any event MIME type sources are loaded first as necessary \(en
4789 .Va mimetypes-load-control
4790 can be used to fine-tune which sources are actually loaded.
4791 Refer to the section on
4792 .Sx "The mime.types files"
4793 for more on MIME type specifications and this topic in general.
4794 MIME type unregistration and cache resets can be triggered with
4799 Without arguments the list of all currently defined mailing lists
4800 (and their attributes, if any) is shown; a more verbose listing will be
4801 produced if either of
4806 Otherwise all given arguments (which need not be quoted except for
4807 whitespace) will be added and henceforth be recognized as mailing lists.
4808 Mailing lists may be removed via the command
4811 If the \*(OPal regular expression support is available then mailing
4812 lists may also be specified as (extended) regular expressions (see
4818 Without arguments the list of all currently defined mailing lists which
4819 have a subscription attribute is shown; a more verbose listing will be
4820 produced if either of
4825 Otherwise this attribute will be set for all given mailing lists,
4826 newly creating them as necessary (as via
4828 Subscription attributes may be removed via the command
4837 but moves the messages to a file named after the local part of the
4838 sender address of the first message (instead of in
4845 but marks the messages for deletion if they were transferred
4852 but also displays header fields which would not pass the
4854 selection, and all MIME parts.
4862 on the given messages, even in non-interactive mode and as long as the
4863 standard output is a terminal.
4869 \*(OP When used without arguments or if
4871 has been given the content of the
4873 cache is shown, loading it first as necessary.
4876 then the cache will only be initialized and
4878 will remove its contents.
4879 Note that \*(UA will try to load the file only once, use
4880 .Ql Ic \&\&netrc Ns \:\0\:clear
4881 to unlock further attempts.
4886 .Sx "On URL syntax and credential lookup" ;
4888 .Sx "The .netrc file"
4889 documents the file format in detail.
4893 Checks for new mail in the current folder without committing any changes
4895 If new mail is present, a message is shown.
4899 the headers of each new message are also shown.
4900 This command is not available for all mailbox types.
4908 Goes to the next message in sequence and types it.
4909 With an argument list, types the next matching message.
4923 If the current folder is accessed via a network connection, a
4925 command is sent, otherwise no operation is performed.
4931 but also displays header fields which would not pass the
4933 selection, and all MIME parts.
4941 on the given messages, even in non-interactive mode and as long as the
4942 standard output is a terminal.
4950 but also pipes header fields which would not pass the
4952 selection, and all parts of MIME
4953 .Ql multipart/alternative
4958 (pi) Takes a message list and a shell command
4959 and pipes the messages through the command.
4960 Without an argument the current message is piped through the command
4967 every message is followed by a formfeed character.
4988 (q) Terminates the session, saving all undeleted, unsaved messages in
4991 preserving all messages marked with
4995 or never referenced in the system
4997 and removing all other messages from the
4999 .Sx "primary system mailbox" .
5000 If new mail has arrived during the session,
5002 .Dq You have new mail
5004 If given while editing a mailbox file with the command line option
5006 then the edit file is rewritten.
5007 A return to the shell is effected,
5008 unless the rewrite of edit file fails,
5009 in which case the user can escape with the exit command.
5013 \*(NQ Read a line from standard input, and assign the splitted and
5014 trimmed line data to the given variables.
5015 The variable names are check by the same rules as documented for
5017 If there are more fields than variables, assign successive fields to the
5018 last given variable.
5019 If there are less fields than variables, assign the empty string to the
5021 The return status is tracked via
5023 even though variable names are checked errors may still happen if it is
5024 tried to set, e.g., strings to variables which expect number settings;
5025 it thus only happens if names are used which have special meaning to \*(UA.
5026 \*(ID This command will likely be extended towards more
5028 compatibility: for now splitting always occurs at whitespace, reverse
5029 solidus newline escaping is always supported, and the \*(OPal line
5030 editing features are always available when on an interactive terminal.
5031 .Bd -literal -offset indent
5034 ? echo "<$a> <$b> <$c>"
5050 Removes the named files or directories.
5051 If a name refer to a mailbox, e.g., a Maildir mailbox, then a mailbox
5052 type specific removal will be performed, deleting the complete mailbox.
5053 The user is asked for confirmation in interactive mode.
5057 Takes the name of an existing folder
5058 and the name for the new folder
5059 and renames the first to the second one.
5060 Both folders must be of the same type.
5064 (R) Reply to originator.
5065 Does not reply to other recipients of the original message.
5067 will exchange this command with
5069 Unless the internal variable
5071 is set the recipient address will be stripped from comments, names etc.
5075 (r) Take a message and group-responds to it by addressing the sender
5078 .Va followup-to-honour ,
5081 .Va recipients-in-cc
5082 influence response behaviour.
5085 offers special support for replying to mailing lists.
5086 Unless the internal variable
5088 is set recipient addresses will be stripped from comments, names etc.
5101 but initiates a group-reply regardless of the value of
5108 but responds to the sender only regardless of the value of
5115 but does not add any header lines.
5116 This is not a way to hide the sender's identity,
5117 but useful for sending a message again to the same recipients.
5121 Takes a list of messages and a user name
5122 and sends each message to the named user.
5124 and related header fields are prepended to the new copy of the message.
5142 .It Ic respondsender
5148 (ret) Superseded by the multiplexer
5153 Only available inside the scope of a
5157 this will stop evaluation of any further macro content, and return
5158 execution control to the caller.
5159 If no arguments are specified, the return value, which will be stored in
5161 as well as the macro command exit status, which is made available in
5164 If only the return value is given the command exit status will be 0.
5165 Both optional parameters must be specified as unsigned (positive)
5168 \*(ID Notes: any non-0 command exit status is treated as a hard error
5169 by the state machinery, and will be propagated up and cause, e.g.,
5170 a file inclusion via
5172 to fail; this two argument form likely is a temporary hack that will
5179 but saves the messages in a file named after the local part of the
5180 sender of the first message instead of (in
5182 and) taking a filename argument.
5186 (s) Takes a message list and a filename and appends each message in turn
5187 to the end of the file.
5188 If no filename is given, the
5191 The filename in quotes, followed by the generated character count
5192 is echoed on the user's terminal.
5195 .Sx "primary system mailbox"
5196 the messages are marked for deletion.
5197 .Sx "Filename transformations"
5202 \*(OB Superseded by the multiplexer
5207 \*(OB Superseded by the multiplexer
5212 \*(OB Superseded by the multiplexer
5217 Takes a message specification (list) and displays a header summary of
5218 all matching messages, as via
5220 This command is an alias of
5223 .Sx "Specifying messages" .
5227 Takes a message list and marks all messages as having been read.
5231 (se) Without arguments this command shows all internal variables which
5232 are currently known to \*(UA (they have been set).
5233 A more verbose listing will be produced if either of
5237 are set, in which case variables may be preceded with a comment line
5238 that gives some context of what \*(UA knows about the given variable.
5240 Otherwise the given variables (and arguments) are set or adjusted.
5241 Arguments are of the form
5243 (no space before or after
5247 if there is no value, i.e., a boolean variable.
5248 Quotation marks may be placed around any part of the assignment
5249 statement to quote blanks or tabs, e.g.,
5251 .Dl set indentprefix='->'
5253 If an argument begins with
5257 the effect is the same as invoking the
5259 command with the remaining part of the variable
5260 .Pf ( Ql unset save ) .
5264 that is known to map to an environment variable will automatically cause
5265 updates in the program environment (unsetting a variable in the
5266 environment requires corresponding system support).
5267 Please use the command
5269 for further environmental control.
5274 .Sx "INTERNAL VARIABLES"
5280 (sh) Invokes an interactive version of the shell.
5284 Without arguments the list of all currently defined shortcuts is
5286 Otherwise all given arguments (which need not be quoted except for
5287 whitespace) are treated as pairs of shortcuts and their expansions,
5288 creating new or changing already existing shortcuts, as necessary.
5289 Shortcuts may be removed via the command
5294 Only available inside the scope of a
5296 ed macro, this will shift the positional parameters (starting at
5298 by the given number (which must be an unsigned, positive, decimal),
5299 or 1 if no argument has been given.
5300 It is an error if the value exceeds the number of positional parameters.
5301 If the given number is 0, no action is performed, successfully.
5307 but performs neither MIME decoding nor decryption, so that the raw
5308 message text is shown.
5312 (si) Shows the size in characters of each message of the given
5317 Shows the current sorting criterion when used without an argument.
5318 Otherwise creates a sorted representation of the current folder,
5321 command and the addressing modes such that they refer to messages in
5323 Message numbers are the same as in regular mode.
5327 a header summary in the new order is also displayed.
5328 Automatic folder sorting can be enabled by setting the
5330 variable, as in, e.g.,
5331 .Ql set autosort=thread .
5332 Possible sorting criterions are:
5334 .Bl -tag -compact -width "subject"
5336 Sort the messages by their
5338 field, that is by the time they were sent.
5340 Sort messages by the value of their
5342 field, that is by the address of the sender.
5345 variable is set, the sender's real name (if any) is used.
5347 Sort the messages by their size.
5349 \*(OP Sort the message by their spam score, as has been classified by
5352 Sort the messages by their message status.
5354 Sort the messages by their subject.
5356 Create a threaded display.
5358 Sort messages by the value of their
5360 field, that is by the address of the recipient.
5363 variable is set, the recipient's real name (if any) is used.
5368 (so) The source command reads commands from the given file.
5369 .Sx "Filename transformations"
5371 If the given expanded argument ends with a vertical bar
5373 then the argument will instead be interpreted as a shell command and
5374 \*(UA will read the output generated by it.
5375 Interpretation of commands read is stopped when an error is encountered.
5378 cannot be used from within macros that execute as
5379 .Va folder-hook Ns s
5382 i.e., it can only be called from macros that were
5389 (beside not supporting pipe syntax aka shell command input) is that
5390 this command will not generate an error nor warn if the given file
5391 argument cannot be opened successfully.
5395 \*(OP Takes a list of messages and clears their
5401 \*(OP Takes a list of messages and causes the
5403 to forget it has ever used them to train its Bayesian filter.
5404 Unless otherwise noted the
5406 flag of the message is inspected to chose whether a message shall be
5414 \*(OP Takes a list of messages and informs the Bayesian filter of the
5418 This also clears the
5420 flag of the messages in question.
5424 \*(OP Takes a list of messages and rates them using the configured
5425 .Va spam-interface ,
5426 without modifying the messages, but setting their
5428 flag as appropriate; because the spam rating headers are lost the rate
5429 will be forgotten once the mailbox is left.
5430 Refer to the manual section
5432 for the complete picture of spam handling in \*(UA.
5436 \*(OP Takes a list of messages and sets their
5442 \*(OP Takes a list of messages and informs the Bayesian filter of the
5448 flag of the messages in question.
5457 Create a threaded representation of the current folder,
5458 i.\|e. indent messages that are replies to other messages in the header
5459 display and change the
5461 command and the addressing modes such that they refer to messages in the
5463 Message numbers are the same as in unthreaded mode.
5467 a header summary in threaded order is also displayed.
5476 slot for white- and blacklisting header fields.
5480 (to) Takes a message list and types out the first
5482 lines of each message on the users' terminal.
5483 Unless a special selection has been established for the
5487 command, the only header fields that are displayed are
5498 It is possible to apply compression to what is displayed by setting
5500 Messages are decrypted and converted to the terminal character set
5505 (tou) Takes a message list and marks the messages for saving in
5507 \*(UA deviates from the POSIX standard with this command,
5510 command will display the following message instead of the current one.
5516 but also displays header fields which would not pass the
5518 selection, and all parts of MIME
5519 .Ql multipart/alternative
5524 (t) Takes a message list and types out each message on the users'
5528 For MIME multipart messages, all parts with a content type of
5532 are shown, the other are hidden except for their headers.
5533 Messages are decrypted and converted to the terminal character set
5538 Delete all given accounts.
5539 An error message is shown if a given account is not defined.
5542 will discard all existing accounts.
5546 (una) Takes a list of names defined by alias commands
5547 and discards the remembered groups of users.
5550 will discard all existing aliases.
5554 Takes a message list and marks each message as not having been answered.
5560 ing, specified by its context and input sequence, both of which may be
5561 specified as a wildcard (asterisk,
5565 will remove all bindings of all contexts.
5569 Only applicable to threaded mode.
5570 Takes a message list and makes the message and all replies to it visible
5571 in header summaries again.
5572 When a message becomes the current message,
5573 it is automatically made visible.
5574 Also when a message with collapsed replies is displayed,
5575 all of these are automatically uncollapsed.
5581 mapping for the given colour type (see
5583 for a list of types) and mapping; if the optional precondition argument
5584 is used then only the exact tuple of mapping and precondition is removed.
5587 will remove all mappings (no precondition allowed).
5589 .Sx "Coloured display"
5590 for the general picture.
5594 Undefine all given macros.
5595 An error message is shown if a given macro is not defined.
5598 will discard all existing macros.
5602 (u) Takes a message list and marks each message as not being deleted.
5605 variable is set, the last message restored will be
5607 d automatically; if no message list had been specified then the usual
5608 search for a visible message is performed, as documented for
5610 showing only the next input prompt if the search fails.
5618 Takes a message list and
5624 Takes a message list and marks each message as not being
5629 \*(OB Superseded by the multiplexer
5634 \*(OB Superseded by the multiplexer
5639 Remove all the given command
5643 will remove all ghosts.
5647 Superseded by the multiplexer
5652 Delete all given MIME types, e.g.,
5653 .Ql unmimetype text/plain
5654 will remove all registered specifications for the MIME type
5658 will discard all existing MIME types, just as will
5660 but which also reenables cache initialization via
5661 .Va mimetypes-load-control .
5665 Forget about all the given mailing lists.
5668 will remove all lists.
5673 .It Ic unmlsubscribe
5674 Remove the subscription attribute from all given mailing lists.
5677 will clear the attribute from all lists which have it set.
5688 Takes a message list and marks each message as not having been read.
5692 Superseded by the multiplexer
5697 \*(OB Superseded by the multiplexer
5702 \*(OB Superseded by the multiplexer
5707 \*(NQ (uns) Takes a list of internal variable names and discards their
5708 remembered values; the reverse of
5715 Deletes the shortcut names given as arguments.
5718 will remove all shortcuts.
5722 Disable sorted or threaded mode
5728 return to normal message order and,
5732 displays a header summary.
5742 \*(NQ Perform URL percent codec operations, rather according to RFC 3986.
5746 .Sx "Command modifiers" ) .
5747 The return status is tracked via
5749 This is a character set agnostic and thus locale dependent operation,
5750 and it may decode bytes which are invalid in the current locale, unless
5751 the input solely consists of characters in the portable character set, see
5752 .Sx "Character sets" .
5753 \*(ID This command does not about URLs beside that.
5755 The first argument specifies the operation:
5759 perform plain URL percent en- and decoding, respectively.
5763 perform a slightly modified operation which should be better for
5764 pathnames: it does not allow a tilde
5766 and will neither accept hyphen-minus
5770 as an initial character.
5771 The remaining arguments form the URL data which is to be converted.
5775 \*(NQ Edit the values of or create the given variable(s) in the
5777 Boolean variables cannot be edited, and variables can also not be
5783 \*(NQ This command produces the same output as the listing mode of
5787 ity adjustments, but only for the given variables.
5791 \*(OP Takes a message list and verifies each message.
5792 If a message is not a S/MIME signed message,
5793 verification will fail for it.
5794 The verification process checks if the message was signed using a valid
5796 if the message sender's email address matches one of those contained
5797 within the certificate,
5798 and if the message content has been altered.
5811 \*(NQ Evaluate arguments according to a given operator.
5812 This is a multiplexer command which can be used to perform signed 64-bit
5813 numeric calculations as well as string operations.
5814 It uses polish notation, i.e., the operator is the first argument and
5815 defines the number and type, and the meaning of the remaining arguments.
5816 An empty argument is replaced with a 0 if a number is expected.
5820 .Sx "Command modifiers" ) .
5821 The return status is tracked via
5823 the result that is shown in case of (soft) errors is
5825 In general only invalid use cases cause hard errors which are reflected in
5827 and affect the state machine.
5830 Numeric operations work on one or two signed 64-bit integers.
5831 One integer is expected by assignment (equals sign
5833 which does nothing but parsing the argument, thus detecting validity and
5834 possible overflow conditions, and unary not (tilde
5836 which creates the bitwise complement.
5837 Two integers are used by addition (plus sign
5839 subtraction (hyphen-minus
5841 multiplication (asterisk
5845 and modulo (percent sign
5847 as well as for the bitwise operators logical or (vertical bar
5850 bitwise and (ampersand
5853 bitwise xor (circumflex
5855 the bitwise signed left- and right shifts
5858 as well as for the unsigned right shift
5862 All numeric operators can be suffixed with a commercial at
5866 this will turn the operation into a saturated one, which means that
5867 overflow errors and division and modulo by zero are still reflected in
5868 the return status, but the result will linger at the minimum or maximum
5869 possible value, instead of overflowing (or trapping).
5870 For the bitwise shifts, the saturated maximum is 63.
5871 If in saturated mode the overflow occurs during parsing the numbers,
5872 then the actual operation will not be performed but the given maximum
5873 value is used as the result immediately.
5876 String operations that take one argument are
5878 which queries the length of the given argument,
5880 which calculates the Chris Torek hash of the given string, and
5882 which performs the usual
5883 .Sx "Filename transformations" ,
5884 on its argument, as well as
5886 which generates a random string of the given length, or of
5888 bytes (a constant from
5890 if the value 0 is given; the random string will be base64url encoded
5891 according to RFC 4648, and thus be usable as a file name.
5894 String operations with two or more arguments are
5896 which searches in the first for the second argument, and shows the
5897 resulting 0-based offset shall it have been found,
5899 which is identical to
5901 but works case-insensitively according to the rules of the ASCII
5904 will show a substring of its first argument:
5905 the second argument is the 0-based starting offset, the optional third
5906 argument can be used to specify the length of the desired substring,
5907 by default the entire string is used;
5908 this operation tries to work around faulty arguments, but the (soft)
5909 return status will still reflect them (set
5916 will try to match the first argument with the regular expression given
5917 in the second argument, as does
5919 but which is case-insensitive.
5920 These operators match according to the active
5922 locale and thus should match correctly strings in the locale encoding.
5923 If the optional third argument has been given then instead of showing
5924 the match offset a replacement operation is performed:
5925 the third argument is treated as if specified via dollar-single-quote
5927 .Sx "Shell-style argument quoting" ) ,
5928 and any occurrence of a positional parameter, e.g.,
5930 is replaced by the corresponding match group of the regular expression.
5932 .Bd -literal -offset indent
5933 ? vexpr -@ +1 -9223372036854775808
5934 ? vput vexpr res ir bananarama (.*)nana(.*) '\e${1}au\e$2'
5941 (v) Takes a message list and invokes the display editor on each message.
5942 Modified contents are discarded unless the
5948 (w) For conventional messages the body without all headers is written.
5949 The original message is never marked for deletion in the originating
5951 The output is decrypted and converted to its native format as necessary.
5952 If the output file exists, the text is appended.
5953 If a message is in MIME multipart format its first part is written to
5954 the specified file as for conventional messages, handling of the remains
5955 depends on the execution mode.
5956 No special handling of compressed files is performed.
5958 In interactive mode the user is consecutively asked for the filenames of
5959 the processed parts.
5960 For convience saving of each part may be skipped by giving an empty
5961 value, the same result as writing it to
5963 Shell piping the part content by specifying a leading vertical bar
5965 character for the filename is supported.
5966 Other user input undergoes the usual
5967 .Sx "Filename transformations" ,
5968 and contents of the destination file are overwritten if the file
5971 \*(ID In non-interactive mode any part which does not specify a filename
5972 is ignored, and suspicious parts of filenames of the remaining parts are
5973 URL percent encoded (as via
5975 to prevent injection of malicious character sequences, resulting in
5976 a filename that will be written into the current directory.
5977 Existing files will not be overwritten, instead the part number or
5978 a dot are appended after a number sign
5980 to the name until file creation succeeds (or fails due to other
5990 \*(UA presents message headers in
5992 fuls as described under the
5995 Without arguments this command scrolls to the next window of messages,
5996 likewise if the argument is
6000 scrolls to the last,
6002 scrolls to the first, and
6007 A number argument prefixed by
6011 indicates that the window is calculated in relation to the current
6012 position, and a number without a prefix specifies an absolute position.
6018 but scrolls to the next or previous window that contains at least one
6028 .\" .Sh COMMAND ESCAPES {{{
6029 .Sh "COMMAND ESCAPES"
6031 Here is a summary of the command escapes available in compose mode,
6032 which are used to perform special functions when composing messages.
6033 Command escapes are only recognized at the beginning of lines.
6034 The actual escape character can be set via the internal variable
6036 it defaults to the tilde
6040 .Bl -tag -width ".It Ic BaNg"
6043 Insert the string of text in the message prefaced by a single
6045 (If the escape character has been changed,
6046 that character must be doubled
6047 in order to send it at the beginning of a line.)
6050 .It Ic ~! Ar command
6051 Execute the indicated shell
6053 which follows, replacing unescaped exclamation marks with the previously
6054 executed command if the internal variable
6056 is set, then return to the message.
6060 Same effect as typing the end-of-file character.
6063 .It Ic ~: Ar \*(UA-command Ns \0or Ic ~_ Ar \*(UA-command
6064 Execute the given \*(UA command.
6065 Not all commands, however, are allowed.
6069 Write a summary of command escapes.
6072 .It Ic ~< Ar filename
6077 .It Ic ~<! Ar command
6079 is executed using the shell.
6080 Its standard output is inserted into the message.
6083 .It Ic ~@ Op Ar filename...
6084 Append or edit the list of attachments.
6087 arguments is expected (see
6088 .Sx "Shell-style argument quoting" ;
6089 any token-separating commas are ignored), to be
6090 interpreted as documented for the command line option
6092 with the message number exception as below.
6095 arguments the attachment list is edited, entry by entry;
6096 if a filename is left empty, that attachment is deleted from the list;
6097 once the end of the list is reached either new attachments may be
6098 entered or the session can be quit by committing an empty
6101 For each mode, if a given file name solely consists of the number sign
6103 followed by a valid message number of the currently active mailbox, then
6104 the given message is attached as a MIME
6106 part (note the number sign is the comment character and must be quoted).
6110 Inserts the string contained in the
6113 .Ql Ic ~i Ns \0Sign ) .
6118 ting the variable(s) instead!) The escape sequences tabulator
6126 Inserts the string contained in the
6129 .Ql Ic ~i Ns \0sign ) .
6134 ting the variable(s) instead!) The escape sequences tabulator
6141 .It Ic ~b Ar name ...
6142 Add the given names to the list of blind carbon copy recipients.
6145 .It Ic ~c Ar name ...
6146 Add the given names to the list of carbon copy recipients.
6150 Read the file specified by the
6152 variable into the message.
6156 Invoke the text editor on the message collected so far.
6157 After the editing session is finished,
6158 the user may continue appending text to the message.
6161 .It Ic ~F Ar messages
6162 Read the named messages into the message being sent, including all
6163 message headers and MIME parts.
6164 If no messages are specified, read in the current message.
6167 .It Ic ~f Ar messages
6168 Read the named messages into the message being sent.
6169 If no messages are specified, read in the current message.
6170 Strips down the list of header fields according to the
6172 white- and blacklist selection of
6174 For MIME multipart messages,
6175 only the first displayable part is included.
6179 Edit the message header fields
6184 by typing each one in turn and allowing the user to edit the field.
6185 The default values for these fields originate from the
6193 Edit the message header fields
6199 by typing each one in turn and allowing the user to edit the field.
6202 .It Ic ~i Ar variable
6203 Insert the value of the specified variable into the message,
6204 adding a newline character at the end.
6205 The message remains unaltered if the variable is unset or empty.
6210 ting the variable(s) instead!) The escape sequences tabulator
6217 .It Ic ~M Ar messages
6218 Read the named messages into the message being sent,
6221 If no messages are specified, read the current message.
6224 .It Ic ~m Ar messages
6225 Read the named messages into the message being sent,
6228 If no messages are specified, read the current message.
6229 Strips down the list of header fields according to the
6231 white- and blacklist selection of
6233 For MIME multipart messages,
6234 only the first displayable part is included.
6238 Display the message collected so far,
6239 prefaced by the message header fields
6240 and followed by the attachment list, if any.
6244 Abort the message being sent,
6245 copying it to the file specified by the
6252 .It Ic ~R Ar filename
6255 but indent each line that has been read by
6259 .It Ic ~r Ar filename Op Ar HERE-delimiter
6260 Read the named file into the message.
6262 can also be a hyphen-minus
6264 in which case standard input is used, e.g., for pasting purposes.
6265 Only in this latter mode
6267 may be given: if it is data will be read in until the given
6269 is seen on a line by itself, and encountering EOF is an error; the
6271 is a required argument in non-interactive mode;
6272 note that variables expansion is performed on the delimiter.
6276 Cause the named string to become the current subject field.
6277 Newline (NL) and carriage-return (CR) bytes are invalid and will be
6278 normalized to space (SP) characters.
6281 .It Ic ~t Ar name ...
6282 Add the given name(s) to the direct recipient list.
6285 .It Ic ~U Ar messages
6286 Read in the given / current message(s) excluding all headers, indented by
6290 .It Ic ~u Ar messages
6291 Read in the given / current message(s), excluding all headers.
6295 Invoke an alternate editor (defined by the
6297 environment variable) on the message collected so far.
6298 Usually, the alternate editor will be a screen editor.
6299 After the editor is quit,
6300 the user may resume appending text to the end of the message.
6303 .It Ic ~w Ar filename
6304 Write the message onto the named file.
6306 the message is appended to it.
6312 except that the message is not saved at all.
6315 .It Ic ~| Ar command
6316 Pipe the message through the specified filter command.
6317 If the command gives no output or terminates abnormally,
6318 retain the original text of the message.
6321 is often used as a rejustifying filter.
6325 .It Ic ~^ Ar cmd Op Ar subcmd Op Ar arg3 Op Ar arg4
6326 Low-level command ment for scripted message access, i.e., for
6327 .Va on-compose-done-shell
6329 .Va on-compose-done .
6330 The used protocol is likely subject to changes, and therefore the
6331 mentioned hooks receive the used protocol version as an initial line.
6332 In general the first field of a response line represents a status code
6333 which specifies whether a command was successful or not, whether result
6334 data is to be expected, and if, the format of the result data.
6335 The status codes are:
6338 .Bl -tag -compact -width _210_
6340 Status ok; the remains of the line are the result.
6342 Status ok; the rest of the line is optionally used for more status.
6343 What follows are lines of result addresses, terminated by an empty line.
6344 The address lines consist of two fields, the first of which is the
6345 plain address, e.g.,
6347 separated by a single ASCII SP space from the second which contains the
6348 unstripped address, even if that is identical to the first field, e.g.,
6349 .Ql (Lovely) Bob <bob@exam.ple> .
6351 Status ok; the rest of the line is optionally used for more status.
6352 What follows are lines of furtherly unspecified string content,
6353 terminated by an empty line.
6354 (All the input, including the empty line, must be consumed before
6355 further commands can be issued.)
6357 Syntax error; invalid command.
6359 Syntax error in parameters or arguments.
6361 Error: an argument fails verification.
6362 For example an invalid address has been specified.
6364 Error: an otherwise valid argument is rendered invalid due to context.
6365 For example, a second address is added to a header which may consist of
6366 a single address only.
6370 If a command indicates failure then the message will have remained
6372 Most commands can fail with
6374 if required arguments are missing (false command usage).
6375 The following commands are supported, and, as usual, case-insensitive:
6378 .Bl -hang -width header
6380 This command allows listing, inspection, and editing of message headers.
6381 The second argument specifies the subcommand to apply, one of:
6384 .Bl -hang -compact -width remove
6386 Without a third argument a list of all yet existing headers is given via
6388 this command is the default command of
6390 if no second argument has been given.
6391 A third argument restricts output to the given header only, which may
6394 if no such field is defined.
6397 Shows the content of the header given as the third argument.
6398 Dependent on the header type this may respond with
6402 any failure results in
6406 This will remove all instances of the header given as the third
6411 if no such header can be found.
6414 Create a new or an additional instance of the header given in the third
6415 argument, with the header body content as given in the fourth argument
6416 (the remains of the line).
6419 if the third argument specifies a free-form header field name that is
6420 invalid, or if body content extraction fails to succeed,
6422 if any extracted address does not pass syntax and/or security checks, and
6424 to indicate prevention of excessing a single-instance header \(em note that
6426 can be appended to (a space separator will be added automatically first).
6428 is returned upon success.
6433 This command allows listing, removal and addition of message attachments.
6434 The second argument specifies the subcommand to apply, one of:
6437 .Bl -hang -compact -width remove
6439 List all attachments via
6443 if no attachments exist.
6444 This command is the default command of
6446 if no second argument has been given.
6449 This will remove the attachment given as the third argument, and report
6453 if no such attachment can be found.
6454 If there exists any path component in the given argument, then an exact
6455 match of the path which has been used to create the attachment is used
6456 directly, but if only the basename of that path matches then all
6457 attachments are traversed to find an exact match first, and the removal
6458 occurs afterwards; if multiple basenames match, a
6461 Message attachments are treated as absolute pathnames.
6463 If no path component exists in the given argument, then all attachments
6464 will be searched for
6466 parameter matches as well as for matches of the basename of the path
6467 which has been used when the attachment has been created; multiple
6472 This will interpret the third argument as a number and remove the
6473 attachment at that list position (counting from one!), reporting
6477 if the argument is not a number or
6479 if no such attachment exists.
6482 Adds the attachment given as the third argument, specified exactly as
6483 documented for the command line option
6485 and supporting the message number extension as documented for
6489 upon success, with the index of the new attachment following,
6491 if the given file cannot be opened,
6493 if an on-the-fly performed character set conversion fails, otherwise
6495 is reported; this is also reported if character-set conversion is
6496 requested but not available.
6499 This uses the same search mechanism as described for
6501 and prints any known attributes of the first found attachment via
6505 if no such attachment can be found.
6506 The attributes are written as lines of keyword and value tuples, the
6507 keyword being separated from the rest of the line with an ASCII SP space
6511 This uses the same search mechanism as described for
6513 and is otherwise identical to
6516 .It Ar attribute-set
6517 This uses the same search mechanism as described for
6519 and will assign the attribute given as the fourth argument, which is
6520 expected to be a value tuple of keyword and other data, separated by
6521 a ASCII SP space or TAB tabulator character.
6522 If the value part is empty, then the given attribute is removed, or
6523 reset to a default value if existence of the attribute is crucial.
6526 upon success, with the index of the found attachment following,
6528 for message attachments or if the given keyword is invalid, and
6530 if no such attachment can be found.
6531 The following keywords may be used (case-insensitively):
6533 .Bl -hang -compact -width ".Ql filename"
6535 Sets the filename of the MIME part, i.e., the name that is used for
6536 display and when (suggesting a name for) saving (purposes).
6537 .It Ql content-description
6538 Associate some descriptive information to the attachment's content, used
6539 in favour of the plain filename by some MUAs.
6541 May be used for uniquely identifying MIME entities in several contexts;
6542 this expects a special reference address format as defined in RFC 2045
6545 upon address content verification failure.
6547 Specifies the media type and subtype of the part; managed automatically.
6548 .It Ql content-disposition
6549 Automatically set to the string
6553 .It Ar attribute-set-at
6554 This uses the same search mechanism as described for
6556 and is otherwise identical to
6566 .\" .Sh INTERNAL VARIABLES {{{
6567 .Sh "INTERNAL VARIABLES"
6569 Internal \*(UA variables are controlled via the
6573 commands; prefixing a variable name with the string
6577 has the same effect as using
6583 Creation or editing of variables can be performed in the
6588 will give more insight on the given variable(s), and
6590 when called without arguments, will show a listing of all variables.
6591 Both commands support a more
6594 Some well-known variables will also become inherited from the
6597 implicitly, others can be explicitly imported with the command
6599 and henceforth share said properties.
6602 Two different kind of internal variables exist.
6603 There are boolean variables, which can only be in one of the two states
6607 and value variables with a(n optional) string value.
6608 For the latter proper quoting is necessary upon assignment time, the
6609 introduction of the section
6611 documents the supported quoting rules.
6613 .Bd -literal -offset indent
6614 wysh set one=val\e 1 two="val 2" \e
6615 three='val "3"' four=$'val \e'4\e''; \e
6616 varshow one two three four; \e
6617 unset one two three four
6621 Dependent upon the actual option the string values will be interpreted
6622 as numbers, colour names, normal text etc., but there also exists
6623 a special kind of string value, the
6624 .Dq boolean string ,
6625 which must either be a decimal integer (in which case
6629 and any other value is true) or any of the (case-insensitive) strings
6635 for a false boolean and
6641 for a true boolean; a special kind of boolean string is the
6643 which is a boolean string that can optionally be prefixed with the
6644 (case-insensitive) term
6648 which causes prompting of the user in interactive mode, with the given
6649 boolean as the default value.
6651 .\" .Ss "Initial settings" {{{
6652 .\" (Keep in SYNC: ./nail.h:okeys, ./nail.rc, ./nail.1:"Initial settings")
6653 .Ss "Initial Settings"
6655 The standard POSIX 2008/Cor 2-2016 mandates the following initial
6661 .Pf no Va autoprint ,
6675 .Pf no Va ignoreeof ,
6677 .Pf no Va keepsave ,
6679 .Pf no Va outfolder ,
6687 .Pf no Va sendwait ,
6696 Notes: \*(UA does not support the
6698 variable \(en use command line options or
6700 to pass options through to a
6702 And the default global
6704 file, which is loaded unless the
6706 (with according argument) or
6708 command line options have been used, or the
6709 .Ev MAILX_NO_SYSTEM_RC
6710 environment variable is set, see
6711 .Sx "Resource files" )
6712 bends those initial settings a bit, e.g., it sets the variables
6717 to name a few, establishes a default
6719 selection etc., and should thus be taken into account.
6722 .\" .Ss "Variables" {{{
6725 .Bl -tag -width ".It Va BaNg"
6729 \*(RO The (hard) exit status of the last command.
6730 This exit status has a meaning for the state machine, in parts
6731 prescribed by the POSIX standard, and, e.g., for
6734 .Va batch-exit-on-error .
6735 This is why \*(UA also knows about a
6737 exit status, which is tracked in
6744 exit status of the last command, which, different to
6746 has no meaning for the state machine, and can therefore easily transport
6747 different error-indicating values.
6748 It is directly addressable with the command
6759 \*(RO Only available inside the scope of a
6761 ed macro, this will expand to all parameters of the macro, separated by
6763 \*(ID The special semantics of the equally named special parameter of the
6765 are not yet supported.
6769 \*(RO Only available inside the scope of a
6771 ed macro, this will expand to all parameters of the macro, separated by
6773 \*(ID The special semantics of the equally named special parameter of the
6775 are not yet supported.
6779 \*(RO Only available inside the scope of a
6781 ed macro, this will expand to the number of positional parameters in
6786 \*(RO Available inside the scope of a
6790 ed macro, this expands to the name of the calling macro, or to the empty
6791 string if the macro is running from top-level.
6792 For the \*(OPal regular expression search and replace operator of
6794 this expands to the entire matching expression.
6798 \*(RO Available inside the scope of a
6802 ed macro, this will access the first positional parameter passed.
6803 All further parameters can be accessed with this syntax, too, e.g.,
6806 etc.; positional parameters can be shifted off the stack by calling
6808 Positional parameters are also accessible in the \*(OPal regular
6809 expression search and replace expression of
6814 \*(RO Is set to the active
6819 \*(RO Is set to the list of
6823 .It Va -folder-resolved
6824 \*(RO Set to the fully resolved path of
6826 once that evaluation has occurred; rather internal.
6829 .It Va -mailbox-display
6830 \*(RO The name of the current mailbox
6832 possibly abbreviated for display purposes.
6835 .It Va -mailbox-resolved
6836 \*(RO The fully resolved path of the current mailbox.
6839 .It Va add-file-recipients
6840 \*(BO When file or pipe recipients have been specified,
6841 mention them in the corresponding address fields of the message instead
6842 of silently stripping them from their recipient list.
6843 By default such addressees are not mentioned.
6847 \*(BO Causes only the local part to be evaluated
6848 when comparing addresses.
6852 \*(BO Causes messages saved in
6854 to be appended to the end rather than prepended.
6855 This should always be set.
6859 \*(BO Causes \*(UA to prompt for the subject of each message sent.
6860 If the user responds with simply a newline,
6861 no subject field will be sent.
6865 \*(BO Causes the prompts for
6869 lists to appear after the message has been edited.
6873 \*(BO If set, \*(UA asks for files to attach at the end of each message,
6874 shall the list be found empty at that time.
6875 An empty line finalizes the list.
6879 \*(BO Causes the user to be prompted for carbon copy recipients
6880 (at the end of each message if
6884 are set) shall the list be found empty (at that time).
6885 An empty line finalizes the list.
6889 \*(BO Causes the user to be prompted for blind carbon copy
6890 recipients (at the end of each message if
6894 are set) shall the list be found empty (at that time).
6895 An empty line finalizes the list.
6899 \*(BO\*(OP Causes the user to be prompted if the message is to be
6900 signed at the end of each message.
6903 variable is ignored when this variable is set.
6907 \*(BO Alternative name for
6912 A sequence of characters to display in the
6916 as shown in the display of
6918 each for one type of messages (see
6919 .Sx "Message states" ) ,
6920 with the default being
6923 .Ql NU\ \ *HMFAT+\-$~
6926 variable is set, in the following order:
6928 .Bl -tag -compact -width ".It Ql _"
6950 start of a collapsed thread.
6952 an uncollapsed thread (TODO ignored for now).
6956 classified as possible spam.
6962 Specifies a list of recipients to which a blind carbon copy of each
6963 outgoing message will be sent automatically.
6967 Specifies a list of recipients to which a carbon copy of each outgoing
6968 message will be sent automatically.
6972 \*(BO Causes threads to be collapsed automatically when threaded mode
6979 \*(BO Enable automatic
6981 ing of a(n existing)
6987 commands, e.g., the message that becomes the new
6989 is shown automatically, as via
6996 \*(BO\*(OB Causes threaded mode (see the
6998 command) to be entered automatically when a folder is opened.
7000 .Ql autosort=thread .
7004 Causes sorted mode (see the
7006 command) to be entered automatically with the value of this variable as
7007 sorting method when a folder is opened, e.g.,
7008 .Ql set autosort=thread .
7012 \*(BO Enables the substitution of all not (reverse-solidus) escaped
7015 characters by the contents of the last executed command for the
7017 shell escape command and
7019 one of the compose mode
7020 .Sx "COMMAND ESCAPES" .
7021 If this variable is not set no reverse solidus stripping is performed.
7024 .It Va batch-exit-on-error
7025 If the batch mode has been enabled via the
7027 command line option, then this variable will be consulted whenever \*(UA
7028 completes one operation.
7029 It is ment as a convenient alternative to manually testing
7031 If any value is set, a number is expected; if it is
7033 then each failed operation will cause \*(UA to exit.
7035 \*(ID If it is set without a value, then only top-level operations that
7037 .Dq on the command-prompt ,
7038 i.e., neither in running macros nor from within source files etc., are
7039 considered, unless a main operation that directly affects the return
7040 value, like, e.g., a failed
7042 command, is affected; this mode of operation is likely to change in v15,
7043 and tests should be performed to see whether the desired effect is seen.
7047 \*(OP Terminals generate multi-byte sequences for certain forms of
7048 input, for example for function and other special keys.
7049 Some terminals however do not write these multi-byte sequences as
7050 a whole, but byte-by-byte, and the latter is what \*(UA actually reads.
7051 This variable specifies the timeout in milliseconds that the MLE (see
7052 .Sx "On terminal control and line editor" )
7053 waits for more bytes to arrive unless it considers a sequence
7059 \*(BO Causes automatic display of a header summary after executing a
7061 command, and thus complements the standard variable
7063 which controls header summary display on program startup.
7064 It is only meaningful if
7070 \*(BO Sets some cosmetical features to traditional BSD style;
7071 has the same affect as setting
7073 and all other variables prefixed with
7075 it also changes the behaviour of
7077 (which does not exist in BSD).
7081 \*(BO Changes the letters shown in the first column of a header
7082 summary to traditional BSD style.
7086 \*(BO Changes the display of columns in a header summary to traditional
7091 \*(BO Changes some informational messages to traditional BSD style.
7097 field to appear immediately after the
7099 field in message headers and with the
7101 .Sx "COMMAND ESCAPES" .
7105 The value that should appear in the
7109 MIME header fields when no character set conversion of the message data
7111 This defaults to US-ASCII, and the chosen character set should be
7112 US-ASCII compatible.
7116 \*(OP The default 8-bit character set that is used as an implicit last
7117 member of the variable
7119 This defaults to UTF-8 if character-set conversion capabilities are
7120 available, and to ISO-8859-1 otherwise, in which case the only supported
7123 and this variable is effectively ignored.
7124 Refer to the section
7125 .Sx "Character sets"
7126 for the complete picture of character set conversion in \*(UA.
7129 .It Va charset-unknown-8bit
7130 \*(OP RFC 1428 specifies conditions when internet mail gateways shall
7132 the content of a mail message by using a character set with the name
7134 Because of the unclassified nature of this character set \*(UA will not
7135 be capable to convert this character set to any other character set.
7136 If this variable is set any message part which uses the character set
7138 is assumed to really be in the character set given in the value,
7139 otherwise the (final) value of
7141 is used for this purpose.
7143 This variable will also be taken into account if a MIME type (see
7144 .Sx "The mime.types files" )
7145 of a MIME message part that uses the
7147 character set is forcefully treated as text.
7151 The default value for the
7156 .It Va colour-disable
7157 \*(BO\*(OP Forcefully disable usage of colours.
7158 Also see the section
7159 .Sx "Coloured display" .
7163 \*(BO\*(OP Whether colour shall be used for output that is paged through
7165 Note that pagers may need special command line options, e.g.,
7173 in order to support colours.
7174 Often doing manual adjustments is unnecessary since \*(UA may perform
7175 adjustments dependent on the value of the environment variable
7177 (see there for more).
7181 In a(n interactive) terminal session, then if this valued variable is
7182 set it will be used as a threshold to determine how many lines the given
7183 output has to span before it will be displayed via the configured
7187 can be forced by setting this to the value
7189 setting it without a value will deduce the current height of the
7190 terminal screen to compute the treshold (see
7195 \*(ID At the moment this uses the count of lines of the message in wire
7196 format, which, dependent on the
7198 of the message, is unrelated to the number of display lines.
7199 (The software is old and historically the relation was a given thing.)
7203 Define a set of custom headers to be injected into newly composed or
7204 forwarded messages; it is also possible to create custom headers in
7207 which can be automated by setting one of the hooks
7208 .Va on-compose-done-shell
7210 .Va on-compose-done .
7211 The value is interpreted as a comma-separated list of custom headers to
7212 be injected, to include commas in the header bodies escape them with
7214 \*(ID Overwriting of automatically managed headers is neither supported
7217 .Dl set customhdr='Hdr1: Body1-1\e, Body1-2, Hdr2: Body2'
7221 Controls the appearance of the
7223 date and time format specification of the
7225 variable, that is used, for example, when viewing the summary of
7227 If unset, then the local receiving date is used and displayed
7228 unformatted, otherwise the message sending
7230 It is possible to assign a
7232 format string and control formatting, but embedding newlines via the
7234 format is not supported, and will result in display errors.
7236 .Ql %Y-%m-%d %H:%M ,
7238 .Va datefield-markout-older .
7241 .It Va datefield-markout-older
7242 Only used in conjunction with
7244 Can be used to create a visible distinction of messages dated more than
7245 a day in the future, or older than six months, a concept comparable to the
7247 option of the POSIX utility
7249 If set to the empty string, then the plain month, day and year of the
7251 will be displayed, but a
7253 format string to control formatting can be assigned.
7259 \*(BO Enables debug messages and obsoletion warnings, disables the
7260 actual delivery of messages and also implies
7266 .It Va disposition-notification-send
7268 .Ql Disposition-Notification-To:
7269 header (RFC 3798) with the message.
7273 .\" TODO .It Va disposition-notification-send-HOST
7275 .\".Va disposition-notification-send
7276 .\" for SMTP accounts on a specific host.
7277 .\" TODO .It Va disposition-notification-send-USER@HOST
7279 .\".Va disposition-notification-send
7280 .\"for a specific account.
7284 \*(BO When dot is set, a period
7286 on a line by itself during message input in (interactive) compose mode
7287 will be treated as end-of-message (in addition to the normal end-of-file
7296 .It Va dotlock-ignore-error
7297 \*(BO\*(OP Synchronization of mailboxes which \*(UA treats as
7299 .Sx "primary system mailbox" Ns
7300 es (see, e.g., the notes on
7301 .Sx "Filename transformations" ,
7302 as well as the documentation of
7304 will be protected with so-called dotlock files\(emthe traditional mail
7305 spool file locking method\(emin addition to system file locking.
7306 Because \*(UA ships with a privilege-separated dotlock creation program
7307 that should always be able to create such a dotlock file there is no
7308 good reason to ignore dotlock file creation errors, and thus these are
7309 fatal unless this variable is set.
7313 \*(BO If this variable is set then the editor is started automatically
7314 when a message is composed in interactive mode, as if the
7316 .Sx "COMMAND ESCAPES"
7320 variable is implied for this automatically spawned editor session.
7324 \*(BO When a message is edited while being composed,
7325 its header is included in the editable text.
7335 fields are accepted within the header, other fields are ignored.
7339 \*(BO When entering interactive mode \*(UA normally writes
7340 .Dq \&No mail for user
7341 and exits immediately if a mailbox is empty or does not exist.
7342 If this variable is set \*(UA starts even with an empty or nonexistent
7343 mailbox (the latter behaviour furtherly depends upon
7350 .Ql Content-Transfer-Encoding
7351 to use in outgoing text messages and message parts, where applicable.
7352 (7-bit clean text messages are sent as-is, without a transfer encoding.)
7355 .Bl -tag -compact -width "_%%_"
7358 8-bit transport effectively causes the raw data be passed through
7359 unchanged, but may cause problems when transferring mail messages over
7360 channels that are not ESMTP (RFC 1869) compliant.
7361 Also, several input data constructs are not allowed by the
7362 specifications and may cause a different transfer-encoding to be used.
7363 .It Ql quoted-printable
7365 Quoted-printable encoding is 7-bit clean and has the property that ASCII
7366 characters are passed through unchanged, so that an english message can
7367 be read as-is; it is also acceptible for other single-byte locales that
7368 share many characters with ASCII, like, e.g., ISO-8859-1.
7369 The encoding will cause a large overhead for messages in other character
7370 sets: e.g., it will require up to twelve (12) bytes to encode a single
7371 UTF-8 character of four (4) bytes.
7373 .Pf (Or\0 Ql b64 . )
7374 The default encoding, it is 7-bit clean and will always be used for
7376 This encoding has a constant input:output ratio of 3:4, regardless of
7377 the character set of the input data it will encode three bytes of input
7378 to four bytes of output.
7379 This transfer-encoding is not human readable without performing
7385 If defined, the first character of the value of this variable
7386 gives the character to use in place of tilde
7389 .Sx "COMMAND ESCAPES" .
7390 If set to the empty string, command escapes are disabled.
7394 If not set then file and command pipeline targets are not allowed,
7395 and any such address will be filtered out, giving a warning message.
7396 If set without a value then all possible recipient address
7397 specifications will be accepted \(en see the section
7398 .Sx "On sending mail, and non-interactive mode"
7400 To accept them, but only in interactive mode, or when tilde commands
7401 were enabled explicitly by using one of the command line options
7405 set this to the (case-insensitive) value
7407 (it actually acts like
7408 .Ql restrict,-all,+name,+addr ,
7409 so that care for ordering issues must be taken) .
7411 In fact the value is interpreted as a comma-separated list of values.
7414 then the existence of disallowed specifications is treated as a hard
7415 send error instead of only filtering them out.
7416 The remaining values specify whether a specific type of recipient
7417 address specification is allowed (optionally indicated by a plus sign
7419 prefix) or disallowed (prefixed with a hyphen-minus
7423 addresses all possible address specifications,
7427 command pipeline targets,
7429 plain user names and (MTA) aliases (\*(OB
7431 may be used as an alternative syntax to
7436 These kind of values are interpreted in the given order, so that
7437 .Ql restrict,\:fail,\:+file,\:-all,\:+addr
7438 will cause hard errors for any non-network address recipient address
7439 unless \*(UA is in interactive mode or has been started with the
7443 command line option; in the latter case(s) any address may be used, then.
7445 Historically invalid network addressees are silently stripped off.
7446 To change this and ensure that any encountered invalid email address
7447 instead causes a hard error, ensure the string
7449 is an entry in the above list.
7450 Setting this automatically enables network addressees
7451 (it actually acts like
7452 .Ql failinvaddr,+addr ,
7453 so that care for ordering issues must be taken) .
7457 Unless this variable is set additional
7459 (Mail-Transfer-Agent)
7460 arguments from the command line, as can be given after a
7462 separator, are ignored due to safety reasons.
7463 However, if set to the special (case-insensitive) value
7465 then the presence of additional MTA arguments is treated as a hard
7466 error that causes \*(UA to exit with failure status.
7467 A lesser strict variant is the otherwise identical
7469 which does accept such arguments in interactive mode, or if tilde
7470 commands were enabled explicitly by using one of the command line options
7477 \*(RO String giving a list of features \*(UA, preceded with a plus sign
7479 if the feature is available, and a hyphen-minus
7482 The output of the command
7484 will include this information.
7488 \*(BO This setting reverses the meanings of a set of reply commands,
7489 turning the lowercase variants, which by default address all recipients
7490 included in the header of a message
7491 .Pf ( Ic reply , respond , followup )
7492 into the uppercase variants, which by default address the sender only
7493 .Pf ( Ic Reply , Respond , Followup )
7496 .Ic replysender , respondsender , followupsender
7498 .Ic replyall , respondall , followupall
7499 are not affected by the current setting of
7504 .It Va file-hook-load-EXTENSION , file-hook-save-EXTENSION
7505 It is possible to install file hooks which will be used by the
7507 command in order to be able to transparently handle (through an
7508 intermediate temporary file) files with specific
7510 s: the variable values can include shell snippets and are expected to
7511 write data to standard output / read data from standard input,
7513 \*(ID The variables may not be changed while there is a mailbox
7515 .Bd -literal -offset indent
7516 set file-hook-load-xy='echo >&2 XY-LOAD; gzip -cd' \e
7517 file-hook-save-xy='echo >&2 XY-SAVE; gzip -c' \e
7518 record=+null-sent.xy
7523 The default path under which mailboxes are to be saved:
7524 file names that begin with the plus sign
7526 will have the plus sign replaced with the value of this variable if set,
7527 otherwise the plus sign will remain unchanged when doing
7528 .Sx "Filename transformations" ;
7531 for more on this topic.
7532 The value supports a subset of transformations itself, and if the
7533 non-empty value does not start with a solidus
7537 will be prefixed automatically.
7541 This variable can be set to the name of a
7543 macro which will be called whenever a
7546 The macro will also be invoked when new mail arrives,
7547 but message lists for commands executed from the macro
7548 only include newly arrived messages then.
7550 are activated by default in a folder hook, causing the covered settings
7551 to be reverted once the folder is left again.
7554 Macro behaviour, including option localization, will change in v15.
7555 One should be aware of that and possibly embed version checks in the
7556 used resource file(s).
7559 .It Va folder-hook-FOLDER
7564 Unlike other folder specifications, the fully expanded name of a folder,
7565 without metacharacters, is used to avoid ambiguities.
7566 However, if the mailbox resides under
7570 specification is tried in addition, e.g., if
7574 (and thus relative to the user's home directory) then
7575 .Pa /home/usr1/mail/sent
7577 .Ql folder-hook-/home/usr1/mail/sent
7578 first, but then followed by
7579 .Ql folder-hook-+sent .
7583 \*(BO Controls whether a
7584 .Ql Mail-Followup-To:
7585 header is generated when sending messages to known mailing lists.
7587 .Va followup-to-honour
7589 .Ic mlist , mlsubscribe , reply
7594 .It Va followup-to-honour
7596 .Ql Mail-Followup-To:
7597 header is honoured when group-replying to a message via
7601 This is a quadoption; if set without a value it defaults to
7611 .It Va forward-as-attachment
7612 \*(BO Original messages are normally sent as inline text with the
7615 and only the first part of a multipart message is included.
7616 With this setting enabled messages are sent as unmodified MIME
7618 attachments with all of their parts included.
7622 The address (or a list of addresses) to put into the
7624 field of the message header, quoting RFC 5322:
7625 the author(s) of the message, that is, the mailbox(es) of the person(s)
7626 or system(s) responsible for the writing of the message.
7629 ing to messages these addresses are handled as if they were in the
7633 If the machine's hostname is not valid at the Internet (for example at
7634 a dialup machine) then either this variable or
7636 (\*(IN and with a defined SMTP protocol in
7639 adds even more fine-tuning capabilities),
7643 contains more than one address,
7646 variable is required (according to the standard RFC 5322).
7648 If a file-based MTA is used, then
7650 (or, if that contains multiple addresses,
7652 can nonetheless be enforced to appear as the envelope sender address at
7653 the MTA protocol level (the RFC 5321 reverse-path), either by using the
7655 command line option (with an empty argument; see there for the complete
7656 picture on this topic), or by setting the internal variable
7657 .Va r-option-implicit .
7661 \*(BO When replying to or forwarding a message \*(UA normally removes
7662 the comment and name parts of email addresses.
7663 If this variable is set such stripping is not performed,
7664 and comments, names etc. are retained.
7668 The string to put before the text of a message with the
7672 .Va forward-as-attachment
7675 .Dq -------- Original Message --------
7676 if unset; No heading is put if it is set to the empty string.
7680 \*(BO Causes the header summary to be written at startup and after
7681 commands that affect the number of messages or the order of messages in
7682 the current folder; enabled by default.
7683 The command line option
7689 complements this and controls header summary display on folder changes.
7694 A format string to use for the summary of
7696 similar to the ones used for
7699 Format specifiers in the given string start with a percent sign
7701 and may be followed by an optional decimal number indicating the field
7702 width \(em if that is negative, the field is to be left-aligned.
7703 Valid format specifiers are:
7706 .Bl -tag -compact -width "_%%_"
7708 A plain percent sign.
7711 a space character but for the current message
7713 for which it expands to
7717 a space character but for the current message
7719 for which it expands to
7722 \*(OP The spam score of the message, as has been classified via the
7725 Shows only a replacement character if there is no spam support.
7727 Message attribute character (status flag); the actual content can be
7731 The date found in the
7733 header of the message when
7735 is set (the default), otherwise the date when the message was received.
7736 Formatting can be controlled by assigning a
7741 The indenting level in threaded mode.
7743 The address of the message sender.
7745 The message thread tree structure.
7746 (Note that this format does not support a field width.)
7748 The number of lines of the message, if available.
7752 The number of octets (bytes) in the message, if available.
7754 Message subject (if any).
7756 Message subject (if any) in double quotes.
7758 Message recipient flags: is the addressee of the message a known or
7759 subscribed mailing list \(en see
7764 The position in threaded/sorted order.
7768 .Ql %>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s ,
7770 .Ql %>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S
7781 .It Va headline-bidi
7782 Bidirectional text requires special treatment when displaying headers,
7783 because numbers (in dates or for file sizes etc.) will not affect the
7784 current text direction, in effect resulting in ugly line layouts when
7785 arabic or other right-to-left text is to be displayed.
7786 On the other hand only a minority of terminals is capable to correctly
7787 handle direction changes, so that user interaction is necessary for
7789 Note that extended host system support is required nonetheless, e.g.,
7790 detection of the terminal character set is one precondition;
7791 and this feature only works in an Unicode (i.e., UTF-8) locale.
7793 In general setting this variable will cause \*(UA to encapsulate text
7794 fields that may occur when displaying
7796 (and some other fields, like dynamic expansions in
7798 with special Unicode control sequences;
7799 it is possible to fine-tune the terminal support level by assigning
7801 no value (or any value other than
7806 will make \*(UA assume that the terminal is capable to properly deal
7807 with Unicode version 6.3, in which case text is embedded in a pair of
7808 U+2068 (FIRST STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE)
7810 In addition no space on the line is reserved for these characters.
7812 Weaker support is chosen by using the value
7814 (Unicode 6.3, but reserve the room of two spaces for writing the control
7815 sequences onto the line).
7820 select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT MARK); the latter
7821 again reserves room for two spaces in addition.
7825 \*(OP If a line editor is available then this can be set to
7826 name the (expandable) path of the location of a permanent history file.
7831 .It Va history-gabby
7832 \*(BO\*(OP Add more entries to the history as is normally done.
7835 .It Va history-gabby-persist
7836 \*(BO\*(OP \*(UA's own MLE will not save the additional
7838 entries in persistent storage unless this variable is set.
7839 On the other hand it will not loose the knowledge of whether
7840 a persistent entry was gabby or not.
7846 \*(OP Setting this variable imposes a limit on the number of concurrent
7848 If set to the value 0 then no further history entries will be added, and
7849 loading and incorporation of the
7851 upon program startup can also be suppressed by doing this.
7852 Runtime changes will not be reflected, but will affect the number of
7853 entries saved to permanent storage.
7857 \*(BO This setting controls whether messages are held in the system
7859 and it is set by default.
7863 Use this string as hostname when expanding local addresses instead of
7864 the value obtained from
7868 It is used, e.g., in
7872 fields, as well as when generating
7874 MIME part related unique ID fields.
7875 Setting it to the empty string will cause the normal hostname to be
7876 used, but nonetheless enables creation of said ID fields.
7877 \*(IN in conjunction with the builtin SMTP
7880 also influences the results:
7881 one should produce some test messages with the desired combination of
7890 \*(BO\*(OP Can be used to turn off the automatic conversion of domain
7891 names according to the rules of IDNA (internationalized domain names
7893 Since the IDNA code assumes that domain names are specified with the
7895 character set, an UTF-8 locale charset is required to represent all
7896 possible international domain names (before conversion, that is).
7900 \*(BO Ignore interrupt signals from the terminal while entering
7901 messages; instead echo them as
7903 characters and discard the current line.
7907 \*(BO Ignore end-of-file conditions
7908 .Pf ( Ql control-D )
7909 in compose mode on message input and in interactive command input.
7910 If set an interactive command input session can only be left by
7911 explicitly using one of the commands
7915 and message input in compose mode can only be terminated by entering
7918 on a line by itself or by using the
7920 .Sx "COMMAND ESCAPES" ;
7922 overrides a setting of
7927 If this is set to a non-empty string it will specify the users
7929 .Sx "primary system mailbox" ,
7932 and the system-dependent default, and (thus) be used to replace
7935 .Sx "Filename transformations" ;
7938 for more on this topic.
7939 The value supports a subset of transformations itself.
7947 .Sx "COMMAND ESCAPES"
7950 option for indenting messages,
7951 in place of the normal tabulator character
7953 which is the default.
7954 Be sure to quote the value if it contains spaces or tabs.
7958 \*(BO If set, an empty system (MBOX) mailbox file is not removed.
7959 Note that, in conjunction with
7962 .Ev POSIXLY_CORRECT )
7963 any empty file will be removed unless this variable is set.
7964 This may improve the interoperability with other mail user agents
7965 when using a common folder directory, and prevents malicious users
7966 from creating fake mailboxes in a world-writable spool directory.
7967 \*(ID Only local regular (MBOX) files are covered, Maildir or other
7968 mailbox types will never be removed, even if empty.
7971 .It Va keep-content-length
7972 \*(BO When (editing messages and) writing
7974 mailbox files \*(UA can be told to keep the
7978 header fields that some MUAs generate by setting this variable.
7979 Since \*(UA does neither use nor update these non-standardized header
7980 fields (which in itself shows one of their conceptual problems),
7981 stripping them should increase interoperability in between MUAs that
7982 work with with same mailbox files.
7983 Note that, if this is not set but
7984 .Va writebackedited ,
7985 as below, is, a possibly performed automatic stripping of these header
7986 fields already marks the message as being modified.
7990 \*(BO When a message is saved it is usually discarded from the
7991 originating folder when \*(UA is quit.
7992 This setting causes all saved message to be retained.
7995 .It Va line-editor-disable
7996 \*(BO Turn off any enhanced line editing capabilities (see
7997 .Sx "On terminal control and line editor"
8001 .It Va line-editor-no-defaults
8002 \*(BO\*(OP Do not establish any default key binding.
8005 .It Va mailx-extra-rc
8006 An additional startup file that is loaded as the last of the
8007 .Sx "Resource files" .
8008 Use this file for commands that are not understood by other POSIX
8014 \*(BO When a message is replied to and this variable is set,
8015 it is marked as having been
8018 .Sx "Message states" .
8022 \*(BO If this is set then when opening MBOX mailbox files \*(UA will not
8023 use the tolerant POSIX rules for detecting message boundaries (so-called
8025 lines), as it does by default for compatibility reasons, but the more
8026 strict rules that have been defined in RFC 4155.
8027 When saving to MBOX mailboxes this indicates when so-called
8029 quoting is to be applied \(em note this is never necessary for any
8030 message newly generated by \*(UA, it only applies to messages generated
8031 by buggy or malicious MUAs.
8032 (\*(UA will use a proper
8036 lines cannot be misinterpreted as message boundaries.)
8038 This should not be set normally, but may be handy when \*(UA complains
8039 about having seen invalid
8041 lines when opening a MBOX: in this case temporarily setting this
8042 variable, re-opening the mailbox in question, unsetting this variable
8043 again and then invoking
8044 .Ql copy * SOME-FILE
8045 will perform proper, POSIX-compliant
8047 quoting for all detected messages, resulting in a valid MBOX mailbox.
8051 \*(BO Internal development variable.
8054 .It Va message-id-disable
8055 \*(BO By setting this variable the generation of
8057 can be completely suppressed, effectively leaving this task up to the
8059 (Mail-Transfer-Agent) or the SMTP server.
8060 (According to RFC 5321 a SMTP server is not required to add this
8061 field by itself, so it should be ensured that it accepts messages without
8063 This variable also affects automatic generation of
8068 .It Va message-inject-head
8069 A string to put at the beginning of each new message.
8070 The escape sequences tabulator
8077 .It Va message-inject-tail
8078 A string to put at the end of each new message.
8079 The escape sequences tabulator
8087 \*(BO Usually, when an
8089 expansion contains the sender, the sender is removed from the expansion.
8090 Setting this option suppresses these removals.
8095 option to be passed through to the
8097 (Mail-Transfer-Agent); though most of the modern MTAs no longer document
8098 this flag, no MTA is known which does not support it (for historical
8102 .It Va mime-allow-text-controls
8103 \*(BO When sending messages, each part of the message is MIME-inspected
8104 in order to classify the
8107 .Ql Content-Transfer-Encoding:
8110 that is required to send this part over mail transport, i.e.,
8111 a computation rather similar to what the
8113 command produces when used with the
8117 This classification however treats text files which are encoded in
8118 UTF-16 (seen for HTML files) and similar character sets as binary
8119 octet-streams, forcefully changing any
8124 .Ql application/octet-stream :
8125 If that actually happens a yet unset charset MIME parameter is set to
8127 effectively making it impossible for the receiving MUA to automatically
8128 interpret the contents of the part.
8130 If this variable is set, and the data was unambiguously identified as
8131 text data at first glance (by a
8135 file extension), then the original
8137 will not be overwritten.
8140 .It Va mime-alternative-favour-rich
8141 \*(BO If this variable is set then rich MIME alternative parts (e.g.,
8142 HTML) will be preferred in favour of included plain text versions when
8143 displaying messages, provided that a handler exists which produces
8144 output that can be (re)integrated into \*(UA's normal visual display.
8145 (E.g., at the time of this writing some newsletters ship their full
8146 content only in the rich HTML part, whereas the plain text part only
8147 contains topic subjects.)
8150 .It Va mime-counter-evidence
8153 field is used to decide how to handle MIME parts.
8154 Some MUAs however do not use
8156 or a similar mechanism to correctly classify content, but simply specify
8157 .Ql application/octet-stream ,
8158 even for plain text attachments like
8160 If this variable is set then \*(UA will try to classify such MIME
8161 message parts on its own, if possible, for example via a possibly
8162 existing attachment filename.
8163 A non-empty value may also be given, in which case a number is expected,
8164 actually a carrier of bits.
8165 Creating the bit-carrying number is a simple addition:
8166 .Bd -literal -offset indent
8167 ? !echo Value should be set to $((2 + 4 + 8))
8168 Value should be set to 14
8171 .Bl -bullet -compact
8173 If bit two is set (2) then the detected
8175 content-type will be carried along with the message and be used for
8177 .Va pipe-TYPE/SUBTYPE
8178 is responsible for the MIME part, shall that question arise;
8179 when displaying such a MIME part the part-info will indicate the
8180 overridden content-type by showing a plus sign
8183 If bit three is set (4) then the counter-evidence is always produced
8184 and a positive result will be used as the MIME type, even forcefully
8185 overriding the parts given MIME type.
8187 If bit four is set (8) then as a last resort the actual content of
8188 .Ql application/octet-stream
8189 parts will be inspected, so that data which looks like plain text can be
8194 .It Va mimetypes-load-control
8195 Can be used to control which of the
8197 databases are loaded by \*(UA, as furtherly described in the section
8198 .Sx "The mime.types files" .
8201 is part of the option value, then the user's personal
8203 file will be loaded (if it exists); likewise the letter
8205 controls loading of the system wide
8206 .Pa /etc/mime.types ;
8207 directives found in the user file take precedence, letter matching is
8209 If this variable is not set \*(UA will try to load both files.
8210 Incorporation of the \*(UA-builtin MIME types cannot be suppressed,
8211 but they will be matched last (the order can be listed via
8214 More sources can be specified by using a different syntax: if the
8215 value string contains an equals sign
8217 then it is instead parsed as a comma-separated list of the described
8220 pairs; the given filenames will be expanded and loaded, and their
8221 content may use the extended syntax that is described in the section
8222 .Sx "The mime.types files" .
8223 Directives found in such files always take precedence (are prepended to
8224 the MIME type cache).
8229 To choose an alternate Mail-Transfer-Agent, set this option to either
8230 the full pathname of an executable (optionally prefixed with a
8232 protocol indicator), or \*(OPally a SMTP protocol URL, e.g., \*(IN
8234 .Dl smtps?://[user[:password]@]server[:port]
8237 .Ql [smtp://]server[:port] . )
8238 The default has been chosen at compie time.
8239 All supported data transfers are executed in child processes, which
8240 run asynchronously, and without supervision, unless either the
8245 If such a child receives a TERM signal, it will abort and
8252 For a file-based MTA it may be necessary to set
8254 in in order to choose the right target of a modern
8257 It will be passed command line arguments from several possible sources:
8260 if set, from the command line if given and the variable
8263 Argument processing of the MTA will be terminated with a
8268 The otherwise occurring implicit usage of the following MTA command
8269 line arguments can be disabled by setting the boolean variable
8270 .Va mta-no-default-arguments
8271 (which will also disable passing
8275 (for not treating a line with only a dot
8277 character as the end of input),
8285 variable is set); in conjunction with the
8287 command line option \*(UA will also (not) pass
8293 \*(OP \*(UA can send mail over SMTP network connections to a single
8294 defined SMTP smarthost, the access URL of which has to be assigned to
8296 To use this mode it is helpful to read
8297 .Sx "On URL syntax and credential lookup" .
8298 It may be necessary to set the
8300 variable in order to use a specific combination of
8305 with some mail providers.
8308 .Bl -bullet -compact
8310 The plain SMTP protocol (RFC 5321) that normally lives on the
8311 server port 25 and requires setting the
8312 .Va smtp-use-starttls
8313 variable to enter a SSL/TLS encrypted session state.
8314 Assign a value like \*(IN
8315 .Ql smtp://[user[:password]@]server[:port]
8317 .Ql smtp://server[:port] )
8318 to choose this protocol.
8320 The so-called SMTPS which is supposed to live on server port 465
8321 and is automatically SSL/TLS secured.
8322 Unfortunately it never became a standardized protocol and may thus not
8323 be supported by your hosts network service database
8324 \(en in fact the port number has already been reassigned to other
8327 SMTPS is nonetheless a commonly offered protocol and thus can be
8328 chosen by assigning a value like \*(IN
8329 .Ql smtps://[user[:password]@]server[:port]
8331 .Ql smtps://server[:port] ) ;
8332 due to the mentioned problems it is usually necessary to explicitly
8337 Finally there is the SUBMISSION protocol (RFC 6409), which usually
8338 lives on server port 587 and is practically identically to the SMTP
8339 protocol from \*(UA's point of view beside that; it requires setting the
8340 .Va smtp-use-starttls
8341 variable to enter a SSL/TLS secured session state.
8342 Assign a value like \*(IN
8343 .Ql submission://[user[:password]@]server[:port]
8345 .Ql submission://server[:port] ) .
8350 .It Va mta-arguments
8351 Arguments to pass through to a file-based
8353 can be given via this variable, which is parsed according to
8354 .Sx "Shell-style argument quoting"
8355 into an array of arguments, and which will be joined onto MTA options
8356 from other sources, and then passed individually to the MTA:
8358 .Dl wysh set mta-arguments='-t -X \&"/tmp/my log\&"'
8361 .It Va mta-no-default-arguments
8362 \*(BO Unless this variable is set \*(UA will pass some well known
8363 standard command line options to a file-based
8365 (Mail-Transfer-Agent), see there for more.
8369 Many systems use a so-called
8371 environment to ensure compatibility with
8373 This works by inspecting the name that was used to invoke the mail
8375 If this variable is set then the mailwrapper (the program that is
8376 actually executed when calling the file-based
8378 will treat its contents as that name.
8383 .It Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
8384 \*(BO\*(IN\*(OP Used to control usage of the users
8386 file for lookup of account credentials, as documented in the section
8387 .Sx "On URL syntax and credential lookup"
8391 .Sx "The .netrc file"
8392 documents the file format.
8404 then \*(UA will read the output of a shell pipe instead of the users
8406 file if this variable is set (to the desired shell command).
8407 This can be used to, e.g., store
8411 .Dl set netrc-pipe='gpg -qd ~/.netrc.pgp'
8415 If this variable has the value
8417 newly created local folders will be in Maildir format.
8421 Checks for new mail in the current folder each time the prompt is shown.
8422 A Maildir folder must be re-scanned to determine if new mail has arrived.
8423 If this variable is set to the special value
8425 then a Maildir folder will not be rescanned completely, but only
8426 timestamp changes are detected.
8430 .It Va on-compose-done-shell , on-compose-done
8431 These hooks run once the normal compose mode is finished, but before the
8432 .Va on-compose-leave
8433 macro hook is called, the
8436 Both hooks will be executed in a subprocess, with their input and output
8437 connected to \*(UA such that they can act as if they would be an
8439 The difference in between them is that the former is a
8441 command, whereas the latter is a normal \*(UA macro, but which is
8442 restricted to a small set of commands (the
8446 will indicate said capability), just enough for the purpose of
8447 controlling the real \*(UA instance sufficiently.
8449 are enabled for these hooks (in the parent process), causing any setting
8450 to be forgotten after the message has been sent.
8452 During execution of these hook \*(UA will temporarily forget whether it
8453 has been started in interactive mode, (a restricted set of)
8454 .Sx "COMMAND ESCAPES"
8455 will always be available, and for guaranteed reproduceabilities sake
8457 will be set to its default.
8458 The compose mode command
8460 has been especially designed for scriptability (via these hooks).
8461 The first line the hook will read on its standard input is the protocol
8462 version of said command escape, currently
8464 backward incompatible protocol changes are to be expected in the
8465 future, and it is advisable to make use of the protocol version.
8466 \*(ID because most \*(UA commands do not take this new functionality
8467 into account but are ment for human interaction special care must be
8468 taken to avoid deadlocks because of unexpected control flow; i.e., that
8469 both involved processes wait for more input to happen at the same time,
8470 or one doesn't expect more input but the other is stuck waiting for
8471 consumation of its output.
8472 .Bd -literal -offset indent
8473 wysh set on-compose-done-shell=$'\e
8475 printf "hello $version! Headers: ";\e
8476 echo \e'~^header list\e';\e
8477 read status result;\e
8478 echo "status=$status result=$result";\e
8481 set on-compose-done=ocdm
8484 echo version is $ver, escape=$escape
8485 if [ "$features" !@ +regex ]
8486 echoerr 'Need regular-expression support, aborting send'
8489 echo '~^header list'
8492 echoerr 'Failed to read header list, bailing out'
8495 if [ "$hl" !@ ' cc' ]
8496 echo '~^header insert cc Diet is your <mirr.or>'
8499 echoerr 'Failed to insert Cc: header, bailing out'
8503 echo '~:set from="Hoola Hoop <hh@exam.ple>"'
8509 .It Va on-compose-enter , on-compose-leave
8510 Macro hooks which will be executed before compose mode is entered, and
8511 after composing has been finished (but before the
8513 is injected, etc.), respectively.
8515 are enabled for these hooks, causing any setting to be forgotten after
8516 the message has been sent.
8517 The following (read-only) variables will be set temporarily during
8518 execution of the macros:
8520 .Bl -tag -compact -width ".It Va compose_subject"
8523 .It Va compose-sender
8525 .It Va compose-to , compose-cc , compose-bcc
8526 The list of receiver addresses as a space-separated list.
8527 .It Va compose-subject
8533 \*(BO Causes the filename given in the
8536 and the sender-based filenames for the
8540 commands to be interpreted relative to the directory given in the
8542 variable rather than to the current directory,
8543 unless it is set to an absolute pathname.
8547 \*(BO If set, each message feed through the command given for
8549 is followed by a formfeed character
8553 .It Va password-USER@HOST , password-HOST , password
8554 \*(IN Variable chain that sets a password, which is used in case none has
8555 been given in the protocol and account-specific URL;
8556 as a last resort \*(UA will ask for a password on the user's terminal if
8557 the authentication method requires a password.
8558 Specifying passwords in a startup file is generally a security risk;
8559 the file should be readable by the invoking user only.
8561 .It Va password-USER@HOST
8562 \*(OU (see the chain above for \*(IN)
8563 Set the password for
8567 If no such variable is defined for a host,
8568 the user will be asked for a password on standard input.
8569 Specifying passwords in a startup file is generally a security risk;
8570 the file should be readable by the invoking user only.
8574 \*(BO Send messages to the
8576 command without performing MIME and character set conversions.
8580 .It Va pipe-TYPE/SUBTYPE
8581 When a MIME message part of type
8583 (case-insensitive) is displayed or quoted,
8584 its text is filtered through the value of this variable interpreted as
8588 forces interpretation of the message part as plain text, e.g.,
8589 .Ql set pipe-application/xml=@
8590 will henceforth display XML
8592 (The same could also be achieved by adding a MIME type marker with the
8595 And \*(OPally MIME type handlers may be defined via
8596 .Sx "The Mailcap files"
8597 \(em corresponding flag strings are shown in parenthesis below.)
8602 can in fact be used to adjust usage and behaviour of a following shell
8603 command specification by appending trigger characters to it, e.g., the
8604 following hypothetical command specification could be used:
8605 .Bd -literal -offset indent
8606 set pipe-X/Y='@*!++=@vim ${MAILX_FILENAME_TEMPORARY}'
8610 .Bl -tag -compact -width ".It Ql __"
8612 Simply by using the special
8614 prefix the MIME type (shell command) handler will only be invoked to
8615 display or convert the MIME part if the message is addressed directly
8616 and alone by itself.
8617 Use this trigger to disable this and always invoke the handler
8618 .Pf ( Cd x-mailx-always ) .
8621 If set the handler will not be invoked when a message is to be quoted,
8622 but only when it will be displayed
8623 .Pf ( Cd x-mailx-noquote ) .
8626 The command will be run asynchronously, i.e., without blocking \*(UA,
8627 which may be a handy way to display a, e.g., PDF file while also
8628 continuing to read the mail message
8629 .Pf ( Cd x-mailx-async ) .
8630 Asynchronous execution implies
8634 The command must be run on an interactive terminal, \*(UA will
8635 temporarily release the terminal to it
8636 .Pf ( Cd needsterminal ) .
8637 This flag is mutual exclusive with
8639 will only be used in interactive mode and implies
8643 Request creation of a zero-sized temporary file, the absolute pathname
8644 of which will be made accessible via the environment variable
8645 .Ev MAILX_FILENAME_TEMPORARY
8646 .Pf ( Cd x-mailx-tmpfile ) .
8647 If this trigger is given twice then the file will be unlinked
8648 automatically by \*(UA when the command loop is entered again at latest
8649 .Pf ( Cd x-mailx-tmpfile-unlink ) .
8650 (Do not use this for asynchronous handlers.)
8653 Normally the MIME part content is passed to the handler via standard
8654 input; if this flag is set then the data will instead be written into
8655 .Ev MAILX_FILENAME_TEMPORARY
8656 .Pf ( Cd x-mailx-tmpfile-fill ) ,
8657 the creation of which is implied; note however that in order to cause
8658 deletion of the temporary file you still have to use two plus signs
8663 To avoid ambiguities with normal shell command content you can use
8664 another commercial at to forcefully terminate interpretation of
8665 remaining characters.
8666 (Any character not in this list will have the same effect.)
8670 Some information about the MIME part to be displayed is embedded into
8671 the environment of the shell command:
8674 .Bl -tag -compact -width ".It Ev _AIL__ILENAME__ENERATED"
8676 .It Ev MAILX_CONTENT
8677 The MIME content-type of the part, if known, the empty string otherwise.
8680 .It Ev MAILX_CONTENT_EVIDENCE
8682 .Va mime-counter-evidence
8683 includes the carry-around-bit (2), then this will be set to the detected
8684 MIME content-type; not only then identical to
8685 .Ev \&\&MAILX_CONTENT
8689 .It Ev MAILX_FILENAME
8690 The filename, if any is set, the empty string otherwise.
8693 .It Ev MAILX_FILENAME_GENERATED
8697 .It Ev MAILX_FILENAME_TEMPORARY
8698 If temporary file creation has been requested through the command prefix
8699 this variable will be set and contain the absolute pathname of the
8705 .It Va pipe-EXTENSION
8706 This is identical to
8707 .Va pipe-TYPE/SUBTYPE
8710 (normalized to lowercase using character mappings of the ASCII charset)
8711 names a file extension, e.g.,
8713 Handlers registered using this method take precedence.
8716 .It Va pop3-auth-USER@HOST , pop3-auth-HOST , pop3-auth
8717 \*(OP\*(IN Variable chain that sets the POP3 authentication method.
8718 The only possible value as of now is
8720 which is thus the default.
8723 .Mx Va pop3-bulk-load
8724 .It Va pop3-bulk-load-USER@HOST , pop3-bulk-load-HOST , pop3-bulk-load
8725 \*(BO\*(OP When accessing a POP3 server \*(UA loads the headers of
8726 the messages, and only requests the message bodies on user request.
8727 For the POP3 protocol this means that the message headers will be
8729 If this variable is set then \*(UA will download only complete messages
8730 from the given POP3 server(s) instead.
8732 .Mx Va pop3-keepalive
8733 .It Va pop3-keepalive-USER@HOST , pop3-keepalive-HOST , pop3-keepalive
8734 \*(OP POP3 servers close the connection after a period of inactivity;
8735 the standard requires this to be at least 10 minutes,
8736 but practical experience may vary.
8737 Setting this variable to a numeric value greater than
8741 command to be sent each value seconds if no other operation is performed.
8744 .It Va pop3-no-apop-USER@HOST , pop3-no-apop-HOST , pop3-no-apop
8745 \*(BO\*(OP Unless this variable is set the
8747 authentication method will be used when connecting to a POP3 server that
8751 is that the password is not sent in clear text over the wire and that
8752 only a single packet is sent for the user/password tuple.
8754 .Va pop3-no-apop-HOST
8757 .Mx Va pop3-use-starttls
8758 .It Va pop3-use-starttls-USER@HOST , pop3-use-starttls-HOST , pop3-use-starttls
8759 \*(BO\*(OP Causes \*(UA to issue a
8761 command to make an unencrypted POP3 session SSL/TLS encrypted.
8762 This functionality is not supported by all servers,
8763 and is not used if the session is already encrypted by the POP3S method.
8765 .Va pop3-use-starttls-HOST
8770 \*(BO This flag enables POSIX mode, which changes behaviour of \*(UA
8771 where that deviates from standardized behaviour.
8772 It will be set implicitly before the
8773 .Sx "Resource files"
8774 are loaded if the environment variable
8776 is set, and adjusting any of those two will be reflected by the other
8780 .It Va print-alternatives
8781 \*(BO When a MIME message part of type
8782 .Ql multipart/alternative
8783 is displayed and it contains a subpart of type
8785 other parts are normally discarded.
8786 Setting this variable causes all subparts to be displayed,
8787 just as if the surrounding part was of type
8788 .Ql multipart/mixed .
8792 The string used as a prompt in interactive mode.
8793 Whenever the variable is evaluated the value is expanded as via
8794 dollar-single-quote expansion (see
8795 .Sx "Shell-style argument quoting" ) .
8796 This (post-assignment, i.e., second) expansion can be used to embed
8797 status information, for example
8802 .Va -mailbox-display .
8804 In order to embed characters which should not be counted when
8805 calculating the visual width of the resulting string, enclose the
8806 characters of interest in a pair of reverse solidus escaped brackets:
8808 a slot for coloured prompts is also available with the \*(OPal command
8810 Prompting may be prevented by setting this to the null string
8812 .Ql set noprompt ) .
8816 This string is used for secondary prompts, but is otherwise identical to
8823 \*(BO Suppresses the printing of the version when first invoked.
8827 If set, \*(UA starts a replying message with the original message
8828 prefixed by the value of the variable
8830 Normally, a heading consisting of
8831 .Dq Fromheaderfield wrote:
8832 is put before the quotation.
8837 variable, this heading is omitted.
8840 is assigned, only the headers selected by the
8843 selection are put above the message body,
8846 acts like an automatic
8848 .Sx "COMMAND ESCAPES"
8852 is assigned, all headers are put above the message body and all MIME
8853 parts are included, making
8855 act like an automatic
8858 .Va quote-as-attachment .
8861 .It Va quote-as-attachment
8862 \*(BO Add the original message in its entirety as a
8864 MIME attachment when replying to a message.
8865 Note this works regardless of the setting of
8870 \*(OP Can be set in addition to
8872 Setting this turns on a more fancy quotation algorithm in that leading
8873 quotation characters are compressed and overlong lines are folded.
8875 can be set to either one or two (space separated) numeric values,
8876 which are interpreted as the maximum (goal) and the minimum line length,
8877 respectively, in a spirit rather equal to the
8879 program, but line-, not paragraph-based.
8880 If not set explicitly the minimum will reflect the goal algorithmically.
8881 The goal cannot be smaller than the length of
8883 plus some additional pad.
8884 Necessary adjustments take place silently.
8887 .It Va r-option-implicit
8888 \*(BO Setting this option evaluates the contents of
8890 (or, if that contains multiple addresses,
8892 and passes the results onto the used (file-based) MTA as described for the
8894 option (empty argument case).
8897 .It Va recipients-in-cc
8898 \*(BO On group replies, specify only the sender of the original mail in
8900 and mention the other recipients in the secondary
8902 By default all recipients of the original mail will be addressed via
8907 If defined, gives the pathname of the folder used to record all outgoing
8909 If not defined, then outgoing mail is not saved.
8910 When saving to this folder fails the message is not sent,
8911 but instead saved to
8915 .It Va record-resent
8916 \*(BO If both this variable and the
8923 commands save messages to the
8925 folder as it is normally only done for newly composed messages.
8928 .It Va reply-in-same-charset
8929 \*(BO If this variable is set \*(UA first tries to use the same
8930 character set of the original message for replies.
8931 If this fails, the mechanism described in
8932 .Sx "Character sets"
8933 is evaluated as usual.
8936 .It Va reply-strings
8937 Can be set to a comma-separated list of (case-insensitive according to
8938 ASCII rules) strings which shall be recognized in addition to the
8941 reply message indicators \(en builtin are
8943 which is mandated by RFC 5322, as well as the german
8948 which often has been seen in the wild;
8949 I.e., the separating colon has to be specified explicitly.
8953 A list of addresses to put into the
8955 field of the message header.
8956 Members of this list are handled as if they were in the
8961 .It Va reply-to-honour
8964 header is honoured when replying to a message via
8968 This is a quadoption; if set without a value it defaults to
8972 .It Va rfc822-body-from_
8973 \*(BO This variable can be used to force displaying a so-called
8975 line for messages that are embedded into an envelope mail via the
8977 MIME mechanism, for more visual convenience.
8981 \*(BO Enable saving of (partial) messages in
8983 upon interrupt or delivery error.
8987 The number of lines that represents a
8996 line display and scrolling via
8998 If this variable is not set \*(UA falls back to a calculation based upon
8999 the detected terminal window size and the baud rate: the faster the
9000 terminal, the more will be shown.
9001 Overall screen dimensions and pager usage is influenced by the
9002 environment variables
9010 .It Va searchheaders
9011 \*(BO Expand message-list specifiers in the form
9013 to all messages containing the substring
9017 The string search is case insensitive.
9021 \*(OP A comma-separated list of character set names that can be used in
9022 outgoing internet mail.
9023 The value of the variable
9025 is automatically appended to this list of character-sets.
9026 If no character set conversion capabilities are compiled into \*(UA then
9027 the only supported charset is
9030 .Va sendcharsets-else-ttycharset
9031 and refer to the section
9032 .Sx "Character sets"
9033 for the complete picture of character set conversion in \*(UA.
9036 .It Va sendcharsets-else-ttycharset
9037 \*(BO\*(OP If this variable is set, but
9039 is not, then \*(UA acts as if
9041 had been set to the value of the variable
9043 In effect this combination passes through the message data in the
9044 character set of the current locale (given that
9046 has not been set manually), i.e., without converting it to the
9048 fallback character set.
9049 Thus, mail message text will be in ISO-8859-1 encoding when send from
9050 within a ISO-8859-1 locale, and in UTF-8 encoding when send from within
9052 If no character set conversion capabilities are available in \*(UA then
9053 the only supported character set is
9058 An address that is put into the
9060 field of outgoing messages, quoting RFC 5322: the mailbox of the agent
9061 responsible for the actual transmission of the message.
9062 This field should normally not be used unless the
9064 field contains more than one address, on which case it is required.
9067 address is handled as if it were in the
9071 .Va r-option-implicit .
9075 \*(OB Predecessor of
9079 .It Va sendmail-arguments
9080 \*(OB Predecessor of
9084 .It Va sendmail-no-default-arguments
9085 \*(OB\*(BO Predecessor of
9086 .Va mta-no-default-arguments .
9089 .It Va sendmail-progname
9090 \*(OB Predecessor of
9095 \*(BO When sending a message wait until the
9097 (including the builtin SMTP one) exits before accepting further commands.
9099 with this variable set errors reported by the MTA will be recognizable!
9100 If the MTA returns a non-zero exit status,
9101 the exit status of \*(UA will also be non-zero.
9105 \*(BO This setting causes \*(UA to start at the last message
9106 instead of the first one when opening a mail folder.
9110 \*(BO Causes \*(UA to use the sender's real name instead of the plain
9111 address in the header field summary and in message specifications.
9115 \*(BO Causes the recipient of the message to be shown in the header
9116 summary if the message was sent by the user.
9120 The string to expand
9123 .Sx "COMMAND ESCAPES" ) .
9127 The string to expand
9130 .Sx "COMMAND ESCAPES" ) .
9134 Must correspond to the name of a readable file if set.
9135 The file's content is then appended to each singlepart message
9136 and to the first part of each multipart message.
9137 Be warned that there is no possibility to edit the signature for an
9141 .It Va skipemptybody
9142 \*(BO If an outgoing message does not contain any text in its first or
9143 only message part, do not send it but discard it silently (see also the
9149 .It Va smime-ca-dir , smime-ca-file
9150 \*(OP Specify the location of trusted CA certificates in PEM (Privacy
9151 Enhanced Mail) format as a directory and a file, respectively, for the
9152 purpose of verification of S/MIME signed messages.
9153 It is possible to set both, the file will be loaded immediately, the
9154 directory will be searched whenever no match has yet been found.
9155 The set of CA certificates which are built into the SSL/TLS library can
9156 be explicitly turned off by setting
9157 .Va smime-ca-no-defaults ,
9158 and further fine-tuning is possible via
9159 .Va smime-ca-flags .
9162 .It Va smime-ca-flags
9163 \*(OP Can be used to fine-tune behaviour of the X509 CA certificate
9164 storage, and the certificate verification that is used.
9165 The actual values and their meanings are documented for
9169 .It Va smime-ca-no-defaults
9170 \*(BO\*(OP Do not load the default CA locations that are built into the
9171 used to SSL/TLS library to verify S/MIME signed messages.
9174 .It Va smime-cipher-USER@HOST , smime-cipher
9175 \*(OP Specifies the cipher to use when generating S/MIME encrypted
9176 messages (for the specified account).
9177 RFC 5751 mandates a default of
9180 Possible values are (case-insensitive and) in decreasing cipher strength:
9188 (DES EDE3 CBC, 168 bits; default if
9190 is not available) and
9194 The actually available cipher algorithms depend on the cryptographic
9195 library that \*(UA uses.
9196 \*(OP Support for more cipher algorithms may be available through
9197 dynamic loading via, e.g.,
9198 .Xr EVP_get_cipherbyname 3
9199 (OpenSSL) if \*(UA has been compiled to support this.
9202 .It Va smime-crl-dir
9203 \*(OP Specifies a directory that contains files with CRLs in PEM format
9204 to use when verifying S/MIME messages.
9207 .It Va smime-crl-file
9208 \*(OP Specifies a file that contains a CRL in PEM format to use when
9209 verifying S/MIME messages.
9212 .It Va smime-encrypt-USER@HOST
9213 \*(OP If this variable is set, messages send to the given receiver are
9214 encrypted before sending.
9215 The value of the variable must be set to the name of a file that
9216 contains a certificate in PEM format.
9218 If a message is sent to multiple recipients,
9219 each of them for whom a corresponding variable is set will receive an
9220 individually encrypted message;
9221 other recipients will continue to receive the message in plain text
9223 .Va smime-force-encryption
9225 It is recommended to sign encrypted messages, i.e., to also set the
9230 .It Va smime-force-encryption
9231 \*(BO\*(OP Causes \*(UA to refuse sending unencrypted messages.
9235 \*(BO\*(OP S/MIME sign outgoing messages with the user's private key
9236 and include the user's certificate as a MIME attachment.
9237 Signing a message enables a recipient to verify that the sender used
9238 a valid certificate,
9239 that the email addresses in the certificate match those in the message
9240 header and that the message content has not been altered.
9241 It does not change the message text,
9242 and people will be able to read the message as usual.
9244 .Va smime-sign-cert , smime-sign-include-certs
9246 .Va smime-sign-message-digest .
9248 .Mx Va smime-sign-cert
9249 .It Va smime-sign-cert-USER@HOST , smime-sign-cert
9250 \*(OP Points to a file in PEM format.
9251 For the purpose of signing and decryption this file needs to contain the
9252 user's private key, followed by his certificate.
9256 is always derived from the value of
9258 (or, if that contains multiple addresses,
9260 For the purpose of encryption the recipient's public encryption key
9261 (certificate) is expected; the command
9263 can be used to save certificates of signed messages (the section
9264 .Sx "Signed and encrypted messages with S/MIME"
9265 gives some details).
9266 This mode of operation is usually driven by the specialized form.
9268 When decrypting messages the account is derived from the recipient
9273 of the message, which are searched for addresses for which such
9275 \*(UA always uses the first address that matches,
9276 so if the same message is sent to more than one of the user's addresses
9277 using different encryption keys, decryption might fail.
9279 For signing and decryption purposes it is possible to use encrypted
9280 keys, and the pseudo-host(s)
9281 .Ql USER@HOST.smime-cert-key
9284 .Ql USER@HOST.smime-cert-cert
9285 for the certificate stored in the same file)
9286 will be used for performing any necessary password lookup,
9287 therefore the lookup can be automatized via the mechanisms described in
9288 .Sx "On URL syntax and credential lookup" .
9289 For example, the hypothetical address
9291 could be driven with a private key / certificate pair path defined in
9292 .Va \&\&smime-sign-cert-bob@exam.ple ,
9293 and needed passwords would then be looked up via the pseudo hosts
9294 .Ql bob@exam.ple.smime-cert-key
9296 .Ql bob@exam.ple.smime-cert-cert ) .
9297 To include intermediate certificates, use
9298 .Va smime-sign-include-certs .
9300 .Mx Va smime-sign-include-certs
9301 .It Va smime-sign-include-certs-USER@HOST , smime-sign-include-certs
9302 \*(OP If used, this is supposed to a consist of a comma-separated list
9303 of files, each of which containing a single certificate in PEM format to
9304 be included in the S/MIME message in addition to the
9307 This can be used to include intermediate certificates of the certificate
9308 authority, in order to allow the receiver's S/MIME implementation to
9309 perform a verification of the entire certificate chain, starting from
9310 a local root certificate, over the intermediate certificates, down to the
9311 .Va smime-sign-cert .
9312 Even though top level certificates may also be included in the chain,
9313 they won't be used for the verification on the receiver's side.
9315 For the purpose of the mechanisms involved here,
9317 refers to the content of the internal variable
9319 (or, if that contains multiple addresses,
9322 .Ql USER@HOST.smime-include-certs
9323 will be used for performing password lookups for these certificates,
9324 shall they have been given one, therefore the lookup can be automatized
9325 via the mechanisms described in
9326 .Sx "On URL syntax and credential lookup" .
9328 .Mx Va smime-sign-message-digest
9329 .It Va smime-sign-message-digest-USER@HOST , smime-sign-message-digest
9330 \*(OP Specifies the message digest to use when signing S/MIME messages.
9331 RFC 5751 mandates a default of
9333 Possible values are (case-insensitive and) in decreasing cipher strength:
9341 The actually available message digest algorithms depend on the
9342 cryptographic library that \*(UA uses.
9343 \*(OP Support for more message digest algorithms may be available
9344 through dynamic loading via, e.g.,
9345 .Xr EVP_get_digestbyname 3
9346 (OpenSSL) if \*(UA has been compiled to support this.
9347 Remember that for this
9349 refers to the variable
9351 (or, if that contains multiple addresses,
9356 \*(OB\*(OP To use the builtin SMTP transport, specify a SMTP URL in
9358 \*(ID For compatibility reasons a set
9360 is used in preference of
9364 .It Va smtp-auth-USER@HOST , smtp-auth-HOST , smtp-auth
9365 \*(OP Variable chain that controls the SMTP
9367 authentication method, possible values are
9373 as well as the \*(OPal methods
9379 method does not need any user credentials,
9381 requires a user name and all other methods require a user name and
9389 .Va smtp-auth-password
9391 .Va smtp-auth-user ) .
9396 .Va smtp-auth-USER@HOST :
9397 may override dependent on sender address in the variable
9400 .It Va smtp-auth-password
9401 \*(OP\*(OU Sets the global fallback password for SMTP authentication.
9402 If the authentication method requires a password, but neither
9403 .Va smtp-auth-password
9405 .Va smtp-auth-password-USER@HOST
9407 \*(UA will ask for a password on the user's terminal.
9409 .It Va smtp-auth-password-USER@HOST
9411 .Va smtp-auth-password
9412 for specific values of sender addresses, dependent upon the variable
9415 .It Va smtp-auth-user
9416 \*(OP\*(OU Sets the global fallback user name for SMTP authentication.
9417 If the authentication method requires a user name, but neither
9420 .Va smtp-auth-user-USER@HOST
9422 \*(UA will ask for a user name on the user's terminal.
9424 .It Va smtp-auth-user-USER@HOST
9427 for specific values of sender addresses, dependent upon the variable
9431 .It Va smtp-hostname
9432 \*(OP\*(IN Normally \*(UA uses the variable
9434 to derive the necessary
9436 information in order to issue a
9443 can be used to use the
9445 from the SMTP account
9452 from the content of this variable (or, if that is the empty string,
9454 or the local hostname as a last resort).
9455 This often allows using an address that is itself valid but hosted by
9456 a provider other than which (in
9458 is about to send the message.
9459 Setting this variable also influences generated
9465 .Mx Va smtp-use-starttls
9466 .It Va smtp-use-starttls-USER@HOST , smtp-use-starttls-HOST , smtp-use-starttls
9467 \*(BO\*(OP Causes \*(UA to issue a
9469 command to make an SMTP
9471 session SSL/TLS encrypted, i.e., to enable transport layer security.
9475 .It Va spam-interface
9476 \*(OP In order to use any of the spam-related commands (like, e.g.,
9478 the desired spam interface must be defined by setting this variable.
9479 Please refer to the manual section
9481 for the complete picture of spam handling in \*(UA.
9482 All or none of the following interfaces may be available:
9484 .Bl -tag -width ".It Ql _ilte_"
9490 .Pf ( Lk http://spamassassin.apache.org SpamAssassin )
9492 Different to the generic filter interface \*(UA will automatically add
9493 the correct arguments for a given command and has the necessary
9494 knowledge to parse the program's output.
9497 will have been compiled into the \*(UA binary if
9502 Shall it be necessary to define a specific connection type (rather than
9503 using a configuration file for that), the variable
9505 can be used as in, e.g.,
9506 .Ql -d server.example.com -p 783 .
9507 It is also possible to specify a per-user configuration via
9509 Note that this interface does not inspect the
9511 flag of a message for the command
9515 generic spam filter support via freely configurable hooks.
9516 This interface is meant for programs like
9518 and requires according behaviour in respect to the hooks' exit
9519 status for at least the command
9522 meaning a message is spam,
9526 for unsure and any other return value indicating a hard error);
9527 since the hooks can include shell code snippets diverting behaviour
9528 can be intercepted as necessary.
9530 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
9533 .Va spamfilter-spam ;
9536 contains examples for some programs.
9537 The process environment of the hooks will have the variable
9538 .Ev MAILX_FILENAME_GENERATED
9540 Note that spam score support for
9542 is not supported unless the \*(OPtional regular expression support is
9544 .Va spamfilter-rate-scanscore
9551 \*(OP Messages that exceed this size will not be passed through to the
9553 .Va spam-interface .
9554 If unset or 0, the default of 420000 bytes is used.
9557 .It Va spamc-command
9558 \*(OP The path to the
9562 .Va spam-interface .
9563 Note that the path is not expanded, but used
9565 A fallback path will have been compiled into the \*(UA binary if the
9566 executable had been found during compilation.
9569 .It Va spamc-arguments
9570 \*(OP Even though \*(UA deals with most arguments for the
9573 automatically, it may at least sometimes be desirable to specify
9574 connection-related ones via this variable, e.g.,
9575 .Ql -d server.example.com -p 783 .
9579 \*(OP Specify a username for per-user configuration files for the
9581 .Va spam-interface .
9582 If this is set to the empty string then \*(UA will use the name of the
9591 .It Va spamfilter-ham , spamfilter-noham , \
9592 spamfilter-nospam , spamfilter-rate , spamfilter-spam
9593 \*(OP Command and argument hooks for the
9595 .Va spam-interface .
9598 contains examples for some programs.
9601 .It Va spamfilter-rate-scanscore
9602 \*(OP Because of the generic nature of the
9605 spam scores are not supported for it by default, but if the \*(OPnal
9606 regular expression support is available then setting this variable can
9607 be used to overcome this restriction.
9608 It is interpreted as follows: first a number (digits) is parsed that
9609 must be followed by a semicolon
9611 and an extended regular expression.
9612 Then the latter is used to parse the first output line of the
9614 hook, and, in case the evaluation is successful, the group that has been
9615 specified via the number is interpreted as a floating point scan score.
9619 .It Va ssl-ca-dir , ssl-ca-file
9620 \*(OP Specify the location of trusted CA certificates in PEM (Privacy
9621 Enhanced Mail) format as a directory and a file, respectively, for the
9622 purpose of verification of SSL/TLS server certificates.
9623 It is possible to set both, the file will be loaded immediately, the
9624 directory will be searched whenever no match has yet been found.
9625 The set of CA certificates which are built into the SSL/TLS library can
9626 be explicitly turned off by setting
9627 .Va ssl-ca-no-defaults ,
9628 and further fine-tuning is possible via
9631 .Xr SSL_CTX_load_verify_locations 3
9632 for more information.
9637 \*(OP Can be used to fine-tune behaviour of the X509 CA certificate
9638 storage, and the certificate verification that is used (also see
9640 The value is expected to consist of a comma-separated list of
9641 configuration directives, with any intervening whitespace being ignored.
9642 The directives directly map to flags that can be passed to
9643 .Xr X509_STORE_set_flags 3 ,
9644 which are usually defined in a file
9645 .Pa openssl/x509_vfy.h ,
9646 and the availability of which depends on the used SSL/TLS library
9647 version: a directive without mapping is ignored (error log subject to
9649 Directives currently understood (case-insensitively) include:
9652 .Bl -tag -compact -width ".It Cd BaNg"
9653 .It Cd no-alt-chains
9654 If the initial chain is not trusted, do not attempt to build an
9656 Setting this flag will make OpenSSL certificate verification match that
9657 of older OpenSSL versions, before automatic building and checking of
9658 alternative chains has been implemented; also see
9660 .It Cd no-check-time
9661 Do not check certificate/CRL validity against current time.
9662 .It Cd partial-chain
9663 By default partial, incomplete chains which cannot be verified up to the
9664 chain top, a self-signed root certificate, will not verify.
9665 With this flag set, a chain succeeds to verify if at least one signing
9666 certificate of the chain is in any of the configured trusted stores of
9668 The OpenSSL manual page
9669 .Xr SSL_CTX_load_verify_locations 3
9670 gives some advise how to manage your own trusted store of CA certificates.
9672 Disable workarounds for broken certificates.
9673 .It Cd trusted-first
9674 Try building a chain using issuers in the trusted store first to avoid
9675 problems with server-sent legacy intermediate certificates.
9676 Newer versions of OpenSSL support alternative chain checking and enable
9677 it by default, resulting in the same behaviour; also see
9683 .It Va ssl-ca-no-defaults
9684 \*(BO\*(OP Do not load the default CA locations that are built into the
9685 used to SSL/TLS library to verify SSL/TLS server certificates.
9688 .It Va ssl-cert-USER@HOST , ssl-cert-HOST , ssl-cert
9689 \*(OP Variable chain that sets the file name for a SSL/TLS client
9690 certificate required by some servers.
9691 This is a direct interface to the
9695 function of the OpenSSL library, if available.
9697 .Mx Va ssl-cipher-list
9698 .It Va ssl-cipher-list-USER@HOST , ssl-cipher-list-HOST , ssl-cipher-list
9699 \*(OP Specifies a list of ciphers for SSL/TLS connections.
9700 This is a direct interface to the
9704 function of the OpenSSL library, if available; see
9706 for more information.
9707 By default \*(UA does not set a list of ciphers, in effect using a
9709 specific cipher (protocol standards ship with a list of acceptable
9710 ciphers), possibly cramped to what the actually used SSL/TLS library
9711 supports \(en the manual section
9712 .Sx "An example configuration"
9713 also contains a SSL/TLS use case.
9716 .It Va ssl-config-file
9717 \*(OP If this variable is set \*(UA will call
9718 .Xr CONF_modules_load_file 3
9719 to allow OpenSSL to be configured according to the host system wide
9721 If a non-empty value is given then this will be used to specify the
9722 configuration file to be used instead of the global OpenSSL default;
9723 note that in this case it is an error if the file cannot be loaded.
9724 The application name will always be passed as
9729 .It Va ssl-crl-dir , ssl-crl-file
9730 \*(OP Specify a directory / a file, respectively that contains a CRL in
9731 PEM format to use when verifying SSL/TLS server certificates.
9734 .It Va ssl-key-USER@HOST , ssl-key-HOST , ssl-key
9735 \*(OP Variable chain that sets the file name for the private key of
9736 a SSL/TLS client certificate.
9737 If unset, the name of the certificate file is used.
9738 The file is expected to be in PEM format.
9739 This is a direct interface to the
9743 function of the OpenSSL library, if available.
9746 .It Va ssl-method-USER@HOST , ssl-method-HOST , ssl-method
9747 \*(OB\*(OP Please use the newer and more flexible
9749 instead: if both values are set,
9751 will take precedence!
9752 Can be set to the following values, the actually used
9754 specification to which it is mapped is shown in parenthesis:
9756 .Pf ( Ql -ALL, TLSv1.2 ) ,
9758 .Pf ( Ql -ALL, TLSv1.1 ) ,
9760 .Pf ( Ql -ALL, TLSv1 )
9763 .Pf ( Ql -ALL, SSLv3 ) ;
9768 and thus includes the SSLv3 protocol.
9769 Note that SSLv2 is no longer supported at all.
9772 .It Va ssl-protocol-USER@HOST , ssl-protocol-HOST , ssl-protocol
9773 \*(OP Specify the used SSL/TLS protocol.
9774 This is a direct interface to the
9778 function of the OpenSSL library, if available;
9779 otherwise an \*(UA internal parser is used which understands the
9780 following subset of (case-insensitive) command strings:
9786 as well as the special value
9788 Multiple specifications may be given via a comma-separated list which
9789 ignores any whitespace.
9792 plus sign prefix will enable a protocol, a
9794 hyphen-minus prefix will disable it, so that
9796 will enable only the TLSv1.2 protocol.
9798 It depends upon the used TLS/SSL library which protocols are actually
9799 supported and which protocols are used if
9801 is not set, but note that SSLv2 is no longer supported at all and
9803 Especially for older protocols explicitly securing
9805 may be worthwile, see
9806 .Sx "An example configuration" .
9810 \*(OP Gives the pathname to an entropy daemon socket, see
9812 Not all SSL/TLS libraries support this.
9815 .It Va ssl-rand-file
9816 \*(OP Gives the filename to a file with random entropy data, see
9817 .Xr RAND_load_file 3 .
9818 If this variable is not set, or set to the empty string, or if the
9819 .Sx "Filename transformations"
9821 .Xr RAND_file_name 3
9822 will be used to create the filename if, and only if,
9824 documents that the SSL PRNG is not yet sufficiently seeded.
9825 If \*(UA successfully seeded the SSL PRNG then it will update the file
9826 .Pf ( Xr RAND_write_file 3 ) .
9827 This variable is only used if
9829 is not set (or not supported by the SSL/TLS library).
9832 .It Va ssl-verify-USER@HOST , ssl-verify-HOST , ssl-verify
9833 \*(OP Variable chain that sets the action to be performed if an error
9834 occurs during SSL/TLS server certificate validation against the
9835 specified or default trust stores
9838 or the SSL/TLS library builtin defaults (unless usage disallowed via
9839 .Va ssl-ca-no-defaults ) ,
9840 and as fine-tuned via
9842 Valid (case-insensitive) values are
9844 (fail and close connection immediately),
9846 (ask whether to continue on standard input),
9848 (show a warning and continue),
9850 (do not perform validation).
9856 If only set without an assigned value, then this setting inhibits the
9862 header fields that include obvious references to \*(UA.
9863 There are two pitfalls associated with this:
9864 First, the message id of outgoing messages is not known anymore.
9865 Second, an expert may still use the remaining information in the header
9866 to track down the originating mail user agent.
9873 suppression does not occur.
9878 (\*(OP) This specifies a comma-separated list of
9883 .Sx "On terminal control and line editor" ,
9884 escape commas with reverse solidus) to be used to overwrite or define
9886 Note that this variable will only be queried once at program startup and
9887 can thus only be specified in resource files or on the command line.
9890 String capabilities form
9892 pairs and are expected unless noted otherwise.
9893 Numerics have to be notated as
9895 where the number is expected in normal decimal notation.
9896 Finally, booleans do not have any value but indicate a true or false
9897 state simply by being defined or not; this indeed means that \*(UA
9898 does not support undefining an existing boolean.
9899 String capability values will undergo some expansions before use:
9900 for one notations like
9903 .Ql control-LETTER ,
9904 and for clarification purposes
9906 can be used to specify
9908 (the control notation
9910 could lead to misreadings when a left bracket follows, which it does for
9911 the standard CSI sequence);
9912 finally three letter octal sequences, as in
9915 To specify that a terminal supports 256-colours, and to define sequences
9916 that home the cursor and produce an audible bell, one might write:
9918 .Bd -literal -offset indent
9919 set termcap='Co#256,home=\eE[H,bel=^G'
9923 The following terminal capabilities are or may be meaningful for the
9924 operation of the builtin line editor or \*(UA in general:
9927 .Bl -tag -compact -width yay
9929 .It Cd colors Ns \0or Cd Co
9931 numeric capability specifying the maximum number of colours.
9932 Note that \*(UA does not actually care about the terminal beside that,
9933 but always emits ANSI / ISO 6429 escape sequences.
9936 .It Cd rmcup Ns \0or Cd te Ns \0/ Cd smcup Ns \0or Cd ti
9940 respectively: exit and enter the alternative screen
9942 effectively turning \*(UA into a fullscreen application.
9943 To disable that, set (at least) one to the empty string.
9945 .It Cd smkx Ns \0or Cd ks Ns \0/ Cd rmkx Ns \0or Cd ke
9949 respectively: enable and disable the keypad.
9950 This is always enabled if available, because it seems even keyboards
9951 without keypads generate other key codes for, e.g., cursor keys in that
9952 case, and only if enabled we see the codes that we are interested in.
9954 .It Cd ed Ns \0or Cd cd
9958 .It Cd clear Ns \0or Cd cl
9960 clear the screen and home cursor.
9961 (Will be simulated via
9966 .It Cd home Ns \0or Cd ho
9971 .It Cd el Ns \0or Cd ce
9973 clear to the end of line.
9974 (Will be simulated via
9976 plus repetitions of space characters.)
9978 .It Cd hpa Ns \0or Cd ch
9979 .Cd column_address :
9980 move the cursor (to the given column parameter) in the current row.
9981 (Will be simulated via
9987 .Cd carriage_return :
9988 move to the first column in the current row.
9989 The default builtin fallback is
9992 .It Cd cub1 Ns \0or Cd le
9994 move the cursor left one space (non-destructively).
9995 The default builtin fallback is
9998 .It Cd cuf1 Ns \0or Cd nd
10000 move the cursor right one space (non-destructively).
10001 The default builtin fallback is
10003 which is used by most terminals.
10011 Many more capabilities which describe key-sequences are documented for
10015 .It Va termcap-disable
10016 \*(OP Disable any interaction with a terminal control library.
10017 If set only some generic fallback builtins and possibly the content of
10019 describe the terminal to \*(UA.
10021 that this variable will only be queried once at program startup and can
10022 thus only be specified in resource files or on the command line.
10026 If defined, gives the number of lines of a message to be displayed
10029 if unset, the first five lines are printed, if set to 0 the variable
10032 If the value is negative then its absolute value will be used for
10033 unsigned right shifting (see
10041 \*(BO If set then the
10043 command series will strip adjacent empty lines and quotations.
10047 The character set of the terminal \*(UA operates on,
10048 and the one and only supported character set that \*(UA can use if no
10049 character set conversion capabilities have been compiled into it,
10050 in which case it defaults to ISO-8859-1 unless it can deduce a value
10053 locale environment.
10054 It defaults to UTF-8 if conversion is available.
10055 Refer to the section
10056 .Sx "Character sets"
10057 for the complete picture about character sets.
10060 .It Va typescript-mode
10061 \*(BO A special multiplex variable that disables all variables and
10062 settings which result in behaviour that interferes with running \*(UA in
10065 .Va colour-disable ,
10066 .Va line-editor-disable
10067 and (before startup completed only)
10068 .Va termcap-disable .
10069 Unsetting it does not restore the former state of the covered settings.
10073 For a safety-by-default policy \*(UA sets its process
10077 but this variable can be used to override that:
10078 set it to an empty value to do not change the (current) setting,
10079 otherwise the process file mode creation mask is updated to the new value.
10080 Child processes inherit the process file mode creation mask.
10083 .It Va user-HOST , user
10084 \*(IN Variable chain that sets a global fallback user name, which is
10085 used in case none has been given in the protocol and account-specific
10087 This variable defaults to the name of the user who runs \*(UA.
10091 \*(BO Setting this enables upward compatibility with \*(UA
10092 version 15.0 in respect to which configuration options are available and
10093 how they are handled.
10094 This manual uses \*(IN and \*(OU to refer to the new and the old way of
10095 doing things, respectively.
10099 \*(BO This setting, also controllable via the command line option
10101 causes \*(UA to be more verbose, e.g., it will display obsoletion
10102 warnings and SSL/TLS certificate chains.
10103 Even though marked \*(BO this option may be set twice in order to
10104 increase the level of verbosity even more, in which case even details of
10105 the actual message delivery and protocol conversations are shown.
10108 is sufficient to disable verbosity as such.
10114 .It Va version , version-major , version-minor , version-update
10115 \*(RO \*(UA version information: the first variable contains a string
10116 containing the complete version identification, the latter three contain
10117 only digits: the major, minor and update version numbers.
10118 The output of the command
10120 will include this information.
10123 .It Va writebackedited
10124 If this variable is set messages modified using the
10128 commands are written back to the current folder when it is quit;
10129 it is only honoured for writable folders in MBOX format, though.
10130 Note that the editor will be pointed to the raw message content in that
10131 case, i.e., neither MIME decoding nor decryption will have been
10132 performed, and proper RFC 4155
10134 quoting of newly added or edited content is also left as an excercise to
10137 .\" }}} (Variables)
10138 .\" }}} (INTERNAL VARIABLES)
10141 .\" .Sh ENVIRONMENT {{{
10145 .Dq environment variable
10146 should be considered an indication that these variables are either
10147 standardized as vivid parts of process environments, or that they are
10148 commonly found in there.
10149 The process environment is inherited from the
10151 once \*(UA is started, and unless otherwise explicitly noted handling of
10152 the following variables transparently integrates into that of the
10153 .Sx "INTERNAL VARIABLES"
10154 from \*(UA's point of view.
10155 This means that, e.g., they can be managed via
10159 causing automatic program environment updates (to be inherited by
10160 newly created child processes).
10163 In order to transparently integrate other environment variables equally
10164 they need to be imported (linked) with the command
10166 This command can also be used to set and unset non-integrated
10167 environment variables from scratch, sufficient system support provided.
10168 The following example, applicable to a POSIX shell, sets the
10170 environment variable for \*(UA only, and beforehand exports the
10172 in order to affect any further processing in the running shell:
10174 .Bd -literal -offset indent
10175 $ EDITOR="vim -u ${HOME}/.vimrc"
10177 $ COLUMNS=80 \*(uA -R
10180 .Bl -tag -width ".It Ev BaNg"
10183 The user's preferred width in column positions for the terminal screen
10185 Queried and used once on program startup, actively managed for child
10186 processes and the MLE (see
10187 .Sx "On terminal control and line editor" )
10188 in interactive mode thereafter.
10192 The name of the (mailbox)
10194 to use for saving aborted messages if
10196 is set; this defaults to
10203 is set no output will be generated, otherwise the contents of the file
10208 Pathname of the text editor to use in the
10212 .Sx "COMMAND ESCAPES" .
10213 A default editor is used if this value is not defined.
10217 The user's home directory.
10218 This variable is only used when it resides in the process environment.
10225 .It Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
10229 .Sx "Character sets" .
10233 The user's preferred number of lines on a page or the vertical screen
10234 or window size in lines.
10235 Queried and used once on program startup, actively managed for child
10236 processes in interactive mode thereafter.
10240 Pathname of the directory lister to use in the
10242 command when operating on local mailboxes.
10245 (path search through
10250 Upon startup \*(UA will actively ensure that this variable refers to the
10251 name of the user who runs \*(UA, in order to be able to pass a verified
10252 name to any newly created child process.
10256 Is used as the users
10258 .Sx "primary system mailbox"
10262 This is assumed to be an absolute pathname.
10266 \*(OP Overrides the default path search for
10267 .Sx "The Mailcap files" ,
10268 which is defined in the standard RFC 1524 as
10269 .Ql ~/.mailcap:\:/etc/mailcap:\:/usr/etc/mailcap:\:/usr/local/etc/mailcap .
10270 .\" TODO we should have a mailcaps-default virtual RDONLY option!
10271 (\*(UA makes it a configuration option, however.)
10272 Note this is not a search path, but a path search.
10276 Is used as a startup file instead of
10279 When \*(UA scripts are invoked on behalf of other users,
10280 either this variable should be set to
10284 command line option should be used in order to avoid side-effects from
10285 reading their configuration files.
10286 This variable is only used when it resides in the process environment.
10289 .It Ev MAILX_NO_SYSTEM_RC
10290 If this variable is set then reading of
10292 at startup is inhibited, i.e., the same effect is achieved as if \*(UA
10293 had been started up with the option
10295 (and according argument) or
10297 This variable is only used when it resides in the process environment.
10301 The name of the users mbox file.
10302 A logical subset of the special
10303 .Sx "Filename transformations"
10307 The fallback default is
10314 .Sx "secondary mailbox"
10315 is used as the file to save messages from the
10317 .Sx "primary system mailbox"
10318 that have been read.
10320 .Sx "Message states" .
10324 \*(IN\*(OP This variable overrides the default location of the user's
10330 Pathname of the program to use for backing the command
10334 variable enforces usage of a pager for output.
10335 The default paginator is
10337 (path search through
10340 \*(UA inspects the contents of this variable: if its contains the string
10342 then a non-existing environment variable
10349 dependent on whether terminal control support is available and whether
10350 that supports full (alternative) screen mode or not (also see
10351 .Sx "On terminal control and line editor" ) .
10355 will optionally be set to
10362 A colon-separated list of directories that is searched by the shell when
10363 looking for commands, e.g.,
10364 .Ql /bin:/usr/bin:/usr/local/bin .
10367 .It Ev POSIXLY_CORRECT
10368 This variable is automatically looked for upon startup, see
10374 The shell to use for the commands
10379 .Sx "COMMAND ESCAPES"
10380 and when starting subprocesses.
10381 A default shell is used if this environment variable is not defined.
10384 .It Ev SOURCE_DATE_EPOCH
10385 If set, this specifies a time in seconds since the Unix epoch
10386 (1970-01-01) to be used in place of the current time.
10387 This is for the sake of reproduceability of tests, to be used during
10388 development or by software packagers.
10392 \*(OP The terminal type for which output is to be prepared.
10393 For extended colour and font control please refer to
10394 .Sx "Coloured display" ,
10395 and for terminal management in general to
10396 .Sx "On terminal control and line editor" .
10400 Used as directory for temporary files instead of
10403 This variable is only used when it resides in the process environment,
10404 but \*(UA will ensure at startup that this environment variable is
10405 updated to contain a usable temporary directory.
10411 (see there), but this variable is not standardized, should therefore not
10412 be used, and is only corrected if already set.
10416 Pathname of the text editor to use in the
10420 .Sx "COMMAND ESCAPES" .
10428 .Bl -tag -width ".It Pa BaNg"
10430 File giving initial commands.
10433 System wide initialization file.
10437 \*(OP Personal MIME type handler definition file, see
10438 .Sx "The Mailcap files" .
10439 (RFC 1524 location, the actual path is a configuration option.)
10442 .It Pa /etc/mailcap
10443 \*(OP System wide MIME type handler definition file, see
10444 .Sx "The Mailcap files" .
10445 (RFC 1524 location, the actual path is a configuration option.)
10448 .It Pa ~/.mime.types
10449 Personal MIME types, see
10450 .Sx "The mime.types files" .
10453 .It Pa /etc/mime.types
10454 System wide MIME types, see
10455 .Sx "The mime.types files" .
10459 \*(IN\*(OP The default location of the users
10461 file \(en the section
10462 .Sx "The .netrc file"
10463 documents the file format.
10466 .\" .Ss "The mime.types files" {{{
10467 .Ss "The mime.types files"
10469 When sending messages \*(UA tries to determine the content type of all
10471 When displaying message content or attachments \*(UA uses the content
10472 type to decide whether it can directly display data or whether it needs
10473 to deal with content handlers.
10474 It learns about M(ultipurpose) I(nternet) M(ail) E(xtensions) types and
10475 how to treat them by reading
10477 files, the loading of which can be controlled by setting the variable
10478 .Va mimetypes-load-control .
10481 can also be used to deal with MIME types.)
10483 files have the following syntax:
10486 .Dl type/subtype extension [extension ...]
10491 are strings describing the file contents, and one or multiple
10493 s, separated by whitespace, name the part of a filename starting after
10494 the last dot (of interest).
10495 Comments may be introduced anywhere on a line with a number sign
10497 causing the remaining line to be discarded.
10499 \*(UA also supports an extended, non-portable syntax in specially
10500 crafted files, which can be loaded via the alternative value syntax of
10501 .Va mimetypes-load-control
10502 and prepends an optional
10506 .Dl [type-marker ]type/subtype extension [extension ...]
10509 The following type markers are supported:
10512 .Bl -tag -compact -width ".It Ar _n_u"
10514 Treat message parts with this content as plain text.
10519 Treat message parts with this content as HTML tagsoup.
10520 If the \*(OPal HTML-tagsoup-to-text converter is not available treat
10521 the content as plain text instead.
10525 but instead of falling back to plain text require an explicit content
10526 handler to be defined.
10531 for sending messages:
10533 .Va mime-allow-text-controls ,
10534 .Va mimetypes-load-control .
10535 For reading etc. messages:
10536 .Sx "HTML mail and MIME attachments" ,
10537 .Sx "The Mailcap files" ,
10539 .Va mime-counter-evidence ,
10540 .Va mimetypes-load-control ,
10541 .Va pipe-TYPE/SUBTYPE ,
10542 .Va pipe-EXTENSION .
10545 .\" .Ss "The Mailcap files" {{{
10546 .Ss "The Mailcap files"
10548 .\" TODO MAILCAP DISABLED
10549 .Sy This feature is not available in v14.9.0, sorry!
10551 .Dq User Agent Configuration Mechanism
10552 which \*(UA \*(OPally supports.
10553 It defines a file format to be used to inform mail user agent programs
10554 about the locally-installed facilities for handling various data
10555 formats, i.e., about commands and how they can be used to display, edit
10556 etc. MIME part contents, as well as a default path search that includes
10557 multiple possible locations of
10561 environment variable that can be used to overwrite that (repeating here
10562 that it is not a search path, but instead a path search specification).
10563 Any existing files will be loaded in sequence, appending any content to
10564 the list of MIME type handler directives.
10568 files consist of a set of newline separated entries.
10569 Comment lines start with a number sign
10571 (in the first column!) and are ignored.
10572 Empty lines are also ignored.
10573 All other lines form individual entries that must adhere to the syntax
10575 To extend a single entry (not comment) its line can be continued on
10576 follow lines if newline characters are
10578 by preceding them with the reverse solidus character
10580 The standard does not specify how leading whitespace of follow lines
10581 is to be treated, therefore \*(UA retains it.
10585 entries consist of a number of semicolon
10587 separated fields, and the reverse solidus
10589 character can be used to escape any following character including
10590 semicolon and itself.
10591 The first two fields are mandatory and must occur in the specified
10592 order, the remaining fields are optional and may appear in any order.
10593 Leading and trailing whitespace of content is ignored (removed).
10596 The first field defines the MIME
10598 the entry is about to handle (case-insensitively, and no reverse solidus
10599 escaping is possible in this field).
10600 If the subtype is specified as an asterisk
10602 the entry is meant to match all subtypes of the named type, e.g.,
10604 would match any audio type.
10605 The second field defines the shell command which shall be used to
10607 MIME parts of the given type; it is implicitly called the
10614 shell commands message (MIME part) data is passed via standard input
10615 unless the given shell command includes one or more instances of the
10618 in which case these instances will be replaced with a temporary filename
10619 and the data will have been stored in the file that is being pointed to.
10622 shell commands data is assumed to be generated on standard output unless
10623 the given command includes (one ore multiple)
10625 In any case any given
10627 format is replaced with a(n already) properly quoted filename.
10628 Note that when a command makes use of a temporary file via
10630 then \*(UA will remove it again, as if the
10631 .Cd x-mailx-tmpfile ,
10632 .Cd x-mailx-tmpfile-fill
10634 .Cd x-mailx-tmpfile-unlink
10635 flags had been set; see below for more.
10638 The optional fields either define a shell command or an attribute (flag)
10639 value, the latter being a single word and the former being a keyword
10640 naming the field followed by an equals sign
10642 succeeded by a shell command, and as usual for any
10644 content any whitespace surrounding the equals sign will be removed, too.
10645 Optional fields include the following:
10648 .Bl -tag -width ".It Cd BaNg"
10650 A program that can be used to compose a new body or body part in the
10652 (Currently unused.)
10654 .It Cd composetyped
10657 field, but is to be used when the composing program needs to specify the
10659 header field to be applied to the composed data.
10660 (Currently unused.)
10663 A program that can be used to edit a body or body part in the given
10665 (Currently unused.)
10668 A program that can be used to print a message or body part in the given
10670 (Currently unused.)
10673 Specifies a program to be run to test some condition, e.g., the machine
10674 architecture, or the window system in use, to determine whether or not
10675 this mailcap entry applies.
10676 If the test fails, a subsequent mailcap entry should be sought; also see
10677 .Cd x-mailx-test-once .
10679 .It Cd needsterminal
10680 This flag field indicates that the given shell command must be run on
10681 an interactive terminal.
10682 \*(UA will temporarily release the terminal to the given command in
10683 interactive mode, in non-interactive mode this entry will be entirely
10684 ignored; this flag implies
10685 .Cd x-mailx-noquote .
10687 .It Cd copiousoutput
10688 A flag field which indicates that the output of the
10690 command will be an extended stream of textual output that can be
10691 (re)integrated into \*(UA's normal visual display.
10692 It is mutually exclusive with
10695 .Cd x-mailx-always .
10697 .It Cd textualnewlines
10698 A flag field which indicates that this type of data is line-oriented and
10699 that, if encoded in
10701 all newlines should be converted to canonical form (CRLF) before
10702 encoding, and will be in that form after decoding.
10703 (Currently unused.)
10705 .It Cd nametemplate
10706 This field gives a file name format, in which
10708 will be replaced by a random string, the joined combination of which
10709 will be used as the filename denoted by
10710 .Ev MAILX_FILENAME_TEMPORARY .
10711 One could specify that a GIF file being passed to an image viewer should
10712 have a name ending in
10715 .Ql nametemplate=%s.gif .
10716 Note that \*(UA ignores the name template unless that solely specifies
10717 a filename suffix that consists of (ASCII) alphabetic and numeric
10718 characters, the underscore and dot only.
10721 Names a file, in X11 bitmap (xbm) format, which points to an appropriate
10722 icon to be used to visually denote the presence of this kind of data.
10723 This field is not used by \*(UA.
10726 A textual description that describes this type of data.
10728 .It Cd x-mailx-always
10729 Extension flag field that denotes that the given
10731 command shall be executed even if multiple messages will be displayed
10733 Normally messages which require external viewers that produce output
10734 which does not integrate into \*(UA's visual display (i.e., do not have
10736 set) have to be addressed directly and individually.
10737 (To avoid cases where, e.g., a thousand PDF viewer instances are spawned
10740 .It Cd x-mailx-even-if-not-interactive
10741 An extension flag test field \(em by default handlers without
10743 are entirely ignored in non-interactive mode, but if this flag is set
10744 then their use will be considered.
10745 It is an error if this flag is set for commands that use the flag
10746 .Cd needsterminal .
10748 .It Cd x-mailx-noquote
10749 An extension flag field that indicates that even a
10752 command shall not be used to generate message quotes
10753 (as it would be by default).
10755 .It Cd x-mailx-async
10756 Extension flag field that denotes that the given
10758 command shall be executed asynchronously, without blocking \*(UA.
10759 Cannot be used in conjunction with
10760 .Cd needsterminal .
10762 .It Cd x-mailx-test-once
10763 Extension flag which denotes whether the given
10765 command shall be evaluated once only and the (boolean) result be cached.
10766 This is handy if some global unchanging condition is to be queried, like
10767 .Dq running under the X Window System .
10769 .It Cd x-mailx-tmpfile
10770 Extension flag field that requests creation of a zero-sized temporary
10771 file, the name of which is to be placed in the environment variable
10772 .Ev MAILX_FILENAME_TEMPORARY .
10773 It is an error to use this flag with commands that include a
10777 .It Cd x-mailx-tmpfile-fill
10778 Normally the MIME part content is passed to the handler via standard
10779 input; if this flag is set then the data will instead be written into
10781 .Cd x-mailx-tmpfile .
10782 In order to cause deletion of the temporary file you will have to set
10783 .Cd x-mailx-tmpfile-unlink
10785 It is an error to use this flag with commands that include a
10789 .It Cd x-mailx-tmpfile-unlink
10790 Extension flag field that requests that the temporary file shall be
10791 deleted automatically when the command loop is entered again at latest.
10792 (Do not use this for asynchronous handlers.)
10793 It is an error to use this flag with commands that include a
10795 format, or without also setting
10796 .Cd x-mailx-tmpfile
10798 .Cd x-mailx-tmpfile-fill .
10800 .It Cd x-mailx-tmpfile-keep
10803 implies the three tmpfile related flags above, but if you want, e.g.,
10805 and deal with the temporary file yourself, you can add in this flag to
10807 .Cd x-mailx-tmpfile-unlink .
10812 The standard includes the possibility to define any number of additional
10813 entry fields, prefixed by
10815 Flag fields apply to the entire
10817 entry \(em in some unusual cases, this may not be desirable, but
10818 differentiation can be accomplished via separate entries, taking
10819 advantage of the fact that subsequent entries are searched if an earlier
10820 one does not provide enough information.
10823 command needs to specify the
10827 command shall not, the following will help out the latter (with enabled
10831 level \*(UA will show information about handler evaluation):
10833 .Bd -literal -offset indent
10834 application/postscript; ps-to-terminal %s; needsterminal
10835 application/postscript; ps-to-terminal %s; compose=idraw %s
10839 In fields any occurrence of the format string
10841 will be replaced by the
10844 Named parameters from the
10846 field may be placed in the command execution line using
10848 followed by the parameter name and a closing
10851 The entire parameter should appear as a single command line argument,
10852 regardless of embedded spaces; thus:
10854 .Bd -literal -offset indent
10856 Content-type: multipart/mixed; boundary=42
10859 multipart/*; /usr/local/bin/showmulti \e
10860 %t %{boundary} ; composetyped = /usr/local/bin/makemulti
10862 # Executed shell command
10863 /usr/local/bin/showmulti multipart/mixed 42
10867 .\" TODO v15: Mailcap: %n,%F
10868 Note that \*(UA does not support handlers for multipart MIME parts as
10869 shown in this example (as of today).
10870 \*(UA does not support the additional formats
10874 An example file, also showing how to properly deal with the expansion of
10876 which includes any quotes that are necessary to make it a valid shell
10877 argument by itself and thus will cause undesired behaviour when placed
10878 in additional user-provided quotes:
10880 .Bd -literal -offset indent
10882 text/richtext; richtext %s; copiousoutput
10884 text/x-perl; perl -cWT %s
10886 application/pdf; \e
10888 trap "rm -f ${infile}" EXIT\e; \e
10889 trap "exit 75" INT QUIT TERM\e; \e
10891 x-mailx-async; x-mailx-tmpfile-keep
10893 application/*; echo "This is \e"%t\e" but \e
10894 is 50 \e% Greek to me" \e; < %s head -c 1024 | cat -vET; \e
10895 copiousoutput; x-mailx-noquote
10900 .Sx "HTML mail and MIME attachments" ,
10901 .Sx "The mime.types files" ,
10904 .Va mime-counter-evidence ,
10905 .Va pipe-TYPE/SUBTYPE ,
10906 .Va pipe-EXTENSION .
10909 .\" .Ss "The .netrc file" {{{
10910 .Ss "The .netrc file"
10914 file contains user credentials for machine accounts.
10915 The default location in the user's
10917 directory may be overridden by the
10919 environment variable.
10920 The file consists of space, tabulator or newline separated tokens.
10921 \*(UA implements a parser that supports a superset of the original BSD
10922 syntax, but users should nonetheless be aware of portability glitches
10923 of that file format, shall their
10925 be usable across multiple programs and platforms:
10928 .Bl -bullet -compact
10930 BSD does not support single, but only double quotation marks, e.g.,
10931 .Ql password="pass with spaces" .
10933 BSD (only?) supports escaping of single characters via a reverse solidus
10934 (e.g., a space can be escaped via
10936 in- as well as outside of a quoted string.
10938 BSD does not require a final quotation mark of the last user input token.
10940 The original BSD (Berknet) parser also supported a format which allowed
10941 tokens to be separated with commas \(en whereas at least Hewlett-Packard
10942 still seems to support this syntax, \*(UA does not!
10944 As a non-portable extension some widely-used programs support
10945 shell-style comments: if an input line starts, after any amount of
10946 whitespace, with a number sign
10948 then the rest of the line is ignored.
10950 Whereas other programs may require that the
10952 file is accessible by only the user if it contains a
10954 token for any other
10958 \*(UA will always require these strict permissions.
10962 Of the following list of supported tokens \*(UA only uses (and caches)
10967 At runtime the command
10969 can be used to control \*(UA's
10973 .Bl -tag -width ".It Cd BaNg"
10974 .It Cd machine Ar name
10975 The hostname of the entries' machine, lowercase-normalized by \*(UA
10977 Any further file content, until either end-of-file or the occurrence
10982 first-class token is bound (only related) to the machine
10985 As an extension that should not be the cause of any worries
10986 \*(UA supports a single wildcard prefix for
10988 .Bd -literal -offset indent
10989 machine *.example.com login USER password PASS
10990 machine pop3.example.com login USER password PASS
10991 machine smtp.example.com login USER password PASS
10997 .Ql pop3.example.com ,
11001 .Ql local.smtp.example.com .
11002 Note that in the example neither
11003 .Ql pop3.example.com
11005 .Ql smtp.example.com
11006 will be matched by the wildcard, since the exact matches take
11007 precedence (it is however faster to specify it the other way around).
11010 This is the same as
11012 except that it is a fallback entry that is used shall none of the
11013 specified machines match; only one default token may be specified,
11014 and it must be the last first-class token.
11016 .It Cd login Ar name
11017 The user name on the remote machine.
11019 .It Cd password Ar string
11020 The user's password on the remote machine.
11022 .It Cd account Ar string
11023 Supply an additional account password.
11024 This is merely for FTP purposes.
11026 .It Cd macdef Ar name
11028 A macro is defined with the specified
11030 it is formed from all lines beginning with the next line and continuing
11031 until a blank line is (consecutive newline characters are) encountered.
11034 entries cannot be utilized by multiple machines, too, but must be
11035 defined following the
11037 they are intended to be used with.)
11040 exists, it is automatically run as the last step of the login process.
11041 This is merely for FTP purposes.
11048 .\" .Sh EXAMPLES {{{
11051 .\" .Ss "An example configuration" {{{
11052 .Ss "An example configuration"
11054 .Bd -literal -offset indent
11055 # This example assumes v15.0 compatibility mode
11058 # Request strict transport security checks!
11059 set ssl-verify=strict
11061 # Where are the up-to-date SSL certificates?
11062 # (Since we manage up-to-date ones explicitly, do not use any,
11063 # possibly outdated, default certificates shipped with OpenSSL)
11064 #set ssl-ca-dir=/etc/ssl/certs
11065 set ssl-ca-file=/etc/ssl/certs/ca-certificates.crt
11066 set ssl-ca-no-defaults
11067 #set ssl-ca-flags=partial-chain
11068 wysh set smime-ca-file="${ssl-ca-file}" \e
11069 smime-ca-no-defaults #smime-ca-flags="${ssl-ca-flags}"
11071 # Do not use protocols older than TLS v1.2.
11072 # Change this only when the remote server does not support it:
11073 # maybe use ssl-protocol-HOST (or -USER@HOST) syntax to define
11074 # such explicit exceptions, then, e.g.
11075 # set ssl-protocol-exam.ple='-ALL,+TLSv1.1'
11076 set ssl-protocol='-ALL,+TLSv1.2'
11078 # Explicitly define the list of ciphers, which may improve security,
11079 # especially with protocols older than TLS v1.2. See ciphers(1).
11080 # Including "@STRENGTH" will sort the final list by algorithm strength.
11081 # In reality it is possibly best to only use ssl-cipher-list-HOST
11082 # (or -USER@HOST), as necessary, again..
11083 set ssl-cipher-list=TLSv1.2:!aNULL:!eNULL:@STRENGTH
11084 # TLSv1.2:!aNULL:!eNULL:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:\e
11085 DHE-RSA-AES256-SHA:@STRENGTH
11086 # ALL:!aNULL:!eNULL:!MEDIUM:!LOW:!MD5:!RC4:!EXPORT:@STRENGTH
11088 # Essential setting: select allowed character sets
11089 set sendcharsets=utf-8,iso-8859-1
11091 # A very kind option: when replying to a message, first try to
11092 # use the same encoding that the original poster used herself!
11093 set reply-in-same-charset
11095 # When replying to or forwarding a message the comment and name
11096 # parts of email addresses are removed unless this variable is set
11099 # When sending messages, wait until the Mail-Transfer-Agent finishs.
11100 # Only like this you will be able to see errors reported through the
11101 # exit status of the MTA (including the builtin SMTP one)!
11104 # Only use builtin MIME types, no mime.types(5) files
11105 set mimetypes-load-control
11107 # Default directory where we act in (relative to $HOME)
11109 # A leading "+" (often) means: under *folder*
11110 # *record* is used to save copies of sent messages
11111 set MBOX=+mbox.mbox record=+sent.mbox DEAD=+dead.txt
11113 # Make "file mymbox" and "file myrec" go to..
11114 shortcut mymbox %:+mbox.mbox myrec +sent.mbox
11116 # Not really optional, e.g., for S/MIME
11117 set from='Your Name <address@exam.ple>'
11119 # It may be necessary to set hostname and/or smtp-hostname
11120 # if the "SERVER" of mta and "domain" of from do not match.
11121 # The `urlencode' command can be used to encode USER and PASS
11122 set mta=(smtps?|submission)://[USER[:PASS]@]SERVER[:PORT] \e
11123 smtp-auth=login/plain... \e
11126 # Never refuse to start into interactive mode, and more
11128 colour-pager crt= \e
11129 followup-to followup-to-honour=ask-yes \e
11130 history-file=+.\*(uAhist history-size=-1 history-gabby \e
11131 mime-counter-evidence=0xE \e
11132 prompt='?\e?!\e![\e${-account}#\e${-mailbox-display}]? ' \e
11133 reply-to-honour=ask-yes \e
11136 # Only include the selected header fields when typing messages
11137 headerpick type retain add from_ date from to cc subject \e
11138 message-id mail-followup-to reply-to
11139 # ...when forwarding messages
11140 headerpick forward retain add subject date from to cc
11141 # ...when saving message, etc.
11142 #headerpick save ignore add ^Original-.*$ ^X-.*$
11144 # Some mailing lists
11145 mlist '@xyz-editor\e.xyz$' '@xyzf\e.xyz$'
11146 mlsubscribe '^xfans@xfans\e.xyz$'
11148 # A real life example of a very huge free mail provider
11150 set folder=~/spool/XooglX inbox=+syste.mbox sent=+sent
11151 set from='Your Name <address@examp.ple>'
11152 set mta=smtp://USER:PASS@smtp.gmXil.com smtp-use-starttls
11155 # Here is a pretty large one which does not allow sending mails
11156 # if there is a domain name mismatch on the SMTP protocol level,
11157 # which would bite us if the value of from does not match, e.g.,
11158 # for people who have a sXXXXeforge project and want to speak
11159 # with the mailing list under their project account (in from),
11160 # still sending the message through their normal mail provider
11162 set folder=~/spool/XandeX inbox=+syste.mbox sent=+sent
11163 set from='Your Name <address@exam.ple>'
11164 set mta=smtps://USER:PASS@smtp.yaXXex.ru:465 \e
11165 hostname=yaXXex.com smtp-hostname=
11168 # Create some new commands so that, e.g., `ls /tmp' will..
11169 wysh ghost lls '!ls ${LS_COLOR_FLAG} -aFlrS'
11170 wysh ghost llS '!ls ${LS_COLOR_FLAG} -aFlS'
11171 wysh ghost ls '!ls ${LS_COLOR_FLAG} -aFrS'
11172 wysh ghost lS '!ls ${LS_COLOR_FLAG} -aFS'
11173 wysh ghost lla '!ls ${LS_COLOR_FLAG} -aFlr'
11174 wysh ghost llA '!ls ${LS_COLOR_FLAG} -aFl'
11175 wysh ghost la '!ls ${LS_COLOR_FLAG} -aFr'
11176 wysh ghost lA '!ls ${LS_COLOR_FLAG} -aF'
11177 wysh ghost ll '!ls ${LS_COLOR_FLAG} -aFltr'
11178 wysh ghost lL '!ls ${LS_COLOR_FLAG} -aFlt'
11179 wysh ghost l '!ls ${LS_COLOR_FLAG} -aFtr'
11180 wysh ghost L '!ls ${LS_COLOR_FLAG} -aFt'
11182 # We do not support gpg(1) directly yet. But simple --clearsign'd
11183 # message parts can be dealt with as follows:
11186 wysh set pipe-text/plain=$'@*#++=@\e
11187 < "${MAILX_FILENAME_TEMPORARY}" awk \e
11188 -v TMPFILE="${MAILX_FILENAME_TEMPORARY}" \e'\e
11190 /^-----BEGIN PGP SIGNED MESSAGE-----/,/^$/ {\e
11193 print "--- GPG --verify ---";\e
11194 system("gpg --verify " TMPFILE " 2>&1");\e
11195 print "--- GPG --verify ---";\e
11199 /^-----BEGIN PGP SIGNATURE-----/,\e
11200 /^-----END PGP SIGNATURE-----/{\e
11210 !printf 'Key IDs to gpg --recv-keys: ';\e
11212 gpg --recv-keys ${keyids};
11218 When storing passwords in
11220 appropriate permissions should be set on this file with
11221 .Ql $ chmod 0600 \*(ur .
11224 is available user credentials can be stored in the central
11226 file instead; e.g., here is a different version of the example account
11227 that sets up SMTP and POP3:
11229 .Bd -literal -offset indent
11234 set folder=~/spool/XandeX inbox=+syste.mbox sent=+sent
11235 set from='Your Name <address@exam.ple>'
11237 # Load an encrypted ~/.netrc by uncommenting the next line
11238 #set netrc-pipe='gpg -qd ~/.netrc.pgp'
11240 set mta=smtps://smtp.yXXXXx.ru:465 \e
11241 smtp-hostname= hostname=yXXXXx.com
11242 set pop3-keepalive=240 pop3-no-apop-pop.yXXXXx.ru
11243 ghost xp fi pop3s://pop.yXXXXx.ru
11252 .Bd -literal -offset indent
11253 machine *.yXXXXx.ru login USER password PASS
11257 This configuration should now work just fine:
11260 .Dl $ echo text | \*(uA -vv -AXandeX -s Subject user@exam.ple
11263 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
11264 .Ss "Signed and encrypted messages with S/MIME"
11266 \*(OP S/MIME provides two central mechanisms:
11267 message signing and message encryption.
11268 A signed message contains some data in addition to the regular text.
11269 The data can be used to verify that the message was sent using a valid
11270 certificate, that the sender's address in the message header matches
11271 that in the certificate, and that the message text has not been altered.
11272 Signing a message does not change its regular text;
11273 it can be read regardless of whether the recipient's software is able to
11277 It is thus usually possible to sign all outgoing messages if so desired.
11278 Encryption, in contrast, makes the message text invisible for all people
11279 except those who have access to the secret decryption key.
11280 To encrypt a message, the specific recipient's public encryption key
11282 It is therefore not possible to send encrypted mail to people unless their
11283 key has been retrieved from either previous communication or public key
11285 A message should always be signed before it is encrypted.
11286 Otherwise, it is still possible that the encrypted message text is
11290 A central concept to S/MIME is that of the certification authority (CA).
11291 A CA is a trusted institution that issues certificates.
11292 For each of these certificates it can be verified that it really
11293 originates from the CA, provided that the CA's own certificate is
11295 A set of CA certificates is usually delivered with OpenSSL and installed
11297 If you trust the source of your OpenSSL software installation,
11298 this offers reasonable security for S/MIME on the Internet.
11300 .Va smime-ca-no-defaults
11301 to avoid using the default certificate and point
11305 to a trusted pool of certificates.
11306 In general, a certificate cannot be more secure than the method its CA
11307 certificate has been retrieved with.
11310 The first thing you need for participating in S/MIME message exchange is
11311 your personal certificate, including a private key.
11312 The certificate contains public information, in particular your name and
11313 your email address(es), and the public key that is used by others to
11314 encrypt messages for you,
11315 and to verify signed messages they supposedly received from you.
11316 The certificate is included in each signed message you send.
11317 The private key must be kept secret.
11318 It is used to decrypt messages that were previously encrypted with your
11319 public key, and to sign messages.
11322 For personal use it is recommended that you get a S/MIME certificate
11323 from one of the major CAs on the Internet using your WWW browser.
11324 Many CAs offer such certificates for free.
11326 .Lk https://www.CAcert.org
11327 which issues client and server certificates to members of their
11328 community for free; their root certificate
11329 .Pf ( Lk https://\:www.cacert.org/\:certs/\:root.crt )
11330 is often not in the default set of trusted CA root certificates, though,
11331 which means you will have to download their root certificate separately
11332 and ensure it is part of our S/MIME certificate validation chain by
11335 or as a vivid member of the
11336 .Va smime-ca-file .
11337 But let us take a step-by-step tour on how to setup S/MIME with
11338 a certificate from CAcert.org despite this situation!
11341 First of all you will have to become a member of the CAcert.org
11342 community, simply by registrating yourself via the web interface.
11343 Once you are, create and verify all email addresses you want to be able
11344 to create signed and encrypted messages for/with using the corresponding
11345 entries of the web interface.
11346 Now ready to create S/MIME certificates, so let us create a new
11347 .Dq client certificate ,
11348 ensure to include all email addresses that should be covered by the
11349 certificate in the following web form, and also to use your name as the
11353 Create a private key and a certificate request on your local computer
11354 (please see the manual pages of the used commands for more in-depth
11355 knowledge on what the used arguments etc. do):
11358 .Dl openssl req -nodes -newkey rsa:4096 -keyout key.pem -out creq.pem
11361 Afterwards copy-and-paste the content of
11363 into the certificate-request (CSR) field of the web form on the
11364 CAcert.org website (you may need to unfold some
11365 .Dq advanced options
11366 to see the corresponding text field).
11367 This last step will ensure that your private key (which never left your
11368 box) and the certificate belong together (through the public key that
11369 will find its way into the certificate via the certificate-request).
11370 You are now ready and can create your CAcert certified certificate.
11371 Download and store or copy-and-paste it as
11376 In order to use your new S/MIME setup a combined private key/public key
11377 (certificate) file has to be created:
11380 .Dl cat key.pem pub.crt > ME@HERE.com.paired
11383 This is the file \*(UA will work with.
11384 If you have created your private key with a passphrase then \*(UA will
11385 ask you for it whenever a message is signed or decrypted.
11386 Set the following variables to henceforth use S/MIME (setting
11388 is of interest for verification only):
11390 .Bd -literal -offset indent
11391 set smime-ca-file=ALL-TRUSTED-ROOT-CERTS-HERE \e
11392 smime-sign-cert=ME@HERE.com.paired \e
11393 smime-sign-message-digest=SHA256 \e
11398 From each signed message you send, the recipient can fetch your
11399 certificate and use it to send encrypted mail back to you.
11400 Accordingly if somebody sends you a signed message, you can do the same,
11403 command to check the validity of the certificate.
11406 Variables of interest for S/MIME signing:
11408 .Va smime-ca-file ,
11409 .Va smime-ca-flags ,
11410 .Va smime-ca-no-defaults ,
11411 .Va smime-crl-dir ,
11412 .Va smime-crl-file ,
11414 .Va smime-sign-cert ,
11415 .Va smime-sign-include-certs
11417 .Va smime-sign-message-digest .
11420 After it has been verified save the certificate via
11422 and tell \*(UA that it should use it for encryption for further
11423 communication with that somebody:
11425 .Bd -literal -offset indent
11427 set smime-encrypt-USER@HOST=FILENAME \e
11428 smime-cipher-USER@HOST=AES256
11432 Additional variables of interest for S/MIME en- and decryption:
11435 .Va smime-encrypt-USER@HOST .
11438 You should carefully consider if you prefer to store encrypted messages
11440 If you do, anybody who has access to your mail folders can read them,
11441 but if you do not, you might be unable to read them yourself later if
11442 you happen to lose your private key.
11445 command saves messages in decrypted form, while the
11449 commands leave them encrypted.
11452 Note that neither S/MIME signing nor encryption applies to message
11453 subjects or other header fields yet.
11454 Thus they may not contain sensitive information for encrypted messages,
11455 and cannot be trusted even if the message content has been verified.
11456 When sending signed messages,
11457 it is recommended to repeat any important header information in the
11461 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
11462 .Ss "Using CRLs with S/MIME or SSL/TLS"
11464 \*(OP Certification authorities (CAs) issue certificate revocation
11465 lists (CRLs) on a regular basis.
11466 These lists contain the serial numbers of certificates that have been
11467 declared invalid after they have been issued.
11468 Such usually happens because the private key for the certificate has
11470 because the owner of the certificate has left the organization that is
11471 mentioned in the certificate, etc.
11472 To seriously use S/MIME or SSL/TLS verification,
11473 an up-to-date CRL is required for each trusted CA.
11474 There is otherwise no method to distinguish between valid and
11475 invalidated certificates.
11476 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
11477 the Internet, so they have to be retrieved by some external mechanism.
11480 \*(UA accepts CRLs in PEM format only;
11481 CRLs in DER format must be converted, like, e.\|g.:
11484 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
11487 To tell \*(UA about the CRLs, a directory that contains all CRL files
11488 (and no other files) must be created.
11493 variables, respectively, must then be set to point to that directory.
11494 After that, \*(UA requires a CRL to be present for each CA that is used
11495 to verify a certificate.
11498 .\" .Ss "Handling spam" {{{
11499 .Ss "Handling spam"
11501 \*(OP \*(UA can make use of several spam interfaces for the purpose of
11502 identification of, and, in general, dealing with spam messages.
11503 A precondition of most commands in order to function is that the
11505 variable is set to one of the supported interfaces.
11506 Once messages have been identified as spam their (volatile)
11508 state can be prompted: the
11512 message specifications will address respective messages and their
11514 entries will be used when displaying the
11516 in the header display.
11521 rates the given messages and sets their
11524 If the spam interface offers spam scores those can also be displayed in
11525 the header display by including the
11535 will interact with the Bayesian filter of the chosen interface and learn
11536 the given messages as
11540 respectively; the last command can be used to cause
11542 of messages; it adheres to their current
11544 state and thus reverts previous teachings.
11549 will simply set and clear, respectively, the mentioned volatile
11551 message flag, without any interface interaction.
11560 requires a running instance of the
11562 server in order to function, started with the option
11564 shall Bayesian filter learning be possible.
11566 .Bd -literal -offset indent
11567 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
11568 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \e
11569 --daemonize [--local] [--allow-tell]
11573 Thereafter \*(UA can make use of these interfaces:
11575 .Bd -literal -offset indent
11576 $ \*(uA -Sspam-interface=spamc -Sspam-maxsize=500000 \e
11577 -Sspamc-command=/usr/local/bin/spamc \e
11578 -Sspamc-arguments="-U /tmp/.spamsock" -Sspamc-user=
11580 $ \*(uA -Sspam-interface=spamc -Sspam-maxsize=500000 \e
11581 -Sspamc-command=/usr/local/bin/spamc \e
11582 -Sspamc-arguments="-d localhost -p 2142" -Sspamc-user=
11586 Using the generic filter approach allows usage of programs like
11588 Here is an example, requiring it to be accessible via
11591 .Bd -literal -offset indent
11592 $ \*(uA -Sspam-interface=filter -Sspam-maxsize=500000 \e
11593 -Sspamfilter-ham="bogofilter -n" \e
11594 -Sspamfilter-noham="bogofilter -N" \e
11595 -Sspamfilter-nospam="bogofilter -S" \e
11596 -Sspamfilter-rate="bogofilter -TTu 2>/dev/null" \e
11597 -Sspamfilter-spam="bogofilter -s" \e
11598 -Sspamfilter-rate-scanscore="1;^(.+)$"
11602 Because messages must exist on local storage in order to be scored (or
11603 used for Bayesian filter training), it is possibly a good idea to
11604 perform the local spam check last:
11606 .Bd -literal -offset indent
11607 define spamdelhook {
11609 spamset (header x-dcc-brand-metrics "bulk")
11610 # Server-side spamassassin(1)
11611 spamset (header x-spam-flag "YES")
11612 del :s # TODO we HAVE to be able to do `spamrate :u ! :sS'
11613 move :S +maybe-spam
11616 move :S +maybe-spam
11618 set folder-hook-FOLDER=spamdelhook
11622 See also the documentation for the variables
11623 .Va spam-interface , spam-maxsize ,
11624 .Va spamc-command , spamc-arguments , spamc-user ,
11625 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
11628 .Va spamfilter-rate-scanscore .
11636 In general it is a good idea to turn on
11642 twice) if something does not work well.
11643 Very often a diagnostic message can be produced that leads to the
11644 problems' solution.
11646 .\" .Ss "\*(UA shortly hangs on startup" {{{
11647 .Ss "\*(UA shortly hangs on startup"
11649 This can have two reasons, one is the necessity to wait for a file lock
11650 and cannot be helped, the other being that \*(UA calls the function
11652 in order to query the nodename of the box (sometimes the real one is
11653 needed instead of the one represented by the internal variable
11655 One may have varying success by ensuring that the real hostname and
11659 or, more generally, that the name service is properly setup \(en
11662 return the expected value?
11663 Does this local hostname has a domain suffix?
11664 RFC 6762 standardized the link-local top-level domain
11666 try again after adding an (additional) entry with this extension.
11669 .\" .Ss "\*(UA exits quick, and output is cleared away" {{{
11670 .Ss "\*(UA exits quick, and output is cleared away"
11672 When this happens even with
11674 set, then this most likely indicates a problem with the creation of
11675 so-called dotlock files: setting
11676 .Va dotlock-ignore-error
11677 should overcome this situation.
11678 This only avoids symptoms, it does not address the problem, though.
11679 Since the output is cleared away \*(UA has support for
11680 .Sx "On terminal control and line editor" ,
11681 and switches to the
11683 which causes the output clearance: by doing
11684 .Ql set termcap='smcup='
11685 this mode can be suppressed, and by setting
11687 (twice) the actual problem should be reported.
11690 .\" .Ss "I cannot login to Google mail aka GMail" {{{
11691 .Ss "I cannot login to Google mail aka GMail"
11693 Since 2014 some free service providers classify programs as
11695 unless they use a special authentification method (OAuth 2.0) which
11696 was not standardized for non-HTTP protocol authentication token query
11697 until August 2015 (RFC 7628).
11700 Different to Kerberos / GSSAPI, which is developed since the mid of the
11701 1980s, where a user can easily create a local authentication ticket for
11702 her- and himself with the locally installed
11704 program, that protocol has no such local part but instead requires
11705 a world-wide-web query to create or fetch a token; since there is no
11706 local cache this query would have to be performed whenever \*(UA is
11707 invoked (in interactive sessions situation may differ).
11710 \*(UA does not support OAuth.
11711 Because of this it is necessary to declare \*(UA a
11712 .Dq less secure app
11713 (on the providers account web page) in order to read and send mail.
11714 However, it also seems possible to take the following steps instead:
11719 give the provider the number of a mobile phone,
11722 .Dq 2-Step Verification ,
11724 create an application specific password (16 characters), and
11726 use that special password instead of the real Google account password in
11727 \*(UA (for more on that see the section
11728 .Sx "On URL syntax and credential lookup" ) .
11732 .\" .Ss "Not \(dqdefunctional\(dq, but the editor key does not work" {{{
11733 .Ss "Not \(dqdefunctional\(dq, but the editor key does not work"
11735 It can happen that the terminal library (see
11736 .Sx "On terminal control and line editor",
11739 reports different codes than the terminal really sends, in which case
11740 \*(UA will tell that a key binding is functional, but will not be able to
11741 recognize it because the received data does not match anything expected.
11746 ings will show the byte sequences that are expected.
11749 To overcome the situation, use, e.g., the program
11751 in conjunction with the command line option
11753 if available, to see the byte sequences which are actually produced
11754 by keypresses, and use the variable
11756 to make \*(UA aware of them.
11757 E.g., the terminal this is typed on produces some false sequences, here
11758 an example showing the shifted home key:
11760 .Bd -literal -offset indent
11763 # 1B 5B=[ 31=1 3B=; 32=2 48=H
11768 ? \*(uA -v -Stermcap='kHOM=\eE[H'
11777 .\" .Sh "SEE ALSO" {{{
11787 .Xr spamassassin 1 ,
11796 .Xr mailwrapper 8 ,
11801 .\" .Sh HISTORY {{{
11804 M. Douglas McIlroy writes in his article
11805 .Dq A Research UNIX Reader: Annotated Excerpts \
11806 from the Programmer's Manual, 1971-1986
11809 command already appeared in First Edition
11813 .Bd -ragged -offset indent
11814 Electronic mail was there from the start.
11815 Never satisfied with its exact behavior, everybody touched it at one
11816 time or another: to assure the safety of simultaneous access, to improve
11817 privacy, to survive crashes, to exploit uucp, to screen out foreign
11818 freeloaders, or whatever.
11819 Not until v7 did the interface change (Thompson).
11820 Later, as mail became global in its reach, Dave Presotto took charge and
11821 brought order to communications with a grab-bag of external networks
11827 Mail was written in 1978 by Kurt Shoens and developed as part of the
11830 distribution until 1995.
11831 Mail has then seen further development in open source
11833 variants, noticeably by Christos Zoulas in
11835 Based upon this Nail, later Heirloom Mailx, was developed by Gunnar
11836 Ritter in the years 2000 until 2008.
11837 Since 2012 S-nail is maintained by Steffen (Daode) Nurpmeso.
11838 This man page is derived from
11839 .Dq The Mail Reference Manual
11840 that was originally written by Kurt Shoens.
11846 .An "Kurt Shoens" ,
11847 .An "Edward Wang" ,
11848 .An "Keith Bostic" ,
11849 .An "Christos Zoulas" ,
11850 .An "Gunnar Ritter" ,
11851 .An "Steffen Nurpmeso" Aq Mt s-nail-users@lists.sourceforge.net
11853 .Mt s-mailx@sdaoden.eu ) .
11856 .\" .Sh CAVEATS {{{
11859 \*(ID Interrupting an operation via
11863 is often problematic: many library functions cannot deal with the
11865 that this software (still) performs.
11868 The SMTP and POP3 protocol support of \*(UA is very basic.
11869 Also, if it fails to contact its upstream SMTP server, it will not make
11870 further attempts to transfer the message at a later time (setting
11875 If this is a concern, it might be better to set up a local SMTP server
11876 that is capable of message queuing.
11882 After deleting some message of a POP3 mailbox the header summary falsely
11883 claims that there are no messages to display, one needs to perform
11884 a scroll or dot movement to restore proper state.
11886 In threaded display a power user may encounter crashes very
11887 occasionally (this is may and very).
11891 in the source repository lists future directions.