nail.1: use -v option to cat(1) if available (Thomas Dickey)
[s-mailx.git] / nail.1
blob27232a613b7181bb497387db5308a79e52f3ce99
1 .\"@ nail.1 - S-nail(1) reference manual.
2 .\"
3 .\" Copyright (c) 1980, 1990, 1993
4 .\"     The Regents of the University of California.  All rights reserved.
5 .\" Copyright (c) 2000
6 .\"     Gunnar Ritter.  All rights reserved.
7 .\" Copyright (c) 2012 - 2015 Steffen (Daode) Nurpmeso <sdaoden@users.sf.net>.
8 .\"
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
11 .\" are met:
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. All advertising materials mentioning features or use of this software
18 .\"    must display the following acknowledgement:
19 .\"     This product includes software developed by the University of
20 .\"     California, Berkeley and its contributors.
21 .\"     This product includes software developed by Gunnar Ritter
22 .\"     and his contributors.
23 .\"
24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS 'AS IS' AND
25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
34 .\" SUCH DAMAGE.
35 .\"
36 .\"--MKREL-START--
37 .\" S-nail(1): v14.8.10 / 2016-08-20
38 .Dd Aug 20, 2016
39 .ds VV \\%v14.8.10
40 .\"--MKREL-END--
41 .\"--MKMAN-START--
42 .ds UU \\%S-NAIL
43 .ds UA \\%S-nail
44 .ds ua \\%s-nail
45 .ds UR \\%s-nail.rc
46 .\"--MKMAN-END--
47 .\" --BEGINSTRIP--
48 .\"
49 .\" If not ~/.mailrc, it breaks POSIX compatibility.  And adjust main.c.
50 .ds ur \\%~/.mailrc
51 .ds OB [Obsolete]
52 .ds OP [Option]
53 .ds IN [v15-compat]
54 .ds OU [no v15-compat]
55 .ds ID [v15 behaviour may differ]
56 .ds BO (Boolean)
57 .ds RO (Read-only)
59 .Dt "\*(UU" 1
60 .Os
61 .Mx -enable
64 .Sh NAME
65 .Nm \*(UA \%[\*(VV]
66 .Nd send and receive Internet mail
69 .\" .Sh SYNOPSIS {{{
70 .Sh SYNOPSIS
72 .Nm \*(ua
73 .Fl h | Fl Fl help
74 .Nm \*(ua
75 .Bk -words
76 .Op Fl BdEFintv~
77 .Op Fl \&: Ar spec
78 .Op Fl A Ar account
79 .Op Fl a Ar attachment
80 .Op Fl b Ar bcc-addr
81 .Op Fl c Ar cc-addr
82 .Op Fl q Ar quote-file
83 .Op Fl r Ar from-addr
84 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
85 .Op Fl s Ar subject
86 .Op Fl X Ar cmd
87 .Op Fl \&.
88 .Ar to-addr ...
89 .Op Fl Fl \~ Ns Ar mta-option ...
90 .Ek
91 .Nm \*(ua
92 .Bk -words
93 .Op Fl BdEeHiNnRv~#
94 .Op Fl \&: Ar spec
95 .Op Fl A Ar account
96 .Op Fl L Ar spec-list
97 .Op Fl r Ar from-addr
98 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
99 .Op Fl X Ar cmd
100 .Fl f Op Ar file
101 .Op Fl Fl \~ Ns Ar mta-option ...
103 .Nm \*(ua
104 .Bk -words
105 .Op Fl BdEeHiNnRv~#
106 .Op Fl \&: Ar spec
107 .Op Fl A Ar account
108 .Op Fl L Ar spec-list
109 .Op Fl r Ar from-addr
110 .Op Fl S Ar variable Ns Op Ns = Ns Ar value
111 .Op Fl u Ar user
112 .Op Fl X Ar cmd
113 .Op Fl Fl \~ Ns Ar mta-option ...
115 .\" }}}
118 .Mx -toc -tree html pdf ps xhtml
121 .\" .Sh DESCRIPTION {{{
122 .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 A partial set of compatibility options exist, tagged as \*(IN and \*(OU,
128 yet complete compatibility won't be possible.
129 To choose upward compatible behaviour, please set the internal variable
130 .Va v15-compat .
131 Anything which will vanish in v15.0 is tagged \*(OB, and using
132 .Fl d
133 will print warnings for many use cases of obsolete features.
137 \*(UA is a mail processing system with a command syntax reminiscent of
138 .Xr ed 1
139 with lines replaced by messages.
140 It is intended to provide the functionality of the POSIX
141 .Xr mailx 1
142 command, but is MIME capable and optionally offers extensions for
143 line editing, S/MIME, SMTP and POP3 among others.
144 It is usable as a mail batch language.
146 .\" .Ss "Options" {{{
147 .Ss "Options"
149 .Bl -tag -width ".Fl _ Ar _ccount"
151 .It Fl \&: Ar spec
152 Explicitly control which of the
153 .Sx "Resource files"
154 shall be loaded: if the letter
155 .Ql s
156 is (case-insensitively) part of the
157 .Ar spec
158 then the system wide
159 .Pa \*(UR
160 is loaded, likewise the letter
161 .Ql u
162 controls loading of the user's personal
163 .Pa \*(ur
164 file, whereas the letters
165 .Ql -
167 .Ql /
168 explicitly forbid loading of any resource files.
169 This option should be used by scripts: to avoid environmental noise they
170 should
171 .Dq detach
172 from any configuration files and create a script-local environment,
173 explicitly setting any desired variable via
174 .Fl S .
175 This option overrides
176 .Fl n .
179 .It Fl A Ar account
180 Executes an
181 .Ic account
182 command (see below) for
183 .Ar account
184 after the startup files have been read.
187 .It Fl a Ar file
188 Attach the given file to the message.
189 The same filename conventions as described in the section
190 .Sx COMMANDS
191 apply: shell word expansion is restricted to the tilde
192 .Ql ~
193 and variables.
194 Shall
195 .Ar file
196 not be accessible but contain a
197 .Ql =
198 character, then anything after the
199 .Ql =
200 is assumed to specify the input character set and anything before
201 .Ql =
202 the filename: this is the only option to specify the input character set
203 (and don't perform any character set conversion) for text attachments
204 from the command line, not using the
205 .Ic ~@
206 tilde escape command.
209 .It Fl B
210 Make standard input and standard output line-buffered.
213 .It Fl b Ar address
214 Send a blind carbon copy to
215 .Ar address .
216 Can be used multiple times, but it is also possible to give
217 a comma-separated list of receivers in a single argument, proper shell
218 quoting provided, e.g.,
219 .Ql -b """qrec1  ,  rec2,rec3, Ex <am@ple>""" .
220 Also see the section
221 .Sx "On sending mail, and non-interactive mode" .
224 .It Fl c Ar address
225 Send carbon copies to the given receiver(s).
226 Can be used multiple times.
229 .It Fl d
230 Sets the
231 .Va debug
232 variable which enables debug messages and disables message delivery,
233 among others; effectively turns almost any operation into a dry-run.
236 .It Fl E
237 Set the
238 .Va skipemptybody
239 variable and thus discard messages with an empty message part body.
240 This is useful for sending messages from scripts.
243 .It Fl e
244 Just check if mail is present (in the specified or system mailbox).
245 If yes, return an exit status of zero, a non-zero value otherwise.
246 To restrict the set of mails to consider in this evaluation a message
247 specification can be added with the option
248 .Fl L .
251 .It Fl F
252 Save the message to send in a file named after the local part of the
253 first recipient's address (instead of in
254 .Va record Ns ).
257 .It Fl f Op Ar file
258 Read in the contents of the user's
259 .Ev MBOX
260 (or the specified file) for processing;
261 when \*(UA is quit, it writes undeleted messages back to this file
262 (but be aware of the
263 .Va hold
264 option).
265 Some special conventions are recognized for the string
266 .Ar file
267 which are documented for the
268 .Ic file
269 command below.
270 Note that
271 .Ar file
272 is not a direct argument to the flag
273 .Fl f ,
274 but is instead taken from the command line after option processing has
275 been completed.
276 In order to use a
277 .Ar file
278 that starts with a hyphen, prefix it with a (relative) path, as in
279 .Ql ./-hyphenbox.mbox .
282 .It Fl H
283 Display a summary of the
284 .Ic headers
285 of all messages in the specified or system mailbox and exit.
286 A configurable summary view is available via the
287 .Fl L
288 option.
291 .It Fl h
292 Show a short usage summary.
293 Because of widespread use a
294 .Fl Fl help
295 argument will have the same effect.
298 .It Fl i
299 Set the
300 .Va ignore
301 variable to ignore tty interrupt signals.
304 .It Fl L Ar spec-list
305 Display a summary of all
306 .Ic headers
307 of only those messages in the specified or system mailbox that match the
308 given
309 .Ar spec-list ,
310 then exit.
311 See the section
312 .Sx "Specifying messages"
313 for the format of
314 .Ar spec-list .
315 If the
316 .Fl e
317 (\*(OB or
318 .Fl H )
319 option has been given in addition no header summary is produced,
320 but \*(UA will instead indicate via its exit status wether
321 .Ar spec-list
322 matched any messages
323 .Pf ( Ql 0 )
324 or not
325 .Pf ( Ql 1 ) ;
326 note that any verbose output is suppressed in this mode and must instead
327 be enabled explicitly (e.g., by using the option
328 .Fl v ) .
331 .It Fl N
332 Unset the
333 .Va header
334 variable and thus inhibit initial display of message headers when
335 reading mail or editing a mail folder.
338 .It Fl n
339 Standard flag that inhibits reading the system wide
340 .Pa \*(UR
341 upon startup.
342 The option
343 .Fl \&:
344 allows more control over the startup sequence; also see
345 .Sx "Resource files" .
348 .It Fl q Ar file
349 Initialize the message body with the contents of the specified file,
350 which may be standard input
351 .Ql -
352 only in non-interactive context.
353 May be given in send mode only.
356 .It Fl R
357 Any folder opened will be in read-only mode.
360 .It Fl r Ar address
362 .Ar address
363 is a valid address then it specifies the envelope sender address to be
364 passed to the MTA as
365 .Ql -f Ar address
366 when a message is send.
367 Shall
368 .Ar address
369 include a user name, comments etc., then the components will be
370 separated and the name part will be passed to the MTA individually via
371 .Ql -F Ar name .
372 The given
373 .Ar address
374 will also be assigned to the
375 .Va from
376 variable, just as if additionally
377 .Ql -Sfrom=address
378 had been specified (therefore affecting SMTP data transfer, too).
380 If instead an empty string is passed as
381 .Ar address
382 then the content of the variable
383 .Va from
384 will be evaluated and used for this purpose whenever the MTA is
385 contacted.
386 Note that \*(UA by default, without
387 .Fl \&\&r
388 that is, neither passes
389 .Ql -f
391 .Ql -F
392 flags to the MTA by itself.
395 .It Fl S Ar variable Ns Op = Ns value
396 Sets the internal option
397 .Ar variable
398 and, in case of a value option, assigns
399 .Ar value
400 to it.
401 Even though variables set via
402 .Fl S
403 may be overwritten from within resource files,
404 the command line setting will be reestablished after all resource files
405 have been loaded.
408 .It Fl s Ar subject
409 Specify the subject of the to-be-sent message.
412 .It Fl t
413 The message given (on standard input) is expected to contain, separated
414 from the message body with an empty line, a message header with
415 .Ql To: ,
416 .Ql Cc: ,
418 .Ql Bcc:
419 fields giving its recipients, which will be added to those given on the
420 command line.
421 If a message subject is specified via
422 .Ql Subject:
423 then it'll be used in favour of one given on the command line.
425 Also understood are
426 .Ql Reply-To:
427 (possibly overriding
428 .Va replyto ) ,
429 .Ql Sender:
430 (p.\ o.\&
431 .Va sender ) .
432 Note you can also specify
433 .Ql From: ,
434 possibly overriding
435 .Va from
436 and the envelope address possibly specified with the option
437 .Fl r !
439 The following, which are normally created automatically based
440 upon the message context, can also be specified:
441 .Ql Message-ID: ,
442 .Ql In-Reply-To: ,
443 .Ql References:
445 .Ql Mail-Followup-To:
446 (special address massage will however still occur for the latter).
447 In fact custom header fields may also be used, the content of which
448 is passed through unchanged.
449 In conjunction with
450 .Fl ~
451 .Sx TILDE ESCAPES
452 can be embedded, too.
455 .It Fl u Ar user
456 Read the system mailbox of
457 .Ar user
458 (appropriate privileges presumed), and
459 .Dq assume to be
460 .Ar user
461 in some aspects, e.g. in respect to
462 .Ic file Ns
463 \(enexpansions of
464 .Ql %
465 etc.; also see
466 .Ev LOGNAME .
469 .It Fl V
470 Show \*(UA's version and exit.
473 .It Fl v
474 Setting the
475 .Va verbose
476 option enables display of some informational context messages.
477 Using it twice increases the level of verbosity.
480 .It Fl X Ar cmd
481 Add the given
482 .Ar cmd
483 to the list of commands to be executed before normal operation starts.
484 Correlates with
485 .Fl #
487 .Va batch-exit-on-error ;
488 the only possibility to execute commands in non-interactive mode when
489 reading startup files is actively prohibited.
492 .It Fl ~
493 Enable
494 .Sx TILDE ESCAPES
495 even if not in interactive mode.
498 .It Fl #
499 Enables batch mode.
500 In batch mode the full set of commands is available, just like in
501 interactive mode, and diverse variable settings and internal states are
502 adjusted for batch necessities, e.g., it sets
503 .Va emptystart ,
504 .Pf no Va header ,
505 .Va quiet ,
506 .Va sendwait ,
507 as well as
508 .Ev MBOX
510 .Va folder
511 (both to
512 .Pa /dev/null ) .
513 It also enables processing of
514 .Sx "TILDE ESCAPES" .
515 E.g., the following should send an email message to
516 .Dq bob :
517 .Bd -literal -offset indent
518 $ LC_ALL=C printf 'm bob\en~s ubject\enText\en~.\enx\en' | \e
519   LC_ALL=C \*(ua -:/ -d#
523 .It Fl \&.
524 This flag forces termination of option processing in order to prevent
525 .Dq option injection
526 (attacks).
527 It also forcefully puts \*(UA into send mode, see
528 .Sx "On sending mail, and non-interactive mode" .
532 In the above list of supported command line options,
533 .Fl d , E , i , N
535 .Fl v
536 are implemented by means of setting the respective option, as via
537 .Fl S .
538 .Bk -words
539 .Op Ar mta-option ...
541 arguments that are given at the end of the command line after a
542 .Ql --
543 separator will be passed through to the mail-transfer-agent (MTA) and
544 persist for an entire (interactive) session \(en if the setting of
545 .Va expandargv
546 allows their recognition;
547 MTA arguments can also be specified in the variable
548 .Va sendmail-arguments ;
549 find MTA interaction described in more detail in the documentation of
550 .Va sendmail .
551 MTA arguments are ignored when mail is send via SMTP data transfer.
552 .\" }}}
554 .\" .Ss "A starter" {{{
555 .Ss "A starter"
557 \*(UA is a direct descendant of
559 Mail, a successor of the Research
561 mail which
562 .Dq was there from the start
563 according to
564 .Sx HISTORY .
567 Mail reference manual begins with the following words:
569 .Bd -ragged -offset indent
570 Mail provides a simple and friendly environment for sending and
571 receiving mail.
572 It divides incoming mail into its constituent messages and allows the
573 user to deal with them in any order.
574 In addition, it provides a set of
575 .Xr ed 1 Ns
576 -like commands for manipulating messages and sending mail.
577 Mail offers the user simple editing capabilities to ease the composition
578 of outgoing messages, as well as providing the ability to define and
579 send to names which address groups of users.
583 \*(UA is thus the user side of the
585 mail system, whereas the system side (mail-transfer-agent, MTA) was
586 traditionally taken by
587 .Xr sendmail 8 ;
588 today
589 .Xr postfix 1
591 .Xr exim 8
592 are often used for this purpose instead.
593 If the \*(OPal SMTP is included in the
594 .Ic features
595 of \*(UA then the system side is not a mandatory precondition for mail
596 delivery.
599 Because \*(UA strives for compliance with POSIX
600 .Xr mailx 1
601 it is likely that some configuration settings have to be adjusted before
602 using it is a smooth experience.
603 The default global
604 .Pa \*(UR
605 file already bends those standard settings a bit towards more user
606 friendliness and safety, e.g., it sets the
607 .Va hold
609 .Va keepsave
610 variables in order to suppress the automatic moving of messages to
611 .Ev MBOX
612 that would otherwise occur (see
613 .Sx "Message states" )
615 .Va keep
616 to not remove empty files in order not to mangle file permissions when
617 files eventually get recreated.
618 It does not set the
619 .Va folder
620 option so that by default file grouping (via the
621 .Ql +
622 prefix as documented also for
623 .Ic file )
624 is not enabled.
625 The section
626 .Sx EXAMPLES
627 contains some further suggestions.
628 .\" }}}
630 .\" .Ss "On sending mail, and non-interactive mode" {{{
631 .Ss "On sending mail, and non-interactive mode"
633 To send a message to one or more people, using a local
634 mail-transfer-agent (MTA; the executable path can be set via
635 .Va sendmail )
636 or the \*(OPal builtin SMTP (set and see the variable
637 .Va smtp )
638 transport to actually deliver the generated mail message, \*(UA can be
639 invoked with arguments which are the names of people to whom the mail
640 will be sent:
642 .Bd -literal -offset indent
643 $ \*(ua -s Subject -a attachm.ent bill@host1 'Bob <bob@host2>'
644 # But... try it in an isolated dry-run mode first
645 $ LC_ALL=C \*(ua -:/ -d -vv -Sfrom="me <he@exam.ple>" \e
646     -b bcc@exam.ple -c cc@exam.ple \e
647     -s Subject -. "(Lovely) Bob <bob@host2>"
651 The command line options
652 .Fl b
654 .Fl c
655 can be used to add (blind) carbon copy receivers.
656 Almost always lists of addresses can be given where an address is
657 expected:
658 whereas comma-separated lists should be given, e.g.,
659 .Ql -c """r1@exam.ple ,  r2@exam.ple,r3@exam.ple""" ,
660 that very example could also be given as the whitespace-separated list
661 .Ql -c """r1@exam.ple   r2@exam.ple r3@exam.ple""" ,
662 but which for obvious reasons would not work for
663 .Ql -c """R1 <r1@exam.ple>, R2 (heh!) <r2@exam.ple>""" .
666 The user is then expected to type in the message contents.
667 In this compose mode \*(UA treats lines beginning with the character
668 .Ql ~
669 special \(en these are so-called
670 .Sx "TILDE ESCAPES"
671 which can be used to read in files, process shell commands, add and edit
672 attachments and more; e.g., the tilde escape
673 .Ql Ic ~e
674 will start the text editor to revise the message in it's current state,
675 .Ql Ic ~h
676 allows editing of the message recipients and
677 .Ql Ic ~?
678 gives an overview of available tilde escapes.
679 Typing
680 .Ql control-D
681 .Pf ( Ql ^D )
682 at the beginning of an empty line leaves compose mode and causes the
683 message to be sent, whereas typing
684 .Ql control-C
685 .Pf ( Ql ^C )
686 twice will abort the current letter (saving its contents in the file
687 denoted by
688 .Ev DEAD
689 unless
690 .Pf no Va save
691 is set).
694 A number of variables can be used to alter default behavior; e.g.,
695 .Ic set Ns
696 ting (also via
697 .Fl S )
698 .Va editalong
699 will automatically startup a text editor when compose mode is entered,
700 .Va askcc
701 will cause the user to be prompted actively for carbon-copy recipients
702 and the
703 .Va dot
704 option will allow leaving compose mode by writing a line consisting
705 solely of a dot
706 .Pf ( Ql \&. ) .
709 Very important, though, is to define which
710 .Sx "Character sets"
711 may be used when sending messages, usually by setting the option
712 .Va sendcharsets
713 accordingly,
714 having read the section
715 .Sx "The mime.types files"
716 to understand how the MIME-type of outgoing attachments is classified
717 and the knowledge that messages are sent asynchronously unless
718 .Va sendwait
719 is set: only with it MTA delivery errors will be recognizable.
722 Setting
723 .Va from
724 is often necessary (e.g., in conjunction with
725 .Va smtp )
726 or desirable, you may want to do some dry-run tests before you go.
727 Saving a copy of the sent messages in a
728 .Va record
729 may also be desirable \(en as for most mailbox file targets some
730 special conventions are recognized, see the
731 .Ic file
732 command for more on that.
733 The section
734 .Sx "On URL syntax and credential lookup"
735 will spread some light on the
736 .Ql USER@HOST
737 variable chains as well as on using URLs for accessing protocol-specific
738 resources, like
739 .Va smtp ,
741 .Sx EXAMPLES
742 contains an example configuration for sending messages via some of the
743 well-known public mail providers;
744 note it also gives a compact overview on how to setup a secure SSL/TLS
745 environment.
748 Message recipients (as specified on the command line or defined in
749 .Ql To: ,
750 .Ql Cc:
752 .Ql Bcc: )
753 may not only be email addressees but can also be names of mailboxes and
754 even complete shell command pipe specifications.
755 Proper (shell) quoting is necessary, e.g., to embed whitespace characters.
756 (Recall that \*(UA deals with mail standards, therefore those define the
757 rules with which content is interpreted.)
758 If the variable
759 .Va expandaddr
760 is not set then only network addresses (see
761 .Xr mailaddr 7
762 for a description of mail addresses) and plain user names (including MTA
763 aliases) may be used, other types will be filtered out, giving a warning
764 message.
766 .\" When changing any of the following adjust any RECIPIENTADDRSPEC;
767 .\" grep the latter for the complete picture
769 If the variable
770 .Va expandaddr
771 is set then extended recipient addresses will optionally be accepted:
772 Any name which starts with a vertical bar
773 .Ql |
774 character specifies a command pipe \(en the command string following the
775 .Ql |
776 is executed and the message is sent to its standard input;
777 Likewise, any name that starts with the character slash
778 .Ql /
779 or the character sequence dot slash
780 .Ql ./
781 is treated as a file, regardless of the remaining content.
782 Any other name which contains an at sign
783 .Ql @
784 character is treated as a network address;
785 Any other name which starts with a plus sign
786 .Ql +
787 character specifies a mailbox name;
788 Any other name which contains a slash
789 .Ql /
790 character but no exclamation mark
791 .Ql \&!
792 or percent sign
793 .Ql %
794 character before also specifies a mailbox name;
795 What remains is treated as a network address.
797 .Bd -literal -offset indent
798 $ echo bla | \*(ua -Sexpandaddr -s test ./mbox.mbox
799 $ echo bla | \*(ua -Sexpandaddr -s test '|cat >> ./mbox.mbox'
800 $ echo safe | LC_ALL=C \e
801     \*(ua -:/ -Sv15-compat -Ssendwait -Snosave \e
802       -Sexpandaddr=fail,-all,+addr -s test \e
803       -. bob@home.net
807 It is possible to create personal distribution lists via the
808 .Ic alias
809 command, so that, for instance, the user can send mail to
810 .Ql cohorts
811 and have it go to a group of people:
814 .Dl alias cohorts bill jkf mark kridle@ucbcory ~/mail/cohorts.mbox
817 Please note that this mechanism has nothing in common with the system
818 wide aliases that may be used by the local MTA (mail-transfer-agent),
819 which are subject to the
820 .Ql name
821 constraint of
822 .Va expandaddr
823 and are often tracked in a file
824 .Pa /etc/aliases
825 (and documented in
826 .Xr aliases 5
828 .Xr sendmail 1 ) .
829 Personal aliases will be expanded by \*(UA before the message is sent,
830 and are thus a convenient alternative to specifying each addressee by
831 itself.
834 To avoid environmental noise scripts should
835 .Dq detach
836 \*(UA from any configuration files and create a script-local
837 environment, ideally with the command line options
838 .Fl \&:
839 to disable any configuration file in conjunction with repititions of
840 .Fl S
841 to specify variables:
843 .Bd -literal -offset indent
844 $ env LC_ALL=C password=NOTSECRET \e
845   \*(ua -:/ -Sv15-compat -Ssendwait -Snosave \e
846     -Sexpandaddr=fail,-all,+addr \e
847     -S 'smtp=smtps://mylogin@some.host:465' -Ssmtp-auth=login \e
848     -S 'from=scriptreply@domain' \e
849     -s 'subject' -a attachment_file \e
850     -. "Recipient 1 <recipient1@domain>" recipient2@domain \e
851     < content_file
855 In interactive mode, which is introduced in the next section, messages
856 can be sent by calling the
857 .Ic mail
858 command with a list of recipient addresses \(em the semantics are
859 completely identical to non-interactive message sending, except that
860 it is likely necessary to separate recipient lists with commas:
862 .Bd -literal -offset indent
863 $ \*(ua -d -Squiet -Semptystart
864 "/var/spool/mail/user": 0 messages
865 ? mail "Recipient 1 <recipient1@domain>", recipient2@domain
866 ? # Will do the right thing (tm)
867 ? m recipient1@domain recipient2@domain
869 .\" }}}
871 .\" .Ss "On reading mail, and interactive mode" {{{
872 .Ss "On reading mail, and interactive mode"
874 When invoked without addressees \*(UA enters interactive mode in which
875 mails may be read.
876 When used like that the user's system mailbox (see the command
877 .Ic file
878 for an in-depth description of the different mailbox types that exist)
879 is read in and a one line header of each message therein is displayed.
880 The visual style of this summary of
881 .Ic headers
882 can be adjusted through the variable
883 .Va headline
884 and the possible sorting criterion via
885 .Va autosort .
886 If the initially opened mailbox is empty \*(UA will instead exit
887 immediately (after displaying a message) unless the variable
888 .Va emptystart
889 is set.
892 At the
893 .Va prompt
894 the command
895 .Ic list
896 will give a listing of all available commands and
897 .Ic help
898 will give a summary of some common ones.
899 If the \*(OPal documentation strings are available one can type
900 .Ql ?X
901 and see the actual expansion of
902 .Ql X
903 and what it's purpose is, i.e., commands can be abbreviated
904 (note that POSIX defines some abbreviations, so that the alphabetical
905 order of commands doesn't necessarily relate to the abbreviations; it is
906 possible to define overwrites with the
907 .Ic ghost
908 command, however).
911 Messages are given numbers (starting at 1) which uniquely identify
912 messages; the current message \(en the
913 .Dq dot
914 \(en will either be the first new message, or the first unread message,
915 or the first message of the mailbox; the option
916 .Va showlast
917 will instead cause usage of the last message for this purpose.
918 The command
919 .Ic headers
920 will display a
921 .Va screen Ns
922 ful of header summaries containing the
923 .Dq dot ,
924 whereas
925 .Ic from
926 will display only the summaries of the given messages, defaulting to the
927 .Dq dot .
930 Messages can be displayed on the user's terminal with the
931 .Ic type
932 command, or short:
933 .Ql t .
934 By default the current message
935 .Pf ( Dq dot )
936 is displayed, but like with many other commands it is possible to give
937 a fancy message specification (see
938 .Sx "Specifying messages" ) ,
939 e.g.,
940 .Ql t:u
941 will display all unread messages,
942 .Ql t.
943 will display the
944 .Dq dot ,
945 .Ql t 1 5
946 will type the messages 1 and 5,
947 .Ql t 1-5
948 will type the messages 1 through 5, and
949 .Ql t-
951 .Ql t+
952 will display the last and the next message, respectively.
953 The command
954 .Ic search
955 (a more substantial alias of the standard command
956 .Ic from )
957 will display a header summary of the given message specification list
958 instead of their content, e.g., the following will search for subjects:
961 .Dl ? from """@Some subject to search for"""
964 In the default setup all header fields of a message will be displayed,
965 but this can be changed: either by blacklisting a list of fields via
966 .Ic ignore ,
967 or by whitelisting only a given list with the
968 .Ic retain
969 command, e.g.,
970 .Ql Ic \:retain Ns \0date from to cc subject .
971 In order to display all header fields of a message regardless of
972 currently active ignore or retain lists, use the command
973 .Ic Type .
974 The variable
975 .Va crt
976 controls wether and when \*(UA will use the configured
977 .Ev PAGER
978 for display instead of directly writing to the user terminal
979 (generally speaking).
980 Note that historically the global
981 .Pa \*(UR
982 not only adjusts the list of displayed headers, but also sets
983 .Va crt .
986 Dependent upon the configuration a line editor (see the section
987 .Sx "On terminal control and line editor" )
988 aims at making user experience with the many
989 .Sx COMMANDS
990 a bit nicer.
991 When reading the system mailbox or when
992 .Fl f
994 .Ic file )
995 specified a mailbox explicitly prefixed with the special
996 .Ql %:
997 modifier (propagating the mailbox to a primary one) then messages which
998 have been read will be moved to a secondary mailbox, the user's
999 .Ev MBOX
1000 file, automatically when the mailbox is left, either by changing the
1001 active mailbox or by quitting \*(UA (also see
1002 .Sx "Message states" )
1003 \(en this automatic moving from a system or primary to the secondary
1004 mailbox is not performed when the variable
1005 .Va hold
1006 is set.
1009 After examining a message the user can also
1010 .Ic delete Ql d
1011 the message,
1012 .Ic reply Ql r
1013 to the sender and all recipients or
1014 .Ic Reply Ql R
1015 exclusively to the sender(s).
1016 Messages can also be
1017 .Ic forward Ns
1018 ed (shorter alias is
1019 .Ic fwd Ns ).
1020 Note that when replying to or forwarding a message recipient addresses
1021 will be stripped from comments and names unless the option
1022 .Va fullnames
1023 is set.
1024 Deletion causes \*(UA to forget about the message;
1025 This is not irreversible, though, one can
1026 .Ic undelete Ql u
1027 the message by giving its number,
1028 or the \*(UA session can be ended by giving the
1029 .Ic exit Ql x
1030 command.
1033 To end a mail processing session one may either issue
1034 .Ic quit Ql q
1035 to cause a full program exit, which possibly includes
1036 automatic moving of read messages to
1037 .Ev MBOX
1038 as well as updating the \*(OPal line editor
1039 .Va history-file ,
1040 or use the command
1041 .Ic exit Ql x
1042 instead in order to prevent any of these actions.
1043 .\" }}}
1045 .\" .Ss "HTML mail and MIME attachments" {{{
1046 .Ss "HTML mail and MIME attachments"
1048 Messages which are HTML-only get more and more common and of course many
1049 messages come bundled with a bouquet of MIME attachments.
1050 Whereas \*(UA \*(OPally supports a simple HTML-to-text converter to deal
1051 with HTML messages (see
1052 .Sx "The mime.types files" ) ,
1053 it normally can't deal with any of these itself, but instead programs
1054 need to become registered to deal with specific MIME types or file
1055 extensions.
1056 These programs may either prepare plain text versions of their input
1057 in order to enable \*(UA to display the content on the terminal,
1058 or display the content themselves, for example in a graphical window.
1061 To install an external handler program for a specific MIME type set an
1062 according
1063 .Va pipe-TYPE/SUBTYPE
1064 variable; to instead define a handler for a specific file extension set
1065 the respective
1066 .Va pipe-EXTENSION
1067 variable \(en these handlers take precedence.
1068 \*(OPally \*(UA supports mail user agent configuration as defined in
1069 RFC 1524; this mechanism, documented in the section
1070 .Sx "The Mailcap files" ,
1071 will be queried for display or quote handlers if none of the former two
1072 .\" TODO v15-compat "will be" -> "is"
1073 did; it will be the sole source for handlers of other purpose.
1074 A last source for handlers may be the MIME type definition itself, if
1075 the \*(UA specific type-marker extension was used when defining the type
1076 with the command
1077 .Ic mimetype .
1078 (Many of the builtin MIME types do so by default.)
1081 The variable
1082 .Va mime-counter-evidence
1083 can be set to improve dealing with faulty MIME part declarations as are
1084 often seen in real-life messages.
1085 E.g., to display a HTML message inline (that is, converted to a more
1086 fancy plain text representation than the builtin converter is capable to
1087 produce) with either of the text-mode browsers
1088 .Xr lynx 1
1090 .Xr elinks 1 ,
1091 teach \*(UA about MathML documents and make it display them as plain
1092 text, and to open PDF attachments in an external PDF viewer,
1093 asynchronously and with some other magic attached:
1095 .Bd -literal -offset indent
1096 if $features !@ HTML-FILTER
1097   #set pipe-text/html="elinks -force-html -dump 1"
1098   set pipe-text/html="lynx -stdin -dump -force_html"
1099   # Display HTML as plain text instead
1100   #set pipe-text/html=@
1101 endif
1102 mimetype '@ application/mathml+xml mathml'
1103 set pipe-application/pdf="@&=@ \e
1104   trap \e"rm -f \e\e\e"${NAIL_FILENAME_TEMPORARY}\e\e\e"\e" EXIT;\e
1105   trap \e"trap \e\e\e"\e\e\e" INT QUIT TERM; exit 1\e" \e INT QUIT TERM;\e
1106   xpdf \e"${NAIL_FILENAME_TEMPORARY}\e""
1110 Note: special care must be taken when using such commands as mail
1111 viruses may be distributed by this method: if messages of type
1112 .Ql application/x-sh
1113 or files with the extension
1114 .Ql .sh
1115 were blindly filtered through the shell, for example, a message sender
1116 could easily execute arbitrary code on the system \*(UA is running on.
1117 For more on MIME, also in respect to sending of messages, see the
1118 sections
1119 .Sx "The mime.types files" ,
1120 .Sx "The Mailcap files"
1121 and the command
1122 .Ic mimetype .
1123 .\" }}}
1125 .\" .Ss "Mailing lists" {{{
1126 .Ss "Mailing lists"
1128 \*(UA offers some support to ease handling of mailing lists.
1129 The command
1130 .Ic mlist
1131 promotes all given arguments to known mailing lists, and
1132 .Ic mlsubscribe
1133 sets their subscription attribute, creating them first as necessary.
1134 (On the other hand
1135 .Ic unmlsubscribe
1136 doesn't
1137 .Ic unmlist
1138 automatically, but only resets the subscription attribute.)
1139 Using the commands without arguments will show (a subset of) all
1140 currently defined mailing lists.
1142 .Va headline
1143 format
1144 .Ql \&%T
1145 can be used to mark out messages with configured list addresses
1146 in the header display.
1149 \*(OPally mailing lists may also be specified as (extended) regular
1150 expressions, which allows matching of many addresses with a single
1151 expression.
1152 However, all fully qualified list addresses are matched via a fast
1153 dictionary, whereas expressions are placed in (a) list(s) which is
1154 (are) matched sequentially.
1156 .Bd -literal -offset indent
1157 set followup-to followup-to-honour=ask-yes reply-to-honour=ask-yes
1158 mlist a1@b1.c1 a2@b2.c2 .*@lists.c3$
1159 mlsubscribe a4@b4.c4 exact@lists.c3
1163 The variable
1164 .Va followup-to-honour
1165 will ensure that a
1166 .Ql Mail-\:Followup-\:To:
1167 header is honoured when the message is being replied to (via
1168 .Ic reply
1170 .Ic Lreply )
1172 .Va followup-to
1173 controls wether this header is created when sending mails; it will be
1174 created automatically for a couple of reasons, too, like when the
1175 special
1176 .Dq mailing list specific
1177 respond command
1178 .Ic Lreply
1179 is used, when
1180 .Ic reply
1181 is used to respond to a message with its
1182 .Ql Mail-Followup-To:
1183 being honoured etc.
1186 A difference in between the handling of known and subscribed lists is
1187 that the address of the sender is usually not part of a generated
1188 .Ql Mail-Followup-To:
1189 when addressing the latter, whereas it is for the former kind of lists.
1190 Usually because there are exceptions: say, if multiple lists are
1191 addressed and not all of them are subscribed lists.
1193 For convenience \*(UA will, temporarily, automatically add a list
1194 address that is presented in the
1195 .Ql List-To:
1196 header of a message that is being responded to to the list of known
1197 mailing lists.
1198 Shall that header have existed \*(UA will instead, dependend on the
1199 variable
1200 .Va reply-to-honour ,
1201 use an also set
1202 .Ql Reply-To:
1203 for this purpose in order to accept a list administrators' wish that
1204 is supposed to have been manifested like that (but only if it provides
1205 a single address which resides on the same domain as what is stated in
1206 .Ql List-To: ) .
1207 .\" }}}
1209 .\" .Ss "Resource files" {{{
1210 .Ss "Resource files"
1212 Upon startup \*(UA reads in several resource files:
1214 .Bl -tag -width ".It Pa _AIL_EXTRA_R_"
1216 .It Pa \*(UR
1217 System wide initialization file.
1218 Reading of this file can be suppressed, either by using the
1219 .Fl \&:
1221 .Fl n
1222 command line options, or by setting the environment variable
1223 .Ev NAIL_NO_SYSTEM_RC .
1226 .It Pa \*(ur
1227 File giving initial commands.
1228 A different file can be chosen by setting the environment variable
1229 .Ev MAILRC .
1230 Reading of this file can be suppressed with the
1231 .Fl \&:
1232 command line option.
1234 .It Va NAIL_EXTRA_RC
1235 Can be used to define an optional startup file to be read after all
1236 other resource files.
1237 It can be used to specify settings that are not understood by other
1238 .Xr mailx 1
1239 implementations, for example.
1240 This variable is only honoured when defined in a resource file.
1244 The content of these files is interpreted as follows:
1247 .Bl -bullet -compact
1249 A lines' leading whitespace is removed.
1251 Empty lines are ignored.
1253 Any other line is interpreted as a command.
1254 It may be spread over multiple input lines if the newline character is
1255 .Dq escaped
1256 by placing a backslash character
1257 .Ql \e
1258 as the last character of the line; whereas any leading whitespace of
1259 follow lines is ignored, trailing whitespace before a escaped newline
1260 remains in the input.
1262 If the line (content) starts with the number sign
1263 .Ql #
1264 then it is a comment-command \(en a real command! \(en and also ignored.
1265 This command is the only form of comment that is understood.
1269 For example:
1271 .Bd -literal -offset indent
1272  # This line is a comment command.  And y\e
1273     es, it is really continued here.
1274 set debug \e
1275     verbose
1276     set editheaders
1278 .\" }}}
1280 .\" .Ss "Character sets" {{{
1281 .Ss "Character sets"
1283 \*(OP \*(UA detects the character set of the terminal by using
1284 mechanisms that are controlled by the
1285 .Ev LC_CTYPE
1286 locale setting
1287 (the manual for
1288 .Xr setlocale 3
1289 should give an overview); the \*(UA internal variable
1290 .Va ttycharset
1291 will be set to the detected terminal character set accordingly
1292 and will thus show up in the output of the commands
1293 .Ic set
1295 .Ic varshow .
1298 However, a user supplied
1299 .Va ttycharset
1300 value is not overwritten by this detection mechanism: this
1301 .Dq feature
1302 must be used if the detection doesn't work properly,
1303 and it may be used to adjust the name of the locale character set.
1304 E.g., on BSD systems one may use a locale with the character set
1305 ISO8859-1, which is not a valid name for this character set; to be on
1306 the safe side, one may set
1307 .Va ttycharset
1308 to the correct name, which is ISO-8859-1.
1311 Note that changing the value doesn't mean much beside that,
1312 since several aspects of the real character set are implied by the
1313 locale environment of the system,
1314 and that stays unaffected by the content of an overwritten
1315 .Va ttycharset
1316 variable.
1317 (This is mostly an issue when interactively using \*(UA, though.
1318 It is actually possible to send mail in a completely
1319 .Dq faked
1320 locale environment, an option that \*(UA's test-suite uses excessively.)
1323 If no character set conversion capabilities have been compiled into
1324 \*(UA
1325 .Pf ( Ic features
1326 doesn't include the term
1327 .Ql ICONV ) ,
1328 then
1329 .Va ttycharset
1330 will be the only supported character set,
1331 it is simply assumed that it can be used to exchange 8-bit messages,
1332 and the rest of this section does not apply;
1333 it may however still be necessary to explicitly set it if automatic
1334 detection fails, since in that case it defaults to the mentioned
1335 .\" (Keep in SYNC: ./nail.1:"Character sets", ./nail.h:CHARSET_*!)
1336 ISO-8859-1.
1339 When reading messages, their text is converted into
1340 .Va ttycharset
1341 as necessary in order to display them on the users terminal.
1342 Unprintable characters and invalid byte sequences are detected
1343 and replaced by proper substitution characters (unless the variable
1344 .Va print-all-chars
1345 was set once \*(UA was started).
1346 Also see
1347 .Va charset-unknown-8bit
1348 to deal with another hairy aspect of message interpretation.
1351 When sending messages all their parts and attachments are classified.
1352 Whereas no character set conversion is performed on those parts which
1353 appear to be binary data,
1354 the character set being used must be declared within the MIME header of
1355 an outgoing text part if it contains characters that do not conform to
1356 the set of characters that are allowed by the email standards.
1357 Permissible values for character sets can be declared using the
1358 .Va sendcharsets
1359 variable, and
1360 .Va charset-8bit ,
1361 which defines a catch-all last-resort fallback character set that is
1362 implicitly appended to the list of character-sets in
1363 .Va sendcharsets .
1366 When replying to a message and the variable
1367 .Va reply-in-same-charset
1368 is set then the character set of the message being replied to is tried
1369 first.
1370 And it is also possible to make \*(UA work even more closely related to
1371 the current locale setting automatically by using the variable
1372 .Va sendcharsets-else-ttycharset ,
1373 please see there for more information.
1376 All the specified character sets are tried in order unless the
1377 conversion of the part or attachment succeeds.
1378 If none of the tried (8-bit) character sets is capable to represent the
1379 content of the part or attachment,
1380 then the message will not be sent and its text will optionally be
1381 .Va save Ns d
1383 .Ev DEAD .
1384 In general, if the message
1385 .Dq Cannot convert from a to b
1386 appears, either some characters are not appropriate for the currently
1387 selected (terminal) character set,
1388 or the needed conversion is not supported by the system.
1389 In the first case, it is necessary to set an appropriate
1390 .Ev LC_CTYPE
1391 locale and/or the variable
1392 .Va ttycharset .
1395 The best results are usually achieved when \*(UA is run in a UTF-8
1396 locale on a UTF-8 capable terminal, in which case the full Unicode
1397 spectrum of characters is available.
1398 In this setup characters from various countries can be displayed,
1399 while it is still possible to use more simple character sets for sending
1400 to retain maximum compatibility with older mail clients.
1403 On the other hand the POSIX standard defines a locale-independent 7-bit
1404 .Dq portable character set
1405 that should be used when overall portability is an issue, the even more
1406 restricted subset named
1407 .Dq portable filename character set
1408 consisting of A-Z, a-z, 0-9, period
1409 .Ql \&. ,
1410 underscore
1411 .Ql _
1413 .Ql -
1414 hyphen.
1415 .\" }}}
1417 .\" .Ss "Message states" {{{
1418 .Ss "Message states"
1420 \*(UA differentiates in between several different message states;
1421 the current state will be reflected in header summary displays if
1422 .Va headline
1423 is configured to do so (via the internal variable
1424 .Va attrlist ) ,
1425 and messages can also be selected and be acted upon depending on their
1426 state (see
1427 .Sx "Specifying messages" ) .
1428 When operating on the system mailbox or in primary mailboxes opened with
1429 the special prefix
1430 .Ql %:
1431 (see
1432 .Ic file )
1433 special actions, like the automatic moving of messages to the secondary
1434 .Ev MBOX
1435 mailbox may be applied when the mailbox is left (also implicitly via
1436 a successful exit of \*(UA, but not if the special command
1437 .Ic exit
1438 is used) \(en however, because this may be irritating to users which
1439 are used to
1440 .Dq more modern
1441 mail-user-agents, the default global
1442 .Pa \*(UR
1443 sets the internal
1444 .Va hold
1446 .Va keepsave
1447 variables in order to suppress this behaviour.
1449 .Bl -tag -width ".It Ql _reserved"
1450 .It Ql new
1451 Message has neither been viewed nor moved to any other state.
1452 Such messages are retained even in the system mailbox.
1454 .It Ql unread
1455 Message has neither been viewed nor moved to any other state, but the
1456 message was present already when the mailbox has been opened last:
1457 Such messages are retained even in the system mailbox.
1459 .It Ql read
1460 The message has been processed by one of the following commands:
1461 .Ic ~f ,
1462 .Ic ~m ,
1463 .Ic ~F ,
1464 .Ic ~M ,
1465 .Ic copy ,
1466 .Ic mbox ,
1467 .Ic next ,
1468 .Ic pipe  ,
1469 .Ic Print ,
1470 .Ic print ,
1471 .Ic top ,
1472 .Ic Type ,
1473 .Ic type ,
1474 .Ic undelete .
1476 .Ic delete ,
1477 .Ic dp ,
1479 .Ic dt
1480 commands may also cause the next message to be marked as read, depending
1481 on the value of the
1482 .Va autoprint
1483 variable.
1484 Except when the
1485 .Ic exit
1486 command is used, messages that are in the system mailbox or in mailboxes
1487 which were opened with the special
1488 .Ql %:
1489 prefix and are in
1490 .Ql read
1491 state when the mailbox is left will be saved in
1492 .Ev MBOX
1493 unless the option
1494 .Va hold
1495 it set.
1497 .It Ql deleted
1498 The message has been processed by one of the following commands:
1499 .Ic delete ,
1500 .Ic dp ,
1501 .Ic dt .
1502 Only
1503 .Ic undelete
1504 can be used to access such messages.
1506 .It Ql preserved
1507 The message has been processed by a
1508 .Ic preserve
1509 command and it will be retained in its current location.
1511 .It Ql saved
1512 The message has been processed by one of the following commands:
1513 .Ic save
1515 .Ic write .
1516 Unless when the
1517 .Ic exit
1518 command is used, messages that are in the system mailbox or in mailboxes
1519 which were opened with the special
1520 .Ql %:
1521 prefix and are in
1522 .Ql saved
1523 state when the mailbox is left will be deleted; they will be saved in
1524 .Ev MBOX
1525 when the option
1526 .Va keepsave
1527 is set.
1529 .\" }}}
1531 .\" .Ss "Specifying messages" {{{
1532 .Ss "Specifying messages"
1534 Commands such as
1535 .Ic from ,
1536 .Ic type
1538 .Ic delete
1539 can be given a list of message numbers as arguments to apply to a number
1540 of messages at once.
1541 Thus
1542 .Ql delete 1 2
1543 deletes messages 1 and 2,
1544 whereas
1545 .Ql delete 1-5
1546 will delete the messages 1 through 5.
1547 In sorted or threaded mode (see the
1548 .Ic sort
1549 command),
1550 .Ql delete 1-5
1551 will delete the messages that are located between (and including)
1552 messages 1 through 5 in the sorted/threaded order, as shown in the
1553 .Ic headers
1554 summary.
1555 Multiple colon modifiers can be joined into one, e.g.,
1556 .Ql :du .
1557 The following special message names exist:
1559 .Bl -tag -width ".It Ar _n_u"
1560 .It Ar :n
1562 .Ql new
1563 messages.
1564 .It Ar :o
1565 All old messages (any not in state
1566 .Ql read
1568 .Ql new ) .
1569 .It Ar :u
1571 .Ql unread
1572 messages.
1573 .It Ar :d
1575 .Ql deleted
1576 messages (for the
1577 .Ic undelete
1579 .Ic from
1580 commands only).
1581 .It Ar :r
1583 .Ql read
1584 messages.
1585 .It Ar :f
1587 .Ic flag Ns
1588 ged messages.
1589 .It Ar :a
1590 All answered messages
1591 (cf. the
1592 .Va markanswered
1593 variable).
1594 .It Ar :t
1595 All messages marked as draft.
1596 .It Ar :s
1597 \*(OP All messages classified as spam.
1598 .It Ar :S
1599 \*(OP All messages with unsure spam classification.
1600 .It Ar \&.
1601 The current message, the so-called
1602 .Dq dot .
1603 .It Ar \&;
1604 The message that was previously the current message.
1605 .It Ar \&,
1606 The parent message of the current message,
1607 that is the message with the Message-ID given in the
1608 .Ql In-Reply-To:
1609 field or the last entry of the
1610 .Ql References:
1611 field of the current message.
1612 .It Ar -
1613 The next previous undeleted message,
1614 or the next previous deleted message for the
1615 .Ic undelete
1616 command.
1617 In sorted/threaded mode,
1618 the next previous such message in the sorted/threaded order.
1619 .It Ar +
1620 The next undeleted message,
1621 or the next deleted message for the
1622 .Ic undelete
1623 command.
1624 In sorted/threaded mode,
1625 the next such message in the sorted/threaded order.
1626 .It Ar ^
1627 The first undeleted message,
1628 or the first deleted message for the
1629 .Ic undelete
1630 command.
1631 In sorted/threaded mode,
1632 the first such message in the sorted/threaded order.
1633 .It Ar $
1634 The last message.
1635 In sorted/threaded mode,
1636 the last message in the sorted/threaded order.
1638 .It Ar & Ns Ar x
1639 In threaded mode,
1640 selects the message addressed with
1641 .Ar x ,
1642 where
1643 .Ar x
1644 is any other message specification,
1645 and all messages from the thread that begins at it.
1646 Otherwise it is identical to
1647 .Ar x .
1649 .Ar x
1650 is omitted,
1651 the thread beginning with the current message is selected.
1653 .It Ar *
1654 All messages.
1655 .It Ar `
1656 All messages that were included in the message list for the previous
1657 command.
1659 .It Ar / Ns Ar string
1660 All messages that contain
1661 .Ar string
1662 in the subject field (case ignored).
1663 See also the
1664 .Va searchheaders
1665 variable.
1667 .Ar string
1668 is empty,
1669 the string from the previous specification of that type is used again.
1671 .It Xo Op Ar @ Ns Ar name-list Ns
1672 .Ar @ Ns Ar expr
1674 All messages that contain the given case-insensitive search
1675 .Ar expr Ns
1676 ession; if the \*(OPal regular expression (see
1677 .Xr re_format 7 )
1678 support is available
1679 .Ar expr
1680 will be interpreted as (an extended) one if any of the
1681 .Dq magical
1682 (extended) regular expression characters is seen.
1683 If the optional
1684 .Ar @ Ns Ar name-list
1685 part is missing, the search is restricted to the subject field body,
1686 but otherwise
1687 .Ar name-list
1688 specifies a comma-separated list of header fields to search, as in
1690 .Dl '@to,from,cc@Someone i ought to know'
1692 In order to search for a string that includes a
1693 .Ql @
1694 (commercial at) character the
1695 .Ar name-list
1696 is effectively non-optional, but may be given as the empty string.
1697 Some special header fields may be abbreviated:
1698 .Ql f ,
1699 .Ql t ,
1700 .Ql c ,
1701 .Ql b
1703 .Ql s
1704 will match
1705 .Ql From ,
1706 .Ql To ,
1707 .Ql Cc ,
1708 .Ql Bcc
1710 .Ql Subject ,
1711 respectively and case-insensitively.
1712 The special names
1713 .Ql header
1715 .Ql <
1716 can be used to search in (all of) the header(s) of the message, and the
1717 special names
1718 .Ql body
1720 .Ql >
1722 .Ql text
1724 .Ql =
1725 can be used to perform full text searches \(en whereas the former
1726 searches only the body, the latter also searches the message header.
1728 This message specification performs full text comparison, but even with
1729 regular expression support it is almost impossible to write a search
1730 expression that savely matches only a specific address domain.
1731 To request that the content of the header is treated as a list of
1732 addresses, and to strip those down to the plain email address which the
1733 search expression is to be matched against, prefix the header name
1734 (abbreviation) with a tilde
1735 .Ql ~ :
1737 .Dl @~f@@a\e.safe\e.domain\e.match$
1739 .It Ar address
1740 A case-insensitive
1741 .Dq any substring matches
1742 search against the
1743 .Ql From:
1744 header, which will match addresses (too) even if
1745 .Va showname
1746 is set (and POSIX says
1747 .Dq any address as shown in a header summary shall be matchable in this form ) ;
1748 However, if the
1749 .Va allnet
1750 variable is set, only the local part of the address is evaluated
1751 for the comparison, not ignoring case, and the setting of
1752 .Va showname
1753 is completely ignored.
1754 For finer control and match boundaries use the
1755 .Ql @
1756 search expression; the \*(OPal IMAP-style
1757 .Ql (from address)
1758 expression can also be used if substring matches are desired.
1762 \*(OP IMAP-style SEARCH expressions may also be used.
1763 This addressing mode is available with all types of folders;
1764 \*(UA will perform the search locally as necessary.
1765 Strings must be enclosed by double quotes
1766 .Ql \&"
1767 in their entirety if they contain white space or parentheses;
1768 within the quotes, only backslash
1769 .Ql \e
1770 is recognized as an escape character.
1771 All string searches are case-insensitive.
1772 When the description indicates that the
1773 .Dq envelope
1774 representation of an address field is used,
1775 this means that the search string is checked against both a list
1776 constructed as
1778 .Bd -literal -offset indent
1779 (\*qname\*q \*qsource\*q \*qlocal-part\*q \*qdomain-part\*q)
1783 for each address,
1784 and the addresses without real names from the respective header field.
1785 These search expressions can be nested using parentheses, see below for
1786 examples.
1789 .Bl -tag -compact -width ".It Ar _n_u"
1790 .It Ar ( criterion )
1791 All messages that satisfy the given
1792 .Ar criterion .
1793 .It Ar ( criterion1 criterion2 ... criterionN )
1794 All messages that satisfy all of the given criteria.
1796 .It Ar ( or criterion1 criterion2 )
1797 All messages that satisfy either
1798 .Ar criterion1
1800 .Ar criterion2 ,
1801 or both.
1802 To connect more than two criteria using
1803 .Ql or
1804 specifications have to be nested using additional parentheses,
1805 as with
1806 .Ql (or a (or b c)) ,
1807 since
1808 .Ql (or a b c)
1809 really means
1810 .Ql ((a or b) and c) .
1811 For a simple
1812 .Ql or
1813 operation of independent criteria on the lowest nesting level,
1814 it is possible to achieve similar effects by using three separate
1815 criteria, as with
1816 .Ql (a) (b) (c) .
1818 .It Ar ( not criterion )
1819 All messages that do not satisfy
1820 .Ar criterion .
1821 .It Ar ( bcc \*q Ns Ar string Ns Ar \*q )
1822 All messages that contain
1823 .Ar string
1824 in the envelope representation of the
1825 .Ql Bcc:
1826 field.
1827 .It Ar ( cc \*q Ns Ar string Ns Ar \*q )
1828 All messages that contain
1829 .Ar string
1830 in the envelope representation of the
1831 .Ql Cc:
1832 field.
1833 .It Ar ( from \*q Ns Ar string Ns Ar \*q )
1834 All messages that contain
1835 .Ar string
1836 in the envelope representation of the
1837 .Ql From:
1838 field.
1839 .It Ar ( subject \*q Ns Ar string Ns Ar \*q )
1840 All messages that contain
1841 .Ar string
1842 in the
1843 .Ql Subject:
1844 field.
1845 .It Ar ( to \*q Ns Ar string Ns Ar \*q )
1846 All messages that contain
1847 .Ar string
1848 in the envelope representation of the
1849 .Ql To:
1850 field.
1851 .It Ar ( header name \*q Ns Ar string Ns Ar \*q )
1852 All messages that contain
1853 .Ar string
1854 in the specified
1855 .Ql Name:
1856 field.
1857 .It Ar ( body \*q Ns Ar string Ns Ar \*q )
1858 All messages that contain
1859 .Ar string
1860 in their body.
1861 .It Ar ( text \*q Ns Ar string Ns Ar \*q )
1862 All messages that contain
1863 .Ar string
1864 in their header or body.
1865 .It Ar ( larger size )
1866 All messages that are larger than
1867 .Ar size
1868 (in bytes).
1869 .It Ar ( smaller size )
1870 All messages that are smaller than
1871 .Ar size
1872 (in bytes).
1874 .It Ar ( before date )
1875 All messages that were received before
1876 .Ar date ,
1877 which must be in the form
1878 .Ql d[d]-mon-yyyy ,
1879 where
1880 .Ql d
1881 denotes the day of the month as one or two digits,
1882 .Ql mon
1883 is the name of the month \(en one of
1884 .Ql Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec ,
1886 .Ql yyyy
1887 is the year as four digits, e.g.,
1888 .Ql 28-Dec-2012 .
1890 .It Ar ( on date )
1891 All messages that were received on the specified date.
1892 .It Ar ( since date )
1893 All messages that were received since the specified date.
1894 .It Ar ( sentbefore date )
1895 All messages that were sent on the specified date.
1896 .It Ar ( senton date )
1897 All messages that were sent on the specified date.
1898 .It Ar ( sentsince date )
1899 All messages that were sent since the specified date.
1900 .It Ar ()
1901 The same criterion as for the previous search.
1902 This specification cannot be used as part of another criterion.
1903 If the previous command line contained more than one independent
1904 criterion then the last of those criteria is used.
1906 .\" }}}
1908 .\" .Ss "On URL syntax and credential lookup" {{{
1909 .Ss "On URL syntax and credential lookup"
1911 \*(IN For accessing protocol-specific resources usage of Uniform
1912 Resource Locators (URL, RFC 1738) has become omnipresent.
1913 \*(UA expects and understands URLs in the following form;
1914 parts in brackets
1915 .Ql []
1916 denote optional parts, optional either because there also exist other
1917 ways to define the information in question or because support of the
1918 part is protocol-specific (e.g.,
1919 .Ql /path
1920 is used by the IMAP protocol but not by POP3);
1921 If any of
1922 .Ql USER
1924 .Ql PASSWORD
1925 are specified they must be given in URL percent encoded form (RFC 3986;
1926 the commands
1927 .Ic urlencode
1929 .Ic urldecode
1930 may be helpful):
1933 .Dl PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
1936 Note that these \*(UA URLs most often don't conform to any real
1937 standard, but instead represent a normalized variant of RFC 1738 \(en
1938 they are not used in data exchange but only ment as a compact,
1939 easy-to-use way of defining and representing information in
1940 a well-known notation.
1943 Many internal variables of \*(UA exist in multiple versions, called
1944 variable chains for the rest of this document: the plain
1945 .Ql variable
1946 as well as
1947 .Ql variable-HOST
1949 .Ql variable-USER@HOST .
1950 Here
1951 .Ql HOST
1952 indeed means
1953 .Ql server:port
1954 if a
1955 .Ql port
1956 had been specified in the respective URL, otherwise it refers to the plain
1957 .Ql server .
1958 Also,
1959 .Ql USER
1960 isn't truly the
1961 .Ql USER
1962 that had been found when doing the user chain lookup as is described
1963 below, i.e., this
1964 .Ql USER
1965 will never be in URL percent encoded form, wether it came from an URL or
1966 not; i.e., values of
1967 .Sx "INTERNAL VARIABLES"
1968 must not be URL percent encoded.
1971 For example, wether an hypothetical URL
1972 .Ql smtp://hey%3Ayou@our.house
1973 had been given that includes a user, or wether the URL was
1974 .Ql smtp://our.house
1975 and the user had been found differently, to lookup the variable chain
1976 .Va smtp-use-starttls
1977 \*(UA first looks for wether
1978 .Ql smtp-\:use-\:starttls-\:hey:you@our.house
1979 is defined, then wether
1980 .Ql smtp-\:use-\:starttls-\:our.house
1981 exists before finally ending up looking at the plain variable itself.
1984 \*(UA obeys the following logic scheme when dealing with the
1985 necessary credential informations of an account:
1987 .Bl -bullet
1989 If no
1990 .Ql USER
1991 has been given in the URL the variables
1992 .Va user-HOST
1994 .Va user
1995 are looked up; if no such variable(s) can be found then \*(UA will,
1996 when enforced by the \*(OPal variables
1997 .Va netrc-lookup-HOST
1999 .Va netrc-lookup ,
2000 search the users
2001 .Pa .netrc
2002 file for a
2003 .Ql HOST
2004 specific entry which provides a
2005 .Ql login
2006 name: this lookup will only succeed if unambiguous (one possible matching
2007 entry for
2008 .Ql HOST ) .
2010 If there is still no
2011 .Ql USER
2012 then \*(UA will fall back to the user who is supposed to run \*(UA:
2013 either the name that has been given with the
2014 .Fl u
2015 command line option (or, equivalently, but with less precedence, the
2016 environment variable
2017 .Ev LOGNAME ) ,
2018 or the
2019 .Dq current
2020 user.
2021 The identity of this user has been fixated during \*(UA startup and is
2022 known to be a valid user on the current host.
2025 Authentication: unless otherwise noted this will lookup the
2026 .Va PROTOCOL-auth-USER@HOST , PROTOCOL-auth-HOST , PROTOCOL-auth
2027 variable chain, falling back to a protocol-specific default should this
2028 have no success.
2031 If no
2032 .Ql PASSWORD
2033 has been given in the URL, then if the
2034 .Ql USER
2035 has been found through the \*(OPal
2036 .Va netrc-lookup
2037 then that may have already provided the password, too.
2038 Otherwise the variable chain
2039 .Va password-USER@HOST , password-HOST , password
2040 is looked up and used if existent.
2042 \*(OP Then if any of the variables of the chain
2043 .Va agent-shell-lookup-USER@HOST , agent-shell-lookup-HOST , \
2044   agent-shell-lookup
2045 is set the shell command specified therein is run and the output (less
2046 newline characters) will be used as the password.
2047 It is perfectly valid for such an agent to simply not return any data,
2048 in which case the password lookup is continued somewhere else;
2049 Any command failure is treated as a hard error, however.
2051 Afterwards the complete \*(OPal variable chain
2052 .Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
2053 is looked up.
2054 If set, the
2055 .Pa .netrc
2056 cache is searched for a password only (multiple user accounts for
2057 a single machine may exist as well as a fallback entry without user
2058 but with a password).
2060 If at that point there is still no password available, but the
2061 (protocols') chosen authentication type requires a password, then in
2062 interactive mode the user will be prompted on the terminal.
2066 .Sy Note:
2067 S/MIME verification works relative to the values found in the
2068 .Ql From:
2070 .Ql Sender: )
2071 header field(s), which means that the values of
2072 .Va smime-sign , smime-sign-cert , smime-sign-include-certs
2074 .Va smime-sign-message-digest
2075 will not be looked up using the
2076 .Ql USER
2078 .Ql HOST
2079 chains from above but instead use the corresponding values from the
2080 message that is being worked on.
2081 In unusual cases multiple and different
2082 .Ql USER
2084 .Ql HOST
2085 combinations may therefore be involved \(en on the other hand those
2086 unusual cases become possible.
2087 The usual case is as short as:
2090 .Dl set smtp=smtp://USER:PASS@HOST smtp-use-starttls \e
2091 .Dl \ \ \ \ smime-sign smime-sign-cert=+smime.pair
2094 The section
2095 .Sx EXAMPLES
2096 contains complete example configurations.
2097 .\" }}}
2099 .\" .Ss "On terminal control and line editor" {{{
2100 .Ss "On terminal control and line editor"
2102 \*(OP \*(UA can be configured to support a line editor,
2103 history lists that can be saved in between sessions,
2104 and terminal control to improve interactive usage experience.
2105 For the former one may either link against an external library
2106 .Pf ( Xr readline 3 ;
2107 behaviour of \*(UA may differ slightly),
2108 or enable the builtin Mailx-Line-Editor (MLE), which should work in all
2109 environments which comply to the ISO C standard
2110 .St -isoC-amd1 ,
2111 and which will support wide glyphs if possible (the necessary
2112 functionality had been removed from ISO C, but was included in
2113 .St -xpg4 ) .
2114 Prevent usage of a line editor in interactive mode by setting the
2115 internal variable
2116 .Va line-editor-disable .
2119 \*(OP If the
2120 .Ic history
2121 feature is available then input from line editor prompts will be saved
2122 in a history list that can be searched in and be expanded from.
2123 Such saving can be prevented by prefixing input with any amount of
2124 whitespace.
2125 Aspects of history, like allowed content, maximum size etc., can be
2126 configured with the variables
2127 .Va history-file ,
2128 .Va history-gabby ,
2129 .Va history-gabby-persist
2131 .Va history-size .
2134 \*(OP For terminal control the standard
2136 .Lb libtermcap
2137 will be initialized to work with the
2138 .Ev TERM Ns
2139 inal, enhancing several interactive usage aspects of \*(UA (shall this
2140 succeed), including the MLE:
2141 For example it will learn the keycodes of special keys like, e.g.,
2142 arrows and it will automatically enter the so-called
2143 .Dq ca-mode
2144 alternative screen shall the terminal support it.
2145 The internal variable
2146 .Va termcap
2147 can be used to overwrite settings or to learn (correct(ed)) keycodes.
2148 Interaction with the
2149 .Lb libtermcap
2150 can be disabled completely by setting
2151 .Va termcap-disable ,
2152 which may be necessary for proper operation on the actual terminal;
2153 note that the variable
2154 .Va termcap
2155 will be queried by some \*(OPal modules of \*(UA, like the MLE,
2156 regardless of the availability of the mentioned library and wether its
2157 use is disabled.
2160 \*(OP The builtin \*(UA line editor MLE supports the following
2161 operations; the notation
2162 .Ql ^-LETTER
2163 stands for the combination of the
2164 .Ql control
2165 key plus the mentioned character, e.g.,
2166 .Ql ^A
2167 means
2168 .Dq hold down control key and press the A key .
2169 Especially without termcap support setting respective entries in
2170 .Va termcap
2171 will help shall MLE misbehave.
2174 .Bl -tag -compact -width "Ql _M"
2175 .It Ql ^A
2176 Go to the start of the line.
2177 .It Ql ^B
2178 Move the cursor backward one character.
2179 .It Ql ^D
2180 Forward delete the character under the cursor;
2181 quits \*(UA if used on the empty line unless the
2182 .Va ignoreeof
2183 option is set.
2184 .It Ql ^E
2185 Go to the end of the line.
2186 .It Ql ^F
2187 Move the cursor forward one character.
2189 .It Ql ^G
2190 Cancel current operation, full reset.
2191 If there is an active history search or tabulator expansion then this
2192 command will first reset that, reverting to the former line content;
2193 thus a second reset is needed for a full reset in this case.
2194 In all cases \*(UA will reset a possibly used multibyte character input
2195 state machine.
2197 .It Ql ^H
2198 The same as
2199 .Dq backspace :
2200 backward delete one character.
2202 .It Ql ^I
2203 The same as
2204 .Dq horizontal tabulator :
2205 try to expand the word before the cursor.
2206 (Note this is not
2207 .Dq tabulator-completion
2208 as is known from the
2209 .Xr sh 1
2210 but really means the usual \*(UA expansion, as documented for
2211 .Ic file ,
2212 yet it involves shell expansion as a last step, too.)
2214 .It Ql ^J
2215 The same as
2216 .Dq ENTER :
2217 complete this line of input.
2218 .It Ql ^K
2219 Delete all characters from the cursor to the end of the line.
2220 .It Ql ^L
2221 Repaint the line.
2222 .It Ql ^N
2223 \*(OP Go to the next history entry.
2224 .It Ql ^O
2225 Execute the command
2226 .Ic dp .
2227 .It Ql ^P
2228 \*(OP Go to the previous history entry.
2229 .It Ql ^R
2230 \*(OP Complete the current line from (the remaining older) history entries.
2231 .It Ql ^U
2232 The same as
2233 .Ql ^A
2234 followed by
2235 .Ql ^K .
2236 .It Ql ^W
2237 Delete the characters from the one preceding the cursor to the preceding
2238 word boundary.
2239 .It Ql ^X
2240 Move the cursor forward one word boundary.
2241 .It Ql ^Y
2242 Move the cursor backward one word boundary.
2246 If the keycodes are known then the left and right cursor keys will map to
2247 .Ql ^B
2249 .Ql ^F ,
2250 respectively, the up and down cursor keys will map to
2251 .Ql ^P
2253 .Ql ^N ,
2254 and the Home/End/PgUp/PgDown keys will call the
2255 .Ic z
2256 command with the respective arguments
2257 .Ql 0 ,
2258 .Ql $ ,
2259 .Ql -
2261 .Ql +
2262 (i.e., perform scrolling through the header summary list).
2263 Also the up and down cursor keys should invoke
2264 .Ic dotmove
2265 for up- and downwards movement if they are used while the
2266 .Ql control
2267 key is held.
2268 .\" }}}
2270 .\" .Ss "Coloured display" {{{
2271 .Ss "Coloured display"
2273 \*(OP \*(UA can be configured to support a coloured display and font
2274 attributes.
2275 Colour usage depends on the value of the environment variable
2276 .Ev TERM :
2277 if that is not set or set to the value
2278 .Ql dumb
2279 then this section doesn't apply, if the value includes the string
2280 .Ql color ,
2281 or if it can be found (case-insensitively) in the variable
2282 .Va colour-terms
2283 then \*(UA will assume a colour-enabled display, but otherwise
2284 a monochrome display is assumed.
2287 On top of what \*(UA knows about the terminal the boolean variable
2288 .Va colour-pager
2289 defines wether colour and font attribute sequences should also be
2290 generated when the output of a command needs to go through the
2291 .Ev PAGER
2292 (also see
2293 .Va crt Ns
2295 This is not enabled by default because different pager programs need
2296 different command line switches or other configuration in order to
2297 support those colour sequences.
2298 \*(UA knows about some widely used pagers and in a clean environment
2299 it is often enough to simply set
2300 .Va colour-pager ;
2301 please refer to that variable for more on this topic.
2304 If the variable
2305 .Va colour-disable
2306 is set then any active usage of colour and font attribute sequences
2307 is suppressed, but without affecting possibly established
2308 .Ic colour
2309 mappings.
2312 To define and control colours and font attributes a single multiplexer
2313 command family exists:
2314 .Ic colour
2315 shows or defines colour mappings for the given colour type (e.g.,
2316 monochrome) and
2317 .Ic uncolour
2318 can be used to remove mappings of a given colour type.
2319 Since colours are only available in interactive mode, it may make
2320 sense to conditionalize the colour setup by encapsulating it with
2321 .Ic if :
2323 .Bd -literal -offset indent
2324 if terminal
2325   colour iso  view-msginfo  ft=bold,fg=green
2326   colour iso  view-header   ft=bold,fg=red   "from,subject"
2327   colour iso  view-header   fg=red
2329   uncolour iso view-header  from,subject
2330   colour iso  view-header   ft=bold,fg=magenta,bg=cyan
2331   colour 256  view-header   ft=bold,fg=208,bg=230 subject,from
2332   colour mono view-header   ft=bold
2333   colour mono view-header   ft=bold,ft=reverse subject,from
2334 endif
2336 .\" }}}
2337 .\" }}} (DESCRIPTION)
2340 .\" .Sh COMMANDS {{{
2341 .Sh COMMANDS
2343 Each command is typed on a line by itself,
2344 and may take arguments following the command word.
2345 The command need not be typed in its entirety \(en
2346 the first command which matches the typed prefix is used.
2347 An \(en alphabetically \(en sorted list of commands can be shown
2348 with the command
2349 .Ic list ,
2350 and the command
2351 .Ic help
2353 .Ic \&? ) ,
2354 when given an argument, will show a documentation string for the
2355 command matching the expanded argument, as in
2356 .Ql ?t ,
2357 which should be a shorthand of
2358 .Ql ?type ;
2359 documentation strings are however \*(OPal.
2362 For commands which take message lists as arguments, the next message
2363 forward that satisfies the command's requirements will be used shall no
2364 explicit message list have been specified.
2365 If there are no messages forward of the current message,
2366 the search proceeds backwards,
2367 and if there are no good messages at all,
2368 \*(UA types
2369 .Dq no applicable messages
2370 and aborts the command.
2371 The arguments to commands can be quoted, using the following methods:
2374 .Bl -bullet -compact -offset indent
2376 An argument can be enclosed between paired double-quotes
2377 .Ql """argument"""
2379 single-quotes
2380 .Ql 'argument' ;
2381 any white space, shell word expansion, or backslash characters (except
2382 as described next) within the quotes are treated literally as part of
2383 the argument.
2384 A double-quote will be treated literally within single-quotes and vice
2385 versa.
2386 Inside such a quoted string the actually used quote character can be
2387 used nonetheless by escaping it with a backslash
2388 .Ql \e ,
2389 as in
2390 .Ql """y\e""ou""" .
2393 An argument that is not enclosed in quotes, as above, can usually still
2394 contain space characters if those spaces are backslash-escaped, as in
2395 .Ql you\e are .
2398 A backslash outside of the enclosing quotes is discarded
2399 and the following character is treated literally as part of the argument.
2402 An unquoted backslash at the end of a command line is discarded and the
2403 next line continues the command.
2407 Filenames, where expected, are subsequently subjected to the following
2408 transformations, in sequence:
2411 .Bl -bullet -compact -offset indent
2413 If the filename begins with an unquoted plus sign, and the
2414 .Va folder
2415 variable is defined,
2416 the plus sign will be replaced by the value of the
2417 .Va folder
2418 variable followed by a slash.
2419 If the
2420 .Va folder
2421 variable is unset or is set to null, the filename will be unchanged.
2424 Shell word expansions are applied to the filename.
2425 .\" TODO shell word expansion shell expand fexpand FEXP_NSHELL
2426 .Sy Compatibility note:
2427 on the long run support for complete shell word expansion will be
2428 replaced by an internally implemented restricted expansion mechanism in
2429 order to circumvent possible security impacts through shell expansion.
2430 Expect that a growing number of program parts only support this
2431 restricted syntax:
2433 Meta expansions are applied to the filename: leading tilde characters
2434 .Pf ( Ql ~/ )
2435 will be replaced by the expansion of
2436 .Ev HOME ,
2437 and any occurrence of
2438 .Ql $VARIABLE
2440 .Ql ${VARIABLE} )
2441 will be replaced by the expansion of the variable, if possible;
2442 \*(UA internal as well as environmental (shell) variables can be
2443 accessed through this mechanism.
2444 In order to include a raw
2445 .Ql $
2446 character precede it with a backslash
2447 .Ql \e ,
2448 to include a backslash double it.
2449 If more than a single pathname results from this expansion and the
2450 command is expecting one file, an error results.
2452 Note that in interactive display context, in order to allow simple
2453 value acceptance (typing
2454 .Dq ENTER ) ,
2455 backslash quoting is performed automatically as necessary, e.g., a file
2456 .Ql diet\e is \ecurd.txt
2457 will be displayed as
2458 .Ql diet\e\e is \e\ecurd.txt .
2462 The following commands are available:
2464 .Bl -tag -width ".Ic _ccount"
2466 .It Ic \&!
2467 Executes the
2468 .Ev SHELL
2469 (see
2470 .Xr sh 1 Ns
2471 ) command which follows.
2474 .It Ic #
2475 The comment-command causes the entire line to be ignored.
2476 .Sy Note:
2477 this really is a normal command which' purpose is to discard its
2478 arguments, not a
2479 .Dq comment-start
2480 indicating special character, which means that, e.g., trailing comments
2481 on a line are not possible.
2484 .It Ic +
2485 Goes to the next message in sequence and types it
2486 (like
2487 .Dq ENTER ) .
2490 .It Ic -
2491 Display the preceding message, or the n'th previous message if given
2492 a numeric argument n.
2495 .It Ic =
2496 Show the current message number (the
2497 .Dq dot ) .
2500 .It Ic \&?
2501 Show a brief summary of commands.
2502 \*(OP Given an argument a synopsis for the command in question is
2503 shown instead; commands can be abbreviated in general and this command
2504 can be used to see the full expansion of an abbreviation including the
2505 synopsis, try, e.g.,
2506 .Ql ?h ,
2507 .Ql ?hel
2509 .Ql ?help
2510 and see how the output changes.
2513 .It Ic \&|
2514 A synonym for the
2515 .Ic pipe
2516 command.
2519 .It Ic ~
2520 Interprets the remainder of the word as a macro name and passes it
2521 through to the
2522 .Ic call
2523 command; e.g.,
2524 .Ql ~ Ns Ar mymacro
2525 is a shorter synonym for
2526 .Ql call Ar mymacro .
2529 .It Ic account
2530 (ac) Creates, selects or lists (an) account(s).
2531 An account is a group of commands and variable settings which together
2532 usually arrange the environment for the purpose of creating a system login.
2533 Without any argument a listing of all defined accounts and their content
2534 is shown.
2535 A specific account can be activated by giving solely its name, resulting
2536 in the system mailbox or inbox of that account to be activated as via an
2537 explicit use of the command
2538 .Ic file .
2539 The two argument form is identical to defining a macro as via
2540 .Ic define .
2541 For example:
2542 .Bd -literal -offset indent
2543 account myisp {
2544   set folder=mail
2545   set record=+Sent
2546   set from="myname@myisp.example (My Name)"
2547   set smtp=smtp://mylogin@smtp.myisp.example
2551 creates an account named
2552 .Ql myisp
2553 which can later be selected by specifying
2554 .Ql account myisp .
2555 The special account
2556 .Ql null
2557 (case-insensitive) always exists.
2558 .Ic localopts
2559 are enabled by default and localize account settings \(en different to
2560 normal macros the settings will be reverted once the account is switched off.
2561 Accounts can be deleted via
2562 .Ic unaccount .
2565 .It Ic alias
2566 (a) With no arguments, shows all currently-defined aliases.
2567 With one argument, shows that alias.
2568 With more than one argument,
2569 creates a new alias or appends to an existing one.
2570 .Ic unalias
2571 can be used to delete aliases.
2574 .It Ic alternates
2575 (alt) Manage a list of alternate addresses / names of the active user,
2576 members of which will be removed from recipient lists when replying to
2577 messages (and the
2578 .Va metoo
2579 variable is not set).
2580 If arguments are given the set of alternate names is replaced by them,
2581 without arguments the current set is displayed.
2584 .It Ic answered
2585 Takes a message list and marks each message as having been answered.
2586 This mark has no technical meaning in the mail system;
2587 it just causes messages to be marked in the header summary,
2588 and makes them specially addressable.
2591 .It Ic call
2592 Calls a macro that has been created via
2593 .Ic define .
2596 .It Ic cd
2597 (ch) Change the working directory to
2598 .Ev HOME
2599 or the given argument.
2600 Synonym for
2601 .Ic chdir .
2604 .It Ic certsave
2605 \*(OP Only applicable to S/MIME signed messages.
2606 Takes a message list and a file name and saves the certificates
2607 contained within the message signatures to the named file in both
2608 human-readable and PEM format.
2609 The certificates can later be used to send encrypted messages to the
2610 respective message senders by setting
2611 .Va smime-encrypt-USER@HOST
2612 variables.
2615 .It Ic chdir
2616 (ch) Change the working directory to
2617 .Ev HOME
2618 or the given argument.
2619 Synonym for
2620 .Ic cd .
2623 .It Ic collapse
2624 Only applicable to threaded mode.
2625 Takes a message list and makes all replies to these messages invisible
2626 in header summaries, unless they are in state
2627 .Ql new .
2631 .It Ic colour
2632 \*(OP Manage colour mappings for the type of colour given as the
2633 (case-insensitive) first argument, which must be one of
2634 .Ql 256
2635 for 256-colour terminals,
2636 .Ql 8 ,
2637 .Ql ansi
2639 .Ql iso
2640 for the standard 8-colour ANSI / ISO 6429 color palette and
2641 .Ql 1
2643 .Ql mono
2644 for monochrome terminals.
2645 Monochrome terminals cannot deal with colours, but only (some) font
2646 attributes.
2649 Without further arguments the list of all currently defined mappings for
2650 the given colour type is shown.
2651 Otherwise the second argument defines the mappable slot, the third
2652 argument a (comma-separated list of) colour and font attribute
2653 specification(s), and the optional fourth argument can be used to
2654 specify a precondition: if conditioned mappings exist they are tested in
2655 (creation) order unless a (case-insensitive) match has been found, and
2656 the default mapping (if any has been established) will only be chosen as
2657 a last resort.
2658 The types of precondition available depend on the mappable slot, the
2659 following of which exist:
2662 .Bl -tag -compact -width view-partinfo
2663 .It Cd sum-dotmark
2664 Mappings prefixed with
2665 .Ql sum-
2666 are used in header summaries, and they all understand the preconditions
2667 .Ql dot
2668 (the current message) and
2669 .Ql older
2670 for elder messages (only honoured in conjunction with
2671 .Va datefield-markout-older ) .
2672 This mapping is used for the
2673 .Dq dotmark
2674 that can be created with the
2675 .Ql %>
2677 .Ql %<
2678 formats of the variable
2679 .Va headline .
2680 .It Cd sum-header
2681 For the complete header summary line except the
2682 .Dq dotmark
2683 and the thread structure.
2684 .It Cd sum-thread
2685 For the thread structure which can be created with the
2686 .Ql %i
2687 format of the variable
2688 .Va headline .
2690 .It Cd view-from_
2691 Mappings prefixed with
2692 .Ql view-
2693 are used when displaying messages.
2694 This mapping is used for so-called
2695 .Ql From_
2696 lines, which are MBOX file format specific header lines.
2697 .It Cd view-header
2698 For header lines.
2699 A comma-separated list of headers to which the mapping applies may be
2700 given as a precondition; if the \*(OPal regular expression support is
2701 available then if any of the
2702 .Dq magical
2703 (extended) regular expression characters is seen the precondition will
2704 be evaluated as (an extended) one.
2705 .It Cd view-msginfo
2706 For the introductional message info line.
2707 .It Cd view-partinfo
2708 For MIME part info lines.
2712 The following (case-insensitive) colour definitions and font attributes
2713 are understood, multiple of which can be specified in a comma-separated
2714 list:
2716 .Bl -tag -width ft=
2717 .It Cd ft=
2718 a font attribute:
2719 .Ql bold ,
2720 .Ql reverse
2722 .Ql underline .
2723 It is possible (and often applicable) to specify multiple font
2724 attributes for a single mapping.
2726 .It Cd fg=
2727 foreground colour attribute:
2728 .Ql black ,
2729 .Ql blue ,
2730 .Ql green ,
2731 .Ql red ,
2732 .Ql brown ,
2733 .Ql magenta ,
2734 .Ql cyan
2736 .Ql white .
2737 To specify a 256-color mode a decimal number colour specification in
2738 the range 0 to 255, inclusive, is supported, and interpreted as follows:
2740 .Bl -tag -compact -width "999 - 999"
2741 .It 0 - 7
2742 the standard ISO 6429 colors, as above.
2743 .It 8 - 15
2744 high intensity variants of the standard colors.
2745 .It 16 - 231
2746 216 colors in tuples of 6.
2747 .It 232 - 255
2748 grayscale from black to white in 24 steps.
2750 .Bd -literal -offset indent
2751 #!/bin/sh -
2752 fg() { printf "\e033[38;5;${1}m($1)"; }
2753 bg() { printf "\e033[48;5;${1}m($1)"; }
2755 while [ $i -lt 256 ]; do fg $i; i=$(($i + 1)); done
2756 printf "\e033[0m\en"
2758 while [ $i -lt 256 ]; do bg $i; i=$(($i + 1)); done
2759 printf "\e033[0m\en"
2762 .It Cd bg=
2763 background colour attribute (see
2764 .Cd fg=
2765 for possible values).
2769 Mappings may be removed with the command
2770 .Ic uncolour .
2771 For a generic overview see the section
2772 .Sx "Coloured display" .
2776 .It Ic Copy
2777 (C) Copy messages to files whose names are derived from the author of
2778 the respective message and don't mark them as being saved;
2779 otherwise identical to
2780 .Ic Save .
2783 .It Ic copy
2784 (c) Copy messages to the named file and don't mark them as being saved;
2785 otherwise identical to
2786 .Ic save .
2789 .It Ic customhdr
2790 With no arguments, shows all currently-defined custom headers.
2791 With one argument, shows that custom header.
2792 With more than one argument, creates a new or replaces an existing
2793 custom header with the name given as the first argument, the content of
2794 which being defined by the concatenated remaining arguments.
2795 .Ic uncustomhdr
2796 can be used to delete custom headers.
2797 \*(ID Overwriting of automatically managed headers is neither supported
2798 nor prevented.
2799 Defined custom headers will be injected into newly composed or forwarded
2800 messages, e.g.:
2802 .Dl customhdr OpenPGP id=12345678; url=http://www.YYY.ZZ
2804 The \*(OB variable
2805 .Va customhdr
2806 may also be used to inject custom headers; it is covered by
2807 .Ic localopts .
2810 .It Ic cwd
2811 Show the name of the current working directory.
2814 .It Ic Decrypt
2815 \*(OP For unencrypted messages this command is identical to
2816 .Ic Copy ;
2817 Encrypted messages are first decrypted, if possible, and then copied.
2820 .It Ic decrypt
2821 \*(OP For unencrypted messages this command is identical to
2822 .Ic copy ;
2823 Encrypted messages are first decrypted, if possible, and then copied.
2826 .It Ic define
2827 Without arguments the current list of macros, including their content,
2828 is shown, otherwise a macro is defined.
2829 A macro definition is a sequence of commands in the following form:
2830 .Bd -literal -offset indent
2831 define name {
2832   command1
2833   command2
2834   ...
2835   commandN
2839 A defined macro can be invoked explicitly by using the
2840 .Ic call
2842 .Ic ~
2843 commands, or implicitly if a macro hook is triggered, e.g., a
2844 .Va folder-hook .
2845 Note that interpretation of
2846 .Ic localopts
2847 depends on how (i.e.,
2848 .Dq as what :
2849 normal macro, folder hook, hook, account switch) the macro is invoked.
2850 Macros can be deleted via
2851 .Ic undefine .
2853 .Sy \*(ID:
2854 Macro behaviour, including option localization, will change in v15.
2855 Please be aware of that and possibly embed a version check in a resource
2856 file of yours!
2859 .It Ic delete
2860 (d) Marks the given message list as
2861 .Ql deleted .
2862 Deleted messages will neither be saved in
2863 .Ev MBOX
2864 nor will they be available for most other commands.
2867 .It Ic discard
2868 (di) Identical to
2869 .Ic ignore .
2870 Also see
2871 .Ic retain .
2875 .It Ic dp , dt
2876 Deletes the current message and displays the next message.
2877 If there is no next message, \*(UA says
2878 .Dq at EOF .
2881 .It Ic dotmove
2882 Move the
2883 .Dq dot
2884 up or down by one message when given
2885 .Ql +
2887 .Ql -
2888 argument, respectively.
2891 .It Ic draft
2892 Takes a message list and marks each given message as a draft.
2893 This mark has no technical meaning in the mail system;
2894 it just causes messages to be marked in the header summary,
2895 and makes them specially addressable.
2898 .It Ic echo
2899 (ec) Echoes its arguments,
2900 resolving special names as documented for the command
2901 .Ic file .
2902 The escape sequences
2903 .Ql \ea ,
2904 .Ql \eb ,
2905 .Ql \ec ,
2906 .Ql \ef ,
2907 .Ql \en ,
2908 .Ql \er ,
2909 .Ql \et ,
2910 .Ql \ev ,
2911 .Ql \e\e
2913 .Ql \e0octal-num
2914 are interpreted just as they are by
2915 .Xr printf 1
2916 (proper quoting provided).
2919 .It Ic edit
2920 (e) Point the text editor (as defined in
2921 .Ev EDITOR )
2922 at each message from the given list in turn.
2923 Modified contents are discarded unless the
2924 .Va writebackedited
2925 variable is set.
2928 .It Ic elif
2929 Part of the
2930 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
2931 conditional \(em if the condition of a preceeding
2932 .Ic if
2933 was false, check the following condition and execute the following block
2934 if it evaluates true.
2937 .It Ic else
2938 (el) Part of the
2939 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
2940 conditional \(em if none of the conditions of the preceeding
2941 .Ic if
2943 .Ic elif
2944 commands was true, the
2945 .Ic else
2946 block is executed.
2949 .It Ic endif
2950 (en) Marks the end of an
2951 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
2952 conditional execution block.
2955 .It Ic errors
2956 \*(OP Since \*(UA uses the console as a user interface it can happen
2957 that messages scroll by too fast to become recognized.
2958 Optionally an error message ring queue is available which stores
2959 duplicates of any error message and notifies the user in interactive
2960 sessions whenever a new error has occurred.
2961 The queue is finite: if its maximum size is reached any new message
2962 replaces the eldest.
2963 The command
2964 .Ic errors
2965 can be used to manage this message queue: if given
2966 .Ar show
2967 or no argument the queue will be displayed and cleared,
2968 .Ar clear
2969 will only clear all messages from the queue.
2972 .It Ic exit
2973 (ex or x) Exit from \*(UA without changing the active mailbox and skip
2974 any saving of messages in
2975 .Ev MBOX
2976 as well as a possibly tracked line editor history file.
2979 .It Ic features
2980 Show the list of features that have been compiled into \*(UA.
2981 (Outputs the contents of the variable
2982 .Va features . )
2985 .It Ic File
2986 (Fi) Like
2987 .Ic file ,
2988 but open the mailbox readonly.
2991 .It Ic file
2992 (fi) The file command switches to a new mailbox.
2993 Without arguments it shows status information of the current mailbox.
2994 If an argument is given, it will write out changes (such as deletions)
2995 the user has made and open a new mailbox.
2996 Some special conventions are recognized for the
2997 .Ar name
2998 argument:
3000 .Bl -tag -compact -offset indent -width ".Ar %:__lespec"
3001 .It Ar #
3002 (number sign) means the previous file,
3003 .It Ar %
3004 (percent sign) means the invoking user's system mailbox,
3005 .It Ar %user
3006 means the system mailbox of
3007 .Ar user
3008 (and never the value of
3009 .Va folder ,
3010 regardless of its actual setting),
3011 .It Ar &
3012 (ampersand) means the invoking user's
3013 .Ev MBOX
3014 file and
3015 .It Ar +file
3016 means a
3017 .Ar file
3018 in the
3019 .Va folder
3020 directory.
3021 .It Ar %:filespec
3022 expands to the same value as
3023 .Ar filespec ,
3024 but the file is handled as a system mailbox by, e.g., the
3025 .Ic mbox
3027 .Ic save
3028 commands, meaning that messages that have been read in the current
3029 session will be moved to the
3030 .Ev MBOX
3031 mailbox instead of simply being flagged as read.
3034 If the name matches one of the strings defined with the command
3035 .Ic shortcut ,
3036 it is replaced by its long form and expanded.
3037 If the name ends with
3038 .Ql .gz ,
3039 .Ql .bz2
3041 .Ql .xz
3042 it is treated as being compressed with
3043 .Xr gzip 1 ,
3044 .Xr bzip2 1
3046 .Xr xz 1 ,
3047 respectively, and transparently handled through an intermediate
3048 (un)compression step (using a temporary file) with the according
3049 facility, sufficient support provided.
3050 Likewise, if the named file doesn't exist, but a file with one of the
3051 mentioned compression extensions does, then the name is automatically
3052 expanded and the compressed file is used.
3054 Otherwise, if the name ends with an extension for which
3055 .Va file-hook-load-EXTENSION
3057 .Va file-hook-save-EXTENSION
3058 variables are set, then the given hooks will be used to load and save
3059 .Dq name ,
3060 and \*(UA will work with an intermediate temporary file.
3062 MBOX files (flat file-based mailboxes) are generally locked during file
3063 operations in order to avoid inconsistencies due to concurrent
3064 modifications.
3065 \*(OPal Mailbox files which \*(UA treats as system or primary mailboxes
3066 will also be protected by so-called dotlock files, the traditional way
3067 of mail spool file locking: for any file
3068 .Ql a
3069 a lock file
3070 .Ql a.lock
3071 will be created for the duration of the synchronization \(em
3072 as necessary a privilege-separated dotlock child process will be used
3073 to accommodate for necessary privilege adjustments in order to create
3074 the dotlock file in the same directory
3075 and with the same user and group identities as the file of interest.
3076 Also see
3077 .Va mbox-rfc4155
3078 for fine-tuning the handling of MBOX files.
3081 .Ar name
3082 refers to a directory with the subdirectories
3083 .Ql tmp ,
3084 .Ql new
3086 .Ql cur ,
3087 then it is treated as a folder in
3088 .Dq Maildir
3089 format.
3090 A name of the form
3092 .Dl \*(IN protocol://[user[:password]@]host[:port][/path]
3093 .Dl \*(OU protocol://[user@]host[:port][/path]
3095 is taken as an Internet mailbox specification.
3096 The \*(OPally supported protocols are
3097 .Ar pop3
3098 (POP3) and
3099 .Ar pop3s
3100 (POP3 with SSL/TLS encrypted transport).
3102 .Ar [/path]
3103 part is valid only for IMAP; there it defaults to
3104 .Ar INBOX .
3105 Also see the section
3106 .Sx "On URL syntax and credential lookup" .
3108 \*(OU If
3109 .Ar user
3110 contains special characters, in particular
3111 .Ql /
3113 .Ql % ,
3114 they must be escaped in URL notation \(en the command
3115 .Ic urlencode
3116 can be used to show the necessary conversion.
3119 .It Ic flag
3120 Takes a message list and marks the messages as
3121 .Ic flag Ns
3122 ged for urgent/special attention.
3123 This mark has no technical meaning in the mail system;
3124 it just causes messages to be highlighted in the header summary,
3125 and makes them specially addressable.
3128 .It Ic folder
3129 (fold) The same as
3130 .Ic file .
3133 .It Ic folders
3134 With no arguments, list the names of the folders in the folder directory.
3135 With an existing folder as an argument,
3136 lists the names of folders below the named folder.
3139 .It Ic Followup
3140 (F) Similar to
3141 .Ic Respond ,
3142 but saves the message in a file named after the local part of the first
3143 recipient's address (instead of in
3144 .Va record Ns ).
3147 .It Ic followup
3148 (fo) Similar to
3149 .Ic respond ,
3150 but saves the message in a file named after the local part of the first
3151 recipient's address (instead of in
3152 .Va record Ns ).
3155 .It Ic followupall
3156 Similar to
3157 .Ic followup ,
3158 but responds to all recipients regardless of the
3159 .Va flipr
3160 variable.
3163 .It Ic followupsender
3164 Similar to
3165 .Ic Followup ,
3166 but responds to the sender only regardless of the
3167 .Va flipr
3168 variable.
3171 .It Ic Forward
3172 Alias for
3173 .Ic Fwd .
3176 .It Ic forward
3177 Alias for
3178 .Ic fwd .
3181 .It Ic from
3182 (f) Takes a list of message specifications and displays a summary of
3183 their message headers, as via
3184 .Ic headers .
3185 An alias of this command is
3186 .Ic search .
3187 Also see
3188 .Sx "Specifying messages" .
3191 .It Ic Fwd
3192 Similar to
3193 .Ic fwd ,
3194 but saves the message in a file named after the local part of the
3195 recipient's address (instead of in
3196 .Va record Ns ).
3199 .It Ic fwd
3200 Takes a message and the address of a recipient
3201 and forwards the message to him.
3202 The text of the original message is included in the new one,
3203 with the value of the
3204 .Va fwdheading
3205 variable preceding it.
3207 .Ic fwdignore
3209 .Ic fwdretain
3210 commands specify which header fields are included in the new message.
3211 Only the first part of a multipart message is included unless the
3212 .Va forward-as-attachment
3213 option is set.
3214 Unless the option
3215 .Va fullnames
3216 is set recipient addresses will be stripped from comments, names etc.
3219 .It Ic fwdignore
3220 Specifies which header fields are to be ignored with the command
3221 .Ic fwd .
3222 This command has no effect when the
3223 .Va forward-as-attachment
3224 option is set.
3227 .It Ic fwdretain
3228 Specifies which header fields are to be retained with the command
3229 .Ic fwd .
3230 .Ic fwdretain
3231 overrides
3232 .Ic fwdignore .
3233 This command has no effect when the
3234 .Va forward-as-attachment
3235 option is set.
3238 .It Ic ghost
3239 Define or list command aliases, so-called ghosts.
3240 Without arguments a list of all currently known aliases is shown.
3241 With one argument the expansion of the given alias is shown.
3242 With two or more arguments a command alias is defined or updated: the
3243 first argument is the name under which the remaining command line should
3244 be accessible, the content of which can be just about anything.
3245 A ghost can be used everywhere a normal command can be used, but always
3246 takes precedence; any arguments that are given to the command alias are
3247 joined onto the alias content, and the resulting string forms the
3248 command line that is, in effect, executed.
3249 Also see
3250 .Ic unghost .
3251 .Bd -literal -offset indent
3252 ? gh xx
3253 `ghost': no such alias: "xx"
3254 ? gh xx echo hello,
3255 ? gh xx
3256 ghost xx "echo hello,"
3257 ? xx
3258 hello,
3259 ? xx world
3260 hello, world
3264 .It Ic headers
3265 (h) Show the current group of headers, the size of which depends on
3266 the variable
3267 .Va screen
3268 and the style of which can be adjusted with the variable
3269 .Va headline .
3270 If a message-specification is given the group of headers containing the
3271 first message therein is shown and the message at the top of the screen
3272 becomes the new
3273 .Dq dot .
3276 .It Ic help
3277 (hel) A synonym for
3278 .Ic \&? .
3281 .It Ic history
3282 \*(OP Either
3283 .Ar show
3285 .Ar clear
3286 the list of history entries;
3287 a decimal
3288 .Ar NUMBER
3289 argument selects and shows the respective history entry \(en
3290 press
3291 .Dq ENTER
3292 to accept it, and the history entry will become the new history top.
3293 The default mode if no arguments are given is
3294 .Ar show .
3297 .It Ic hold
3298 (ho, also
3299 .Ic preserve )
3300 Takes a message list and marks each message therein to be saved in the
3301 user's system mailbox instead of in
3302 .Ev MBOX .
3303 Does not override the
3304 .Ic delete
3305 command.
3306 \*(UA deviates from the POSIX standard with this command, because a
3307 .Ic next
3308 command issued after
3309 .Ic hold
3310 will display the following message, not the current one.
3314 .It Ic if
3315 (i) Part of the nestable
3316 .Ic if Ns / Ns Ic elif Ns / Ns Ic else Ns / Ns Ic endif
3317 conditional execution construct \(em if the given condition is true then
3318 the encapsulated block is executed.
3319 POSIX only supports the (case-insensitive) conditions
3320 .Ql r Ns
3321 eceive
3323 .Ql s Ns
3324 end, all remaining conditions are non-portable extensions; note that
3325 falsely specified conditions cause the execution of the entire
3326 conditional construct until the (matching) closing
3327 .Ic endif
3328 command to be suppressed.
3329 The syntax of the nestable
3330 .Ic if
3331 conditional execution construct requires that each condition and syntax
3332 element is surrounded by whitespace.
3334 .Bd -literal -offset indent
3335 if receive
3336   commands ...
3337 else
3338   commands ...
3339 endif
3343 The (case-insensitive) condition
3344 .Ql t Ns
3345 erminal will evaluate to true if the standard input is a terminal, i.e.,
3346 in interactive sessions.
3347 Another condition can be any boolean value (see the section
3348 .Sx "INTERNAL VARIABLES"
3349 for textual boolean representations) to mark an enwrapped block as
3350 .Dq never execute
3352 .Dq always execute .
3353 It is possible to check
3354 .Sx "INTERNAL VARIABLES"
3355 as well as
3356 .Sx ENVIRONMENT
3357 variables for existence or compare their expansion against a user given
3358 value or another variable by using the
3359 .Ql $
3360 .Pf ( Dq variable next )
3361 conditional trigger character;
3362 a variable on the right hand side may be signalled using the same
3363 mechanism.
3364 The variable names may be enclosed in a pair of matching braces.
3367 The available comparison operators are
3368 .Ql <
3369 (less than),
3370 .Ql <=
3371 (less than or equal to),
3372 .Ql ==
3373 (equal),
3374 .Ql !=
3375 (not equal),
3376 .Ql >=
3377 (greater than or equal to),
3378 .Ql >
3379 (greater than),
3380 .Ql =@
3381 (is substring of) and
3382 .Ql !@
3383 (is not substring of).
3384 The values of the left and right hand side are treated as strings and
3385 are compared 8-bit byte-wise, ignoring case according to the rules of
3386 the US-ASCII encoding (therefore, dependend on the active locale,
3387 possibly producing false results for strings in the locale encoding).
3388 Except for the substring checks the comparison will instead be performed
3389 arithmetically if both, the user given value as well as the variable
3390 content, can be parsed as numbers (integers).
3391 An unset variable is treated as the empty string.
3394 When the \*(OPal regular expression support is available, the additional
3395 test cases
3396 .Ql =~
3398 .Ql !~
3399 can be used.
3400 They treat the right hand side as an extended regular expression that is
3401 matched case-insensitively and according to the active
3402 .Ev LC_CTYPE
3403 locale, meaning that strings in the locale encoding should be matched
3404 correctly.
3407 Conditions can be joined via AND-OR lists (where the AND operator is
3408 .Ql &&
3409 and the OR operator is
3410 .Ql || ) ,
3411 which have equal precedence and will be evaluated with left
3412 associativity, thus using the same syntax that is known for the
3413 .Xr sh 1 .
3414 It is also possible to form groups of conditions and lists by enclosing
3415 them in pairs of brackets
3416 .Ql [\ \&.\&.\&.\ ] ,
3417 which may be interlocked within each other, and also be joined via
3418 AND-OR lists.
3421 The results of individual conditions and entire groups may be modified
3422 via unary operators: the unary operator
3423 .Ql \&!
3424 will reverse the result.
3426 .Bd -literal -offset indent
3427 if $debug
3428   echo *debug* is set
3429 endif
3430 if $ttycharset == "UTF-8"
3431   echo *ttycharset* is set to UTF-8, case-insensitively
3432 endif
3433 set t1=one t2=one
3434 if ${t1} == ${t2}
3435   echo These two variables are equal
3436 endif
3437 if $version-major >= 15
3438   echo Running a new version..
3439   if $features =@ "regex"
3440     if $TERM =~ "^xterm\&.*"
3441       echo ..in an X terminal
3442     endif
3443   endif
3444   if [ [ true ] && [ [ ${debug} ] || [ $verbose ] ] ]
3445     echo Noisy, noisy
3446   endif
3447   if true && $debug || ${verbose}
3448     echo Left associativity, as is known from the shell
3449   endif
3450   if ! ! true && ! [ ! $debug && ! $verbose ]
3451     echo Unary operator support
3452   endif
3453 endif
3458 .It Ic ignore
3459 Without arguments the list of ignored header fields is shown,
3460 otherwise the given list of header fields is added to the ignore list:
3461 Header fields in the ignore list are not shown on the terminal when
3462 a message is displayed.
3463 To display a message in its entirety, use the commands
3464 .Ic Type
3466 .Ic Print .
3467 Also see
3468 .Ic discard
3470 .Ic retain .
3473 .It Ic list
3474 Shows the names of all available commands, alphabetically sorted.
3477 .It Ic localopts
3478 This command can be used to localize changes to variables, meaning that
3479 their state will be reverted to the former one once the covered scope
3480 is left.
3481 It can only be used inside of macro definition blocks introduced by
3482 .Ic account
3484 .Ic define ,
3485 and is interpreted as a boolean (string, see
3486 .Sx "INTERNAL VARIABLES" ) ;
3488 .Dq covered scope
3489 of an account is left once it is switched off again.
3490 .Bd -literal -offset indent
3491 define temporary_settings {
3492   set global_option1
3493   localopts on
3494   set local_option1
3495   set local_option2
3496   localopts off
3497   set global_option2
3501 .Sy Note
3502 that this setting
3503 .Dq stacks up :
3504 i.e., if
3505 .Ql macro1
3506 enables change localization and calls
3507 .Ql macro2 ,
3508 which explicitly resets localization, then any value changes within
3509 .Ql macro2
3510 will still be reverted by
3511 .Ql macro1 !
3514 .It Ic Lreply
3515 Reply to messages that come in via known
3516 .Pf ( Ic mlist )
3517 or subscribed
3518 .Pf ( Ic mlsubscribe )
3519 mailing lists, or pretend to do so (see
3520 .Sx "Mailing lists" ) :
3521 on top of the usual
3522 .Ic reply
3523 functionality this will actively resort and even remove message
3524 recipients in order to generate a message that is supposed to be sent to
3525 a mailing list.
3526 For example it will also implicitly generate a
3527 .Ql Mail-Followup-To:
3528 header if that seems useful, regardless of the setting of the variable
3529 .Va followup-to .
3532 .It Ic Mail
3533 Similar to
3534 .Ic mail ,
3535 but saves the message in a file named after the local part of the first
3536 recipient's address (instead of in
3537 .Va record Ns ).
3540 .It Ic mail
3541 (m) Takes a (list of) recipient address(es) as (an) argument(s),
3542 or asks on standard input if none were given;
3543 then collects the remaining mail content and sends it out.
3546 .It Ic mbox
3547 (mb) The given message list is to be sent to
3548 .Ev MBOX
3549 when \*(UA is quit; this is the default action unless the
3550 .Va hold
3551 option is set.
3552 \*(ID This command can only be used in a system mailbox (see
3553 .Ic file ) .
3556 .It Ic mimetype
3557 Without any arguments the content of the MIME type cache will displayed.
3558 Otherwise each argument defines a complete MIME type specification of
3559 a type that shall be added (prepended) to the cache.
3560 In any event MIME type sources are loaded first as necessary \(en
3561 .Va mimetypes-load-control
3562 can be used to fine-tune which sources are actually loaded.
3563 Refer to the section on
3564 .Sx "The mime.types files"
3565 for more on MIME type specifications and this topic in general.
3566 MIME type unregistration and cache resets can be triggered with
3567 .Ic unmimetype .
3570 .It Ic mlist
3571 Without arguments the list of all currently defined mailing lists
3572 (and their attributes, if any) is shown; a more verbose listing will be
3573 produced if either of
3574 .Va debug
3576 .Va verbose
3577 are set.
3578 Otherwise all given arguments (which need not be quoted except for
3579 whitespace) will be added and henceforth be recognized as mailing lists.
3580 Mailing lists may be removed via the command
3581 .Ic unmlist .
3583 If the \*(OPal regular expression support is available then mailing
3584 lists may also be specified as (extended) regular expressions (see
3585 .Xr re_format 7
3586 for more on those).
3589 .It Ic mlsubscribe
3590 Without arguments the list of all currently defined mailing lists which
3591 have a subscription attribute is shown; a more verbose listing will be
3592 produced if either of
3593 .Va debug
3595 .Va verbose
3596 are set.
3597 Otherwise this attribute will be set for all given mailing lists,
3598 newly creating them as necessary (as via
3599 .Ic mlist ) .
3600 Subscription attributes may be removed via the command
3601 .Ic unmlsubscribe .
3602 Also see
3603 .Va followup-to .
3606 .It Ic Move
3607 Similar to
3608 .Ic move ,
3609 but moves the messages to a file named after the local part of the
3610 sender address of the first message (instead of in
3611 .Va record Ns ).
3614 .It Ic move
3615 Acts like
3616 .Ic copy
3617 but marks the messages for deletion if they were transferred
3618 successfully.
3621 .It Ic More
3622 Like
3623 .Ic more ,
3624 but also displays ignored header fields and all MIME parts.
3625 Identical to
3626 .Ic Page .
3629 .It Ic more
3630 Invokes the
3631 .Ev PAGER
3632 on the given messages, even in non-interactive mode and as long as the
3633 standard output is a terminal.
3634 Identical to
3635 .Ic page .
3638 .It Ic netrc
3639 \*(OP When used without arguments or if
3640 .Ar show
3641 has been given the content of the
3642 .Pa .netrc
3643 cache is shown, loading it first as necessary,
3644 If the argument is
3645 .Ar load
3646 then the cache will only be initialized and
3647 .Ar clear
3648 will remove its contents.
3649 Note that \*(UA will try to load the file only once, use
3650 .Ql Ic netrc Ns \:\0\:clear
3651 to unlock further attempts.
3653 .Va netrc-lookup
3654 and the section
3655 .Sx "On URL syntax and credential lookup" ;
3656 the section
3657 .Sx "The .netrc file"
3658 documents the file format in detail.
3661 .It Ic newmail
3662 Checks for new mail in the current folder without committing any changes
3663 before.
3664 If new mail is present, a message is shown.
3665 If the
3666 .Va header
3667 variable is set,
3668 the headers of each new message are also shown.
3671 .It Ic next
3672 (n) (like
3673 .Ql +
3675 .Dq ENTER )
3676 Goes to the next message in sequence and types it.
3677 With an argument list, types the next matching message.
3680 .It Ic New
3681 Same as
3682 .Ic Unread .
3685 .It Ic new
3686 Same as
3687 .Ic unread .
3690 .It Ic noop
3691 If the current folder is accessed via a network connection, a
3692 .Dq NOOP
3693 command is sent, otherwise no operation is performed.
3696 .It Ic Page
3697 Like
3698 .Ic page ,
3699 but also displays ignored header fields and all MIME parts.
3700 Identical to
3701 .Ic More .
3704 .It Ic page
3705 Invokes the
3706 .Ev PAGER
3707 on the given messages, even in non-interactive mode and as long as the
3708 standard output is a terminal.
3709 Identical to
3710 .Ic more .
3713 .It Ic Pipe
3714 Like
3715 .Ic pipe
3716 but also pipes ignored header fields and all parts of MIME
3717 .Ql multipart/alternative
3718 messages.
3721 .It Ic pipe
3722 (pi) Takes a message list and a shell command
3723 and pipes the messages through the command.
3724 Without an argument the current message is piped through the command
3725 given by the
3726 .Va cmd
3727 variable.
3728 If the
3729 .Va page
3730 variable is set,
3731 every message is followed by a formfeed character.
3734 .It Ic preserve
3735 (pre) A synonym for
3736 .Ic hold .
3739 .It Ic Print
3740 (P) Alias for
3741 .Ic Type .
3744 .It Ic print
3745 (p) Research
3747 equivalent of
3748 .Ic type .
3751 .It Ic quit
3752 (q) Terminates the session, saving all undeleted, unsaved messages in
3753 the current
3754 .Ev MBOX ,
3755 preserving all messages marked with
3756 .Ic hold
3758 .Ic preserve
3759 or never referenced in the system mailbox,
3760 and removing all other messages from the system mailbox.
3761 If new mail has arrived during the session,
3762 the message
3763 .Dq You have new mail
3764 will be shown.
3765 If given while editing a mailbox file with the command line flag
3766 .Fl f ,
3767 then the edit file is rewritten.
3768 A return to the shell is effected,
3769 unless the rewrite of edit file fails,
3770 in which case the user can escape with the exit command.
3773 .It Ic redirect
3774 Same as
3775 .Ic resend .
3778 .It Ic Redirect
3779 Same as
3780 .Ic Resend .
3783 .It Ic remove
3784 Removes the named folders.
3785 The user is asked for confirmation in interactive mode.
3788 .It Ic rename
3789 Takes the name of an existing folder
3790 and the name for the new folder
3791 and renames the first to the second one.
3792 Both folders must be of the same type.
3795 .It Ic Reply
3796 (R) Reply to originator.
3797 Does not reply to other recipients of the original message.
3798 .Va flipr
3799 will exchange this command with
3800 .Ic reply .
3801 Unless the option
3802 .Va fullnames
3803 is set the recipient address will be stripped from comments, names etc.
3806 .It Ic reply
3807 (r) Take a message and group-responds to it by addressing the sender
3808 and all recipients.
3809 .Va followup-to ,
3810 .Va followup-to-honour ,
3811 .Va reply-to-honour
3812 as well as
3813 .Va recipients-in-cc
3814 influence response behaviour.
3815 The command
3816 .Ic Lreply
3817 offers special support for replying to mailing lists.
3818 Unless the option
3819 .Va fullnames
3820 is set recipient addresses will be stripped from comments, names etc.
3822 .Va flipr
3823 is set the commands
3824 .Ic Reply
3826 .Ic reply
3827 are exchanged.
3830 .It Ic replyall
3831 Similar to
3832 .Ic reply ,
3833 but initiates a group-reply regardless of the value of
3834 .Va flipr .
3837 .It Ic replysender
3838 Similar to
3839 .Ic Reply ,
3840 but responds to the sender only regardless of the value of
3841 .Va flipr .
3844 .It Ic Resend
3845 Like
3846 .Ic resend ,
3847 but does not add any header lines.
3848 This is not a way to hide the sender's identity,
3849 but useful for sending a message again to the same recipients.
3852 .It Ic resend
3853 Takes a list of messages and a user name
3854 and sends each message to the named user.
3855 .Ql Resent-From:
3856 and related header fields are prepended to the new copy of the message.
3859 .It Ic Respond
3860 Same as
3861 .Ic Reply .
3864 .It Ic respond
3865 Same as
3866 .Ic reply .
3869 .It Ic respondall
3870 Same as
3871 .Ic replyall .
3874 .It Ic respondsender
3875 Same as
3876 .Ic replysender .
3879 .It Ic retain
3880 (ret) Without arguments the list of retained header fields is shown,
3881 otherwise the given list of header fields is added to the retain list:
3882 Header fields in the retain list are shown on the terminal when
3883 a message is displayed, all other header fields are suppressed.
3884 To display a message in its entirety, use the commands
3885 .Ic Type
3887 .Ic Print .
3888 Also see
3889 .Ic discard
3891 .Ic ignore ;
3892 .Ic retain
3893 takes precedence over the mentioned.
3896 .It Ic Save
3897 (S) Similar to
3898 .Ic save,
3899 but saves the messages in a file named after the local part of the
3900 sender of the first message instead of (in
3901 .Va record
3902 and) taking a filename argument.
3905 .It Ic save
3906 (s) Takes a message list and a filename and appends each message in turn
3907 to the end of the file.
3908 If no filename is given, the
3909 .Ev MBOX
3910 file is used.
3911 The filename in quotes, followed by the generated character count
3912 is echoed on the user's terminal.
3913 If editing a system mailbox the messages are marked for deletion.
3914 Filename interpretation as described for the
3915 .Ic file
3916 command is performed.
3919 .It Ic savediscard
3920 Same as
3921 .Ic saveignore .
3924 .It Ic saveignore
3925 Is to
3926 .Ic save
3927 what
3928 .Ic ignore
3929 is to
3930 .Ic print
3932 .Ic type .
3933 Header fields thus marked are filtered out when saving a message by
3934 .Ic save
3935 or when automatically saving to
3936 .Ev MBOX .
3937 This command should only be applied to header fields that do not contain
3938 information needed to decode the message,
3939 as MIME content fields do.
3942 .It Ic saveretain
3943 Is to
3944 .Ic save
3945 what
3946 .Ic retain
3947 is to
3948 .Ic print
3950 .Ic type .
3951 Header fields thus marked are the only ones saved with a message when
3952 saving by
3953 .Ic save
3954 or when automatically saving to
3955 .Ev MBOX .
3956 .Ic saveretain
3957 overrides
3958 .Ic saveignore .
3959 The use of this command is strongly discouraged since it may strip
3960 header fields that are needed to decode the message correctly.
3963 .It Ic search
3964 Takes a message specification (list) and displays a header summary of
3965 all matching messages, as via
3966 .Ic headers .
3967 This command is an alias of
3968 .Ic from .
3969 Also see
3970 .Sx "Specifying messages" .
3973 .It Ic seen
3974 Takes a message list and marks all messages as having been read.
3977 .It Ic set
3978 (se) Without arguments this command shows all variables and their
3979 values which are currently known to \*(UA.
3980 Setting any of the variables
3981 .Va bsdcompat
3983 .Va bsdset
3984 changes the output format to BSD style, otherwise a properly quoted
3985 listing is produced.
3987 .Va debug
3988 is set or
3989 .Va verbose
3990 has been set twice then the listing is modified to mark out assembled
3991 variables.
3993 Otherwise modifies (set and unsets) the given variables.
3994 Arguments are of the form
3995 .Ql option=value
3996 (no space before or after
3997 .Ql = ) ,
3998 or plain
3999 .Ql option
4000 if there is no value.
4001 Quotation marks may be placed around any part of the assignment
4002 statement to quote blanks or tabs, e.g.,
4004 .Dl set indentprefix="->"
4006 If an argument begins with
4007 .Ql no ,
4008 as in
4009 .Ql set nosave ,
4010 the effect is the same as invoking the
4011 .Ic unset
4012 command with the remaining part of the variable
4013 .Pf ( Ql unset save ) .
4016 .It Ic setenv
4017 Identical to
4018 .Ic set
4019 except that the variables are also exported into the program environment;
4020 since this task requires native host support the command will always
4021 report error if that is not available (but still act like
4022 .Ic set
4023 in this case).
4024 This operation is a no-op unless all resource files have been loaded.
4025 Also see
4026 .Ic unsetenv .
4029 .It Ic shell
4030 (sh) Invokes an interactive version of the shell.
4033 .It Ic shortcut
4034 Without arguments the list of all currently defined shortcuts is
4035 shown.
4036 Otherwise all given arguments (which need not be quoted except for
4037 whitespace) are treated as pairs of shortcuts and their expansions,
4038 creating new or changing already existing shortcuts, as necessary.
4039 Shortcuts may be removed via the command
4040 .Ic unshortcut .
4041 The expansion strings should be in the syntax that has been described
4042 for the
4043 .Ic file
4044 command.
4047 .It Ic show
4048 Like
4049 .Ic type ,
4050 but performs neither MIME decoding nor decryption, so that the raw
4051 message text is shown.
4054 .It Ic size
4055 (si) Shows the size in characters of each message of the given
4056 message-list.
4059 .It Ic sort
4060 Shows the current sorting criterion when used without an argument.
4061 Otherwise creates a sorted representation of the current folder,
4062 and changes the
4063 .Ic next
4064 command and the addressing modes such that they refer to messages in
4065 the sorted order.
4066 Message numbers are the same as in regular mode.
4067 If the
4068 .Va header
4069 variable is set,
4070 a header summary in the new order is also displayed.
4071 Automatic folder sorting can be enabled by setting the
4072 .Va autosort
4073 variable, as in, e.g.,
4074 .Ql set autosort=thread .
4075 Possible sorting criterions are:
4077 .Bl -tag -compact -offset indent -width "subject"
4078 .It date
4079 Sort the messages by their
4080 .Ql Date:
4081 field, that is by the time they were sent.
4082 .It from
4083 Sort messages by the value of their
4084 .Ql From:
4085 field, that is by the address of the sender.
4086 If the
4087 .Va showname
4088 variable is set, the sender's real name (if any) is used.
4089 .It size
4090 Sort the messages by their size.
4091 .It spam
4092 \*(OP Sort the message by their spam score, as has been classified by
4093 .Ic spamrate .
4094 .It status
4095 Sort the messages by their message status.
4096 .It subject
4097 Sort the messages by their subject.
4098 .It thread
4099 Create a threaded display.
4100 .It to
4101 Sort messages by the value of their
4102 .Ql To:
4103 field, that is by the address of the recipient.
4104 If the
4105 .Va showname
4106 variable is set, the recipient's real name (if any) is used.
4110 .It Ic source
4111 (so) The source command reads commands from the given file, which is
4112 subject to the usual filename expansions (see introductional words of
4113 .Sx COMMANDS ) .
4114 If the given argument ends with a vertical bar
4115 .Ql |
4116 then the argument will instead be interpreted as a shell command and
4117 \*(UA will read the output generated by it.
4120 .It Ic source_if
4121 The difference to
4122 .Ic source
4123 (beside not supporting pipe syntax a.k.a. shell command input) is that
4124 this command will not generate an error if the given file argument
4125 cannot be opened successfully.
4126 This can matter in, e.g., resource files, since loading of those is
4127 stopped when an error is encountered.
4130 .It Ic spamclear
4131 \*(OP Takes a list of messages and clears their
4132 .Ql is-spam
4133 flag.
4136 .It Ic spamforget
4137 \*(OP Takes a list of messages and causes the
4138 .Va spam-interface
4139 to forget it has ever used them to train its Bayesian filter.
4140 Unless otherwise noted the
4141 .Ql is-spam
4142 flag of the message is inspected to chose wether a message shall be
4143 forgotten to be
4144 .Dq ham
4146 .Dq spam .
4149 .It Ic spamham
4150 \*(OP Takes a list of messages and informs the Bayesian filter of the
4151 .Va spam-interface
4152 that they are
4153 .Dq ham .
4154 This also clears the
4155 .Ql is-spam
4156 flag of the messages in question.
4159 .It Ic spamrate
4160 \*(OP Takes a list of messages and rates them using the configured
4161 .Va spam-interface ,
4162 without modifying the messages, but setting their
4163 .Ql is-spam
4164 flag as appropriate; because the spam rating headers are lost the rate
4165 will be forgotten once the mailbox is left.
4166 Refer to the manual section
4167 .Sx "Handling spam"
4168 for the complete picture of spam handling in \*(UA.
4171 .It Ic spamset
4172 \*(OP Takes a list of messages and sets their
4173 .Ql is-spam
4174 flag.
4177 .It Ic spamspam
4178 \*(OP Takes a list of messages and informs the Bayesian filter of the
4179 .Va spam-interface
4180 that they are
4181 .Dq spam .
4182 This also sets the
4183 .Ql is-spam
4184 flag of the messages in question.
4187 .It Ic thread
4188 \*(OB The same as
4189 .Ql sort thread
4190 (consider using a
4191 .Ql ghost
4192 as necessary).
4193 Create a threaded representation of the current folder,
4194 i.\|e. indent messages that are replies to other messages in the header
4195 display and change the
4196 .Ic next
4197 command and the addressing modes such that they refer to messages in the
4198 threaded order.
4199 Message numbers are the same as in unthreaded mode.
4200 If the
4201 .Va header
4202 variable is set,
4203 a header summary in threaded order is also displayed.
4206 .It Ic top
4207 (to) Takes a message list and displays the top few lines of each.
4208 The number of lines shown is controlled by the variable
4209 .Va toplines
4210 and defaults to five.
4213 .It Ic touch
4214 (tou) Takes a message list and marks the messages for saving in
4215 .Ev MBOX .
4216 \*(UA deviates from the POSIX standard with this command,
4217 as a following
4218 .Ic next
4219 command will display the following message instead of the current one.
4222 .It Ic Type
4223 (T) Like
4224 .Ic type
4225 but also displays out ignored header fields and all parts of MIME
4226 .Ql multipart/alternative
4227 messages.
4230 .It Ic type
4231 (t) Takes a message list and types out each message on the user's
4232 terminal, honouring
4233 .Ic ignore
4235 .Ic retain
4236 lists.
4237 For MIME multipart messages, all parts with a content type of
4238 .Ql text
4240 .Ql message
4241 are shown, the other are hidden except for their headers.
4242 Messages are decrypted and converted to the terminal character set
4243 if necessary.
4246 .It Ic unaccount
4247 Delete all given accounts.
4248 An error message is shown if a given account is not defined.
4249 The special name
4250 .Ql *
4251 will discard all existing accounts.
4254 .It Ic unalias
4255 (una) Takes a list of names defined by alias commands
4256 and discards the remembered groups of users.
4257 The special name
4258 .Ql *
4259 will discard all existing aliases.
4262 .It Ic unanswered
4263 Takes a message list and marks each message as not having been answered.
4266 .It Ic uncollapse
4267 Only applicable to threaded mode.
4268 Takes a message list and makes the message and all replies to it visible
4269 in header summaries again.
4270 When a message becomes the current message,
4271 it is automatically made visible.
4272 Also when a message with collapsed replies is displayed,
4273 all of these are automatically uncollapsed.
4276 .It Ic uncolour
4277 Forget about a
4278 .Ic colour
4279 mapping for the given colour type (see
4280 .Ic colour
4281 for a list of types) and mapping; if the optional precondition argument
4282 is used then only the exact tuple of mapping and precondition is removed.
4283 The special name
4284 .Ql *
4285 will remove all mappings (no precondition allowed).
4286 Also see
4287 .Sx "Coloured display"
4288 for the general picture.
4291 .It Ic uncustomhdr
4292 Deletes the custom headers given as arguments.
4293 The special name
4294 .Ql *
4295 will remove all custom headers.
4298 .It Ic undefine
4299 Undefine all given macros.
4300 An error message is shown if a given macro is not defined.
4301 The special name
4302 .Ql *
4303 will discard all existing macros.
4306 .It Ic undelete
4307 (u) Takes a message list and marks each message as not being deleted.
4310 .It Ic undraft
4311 Takes a message list and
4312 .Pf un Ic draft Ns
4313 s each message.
4316 .It Ic unflag
4317 Takes a message list and marks each message as not being
4318 .Ic flag Ns ged .
4321 .It Ic unfwdignore
4322 Removes the header field names from the list of ignored fields for the
4323 .Ic forward
4324 command.
4325 The special name
4326 .Ql *
4327 will remove all fields.
4330 .It Ic unfwdretain
4331 Removes the header field names from the list of retained fields for the
4332 .Ic forward
4333 command.
4334 The special name
4335 .Ql *
4336 will remove all fields.
4339 .It Ic unghost
4340 Remove all the given command
4341 .Ic ghost Ns s Ns .
4342 The special name
4343 .Ql *
4344 will remove all ghosts.
4347 .It Ic unignore
4348 Removes the header field names from the list of ignored fields.
4349 The special name
4350 .Ql *
4351 will remove all fields.
4354 .It Ic unmimetype
4355 Delete all given MIME types, e.g.,
4356 .Ql unmimetype text/plain
4357 will remove all registered specifications for the MIME type
4358 .Ql text/plain .
4359 The special name
4360 .Ql *
4361 will discard all existing MIME types, just as will
4362 .Ql reset ,
4363 but which also reenables cache initialization via
4364 .Va mimetypes-load-control .
4367 .It Ic unmlist
4368 Forget about all the given mailing lists.
4369 The special name
4370 .Ql *
4371 will remove all lists.
4372 Also see
4373 .Ic mlist .
4376 .It Ic unmlsubscribe
4377 Remove the subscription attribute from all given mailing lists.
4378 The special name
4379 .Ql *
4380 will clear the attribute from all lists which have it set.
4381 Also see
4382 .Ic mlsubscribe .
4385 .It Ic Unread
4386 Same as
4387 .Ic unread .
4390 .It Ic unread
4391 Takes a message list and marks each message as not having been read.
4394 .It Ic unretain
4395 Removes the header field names from the list of retained fields.
4396 The special name
4397 .Ql *
4398 will remove all fields.
4401 .It Ic unsaveignore
4402 Removes the header field names from the list of ignored fields for
4403 saving.
4404 The special name
4405 .Ql *
4406 will remove all fields.
4409 .It Ic unsaveretain
4410 Removes the header field names from the list of retained fields for
4411 saving.
4412 The special name
4413 .Ql *
4414 will remove all fields.
4417 .It Ic unset
4418 (uns) Takes a list of option names and discards their remembered values;
4419 the reverse of
4420 .Ic set .
4423 .It Ic unsetenv
4424 Identical to
4425 .Ic unset
4426 except that the variables are also removed from the program environment;
4427 since this task requires native host support the command will always
4428 report error if that is not available (but still act like
4429 .Ic unset Ns
4431 This operation is a no-op unless all resource files have been loaded.
4432 Also see
4433 .Ic setenv .
4436 .It Ic unshortcut
4437 Deletes the shortcut names given as arguments.
4438 The special name
4439 .Ql *
4440 will remove all shortcuts.
4443 .It Ic unsort
4444 Disable sorted or threaded mode
4445 (see the
4446 .Ic sort
4448 .Ic thread
4449 commands),
4450 return to normal message order and,
4451 if the
4452 .Va header
4453 variable is set,
4454 displays a header summary.
4457 .It Ic unthread
4458 \*(OB
4459 Same as
4460 .Ic unsort .
4463 .It Ic urldecode
4464 Decode the given URL-encoded string arguments and show the results.
4465 Note the resulting strings may not be valid in the current locale, see
4466 .Ic urlencode .
4469 .It Ic urlencode
4470 URL-encode the given arguments and show the results.
4471 Because the arguments effectively are in the character set of the
4472 current locale the results will vary accordingly unless the input solely
4473 consists of characters in the portable character set, see
4474 .Sx "Character sets" .
4477 .It Ic varedit
4478 Edit the values of or create the given variable(s) in the
4479 .Ev EDITOR .
4480 Boolean variables cannot be edited.
4483 .It Ic varshow
4484 Show informations about all the given variables.
4485 \*(UA knows about a finite set of known builtin variables that are
4486 subdivided further in boolean and value variants;
4487 they may have special properties, like
4488 .Dq read-only
4489 (setting may not be changed) and
4490 .Dq virtual ,
4491 meaning that the value is generated on-the-fly as necessary.
4492 Beside those known variables an infinite number of unknown, so-called
4493 .Dq assembled
4494 variables, which are expected to be able to store values, may exist.
4495 .Bd -literal -offset indent
4496 ? set foo=bar nobar
4497 ? varshow sendwait version-major foo bar
4498 "sendwait": (73) boolean: set=1 (ENVIRON=0)
4499 "version-major": (192) value, read-only, virtual:\e
4500   set=1 (ENVIRON=0) value<14>
4501 "foo": (assembled) set=1 (ENVIRON=0) value<bar>
4502 "bar": (assembled) set=0 (ENVIRON=0) value<NULL>
4506 .It Ic verify
4507 \*(OP Takes a message list and verifies each message.
4508 If a message is not a S/MIME signed message,
4509 verification will fail for it.
4510 The verification process checks if the message was signed using a valid
4511 certificate,
4512 if the message sender's email address matches one of those contained
4513 within the certificate,
4514 and if the message content has been altered.
4517 .It Ic visual
4518 (v) Takes a message list and invokes the display editor on each message.
4519 Modified contents are discarded unless the
4520 .Va writebackedited
4521 variable is set.
4524 .It Ic write
4525 (w) For conventional messages the body without all headers is written.
4526 The output is decrypted and converted to its native format as necessary.
4527 If the output file exists, the text is appended.
4528 If a message is in MIME multipart format its first part is written to
4529 the specified file as for conventional messages,
4530 and the user is asked for a filename to save each other part.
4531 For convience saving of each part may be skipped by giving an empty value;
4532 the same result can also be achieved by writing it to
4533 .Pa /dev/null .
4534 For the second and subsequent parts a leading
4535 .Ql |
4536 character causes the part to be piped to the remainder of the user input
4537 interpreted as a shell command;
4538 otherwise the user input is expanded as usually for folders,
4539 e.g., tilde expansion is performed.
4540 In non-interactive mode, only the parts of the multipart message
4541 that have a filename given in the part header are written,
4542 the others are discarded.
4543 The original message is never marked for deletion in the originating
4544 mail folder.
4545 For attachments,
4546 the contents of the destination file are overwritten if the file
4547 previously existed.
4548 No special handling of compressed files is performed.
4551 .It Ic xit
4552 (x) A synonym for
4553 .Ic exit .
4556 .It Ic z
4557 \*(UA presents message headers in windowfuls as described under the
4558 .Ic headers
4559 command.
4560 This command scrolls to the next window of messages.
4561 If an argument is given,
4562 it specifies the window to use.
4563 A number prefixed by
4564 .Ql +
4566 .Ql \-
4567 indicates that the window is calculated in relation to the current position.
4568 A number without a prefix specifies an absolute window number,
4569 and a
4570 .Ql $
4571 lets \*(UA scroll to the last window of messages.
4574 .It Ic Z
4575 Similar to
4576 .Ic z ,
4577 but scrolls to the next or previous window that contains at least one
4578 .Ql new
4580 .Ic flag Ns
4581 ged message.
4583 .\" }}}
4586 .\" .Sh TILDE ESCAPES {{{
4587 .Sh "TILDE ESCAPES"
4589 Here is a summary of the tilde escapes,
4590 which are used to perform special functions when composing messages.
4591 Tilde escapes are only recognized at the beginning of lines.
4592 The name
4593 .Dq tilde escape
4594 is somewhat of a misnomer since the actual escape character can be
4595 changed by adjusting the option
4596 .Va escape .
4598 .Bl -tag -width ".Ic __ filename"
4600 .It Ic ~~ Ar string
4601 Insert the string of text in the message prefaced by a single
4602 .Ql ~ .
4603 (If the escape character has been changed,
4604 that character must be doubled
4605 in order to send it at the beginning of a line.)
4608 .It Ic ~! Ar command
4609 Execute the indicated shell
4610 .Ar command ,
4611 then return to the message.
4614 .It Ic ~.
4615 Same effect as typing the end-of-file character.
4618 .It Ic ~: Ar \*(UA-command Ns \0or Ic ~_ Ar \*(UA-command
4619 Execute the given \*(UA command.
4620 Not all commands, however, are allowed.
4623 .It Ic ~?
4624 Write a summary of command escapes.
4627 .It Ic ~< Ar filename
4628 Identical to
4629 .Ic ~r .
4632 .It Ic ~<! Ar command
4633 .Ar command
4634 is executed using the shell.
4635 Its standard output is inserted into the message.
4638 .It Ic ~@ Op Ar filename...
4639 With no arguments, edit the attachment list interactively.
4640 If an attachment's file name is left empty,
4641 that attachment is deleted from the list.
4642 When the end of the attachment list is reached,
4643 \*(UA will ask for further attachments until an empty name is given.
4644 If a given file name solely consists of the number sign
4645 .Ql #
4646 followed by a valid message number of the currently active mailbox, then
4647 the given message is attached as a MIME
4648 .Ql message/rfc822
4649 and the rest of this section does not apply.
4651 If character set conversion has been compiled into \*(UA, then this mode
4652 gives the user the option to specify input and output character sets,
4653 unless the file extension indicates binary content, in which case \*(UA
4654 asks wether this step shall be skipped for the attachment in question.
4655 If not skipped, then the charset that succeeds to represent the
4656 attachment data will be used in the
4657 .Ql charset=
4658 MIME parameter of the mail message:
4660 .Bl -bullet -compact
4662 If input and output character sets are specified, then the conversion is
4663 performed on the fly.
4664 The user will be asked repeatedly until the desired conversion succeeds.
4666 If only an output character set is specified, then the input is assumed
4667 to be in the
4668 .Va ttycharset
4669 charset and will be converted to the given output charset on the fly.
4670 The user will be asked repeatedly until the desired conversion succeeds.
4672 If no character sets are specified at all then the algorithm that is
4673 documented in the section
4674 .Sx "Character sets"
4675 is applied, but directly and on the fly.
4676 The user will be asked repeatedly until the desired conversion succeeds.
4678 Finally, if an input-, but no output character set is specified, then no
4679 conversion is ever performed, but the
4680 .Ql charset=
4681 MIME parameter value will still be set to the user input.
4683 The character set selection loop can be left by typing
4684 .Ql control-C ,
4685 i.e., causing an interrupt.
4686 .\" \*(OU next sentence
4687 Note that before \*(UA version 15.0 this terminates the entire
4688 current attachment selection, not only the character set selection.
4691 Without character set conversion support, \*(UA will ask for the input
4692 character set only, and it'll set the
4693 .Ql charset=
4694 MIME parameter value to the given input, if any;
4695 if no user input is seen then the
4696 .Va ttycharset
4697 character set will be used for the parameter value instead.
4698 Note that the file extension check isn't performed in this mode, since
4699 no conversion will take place anyway.
4701 Note that in non-interactive mode, for reproduceabilities sake, there
4702 will always be two questions for each attachment, regardless of wether
4703 character set conversion is available and what the file extension is.
4704 The first asks for the filename, and the second asks for the input
4705 character set to be passed through to the corresponding MIME parameter;
4706 no conversion will be tried if there is input to the latter question,
4707 otherwise the usual conversion algorithm, as above, is applied.
4708 For message attachments, the answer to the second question is completely
4709 ignored.
4711 If (instead)
4712 .Ar filename
4713 arguments are specified for the
4714 .Ic \&\&~@
4715 command they are treated as a comma-separated list of files,
4716 which are all expanded and appended to the end of the attachment list.
4717 (Commas need to be escaped with backslash, but filenames with leading or
4718 trailing whitespace can only be added via the command line or the first
4719 method.
4720 Message attachments can only be added via the first method;
4721 filenames which clash with message numbers can only be added via the
4722 command line or the second method.)
4723 In this mode the (text) attachments are assumed to be in
4724 .Va ttycharset
4725 encoding, and will be evaluated as documented in the section
4726 .Sx "Character sets" .
4729 .It Ic ~A
4730 Inserts the string contained in the
4731 .Va Sign
4732 variable (same as
4733 .Ql Ic ~i Ns \0Sign ) .
4734 The escape sequences tabulator
4735 .Ql \et
4736 and newline
4737 .Ql \en
4738 are understood.
4741 .It Ic ~a
4742 Inserts the string contained in the
4743 .Va sign
4744 variable (same as
4745 .Ql Ic ~i Ns \0sign ) .
4746 The escape sequences tabulator
4747 .Ql \et
4748 and newline
4749 .Ql \en
4750 are understood.
4753 .It Ic ~b Ar name ...
4754 Add the given names to the list of blind carbon copy recipients.
4757 .It Ic ~c Ar name ...
4758 Add the given names to the list of carbon copy recipients.
4761 .It Ic ~d
4762 Read the file specified by the
4763 .Ev DEAD
4764 variable into the message.
4767 .It Ic ~e
4768 Invoke the text editor on the message collected so far.
4769 After the editing session is finished,
4770 the user may continue appending text to the message.
4773 .It Ic ~F Ar messages
4774 Read the named messages into the message being sent, including all
4775 message headers and MIME parts.
4776 If no messages are specified, read in the current message.
4779 .It Ic ~f Ar messages
4780 Read the named messages into the message being sent.
4781 If no messages are specified, read in the current message.
4782 .Ic ignore
4784 .Ic retain
4785 lists are used to modify the message headers.
4786 For MIME multipart messages,
4787 only the first displayable part is included.
4790 .It Ic ~H
4791 Edit the message header fields
4792 .Ql From: ,
4793 .Ql Reply-To:
4795 .Ql Sender:
4796 by typing each one in turn and allowing the user to edit the field.
4797 The default values for these fields originate from the
4798 .Va from , replyto
4800 .Va sender
4801 variables.
4804 .It Ic ~h
4805 Edit the message header fields
4806 .Ql To: ,
4807 .Ql Cc: ,
4808 .Ql Bcc:
4810 .Ql Subject:
4811 by typing each one in turn and allowing the user to edit the field.
4814 .It Ic ~i Ar variable
4815 Insert the value of the specified variable into the message,
4816 adding a newline character at the end.
4817 The message remains unaltered if the variable is unset or empty.
4818 The escape sequences tabulator
4819 .Ql \et
4820 and newline
4821 .Ql \en
4822 are understood.
4825 .It Ic ~M Ar messages
4826 Read the named messages into the message being sent,
4827 indented by
4828 .Va indentprefix .
4829 If no messages are specified, read the current message.
4832 .It Ic ~m Ar messages
4833 Read the named messages into the message being sent,
4834 indented by
4835 .Va indentprefix .
4836 If no messages are specified, read the current message.
4837 .Ic ignore
4839 .Ic retain
4840 lists are used to modify the message headers.
4841 For MIME multipart messages,
4842 only the first displayable part is included.
4845 .It Ic ~p
4846 Display the message collected so far,
4847 prefaced by the message header fields
4848 and followed by the attachment list, if any.
4851 .It Ic ~q
4852 Abort the message being sent,
4853 copying it to the file specified by the
4854 .Ev DEAD
4855 variable if
4856 .Va save
4857 is set.
4860 .It Ic ~R Ar filename
4861 Read the named file into the message, indented by
4862 .Va indentprefix .
4865 .It Ic ~r Ar filename
4866 Read the named file into the message.
4869 .It Ic ~s Ar string
4870 Cause the named string to become the current subject field.
4873 .It Ic ~t Ar name ...
4874 Add the given name(s) to the direct recipient list.
4877 .It Ic ~U Ar messages
4878 Read in the given / current message(s) excluding all headers, indented by
4879 .Va indentprefix .
4882 .It Ic ~u Ar messages
4883 Read in the given / current message(s), excluding all headers.
4886 .It Ic ~v
4887 Invoke an alternate editor (defined by the
4888 .Ev VISUAL
4889 option) on the message collected so far.
4890 Usually, the alternate editor will be a screen editor.
4891 After the editor is quit,
4892 the user may resume appending text to the end of the message.
4895 .It Ic ~w Ar filename
4896 Write the message onto the named file.
4897 If the file exists,
4898 the message is appended to it.
4901 .It Ic ~x
4902 Same as
4903 .Ic ~q ,
4904 except that the message is not saved at all.
4907 .It Ic ~| Ar command
4908 Pipe the message through the specified filter command.
4909 If the command gives no output or terminates abnormally,
4910 retain the original text of the message.
4911 E.g., the command
4912 .Xr fmt 1
4913 is often used as a rejustifying filter.
4915 .\" }}}
4918 .\" .Sh INTERNAL VARIABLES {{{
4919 .Sh "INTERNAL VARIABLES"
4921 Internal \*(UA variables are controlled via the
4922 .Ic set
4924 .Ic unset
4925 commands; prefixing a variable name with the string
4926 .Ql no
4927 and calling
4928 .Ic set
4929 has the same effect as using
4930 .Ic unset :
4931 .Ql unset crt
4933 .Ql set nocrt
4934 do the same thing.
4935 Creation or editing of variables can be performed in the
4936 .Ev EDITOR
4937 with the command
4938 .Ic varedit .
4939 .Ic varshow
4940 will give more insight on the given variable(s), and
4941 .Ic set ,
4942 when called without arguments, will show a listing of all variables.
4943 Variables are also implicitly inherited from the program
4944 .Sx ENVIRONMENT
4945 and can be set explicitly via the command line option
4946 .Fl S .
4949 Two different kind of variables exist.
4950 There are boolean variables, which can only be in one of the two states
4951 .Dq set
4953 .Dq unset ,
4954 and value variables with a(n optional) string value.
4955 For the latter proper quoting is necessary upon assignment time:
4956 To embed whitespace (space and tabulator) in a value it either needs to
4957 be escaped with a backslash character, or the entire value must be
4958 enclosed in (double or single) quotation marks;
4959 To use quotation marks identical to those used to enclose the value,
4960 escape them with a backslash character.
4961 The backslash character has no special meaning except in these cases.
4963 .Bd -literal -offset indent
4964 set one=val\e 1 two="val 2" \e
4965     three='val "3"' four='val \e'4\e''
4966 varshow one two three four
4967 unset one two three four
4971 Dependent upon the actual option the string values will be interpreted
4972 as numbers, colour names, normal text etc., but there also exists
4973 a special kind of string value, the
4974 .Dq boolean string ,
4975 which must either be a decimal integer (in which case
4976 .Ql 0
4977 is false and
4978 .Ql 1
4979 and any other value is true) or any of the (case-insensitive) strings
4980 .Ql off ,
4981 .Ql no
4983 .Ql false
4984 for a false boolean and
4985 .Ql on ,
4986 .Ql yes
4988 .Ql true
4989 for a true boolean; a special kind of boolean string is the
4990 .Dq quadoption ,
4991 which is a boolean string that can optionally be prefixed with the
4992 (case-insensitive) term
4993 .Ql ask- ,
4994 as in
4995 .Ql ask-yes ,
4996 which causes prompting of the user in interactive mode, with the given
4997 boolean as the default value.
4999 .\" .Ss "Initial settings" {{{
5000 .\" (Keep in SYNC: ./main.c:_startup(), ./nail.rc, ./nail.1:"Initial settings"!)
5001 .Ss "Initial Settings"
5003 The standard POSIX 2008/Cor 1-2013 mandates the following initial
5004 variable settings:
5005 .Pf no Va allnet ,
5006 .Pf no Va append ,
5007 .Va asksub ,
5008 .Pf no Va askbcc ,
5009 .Pf no Va autoprint ,
5010 .Pf no Va bang ,
5011 .Pf no Va cmd ,
5012 .Pf no Va crt ,
5013 .Pf no Va debug ,
5014 .Pf no Va dot ,
5015 .Va escape
5016 set to
5017 .Ql ~ ,
5018 .Pf no Va flipr ,
5019 .Pf no Va folder ,
5020 .Va header ,
5021 .Pf no Va hold ,
5022 .Pf no Va ignore ,
5023 .Pf no Va ignoreeof ,
5024 .Pf no Va keep ,
5025 .Pf no Va keepsave ,
5026 .Pf no Va metoo ,
5027 .Pf no Va outfolder ,
5028 .Pf no Va page ,
5029 .Va prompt
5030 set to
5031 .Ql ?\0
5032 (note that \*(UA deviates from the standard by using
5033 .Ql \e&\0 ,
5034 but the
5035 .Ql \e&
5036 special prompt escape results in
5037 .Dq \&?
5038 being shown unless
5039 .Va bsdcompat
5040 is set),
5041 .Pf no Va quiet ,
5042 .Pf no Va record ,
5043 .Va save ,
5044 .Pf no Va sendwait ,
5045 .Pf no Va showto ,
5046 .Pf no Va Sign ,
5047 .Pf no Va sign ,
5048 .Va toplines
5049 set to
5050 .Ql 5 .
5053 Notes: \*(UA doesn't support the
5054 .Pf no Va onehop
5055 variable \(en use command line options or
5056 .Va sendmail-arguments
5057 to pass options through to a MTA.
5058 And the default global
5059 .Pa \*(UR
5060 file (which is loaded unless the
5061 .Fl n
5062 command line flag has been used or the
5063 .Ev NAIL_NO_SYSTEM_RC
5064 environment variable is set) bends those initial settings a bit, e.g.,
5065 it sets the variables
5066 .Va hold ,
5067 .Va keepsave
5069 .Va keep ,
5070 to name a few, calls
5071 .Ic retain
5072 etc., and should thus be taken into account.
5073 .\" }}}
5075 .\" .Ss "Variables" {{{
5076 .Ss "Variables"
5078 .Bl -tag -width ".It Va _utoprin_"
5080 .It Va add-file-recipients
5081 \*(BO When file or pipe recipients have been specified,
5082 mention them in the corresponding address fields of the message instead
5083 of silently stripping them from their recipient list.
5084 By default such addressees are not mentioned.
5086 .Mx Va agent-shell-lookup
5087 .It Va agent-shell-lookup-USER@HOST , agent-shell-lookup-HOST , \
5088   agent-shell-lookup
5089 \*(IN\*(OP Account passwords can be fetched via an external agent
5090 program in order to permit encrypted password storage \(en see
5091 .Sx "On URL syntax and credential lookup"
5092 for more on credential lookup.
5093 If this is set then the content is interpreted as a shell command the
5094 output of which (with newline characters removed) is treated as the
5095 account password shall the command succeed (and have produced non-empty
5096 non-newline output); e.g., via
5097 .Xr gpg 1 :
5098 .Bd -literal -offset indent
5099 $ echo PASSWORD > .pass
5100 $ gpg -e .pass
5101 $ eval `gpg-agent --daemon \e
5102     --pinentry-program=/usr/bin/pinentry-curses \e
5103     --max-cache-ttl 99999 --default-cache-ttl 99999`
5104 $ echo 'set agent-shell-lookup="gpg -d .pass.gpg"' \e
5105     >> \*(ur
5108 A couple of environment variables will be set for the agent:
5110 .Bl -tag -compact -width ".It Ev _AIL_TMPDIR[337]"
5111 .It Ev NAIL_TMPDIR
5112 The temporary directory that \*(UA uses.
5113 Usually identical to
5114 .Ev TMPDIR ,
5115 but guaranteed to be set and usable by child processes;
5116 to ensure the latter condition for
5117 .Ev TMPDIR
5118 also, it'll be set.
5119 .It Ev NAIL_USER
5120 The user
5121 .Pf ( Ql USER )
5122 for which the password is looked up.
5123 .It Ev NAIL_USER_ENC
5124 The URL percent-encoded variant of
5125 .Ev NAIL_USER .
5126 .It Ev NAIL_HOST
5127 The plain machine hostname of the user account.
5128 .It Ev NAIL_HOST_PORT
5130 .Ql HOST
5131 (hostname possibly including port) of the user account.
5135 .It Va allnet
5136 \*(BO Causes only the local part to be evaluated
5137 when comparing addresses.
5140 .It Va append
5141 \*(BO Causes messages saved in
5142 .Ev MBOX
5143 to be appended to the end rather than prepended.
5144 This should always be set.
5147 .It Va ask
5148 \*(BO Causes \*(UA to prompt for the subject of each message sent.
5149 If the user responds with simply a newline,
5150 no subject field will be sent.
5153 .It Va askatend
5154 \*(BO Causes the prompts for
5155 .Ql Cc:
5157 .Ql Bcc:
5158 lists to appear after the message has been edited.
5161 .It Va askattach
5162 \*(BO If set, \*(UA asks for files to attach at the end of each message,
5163 shall the list be found empty at that time.
5164 An empty line finalizes the list.
5167 .It Va askcc
5168 \*(BO Causes the user to be prompted for carbon copy recipients
5169 (at the end of each message if
5170 .Va askatend
5172 .Va bsdcompat
5173 are set) shall the list be found empty (at that time).
5174 An empty line finalizes the list.
5177 .It Va askbcc
5178 \*(BO Causes the user to be prompted for blind carbon copy
5179 recipients (at the end of each message if
5180 .Va askatend
5182 .Va bsdcompat
5183 are set) shall the list be found empty (at that time).
5184 An empty line finalizes the list.
5187 .It Va asksign
5188 \*(BO\*(OP Causes the user to be prompted if the message is to be
5189 signed at the end of each message.
5191 .Va smime-sign
5192 variable is ignored when this variable is set.
5195 .It Va asksub
5196 \*(BO Alternative name for
5197 .Va ask .
5203 .It Va attachment-ask-content-description , \
5204   attachment-ask-content-disposition , \
5205   attachment-ask-content-id , \
5206   attachment-ask-content-type
5207 \*(BO If set then the user will be prompted for some attachment
5208 information when editing the attachment list.
5209 It is advisable to not use these but for the first of the variables;
5210 even for that it has to be noted that the data is used
5211 .Dq as is .
5215 .It Va attrlist
5216 A sequence of characters to display in the
5217 .Ql attribute
5218 column of the
5219 .Va headline
5220 as shown in the display of
5221 .Ic headers ;
5222 each for one type of messages (see
5223 .Sx "Message states" ) ,
5224 with the default being
5225 .Ql NUROSPMFAT+\-$~
5227 .Ql NU\ \ *HMFAT+\-$~
5228 if the
5229 .Va bsdflags
5230 variable is set, in the following order:
5232 .Bl -tag -compact -offset indent -width ".It Ql _"
5233 .It Ql N
5234 new.
5235 .It Ql U
5236 unread but old.
5237 .It Ql R
5238 new but read.
5239 .It Ql O
5240 read and old.
5241 .It Ql S
5242 saved.
5243 .It Ql P
5244 preserved.
5245 .It Ql M
5246 mboxed.
5247 .It Ql F
5248 flagged.
5249 .It Ql A
5250 answered.
5251 .It Ql T
5252 draft.
5253 .It Ql +
5254 start of a collapsed thread.
5255 .It Ql -
5256 an uncollapsed thread (TODO ignored for now).
5257 .It Ql $
5258 classified as spam.
5259 .It Ql ~
5260 classified as possible spam.
5265 .It Va autobcc
5266 Specifies a list of recipients to which a blind carbon copy of each
5267 outgoing message will be sent automatically.
5270 .It Va autocc
5271 Specifies a list of recipients to which a carbon copy of each outgoing
5272 message will be sent automatically.
5275 .It Va autocollapse
5276 \*(BO Causes threads to be collapsed automatically when threaded mode
5277 is entered (see the
5278 .Ic collapse
5279 command).
5282 .It Va autoprint
5283 \*(BO Causes the delete command to behave like
5284 .Ql dp - ;
5285 thus, after deleting a message the next one will be typed automatically.
5288 .It Va autothread
5289 \*(BO\*(OB Causes threaded mode (see the
5290 .Ic thread
5291 command) to be entered automatically when a folder is opened.
5292 The same as
5293 .Ql autosort=thread .
5296 .It Va autosort
5297 Causes sorted mode (see the
5298 .Ic sort
5299 command) to be entered automatically with the value of this option as
5300 sorting method when a folder is opened, e.g.,
5301 .Ql set autosort=thread .
5304 .It Va bang
5305 \*(BO Enables the substitution of
5306 .Ql \&!
5307 by the contents of the last command line in shell escapes.
5310 .It Va batch-exit-on-error
5311 \*(BO If the batch mode has been enabled via the
5312 .Fl #
5313 command line option, then this variable will be consulted whenever \*(UA
5314 completes one operation (returns to the command prompt); if it is set
5315 then \*(UA will terminate if the last operation generated an error.
5318 .It Va bsdannounce
5319 \*(BO Causes automatic display of a header summary after executing a
5320 .Ic file
5321 command.
5324 .It Va bsdcompat
5325 \*(BO Sets some cosmetical features to traditional BSD style;
5326 has the same affect as setting
5327 .Va askatend
5328 and all other variables prefixed with
5329 .Ql bsd ;
5330 it also changes the meaning of the \*(UA specific
5331 .Ql \e&
5332 .Va prompt
5333 escape sequence and changes behaviour of
5334 .Va emptystart
5335 (which doesn't exist in BSD).
5338 .It Va bsdflags
5339 \*(BO Changes the letters shown in the first column of a header
5340 summary to traditional BSD style.
5343 .It Va bsdheadline
5344 \*(BO Changes the display of columns in a header summary to traditional
5345 BSD style.
5348 .It Va bsdmsgs
5349 \*(BO Changes some informational messages to traditional BSD style.
5352 .It Va bsdorder
5353 \*(BO Causes the
5354 .Ql Subject:
5355 field to appear immediately after the
5356 .Ql To:
5357 field in message headers and with the
5358 .Ic ~h
5359 .Sx "TILDE ESCAPES" .
5362 .It Va bsdset
5363 \*(BO Changes the output format of the
5364 .Ic set
5365 command to traditional BSD style.
5368 .It Va charset-7bit
5369 The value that should appear in the
5370 .Ql charset=
5371 parameter of
5372 .Ql Content-Type:
5373 MIME header fields when no character set conversion of the message data
5374 was performed.
5375 This defaults to US-ASCII, and the chosen character set should be
5376 US-ASCII compatible.
5379 .It Va charset-8bit
5380 \*(OP The default 8-bit character set that is used as an implicit last
5381 member of the variable
5382 .Va sendcharsets .
5383 This defaults to UTF-8.
5384 If no character set conversion capabilities are available in \*(UA then
5385 the only supported character set is
5386 .Va ttycharset .
5387 Refer to the section
5388 .Sx "Character sets"
5389 for the complete picture of character set conversion in \*(UA.
5392 .It Va charset-unknown-8bit
5393 \*(OP RFC 1428 specifies conditions when internet mail gateways shall
5394 .Dq upgrade
5395 the content of a mail message by using a character set with the name
5396 .Ql unknown-8bit .
5397 Because of the unclassified nature of this character set \*(UA will not
5398 be capable to convert this character set to any other character set.
5399 If this variable is set any message part which uses the character set
5400 .Ql unknown-8bit
5401 is assumed to really be in the character set given in the value,
5402 otherwise the (final) value of
5403 .Va charset-8bit
5404 is used for this purpose.
5406 This variable will also be taken into account if a MIME type (see
5407 .Sx "The mime.types files" )
5408 of a MIME message part that uses the
5409 .Ql binary
5410 character set is forcefully treated as text.
5413 .It Va cmd
5414 The default value for the
5415 .Ic pipe
5416 command.
5419 .It Va colour-disable
5420 \*(BO\*(OP Forcefully disable usage of colours.
5421 Also see the section
5422 .Sx "Coloured display" .
5425 .It Va colour-pager
5426 \*(BO\*(OP Wether colour shall be used for output that is paged through
5427 .Ev PAGER .
5428 Note that pagers may need special flags, e.g.,
5429 .Xr less 1
5430 requires the option
5431 .Fl \&\&R
5433 .Xr lv 1
5434 the option
5435 .Fl \&\&c
5436 in order to support colours; therefore \*(UA will inspect the variable
5437 .Ev PAGER
5438 \(en if that starts with the string
5439 .Dq less
5440 a non-existing environment variable
5441 .Va LESS
5442 will be set to
5443 .Ql FRSXi ,
5444 likewise for
5445 .Dq lv
5446 .Va LV
5447 will optionally be set to
5448 .Dq -c .
5449 Also see the section
5450 .Sx "Coloured display"
5451 for more on this.
5454 .It Va colour-terms
5455 \*(OP A comma-separated list of
5456 .Ev TERM Ns
5457 inals for which coloured display can be used.
5458 Entries only need to be added if the string
5459 .Ql color
5460 isn't part of the terminal name itself; the default value is
5462 .\" (Keep in SYNC: ./nail.h:n_COLOUR_TERMS, ./nail.1:*colour-terms*"!)
5463 .Dl aterm,cons25,gnome,konsole,\:kterm,\:linux,\:\
5464 rxvt,\:rxvt-unicode,\:screen,\:sun,\:vt100,\:vt220,\:wsvt25,\:xterm
5467 .It Va crt
5468 In a(n interactive) terminal session, then if this valued option is set
5469 it'll be used as a threshold to determine how many lines the given
5470 output has to span before it will be displayed via the configured
5471 .Ev PAGER ;
5472 Usage of the
5473 .Ev PAGER
5474 can be forced by setting this to the value
5475 .Ql 0 ,
5476 setting it without a value will deduce the current height of the
5477 terminal screen to compute the treshold (see
5478 .Ev LINES ,
5479 .Va screen
5481 .Xr stty 1 ) .
5484 .It Va customhdr
5485 \*(OB A variable counterpart of the
5486 .Ic customhdr
5487 command (see there for documentation), interpreted as a comma-separated
5488 list of custom headers to be injected, to include commas in the header
5489 bodies escape them with backslash, e.g.:
5491 .Dl set customhdr="Hdr1: Body1-1\e, Body1-2,  Hdr2: Body2"
5494 .It Va datefield
5495 In the summary of
5496 .Ic headers
5497 the message date, if any is to be displayed according to the format of
5498 .Va headline ,
5499 is by default taken from the
5500 .Ql From_
5501 line of the message.
5502 If this variable is set the date as given in the
5503 .Ql Date:
5504 header field is used instead, converted to local time.
5505 To control the display format of the date assign a valid
5506 .Xr strftime 3
5507 format string.
5508 (Note that the
5509 .Ql %n
5510 format should not be used, because \*(UA doesn't take embedded newlines
5511 into account when calculating how many lines fit onto the screen.)
5512 Also see
5513 .Va datefield-markout-older .
5516 .It Va datefield-markout-older
5517 This option, when set in addition to
5518 .Va datefield ,
5519 is used to display
5520 .Dq older
5521 messages (concept is rather comparable to the
5522 .Fl \&\&l
5523 option of the POSIX utility
5524 .Xr ls 1 ) .
5525 The content interpretation is identical to
5526 .Va \&\&datefield .
5529 .It Va debug
5530 \*(BO Enables debug messages and obsoletion warnings, disables the
5531 actual delivery of messages and also implies
5532 .Pf no Va record
5533 as well as
5534 .Pf no Va save .
5537 .It Va disposition-notification-send
5538 \*(BO\*(OP Emit a
5539 .Ql Disposition-Notification-To:
5540 header (RFC 3798) with the message.
5541 This requires the
5542 .Va from
5543 variable to be set.
5544 .\" TODO .It Va disposition-notification-send-HOST
5545 .\"Overrides
5546 .\".Va disposition-notification-send
5547 .\" for SMTP accounts on a specific host.
5548 .\" TODO .It Va disposition-notification-send-USER@HOST
5549 .\"Overrides
5550 .\".Va disposition-notification-send
5551 .\"for a specific account.
5554 .It Va dot
5555 \*(BO When dot is set, a period
5556 .Ql \&.
5557 on a line by itself during message input in (interactive) compose mode
5558 will be treated as end-of-message (in addition to the normal end-of-file
5559 condition).
5561 .Va ignoreeof
5562 is set
5563 .Pf no Va dot
5564 is ignored.
5567 .It Va dotlock-ignore-error
5568 \*(BO\*(OP Synchronization of mailboxes which \*(UA treats as system
5569 mailboxes (see the command
5570 .Ic file )
5571 will be protected with so-called dotlock files\(emthe traditional mail
5572 spool file locking method\(emin addition to system file locking.
5573 Because \*(UA ships with a privilege-separated dotlock creation program
5574 that should always be able to create such a dotlock file there is no
5575 good reason to ignore dotlock file creation errors, and thus these are
5576 fatal unless this variable is set.
5579 .It Va editalong
5580 \*(BO If this variable is set then the editor is started automatically
5581 when a message is composed in interactive mode, as if the
5582 .Ic ~e
5583 .Sx "TILDE ESCAPES"
5584 had been specified.
5586 .Va editheaders
5587 variable is implied for this automatically spawned editor session.
5590 .It Va editheaders
5591 \*(BO When a message is edited while being composed,
5592 its header is included in the editable text.
5594 .Ql To: ,
5595 .Ql Cc: ,
5596 .Ql Bcc: ,
5597 .Ql Subject: ,
5598 .Ql From: ,
5599 .Ql Reply-To:
5601 .Ql Sender:
5602 fields are accepted within the header, other fields are ignored.
5605 .It Va emptystart
5606 \*(BO When entering interactive mode \*(UA normally writes
5607 .Dq \&No mail for user
5608 and exits immediately if a mailbox is empty or doesn't exist.
5609 If this option is set \*(UA starts even with an empty or nonexistent
5610 mailbox (the latter behaviour furtherly depends upon
5611 .Va bsdcompat ,
5612 though).
5615 .It Va encoding
5616 Suggestion for the MIME encoding to use in outgoing text messages
5617 and message parts.
5618 Valid values are the default
5619 .Ql quoted-printable ,
5620 .Ql 8bit
5622 .Ql base64 .
5623 .Ql 8bit
5624 may cause problems when transferring mail messages over channels that
5625 are not ESMTP (RFC 1869) compliant.
5626 If there is no need to encode a message,
5627 .Ql 7bit
5628 transfer mode is always used regardless of this variable.
5629 Binary data is always encoded as
5630 .Ql base64 .
5633 .It Va escape
5634 If defined, the first character of this option
5635 gives the character to use in place of
5636 .Ql ~
5637 to denote
5638 .Sx "TILDE ESCAPES" .
5641 .It Va expandaddr
5642 If not set then file and command pipeline targets are not allowed,
5643 and any such address will be filtered out, giving a warning message.
5644 If set without a value then all possible recipient address
5645 specifications will be accepted \(en see the section
5646 .Sx "On sending mail, and non-interactive mode"
5647 for more on this.
5648 To accept them, but only in interactive mode, or when tilde commands
5649 were enabled explicitly by using one of the command line options
5650 .Fl ~
5652 .Fl # ,
5653 set this to the (case-insensitive) value
5654 .Ql restrict
5655 (note right now this is actually like setting
5656 .Ql restrict,-all,+name,+addr ) .
5658 In fact the value is interpreted as a comma-separated list of values.
5659 If it contains
5660 .Ql fail
5661 then the existence of disallowed specifications is treated as a hard
5662 send error instead of only filtering them out.
5663 The remaining values specify wether a specific type of recipient
5664 address specification is allowed (optionally indicated by a plus sign
5665 .Ql +
5666 prefix) or disallowed (prefixed with a hyphen
5667 .Ql - ) .
5668 The value
5669 .Ql all
5670 addresses all possible address specifications,
5671 .Ql file
5672 file targets,
5673 .Ql pipe
5674 command pipeline targets,
5675 .Ql name
5676 plain user names and (MTA) aliases (\*(OB
5677 .Ql noalias
5678 may be used as an alternative syntax to
5679 .Ql -name )
5681 .Ql addr
5682 network addresses.
5683 These kind of values are interpreted in the given order, so that
5684 .Ql restrict,\:fail,\:+file,\:-all,\:+addr
5685 will cause hard errors for any non-network address recipient address
5686 unless \*(UA is in interactive mode or has been started with the
5687 .Fl ~
5689 .Fl #
5690 command line option; in the latter case(s) any address may be used, then.
5693 .It Va expandargv
5694 Unless this variable is set additional mail-transfer-agent (MTA)
5695 arguments from the command line, as can be given after a
5696 .Ql --
5697 separator, are ignored due to safety reasons.
5698 However, if set to the special (case-insensitive) value
5699 .Ql fail ,
5700 then the presence of additional MTA arguments is treated as a hard
5701 error that causes \*(UA to exit with failure status.
5702 A lesser strict variant is the otherwise identical
5703 .Ql restrict ,
5704 which does accept such arguments in interactive mode, or if tilde
5705 commands were enabled explicitly by using one of the command line options
5706 .Fl ~
5708 .Fl # .
5711 .It Va features
5712 \*(RO Information on the features compiled into \*(UA \(en the content
5713 of this variable is identical to the output of the command
5714 .Ic features .
5717 .It Va flipr
5718 \*(BO This option reverses the meanings of a set of reply commands,
5719 turning the lowercase variants, which by default address all recipients
5720 included in the header of a message
5721 .Pf ( Ic reply , respond , followup )
5722 into the uppercase variants, which by default address the sender only
5723 .Pf ( Ic Reply , Respond , Followup )
5724 and vice versa.
5725 The commands
5726 .Ic replysender , respondsender , followupsender
5727 as well as
5728 .Ic replyall , respondall , followupall
5729 are not affected by the current setting of
5730 .Va flipr .
5734 .It Va file-hook-load-EXTENSION , file-hook-save-EXTENSION
5735 It is possible to install file hooks which will be used by the
5736 .Ic file
5737 command in order to be able to transparently handle (through an
5738 intermediate temporary file) files with specific
5739 .Ql EXTENSION Ns
5740 s: the variable values can include shell snippets and are expected to
5741 write data to standard output / read data from standard input,
5742 respectively.
5743 \*(ID The variables may not be changed while there is a mailbox
5744 attendant.
5745 .Bd -literal -offset indent
5746 set file-hook-load-xy='echo >&2 XY-LOAD; gzip -cd' \e
5747     file-hook-save-xy='echo >&2 XY-SAVE; gzip -c' \e
5748     record=+null-sent.xy
5752 .It Va folder
5753 The name of the directory to use for storing folders of messages.
5754 All folder names that begin with
5755 .Ql +
5756 refer to files below it.
5757 The same special conventions as documented for the
5758 .Ic file
5759 command may be used when specifying a new value for
5760 .Va \&\&folder ,
5761 but be aware that the expansion is fully performed immediately.
5764 .It Va folder-hook
5765 This variable can be set to the name of a
5766 .Ic define Ns d
5767 macro which will be called whenever a
5768 .Ic file
5769 is opened.
5770 The macro will also be invoked when new mail arrives,
5771 but message lists for commands executed from the macro
5772 only include newly arrived messages then.
5773 .Ic localopts
5774 are activated by default in a folder hook, causing the covered settings
5775 to be reverted once the folder is left again.
5777 .Sy \*(ID:
5778 Macro behaviour, including option localization, will change in v15.
5779 Please be aware of that and possibly embed a version check in a resource
5780 file of yours.
5783 .It Va folder-hook-FOLDER
5784 Overrides
5785 .Va folder-hook
5786 for a folder named
5787 .Ql FOLDER .
5788 Unlike other folder specifications, the fully expanded name of a folder,
5789 without metacharacters, is used to avoid ambiguities.
5790 However, if the mailbox resides under
5791 .Va folder
5792 then the usual
5793 .Ql +
5794 specification is tried in addition, e.g., if
5795 .Va \&\&folder
5797 .Dq mail
5798 (and thus relative to the user's home directory) then
5799 .Pa /home/usr1/mail/sent
5800 will be tried as
5801 .Ql folder-hook-/home/usr1/mail/sent
5802 first, but then followed by
5803 .Ql folder-hook-+sent .
5806 .It Va followup-to
5807 \*(BO Controls wether a
5808 .Ql Mail-Followup-To:
5809 header is generated when sending messages to known mailing lists.
5810 Also see
5811 .Va followup-to-honour
5812 and the commands
5813 .Ic mlist , mlsubscribe , reply
5815 .Ic Lreply .
5818 .It Va followup-to-honour
5819 Controls wether a
5820 .Ql Mail-Followup-To:
5821 header is honoured when group-replying to a message via
5822 .Ic reply
5824 .Ic Lreply .
5825 This is a quadoption; if set without a value it defaults to
5826 .Dq yes .
5827 Also see
5828 .Va followup-to
5829 and the commands
5830 .Ic mlist
5832 .Ic mlsubscribe .
5835 .It Va forward-as-attachment
5836 \*(BO Original messages are normally sent as inline text with the
5837 .Ic forward
5838 command,
5839 and only the first part of a multipart message is included.
5840 With this option messages are sent as unmodified MIME
5841 .Ql message/rfc822
5842 attachments with all of their parts included.
5845 .It Va from
5846 The address (or a list of addresses) to put into the
5847 .Ql From:
5848 field of the message header, quoting RFC 5322:
5849 the author(s) of the message, that is, the mailbox(es) of the person(s)
5850 or system(s) responsible for the writing of the message.
5851 If replying to messages these addresses are handled as if they were in
5853 .Ic alternates
5854 list.
5855 If the machine's hostname is not valid at the Internet (for example at
5856 a dialup machine) then either this variable or
5857 .Va hostname
5858 (\*(IN and with
5859 .Va smtp
5860 .Va smtp-hostname
5861 adds even more fine-tuning capabilities),
5862 have to be set.
5864 .Va \&\&from
5865 contains more than one address,
5866 setting the
5867 .Va sender
5868 variable is required (according to the standard RFC 5322).
5871 .It Va fullnames
5872 \*(BO When replying to or forwarding a message \*(UA normally removes
5873 the comment and name parts of email addresses.
5874 If this variable is set such stripping is not performed,
5875 and comments, names etc. are retained.
5878 .It Va fwdheading
5879 The string to put before the text of a message with the
5880 .Ic forward
5881 command
5882 (unless the
5883 .Va forward-as-attachment
5884 variable is set).
5885 Defaults to
5886 .Dq -------- Original Message --------
5887 if unset; No heading is put if it is set to the empty string.
5890 .It Va header
5891 \*(BO Causes the header summary to be written at startup and after
5892 commands that affect the number of messages or the order of messages in
5893 the current folder; enabled by default.
5894 The command line option
5895 .Fl N
5896 can be used to set
5897 .Pf no Va header .
5901 .It Va headline
5902 A format string to use for the summary of
5903 .Ic headers ,
5904 similar to the ones used for
5905 .Xr printf 3
5906 formats.
5907 Format specifiers in the given string start with a percent character
5908 .Ql %
5909 and may be followed by an optional decimal number indicating the field
5910 width \(em if that is negative, the field is to be left-aligned.
5911 Valid format specifiers are:
5914 .Bl -tag -compact -offset indent -width "_%%_"
5915 .It Ql %%
5916 A plain percent character.
5917 .It Ql %>
5918 .Dq Dotmark :
5919 a space character but for the current message
5920 .Pf ( Dq dot ) ,
5921 for which it expands to
5922 .Ql > .
5923 .It Ql %<
5924 .Dq Dotmark :
5925 a space character but for the current message
5926 .Pf ( Dq dot ) ,
5927 for which it expands to
5928 .Ql < .
5929 .It Ql %$
5930 \*(OP The spam score of the message, as has been classified via the
5931 command
5932 .Ic spamrate .
5933 Shows only a replacement character if there is no spam support.
5934 .It Ql %a
5935 Message attribute character (status flag); the actual content can be
5936 adjusted by setting
5937 .Va attrlist .
5938 .It Ql %d
5939 The date when the message was received, or the date found in the
5940 .Ql From:
5941 header when the
5942 .Va datefield
5943 variable is set (optionally to a date display format string).
5944 .It Ql %e
5945 The indenting level in threaded mode.
5946 .It Ql %f
5947 The address of the message sender.
5948 .It Ql %i
5949 The message thread tree structure.
5950 (Note that this format doesn't support a field width.)
5951 .It Ql %l
5952 The number of lines of the message, if available.
5953 .It Ql %m
5954 Message number.
5955 .It Ql %o
5956 The number of octets (bytes) in the message, if available.
5957 .It Ql %s
5958 Message subject (if any).
5959 .It Ql %S
5960 Message subject (if any) in double quotes.
5961 .It Ql \&%T
5962 Message recipient flags: is the addressee of the message a known or
5963 subscribed mailing list \(en see
5964 .Ic mlist
5966 .Ic mlsubscribe .
5967 .It Ql %t
5968 The position in threaded/sorted order.
5971 The default is
5972 .Ql %>\&%a\&%m\ %-18f\ %16d\ %4l/%\-5o\ %i%-s ,
5974 .Ql %>\&%a\&%m\ %20-f\ \ %16d\ %3l/%\-5o\ %i%-S
5976 .Va bsdcompat
5977 is set.
5978 Also see
5979 .Va attrlist
5981 .Va headline-bidi .
5985 .It Va headline-bidi
5986 Bidirectional text requires special treatment when displaying headers,
5987 because numbers (in dates or for file sizes etc.) will not affect the
5988 current text direction, in effect resulting in ugly line layouts when
5989 arabic or other right-to-left text is to be displayed.
5990 On the other hand only a minority of terminals is capable to correctly
5991 handle direction changes, so that user interaction is necessary for
5992 acceptable results.
5993 Note that extended host system support is required nonetheless, e.g.,
5994 detection of the terminal character set is one precondition;
5995 and this feature only works in an Unicode (i.e., UTF-8) locale.
5997 In general setting this variable will cause \*(UA to encapsulate text
5998 fields that may occur when displaying
5999 .Va headline
6000 (and some other fields, like dynamic expansions in
6001 .Va prompt )
6002 with special Unicode control sequences;
6003 it is possible to fine-tune the terminal support level by assigning
6004 a value:
6005 no value (or any value other than
6006 .Ql 1 ,
6007 .Ql 2
6009 .Ql 3 )
6010 will make \*(UA assume that the terminal is capable to properly deal
6011 with Unicode version 6.3, in which case text is embedded in a pair of
6012 U+2068 (FIRST STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE)
6013 characters.
6014 In addition no space on the line is reserved for these characters.
6016 Weaker support is chosen by using the value
6017 .Ql 1
6018 (Unicode 6.3, but reserve the room of two spaces for writing the control
6019 sequences onto the line).
6020 The values
6021 .Ql 2
6023 .Ql 3
6024 select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT MARK); the latter
6025 again reserves room for two spaces in addition.
6028 .It Va history-file
6029 \*(OP If a line editor is available then this can be set to
6030 name the (expandable) path of the location of a permanent history file.
6033 .It Va history-gabby
6034 \*(BO\*(OP Add more entries to the history as is normally done.
6037 .It Va history-gabby-persist
6038 \*(BO\*(OP \*(UA's own MLE will not save the additional
6039 .Va history-gabby
6040 entries in persistent storage unless this variable is set.
6041 On the other hand it will not loose the knowledge of wether a persistent
6042 entry was gabby or not.
6043 Also see
6044 .Va history-file .
6047 .It Va history-size
6048 \*(OP If a line editor is available this value restricts the
6049 amount of history entries that are saved into a set and valid
6050 .Va history-file .
6051 A value of less than 0 disables this feature;
6052 note that loading and incorporation of
6053 .Va history-file
6054 upon program startup can also be suppressed by doing this.
6055 An unset or invalid value, or 0, causes a default value to be used.
6056 Dependent on the available line editor this will also define the
6057 number of history entries in memory;
6058 it is also editor-specific wether runtime updates of this value will be
6059 honoured.
6062 .It Va hold
6063 \*(BO This option is used to hold messages in the system mailbox,
6064 and it is set by default.
6067 .It Va hostname
6068 Use this string as hostname when expanding local addresses instead of
6069 the value obtained from
6070 .Xr uname 3
6072 .Xr getaddrinfo 3 ,
6073 i.e., in
6074 .Ql Message-ID:
6076 .Ql From:
6077 fields.
6078 Note that when
6079 .Va smtp
6080 transport is not used then it is normally the responsibility of the MTA
6081 to create these fields, \*(IN in conjunction with
6082 .Va smtp
6083 however
6084 .Va smtp-hostname
6085 also influences the results;
6086 you should produce some test messages with the desired combination of
6087 .Va \&\&hostname ,
6088 and/or
6089 .Va from ,
6090 .Va sender
6091 etc. first.
6094 .It Va idna-disable
6095 \*(BO\*(OP Can be used to turn off the automatic conversion of domain
6096 names according to the rules of IDNA (internationalized domain names
6097 for applications).
6098 Since the IDNA code assumes that domain names are specified with the
6099 .Va ttycharset
6100 character set, an UTF-8 locale charset is required to represent all
6101 possible international domain names (before conversion, that is).
6104 .It Va ignore
6105 \*(BO Ignore interrupt signals from the terminal while entering
6106 messages; instead echo them as
6107 .Ql @
6108 characters and discard the current line.
6111 .It Va ignoreeof
6112 \*(BO Ignore end-of-file conditions
6113 .Pf ( Ql control-D )
6114 in compose mode on message input and in interactive command input.
6115 If set an interactive command input session can only be left by
6116 explicitly using one of the commands
6117 .Ic exit
6119 .Ic quit ,
6120 and message input in compose mode can only be terminated by entering
6121 a period
6122 .Ql \&.
6123 on a line by itself or by using the
6124 .Ic ~.
6125 .Sx "TILDE ESCAPES" ;
6126 .Va ignoreeof
6127 overrides a setting of
6128 .Pf no Va dot .
6131 .It Va indentprefix
6132 String used by the
6133 .Ic ~m , ~M
6135 .Ic ~R
6136 .Sx "TILDE ESCAPES"
6137 and by the
6138 .Va quote
6139 option for indenting messages,
6140 in place of the normal tabulator character
6141 .Ql ^I ,
6142 which is the default.
6143 Be sure to quote the value if it contains spaces or tabs.
6146 .It Va keep
6147 \*(BO If set, an empty mailbox file is not removed.
6148 This may improve the interoperability with other mail user agents
6149 when using a common folder directory, and prevents malicious users
6150 from creating fake mailboxes in a world-writable spool directory.
6151 Note this only applies to local regular (MBOX) files, other mailbox
6152 types will never be removed.
6155 .It Va keep-content-length
6156 \*(BO When (editing messages and) writing
6157 .Ev MBOX
6158 mailbox files \*(UA can be told to keep the
6159 .Ql Content-Length:
6161 .Ql Lines:
6162 header fields that some MUAs generate by setting this variable.
6163 Since \*(UA does neither use nor update these non-standardized header
6164 fields (which in itself shows one of their conceptual problems),
6165 stripping them should increase interoperability in between MUAs that
6166 work with with same mailbox files.
6167 Note that, if this is not set but
6168 .Va writebackedited ,
6169 as below, is, a possibly performed automatic stripping of these header
6170 fields already marks the message as being modified.
6173 .It Va keepsave
6174 \*(BO When a message is saved it is usually discarded from the
6175 originating folder when \*(UA is quit.
6176 Setting this option causes all saved message to be retained.
6179 .It Va line-editor-disable
6180 \*(BO Turn off any enhanced line editing capabilities (see
6181 .Sx "On terminal control and line editor"
6182 for more).
6185 .It Va markanswered
6186 \*(BO When a message is replied to and this variable is set,
6187 it is marked as having been answered.
6188 This mark has no technical meaning in the mail system;
6189 it just causes messages to be marked in the header summary,
6190 and makes them specially addressable.
6193 .It Va mbox-rfc4155
6194 \*(BO \*(UA generates and expects fully RFC 4155 compliant MBOX text
6195 mailboxes.
6196 Messages which are fetched over the network or from within already
6197 existing Maildir (or any non-MBOX) mailboxes may require so-called
6198 .Ql From_
6199 quoting (insertion of additional
6200 .Ql >
6201 characters to prevent line content misinterpretation) to be applied in
6202 order to be storable in MBOX mailboxes, however, dependent on the
6203 circumspection of the message producer.
6204 (E.g., \*(UA itself will, when newly generating messages, choose a
6205 .Pf Content-Transfer- Va encoding
6206 that prevents the necessity for such quoting \(en a necessary
6207 precondition to ensure message checksums won't change.)
6209 By default \*(UA will perform this
6210 .Ql From_
6211 quoting in a way that results in a MBOX file that is compatible with
6212 the POSIX MBOX layout, which means that, in order not to exceed the
6213 capabilities of simple applications, many more
6214 .Ql From_
6215 lines get quoted (thus modified) than necessary according to RFC 4155.
6216 Set this option to instead generate MBOX files which comply to RFC 4155.
6219 .It Va memdebug
6220 \*(BO Internal development variable.
6223 .It Va message-id-disable
6224 \*(BO By setting this option the generation of
6225 .Ql Message-ID:
6226 can be completely suppressed, effectively leaving this task up to the
6227 mail-transfer-agent (MTA) or the SMTP server.
6228 (According to RFC 5321 your SMTP server is not required to add this
6229 field by itself, so you should ensure that it accepts messages without a
6230 .Ql Message-ID . )
6233 .It Va message-inject-head
6234 A string to put at the beginning of each new message.
6235 The escape sequences tabulator
6236 .Ql \et
6237 and newline
6238 .Ql \en
6239 are understood.
6242 .It Va message-inject-tail
6243 A string to put at the end of each new message.
6244 The escape sequences tabulator
6245 .Ql \et
6246 and newline
6247 .Ql \en
6248 are understood.
6251 .It Va metoo
6252 \*(BO Usually, when an
6253 .Ic alias
6254 expansion contains the sender, the sender is removed from the expansion.
6255 Setting this option suppresses these removals.
6256 Note that a set
6257 .Va metoo
6258 also causes a
6259 .Ql -m
6260 option to be passed to mail-transfer-agents (MTAs);
6261 though most of the modern MTAs don't (no longer) document this flag, no
6262 MTA is known which doesn't support it (for historical compatibility).
6265 .It Va mime-allow-text-controls
6266 \*(BO When sending messages, each part of the message is MIME-inspected
6267 in order to classify the
6268 .Ql Content-Type:
6270 .Ql Content-Transfer-Encoding:
6271 (see
6272 .Va encoding )
6273 that is required to send this part over mail transport, i.e.,
6274 a computation rather similar to what the
6275 .Xr file 1
6276 command produces when used with the
6277 .Ql --mime
6278 option.
6280 This classification however treats text files which are encoded in
6281 UTF-16 (seen for HTML files) and similar character sets as binary
6282 octet-streams, forcefully changing any
6283 .Ql text/plain
6285 .Ql text/html
6286 specification to
6287 .Ql application/octet-stream :
6288 If that actually happens a yet unset charset MIME parameter is set to
6289 .Ql binary ,
6290 effectively making it impossible for the receiving MUA to automatically
6291 interpret the contents of the part.
6293 If this option is set, and the data was unambiguously identified as text
6294 data at first glance (by a
6295 .Ql .txt
6297 .Ql .html
6298 file extension), then the original
6299 .Ql Content-Type:
6300 will not be overwritten.
6303 .It Va mime-alternative-favour-rich
6304 \*(BO If this variable is set then rich MIME alternative parts (e.g.,
6305 HTML) will be preferred in favour of included plain text versions when
6306 displaying messages, provided that a handler exists which produces
6307 output that can be (re)integrated into \*(UA's normal visual display.
6308 (E.g., at the time of this writing some newsletters ship their full
6309 content only in the rich HTML part, whereas the plain text part only
6310 contains topic subjects.)
6313 .It Va mime-counter-evidence
6314 Normally the
6315 .Ql Content-Type:
6316 field is used to decide how to handle MIME parts.
6317 Some MUAs however don't use
6318 .Xr mime.types 5
6319 or a similar mechanism to correctly classify content, but simply specify
6320 .Ql application/octet-stream ,
6321 even for plain text attachments like
6322 .Ql text/diff .
6323 If this variable is set then \*(UA will try to classify such MIME
6324 message parts on its own, if possible, for example via a possibly
6325 existent attachment filename.
6326 A non-empty value may also be given, in which case a number is expected,
6327 actually a carrier of bits.
6328 Creating the bit-carrying number is a simple addition:
6329 .Bd -literal -offset indent
6330 ? !echo Value should be set to $((2 + 4 + 8))
6331 Value should be set to 14
6334 .Bl -bullet -compact
6336 If bit two is set (2) then the detected
6337 .Dq real
6338 content-type will be carried along with the message and be used for
6339 deciding which
6340 .Va pipe-TYPE/SUBTYPE
6341 is responsible for the MIME part, shall that question arise;
6342 when displaying such a MIME part the part-info will indicate the
6343 overridden content-type by showing a plus-sign
6344 .Ql + .
6346 If bit three is set (4) then the counter-evidence is always produced
6347 and a positive result will be used as the MIME type, even forcefully
6348 overriding the parts given MIME type.
6350 If bit four is set (8) then as a last resort the actual content of
6351 .Ql application/octet-stream
6352 parts will be inspected, so that data which looks like plain text can be
6353 treated as such.
6357 .It Va mimetypes-load-control
6358 This option can be used to control which of the
6359 .Xr mime.types 5
6360 databases are loaded by \*(UA, as furtherly described in the section
6361 .Sx "The mime.types files" .
6362 If the letter
6363 .Ql u
6364 is part of the option value, then the user's personal
6365 .Pa ~/.mime.types
6366 file will be loaded (if it exists); likewise the letter
6367 .Ql s
6368 controls loading of the system wide
6369 .Pa /etc/mime.types ;
6370 directives found in the user file take precedence, letter matching is
6371 case-insensitive.
6372 If this option is not set \*(UA will try to load both files.
6373 Incorporation of the \*(UA-builtin MIME types cannot be suppressed,
6374 but they will be matched last.
6376 More sources can be specified by using a different syntax: if the
6377 value string contains an equals sign
6378 .Ql =
6379 then it is instead parsed as a comma-separated list of the described
6380 letters plus
6381 .Ql f=FILENAME
6382 pairs; the given filenames will be expanded and loaded, and their
6383 content may use the extended syntax that is described in the section
6384 .Sx "The mime.types files" .
6385 Directives found in such files always take precedence (are prepended to
6386 the MIME type cache).
6389 .It Va NAIL_EXTRA_RC
6390 The name of an optional startup file to be read last.
6391 This variable has an effect only if it is set in any of the
6392 .Sx "Resource files" ,
6393 it is not imported from the environment.
6394 Use this file for commands that are not understood by other POSIX
6395 .Xr mailx 1
6396 implementations.
6398 .Mx Va netrc-lookup
6399 .It Va netrc-lookup-USER@HOST , netrc-lookup-HOST , netrc-lookup
6400 \*(BO\*(IN\*(OP Used to control usage of the users
6401 .Pa .netrc
6402 file for lookup of account credentials, as documented in the section
6403 .Sx "On URL syntax and credential lookup"
6404 and for the command
6405 .Ic netrc ;
6406 the section
6407 .Sx "The .netrc file"
6408 documents the file format.
6411 .It Va newfolders
6412 If this variable has the value
6413 .Ql maildir ,
6414 newly created local folders will be in Maildir format.
6417 .It Va newmail
6418 Checks for new mail in the current folder each time the prompt is shown.
6419 A Maildir folder must be re-scanned to determine if new mail has arrived.
6420 If this variable is set to the special value
6421 .Ql nopoll
6422 then a Maildir folder will not be rescanned completely, but only
6423 timestamp changes are detected.
6427 .It Va on-compose-enter , on-compose-leave
6428 \*(ID Macro hooks which will be executed before compose mode is
6429 entered, and after composing has been finished, respectively.
6430 Please note that this interface is very likely to change in v15, and
6431 should therefore possibly even be seen as experimental.
6432 .Ic localopts
6433 are by default enabled for these hooks, causing any setting to be
6434 forgotten after the message has been sent.
6435 The following variables will be set temporarily during execution of the
6436 macros.
6438 .Bl -tag -compact -width ".It Va compose_subject"
6439 .It Va compose-from
6440 .Va from .
6441 .It Va compose-sender
6442 .Va sender .
6443 .It Va compose-to , compose-cc , compose-bcc
6444 The list of receiver addresses as a space-separated list.
6445 .It Va compose-subject
6446 The subject.
6450 .It Va outfolder
6451 \*(BO Causes the filename given in the
6452 .Va record
6453 variable
6454 and the sender-based filenames for the
6455 .Ic Copy
6457 .Ic Save
6458 commands to be interpreted relative to the directory given in the
6459 .Va folder
6460 variable rather than to the current directory,
6461 unless it is set to an absolute pathname.
6464 .It Va page
6465 \*(BO If set, each message feed through the command given for
6466 .Ic pipe
6467 is followed by a formfeed character
6468 .Ql \ef .
6470 .Mx Va password
6471 .It Va password-USER@HOST , password-HOST , password
6472 \*(IN Variable chain that sets a password, which is used in case none has
6473 been given in the protocol and account-specific URL;
6474 as a last resort \*(UA will ask for a password on the user's terminal if
6475 the authentication method requires a password.
6476 Specifying passwords in a startup file is generally a security risk;
6477 the file should be readable by the invoking user only.
6479 .It Va password-USER@HOST
6480 \*(OU (see the chain above for \*(IN)
6481 Set the password for
6482 .Ql USER
6483 when connecting to
6484 .Ql HOST .
6485 If no such variable is defined for a host,
6486 the user will be asked for a password on standard input.
6487 Specifying passwords in a startup file is generally a security risk;
6488 the file should be readable by the invoking user only.
6491 .It Va piperaw
6492 \*(BO Send messages to the
6493 .Ic pipe
6494 command without performing MIME and character set conversions.
6498 .It Va pipe-TYPE/SUBTYPE
6499 When a MIME message part of type
6500 .Ql TYPE/SUBTYPE
6501 (case-insensitive) is displayed or quoted,
6502 its text is filtered through the value of this variable interpreted as
6503 a shell command.
6504 The special value
6505 .Ql @
6506 forces interpretation of the message part as plain text, e.g.,
6507 .Ql set pipe-application/xml=@
6508 will henceforth display XML
6509 .Dq as is .
6510 (The same could also be achieved by adding a MIME type marker with the
6511 .Ic mimetype
6512 command.
6513 And \*(OPally MIME type handlers may be defined via
6514 .Sx "The Mailcap files"
6515 \(em corresponding flag strings are shown in parenthesis below.)
6518 The special value
6519 .Ql @
6520 can in fact be used to adjust usage and behaviour of a following shell
6521 command specification by appending trigger characters to it, e.g., the
6522 following hypothetical command specification could be used:
6523 .Bd -literal -offset indent
6524 set pipe-X/Y="@*!++=@vim ${NAIL_FILENAME_TEMPORARY}"
6528 .Bl -tag -compact -width ".It Ql __"
6529 .It Ql *
6530 Simply by using the special
6531 .Ql @
6532 prefix the MIME type (shell command) handler will only be invoked to
6533 display or convert the MIME part if the message is addressed directly
6534 and alone by itself.
6535 Use this trigger to disable this and always invoke the handler
6536 .Pf ( Cd x-mailx-always ) .
6538 .It Ql #
6539 If set the handler will not be invoked when a message is to be quoted,
6540 but only when it will be displayed
6541 .Pf ( Cd x-mailx-noquote ) .
6543 .It Ql &
6544 The command will be run asynchronously, i.e., without blocking \*(UA,
6545 which may be a handy way to display a, e.g., PDF file while also
6546 continuing to read the mail message
6547 .Pf ( Cd x-mailx-async ) .
6548 Asynchronous execution implies
6549 .Ql # .
6551 .It Ql \&!
6552 The command must be run on an interactive terminal, \*(UA will
6553 temporarily release the terminal to it
6554 .Pf ( Cd needsterminal ) .
6555 This flag is mutual exclusive with
6556 .Ql & ,
6557 will only be used in interactive mode and implies
6558 .Ql # .
6560 .It Ql +
6561 Request creation of a zero-sized temporary file, the absolute pathname
6562 of which will be made accessable via the environment variable
6563 .Ev NAIL_FILENAME_TEMPORARY
6564 .Pf ( Cd x-mailx-tmpfile ) .
6565 If this trigger is given twice then the file will be unlinked
6566 automatically by \*(UA when the command loop is entered again at latest
6567 .Pf ( Cd x-mailx-tmpfile-unlink ) .
6568 (Don't use this for asynchronous handlers.)
6570 .It Ql =
6571 Normally the MIME part content is passed to the handler via standard
6572 input; if this flag is set then the data will instead be written into
6573 .Ev NAIL_FILENAME_TEMPORARY
6574 .Pf ( Cd x-mailx-tmpfile-fill ) ,
6575 the creation of which is implied; note however that in order to cause
6576 deletion of the temporary file you still have to use two plus signs
6577 .Ql ++
6578 explicitly!
6580 .It Ql @
6581 To avoid ambiguities with normal shell command content you can use
6582 another at-sign to forcefully terminate interpretation of remaining
6583 characters.
6584 (Any character not in this list will have the same effect.)
6588 Some information about the MIME part to be displayed is embedded into
6589 the environment of the shell command:
6592 .Bl -tag -compact -width ".It Ev _AIL__ILENAME__ENERATED"
6594 .It Ev NAIL_CONTENT
6595 The MIME content-type of the part, if known, the empty string otherwise.
6598 .It Ev NAIL_CONTENT_EVIDENCE
6600 .Va mime-counter-evidence
6601 includes the carry-around-bit (2), then this will be set to the detected
6602 MIME content-type; not only then identical to
6603 .Ev \&\&NAIL_CONTENT
6604 otherwise.
6607 .It Ev NAIL_FILENAME
6608 The filename, if any is set, the empty string otherwise.
6611 .It Ev NAIL_FILENAME_GENERATED
6612 A random string.
6615 .It Ev NAIL_FILENAME_TEMPORARY
6616 If temporary file creation has been requested through the command prefix
6617 this variable will be set and contain the absolute pathname of the
6618 temporary file.
6621 .It Ev NAIL_TMPDIR
6622 The temporary directory that \*(UA uses.
6623 Usually identical to
6624 .Ev TMPDIR ,
6625 but guaranteed to be set and usable by child processes;
6626 to ensure the latter condition for
6627 .Ev \&\&TMPDIR
6628 also, it'll be set.
6633 .It Va pipe-EXTENSION
6634 This is identical to
6635 .Va pipe-TYPE/SUBTYPE
6636 except that
6637 .Ql EXTENSION
6638 (normalized to lowercase using character mappings of the ASCII charset)
6639 names a file extension, e.g.,
6640 .Ql xhtml .
6641 Handlers registered using this method take precedence.
6643 .Mx Va pop3-auth
6644 .It Va pop3-auth-USER@HOST , pop3-auth-HOST , pop3-auth
6645 \*(OP\*(IN Variable chain that sets the POP3 authentication method.
6646 The only possible value as of now is
6647 .Ql plain ,
6648 which is thus the default.
6651 .Mx Va pop3-bulk-load
6652 .It Va pop3-bulk-load-USER@HOST , pop3-bulk-load-HOST , pop3-bulk-load
6653 \*(BO\*(OP When accessing a POP3 server \*(UA loads the headers of
6654 the messages, and only requests the message bodies on user request.
6655 For the POP3 protocol this means that the message headers will be
6656 downloaded twice.
6657 If this option is set then \*(UA will download only complete messages
6658 from the given POP3 server(s) instead.
6660 .Mx Va pop3-keepalive
6661 .It Va pop3-keepalive-USER@HOST , pop3-keepalive-HOST , pop3-keepalive
6662 \*(OP POP3 servers close the connection after a period of inactivity;
6663 the standard requires this to be at least 10 minutes,
6664 but practical experience may vary.
6665 Setting this variable to a numeric value greater than
6666 .Ql 0
6667 causes a
6668 .Ql NOOP
6669 command to be sent each value seconds if no other operation is performed.
6671 .Mx Va pop3-no-apop
6672 .It Va pop3-no-apop-USER@HOST , pop3-no-apop-HOST , pop3-no-apop
6673 \*(BO\*(OP Unless this variable is set the
6674 .Ql APOP
6675 authentication method will be used when connecting to a POP3 server that
6676 advertises support.
6677 The advantage of
6678 .Ql APOP
6679 is that the password is not sent in clear text over the wire and that
6680 only a single packet is sent for the user/password tuple.
6681 Note that
6682 .Va pop3-no-apop-HOST
6683 requires \*(IN.
6685 .Mx Va pop3-use-starttls
6686 .It Va pop3-use-starttls-USER@HOST , pop3-use-starttls-HOST , pop3-use-starttls
6687 \*(BO\*(OP Causes \*(UA to issue a
6688 .Ql STLS
6689 command to make an unencrypted POP3 session SSL/TLS encrypted.
6690 This functionality is not supported by all servers,
6691 and is not used if the session is already encrypted by the POP3S method.
6692 Note that
6693 .Va pop3-use-starttls-HOST
6694 requires \*(IN.
6697 .It Va print-alternatives
6698 \*(BO When a MIME message part of type
6699 .Ql multipart/alternative
6700 is displayed and it contains a subpart of type
6701 .Ql text/plain ,
6702 other parts are normally discarded.
6703 Setting this variable causes all subparts to be displayed,
6704 just as if the surrounding part was of type
6705 .Ql multipart/mixed .
6708 .It Va prompt
6709 The string shown when a command is accepted.
6710 Prompting may be prevented by either setting this to the null string
6711 or by setting
6712 .Pf no Va prompt .
6713 The same XSI escape sequences that are understood by the
6714 .Ic echo
6715 command may be used within
6716 .Va \&\&prompt .
6718 In addition, the following \*(UA specific additional sequences are
6719 understood:
6720 .Ql \e& ,
6721 which expands to
6722 .Dq \&?
6723 unless
6724 .Va bsdcompat
6725 is set, in which case it expands to
6726 .Dq \&& ;
6727 note that
6728 .Ql \e&\0
6729 is the default value of
6730 .Va \&\&prompt .
6731 .Ql \e? ,
6732 which will expand to
6733 .Dq 1
6734 if the last command failed and to
6735 .Dq 0
6736 otherwise,
6737 .Ql \e$ ,
6738 which will expand to the name of the currently active
6739 .Ic account ,
6740 if any, and to the empty string otherwise, and
6741 .Ql \e@ ,
6742 which will expand to the name of the currently active mailbox.
6743 (Note that the prompt buffer is size-limited, excess is cut off.)
6745 Even though
6746 .Va \&\&prompt
6747 checks for
6748 .Va headline-bidi
6749 to encapsulate the expansions of the
6750 .Ql \e$
6752 .Ql \e@
6753 escape sequences as necessary to correctly display bidirectional text,
6754 this is not true for the final string that makes up
6755 .Va \&\&prompt
6756 as such, i.e., real BIDI handling is not supported.
6759 .It Va quiet
6760 \*(BO Suppresses the printing of the version when first invoked.
6763 .It Va quote
6764 If set, \*(UA starts a replying message with the original message
6765 prefixed by the value of the variable
6766 .Va indentprefix .
6767 Normally, a heading consisting of
6768 .Dq Fromheaderfield wrote:
6769 is put before the quotation.
6770 If the string
6771 .Ql noheading
6772 is assigned to the
6773 .Va \&\&quote
6774 variable, this heading is omitted.
6775 If the string
6776 .Ql headers
6777 is assigned, the headers selected by the
6778 .Ic ignore Ns / Ns Ic retain
6779 commands are put above the message body,
6780 thus
6781 .Va \&\&quote
6782 acts like an automatic
6783 .Pf ` Ic ~m Ns '
6784 .Sx "TILDE ESCAPES"
6785 command, then.
6786 If the string
6787 .Ql allheaders
6788 is assigned, all headers are put above the message body and all MIME
6789 parts are included, making
6790 .Va \&\&quote
6791 act like an automatic
6792 .Pf ` Ic ~M Ns '
6793 command; also see
6794 .Va quote-as-attachment .
6797 .It Va quote-as-attachment
6798 \*(BO Add the original message in its entirety as a
6799 .Ql message/rfc822
6800 MIME attachment when replying to a message.
6801 Note this works regardless of the setting of
6802 .Va quote .
6805 .It Va quote-fold
6806 \*(OP Can be set in addition to
6807 .Va indentprefix .
6808 Setting this turns on a more fancy quotation algorithm in that leading
6809 quotation characters are compressed and overlong lines are folded.
6810 .Va \&\&quote-fold
6811 can be set to either one or two (space separated) numeric values,
6812 which are interpreted as the maximum (goal) and the minimum line length,
6813 respectively, in a spirit rather equal to the
6814 .Xr fmt 1
6815 program, but line-, not paragraph-based.
6816 If not set explicitly the minimum will reflect the goal algorithmically.
6817 The goal can't be smaller than the length of
6818 .Va indentprefix
6819 plus some additional pad.
6820 Necessary adjustments take place silently.
6823 .It Va recipients-in-cc
6824 \*(BO On group replies, specify only the sender of the original mail in
6825 .Ql To:
6826 and mention the other recipients in the secondary
6827 .Ql Cc: .
6828 By default all recipients of the original mail will be addressed via
6829 .Ql To: .
6832 .It Va record
6833 If defined, gives the pathname of the folder used to record all outgoing
6834 mail.
6835 If not defined, then outgoing mail is not saved.
6836 When saving to this folder fails the message is not sent,
6837 but instead saved to
6838 .Ev DEAD .
6841 .It Va record-resent
6842 \*(BO If both this variable and the
6843 .Va record
6844 variable are set,
6846 .Ic resend
6848 .Ic Resend
6849 commands save messages to the
6850 .Va record
6851 folder as it is normally only done for newly composed messages.
6854 .It Va reply-in-same-charset
6855 \*(BO If this variable is set \*(UA first tries to use the same
6856 character set of the original message for replies.
6857 If this fails, the mechanism described in
6858 .Sx "Character sets"
6859 is evaluated as usual.
6862 .It Va reply_strings
6863 Can be set to a comma-separated list of (case-insensitive according to
6864 ASCII rules) strings which shall be recognized in addition to the
6865 builtin strings as
6866 .Ql Subject:
6867 reply message indicators \(en builtin are
6868 .Ql Re: ,
6869 which is mandated by RFC 5322, as well as the german
6870 .Ql Aw: .
6873 .It Va replyto
6874 A list of addresses to put into the
6875 .Ql Reply-To:
6876 field of the message header.
6877 Members of this list are handled as if they were in the
6878 .Ic alternates
6879 list.
6882 .It Va reply-to-honour
6883 Controls wether a
6884 .Ql Reply-To:
6885 header is honoured when replying to a message via
6886 .Ic reply
6888 .Ic Lreply .
6889 This is a quadoption; if set without a value it defaults to
6890 .Dq yes .
6893 .It Va rfc822-body-from_
6894 \*(BO This variable can be used to force displaying a so-called
6895 .Ql From_
6896 line for messages that are embedded into an envelope mail via the
6897 .Ql message/rfc822
6898 MIME mechanism, for more visual convenience.
6901 .It Va save
6902 \*(BO Enable saving of (partial) messages in
6903 .Ev DEAD
6904 upon interrupt or delivery error.
6907 .It Va screen
6908 When \*(UA initially displays the message headers it determines the
6909 number to display by looking at the speed of the terminal.
6910 The faster the terminal, the more will be shown.
6911 This option specifies the number to use and overrides the calculation.
6912 This number is also used for scrolling with the
6913 .Ic z
6914 command.
6915 Overall screen dimensions and pager usage is influenced by the
6916 environment variables
6917 .Ev COLUMNS
6919 .Ev LINES
6920 and the variable
6921 .Va crt .
6924 .It Va searchheaders
6925 \*(BO Expand message-list specifiers in the form
6926 .Ql /x:y
6927 to all messages containing the substring
6928 .Dq y
6929 in the header field
6930 .Ql x .
6931 The string search is case insensitive.
6934 .It Va sendcharsets
6935 \*(OP A comma-separated list of character set names that can be used in
6936 outgoing internet mail.
6937 The value of the variable
6938 .Va charset-8bit
6939 is automatically appended to this list of character-sets.
6940 If no character set conversion capabilities are compiled into \*(UA then
6941 the only supported charset is
6942 .Va ttycharset .
6943 Also see
6944 .Va sendcharsets-else-ttycharset
6945 and refer to the section
6946 .Sx "Character sets"
6947 for the complete picture of character set conversion in \*(UA.
6950 .It Va sendcharsets-else-ttycharset
6951 \*(BO\*(OP If this variable is set, but
6952 .Va sendcharsets
6953 is not, then \*(UA acts as if
6954 .Va sendcharsets
6955 had been set to the value of the variable
6956 .Va ttycharset .
6957 In effect this combination passes through the message data in the
6958 character set of the current locale (given that
6959 .Va ttycharset
6960 hasn't been set manually), i.e., without converting it to the
6961 .Va charset-8bit
6962 fallback character set.
6963 Thus, mail message text will be in ISO-8859-1 encoding when send from
6964 within a ISO-8859-1 locale, and in UTF-8 encoding when send from within
6965 an UTF-8 locale.
6966 If no character set conversion capabilities are available in \*(UA then
6967 the only supported character set is
6968 .Va ttycharset .
6971 .It Va sender
6972 An address that is put into the
6973 .Ql Sender:
6974 field of outgoing messages, quoting RFC 5322: the mailbox of the agent
6975 responsible for the actual transmission of the message.
6976 This field should normally not be used unless the
6977 .Ql From:
6978 field contains more than one address, on which case it is required.
6980 .Va \&\&sender
6981 address is handled as if it were in the
6982 .Ic alternates
6983 list.
6986 .It Va sendmail
6987 To use an alternate mail transport agent (MTA),
6988 set this option to the full pathname of the program to use.
6989 It may be necessary to set
6990 .Va sendmail-progname
6991 in addition.
6993 The MTA will be passed command line arguments from several possible
6994 sources: from the variable
6995 .Va sendmail-arguments
6996 if set, from the command line if given and the variable
6997 .Va expandargv
6998 allows their use.
6999 Argument processing of the MTA will be terminated with a
7000 .Ql --
7001 separator.
7003 The otherwise occurring implicit usage of the following MTA command line
7004 arguments can be disabled by setting the boolean option
7005 .Va sendmail-no-default-arguments
7006 (which will also disable passing
7007 .Ql --
7008 to the MTA):
7009 .Ql -i
7010 (for not treating a line with only a dot
7011 .Ql \&.
7012 character as the end of input),
7013 .Ql -m
7014 (shall the option
7015 .Va metoo
7016 be set) and
7017 .Ql -v
7018 (if the
7019 .Va verbose
7020 option is set); in conjunction with the
7021 .Fl r
7022 command line option \*(UA will also pass
7023 .Ql -f
7024 as well as
7025 .Ql -F .
7028 .It Va sendmail-arguments
7029 Arguments to pass through to the Mail-Transfer-Agent can be given via
7030 this option.
7031 The content of this variable will be split up in a vector of arguments
7032 which will be joined onto other possible MTA options:
7034 .Dl set sendmail-arguments='-t -X \&"/tmp/my log\&"'
7037 .It Va sendmail-no-default-arguments
7038 \*(BO Unless this option is set \*(UA will pass some well known
7039 standard command line options to the defined
7040 .Va sendmail
7041 program, see there for more.
7044 .It Va sendmail-progname
7045 Many systems use a so-called
7046 .Xr mailwrapper 8
7047 environment to ensure compatibility with
7048 .Xr sendmail 1 .
7049 This works by inspecting the name that was used to invoke the mail
7050 delivery system.
7051 If this variable is set then the mailwrapper (the program that is
7052 actually executed when calling
7053 .Dq sendmail )
7054 will treat its contents as that name.
7055 The default is
7056 .Ql sendmail .
7059 .It Va sendwait
7060 \*(BO When sending a message wait until the MTA (including the builtin
7061 SMTP one) exits before accepting further commands.
7062 .Sy Only
7063 with this variable set errors reported by the MTA will be recognizable!
7064 If the MTA returns a non-zero exit status,
7065 the exit status of \*(ua will also be non-zero.
7068 .It Va showlast
7069 \*(BO Setting this option causes \*(UA to start at the last message
7070 instead of the first one when opening a mail folder.
7073 .It Va showname
7074 \*(BO Causes \*(UA to use the sender's real name instead of the plain
7075 address in the header field summary and in message specifications.
7078 .It Va showto
7079 \*(BO Causes the recipient of the message to be shown in the header
7080 summary if the message was sent by the user.
7083 .It Va Sign
7084 A string for use with the
7085 .Ic ~A
7086 tilde escape.
7089 .It Va sign
7090 A string for use with the
7091 .Ic ~a
7092 tilde escape.
7095 .It Va signature
7096 Must correspond to the name of a readable file if set.
7097 The file's content is then appended to each singlepart message
7098 and to the first part of each multipart message.
7099 Be warned that there is no possibility to edit the signature for an
7100 individual message.
7103 .It Va skipemptybody
7104 \*(BO If an outgoing message does not contain any text in its first or
7105 only message part, do not send it but discard it silently (see also the
7106 command line option
7107 .Fl E ) .
7110 .It Va smime-ca-dir
7111 \*(OP Specifies a directory with CA certificates in PEM (Privacy
7112 Enhanced Mail) format for verification of S/MIME signed messages.
7115 .It Va smime-ca-file
7116 \*(OP Specifies a file with CA certificates in PEM format for
7117 verification of S/MIME signed messages.
7119 .Mx Va smime-cipher
7120 .It Va smime-cipher-USER@HOST , smime-cipher
7121 \*(OP Specifies the cipher to use when generating S/MIME encrypted
7122 messages (for the specified account).
7123 RFC 5751 mandates a default of
7124 .Ql aes128
7125 (AES-128 CBC).
7126 Possible values are (case-insensitive and) in decreasing cipher strength:
7127 .Ql aes256
7128 (AES-256 CBC),
7129 .Ql aes192
7130 (AES-192 CBC),
7131 .Ql aes128
7132 (AES-128 CBC),
7133 .Ql des3
7134 (DES EDE3 CBC, 168 bits; default if
7135 .Ql aes128
7136 isn't available) and
7137 .Ql des
7138 (DES CBC, 56 bits).
7140 The actually available cipher algorithms depend on the cryptographic
7141 library that \*(UA uses.
7142 \*(OP Support for more cipher algorithms may be available through
7143 dynamic loading via, e.g.,
7144 .Xr EVP_get_cipherbyname 3
7145 (OpenSSL) if \*(UA has been compiled to support this.
7148 .It Va smime-crl-dir
7149 \*(OP Specifies a directory that contains files with CRLs in PEM format
7150 to use when verifying S/MIME messages.
7153 .It Va smime-crl-file
7154 \*(OP Specifies a file that contains a CRL in PEM format to use when
7155 verifying S/MIME messages.
7158 .It Va smime-encrypt-USER@HOST
7159 \*(OP If this variable is set, messages send to the given receiver are
7160 encrypted before sending.
7161 The value of the variable must be set to the name of a file that
7162 contains a certificate in PEM format.
7164 If a message is sent to multiple recipients,
7165 each of them for whom a corresponding variable is set will receive an
7166 individually encrypted message;
7167 other recipients will continue to receive the message in plain text
7168 unless the
7169 .Va smime-force-encryption
7170 variable is set.
7171 It is recommended to sign encrypted messages, i.e., to also set the
7172 .Va smime-sign
7173 variable.
7176 .It Va smime-force-encryption
7177 \*(BO\*(OP Causes \*(UA to refuse sending unencrypted messages.
7180 .It Va smime-no-default-ca
7181 \*(BO\*(OP Don't load default CA locations when verifying S/MIME signed
7182 messages.
7185 .It Va smime-sign
7186 \*(BO\*(OP S/MIME sign outgoing messages with the user's private key
7187 and include the user's certificate as a MIME attachment.
7188 Signing a message enables a recipient to verify that the sender used
7189 a valid certificate,
7190 that the email addresses in the certificate match those in the message
7191 header and that the message content has not been altered.
7192 It does not change the message text,
7193 and people will be able to read the message as usual.
7194 Also see
7195 .Va smime-sign-cert , smime-sign-include-certs
7197 .Va smime-sign-message-digest .
7199 .Mx Va smime-sign-cert
7200 .It Va smime-sign-cert-USER@HOST , smime-sign-cert
7201 \*(OP Points to a file in PEM format.
7202 For the purpose of signing and decryption this file needs to contain the
7203 user's private key as well as his certificate.
7205 For message signing
7206 .Ql USER@HOST
7207 is always derived from the value of
7208 .Va from
7209 (or, if that contains multiple addresses,
7210 .Va sender ) .
7211 For the purpose of encryption the recipient's public encryption key
7212 (certificate) is expected; the command
7213 .Ic certsave
7214 can be used to save certificates of signed messages (the section
7215 .Sx "Signed and encrypted messages with S/MIME"
7216 gives some details).
7217 This mode of operation is usually driven by the specialized form.
7219 When decrypting messages the account is derived from the recipient
7220 fields
7221 .Pf ( Ql To:
7223 .Ql Cc: )
7224 of the message, which are searched for addresses for which such
7225 a variable is set.
7226 \*(UA always uses the first address that matches,
7227 so if the same message is sent to more than one of the user's addresses
7228 using different encryption keys, decryption might fail.
7230 .Mx Va smime-sign-include-certs
7231 .It Va smime-sign-include-certs-USER@HOST , smime-sign-include-certs
7232 \*(OP If used, this is supposed to a consist of a comma-separated list
7233 of files, each of which containing a single certificate in PEM format to
7234 be included in the S/MIME message in addition to the
7235 .Va smime-sign-cert
7236 certificate.
7237 This is most useful for long certificate chains if it is desired to aid
7238 the receiving party's verification process.
7239 Note that top level certificates may also be included in the chain but
7240 don't play a role for verification.
7241 Also see
7242 .Va smime-sign-cert .
7243 Remember that for this
7244 .Ql USER@HOST
7245 refers to the variable
7246 .Va from
7247 (or, if that contains multiple addresses,
7248 .Va sender ) .
7250 .Mx Va smime-sign-message-digest
7251 .It Va smime-sign-message-digest-USER@HOST , smime-sign-message-digest
7252 \*(OP Specifies the message digest to use when signing S/MIME messages.
7253 RFC 5751 mandates a default of
7254 .Ql sha1 .
7255 Possible values are (case-insensitive and) in decreasing cipher strength:
7256 .Ql sha512 ,
7257 .Ql sha384 ,
7258 .Ql sha256 ,
7259 .Ql sha224
7261 .Ql md5 .
7263 The actually available message digest algorithms depend on the
7264 cryptographic library that \*(UA uses.
7265 \*(OP Support for more message digest algorithms may be available
7266 through dynamic loading via, e.g.,
7267 .Xr EVP_get_digestbyname 3
7268 (OpenSSL) if \*(UA has been compiled to support this.
7269 Remember that for this
7270 .Ql USER@HOST
7271 refers to the variable
7272 .Va from
7273 (or, if that contains multiple addresses,
7274 .Va sender ) .
7278 .It Va smtp
7279 \*(OP Normally \*(UA invokes the program defined via
7280 .Va sendmail
7281 to transfer messages, as described in
7282 .Sx "On sending mail, and non-interactive mode" .
7283 Setting the
7284 .Va \&\&smtp
7285 variable will instead cause SMTP network connections be made to the
7286 server specified therein in order to directly submit the message.
7287 \*(UA knows about three different
7288 .Dq SMTP protocols :
7290 .Bl -bullet -compact
7292 The plain SMTP protocol (RFC 5321) that normally lives on the
7293 server port 25 and requires setting the
7294 .Va smtp-use-starttls
7295 variable to enter a SSL/TLS encrypted session state.
7296 Assign a value like \*(IN
7297 .Ql [smtp://][user[:password]@]server[:port]
7298 (\*(OU
7299 .Ql [smtp://]server[:port] )
7300 to choose this protocol.
7302 Then the so-called SMTPS which is supposed to live on server port 465
7303 and is automatically SSL/TLS secured.
7304 Unfortunately it never became a standardized protocol and may thus not
7305 be supported by your hosts network service database
7306 \(en in fact the port number has already been reassigned to other
7307 protocols!
7309 SMTPS is nonetheless a commonly offered protocol and thus can be
7310 chosen by assigning a value like \*(IN
7311 .Ql smtps://[user[:password]@]server[:port]
7312 (\*(OU
7313 .Ql smtps://server[:port] ) ;
7314 due to the mentioned problems it is usually necessary to explicitly
7315 specify the port as
7316 .Ql :465 ,
7317 however.
7319 Finally there is the SUBMISSION protocol (RFC 6409), which usually
7320 lives on server port 587 and is practically identically to the SMTP
7321 protocol from \*(UA's point of view beside that; it requires setting the
7322 .Va smtp-use-starttls
7323 variable to enter a SSL/TLS secured session state.
7324 Assign a value like \*(IN
7325 .Ql submission://[user[:password]@]server[:port]
7326 (\*(OU
7327 .Ql submission://server[:port] ) .
7330 For more on credentials etc. please see
7331 .Sx "On URL syntax and credential lookup" .
7332 The SMTP transfer is executed in a child process, which runs
7333 asynchronously unless either the
7334 .Va sendwait
7335 or the
7336 .Va verbose
7337 variable is set.
7338 If it receives a TERM signal, it will abort and save the message to
7339 .Ev DEAD .
7342 .Mx Va smtp-auth
7343 .It Va smtp-auth-USER@HOST , smtp-auth-HOST , smtp-auth
7344 \*(OP Variable chain that sets the SMTP authentication method.
7345 Possible values are
7346 .Ql none
7347 (\*(OU default),
7348 .Ql plain
7349 (\*(IN default),
7350 .Ql login
7351 as well as the \*(OPal methods
7352 .Ql cram-md5
7354 .Ql gssapi .
7356 .Ql none
7357 method doesn't need any user credentials,
7358 .Ql gssapi
7359 requires a user name and all other methods require a user name and
7360 a password.
7361 See \*(IN
7362 .Va smtp ,
7363 .Va user
7365 .Va password
7366 (\*(OU
7367 .Va smtp-auth-password
7369 .Va smtp-auth-user ) .
7370 Note that
7371 .Va smtp-auth-HOST
7372 is \*(IN.
7373 \*(OU: Note for
7374 .Va smtp-auth-USER@HOST :
7375 may override dependend on sender address in the variable
7376 .Va from .
7378 .It Va smtp-auth-password
7379 \*(OP\*(OU Sets the global fallback password for SMTP authentication.
7380 If the authentication method requires a password, but neither
7381 .Va smtp-auth-password
7382 nor a matching
7383 .Va smtp-auth-password-USER@HOST
7384 can be found,
7385 \*(UA will ask for a password on the user's terminal.
7387 .It Va smtp-auth-password-USER@HOST
7388 \*(OU Overrides
7389 .Va smtp-auth-password
7390 for specific values of sender addresses, dependent upon the variable
7391 .Va from .
7393 .It Va smtp-auth-user
7394 \*(OP\*(OU Sets the global fallback user name for SMTP authentication.
7395 If the authentication method requires a user name, but neither
7396 .Va smtp-auth-user
7397 nor a matching
7398 .Va smtp-auth-user-USER@HOST
7399 can be found,
7400 \*(UA will ask for a user name on the user's terminal.
7402 .It Va smtp-auth-user-USER@HOST
7403 \*(OU Overrides
7404 .Va smtp-auth-user
7405 for specific values of sender addresses, dependent upon the variable
7406 .Va from .
7409 .It Va smtp-hostname
7410 \*(IN Normally \*(UA uses the variable
7411 .Va from
7412 to derive the necessary
7413 .Ql USER@HOST
7414 information to issue a
7415 .Ql MAIL FROM:<>
7416 SMTP command.
7417 Setting
7418 .Va smtp-hostname
7419 can be used to use the
7420 .Ql USER
7421 from the SMTP account
7422 .Pf ( Va smtp
7423 or the
7424 .Va user
7425 variable chain)
7426 and the
7427 .Ql HOST
7428 from the content of this variable (or, if that is the empty string,
7429 .Va hostname
7430 or the local hostname as a last resort).
7431 This often allows using an address that is itself valid but hosted by
7432 a provider other than which (in
7433 .Va from )
7434 is about to send the message.
7435 Setting this variable also influences the generated
7436 .Ql Message-ID: .
7438 .Mx Va smtp-use-starttls
7439 .It Va smtp-use-starttls-USER@HOST , smtp-use-starttls-HOST , smtp-use-starttls
7440 \*(BO\*(OP Causes \*(UA to issue a
7441 .Ql STARTTLS
7442 command to make an SMTP session SSL/TLS encrypted, i.e., to enable
7443 transport layer security.
7447 .It Va spam-interface
7448 \*(OP In order to use any of the spam-related commands (like, e.g.,
7449 .Ic spamrate )
7450 the desired spam interface must be defined by setting this variable.
7451 Please refer to the manual section
7452 .Sx "Handling spam"
7453 for the complete picture of spam handling in \*(UA.
7454 All or none of the following interfaces may be available:
7456 .Bl -tag -width ".It Ql _ilte_"
7457 .It Ql spamc
7458 Interaction with
7459 .Xr spamc 1
7460 from the
7461 .Xr spamassassin 1
7462 .Pf ( Lk http://spamassassin.apache.org SpamAssassin )
7463 suite.
7464 Different to the generic filter interface \*(UA will automatically add
7465 the correct arguments for a given command and has the necessary
7466 knowledge to parse the program's output.
7467 A default value for
7468 .Va spamc-command
7469 will have been compiled into the \*(UA binary if
7470 .Xr spamc 1
7471 has been found in
7472 .Ev PATH
7473 during compilation.
7474 Shall it be necessary to define a specific connection type (rather than
7475 using a configuration file for that), the variable
7476 .Va spamc-arguments
7477 can be used as in, e.g.,
7478 .Ql -d server.example.com -p 783 .
7479 It is also possible to specify a per-user configuration via
7480 .Va spamc-user .
7481 Note that this interface doesn't inspect the
7482 .Ql is-spam
7483 flag of a message for the command
7484 .Ic spamforget .
7486 .It Ql spamd
7487 \*(UA will directly communicate with the
7488 .Xr spamassassin 1
7489 daemon
7490 .Xr spamd 1
7491 via a path-based
7492 .Xr unix 4
7493 stream socket as specified in
7494 .Va spamd-socket .
7495 It is possible to specify a per-user configuration via
7496 .Va spamd-user .
7498 .It Ql filter
7499 generic spam filter support via freely configurable hooks.
7500 This interface is ment for programs like
7501 .Xr bogofilter 1
7503 .Xr sylfilter 1
7504 and requires according behaviour in respect to the hooks' exit
7505 status for at least the command
7506 .Ic spamrate
7507 .Pf ( Ql 0
7508 meaning a message is spam,
7509 .Ql 1
7510 for non-spam,
7511 .Ql 2
7512 for unsure and any other return value indicating a hard error);
7513 since the hooks can include shell code snippets diverting behaviour
7514 can be intercepted as necessary.
7515 The hooks are
7516 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
7517   spamfilter-rate
7519 .Va spamfilter-spam ;
7520 the manual section
7521 .Sx "Handling spam"
7522 contains examples for some programs.
7523 The process environment of the hooks will have the variables
7524 .Ev NAIL_TMPDIR , TMPDIR
7526 .Ev NAIL_FILENAME_GENERATED
7527 set.
7528 Note that spam score support for
7529 .Ic spamrate
7530 isn't supported unless the \*(OPtional regular expression support is
7531 available and the
7532 .Va spamfilter-rate-scanscore
7533 variable is set.
7538 .It Va spam-maxsize
7539 \*(OP Messages that exceed this size won't be passed through to the
7540 configured
7541 .Va spam-interface .
7542 The default is 420000 bytes.
7545 .It Va spamc-command
7546 \*(OP The path to the
7547 .Xr spamc 1
7548 program for the
7549 .Ql spamc
7550 .Va spam-interface .
7551 Note that the path is not expanded, but used
7552 .Dq as is .
7553 A fallback path will have been compiled into the \*(UA binary if the
7554 executable had been found during compilation.
7557 .It Va spamc-arguments
7558 \*(OP Even though \*(UA deals with most arguments for the
7559 .Ql spamc
7560 .Va spam-interface
7561 automatically, it may at least sometimes be desirable to specifiy
7562 connection-related ones via this variable, e.g.,
7563 .Ql -d server.example.com -p 783 .
7566 .It Va spamc-user
7567 \*(OP Specify a username for per-user configuration files for the
7568 .Ql spamc
7569 .Va spam-interface .
7570 If this is set to the empty string then \*(UA will use the name of the
7571 current
7572 .Va user .
7575 .It Va spamd-socket
7576 \*(OP Specify the path of the
7577 .Xr unix 4
7578 domain socket on which
7579 .Xr spamd 1
7580 listens for connections for the
7581 .Ql spamd
7582 .Va spam-interface .
7583 Note that the path is not expanded, but used
7584 .Dq as is .
7587 .It Va spamd-user
7588 \*(OP Specify a username for per-user configuration files for the
7589 .Ql spamd
7590 .Va spam-interface .
7591 If this is set to the empty string then \*(UA will use the name of the
7592 current
7593 .Va user .
7600 .It Va spamfilter-ham , spamfilter-noham , \
7601   spamfilter-nospam , spamfilter-rate , spamfilter-spam
7602 \*(OP Command and argument hooks for the
7603 .Ql filter
7604 .Va spam-interface .
7605 The manual section
7606 .Sx "Handling spam"
7607 contains examples for some programs.
7610 .It Va spamfilter-rate-scanscore
7611 \*(OP Because of the generic nature of the
7612 .Ql filter
7613 .Va spam-interface
7614 spam scores are not supported for it by default, but if the \*(OPtional
7615 regular expression support is available then setting this variable can
7616 be used to overcome this restriction.
7617 It is interpreted as follows: first a number (digits) is parsed that
7618 must be followed by a semicolon
7619 .Ql \&;
7620 and an extended regular expression.
7621 Then the latter is used to parse the first output line of the
7622 .Va spamfilter-rate
7623 hook, and, in case the evaluation is successful, the group that has been
7624 specified via the number is interpreted as a floating point scan score.
7627 .It Va ssl-ca-dir
7628 \*(OP Specifies a directory with CA certificates in PEM (Pricacy
7629 Enhanced Mail) for verification of of SSL/TLS server certificates.
7631 .Xr SSL_CTX_load_verify_locations 3
7632 for more information.
7635 .It Va ssl-ca-file
7636 \*(OP Specifies a file with CA certificates in PEM format for
7637 verification of SSL/TLS server certificates.
7639 .Xr SSL_CTX_load_verify_locations 3
7640 for more information.
7642 .Mx Va ssl-cert
7643 .It Va ssl-cert-USER@HOST , ssl-cert-HOST , ssl-cert
7644 \*(OP Variable chain that sets the file name for a SSL/TLS client
7645 certificate required by some servers.
7646 This is a direct interface to the
7647 .Ql Certificate
7648 slot of the
7649 .Xr SSL_CONF_cmd 3
7650 function of the OpenSSL library, if available.
7652 .Mx Va ssl-cipher-list
7653 .It Va ssl-cipher-list-USER@HOST , ssl-cipher-list-HOST , ssl-cipher-list
7654 \*(OP Specifies a list of ciphers for SSL/TLS connections.
7655 This is a direct interface to the
7656 .Ql CipherString
7657 slot of the
7658 .Xr SSL_CONF_cmd 3
7659 function of the OpenSSL library, if available; see
7660 .Xr ciphers 1
7661 for more information.
7662 By default \*(UA doesn't set a list of ciphers, which in effect will use a
7663 .Va ssl-protocol
7664 specific cipher (protocol standards ship with a list of acceptable
7665 ciphers), possibly cramped to what the actually used SSL/TLS library
7666 supports \(en the manual section
7667 .Sx "An example configuration"
7668 also contains a SSL/TLS use case.
7671 .It Va ssl-config-file
7672 \*(OP If this variable is set \*(UA will call
7673 .Xr CONF_modules_load_file 3
7674 to allow OpenSSL to be configured according to the host system wide
7675 security settings.
7676 If a non-empty value is given then this will be used to specify the
7677 configuration file to be used instead of the global OpenSSL default;
7678 note that in this case it is an error if the file cannot be loaded.
7679 The application name will always be passed as
7680 .Dq \*(ua .
7683 .It Va ssl-crl-file
7684 \*(OP Specifies a file that contains a CRL in PEM format to use when
7685 verifying SSL/TLS server certificates.
7688 .It Va ssl-crl-dir
7689 \*(OP Specifies a directory that contains files with CRLs in PEM format
7690 to use when verifying SSL/TLS server certificates.
7692 .Mx Va ssl-key
7693 .It Va ssl-key-USER@HOST , ssl-key-HOST , ssl-key
7694 \*(OP Variable chain that sets the file name for the private key of
7695 a SSL/TLS client certificate.
7696 If unset, the name of the certificate file is used.
7697 The file is expected to be in PEM format.
7698 This is a direct interface to the
7699 .Ql PrivateKey
7700 slot of the
7701 .Xr SSL_CONF_cmd 3
7702 function of the OpenSSL library, if available.
7704 .Mx Va ssl-method
7705 .It Va ssl-method-USER@HOST , ssl-method-HOST , ssl-method
7706 \*(OP
7707 \*(OB Please use the newer and more flexible
7708 .Va ssl-protocol
7709 instead: if both values are set,
7710 .Va ssl-protocol
7711 will take precedence!
7712 Can be set to the following values, the actually used
7713 .Va ssl-protocol
7714 specification to which it is mapped is shown in parenthesis:
7715 .Ql tls1.2
7716 .Pf ( Ql -ALL, TLSv1.2 ) ,
7717 .Ql tls1.1
7718 .Pf ( Ql -ALL, TLSv1.1 ) ,
7719 .Ql tls1
7720 .Pf ( Ql -ALL, TLSv1 )
7722 .Ql ssl3
7723 .Pf ( Ql -ALL, SSLv3 ) ;
7724 the special value
7725 .Ql auto
7726 is mapped to
7727 .Ql ALL, -SSLv2
7728 and thus includes the SSLv3 protocol.
7729 Note that SSLv2 is no longer supported at all.
7732 .It Va ssl-no-default-ca
7733 \*(BO\*(OP Don't load default CA locations to verify SSL/TLS server
7734 certificates.
7736 .Mx Va ssl-protocol
7737 .It Va ssl-protocol-USER@HOST , ssl-protocol-HOST , ssl-protocol
7738 \*(OP Specify the used SSL/TLS protocol.
7739 This is a direct interface to the
7740 .Ql Protocol
7741 slot of the
7742 .Xr SSL_CONF_cmd 3
7743 function of the OpenSSL library, if available;
7744 otherwise an \*(UA internal parser is used which understands the
7745 following subset of (case-insensitive) command strings:
7746 .Ql SSLv3 ,
7747 .Ql TLSv1 ,
7748 .Ql TLSv1.1
7750 .Ql TLSv1.2 ,
7751 as well as the special value
7752 .Ql ALL .
7753 Multiple specifications may be given via a comma-separated list which
7754 ignores any whitespace.
7755 An optional
7756 .Ql +
7757 plus prefix will enable a protocol, a
7758 .Ql -
7759 minus prefix will disable it, so that
7760 .Ql -ALL, TLSv1.2
7761 will enable only the TLSv1.2 protocol.
7763 It depends upon the used TLS/SSL library which protocols are actually
7764 supported and which protocols are used if
7765 .Va ssl-protocol
7766 is not set, but note that SSLv2 is no longer supported at all and
7767 actively disabled.
7768 Especially for older protocols explicitly securing
7769 .Va ssl-cipher-list
7770 may be worthwile, see
7771 .Sx "An example configuration" .
7774 .It Va ssl-rand-egd
7775 \*(OP Gives the pathname to an entropy daemon socket, see
7776 .Xr RAND_egd 3 .
7777 Not all SSL/TLS libraries support this.
7780 .It Va ssl-rand-file
7781 \*(OP Gives the filename to a file with random entropy data, see
7782 .Xr RAND_load_file 3 .
7783 If this variable is not set, or set to the empty string, or if the
7784 filename expansion failed, then
7785 .Xr RAND_file_name 3
7786 will be used to create the filename if, and only if,
7787 .Xr RAND_status 3
7788 documents that the SSL PRNG is not yet sufficiently seeded.
7789 If \*(UA successfully seeded the SSL PRNG then it'll update the file via
7790 .Xr RAND_write_file 3 .
7791 This variable is only used if
7792 .Va ssl-rand-egd
7793 is not set (or not supported by the SSL/TLS library).
7795 .Mx Va ssl-verify
7796 .It Va ssl-verify-USER@HOST , ssl-verify-HOST , ssl-verify
7797 \*(OP Variable chain that sets the action to be performed if an error
7798 occurs during SSL/TLS server certificate validation.
7799 Valid (case-insensitive) values are
7800 .Ql strict
7801 (fail and close connection immediately),
7802 .Ql ask
7803 (ask whether to continue on standard input),
7804 .Ql warn
7805 (show a warning and continue),
7806 .Ql ignore
7807 (do not perform validation).
7808 The default is
7809 .Ql ask .
7812 .It Va stealthmua
7813 If only set without an assigned value, then this option inhibits the
7814 generation of the
7815 .Ql Message-ID:
7817 .Ql User-Agent:
7818 header fields that include obvious references to \*(UA.
7819 There are two pitfalls associated with this:
7820 First, the message id of outgoing messages is not known anymore.
7821 Second, an expert may still use the remaining information in the header
7822 to track down the originating mail user agent.
7823 If set to the value
7824 .Ql noagent ,
7825 then the mentioned
7826 .Ql Message-ID:
7827 suppression doesn't occur.
7831 .It Va termcap
7832 (\*(OP) This specifies a comma-separated list of
7833 .Lb libtermcap
7834 capabilities (see
7835 .Sx "On terminal control and line editor" ,
7836 escape commas with backslash) to be used to overwrite or define entries.
7837 .Sy Note
7838 that this variable will only be queried once at program startup and can
7839 thus only be specified in resource files or on the command line.
7842 String capabilities form
7843 .Ql cap=value
7844 pairs and are expected unless noted otherwise.
7845 Numerics have to be notated as
7846 .Ql cap#number
7847 where the number is expected in normal decimal notation.
7848 Finally, booleans don't have any value but indicate a true or false
7849 state simply by being defined or not; this indeed means that \*(UA
7850 doesn't support undefining a boolean that normally exists.
7851 The following example defines entries for combinations of
7852 .Ql control-CURSOR :
7854 .Bd -literal -offset indent
7855 set termcap="%k=\e033[D,%o=\e033[C,%q=\e033[A,%r=\e033[B"
7859 Keycodes can easily be detected with the command
7860 .Xr cat 1
7861 by running it on an interactive terminal via
7862 .Ql $ cat
7863 (using the
7864 .Fl \&\&v
7865 command line option if available) and pressing some keys: here
7866 .Ql ^[
7867 will stand for
7868 .Ql escape
7870 .Ql ^LETTER
7872 .Ql control-LETTER
7873 (actually a visualized numeric where
7874 .Ql A
7875 stands for 1 etc.; in fact: the numeric value of
7876 .Ql LETTER
7877 in the US-ASCII character set bitwise XORd with
7878 .Ql 0x40 ,
7879 e.g.,
7880 .Ql $ echo $((0x41 ^ 0x40)) .
7881 Note that
7882 .Ql escape
7883 and other control characters have to be notated as shell-style
7884 escape sequences, e.g.,
7885 .Ql \e033
7886 for (US-ASCII)
7887 .Ql escape
7889 .Ql \e001
7891 .Ql ^A .
7894 The following terminal capabilities are or may be meaningful for the
7895 operation of the builtin line editor or \*(UA in general:
7898 .Bl -tag -compact -width yay
7899 .\" HAVE_TERMCAP
7900 .It Cd te , ti
7901 .Cd exit_ca_mode Ns / Ns Cd rmcup
7903 .Cd enter_ca_mode Ns / Ns Cd smcup ,
7904 respectively: exit and enter the alternative screen
7905 .Dq ca-mode ,
7906 effectively turning \*(UA into a fullscreen application.
7907 To disable that, set (at least) one to the empty string.
7909 .It Cd ks , ke
7910 .Cd keypad_xmit Ns / Ns Cd smkx
7912 .Cd keypad_local Ns / Ns Cd rmkx ,
7913 respectively: enable and disable the keypad.
7914 This is always enabled if available, because it seems even keyboards
7915 without keypads generate other key codes for, e.g., cursor keys in that
7916 case, and only if enabled we see the codes that we are interested in.
7918 .It Cd cd
7919 .Cd clr_eos Ns / Ns Cd ed :
7920 clear the screen.
7922 .It Cd cl
7923 .Cd clear_screen Ns / Ns Cd clear :
7924 clear the screen and home cursor.
7925 (Will be simulated via
7926 .Cd ho
7927 plus
7928 .Cd cd . )
7930 .It Cd ho
7931 .Cd cursor_home Ns / Ns Cd home :
7932 home cursor.
7934 .\" HAVE_MLE
7935 .It Cd ce
7936 .Cd clr_eol Ns / Ns Cd el :
7937 clear to the end of line.
7938 (Will be simulated via
7939 .Cd ch
7940 plus repititions of space characters.)
7942 .It Cd ch
7943 .Cd column_address Ns / Ns Cd hpa :
7944 move the cursor (to the given column parameter) in the current row.
7945 (Will be simulated via
7946 .Cd cr
7947 plus
7948 .Cd nd . )
7950 .It Cd cr
7951 .Cd carriage_return Ns / Ns Cd cr :
7952 move to the first column in the current row.
7953 The default builtin fallback is
7954 .Ql \er .
7956 .It Cd le
7957 .Cd cursor_left Ns / Ns Cd cub1 :
7958 move the cursor left one space (non-destructively).
7959 The default builtin fallback is
7960 .Ql \eb .
7962 .It Cd nd
7963 .Cd cursor_right Ns / Ns Cd cuf1 :
7964 move the cursor right one space (non-destructively).
7965 The default builtin fallback is
7966 .Ql \e033[C ,
7967 which is used by most terminals.
7968 Less often occur
7969 .Ql \e033OC
7971 .Ql \e014 .
7973 .It Cd %k , %o , %q , %r
7974 The left, right, up and down cursor keys with the
7975 .Ql control
7976 key held.
7981 .It Va termcap-disable
7982 \*(OP Disable any interaction with the
7983 .Lb libtermcap .
7984 If set only some generic fallback builtins and possibly the content of
7985 .Va termcap
7986 describe the terminal to \*(UA.
7987 .Sy Note
7988 that this variable will only be queried once at program startup and can
7989 thus only be specified in resource files or on the command line.
7992 .It Va toplines
7993 If defined, gives the number of lines of a message to be displayed
7994 with the command
7995 .Ic top ;
7996 normally, the first five lines are printed.
7999 .It Va ttycharset
8000 The character set of the terminal \*(UA operates on,
8001 and the one and only supported character set that \*(UA can use if no
8002 character set conversion capabilities have been compiled into it,
8003 in which case it defaults to ISO-8859-1 unless it can deduce a value
8004 from the
8005 .Ev LC_CTYPE
8006 locale environment.
8007 Refer to the section
8008 .Sx "Character sets"
8009 for the complete picture about character sets.
8011 .Mx Va user
8012 .It Va user-HOST , user
8013 \*(IN Variable chain that sets a global fallback user name, which is
8014 used in case none has been given in the protocol and account-specific
8015 URL.
8016 This variable defaults to the value of the first of
8017 .Ev LOGNAME
8019 .Ev USER
8020 that is set (the former being SystemV and POSIX standard, the latter BSD).
8023 .It Va v15-compat
8024 \*(BO Setting this option enables upward compatibility with \*(UA
8025 version 15.0 in respect to which configuration options are available and
8026 how they are handled.
8027 This manual uses \*(IN and \*(OU to refer to the new and the old way of
8028 doing things, respectively.
8031 .It Va verbose
8032 \*(BO Setting this option, also controllable via the command line option
8033 .Fl v ,
8034 causes \*(UA to be more verbose, e.g., it will display obsoletion
8035 warnings and SSL/TLS certificate chains.
8036 Even though marked \*(BO this option may be set twice in order to
8037 increase the level of verbosity even more, in which case even details of
8038 the actual message delivery and protocol conversations are shown.
8039 A single
8040 .Pf no Va verbose
8041 is sufficient to disable verbosity as such.
8047 .It Va version , version-major , version-minor , version-update
8048 \*(RO \*(UA version information: the first variable contains a string
8049 containing the complete version identification \(en this is identical to
8050 the output of the command
8051 .Ic version .
8052 The latter three contain only digits: the major, minor and update
8053 version numbers.
8056 .It Va writebackedited
8057 If this variable is set messages modified using the
8058 .Ic edit
8060 .Ic visual
8061 commands are written back to the current folder when it is quit;
8062 it is only honoured for writable folders in MBOX format, though.
8063 Note that the editor will be pointed to the raw message content in that
8064 case, i.e., neither MIME decoding nor decryption will have been
8065 performed, and proper RFC 4155
8066 .Ql From_
8067 quoting of newly added or edited content is also left as an excercise to
8068 the user.
8070 .\" }}} (Variables)
8071 .\" }}} (INTERNAL VARIABLES)
8074 .\" .Sh ENVIRONMENT {{{
8075 .Sh ENVIRONMENT
8077 The term
8078 .Dq environment variable
8079 should be considered an indication that the following variables are
8080 either standardized as being vivid parts of process environments, or
8081 are commonly found in there.
8082 The process environment is inherited from the
8083 .Xr sh 1
8084 once \*(UA is started, and unless otherwise explicitly noted variables
8085 in there integrate into the normal handling of
8086 .Sx "INTERNAL VARIABLES" ,
8087 from \*(UAs point of view, i.e., they can be
8088 .Ic set
8089 as such in resource files and need not necessarily come from the process
8090 environment and be managed via
8091 .Ic setenv
8093 .Ic unsetenv .
8094 E.g., the following example, applicable to a POSIX shell, sets the
8095 .Ev COLUMNS
8096 environment variable for \*(UA only, and beforehand exports the
8097 .Ev EDITOR
8098 in order to affect any further processing in the running shell:
8100 .Bd -literal -offset indent
8101 $ EDITOR="vim -u ${HOME}/.vimrc"
8102 $ export EDITOR
8103 $ COLUMNS=80 \*(ua -R
8106 .Bl -tag -width ".It Ev _AILR_"
8108 .It Ev COLUMNS
8109 The user's preferred width in column positions for the terminal screen
8110 or window.
8111 Queried and used once on program startup.
8114 .It Ev DEAD
8115 The name of the file to use for saving aborted messages if
8116 .Va save
8117 is set; this defaults to
8118 .Pa dead.letter
8119 in the user's
8120 .Ev HOME
8121 directory.
8124 .It Ev EDITOR
8125 Pathname of the text editor to use in the
8126 .Ic edit
8127 command and
8128 .Ic ~e
8129 .Sx "TILDE ESCAPES" .
8130 A default editor is used if this value is not defined.
8133 .It Ev HOME
8134 The user's home directory.
8135 This variable is only used when it resides in the process environment.
8137 .Ic setenv
8138 to update the value at runtime.
8145 .It Ev LANG , LC_ALL , LC_COLLATE , LC_CTYPE , LC_MESSAGES
8147 .Xr locale 7
8149 .Sx "Character sets" .
8152 .It Ev LINES
8153 The user's preferred number of lines on a page or the vertical screen
8154 or window size in lines.
8155 Queried and used once on program startup.
8158 .It Ev LISTER
8159 Pathname of the directory lister to use in the
8160 .Ic folders
8161 command when operating on local mailboxes.
8162 Default is
8163 .Xr ls 1
8164 (path search through
8165 .Ev SHELL ) .
8168 .It Ev LOGNAME
8169 Force identification as the given user, i.e., identical to the
8170 .Fl u
8171 command line option.
8172 This variable is standardized and therefore used in preference to the
8173 otherwise identical
8174 .Ev USER ;
8175 it is only used when it resides in the process environment.
8176 \*(ID The variable can be updated at runtime via
8177 .Ic setenv ,
8178 but without having an effect on \*(UA itself.
8181 .It Ev MAIL
8182 Is used as the user's mailbox, if set.
8183 Otherwise, a system-dependent default is used.
8184 Supports a logical subset of the special conventions that are documented
8185 for the
8186 .Ic file
8187 command and the
8188 .Va folder
8189 option.
8192 .It Ev MAILCAPS
8193 \*(OP Overrides the default path search for
8194 .Sx "The Mailcap files" ,
8195 which is defined in the standard RFC 1524 as
8196 .Ql ~/.mailcap:\:/etc/mailcap:\:/usr/etc/mailcap:\:/usr/local/etc/mailcap .
8197 .\" TODO we should have a mailcaps-default virtual RDONLY option!
8198 (\*(UA makes it a configuration option, however.)
8199 Note this is not a search path, but a path search.
8202 .It Ev MAILRC
8203 Is used as a startup file instead of
8204 .Pa \*(ur
8205 if set.
8206 When \*(UA scripts are invoked on behalf of other users,
8207 either this variable should be set to
8208 .Pa /dev/null
8209 or the
8210 .Fl \&:
8211 command line option should be used in order to avoid side-effects from
8212 reading their configuration files.
8213 This variable is only used when it resides in the process environment.
8216 .It Ev MBOX
8217 The name of the user's mbox file.
8218 A logical subset of the special conventions that are documented for the
8219 .Ic file
8220 command and the
8221 .Va folder
8222 option may be used.
8223 The fallback default is
8224 .Pa mbox
8225 in the user's
8226 .Ev HOME
8227 directory.
8228 Traditionally this secondary mailbox is used as the file to save
8229 messages from the system mailbox that have been read.
8230 Also see
8231 .Sx "Message states" .
8234 .It Ev NAIL_NO_SYSTEM_RC
8235 If this variable is set then reading of
8236 .Pa \*(UR
8237 at startup is inhibited, i.e., the same effect is achieved as if \*(UA
8238 had been started up with the option
8239 .Fl n .
8240 This variable is only used when it resides in the process environment.
8243 .It Ev NETRC
8244 \*(IN\*(OP This variable overrides the default location of the user's
8245 .Pa .netrc
8246 file.
8249 .It Ev PAGER
8250 Pathname of the program to use in the more command or when the
8251 .Va crt
8252 variable is set.
8253 The default paginator is
8254 .Xr more 1
8255 (path search through
8256 .Ev SHELL ) .
8259 .It Ev PATH
8260 A list of directories that is searched by the shell when looking for
8261 commands (as such only recognized in the process environment).
8264 .It Ev SHELL
8265 The shell to use for the commands
8266 .Ic \&! ,
8267 .Ic shell ,
8269 .Ic ~!
8270 .Sx "TILDE ESCAPES"
8271 and when starting subprocesses.
8272 A default shell is used if this option is not defined.
8275 .It Ev TERM
8276 \*(OP The terminal type for which output is to be prepared.
8277 For extended colour and font control please refer to
8278 .Sx "Coloured display" ,
8279 and for terminal management in general to
8280 .Sx "On terminal control and line editor" .
8283 .It Ev TMPDIR
8284 Used as directory for temporary files instead of
8285 .Pa /tmp ,
8286 if set.
8287 This variable is only used when it resides in the process environment.
8289 .Ic setenv
8290 to update the value at runtime.
8293 .It Ev USER
8294 This variable comes from the BSD world and is only used if the POSIX
8295 standard environment variable
8296 .Ev LOGNAME ,
8297 which originates in SysV
8298 .Ux ,
8299 is not set.
8300 Force identification as the given user, i.e., identical to the
8301 .Fl u
8302 command line option.
8303 This variable is only used when it resides in the process environment.
8304 \*(ID The variable can be updated at runtime via
8305 .Ic setenv ,
8306 but without having an effect on \*(UA itself.
8309 .It Ev VISUAL
8310 Pathname of the text editor to use in the
8311 .Ic visual
8312 command and
8313 .Ic ~v
8314 .Sx "TILDE ESCAPES" .
8316 .\" }}}
8319 .\" .Sh FILES {{{
8320 .Sh FILES
8322 .Bl -tag -width ".It Pa _etc/mime.type_"
8323 .It Pa \*(ur
8324 File giving initial commands.
8326 .It Pa \*(UR
8327 System wide initialization file.
8330 .It Pa ~/.mailcap
8331 \*(OP Personal MIME type handler definition file, see
8332 .Sx "The Mailcap files" .
8333 (RFC 1524 location, the actual path is a configuration option.)
8336 .It Pa /etc/mailcap
8337 \*(OP System wide MIME type handler definition file, see
8338 .Sx "The Mailcap files" .
8339 (RFC 1524 location, the actual path is a configuration option.)
8342 .It Pa ~/.mime.types
8343 Personal MIME types, see
8344 .Sx "The mime.types files" .
8347 .It Pa /etc/mime.types
8348 System wide MIME types, see
8349 .Sx "The mime.types files" .
8352 .It Pa ~/.netrc
8353 \*(IN\*(OP The default location of the users
8354 .Pa .netrc
8355 file \(en the section
8356 .Sx "The .netrc file"
8357 documents the file format.
8360 .\" .Ss "The mime.types files" {{{
8361 .Ss "The mime.types files"
8363 When sending messages \*(UA tries to determine the content type of all
8364 attachments.
8365 When displaying message content or attachments \*(UA uses the content
8366 type to decide wether it can directly display data or wether it needs to
8367 deal with content handlers.
8368 It learns about MIME types and how to treat them by reading
8369 .Pa mime.types
8370 files, the loading of which can be controlled by setting the variable
8371 .Va mimetypes-load-control .
8372 (The command
8373 .Ic mimetype
8374 can also be used to deal with MIME types.)
8375 .Pa mime.types
8376 files have the following syntax:
8379 .Dl type/subtype extension [extension ...]
8382 where
8383 .Ql type/subtype
8384 are strings describing the file contents, and one or multiple
8385 .Ql extension Ns
8386 s, separated by whitespace, name the part of a filename starting after
8387 the last dot (of interest).
8388 Comments may be introduced anywhere on a line with a number sign
8389 .Ql # ,
8390 causing the remaining line to be discarded.
8392 \*(UA also supports an extended, non-portable syntax in specially
8393 crafted files, which can be loaded via the alternative value syntax of
8394 .Va mimetypes-load-control
8395 and prepends an optional
8396 .Ql type-marker :
8399 .Dl [type-marker ]type/subtype extension [extension ...]
8402 The following type markers are supported:
8405 .Bl -tag -compact -offset indent -width ".It Ar _n_u"
8406 .It Ar @
8407 Treat message parts with this content as plain text.
8408 .It Ar @t@
8409 The same as plain
8410 .Ar @ .
8411 .It Ar @h@
8412 Treat message parts with this content as HTML tagsoup.
8413 If the \*(OPal HTML-tagsoup-to-text converter is not available treat
8414 the content as plain text instead.
8415 .It Ar @H@
8416 Likewise
8417 .Ar @h@
8418 but instead of falling back to plain text require an explicit content
8419 handler to be defined.
8423 Further reading:
8424 for sending messages:
8425 .Ic mimetype ,
8426 .Va mime-allow-text-controls ,
8427 .Va mimetypes-load-control .
8428 For reading etc. messages:
8429 .Sx "HTML mail and MIME attachments" ,
8430 .Sx "The Mailcap files" ,
8431 .Ic mimetype ,
8432 .Va mime-counter-evidence ,
8433 .Va mimetypes-load-control ,
8434 .Va pipe-TYPE/SUBTYPE ,
8435 .Va pipe-EXTENSION .
8436 .\" }}}
8438 .\" .Ss "The Mailcap files" {{{
8439 .Ss "The Mailcap files"
8441 RFC 1524 defines a
8442 .Dq User Agent Configuration Mechanism
8443 which \*(UA \*(OPally supports.
8444 It defines a file format to be used to inform mail user agent programs
8445 about the locally-installed facilities for handling various data
8446 formats, i.e., about commands and how they can be used to display, edit
8447 etc. MIME part contents, as well as a default path search that includes
8448 multiple possible locations of
8449 .Dq mailcap
8450 files and the
8451 .Ev MAILCAPS
8452 environment variable that can be used to overwrite that (repeating here
8453 that it is not a search path, but instead a path search specification).
8454 Any existing files will be loaded in sequence, appending any content to
8455 the list of MIME type handler directives.
8458 .Dq Mailcap
8459 files consist of a set of newline separated entries.
8460 Comment lines start with a number sign
8461 .Ql #
8462 (in the first column!) and are ignored.
8463 Empty lines are also ignored.
8464 All other lines form individual entries that must adhere to the syntax
8465 described below.
8466 To extend a single entry (not comment) its line can be continued on
8467 follow lines if newline characters are
8468 .Dq escaped
8469 by preceding them with the backslash character
8470 .Ql \e .
8471 The standard doesn't specify how leading whitespace of follow lines is
8472 to be treated, therefore \*(UA retains it.
8475 .Dq Mailcap
8476 entries consist of a number of semicolon
8477 .Ql \&;
8478 separated fields, and the backslash
8479 .Ql \e
8480 character can be used to escape any following character including
8481 semicolon and itself.
8482 The first two fields are mandatory and must occur in the specified
8483 order, the remaining fields are optional and may appear in any order.
8484 Leading and trailing whitespace of content is ignored (removed).
8487 The first field defines the MIME
8488 .Ql TYPE/SUBTYPE
8489 the entry is about to handle (case-insensitively, and no backslash
8490 escaping is possible in this field).
8491 If the subtype is specified as an asterisk
8492 .Ql *
8493 the entry is ment to match all subtypes of the named type, e.g.,
8494 .Ql audio/*
8495 would match any audio type.
8496 The second field defines the shell command which shall be used to
8497 .Dq display
8498 MIME parts of the given type; it is implicitly called the
8499 .Cd view
8500 command.
8503 For data
8504 .Dq consuming
8505 shell commands message (MIME part) data is passed via standard input
8506 unless the given shell command includes one or more instances of the
8507 (unquoted) string
8508 .Ql %s ,
8509 in which case these instances will be replaced with a temporary filename
8510 and the data will have been stored in the file that is being pointed to.
8511 Likewise, for data
8512 .Dq producing
8513 shell commands data is assumed to be generated on standard output unless
8514 the given command includes (one ore multiple)
8515 .Ql %s .
8516 In any case any given
8517 .Ql %s
8518 format is replaced with a(n already) properly quoted filename.
8519 Note that when a command makes use of a temporary file via
8520 .Ql %s
8521 then \*(UA will remove it again, as if the
8522 .Cd x-mailx-tmpfile ,
8523 .Cd x-mailx-tmpfile-fill
8525 .Cd x-mailx-tmpfile-unlink
8526 flags had been set; see below for more.
8529 The optional fields either define a shell command or an attribute (flag)
8530 value, the latter being a single word and the former being a keyword
8531 naming the field followed by an equals sign
8532 .Ql =
8533 succeeded by a shell command, and as usual for any
8534 .Dq Mailcap
8535 content any whitespace surrounding the equals sign will be removed, too.
8536 Optional fields include the following:
8539 .Bl -tag -width textualnewlines
8540 .It Cd compose
8541 A program that can be used to compose a new body or body part in the
8542 given format.
8543 (Currently unused.)
8545 .It Cd composetyped
8546 Similar to the
8547 .Cd compose
8548 field, but is to be used when the composing program needs to specify the
8549 .Ql Content-type:
8550 header field to be applied to the composed data.
8551 (Currently unused.)
8553 .It Cd edit
8554 A program that can be used to edit a body or body part in the given
8555 format.
8556 (Currently unused.)
8558 .It Cd print
8559 A program that can be used to print a message or body part in the given
8560 format.
8561 (Currently unused.)
8563 .It Cd test
8564 Specifies a program to be run to test some condition, e.g., the machine
8565 architecture, or the window system in use, to determine whether or not
8566 this mailcap entry applies.
8567 If the test fails, a subsequent mailcap entry should be sought; also see
8568 .Cd x-mailx-test-once .
8570 .It Cd needsterminal
8571 This flag field indicates that the given shell command must be run on
8572 an interactive terminal.
8573 \*(UA will temporarily release the terminal to the given command in
8574 interactive mode, in non-interactive mode this entry will be entirely
8575 ignored; this flag implies
8576 .Cd x-mailx-noquote .
8578 .It Cd copiousoutput
8579 A flag field which indicates that the output of the
8580 .Cd view
8581 command will be an extended stream of textual output that can be
8582 (re)integrated into \*(UA's normal visual display.
8583 It is mutually exclusive with
8584 .Cd needsterminal
8585 and implies
8586 .Cd x-mailx-always .
8588 .It Cd textualnewlines
8589 A flag field which indicates that this type of data is line-oriented and
8590 that, if encoded in
8591 .Ql base64 ,
8592 all newlines should be converted to canonical form (CRLF) before
8593 encoding, and will be in that form after decoding.
8594 (Currently unused.)
8596 .It Cd nametemplate
8597 This field gives a file name format, in which
8598 .Ql %s
8599 will be replaced by a random string, the joined combination of which
8600 will be used as the filename denoted by
8601 .Ev NAIL_FILENAME_TEMPORARY .
8602 One could specify that a GIF file being passed to an image viewer should
8603 have a name ending in
8604 .Ql .gif
8605 by using
8606 .Ql nametemplate=%s.gif .
8607 Note that \*(UA ignores the name template unless that solely specifies
8608 a filename suffix that consists of (ASCII) alphabetic and numeric
8609 characters, the underscore and dot only.
8611 .It Cd x11-bitmap
8612 Names a file, in X11 bitmap (xbm) format, which points to an appropriate
8613 icon to be used to visually denote the presence of this kind of data.
8614 This field is not used by \*(UA.
8616 .It Cd description
8617 A textual description that describes this type of data.
8619 .It Cd x-mailx-always
8620 Extension flag field that denotes that the given
8621 .Cd view
8622 command shall be executed even if multiple messages will be displayed
8623 at once.
8624 Normally messages which require external viewers that produce output
8625 which doesn't integrate into \*(UA's visual display (i.e., don't have
8626 .Cd copiousoutput
8627 set) have to be addressed directly and individually.
8628 (To avoid cases where, e.g., a thousand PDF viewer instances are spawned
8629 in sequence.)
8631 .It Cd x-mailx-even-if-not-interactive
8632 An extension flag test field \(em by default handlers without
8633 .Cd copiousoutput
8634 are entirely ignored in non-interactive mode, but if this flag is set
8635 then their use will be considered.
8636 It is an error if this flag is set for commands that use the flag
8637 .Cd needsterminal .
8639 .It Cd x-mailx-noquote
8640 An extension flag field that indicates that even a
8641 .Cd copiousoutput
8642 .Cd view
8643 command shall not be used to generate message quotes
8644 (as it would be by default).
8646 .It Cd x-mailx-async
8647 Extension flag field that denotes that the given
8648 .Cd view
8649 command shall be executed asynchronously, without blocking \*(UA.
8650 Cannot be used in conjunction with
8651 .Cd needsterminal .
8653 .It Cd x-mailx-test-once
8654 Extension flag which denotes wether the given
8655 .Cd test
8656 command shall be evaluated once only and the (boolean) result be cached.
8657 This is handy if some global unchanging condition is to be queried, like
8658 .Dq running under the X Window System .
8660 .It Cd x-mailx-tmpfile
8661 Extension flag field that requests creation of a zero-sized temporary
8662 file, the name of which is to be placed in the environment variable
8663 .Ev NAIL_FILENAME_TEMPORARY .
8664 It is an error to use this flag with commands that include a
8665 .Ql %s
8666 format.
8668 .It Cd x-mailx-tmpfile-fill
8669 Normally the MIME part content is passed to the handler via standard
8670 input; if this flag is set then the data will instead be written into
8671 the implied
8672 .Cd x-mailx-tmpfile .
8673 In order to cause deletion of the temporary file you will have to set
8674 .Cd x-mailx-tmpfile-unlink
8675 explicitly!
8676 It is an error to use this flag with commands that include a
8677 .Ql %s
8678 format.
8680 .It Cd x-mailx-tmpfile-unlink
8681 Extension flag field that requests that the temporary file shall be
8682 deleted automatically when the command loop is entered again at latest.
8683 (Don't use this for asynchronous handlers.)
8684 It is an error to use this flag with commands that include a
8685 .Ql %s
8686 format, or without also setting
8687 .Cd x-mailx-tmpfile
8689 .Cd x-mailx-tmpfile-fill .
8691 .It Cd x-mailx-tmpfile-keep
8692 Using the string
8693 .Ql %s
8694 implies the three tmpfile related flags above, but if you want, e.g.,
8695 .Cd x-mailx-async
8696 and deal with the temporary file yourself, you can add in this flag to
8697 forcefully ignore
8698 .Cd x-mailx-tmpfile-unlink .
8703 The standard includes the possibility to define any number of additional
8704 entry fields, prefixed by
8705 .Ql x- .
8706 Flag fields apply to the entire
8707 .Dq Mailcap
8708 entry \(em in some unusual cases, this may not be desirable, but
8709 differentiation can be accomplished via separate entries, taking
8710 advantage of the fact that subsequent entries are searched if an earlier
8711 one does not provide enough information.
8712 E.g., if a
8713 .Cd view
8714 command needs to specify the
8715 .Cd needsterminal
8716 flag, but the
8717 .Cd compose
8718 command shall not, the following will help out the latter (with enabled
8719 .Va debug
8720 or an increased
8721 .Va verbose
8722 level \*(UA will show informations about handler evaluation):
8724 .Bd -literal -offset indent
8725 application/postscript; ps-to-terminal %s; needsterminal
8726 application/postscript; ps-to-terminal %s; compose=idraw %s
8730 In fields any occurrence of the format string
8731 .Ql %t
8732 will be replaced by the
8733 .Ql TYPE/SUBTYPE
8734 specification.
8735 Named parameters from the
8736 .Ql Content-type:
8737 field may be placed in the command execution line using
8738 .Ql %{
8739 followed by the parameter name and a closing
8740 .Ql }
8741 character.
8742 The entire parameter should appear as a single command line argument,
8743 regardless of embedded spaces; thus:
8745 .Bd -literal -offset indent
8746 # Message
8747 Content-type:  multipart/mixed; boundary=42
8749 # Mailcap file
8750 multipart/*; /usr/local/bin/showmulti \e
8751   %t %{boundary}  ;  composetyped  = /usr/local/bin/makemulti
8753 # Executed shell command
8754 /usr/local/bin/showmulti multipart/mixed 42
8758 .\" TODO v15: Mailcap: %n,%F
8759 Note that \*(UA doesn't support handlers for multipart MIME parts as
8760 shown in this example (as of today).
8761 \*(UA doesn't support the additional formats
8762 .Ql %n
8764 .Ql %F .
8765 An example file, also showing how to properly deal with the expansion of
8766 .Ql %s ,
8767 which includes any quotes that are necessary to make it a valid shell
8768 argument by itself and thus will cause undesired behaviour when placed
8769 in additional user-provided quotes:
8771 .Bd -literal -offset indent
8772 # Comment line
8773 text/richtext; richtext %s; copiousoutput
8775 text/x-perl; perl -cWT %s
8777 application/pdf; \e
8778   infile=%s\e; \e
8779     trap "rm -f ${infile}" EXIT\e; \e
8780     trap "exit 75" INT QUIT TERM\e; \e
8781     mupdf %s; \e
8782   x-mailx-async; x-mailx-tmpfile-keep
8784 application/*; echo "This is \e"%t\e" but \e
8785     is 50 \e% Greek to me" \e; < %s head -c 1024 | cat -vET; \e
8786   copiousoutput; x-mailx-noquote
8790 Further reading:
8791 .Sx "HTML mail and MIME attachments" ,
8792 .Sx "The mime.types files" ,
8793 .Ic mimetype ,
8794 .Ev MAILCAPS ,
8795 .Va mime-counter-evidence ,
8796 .Va pipe-TYPE/SUBTYPE ,
8797 .Va pipe-EXTENSION .
8798 .\" }}}
8800 .\" .Ss "The .netrc file" {{{
8801 .Ss "The .netrc file"
8804 .Pa .netrc
8805 file contains user credentials for machine accounts.
8806 The default location in the user's
8807 .Ev HOME
8808 directory may be overridden by the
8809 .Ev NETRC
8810 environment variable.
8811 The file consists of space, tabulator or newline separated tokens.
8812 \*(UA implements a parser that supports a superset of the original BSD
8813 syntax, but users should nonetheless be aware of portability glitches
8814 of that file format, shall their
8815 .Pa .netrc
8816 be usable across multiple programs and platforms:
8819 .Bl -bullet -compact
8821 BSD doesn't support single, but only double quotation marks, e.g.,
8822 .Ql password="pass with spaces" .
8824 BSD (only?) supports escaping of single characters via a backslash
8825 (e.g., a space can be escaped via
8826 .Ql \e\0 ) ,
8827 in- as well as outside of a quoted string.
8829 BSD doesn't require the final quotation mark of the final user input token.
8831 The original BSD (Berknet) parser also supported a format which allowed
8832 tokens to be separated with commas \(en whereas at least Hewlett-Packard
8833 still seems to support this syntax, \*(UA does not!
8835 As a non-portable extension some widely-used programs support
8836 shell-style comments: if an input line starts, after any amount of
8837 whitespace, with a number sign
8838 .Ql # ,
8839 then the rest of the line is ignored.
8841 Whereas other programs may require that the
8842 .Pa .netrc
8843 file is accessible by only the user if it contains a
8844 .Cd password
8845 token for any other
8846 .Cd login
8847 than
8848 .Dq anonymous ,
8849 \*(UA will always require these strict permissions.
8853 Of the following list of supported tokens \*(UA only uses (and caches)
8854 .Cd machine ,
8855 .Cd login
8857 .Cd password .
8858 At runtime the command
8859 .Ic netrc
8860 can be used to control \*(UAs
8861 .Pa .netrc
8862 cache.
8864 .Bl -tag -width password
8865 .It Cd machine Ar name
8866 The hostname of the entries' machine, lowercase-normalized by \*(UA
8867 before use.
8868 Any further file content, until either end-of-file or the occurrence
8869 of another
8870 .Cd machine
8871 or a
8872 .Cd default
8873 first-class token is bound (only related) to the machine
8874 .Ar name .
8876 As an extension that shouldn't be the cause of any worries
8877 \*(UA supports a single wildcard prefix for
8878 .Ar name :
8879 .Bd -literal -offset indent
8880 machine *.example.com login USER password PASS
8881 machine pop3.example.com login USER password PASS
8882 machine smtp.example.com login USER password PASS
8885 which would match
8886 .Ql xy.example.com
8887 as well as
8888 .Ql pop3.example.com ,
8889 but neither
8890 .Ql example.com
8892 .Ql local.smtp.example.com .
8893 Note that in the example neither
8894 .Ql pop3.example.com
8896 .Ql smtp.example.com
8897 will be matched by the wildcard, since the exact matches take
8898 precedence (it is however faster to specify it the other way around).
8900 .It Cd default
8901 This is the same as
8902 .Cd machine
8903 except that it is a fallback entry that is used shall none of the
8904 specified machines match; only one default token may be specified,
8905 and it must be the last first-class token.
8907 .It Cd login Ar name
8908 The user name on the remote machine.
8910 .It Cd password Ar string
8911 The user's password on the remote machine.
8913 .It Cd account Ar string
8914 Supply an additional account password.
8915 This is merely for FTP purposes.
8917 .It Cd macdef Ar name
8918 Define a macro.
8919 A macro is defined with the specified
8920 .Ar name ;
8921 it is formed from all lines beginning with the next line and continuing
8922 until a blank line is (consecutive newline characters are) encountered.
8923 (Note that
8924 .Cd macdef
8925 entries cannot be utilized by multiple machines, too, but must be
8926 defined following the
8927 .Ic machine
8928 they are intended to be used with.)
8929 If a macro named
8930 .Ar init
8931 exists, it is automatically run as the last step of the login process.
8932 This is merely for FTP purposes.
8934 .\" }}}
8936 .\" }}}
8939 .\" .Sh EXAMPLES {{{
8940 .Sh EXAMPLES
8942 .\" .Ss "An example configuration" {{{
8943 .Ss "An example configuration"
8945 .Bd -literal -offset indent
8946 # This example assumes v15.0 compatibility mode
8947 set v15-compat
8949 # Where are the up-to-date SSL certificates?
8950 #set ssl-ca-dir=/etc/ssl/certs
8951 set ssl-ca-file=/etc/ssl/certs/ca-certificates.crt
8953 # (Since we manage up-to-date ones explicitly, don't use any,
8954 # possibly outdated, default certificates shipped with OpenSSL
8955 set ssl-no-default-ca
8957 # Don't use protocols older than TLS v1.2.
8958 # Change this only when the remote server doesn't support it:
8959 # maybe use ssl-protocol-HOST (or -USER@HOST) syntax to define
8960 # such explicit exceptions, then
8961 set ssl-protocol="-ALL,+TLSv1.2"
8963 # Explicitly define the list of ciphers, which may improve security,
8964 # especially with protocols older than TLS v1.2.  See ciphers(1).
8965 # Hint: it is important to include "@STRENGTH": only with it the
8966 # final list will be sorted by algorithm strength.
8967 # This is an example: in reality it is possibly best to only use
8968 # ssl-cipher-list-HOST (or -USER@HOST), as necessary, again..
8969 set ssl-cipher-list="ALL:!aNULL:!MEDIUM:!LOW:\e
8970     !MD5:!RC4:!EXPORT:@STRENGTH"
8972 # Request strict transport security checks!
8973 set ssl-verify=strict
8975 # Essential setting: select allowed character sets
8976 set sendcharsets=utf-8,iso-8859-1
8978 # A very kind option: when replying to a message, first try to
8979 # use the same encoding that the original poster used herself!
8980 set reply-in-same-charset
8982 # When replying to or forwarding a message the comment and name
8983 # parts of email addresses are removed unless this variable is set
8984 set fullnames
8986 # When sending messages, wait until the Mail-Transfer-Agent finishs.
8987 # Only like this you'll be able to see errors reported through the
8988 # exit status of the MTA (including the builtin SMTP one)!
8989 set sendwait
8991 # Only use builtin MIME types, no mime.types(5) files
8992 set mimetypes-load-control
8994 # Default directory where we act in (relative to $HOME)
8995 set folder=mail
8996 # A leading "+" (often) means: under *folder*
8997 # *record* is used to save copies of sent messages
8998 set MBOX=+mbox.mbox record=+sent.mbox DEAD=+dead.mbox
9000 # Make "file mymbox" and "file myrec" go to..
9001 shortcut mymbox %:+mbox.mbox myrec +sent.mbox
9003 # Not really optional, e.g., for S/MIME
9004 set from="Your Name <youremail@domain>"
9006 # It may be necessary to set hostname and/or smtp-hostname
9007 # if the "SERVER" of smtp and "domain" of from don't match.
9008 # The `urlencode' command can be used to encode USER and PASS
9009 set smtp=(smtp[s]/submission)://[USER[:PASS]@]SERVER[:PORT] \e
9010     smtp-auth=login/plain... \e
9011     smtp-use-starttls
9013 # Never refuse to start into interactive mode, and more
9014 set emptystart \e
9015     colour-pager crt= \e
9016     followup-to followup-to-honour=ask-yes \e
9017     history-file=+.\*(uahist history-size=-1 history-gabby \e
9018     mime-counter-evidence=0xE \e
9019     prompt="\e033[31m?\e?[\e$ \e@]\e& \e033[0m" \e
9020     reply-to-honour=ask-yes
9022 # When `p'rinting messages, show only these headers
9023 # (use `P'rint for all headers and `S'how for raw message)
9024 retain date from to cc subject
9026 # Some mailing lists
9027 mlist @xyz-editor.xyz$ @xyzf.xyz$
9028 mlsubscribe ^xfans@xfans.xyz$
9030 # A real life example of a very huge free mail provider
9031 account XooglX {
9032   set from="Your Name <youremail@domain>"
9033   # (The plain smtp:// proto is optional)
9034   set smtp=USER:PASS@smtp.gmXil.com smtp-use-starttls
9037 # Here is a pretty large one which does not allow sending mails
9038 # if there is a domain name mismatch on the SMTP protocol level,
9039 # which would bite us if the value of from does not match, e.g.,
9040 # for people who have a sXXXXeforge project and want to speak
9041 # with the mailing list under their project account (in from),
9042 # still sending the message through their normal mail provider
9043 account XandeX {
9044   set from="Your Name <youremail@domain>"
9045   set smtp=smtps://USER:PASS@smtp.yaXXex.ru:465 \e
9046       hostname=yaXXex.com smtp-hostname=
9049 # Create some new commands so that, e.g., `ls /tmp' will..
9050 ghost l   !ls -aFtr
9051 ghost L   !ls -aFt
9052 ghost ll  !ls -aFltr
9053 ghost Ll  !ls -aFlt
9054 ghost la  !ls -aFr
9055 ghost La  !ls -aF
9056 ghost lla !ls -aFlr
9057 ghost Lla !ls -aFl
9058 ghost lS  !ls -aFrS
9059 ghost LS  !ls -aFS
9060 ghost llS !ls -aFlrS
9061 ghost LlS !ls -aFlS
9063 # We don't support gpg(1) directly yet.  But simple --clearsign'd
9064 # message parts can be dealt with as follows:
9065 define V {
9066   localopts yes
9067   set pipe-text/plain="@*#++=@\e
9068     < \e"${NAIL_FILENAME_TEMPORARY}\e" awk \e
9069         -v TMPFILE=\e"${NAIL_FILENAME_TEMPORARY}\e" '\e
9070       BEGIN {done=0}\e
9071       /^-----BEGIN PGP SIGNED MESSAGE-----/,/^$/ {\e
9072         if (done++ != 0)\e
9073           next;\e
9074         print \e"--- GPG --verify ---\e";\e
9075         system(\e"gpg --verify \e" TMPFILE \e" 2>&1\e");\e
9076         print \e"--- GPG --verify ---\e";\e
9077         print \e"\e";\e
9078         next;\e
9079       }\e
9080       /^-----BEGIN PGP SIGNATURE-----/,\e
9081           /^-----END PGP SIGNATURE-----/ {\e
9082         next;\e
9083       }\e
9084       {print}\e
9085       '"
9086   print
9088 ghost V call V
9090 define RK {
9091   !printf 'Key IDs to gpg --recv-keys: ';\e
9092     read keyids;\e
9093     gpg --recv-keys ${keyids};
9095 ghost RK call RK
9099 When storing passwords in
9100 .Pa \*(ur
9101 appropriate permissions should be set on this file with
9102 .Ql $ chmod 0600 \*(ur .
9103 If the \*(OPal
9104 .Va netrc-lookup
9105 is available user credentials can be stored in the central
9106 .Pa .netrc
9107 file instead; e.g., here is a different version of the example account
9108 that sets up SMTP and POP3:
9110 .Bd -literal -offset indent
9111 account XandeX {
9112   set from="Your Name <youremail@domain>"
9113   set netrc-lookup
9114   #set agent-shell-lookup="gpg -d .pass.gpg"
9116   set smtp=smtps://smtp.yXXXXx.ru:465 \e
9117       smtp-hostname= hostname=yXXXXx.com
9118   set pop3-keepalive=240 pop3-no-apop-pop.yXXXXx.ru
9119   ghost xp fi pop3s://pop.yXXXXx.ru
9124 and, in the
9125 .Pa .netrc
9126 file:
9128 .Bd -literal -offset indent
9129 machine *.yXXXXx.ru login USER password PASS
9133 If the also \*(OPal
9134 .Va agent-shell-lookup
9135 is available things could be diversified further by using encrypted
9136 password storage: for this, don't specify
9137 .Ql password PASS
9138 in the
9139 .Pa .netrc
9140 file and instead uncomment the line that defines agent lookup in the
9141 example
9142 .Ic account
9143 above, then create the encrypted password storage file
9144 .Pa .pass.gpg :
9146 .Bd -literal -offset indent
9147 $ echo PASS > .pass
9148 $ gpg -e .pass
9149 $ eval `gpg-agent --daemon \e
9150         --pinentry-program=/usr/bin/pinentry-curses \e
9151         --max-cache-ttl 99999 --default-cache-ttl 99999`
9155 This configuration should now work just fine (use the
9156 .Fl d
9157 command line option for a(n almost) dry-run):
9160 .Dl $ echo text | \*(ua -vv -AXandeX -s Subject some@where
9161 .\" }}}
9163 .\" .Ss "Signed and encrypted messages with S/MIME" {{{
9164 .Ss "Signed and encrypted messages with S/MIME"
9166 \*(OP S/MIME provides two central mechanisms:
9167 message signing and message encryption.
9168 A signed message contains some data in addition to the regular text.
9169 The data can be used to verify that the message was sent using a valid
9170 certificate, that the sender's address in the message header matches
9171 that in the certificate, and that the message text has not been altered.
9172 Signing a message does not change its regular text;
9173 it can be read regardless of whether the recipient's software is able to
9174 handle S/MIME.
9177 It is thus usually possible to sign all outgoing messages if so desired.
9178 Encryption, in contrast, makes the message text invisible for all people
9179 except those who have access to the secret decryption key.
9180 To encrypt a message, the specific recipient's public encryption key
9181 must be known.
9182 It is therefore not possible to send encrypted mail to people unless their
9183 key has been retrieved from either previous communication or public key
9184 directories.
9185 A message should always be signed before it is encrypted.
9186 Otherwise, it is still possible that the encrypted message text is
9187 altered.
9190 A central concept to S/MIME is that of the certification authority (CA).
9191 A CA is a trusted institution that issues certificates.
9192 For each of these certificates it can be verified that it really
9193 originates from the CA, provided that the CA's own certificate is
9194 previously known.
9195 A set of CA certificates is usually delivered with OpenSSL and installed
9196 on your system.
9197 If you trust the source of your OpenSSL software installation,
9198 this offers reasonable security for S/MIME on the Internet.
9199 (Otherwise set
9200 .Va ssl-no-default-ca
9201 and use
9202 .Va smime-ca-file
9203 and/or
9204 .Va smime-ca-dir . )
9205 In general, a certificate cannot be more secure than the method its CA
9206 certificate has been retrieved with, though.
9207 Thus if you download a CA certificate from the Internet,
9208 you can only trust the messages you verify using that certificate as
9209 much as you trust the download process.
9212 The first thing you need for participating in S/MIME message exchange is
9213 your personal certificate, including a private key.
9214 The certificate contains public information, in particular your name and
9215 your email address(es), and the public key that is used by others to
9216 encrypt messages for you,
9217 and to verify signed messages they supposedly received from you.
9218 The certificate is included in each signed message you send.
9219 The private key must be kept secret.
9220 It is used to decrypt messages that were previously encrypted with your
9221 public key, and to sign messages.
9224 For personal use it is recommended that you get a S/MIME certificate
9225 from one of the major CAs on the Internet using your WWW browser.
9226 Many CAs offer such certificates for free.
9227 There is also
9228 .Lk https://www.CAcert.org
9229 which issues client and server certificates to members of their
9230 community for free; their root certificate
9231 .Pf ( Lk https://\:www.cacert.org/\:certs/\:root.crt )
9232 is often not in the default set of trusted CA root certificates, though,
9233 which means you will have to download their root certificate separately
9234 and ensure it is part of our S/MIME certificate validation chain by
9235 including it in
9236 .Va smime-ca-dir
9237 or as a vivid member of the
9238 .Va smime-ca-file .
9239 But let's take a step-by-step tour on how to setup S/MIME with
9240 a certificate from CAcert.org despite this situation!
9243 First of all you will have to become a member of the CAcert.org
9244 community, simply by registrating yourself via the web interface.
9245 Once you are, create and verify all email addresses you want to be able
9246 to create signed and encrypted messages for/with using the corresponding
9247 entries of the web interface.
9248 Now ready to create S/MIME certificates, so let's create a new
9249 .Dq client certificate ,
9250 ensure to include all email addresses that should be covered by the
9251 certificate in the following web form, and also to use your name as the
9252 .Dq common name .
9255 Create a private key and a certificate request on your local computer
9256 (please see the manual pages of the used commands for more in-depth
9257 knowledge on what the used arguments etc. do):
9260 .Dl openssl req -nodes -newkey rsa:4096 -keyout key.pem -out creq.pem
9263 Afterwards copy-and-paste the content of
9264 .Dq creq.pem
9265 into the certificate-request (CSR) field of the web form on the
9266 CAcert.org website (you may need to unfold some
9267 .Dq advanced options
9268 to see the corresponding text field).
9269 This last step will ensure that your private key (which never left your
9270 box) and the certificate belong together (through the public key that
9271 will find its way into the certificate via the certificate-request).
9272 You are now ready and can create your CAcert certified certificate.
9273 Download and store or copy-and-paste it as
9274 .Dq pub.crt .
9277 Yay.
9278 In order to use your new S/MIME setup you will have to create
9279 a combined private key/public key (certificate) file:
9282 .Dl cat key.pem pub.crt > ME@HERE.com.paired
9285 This is the file \*(UA will work with.
9286 If you have created your private key with a passphrase then \*(UA will
9287 ask you for it whenever a message is signed or decrypted.
9288 Set the following variables to henceforth use S/MIME (setting
9289 .Va smime-ca-file
9290 is of interest for verification only):
9292 .Bd -literal -offset indent
9293 set smime-ca-file=ALL-TRUSTED-ROOT-CERTS-HERE \e
9294   smime-sign-cert=ME@HERE.com.paired \e
9295   smime-sign-message-digest=SHA256 \e
9296   smime-sign
9300 From each signed message you send, the recipient can fetch your
9301 certificate and use it to send encrypted mail back to you.
9302 Accordingly if somebody sends you a signed message, you can do the same,
9303 and use the
9304 .Ic verify
9305 command to check the validity of the certificate.
9308 Variables of interest for S/MIME signing:
9309 .Va smime-ca-dir ,
9310 .Va smime-ca-file ,
9311 .Va smime-crl-dir ,
9312 .Va smime-crl-file ,
9313 .Va smime-no-default-ca ,
9314 .Va smime-sign ,
9315 .Va smime-sign-cert ,
9316 .Va smime-sign-include-certs
9318 .Va smime-sign-message-digest .
9321 After it has been verified save the certificate via
9322 .Ic certsave
9323 and tell \*(UA that it should use it for encryption for further
9324 communication with that somebody:
9326 .Bd -literal -offset indent
9327 certsave FILENAME
9328 set smime-encrypt-USER@HOST=FILENAME \e
9329     smime-cipher-USER@HOST=AES256
9333 Additional variables of interest for S/MIME en- and decryption:
9334 .Va smime-cipher
9336 .Va smime-encrypt-USER@HOST .
9339 You should carefully consider if you prefer to store encrypted messages
9340 in decrypted form.
9341 If you do, anybody who has access to your mail folders can read them,
9342 but if you do not, you might be unable to read them yourself later if
9343 you happen to lose your private key.
9345 .Ic decrypt
9346 command saves messages in decrypted form, while the
9347 .Ic save , copy ,
9349 .Ic move
9350 commands leave them encrypted.
9353 Note that neither S/MIME signing nor encryption applies to message
9354 subjects or other header fields yet.
9355 Thus they may not contain sensitive information for encrypted messages,
9356 and cannot be trusted even if the message content has been verified.
9357 When sending signed messages,
9358 it is recommended to repeat any important header information in the
9359 message text.
9360 .\" }}}
9362 .\" .Ss "Using CRLs with S/MIME or SSL/TLS" {{{
9363 .Ss "Using CRLs with S/MIME or SSL/TLS"
9365 \*(OP Certification authorities (CAs) issue certificate revocation
9366 lists (CRLs) on a regular basis.
9367 These lists contain the serial numbers of certificates that have been
9368 declared invalid after they have been issued.
9369 Such usually happens because the private key for the certificate has
9370 been compromised,
9371 because the owner of the certificate has left the organization that is
9372 mentioned in the certificate, etc.
9373 To seriously use S/MIME or SSL/TLS verification,
9374 an up-to-date CRL is required for each trusted CA.
9375 There is otherwise no method to distinguish between valid and
9376 invalidated certificates.
9377 \*(UA currently offers no mechanism to fetch CRLs, nor to access them on
9378 the Internet, so you have to retrieve them by some external mechanism.
9381 \*(UA accepts CRLs in PEM format only;
9382 CRLs in DER format must be converted, like, e.\|g.:
9385 .Dl $ openssl crl \-inform DER \-in crl.der \-out crl.pem
9388 To tell \*(UA about the CRLs, a directory that contains all CRL files
9389 (and no other files) must be created.
9391 .Va smime-crl-dir
9393 .Va ssl-crl-dir
9394 variables, respectively, must then be set to point to that directory.
9395 After that, \*(UA requires a CRL to be present for each CA that is used
9396 to verify a certificate.
9397 .\" }}}
9399 .\" .Ss "Handling spam" {{{
9400 .Ss "Handling spam"
9402 \*(OP \*(UA can make use of several spam interfaces for the purpose of
9403 identification of, and, in general, dealing with spam messages.
9404 A precondition of most commands in order to function is that the
9405 .Va spam-interface
9406 variable is set to one of the supported interfaces.
9407 Once messages have been identified as spam their (volatile)
9408 .Ql is-spam
9409 state can be prompted: the
9410 .Ql Ar :s
9412 .Ql Ar :S
9413 message specifications will address respective messages and their
9414 .Va attrlist
9415 entries will be used when displaying the
9416 .Va headline
9417 in the header display.
9419 .Bl -bullet
9421 .Ic spamrate
9422 rates the given messages and sets their
9423 .Ql is-spam
9424 flag accordingly.
9425 If the spam interface offers spam scores those can also be displayed in
9426 the header display by including the
9427 .Ql %$
9428 format in the
9429 .Va headline
9430 variable.
9432 .Ic spamham ,
9433 .Ic spamspam
9435 .Ic spamforget
9436 will interact with the Bayesian filter of the chosen interface and learn
9437 the given messages as
9438 .Dq ham
9440 .Dq spam ,
9441 respectively; the last command can be used to cause
9442 .Dq unlearning
9443 of messages; it adheres to their current
9444 .Ql is-spam
9445 state and thus reverts previous teachings.
9447 .Ic spamclear
9449 .Ic spamset
9450 will simply set and clear, respectively, the mentioned volatile
9451 .Ql is-spam
9452 message flag, without any interface interaction.
9457 .Xr spamassassin 1
9458 based
9459 .Va spam-interface Ns s
9460 .Ql spamc
9462 .Ql spamd
9463 require a running instance of the
9464 .Xr spamd 1
9465 server in order to function, started with the option
9466 .Fl -allow-tell
9467 shall Bayesian filter learning be possible.
9468 .Ql spamd
9469 only works via a local path-based
9470 .Xr unix 4
9471 socket, but otherwise the following will be equivalently fine:
9473 .Bd -literal -offset indent
9474 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
9475 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \e
9476     --daemonize [--local] [--allow-tell]
9480 Thereafter \*(UA can make use of these interfaces:
9482 .Bd -literal -offset indent
9483 $ \*(ua -Sspam-interface=spamd -Sspam-maxsize=500000 \e
9484     -Sspamd-socket=/tmp/.spamsock -Sspamd-user=
9486 $ \*(ua -Sspam-interface=spamc -Sspam-maxsize=500000 \e
9487     -Sspamc-command=/usr/local/bin/spamc \e
9488     -Sspamc-arguments="-U /tmp/.spamsock" -Sspamc-user=
9490 $ \*(ua -Sspam-interface=spamc -Sspam-maxsize=500000 \e
9491     -Sspamc-command=/usr/local/bin/spamc \e
9492     -Sspamc-arguments="-d localhost -p 2142" -Sspamc-user=
9496 Using the generic filter approach allows usage of programs like
9497 .Xr bogofilter 1
9499 .Xr sylfilter 1 .
9500 Here is an example for the former, requiring it to be accessible via
9501 .Ev PATH :
9503 .Bd -literal -offset indent
9504 $ \*(ua -Sspam-interface=filter -Sspam-maxsize=500000 \e
9505     -Sspamfilter-ham="bogofilter -n" \e
9506     -Sspamfilter-noham="bogofilter -N" \e
9507     -Sspamfilter-nospam="bogofilter -S" \e
9508     -Sspamfilter-rate="bogofilter -TTu 2>/dev/null" \e
9509     -Sspamfilter-spam="bogofilter -s" \e
9510     -Sspamfilter-rate-scanscore="1;^(.+)$"
9514 Because messages must exist on local storage in order to be scored (or
9515 used for Bayesian filter training), it is possibly a good idea to
9516 perform the local spam check last:
9518 .Bd -literal -offset indent
9519 define spamdelhook {
9520   # Server side DCC
9521   spamset (header x-dcc-brand-metrics "bulk")
9522   # Server-side spamassassin(1)
9523   spamset (header x-spam-flag "YES")
9524   del :s # TODO we HAVE to be able to do `spamrate :u ! :sS'
9525   move :S +maybe-spam
9526   spamrate :u
9527   del :s
9528   move :S +maybe-spam
9530 set folder-hook-FOLDER=spamdelhook
9534 See also the documentation for the variables
9535 .Va spam-interface , spam-maxsize ,
9536 .Va spamc-command , spamc-arguments , spamc-user ,
9537 .Va spamd-socket , spamd-user ,
9538 .Va spamfilter-ham , spamfilter-noham , spamfilter-nospam , \
9539   spamfilter-rate
9541 .Va spamfilter-rate-scanscore .
9542 .\" }}}
9543 .\" }}} (Examples)
9546 .\" .Sh "FAQ" {{{
9547 .Sh "FAQ"
9549 .\" .Ss "\*(UA shortly hangs on startup" {{{
9550 .Ss "\*(UA shortly hangs on startup"
9552 This can have two reasons, one is the necessity to wait for a file lock
9553 and can't be helped, the other being that \*(UA calls the function
9554 .Xr uname 2
9555 in order to query the nodename of the box (sometimes the real one is
9556 needed instead of the one represented by the internal variable
9557 .Va hostname ) .
9558 You may have varying success by ensuring that the real hostname and
9559 .Ql localhost
9560 have entries in
9561 .Pa /etc/hosts ,
9562 or, more generally, that the name service is properly setup \(en
9563 and does
9564 .Xr hostname 1
9565 return what you'd expect?
9566 Does this local hostname has a domain suffix?
9567 RFC 6762 standardized the link-local top-level domain
9568 .Ql .local .
9569 .\" }}}
9571 .\" .Ss "I can't login to Google mail a.k.a. GMail" {{{
9572 .Ss "I can't login to Google mail a.k.a. GMail"
9574 Since 2014 some free service providers classify programs as
9575 .Dq less secure
9576 unless they use a special authentification method (OAuth 2.0) which
9577 wasn't standardized for non-HTTP protocol authentication token query
9578 until August 2015 (RFC 7628).
9581 Different to Kerberos / GSSAPI, which is developed since the mid of the
9582 1980s, where a user can easily create a local authentication ticket for
9583 her- and himself with the locally installed
9584 .Xr kinit 1
9585 program, that protocol has no such local part but instead requires
9586 a world-wide-web query to create or fetch a token; since there is no
9587 local cache this query has to be performed whenever \*(UA is invoked
9588 from the command line (in interactive sessions situation may differ).
9591 \*(UA doesn't support OAuth.
9592 Because of this it is necessary to declare \*(UA a
9593 .Dq less secure app
9594 (on the providers account web page) in order to read and send mail.
9595 However, it also seems possible to take the following steps instead:
9598 .Bl -enum -compact
9600 give the provider the number of a mobile phone,
9602 enable
9603 .Dq 2-Step Verification ,
9605 create an application specific password (16 characters), and
9607 use that special password instead of your real Google account password in
9608 S-nail (for more on that see the section
9609 .Sx "On URL syntax and credential lookup" ) .
9611 .\" }}}
9612 .\" }}}
9615 .\" .Sh "SEE ALSO" {{{
9616 .Sh "SEE ALSO"
9618 .Xr bogofilter 1 ,
9619 .Xr bzip2 1 ,
9620 .Xr file 1 ,
9621 .Xr fmt 1 ,
9622 .Xr gpg 1 ,
9623 .Xr gpg-agent 1 ,
9624 .Xr gzip 1 ,
9625 .Xr less 1 ,
9626 .Xr more 1 ,
9627 .Xr newaliases 1 ,
9628 .Xr openssl 1 ,
9629 .Xr postfix 1 ,
9630 .Xr printf 1 ,
9631 .Xr sendmail 1 ,
9632 .Xr sh 1 ,
9633 .Xr spamassassin 1 ,
9634 .Xr spamc 1 ,
9635 .Xr spamd 1 ,
9636 .Xr sylfilter 1 ,
9637 .Xr vacation 1 ,
9638 .Xr xterm 1 ,
9639 .Xr xz 1 ,
9640 .Xr iconv 3 ,
9641 .Xr readline 3 ,
9642 .Xr setlocale 3 ,
9643 .Xr ssl 3 ,
9644 .Xr aliases 5 ,
9645 .Xr termcap 5 ,
9646 .Xr terminfo 5 ,
9647 .Xr locale 7 ,
9648 .Xr mailaddr 7 ,
9649 .Xr re_format 7 ,
9650 .Xr exim 8 ,
9651 .Xr mailwrapper 8 ,
9652 .Xr sendmail 8
9653 .\" }}}
9656 .\" .Sh HISTORY {{{
9657 .Sh HISTORY
9659 M. Douglas McIlroy writes in his article
9660 .Dq A Research UNIX Reader: Annotated Excerpts \
9661 from the Programmer's Manual, 1971-1986
9663 .Xr mail 1
9664 command already appeared in First Edition
9666 in 1971:
9668 .Bd -ragged -offset indent
9669 Electronic mail was there from the start.
9670 Never satisfied with its exact behavior, everybody touched it at one
9671 time or another: to assure the safety of simultaneous access, to improve
9672 privacy, to survive crashes, to exploit uucp, to screen out foreign
9673 freeloaders, or whatever.
9674 Not until v7 did the interface change (Thompson).
9675 Later, as mail became global in its reach, Dave Presotto took charge and
9676 brought order to communications with a grab-bag of external networks
9677 (v8).
9682 Mail was written in 1978 by Kurt Shoens and developed as part of the
9685 distribution until 1995.
9686 Mail has then seen further development in open source
9688 variants, noticeably by Christos Zoulas in
9689 .Pf Net Bx .
9690 Basing upon this Nail, later Heirloom Mailx, was developed by Gunnar
9691 Ritter in the years 2000 until 2008.
9692 Since 2012 S-nail is maintained by Steffen (Daode) Nurpmeso.
9693 This man page is derived from
9694 .Dq The Mail Reference Manual
9695 that was originally written by Kurt Shoens.
9696 .\" }}}
9699 .Sh AUTHORS
9701 .An "Kurt Shoens" ,
9702 .An "Christos Zoulas" ,
9703 .An "Gunnar Ritter" ,
9704 .An "Steffen Nurpmeso" Aq Mt s-nail-users@lists.sourceforge.net
9705 (later
9706 .Mt s-mailx@sdaoden.eu ) .
9709 .\" .Sh CAVEATS {{{
9710 .Sh CAVEATS
9712 The character set conversion uses and relies upon the
9713 .Xr iconv 3
9714 function.
9715 Its functionality differs widely between the various system environments
9716 \*(UA runs on.
9719 Limitations with POP3 mailboxes are:
9720 It is not possible to edit messages, they can only be copied and deleted.
9721 The line count for the header display is only appropriate if the entire
9722 message has been downloaded from the server.
9723 The status field of a message is maintained by the server between
9724 connections; some servers do not update it at all, and with a server
9725 that does, the
9726 .Ic exit
9727 command will not cause the message status to be reset.
9729 .Ic newmail
9730 command and the
9731 .Va newmail
9732 variable have no effect.
9733 It is not possible to rename or to remove POP3 mailboxes.
9736 If a
9737 .Dq RUBOUT
9738 (interrupt,
9739 .Ql control-C )
9740 is typed while a POP3 operation is in progress, \*(UA will wait
9741 until the operation can be safely aborted, and will then return to the
9742 command loop and print the prompt again.
9743 When a second
9744 .Dq RUBOUT
9745 is typed while \*(UA is waiting for the operation to complete, the
9746 operation itself will be cancelled.
9747 In this case, data that has not been fetched yet will have to be fetched
9748 before the next command can be performed.
9749 If the cancelled operation was using an SSL/TLS encrypted channel,
9750 an error in the SSL transport will very likely result and render the
9751 connection unusable.
9754 As \*(UA is a mail user agent, it provides only basic SMTP services.
9755 If it fails to contact its upstream SMTP server, it will not make
9756 further attempts to transfer the message at a later time,
9757 and it does not leave other information about this condition than an
9758 error message on the terminal and an entry in
9759 .Ev DEAD .
9760 This is usually not a problem if the SMTP server is located in the same
9761 local network as the computer on which \*(UA is run.
9762 However, care should be taken when using a remote server of an ISP;
9763 it might be better to set up a local SMTP server then which just acts as
9764 a proxy.
9767 \*(UA immediately contacts the SMTP server (or
9768 .Xr sendmail 1 ) .
9769 It would not make much sense for \*(UA to defer outgoing mail since SMTP
9770 servers usually provide much more elaborated delay handling than \*(UA
9771 could perform as a client.
9772 .\" }}}
9775 .Sh BUGS
9777 See the file
9778 .Pa TODO
9779 from the distribution or the repository.
9781 After deleting some message of a POP3 mailbox the header summary falsely
9782 claims that there are no messages to display, you need to perform
9783 a scroll or dot movement to restore proper state.
9785 In threaded display a power user may encounter crashes very
9786 occasionally (this is may and very).
9787 .\" s-ts-mode