1S-NAIL(1) BSD General Commands Manual S-NAIL(1)
2
4 S-nail [v14.9.24] — send and receive Internet mail
5
7 s-nail [-DdEFinv~#] [-: spec] [-A account] [:-a attachment:]
8 [:-b bcc-addr:] [:-C "field: body":] [:-c cc-addr:]
9 [-M type | -m file | -q file | -t] [-r from-addr]
10 [:-S var[=value]:] [-s subject] [:-T "field: addr":] [:-X cmd:]
11 [:-Y cmd:] [-.] :to-addr: [-- :mta-option:]
12 s-nail [-DdEeHiNnRv~#] [-: spec] [-A account] [:-C "field: body":]
14 [-L spec] [-r from-addr] [:-S var[=value]:] [-u user] [:-X cmd:]
15 [:-Y cmd:] [-- :mta-option:]
16 s-nail [-DdEeHiNnRv~#] [-: spec] [-A account] [:-C "field: body":] -f
17 [-L spec] [-r from-addr] [:-S var[=value]:] [:-X cmd:] [:-Y cmd:]
18 [file] [-- :mta-option:]
19 s-nail -h | --help
21 s-nail -V | --version
22
24 Note: S-nail (S-nail) will see major changes in v15.0 (circa 2022).
25 Some backward incompatibilities cannot be avoided. COMMANDS change
26 to Shell-style argument quoting, and shell metacharacters will be‐
27 come (more) meaningful. Some commands accept new syntax today via
28 wysh (Command modifiers). Behaviour is flagged [v15-compat] and
29 [no v15-compat], setting v15-compat (INTERNAL VARIABLES) will
30 choose new behaviour when applicable; giving it a value makes wysh
31 an implied default. [Obsolete] flags what will vanish.
32 Warning! v15-compat (with value) will be a default in v14.10.0!
34 S-nail provides a simple and friendly environment for sending and receiv‐
36 ing mail. It is intended to provide the functionality of the POSIX
37 mailx(1) command, but is MIME capable and optionally offers extensions
38 for line editing, S/MIME, SMTP and POP3, among others. S-nail divides
39 incoming mail into its constituent messages and allows the user to deal
40 with them in any order. It offers many COMMANDS and INTERNAL VARIABLES
41 for manipulating messages and sending mail. It provides the user simple
42 editing capabilities to ease the composition of outgoing messages, and
43 increasingly powerful and reliable non-interactive scripting capabili‐
44 ties.
45 Options
47 -: spec, --resource-files=..
48 Controls loading of (as via source) Resource files: spec is
49 parsed case-insensitively, the letter ‘s’ corresponds to the
50 system wide s-nail.rc, ‘u’ the user's personal file ~/.mailrc.
51 The (original) system wide resource is also compiled-in, acces‐
52 sible via ‘x’. The letters ‘-’ and ‘/’ disable usage of re‐
53 source files. Order matters, default is ‘su’. This option
54 overrides -n.
55 -A name, --account=..
57 Activate user account name after program startup is complete
58 (resource files loaded, only -X commands are to be executed),
59 and switch to its primary system mailbox (most likely the
60 inbox). If activation fails the program exits if used non-in‐
61 teractively, or if any of errexit or posix are set.
62 -a file[=input-charset[#output-charset]], --attach=..
64 (Send mode) Attach file. For (Compose mode) opportunities re‐
65 fer to ~@ and ~^. file is subject to tilde expansion (see
66 Filename transformations and folder); if it is not accessible
67 but contains a ‘=’ character, anything before the last ‘=’ will
68 be used as the filename, anything thereafter as a character set
69 specification, as shown.
70 If only an input character set is specified, the input side is
72 fixed, and no character set conversion will be applied; an
73 empty or the special string hyphen-minus ‘-’ is taken for
74 ttycharset (the default). If an output character set has also
75 been specified the desired conversion is performed immediately,
76 not considering file type and content, except for an empty
77 string or hyphen-minus ‘-’, which select the default conversion
78 algorithm (see Character sets): no immediate conversion is per‐
79 formed, file and its contents will be MIME-classified (HTML
80 mail and MIME attachments, The mime.types files) first — only
81 the latter mode is available unless features includes
82 ‘,+iconv,’.
83 -B ([Obsolete]: S-nail will always use line-buffered output, to
85 gain line-buffered input even in batch mode enable batch mode
86 via -#.)
87 -b addr, --bcc=..
89 (Send mode) Send a blind carbon copy to recipient addr. The
90 option may be used multiple times. Also see the section On
91 sending mail, and non-interactive mode.
92 -C "field: body", --custom-header=..
94 Create a custom header which persists for an entire session. A
95 custom header consists of the field name followed by a colon
96 ‘:’ and the field content body, for example ‘-C "Blah: Neminem
97 laede; imo omnes, quantum potes, juva"’. Standard header field
98 names cannot be overwritten by custom headers. Runtime ad‐
99 justable custom headers are available via the variable
100 customhdr, and in (Compose mode) ~^, one of the COMMAND
101 ESCAPES, as well as digmsg are the most flexible and powerful
102 options to manage message headers. This option may be used
103 multiple times.
104 -c addr, --cc=..
106 (Send mode) Just like -b, except it places the argument in the
107 list of carbon copies.
108 -D, --disconnected
110 [Option] Startup with disconnected set.
111 -d, --debug
113 Enter a debug-only sandbox mode by setting the internal vari‐
114 able debug; the same can be achieved via ‘-S debug’ or ‘set
115 debug’. Also see -v.
116 -E, --discard-empty-messages
118 (Send mode) set skipemptybody and thus discard messages with an
119 empty message part body, successfully.
120 -e, --check-and-exit
122 Just check if mail is present (in the system inbox or the one
123 specified via -f): if yes, return an exit status of zero, a
124 non-zero value otherwise. To restrict the set of mails to con‐
125 sider in this evaluation a message specification can be added
126 with the option -L. Quickrun: does not open an interactive
127 session.
128 -F (Send mode) Save the message to send in a file named after the
130 local part of the first recipient's address (instead of in
131 record).
132 -f, --file
134 Read in the contents of the user's secondary mailbox MBOX (or
135 the specified file) for processing; when S-nail is quit, it
136 writes undeleted messages back to this file (but be aware of
137 the hold option). The optional file argument will undergo some
138 special Filename transformations (as via folder). Note that
139 file is not an argument to the flag -f, but is instead taken
140 from the command line after option processing has been com‐
141 pleted. In order to use a file that starts with a hyphen-mi‐
142 nus, prefix with a relative path, as in ‘./-hyphenbox.mbox’.
143 -H, --header-summary
145 Display a summary of headers for the given folder (depending on
146 -u, inbox or MAIL, or as specified via -f), then exit. A con‐
147 figurable summary view is available via the option -L. This
148 mode does not honour showlast. Quickrun: does not open an in‐
149 teractive session.
150 -h, --help
152 Show a brief usage summary; use --long-help for a list long op‐
153 tions.
154 -i set ignore to ignore tty interrupt signals.
156 -L spec, --search=..
158 Display a summary of headers of all messages that match the
159 given spec in the folder found by the same algorithm used by
160 -H, then exit. See the section Specifying messages for the
161 format of spec. This mode does not honour showlast.
162 If the -e option has been given in addition no header summary
164 is produced, but S-nail will instead indicate via its exit sta‐
165 tus whether spec matched any messages (‘0’) or not (‘1’); note
166 that any verbose output is suppressed in this mode and must in‐
167 stead be enabled explicitly (see -v). Quickrun: does not open
168 an interactive session.
169 -M type (Send mode) Will flag standard input with the MIME
171 ‘Content-Type:’ set to the given known type (HTML mail and MIME
172 attachments, The mime.types files) and use it as the main mes‐
173 sage body. [v15 behaviour may differ] Using this option will
174 bypass processing of message-inject-head and
175 message-inject-tail. Also see -q, -m, -t.
176 -m file (Send mode) MIME classify the specified file and use it as the
178 main message body. [v15 behaviour may differ] Using this op‐
179 tion will bypass processing of message-inject-head and
180 message-inject-tail. Also see -q, -M, -t.
181 -N, --no-header-summary
183 inhibit the initial display of message headers when reading
184 mail or editing a mailbox folder by calling unset for the in‐
185 ternal variable header.
186 -n Standard flag that inhibits reading the system wide s-nail.rc
188 upon startup. The option -: allows more control over the
189 startup sequence; also see Resource files.
190 -q file, --quote-file=..
192 (Send mode) Initialize the message body with the contents of
193 file, which may be standard input ‘-’ only in non-interactive
194 context. Also see -M, -m, -t.
195 -R, --read-only
197 Any mailbox folder aka folder opened will be in read-only mode.
198 -r from-addr, --from-address=..
200 The RFC 5321 reverse-path used for relaying and delegating mes‐
201 sages to its destination(s), for example to report delivery er‐
202 rors, is normally derived from the address which appears in the
203 from header (or, if that contains multiple addresses, in
204 sender). A file-based aka local executable mta (Mail-Transfer-
205 Agent), however, instead uses the local identity of the initi‐
206 ating user.
207 When this command line option is used the given single ad‐
209 dressee from-addr will be assigned to the internal variable
210 from, but in addition the command line option -f from-addr will
211 be passed to a file-based mta whenever a message is sent.
212 Shall from-addr include a user name the address components will
213 be separated and the name part will be passed to a file-based
214 mta individually via -F name. Even though not a recipient the
215 ‘shquote’ expandaddr flag is supported.
216 If an empty string is passed as from-addr then the content of
218 the variable from (or, if that contains multiple addresses,
219 sender) will be evaluated and used for this purpose whenever
220 the file-based mta is contacted. By default, without -r that
221 is, neither -f nor -F command line options are used when con‐
222 tacting a file-based MTA, unless this automatic deduction is
223 enforced by setting the internal variable r-option-implicit.
224 Remarks: many default installations and sites disallow overrid‐
226 ing the local user identity like this unless either the MTA has
227 been configured accordingly or the user is member of a group
228 with special privileges. Passing an invalid address will cause
229 an error.
230 -S var[=value], --set=..
232 set (or, with a prefix string ‘no’, as documented in INTERNAL
233 VARIABLES, unset) variable and optionally assign value, if sup‐
234 ported; [v15 behaviour may differ] the entire expression is
235 evaluated as if specified within dollar-single-quotes (see
236 Shell-style argument quoting) if the internal variable
237 v15-compat is set. If the operation fails the program will
238 exit if any of errexit or posix are set. Settings established
239 via -S cannot be changed from within Resource files or an ac‐
240 count switch initiated by -A. They will become mutable again
241 before commands registered via -X are executed.
242 -s subject, --subject=..
244 (Send mode) Specify the subject of the message to be sent.
245 Newline (NL) and carriage-return (CR) bytes are invalid and
246 will be normalized to space (SP) characters.
247 -T "field: addr", --target=..
249 (Send mode) Add addr to the list of receivers targeted by
250 field, for now supported are only ‘bcc’, ‘cc’, ‘fcc’, and ‘to’.
251 Field and body (address) are separated by a colon ‘:’ and op‐
252 tionally blank (space, tabulator) characters. The ‘shquote’
253 expandaddr flag is supported. addr is parsed like a message
254 header address line, as if it would be part of a template mes‐
255 sage fed in via -t, and the same modifier suffix is supported.
256 This option may be used multiple times.
257 -t, --template
259 (Send mode) The text message given (on standard input) is ex‐
260 pected to contain, separated from the message body by an empty
261 line, one or multiple plain text message headers. [v15 behav‐
262 iour may differ] Readily prepared MIME mail messages cannot be
263 passed. Headers can span multiple consecutive lines if follow
264 lines start with any amount of whitespace. A line starting
265 with the number sign ‘#’ in the first column is ignored. Mes‐
266 sage recipients can be given via the message headers ‘To:’,
267 ‘Cc:’, ‘Bcc:’ (the ‘?single’ modifier enforces treatment as a
268 single addressee, for example ‘To?single: exa, <m@ple>’) or
269 ‘Fcc:’, they will be added to any recipients specified on the
270 command line, and are likewise subject to expandaddr validity
271 checks. If a message subject is specified via ‘Subject:’ then
272 it will be used in favour of one given on the command line.
273 More optional headers are ‘Reply-To:’ (possibly overriding
275 reply-to), ‘Sender:’ (sender), ‘From:’ (from and / or option
276 -r). ‘Message-ID:’, ‘In-Reply-To:’, ‘References:’ and
277 ‘Mail-Followup-To:’, by default created automatically dependent
278 on message context, will be used if specified (a special ad‐
279 dress massage will however still occur for the latter). Any
280 other custom header field (also see -C, customhdr and ~^) is
281 passed through entirely unchanged, and in conjunction with the
282 options -~ or -# it is possible to embed COMMAND ESCAPES. Also
283 see -M, -m, -q.
284 -u user, --inbox-of=..
286 Initially read the primary system mailbox of user, appropriate
287 privileges presumed; effectively identical to ‘-f %user’.
288 -V, --version
290 Show S-nails version and exit. The command version will also
291 show the list of features: ‘$ s-nail -:/ -Xversion -Xx’.
292 -v, --verbose
294 sets the internal variable verbose to enable logging of infor‐
295 mational context messages. (Increases level of verbosity when
296 used multiple times.) Also see -d.
297 -X cmd, --startup-cmd=..
299 Add the given (or multiple for a multiline argument) cmd to a
300 list of commands to be executed before normal operation starts.
301 The commands will be evaluated as a unit, just as via source.
302 Correlates with -# and errexit.
303 -Y cmd, --cmd=..
305 Add the given (or multiple for a multiline argument) cmd to a
306 list of commands to be executed after normal operation has
307 started. The commands will be evaluated successively in the
308 given order, and as if given on the program's standard input —
309 before interactive prompting begins in interactive mode, after
310 standard input has been consumed otherwise.
311 -~, --enable-cmd-escapes
313 Enable COMMAND ESCAPES in (Compose mode) even in non-interac‐
314 tive use cases. This can for example be used to automatically
315 format the composed message text before sending the message:
316 $ ( echo 'line one. Word. Word2.';\
318 echo '~| /usr/bin/fmt -tuw66' ) |\
319 LC_ALL=C s-nail -d~:/ -Sttycharset=utf-8 bob@exam.ple
320 -#, --batch-mode
322 Enables batch mode: standard input is made line buffered, the
323 complete set of (interactive) commands is available, processing
324 of COMMAND ESCAPES is enabled in Compose mode, and diverse
325 INTERNAL VARIABLES are adjusted for batch necessities, exactly
326 as if done via -S: emptystart, noerrexit, noheader, noposix,
327 quiet, sendwait, typescript-mode as well as MAIL, MBOX and
328 inbox (the latter three to /dev/null). Also, the values of
329 COLUMNS and LINES are looked up, and acted upon. The following
330 prepares an email message in a batched dry run:
331 $ for name in bob alice@exam.ple lisa@exam.ple; do
333 printf 'mail %s\n~s ubject\nText\n~.\n' "${name}"
334 done |
335 LC_ALL=C s-nail -#:x -Smta=test \
336 -X'alias bob bob@exam.ple'
337 -., --end-options
339 This flag forces termination of option processing in order to
340 prevent “option injection” (attacks). It also forcefully puts
341 S-nail into send mode, see On sending mail, and non-interactive
342 mode.
343 If the setting of expandargv allows their recognition all mta-option ar‐
345 guments given at the end of the command line after a ‘--’ separator will
346 be passed through to a file-based mta (Mail-Transfer-Agent) and persist
347 for the entire session. expandargv constraints do not apply to the con‐
348 tent of mta-arguments. Command line receiver address handling supports
349 the ‘shquote’ constraint of expandaddr, for more please see On sending
350 mail, and non-interactive mode.
351 $ s-nail -#:/ -X 'addrcodec enc Hey, ho <silver@go>' -Xx
353 A starter
355 S-nail is a direct descendant of BSD Mail, itself a successor to the Re‐
356 search UNIX mail which “was there from the start” according to HISTORY.
357 It thus represents the user side of the UNIX mail system, whereas the
358 system side (Mail-Transfer-Agent, MTA) was traditionally taken by
359 sendmail(8) (and most MTAs provide a binary of this name for compatibil‐
360 ity reasons). If the [Option]al SMTP mta is included in the features of
361 S-nail then the system side is not a mandatory precondition for mail de‐
362 livery.
363 S-nail strives for compliance with the POSIX mailx(1) standard, but
365 posix, one of the INTERNAL VARIABLES, or its ENVIRONMENTal equivalent
366 POSIXLY_CORRECT, needs to be set to adjust behaviour to be almost on par.
367 Almost, because there is one important difference: POSIX Shell-style
368 argument quoting is ([v15 behaviour may differ] increasingly) used in‐
369 stead of the Old-style argument quoting that the standard documents,
370 which is believed to be a feature. The builtin as well as the (default)
371 global s-nail.rc Resource files already bend the standard imposed set‐
372 tings a bit.
373 For example, hold and keepsave are set in order to suppress the automatic
375 moving of messages to the secondary mailbox MBOX that would otherwise oc‐
376 cur (see Message states), and keep to not remove empty system MBOX mail‐
377 box files (or all empty such files in posix mode) to avoid mangling of
378 file permissions when files eventually get recreated.
379 To enter interactive mode even if the initial mailbox is empty emptystart
381 is set, editheaders to allow editing of headers as well as fullnames to
382 not strip down addresses in Compose mode, and quote to include the mes‐
383 sage that is being responded to when replying, which is indented by an
384 indentprefix that also deviates from standard imposed settings.
385 mime-counter-evidence is fully enabled, too. It sets followup-to-honour
386 and reply-to-honour to comply with reply address desires.
387 Credentials and other settings are easily addressable by grouping them
389 via account. The file mode creation mask can be managed with umask.
390 Files and shell pipe output can be sourced for evaluation, also during
391 startup from within the Resource files. Informational context can be
392 available by setting verbose or debug (as via -v, -d).
393 On sending mail, and non-interactive mode
395 To send a message to one or more people, using a local or built-in mta
396 (Mail-Transfer-Agent) transport to actually deliver the generated mail
397 message, S-nail can be invoked with arguments which are the names of peo‐
398 ple to whom the mail will be sent, and the command line options -b and -c
399 can be used to add (blind) carbon copy receivers:
400 # Via test MTA
402 $ echo Hello, world | s-nail -:/ -Smta=test -s test $LOGNAME
403 # Via sendmail(1) MTA
405 $ </dev/null s-nail -:x -s test $LOGNAME
406 # Debug dry-run mode:
408 $ </dev/null LC_ALL=C s-nail -d -:/ \
409 -Sttycharset=utf8 -Sfullnames \
410 -b bcc@exam.ple -c cc@exam.ple -. \
411 '(Lovely) Bob <bob@exam.ple>' eric@exam.ple
412 # With SMTP (no real sending due to -d debug dry-run)
414 $ LC_ALL=C s-nail -d -:/ -Sv15-compat -Sttycharset=utf8 \
415 -S mta=smtps://mylogin@exam.ple:465 -Ssmtp-auth=none \
416 -S from=scriptreply@exam.ple \
417 -a /etc/mail.rc --end-options \
418 eric@exam.ple < /tmp/letter.txt
419 Email addresses and plain user names are subject to alternates filtering,
421 names only are first expanded through alias and mta-aliases. An address
422 in angle brackets consisting only of a valid local user ‘<name>’ will be
423 converted to a fully qualified address if either hostname is not set, or
424 set to a non-empty value; if set to the empty value the conversion is
425 left up to the mta. By setting expandaddr fine-grained control of recip‐
426 ient address types other than user names and network addresses is possi‐
427 ble. Recipients are classified as follows: any name that starts with a
428 vertical bar ‘|’ character specifies a command pipe – the command string
429 following the ‘|’ is executed and the message is sent to its standard in‐
430 put; likewise, any name that consists only of hyphen-minus ‘-’ or starts
431 with the character solidus ‘/’ or the character sequence dot solidus ‘./’
432 is treated as a file, regardless of the remaining content. Any other
433 name which contains a commercial at ‘@’ character is a network address;
434 Any other name which starts with a plus sign ‘+’ character is a mailbox
435 name; Any other name which contains a solidus ‘/’ character but no excla‐
436 mation mark ‘!’ or percent sign ‘%’ character before is also a mailbox
437 name; What remains is treated as a network address. This classification
438 can be avoided by using a ‘Fcc:’ header, see Compose mode.
439 $ echo bla | s-nail -Sexpandaddr -s test ./mbox.mbox
441 $ echo bla | s-nail -Sexpandaddr -s test '|cat >> ./mbox.mbox'
442 $ echo safe | LC_ALL=C \
443 s-nail -:/ -Smta=test -Sv15-compat -Sttycharset=utf8 \
444 --set mime-force-sendout --set fullnames \
445 -S expandaddr=fail,-all,+addr,failinvaddr -s test \
446 --end-options 'Imagine John <cold@turk.ey>'
447 Before messages are sent they undergo editing in Compose mode. But many
449 settings are static and can be set more generally. The envelope sender
450 address for example is defined by from, explicitly defining an originat‐
451 ing hostname may be desirable, especially with the built-in SMTP Mail-
452 Transfer-Agent mta. Character sets for outgoing message and MIME part
453 content are configurable via sendcharsets, whereas input data is assumed
454 to be in ttycharset. Message data will be passed over the wire in a
455 mime-encoding, and MIME parts aka attachments need a mimetype, usually
456 taken out of The mime.types files. Saving copies of sent messages in a
457 record mailbox may be desirable – as for most mailbox folder targets
458 Filename transformations will be performed.
459 For the purpose of arranging a complete environment of settings that can
461 be switched to with a single command or command line option there are
462 accounts. Alternatively a flat configuration could be possible, making
463 use of so-called variable chains which automatically pick ‘USER@HOST’ or
464 ‘HOST’ context-dependent variants some variables support: for example ad‐
465 dressing ‘Folder pop3://yaa@exam.ple’ would find
466 pop3-no-apop-yaa@exam.ple, pop3-no-apop-exam.ple and pop3-no-apop in or‐
467 der. For more please see On URL syntax and credential lookup and
468 INTERNAL VARIABLES.
469 To avoid environmental noise scripts should create a script-local envi‐
471 ronment, ideally with the command line options -: to disable configura‐
472 tion files in conjunction with repetitions of -S to specify variables:
473 $ env LC_ALL=C s-nail -:/ \
475 -Sv15-compat \
476 -Sttycharset=utf-8 -Smime-force-sendout \
477 -Sexpandaddr=fail,-all,failinvaddr \
478 -S mta=smtps://mylogin@exam.ple:465 -Ssmtp-auth=login \
479 -S from=scriptreply@exam.ple \
480 -s 'Subject to go' -a attachment_file \
481 -Sfullnames -. \
482 'Recipient 1 <rec1@exam.ple>' rec2@exam.ple \
483 < content_file
484 As shown, scripts producing messages can “fake” a locale environment, the
486 above specifies the all-compatible 7-bit clean LC_ALL “C”, but will none‐
487 theless take and send UTF-8 in the message text by using ttycharset. If
488 character set conversion is compiled in (features includes the term
489 ‘,+iconv,’) invalid (according to ttycharset) character input data would
490 normally cause errors; setting mime-force-sendout will instead, as a last
491 resort, classify the input as binary data, and therefore allow message
492 creation to be successful. (Such content can then be inspected either by
493 installing a pipe-TYPE/SUBTYPE handler for ‘application/octet-stream’, or
494 possibly automatically through mime-counter-evidence).
495 In interactive mode, introduced soon, messages can be sent by calling the
497 mail command with a list of recipient addresses:
498 $ s-nail -:/ -Squiet -Semptystart -Sfullnames -Smta=test
500 "/var/spool/mail/user": 0 messages
501 ? mail "Recipient 1 <rec1@exam.ple>", rec2@exam.ple
502 ...
503 ? # Will do the right thing (tm)
504 ? m rec1@exam.ple rec2@exam.ple
505 Compose mode
507 If standard input is a terminal rather than the message to be sent, the
508 user is expected to type in the message contents. In compose mode lines
509 beginning with the character ‘~’ (in fact the value of escape) are spe‐
510 cial – these are so-called COMMAND ESCAPES which can be used to read in
511 files, process shell commands, add and edit attachments and more. For
512 example ~v or ~e will start the VISUAL text EDITOR, respectively, to re‐
513 vise the message in its current state, ~h allows editing of the most im‐
514 portant message headers, with the potent ~^ custom headers can be cre‐
515 ated, for example (more specifically than with -C and customhdr). [Op‐
516 tion]ally ~? gives an overview of most other available command escapes.
517 To create file-carbon-copies the special recipient header ‘Fcc:’ may be
519 used as often as desired, for example via ~^. Its entire value (or body
520 in standard terms) is interpreted as a folder target, after having been
521 subject to Filename transformations: this is the only way to create a
522 file-carbon-copy without introducing an ambiguity regarding the interpre‐
523 tation of the address, file names with leading vertical bars or commer‐
524 cial ats can be used. Like all other recipients ‘Fcc:’ is subject to the
525 checks of expandaddr. Any local file and pipe command addressee honours
526 the setting of mbox-fcc-and-pcc.
527 Once finished with editing the command escape ~. (see there) will call
529 hooks, insert automatic injections and receivers, leave compose mode and
530 send the message once it is completed. Aborting letter composition is
531 possible with either of ~x or ~q, the latter of which will save the mes‐
532 sage in the file denoted by DEAD unless nosave is set. And unless
533 ignoreeof is set the effect of ~. can also be achieved by typing end-of-
534 transmission (EOT) via ‘control-D’ (‘^D’) at the beginning of an empty
535 line, and ~q is always reachable by typing end-of-text (ETX) twice via
536 ‘control-C’ (‘^C’).
537 The compose mode hooks on-compose-enter, on-compose-splice,
539 on-compose-leave and on-compose-cleanup may be set to defined macros and
540 provide reliable and increasingly powerful mechanisms to perform auto‐
541 mated message adjustments dependent on message context, for example addi‐
542 tion of message signatures (message-inject-head, message-inject-tail) or
543 creation of additional receiver lists (also by setting autocc, autobcc).
544 To achieve that the command digmsg may be used in order to query and ad‐
545 just status of message(s). The splice hook can also make use of COMMAND
546 ESCAPES. ([v15 behaviour may differ] The compose mode hooks work for
547 forward, mail, reply and variants; resend and Resend only provide the
548 hooks on-resend-enter and on-resend-cleanup, which are pretty restricted
549 due to the nature of the operation.)
550 On reading mail, and more on interactive mode
552 When invoked without addressees S-nail enters interactive mode in which
553 mails may be read. When used like that the user's system inbox (for more
554 on mailbox types please see the command folder) is read in and a one line
555 header of each message therein is displayed if the variable header is
556 set. The visual style of this summary of headers can be adjusted through
557 the variable headline and the possible sorting criterion via autosort.
558 Scrolling through screenfuls of headers can be performed with the command
559 z. If the initially opened mailbox is empty S-nail will instead exit im‐
560 mediately (after displaying a message) unless the variable emptystart is
561 set.
562 At the prompt the command list will give a listing of all available com‐
564 mands and help will [Option]ally give a summary of some common ones. If
565 the [Option]al documentation strings are available (see features) one can
566 type ‘help X’ (or ‘?X’) and see the actual expansion of ‘X’ and what its
567 purpose is, i.e., commands can be abbreviated (note that POSIX defines
568 some abbreviations, so that the alphabetical order of commands does not
569 necessarily relate to the abbreviations; it is however possible to define
570 overwrites with commandalias). These commands can also produce a more
571 verbose output.
572 Messages are given numbers (starting at 1) which uniquely identify mes‐
574 sages; the current message – the “dot” – will either be the first new
575 message, or the first unread message, or the first message of the mail‐
576 box; the internal variable showlast will instead cause usage of the last
577 message for this purpose. The command headers will display a screenful
578 of header summaries containing the “dot”, whereas from will display only
579 the summaries of the given messages, defaulting to the “dot”.
580 Message content can be displayed with the command type (‘t’, alias
582 print). Here the variable crt controls whether and when S-nail will use
583 the configured PAGER for display instead of directly writing to the user
584 terminal screen, the sole difference to the command more, which will al‐
585 ways use the PAGER. The command top will instead only show the first
586 toplines of a message (maybe even compressed if topsqueeze is set). Mes‐
587 sage display experience may improve by setting and adjusting
588 mime-counter-evidence, and also see HTML mail and MIME attachments.
589 By default the current message (“dot”) is displayed, but like with many
591 other commands it is possible to give a fancy message specification (see
592 Specifying messages), for example ‘t:u’ will display all unread messages,
593 ‘t.’ will display the “dot”, ‘t 1 5’ will type the messages 1 and 5, ‘t
594 1-5’ will type the messages 1 through 5, and ‘t-’ and ‘t+’ will display
595 the previous and the next message, respectively. The command search (a
596 more substantial alias for from) will display a header summary of the
597 given message specification list instead of their content; the following
598 will search for subjects:
599 ? from '@Some subject to search for'
601 In the default setup all header fields of a message will be typed, but
603 fields can be white- or blacklisted for a variety of applications by us‐
604 ing the command headerpick, e.g., to restrict their display to a very re‐
605 stricted set for type: ‘headerpick type retain from to cc subject’. In
606 order to display all header fields of a message regardless of currently
607 active ignore or retain lists, use the commands Type and Top; Show will
608 show the raw message content. Note that historically the global
609 s-nail.rc not only adjusts the list of displayed headers, but also sets
610 crt. ([v15 behaviour may differ] A yet somewhat restricted) Reliable
611 scriptable message inspection is available via digmsg.
612 Dependent upon the configuration a line editor (see the section On
614 terminal control and line editor) aims at making the user experience with
615 the many COMMANDS a bit nicer. When reading the system inbox, or when -f
616 (or folder) specified a mailbox explicitly prefixed with the special ‘%:’
617 modifier (to propagate it to a primary system mailbox), then messages
618 which have been read (see Message states) will be automatically moved to
619 a secondary mailbox, the user's MBOX file, when the mailbox is left, ei‐
620 ther by changing the active mailbox or by quitting S-nail – this auto‐
621 matic moving from a system- or primary- to the secondary mailbox is not
622 performed when the variable hold is set. Messages can also be explicitly
623 moved to other mailboxes, whereas copy keeps the original message. write
624 can be used to write out data content of specific parts of messages.
625 After examining a message the user can reply ‘r’ to the sender and all
627 recipients (which will also be placed in ‘To:’ unless recipients-in-cc is
628 set), or Reply ‘R’ exclusively to the sender(s). To comply with with the
629 receivers desired reply address the quadoptions followup-to-honour and
630 reply-to-honour should usually be set. The commands Lreply and Lfollowup
631 know how to apply a special addressee massage, see Mailing lists. Depen‐
632 dent on the presence and value of quote the message being replied to will
633 be included in a quoted form. forwarding a message will allow editing
634 the new message: the original message will be contained in the message
635 body, adjusted according to headerpick. It is possible to resend or
636 Resend messages: the former will add a series of ‘Resent-’ headers,
637 whereas the latter will not; different to newly created messages editing
638 is not possible and no copy will be saved even with record unless the ad‐
639 ditional variable record-resent is set. When sending, replying or for‐
640 warding messages comments and full names will be stripped from recipient
641 addresses unless the internal variable fullnames is set.
642 Of course messages can be delete ‘d’, and they can spring into existence
644 again via undelete, or when the S-nail session is ended via the exit or
645 xit commands to perform a quick program termation. To end a mail pro‐
646 cessing session regularly and perform a full program exit one may issue
647 the command quit. It will, among others, move read messages to the
648 secondary mailbox MBOX as necessary, discard deleted messages in the cur‐
649 rent mailbox, and update the [Option]al (see features) line editor
650 history-file. By the way, whenever the main event loop is about to look
651 out for the next input line it will trigger the hook on-main-loop-tick.
652 HTML mail and MIME attachments
654 HTML-only messages become more and more common, and many messages come
655 bundled with a bouquet of MIME (Multipurpose Internet Mail Extensions)
656 parts and attachments. To get a notion of MIME types there is a built-in
657 default set, onto which the content of The mime.types files will be added
658 (as configured and allowed by mimetypes-load-control). Types can also
659 become registered and listed with the command mimetype. To improve in‐
660 teraction with the faulty MIME part declarations of real life
661 mime-counter-evidence will allow verification of the given assertion, and
662 the possible provision of an alternative, better MIME type. Note plain
663 text parts will always be preferred in ‘multipart/alternative’ MIME mes‐
664 sages unless mime-alternative-favour-rich is set.
665 Whereas a simple HTML-to-text filter for displaying HTML messages is [Op‐
667 tion]ally supported (indicated by ‘,+filter-html-tagsoup,’ in features),
668 MIME types other than plain text cannot be handled directly. To deal
669 with specific non-text MIME types or file extensions programs need to be
670 registered which either prepare (re-)integrable plain text versions of
671 their input (a mode which is called copiousoutput), or display the con‐
672 tent externally, for example in a graphical window: the latter type is
673 only considered by and for the command mimeview.
674 To install a handler program for a MIME type an according
676 pipe-TYPE/SUBTYPE variable needs to be set; to define a handler for a
677 file extension pipe-EXTENSION can be used – these handlers take prece‐
678 dence. [Option]ally mail user agent configuration is supported (see The
679 Mailcap files), and will be queried for display or quote handlers after
680 the former ones. Type-markers registered via mimetype are the last pos‐
681 sible source for information how to handle a MIME type.
682 For example, to display HTML messages integrated via the text browsers
684 lynx(1) or elinks(1), register a MathML MIME type and enable its plain
685 text display, and to open PDF attachments in an external PDF viewer,
686 asynchronously and with some other magic attached:
687 ? if "$features" !% ,+filter-html-tagsoup,
689 ? #set pipe-text/html='?* elinks -force-html -dump 1'
690 ? set pipe-text/html='?* lynx -stdin -dump -force_html'
691 ? # Display HTML as plain text instead
692 ? #set pipe-text/html=?t
693 ? endif
694 ? mimetype ?t application/mathml+xml mathml
696 ? wysh set pipe-application/pdf='?&=? \
698 trap "rm -f \"${MAILX_FILENAME_TEMPORARY}\"" EXIT;\
699 trap "trap \"\" INT QUIT TERM; exit 1" INT QUIT TERM;\
700 mupdf "${MAILX_FILENAME_TEMPORARY}"'
701 ? define showhtml {
703 ? \localopts yes
704 ? \set mime-alternative-favour-rich pipe-text/html=?h?
705 ? \type "$@"
706 ? }
707 ? \commandalias html \\call showhtml
708 Mailing lists
710 Known or subscribed-to mailing lists may be flagged in the summary of
711 headers (headline format character ‘%L’), and will gain special treatment
712 when sending mails: the variable followup-to-honour will ensure that a
713 ‘Mail-Followup-To:’ header is honoured when a message is being replied to
714 (reply, followup, Lreply, Lfollowup), and followup-to controls creation
715 of this header when creating mails, if the necessary user setup (from,
716 sender); is available; then, it may also be created automatically, for
717 example when list-replying via Lreply or Lfollowup, when followup or
718 reply is used and the messages ‘Mail-Followup-To:’ is honoured etc.
719 The commands mlist and mlsubscribe manage S-nails notion of which ad‐
721 dresses are mailing lists. With the [Option]al regular expression sup‐
722 port any address which contains any of the magic regular expression char‐
723 acters (‘^[*+?|$’; see re_format(7) or regex(7), dependent on the host
724 system) will be compiled and used as one, possibly matching many ad‐
725 dresses. It is not possible to escape the “magic”: in order to match
726 special characters as-is, bracket expressions must be used, for example
727 ‘search @subject@'[[]open bracket'’.
728 ? set followup-to followup-to-honour=ask-yes \
730 reply-to-honour=ask-yes
731 ? mlist a1@b1.c1 a2@b2.c2 '.*@lists\.c3$'
732 ? mlsubscribe a4@b4.c4 exact@lists.c3
733 Known and subscribed lists differ in that for the latter the users ad‐
735 dress is not part of a generated ‘Mail-Followup-To:’. There are excep‐
736 tions, for example if multiple lists are addressed and not all have the
737 subscription attribute. When replying to a message its list address
738 (‘List-Post:’ header) is automatically and temporarily treated like a
739 known mlist; dependent on the variable reply-to-honour an existing
740 ‘Reply-To:’ is used instead (if it is a single address on the same domain
741 as ‘List-Post:’) in order to accept a list administrator's wish that is
742 supposed to have been manifested like that.
743 For convenience and compatibility with mail programs that do not honour
745 the non-standard M-F-T, an automatic user entry in the carbon-copy ‘Cc:’
746 address list of generated message can be created by setting
747 followup-to-add-cc. This entry will be added whenever the user will be
748 placed in the ‘Mail-Followup-To:’ list, and is not a regular addressee
749 already. reply-to-swap-in tries to deal with the address rewriting that
750 many mailing-lists nowadays perform to work around DKIM / DMARC etc.
751 standard imposed problems.
752 Signed and encrypted messages with S/MIME
754 [Option] S/MIME provides two central mechanisms: message signing and mes‐
755 sage encryption. A signed message contains some data in addition to the
756 regular text. The data can be used to verify that the message has been
757 sent using a valid certificate, that the sender address matches that in
758 the certificate, and that the message text has not been altered. Signing
759 a message does not change its regular text; it can be read regardless of
760 whether the recipients software is able to handle S/MIME. It is thus
761 usually possible to sign all outgoing messages if so desired.
762 Encryption, in contrast, makes the message text invisible for all people
764 except those who have access to the secret decryption key. To encrypt a
765 message, the specific recipients public encryption key must be known. It
766 is therefore not possible to send encrypted mail to people unless their
767 key has been retrieved from either previous communication or public key
768 directories. Because signing is performed with private keys, and encryp‐
769 tion with public keys, messages should always be signed before being en‐
770 crypted.
771 A central concept to S/MIME is that of the certification authority (CA).
773 A CA is a trusted institution that issues certificates. For each of
774 these certificates it can be verified that it really originates from the
775 CA, provided that the CA's own certificate is previously known. A set of
776 CA certificates is usually delivered and installed together with the
777 cryptographical library that is used on the local system. Therefore rea‐
778 sonable security for S/MIME on the Internet is provided if the source
779 that provides that library installation is trusted. It is also possible
780 to use a specific pool of trusted certificates. If this is desired,
781 smime-ca-no-defaults should be set to avoid using the default certificate
782 pool, and smime-ca-file and/or smime-ca-dir should be pointed to a
783 trusted pool of certificates. A certificate cannot be more secure than
784 the method its CA certificate has been retrieved with.
785 This trusted pool of certificates is used by the command verify to ensure
787 that the given S/MIME messages can be trusted. If so, verified sender
788 certificates that were embedded in signed messages can be saved locally
789 with the command certsave, and used by S-nail to encrypt further communi‐
790 cation with these senders:
791 ? certsave FILENAME
793 ? set smime-encrypt-USER@HOST=FILENAME \
794 smime-cipher-USER@HOST=AES256
795 To sign outgoing messages, in order to allow receivers to verify the ori‐
797 gin of these messages, a personal S/MIME certificate is required. S-nail
798 supports password-protected personal certificates (and keys), see
799 smime-sign-cert. The section On URL syntax and credential lookup gives
800 an overview of the possible sources of user credentials, and S/MIME step
801 by step shows examplarily how a private S/MIME certificate can be ob‐
802 tained. In general, if such a private key plus certificate “pair” is
803 available, all that needs to be done is to set some variables:
804 ? set smime-sign-cert=ME@exam.ple.paired \
806 smime-sign-digest=SHA512 \
807 smime-sign from=myname@my.host
808 Variables of interest for S/MIME in general are smime-ca-dir,
810 smime-ca-file, smime-ca-flags, smime-ca-no-defaults, smime-crl-dir,
811 smime-crl-file. For S/MIME signing of interest are smime-sign,
812 smime-sign-cert, smime-sign-include-certs and smime-sign-digest. Addi‐
813 tional variables of interest for S/MIME en- and decryption: smime-cipher
814 and smime-encrypt-USER@HOST. Variables of secondary interest may be
815 content-description-smime-message and
816 content-description-smime-signature. S/MIME is available if ‘,+smime,’
817 is included in features.
818 [v15 behaviour may differ] Note that neither S/MIME signing nor encryp‐
820 tion applies to message subjects or other header fields yet. Thus they
821 may not contain sensitive information for encrypted messages, and cannot
822 be trusted even if the message content has been verified. When sending
823 signed messages, it is recommended to repeat any important header infor‐
824 mation in the message text.
825 On URL syntax and credential lookup
827 For accessing protocol-specific resources Uniform Resource Locators (URL,
828 RFC 3986) have become omnipresent. Here they are expected in a
829 “normalized” variant, not used in data exchange, but only meant as a com‐
830 pact, easy-to-use way of defining and representing information in a well-
831 known notation; as such they do not conform to any real standard. Op‐
832 tional parts are placed in brackets ‘[]’, optional either because there
833 also exist other ways to define the information, or because the part is
834 protocol specific. ‘/path’ for example is used by the [Option]al Maildir
835 folder type and the IMAP protocol, but not by POP3. If ‘USER’ and
836 ‘PASSWORD’ are included in an URL server specification, URL percent en‐
837 coded (RFC 3986) forms are needed, generable with urlcodec.
838 PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
840 Often INTERNAL VARIABLES exist in multiple versions, called “variable
842 chains” in this document: the plain ‘variable’ as well as ‘variable-HOST’
843 and ‘variable-USER@HOST’. If a port was specified ‘HOST’ really means
844 ‘server:port’, not ‘server’. And this ‘USER’ is never in URL percent en‐
845 coded form. For example, whether the hypothetical ‘smtp://wings%3Aof
846 @a.dove’ including user and password was used, or whether it was
847 ‘smtp://a.dove’ and it came from a different source, to lookup the chain
848 tls-config-pairs first ‘tls-config-pairs-wings:of@a.dove’ is looked up,
849 then ‘tls-config-pairs-a.dove’, before finally looking up the plain vari‐
850 able.
851 The logic to collect (an accounts) credential information is as follows:
853 • A user is always required. If no ‘USER’ has been given in the URL
855 the variables user-HOST and user are looked up. Afterwards, when en‐
856 forced by the [Option]al variables netrc-lookup-HOST or netrc-lookup,
857 The .netrc file of the user will be searched for a ‘HOST’ specific
858 entry which provides a ‘login’ name: only unambiguous entries are
859 used (one possible matching entry for ‘HOST’).
860 If there is still no ‘USER’ then the verified LOGNAME, known to be a
862 valid user on the current host, is used.
863 • Authentication: unless otherwise noted the chain
865 PROTOCOL-auth-USER@HOST, PROTOCOL-auth-HOST, PROTOCOL-auth is
866 checked, falling back to a protocol-specific default as necessary.
867 • If no ‘PASSWORD’ has been given in the URL, then if the ‘USER’ has
869 been found through the [Option]al netrc-lookup, that may have also
870 provided the password. Otherwise the chain password-USER@HOST,
871 password-HOST, password is looked up.
872 Thereafter the (now complete) [Option]al chain
874 netrc-lookup-USER@HOST, netrc-lookup-HOST, netrc-lookup is checked,
875 if set the netrc cache is searched for a password only (multiple user
876 accounts for a single machine may exist as well as a fallback entry
877 without user but with a password).
878 If at that point there is still no password available, but the (pro‐
880 tocols') chosen authentication type requires a password, then in in‐
881 teractive mode the user will be prompted on the terminal.
882 Note: S/MIME verification works relative to the values found in the
884 ‘From:’ (or ‘Sender:’) header field(s), which means the values of
885 smime-sign, smime-sign-cert, smime-sign-include-certs and
886 smime-sign-digest will not be looked up using the ‘USER’ and ‘HOST’
887 chains from above, but instead use the corresponding values from the mes‐
888 sage that is being worked on. If no address matches we assume and use
889 the setting of from. In unusual cases multiple and different ‘USER’ and
890 ‘HOST’ combinations may therefore be involved – on the other hand those
891 unusual cases become possible. The usual case is as short as:
892 set mta=smtp://USER:PASS@HOST smtp-use-starttls \
894 smime-sign smime-sign-cert=+smime.pair \
895 from=myname@my.host
896 The section EXAMPLES contains complete example configurations.
898 Encrypted network communication
900 [Option] SSL (Secure Sockets Layer) aka its successor TLS (Transport
901 Layer Security) are protocols which aid in securing communication by pro‐
902 viding a safely initiated and encrypted network connection. A central
903 concept of TLS are certificates: as part of each network connection setup
904 a (set of) certificates will be exchanged through which the identity of
905 the network peer can be cryptographically verified; if possible the
906 TLS/SNI (ServerNameIndication) extension will be enabled to allow servers
907 fine-grained control over the certificates being used. A locally in‐
908 stalled pool of trusted certificates will then be inspected, and verifi‐
909 cation will succeed if it contains a(n in)direct signer of the presented
910 certificate(s).
911 The local pool of trusted so-called CA (Certification Authority) certifi‐
913 cates is usually delivered with and used along the TLS library. A custom
914 pool of trusted certificates can be selected by pointing tls-ca-file
915 and/or (with special preparation) tls-ca-dir to the desired location;
916 setting tls-ca-no-defaults in addition will avoid additional inspection
917 of the default pool. A certificate cannot be more secure than the method
918 its CA certificate has been retrieved with. For inspection or other pur‐
919 poses, the certificate of a server (as seen when connecting to it) can be
920 fetched with the command tls (port can usually be the protocol name, too,
921 and tls-verify is taken into account here):
922 $ s-nail -vX 'tls certchain SERVER-URL[:PORT]; x'
924 A local pool of CA certificates is not strictly necessary, however,
926 server certificates can also be verified via their fingerprint. For this
927 a message digest will be calculated and compared against the variable
928 chain tls-fingerprint, and verification will succeed if the fingerprint
929 matches. The message digest (algorithm) can be configured via the vari‐
930 able chain tls-fingerprint-digest; tls can again be used:
931 $ s-nail -X 'wysh set verbose; tls fingerprint SERVER-URL[:PORT]; x'
933 It depends on the used protocol whether encrypted communication is possi‐
935 ble, and which configuration steps have to be taken to enable it. Some
936 protocols, like POP3S, are implicitly encrypted, others, like POP3, can
937 upgrade a plain text connection if so requested. For example, to use the
938 ‘STLS’ that POP3 offers (a member of) the variable (chain)
939 pop3-use-starttls needs to be set, with convenience via shortcut:
940 shortcut encpop1 pop3s://pop1.exam.ple
942 shortcut encpop2 pop3://pop2.exam.ple
944 set pop3-use-starttls-pop2.exam.ple
945 set mta=smtps://smtp.exam.ple:465
947 set mta=smtp://smtp.exam.ple smtp-use-starttls
948 Normally that is all there is to do, given that TLS libraries try to pro‐
950 vide safe defaults, plenty of knobs however exist to adjust settings.
951 For example certificate verification settings can be fine-tuned via
952 tls-ca-flags, and the TLS configuration basics are accessible via
953 tls-config-pairs, for example to control protocol versions or cipher
954 lists. In the past hints on how to restrict the set of protocols to
955 highly secure ones were indicated, but as of the time of this writing the
956 list of protocols or ciphers may need to become relaxed in order to be
957 able to connect to some servers; the following example allows connecting
958 to a “Lion” that uses OpenSSL 0.9.8za from June 2014 (refer to INTERNAL
959 VARIABLES for more on variable chains):
960 wysh set tls-config-pairs-lion@exam.ple='MinProtocol=TLSv1.1,\
962 CipherString=TLSv1.2:!aNULL:!eNULL:\
963 ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:\
964 DHE-RSA-AES256-SHA:@STRENGTH'
965 The OpenSSL program ciphers(1) should be referred to when creating a cus‐
967 tom cipher list. Variables of interest for TLS in general are
968 tls-ca-dir, tls-ca-file, tls-ca-flags, tls-ca-no-defaults,
969 tls-config-file, tls-config-module, tls-config-pairs, tls-crl-dir,
970 tls-crl-file, tls-rand-file as well as tls-verify. Also see
971 tls-features. TLS is available if ‘+tls’ is included in features.
972 Character sets
974 [Option] The user's locale environment is detected by looking at the
975 LC_ALL environment variable. The internal variable ttycharset will be
976 set to the detected terminal character set accordingly, and will thus
977 show up in the output of commands like set and varshow. This character
978 set will be targeted when trying to display data, and user input data is
979 expected to be in this character set, too.
980 When creating messages their character input data is classified. 7-bit
982 clean text data and attachments will be classified as charset-7bit.
983 8-bit data will [Option]ally be converted into members of sendcharsets
984 until a character set conversion succeeds. charset-8bit is the implied
985 default last member of this list. If no 8-bit character set is capable
986 to represent input data, no message will be sent, and its text will op‐
987 tionally be saved in DEAD. If that is not acceptable, for example in
988 script environments, mime-force-sendout can be set to force sending of
989 non-convertible data as ‘application/octet-stream’ classified binary con‐
990 tent instead: like this receivers still have the option to inspect mes‐
991 sage content (for example via mime-counter-evidence). If the [Option]al
992 character set conversion is not available (features misses ‘,+iconv,’),
993 ttycharset is the only supported character set for non 7-bit clean data,
994 and it is simply assumed it can be used to exchange 8-bit messages.
995 ttycharset may also be given an explicit value to send mail in a com‐
997 pletely “faked” locale environment, which can be used to generate and
998 send for example 8-bit UTF-8 input data in a pure 7-bit US-ASCII
999 ‘LC_ALL=C’ environment (an example of this can be found in the section On
1000 sending mail, and non-interactive mode). Due to lack of programming in‐
1001 terfaces reading mail will not really work as expected in a faked envi‐
1002 ronment: whereas ttycharset might be addressable, any output will be made
1003 safely printable, as via vexpr makeprint, according to the actual locale
1004 environment, which is not affected by ttycharset.
1005 Classifying 7-bit clean data as charset-7bit is a problem if the input
1007 character set (ttycharset) is a multibyte character set that is itself
1008 7-bit clean. For example, the Japanese character set ISO-2022-JP is, but
1009 is capable to encode the rich set of Japanese Kanji, Hiragana and
1010 Katakana characters: in order to notify receivers of this character set
1011 the mail message must be MIME encoded so that the character set
1012 ISO-2022-JP can be advertised, otherwise an invalid email message would
1013 result! To achieve this, the variable charset-7bit can be set to
1014 ISO-2022-JP. (Today a better approach regarding email is the usage of
1015 UTF-8, which uses 8-bit bytes for non-US-ASCII data.)
1016 When replying to a message and the variable reply-in-same-charset is set,
1018 the character set of the message being replied to is tried first as a
1019 target character set (still being a subject of charsetalias filtering,
1020 however). Another opportunity is sendcharsets-else-ttycharset to reflect
1021 the user's locale environment automatically, it will treat ttycharset as
1022 an implied member of (an unset) sendcharsets.
1023 [Option] When reading messages, their text data is converted into
1025 ttycharset as necessary in order to display them on the user's terminal.
1026 Unprintable characters and invalid byte sequences are detected and re‐
1027 placed by substitution characters. Character set mappings for source
1028 character sets can be established with charsetalias, which may be handy
1029 to work around faulty or incomplete character set catalogues (one could
1030 for example add a missing LATIN1 to ISO-8859-1 mapping), or to enforce
1031 treatment of one character set as another one (“interpret LATIN1 as
1032 CP1252”). Also see charset-unknown-8bit to deal with another hairy as‐
1033 pect of message interpretation.
1034 In general, if a message saying “cannot convert from a to b” appears, ei‐
1036 ther some characters are not appropriate for the currently selected (ter‐
1037 minal) character set, or the needed conversion is not supported by the
1038 system. In the first case, it is necessary to set an appropriate
1039 LC_CTYPE locale and/or the variable ttycharset. The best results are
1040 usually achieved when running in a UTF-8 locale on a UTF-8 capable termi‐
1041 nal, in which case the full Unicode spectrum of characters is available.
1042 In this setup characters from various countries can be displayed, while
1043 it is still possible to use more simple character sets for sending to re‐
1044 tain maximum compatibility with older mail clients.
1045 On the other hand the POSIX standard defines a locale-independent 7-bit
1047 “portable character set” that should be used when overall portability is
1048 an issue, the even more restricted subset named “portable filename
1049 character set” consists of A-Z, a-z, 0-9, period ‘.’, underscore ‘_’ and
1050 hyphen-minus ‘-’.
1051 Message states
1053 S-nail differentiates in between several message states; the current
1054 state will be reflected in the summary of headers if the attrlist of the
1055 configured headline allows, and Specifying messages dependent on their
1056 state is possible. When operating on the system inbox, or in any other
1057 primary system mailbox, special actions, like the automatic moving of
1058 messages to the secondary mailbox MBOX, may be applied when the mailbox
1059 is left (also implicitly by program termination, unless the command exit
1060 was used) – however, because this may be irritating to users which are
1061 used to “more modern” mail-user-agents, the provided global s-nail.rc
1062 template sets the internal hold and keepsave variables in order to sup‐
1063 press this behaviour.
1064 ‘new’ Message has neither been viewed nor moved to any other state.
1066 Such messages are retained even in the primary system mailbox.
1067 ‘unread’ Message has neither been viewed nor moved to any other state,
1069 but the message was present already when the mailbox has been
1070 opened last: Such messages are retained even in the primary
1071 system mailbox.
1072 ‘read’ The message has been processed by one of the following com‐
1074 mands: ~f, ~m, ~F, ~M, copy, mbox, next, pipe, Print, print,
1075 top, Type, type, undelete. The commands dp and dt will always
1076 try to automatically “step” and type the “next” logical mes‐
1077 sage, and may thus mark multiple messages as read, the delete
1078 command will do so if the internal variable autoprint is set.
1079 Except when the exit command is used, messages that are in a
1081 primary system mailbox and are in ‘read’ state when the mailbox
1082 is left will be saved in the secondary mailbox MBOX unless the
1083 internal variable hold it set.
1084 ‘deleted’ The message has been processed by one of the following com‐
1086 mands: delete, dp, dt. Only undelete can be used to access
1087 such messages.
1088 ‘preserved’ The message has been processed by a preserve command and it
1090 will be retained in its current location.
1091 ‘saved’ The message has been processed by one of the following com‐
1093 mands: save or write. Unless when the exit command is used,
1094 messages that are in a primary system mailbox and are in
1095 ‘saved’ state when the mailbox is left will be deleted; they
1096 will be saved in the secondary mailbox MBOX when the internal
1097 variable keepsave is set.
1098 In addition to these message states, flags which otherwise have no tech‐
1100 nical meaning in the mail system except allowing special ways of address‐
1101 ing them when Specifying messages can be set on messages. These flags
1102 are saved with messages and are thus persistent, and are portable between
1103 a set of widely used MUAs.
1104 answered Mark messages as having been answered.
1106 draft Mark messages as being a draft.
1108 flag Mark messages which need special attention.
1110 Specifying messages
1112 [Only new quoting rules] COMMANDS which take Message list arguments, such
1113 as search, type, copy, and delete, can perform actions on a number of
1114 messages at once. Specifying invalid messages, or using illegal syntax,
1115 will cause errors to be reported through the INTERNAL VARIABLES !, ^ERR
1116 and companions, as well as the command exit status ?.
1117 For example, ‘delete 1 2’ deletes the messages 1 and 2, whereas ‘delete
1119 1-5’ will delete the messages 1 through 5. In sorted or threaded mode
1120 (see the sort command), ‘delete 1-5’ will delete the messages that are
1121 located between (and including) messages 1 through 5 in the
1122 sorted/threaded order, as shown in the headers summary.
1123 Errors can for example be ^ERR-BADMSG when requesting an invalid message,
1125 ^ERR-NOMSG if no applicable message can be found, ^ERR-CANCELED for miss‐
1126 ing informational data (mostly thread-related). ^ERR-INVAL for invalid
1127 syntax as well as ^ERR-IO for input/output errors can happen. The fol‐
1128 lowing special message names exist:
1129 . The current message, the so-called “dot”.
1131 ; The message that was previously the current message; needs to
1133 be quoted.
1134 , The parent message of the current message, that is the message
1136 with the Message-ID given in the ‘In-Reply-To:’ field or the
1137 last entry of the ‘References:’ field of the current message.
1138 - The previous undeleted message, or the previous deleted message
1140 for the undelete command; In sorted or ‘thread’ed mode, the
1141 previous such message in the according order.
1142 + The next undeleted message, or the next deleted message for the
1144 undelete command; In sorted or ‘thread’ed mode, the next such
1145 message in the according order.
1146 ^ The first undeleted message, or the first deleted message for
1148 the undelete command; In sorted or ‘thread’ed mode, the first
1149 such message in the according order.
1150 $ The last message; In sorted or ‘thread’ed mode, the last such
1152 message in the according order. Needs to be quoted.
1153 &x In ‘thread’ed sort mode, selects the message addressed with x,
1155 where x is any other message specification, and all messages
1156 from the thread that begins at it. Otherwise it is identical
1157 to x. If x is omitted, the thread beginning with the current
1158 message is selected.
1159 * All messages.
1161 ` All messages that were included in the Message list arguments
1163 of the previous command; needs to be quoted. (A convenient way
1164 to read all new messages is to select them via ‘from :n’, as
1165 below, and then to read them in order with the default command
1166 — next — simply by successively typing ‘`’; for this to work
1167 showlast must be set.)
1168 x-y An inclusive range of message numbers. Selectors that may also
1170 be used as endpoints include any of .;-+^$.
1171 address A case-insensitive “any substring matches” search against the
1173 ‘From:’ header, which will match addresses (too) even if
1174 showname is set (and POSIX says “any address as shown in a
1175 header summary shall be matchable in this form”); However, if
1176 the allnet variable is set, only the local part of the address
1177 is evaluated for the comparison, not ignoring case, and the
1178 setting of showname is completely ignored. For finer control
1179 and match boundaries use the ‘@’ search expression.
1180 /string All messages that contain string in the subject field (case ig‐
1182 nored according to locale). See also the searchheaders vari‐
1183 able. If string is empty, the string from the previous speci‐
1184 fication of that type is used again.
1185 [@name-list]@expr
1187 All messages that contain the given case-insensitive search
1188 expression; If the [Option]al regular expression support is
1189 available expr will be interpreted as (an extended) one if any
1190 of the magic regular expression characters is seen. If the op‐
1191 tional @name-list part is missing the search is restricted to
1192 the subject field body, but otherwise name-list specifies a
1193 comma-separated list of header fields to search, for example
1194 '@to,from,cc@Someone i ought to know'
1196 In order to search for a string that includes a ‘@’ (commercial
1198 at) character the name-list is effectively non-optional, but
1199 may be given as the empty string. Also, specifying an empty
1200 search expression will effectively test for existence of the
1201 given header fields. Some special header fields may be abbre‐
1202 viated: ‘f’, ‘t’, ‘c’, ‘b’ and ‘s’ will match ‘From’, ‘To’,
1203 ‘Cc’, ‘Bcc’ and ‘Subject’, respectively and case-insensitively.
1204 [Option]ally, and just like expr, name-list will be interpreted
1205 as (an extended) regular expression if any of the magic regular
1206 expression characters is seen.
1207 The special names ‘header’ or ‘<’ can be used to search in (all
1209 of) the header(s) of the message, and the special names ‘body’
1210 or ‘>’ and ‘text’ or ‘=’ will perform full text searches –
1211 whereas the former searches only the body, the latter also
1212 searches the message header ([v15 behaviour may differ] this
1213 mode yet brute force searches over the entire decoded content
1214 of messages, including administrativa strings).
1215 This specification performs full text comparison, but even with
1217 regular expression support it is almost impossible to write a
1218 search expression that safely matches only a specific address
1219 domain. To request that the body content of the header is
1220 treated as a list of addresses, and to strip those down to the
1221 plain email address which the search expression is to be
1222 matched against, prefix the effective name-list with a tilde
1223 ‘~’:
1224 '@~f,c@@a\.safe\.domain\.match$'
1226 :c All messages of state or with matching condition ‘c’, where ‘c’
1228 is one or multiple of the following colon modifiers:
1229 a answered messages (cf. the variable markanswered).
1231 d ‘deleted’ messages (for the undelete and from com‐
1232 mands only).
1233 f flagged messages.
1234 L Messages with receivers that match mlsubscribed ad‐
1235 dresses.
1236 l Messages with receivers that match mlisted addresses.
1237 n ‘new’ messages.
1238 o Old messages (any not in state ‘read’ or ‘new’).
1239 r ‘read’ messages.
1240 S [Option] Messages with unsure spam classification
1241 (see Handling spam).
1242 s [Option] Messages classified as spam.
1243 t Messages marked as draft.
1244 u ‘unread’ messages.
1245 [Option] IMAP-style SEARCH expressions may also be used. These consist
1247 of keywords and criterions, and because Message list arguments are split
1248 into tokens according to Shell-style argument quoting it is necessary to
1249 quote the entire IMAP search expression in order to ensure that it re‐
1250 mains a single token. This addressing mode is available with all types
1251 of mailbox folders; S-nail will perform the search locally as necessary.
1252 Strings must be enclosed by double quotation marks ‘"’ in their entirety
1253 if they contain whitespace or parentheses; within the quotes, only re‐
1254 verse solidus ‘\’ is recognized as an escape character. All string
1255 searches are case-insensitive. When the description indicates that the
1256 “envelope” representation of an address field is used, this means that
1257 the search string is checked against both a list constructed as
1258 '("name" "source" "local-part" "domain-part")'
1260 for each address, and the addresses without real names from the respec‐
1262 tive header field. These search expressions can be nested using paren‐
1263 theses, see below for examples.
1264 (criterion)
1266 All messages that satisfy the given criterion.
1267 (criterion1 criterion2 ... criterionN)
1268 All messages that satisfy all of the given criteria.
1269 (or criterion1 criterion2)
1270 All messages that satisfy either criterion1 or criterion2, or
1271 both. To connect more than two criteria using ‘or’ specifica‐
1272 tions have to be nested using additional parentheses, as with
1273 ‘(or a (or b c))’, since ‘(or a b c)’ really means ‘((a or b)
1274 and c)’. For a simple ‘or’ operation of independent criteria
1275 on the lowest nesting level, it is possible to achieve similar
1276 effects by using three separate criteria, as with ‘(a) (b)
1277 (c)’.
1278 (not criterion)
1279 All messages that do not satisfy criterion.
1280 (bcc "string")
1281 All messages that contain string in the envelope representation
1282 of the ‘Bcc:’ field.
1283 (cc "string")
1284 All messages that contain string in the envelope representation
1285 of the ‘Cc:’ field.
1286 (from "string")
1287 All messages that contain string in the envelope representation
1288 of the ‘From:’ field.
1289 (subject "string")
1290 All messages that contain string in the ‘Subject:’ field.
1291 (to "string")
1292 All messages that contain string in the envelope representation
1293 of the ‘To:’ field.
1294 (header name "string")
1295 All messages that contain string in the specified ‘Name:’
1296 field.
1297 (body "string")
1298 All messages that contain string in their body.
1299 (text "string")
1300 All messages that contain string in their header or body.
1301 (larger size)
1302 All messages that are larger than size (in bytes).
1303 (smaller size)
1304 All messages that are smaller than size (in bytes).
1305 (before date)
1306 All messages that were received before date, which must be in
1307 the form ‘d[d]-mon-yyyy’, where ‘d’ denotes the day of the
1308 month as one or two digits, ‘mon’ is the name of the month –
1309 one of ‘Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec’, and
1310 ‘yyyy’ is the year as four digits, for example ‘28-Dec-2012’.
1311 (on date)
1312 All messages that were received on the specified date.
1313 (since date)
1314 All messages that were received since the specified date.
1315 (sentbefore date)
1316 All messages that were sent on the specified date.
1317 (senton date)
1318 All messages that were sent on the specified date.
1319 (sentsince date)
1320 All messages that were sent since the specified date.
1321 () The same criterion as for the previous search. This specifica‐
1322 tion cannot be used as part of another criterion. If the pre‐
1323 vious command line contained more than one independent crite‐
1324 rion then the last of those criteria is used.
1325 On terminal control and line editor
1327 [Option] Terminal control through one of the standard UNIX libraries,
1328 Termcap Access Library (libtermcap, -ltermcap) or Terminal Information
1329 Library (libterminfo, -lterminfo), may be available. For the TERMinal
1330 defined in the environment interactive usage aspects, for example
1331 Coloured display, and insight of cursor and function keys for the Mailx-
1332 Line-Editor (MLE), will be enhanced or enabled. Library interaction can
1333 be disabled on a per-invocation basis via termcap-disable, whereas the
1334 internal variable termcap is always used as a preferred source of termi‐
1335 nal capabilities. (For a usage example see the FAQ entry Not
1336 "defunctional", but the editor key does not work.)
1337 [Option] The built-in Mailx-Line-Editor (MLE) should work in all environ‐
1339 ments which comply to the ISO C standard ISO/IEC 9899/AMD1:1995
1340 (“ISO C90, Amendment 1”), and will support wide glyphs if possible (the
1341 necessary functionality had been removed from ISO C, but was included in
1342 X/Open Portability Guide Issue 4 (“XPG4”)). Usage of a line editor in
1343 interactive mode can be prevented by setting line-editor-disable. Espe‐
1344 cially if the [Option]al terminal control support is missing setting en‐
1345 tries in termcap will help shall the MLE misbehave, see there for more.
1346 The MLE can support a little bit of colour.
1347 [Option] If the history feature is available then input from line editor
1349 prompts will be saved in a history list that can be searched in and be
1350 expanded from. Such saving can be prevented by prefixing input with any
1351 amount of whitespace. Aspects of history, like allowed content and maxi‐
1352 mum size, as well as whether history shall be saved persistently, can be
1353 configured with the internal variables history-file, history-gabby,
1354 history-gabby-persist and history-size. There also exists the macro hook
1355 on-history-addition which can be used to apply finer control on what en‐
1356 ters history.
1357 The MLE supports a set of editing and control commands. By default (as)
1359 many (as possible) of these will be assigned to a set of single-letter
1360 control codes, which should work on any terminal (and can be generated by
1361 holding the “control” key while pressing the key of desire, for example
1362 ‘control-D’). If the [Option]al bind command is available then the MLE
1363 commands can also be accessed freely by assigning the command name, which
1364 is shown in parenthesis in the list below, to any desired key-sequence,
1365 and the MLE will instead and also use bind to establish its built-in key
1366 bindings (more of them if the [Option]al terminal control is available),
1367 an action which can then be suppressed completely by setting
1368 line-editor-no-defaults. Shell-style argument quoting notation is used
1369 in the following:
1370 ‘\cA’ Go to the start of the line (mle-go-home).
1372 ‘\cB’ Move the cursor backward one character (mle-go-bwd).
1373 ‘\cC’ raise(3) ‘SIGINT’ (mle-raise-int).
1374 ‘\cD’ Forward delete the character under the cursor; quits S-nail if
1375 used on the empty line unless the internal variable ignoreeof
1376 is set (mle-del-fwd).
1377 ‘\cE’ Go to the end of the line (mle-go-end).
1378 ‘\cF’ Move the cursor forward one character (mle-go-fwd).
1379 ‘\cG’ Cancel current operation, full reset. If there is an active
1380 history search or tabulator expansion then this command will
1381 first reset that, reverting to the former line content; thus a
1382 second reset is needed for a full reset in this case
1383 (mle-reset).
1384 ‘\cH’ Backspace: backward delete one character (mle-del-bwd).
1385 ‘\cI’ [Only new quoting rules] Horizontal tabulator: try to expand
1386 the word before the cursor, supporting the usual Filename
1387 transformations (mle-complete; this is affected by
1388 mle-quote-rndtrip and line-editor-cpl-word-breaks).
1389 ‘\cJ’ Newline: commit the current line (mle-commit).
1390 ‘\cK’ Cut all characters from the cursor to the end of the line
1391 (mle-snarf-end).
1392 ‘\cL’ Repaint the line (mle-repaint).
1393 ‘\cN’ [Option] Go to the next history entry (mle-hist-fwd).
1394 ‘\cO’ ([Option]ally context-dependent) Invokes the command dt.
1395 ‘\cP’ [Option] Go to the previous history entry (mle-hist-bwd).
1396 ‘\cQ’ Toggle roundtrip mode shell quotes, where produced, on and off
1397 (mle-quote-rndtrip). This setting is temporary, and will be
1398 forgotten once the command line is committed; also see shcodec.
1399 ‘\cR’ [Option] Complete the current line from (the remaining) older
1400 history entries (mle-hist-srch-bwd).
1401 ‘\cS’ [Option] Complete the current line from (the remaining) newer
1402 history entries (mle-hist-srch-fwd).
1403 ‘\cT’ Paste the snarf buffer (mle-paste).
1404 ‘\cU’ The same as ‘\cA’ followed by ‘\cK’ (mle-snarf-line).
1405 ‘\cV’ Prompts for a Unicode character (hexadecimal number without
1406 prefix, see vexpr) to be inserted (mle-prompt-char). Note this
1407 command needs to be assigned to a single-letter control code in
1408 order to become recognized and executed during input of a key-
1409 sequence (only three single-letter control codes can be used
1410 for that shortcut purpose); this control code is then special-
1411 treated and thus cannot be part of any other sequence (because
1412 it will trigger the mle-prompt-char function immediately).
1413 ‘\cW’ Cut the characters from the one preceding the cursor to the
1414 preceding word boundary (mle-snarf-word-bwd).
1415 ‘\cX’ Move the cursor forward one word boundary (mle-go-word-fwd).
1416 ‘\cY’ Move the cursor backward one word boundary (mle-go-word-bwd).
1417 ‘\cZ’ raise(3) ‘SIGTSTP’ (mle-raise-tstp).
1418 ‘\c[’ Escape: reset a possibly used multibyte character input state
1419 machine and [Option]ally a lingering, incomplete key binding
1420 (mle-cancel). This command needs to be assigned to a single-
1421 letter control code in order to become recognized and executed
1422 during input of a key-sequence (only three single-letter con‐
1423 trol codes can be used for that shortcut purpose). This con‐
1424 trol code may also be part of a multi-byte sequence, but if a
1425 sequence is active and the very control code is currently also
1426 an expected input, then the active sequence takes precedence
1427 and will consume the control code.
1428 ‘\c\’ ([Option]ally context-dependent) Invokes the command ‘z+’.
1429 ‘\c]’ ([Option]ally context-dependent) Invokes the command ‘z$’.
1430 ‘\c^’ ([Option]ally context-dependent) Invokes the command ‘z0’.
1431 ‘\c_’ Cut the characters from the one after the cursor to the suc‐
1432 ceeding word boundary (mle-snarf-word-fwd).
1433 ‘\c?’ Backspace: mle-del-bwd.
1434 – mle-bell: ring the audible bell.
1435 – [Option] mle-clear-screen: move the cursor home and clear the
1436 screen.
1437 – mle-fullreset: different to mle-reset this will immediately re‐
1438 set a possibly active search etc.
1439 – mle-go-screen-bwd: move the cursor backward one screen width.
1440 – mle-go-screen-fwd: move the cursor forward one screen width.
1441 – mle-raise-quit: [22mraise(3) ‘SIGQUIT’.
1442 Coloured display
1444 [Option] Colours and font attributes through ANSI a.k.a. ISO 6429 SGR
1445 (select graphic rendition) escape sequences are optionally supported.
1446 Usage of colours and font attributes solely depends upon the capability
1447 of the detected terminal type (TERM), and as fine-tuned through termcap.
1448 Colours and font attributes can be managed with the multiplexer command
1449 colour, and uncolour removes the given mappings. Setting colour-disable
1450 suppresses usage of colour and font attribute sequences, while leaving
1451 established mappings unchanged.
1452 Whether actually applicable colour and font attribute sequences should
1454 also be generated when output is going to be paged through the external
1455 PAGER (also see crt) depends upon the setting of colour-pager, because
1456 pagers usually need to be configured in order to support ISO escape se‐
1457 quences. Knowledge of some widely used pagers is however built-in, and
1458 in a clean environment it is often enough to simply set colour-pager;
1459 please refer to that variable for more on this topic.
1460 It might make sense to conditionalize colour setup on interactive mode
1462 via if (‘terminal’ indeed means “interactive”):
1463 if terminal && "$features" =% ,+colour,
1465 colour iso view-msginfo ft=bold,fg=green
1466 colour iso view-header ft=bold,fg=red (from|subject) # regex
1467 colour iso view-header fg=red
1468 uncolour iso view-header from,subject
1470 colour iso view-header ft=bold,fg=magenta,bg=cyan
1471 colour 256 view-header ft=bold,fg=208,bg=230 "subject,from"
1472 colour mono view-header ft=bold
1473 colour mono view-header ft=bold,ft=reverse subject,from
1474 endif
1475 Handling spam
1477 [Option] S-nail can make use of several spam interfaces for the purpose
1478 of identification of, and, in general, dealing with spam messages. A
1479 precondition of most commands in order to function is that the
1480 spam-interface variable is set to one of the supported interfaces.
1481 Specifying messages that have been identified as spam is possible via
1482 their (volatile) ‘is-spam’ state by using the ‘:s’ and ‘:S’ specifica‐
1483 tions, and their attrlist entries will be used when displaying the
1484 headline in the summary of headers.
1485 • spamrate rates the given messages and sets their ‘is-spam’ flag ac‐
1487 cordingly. If the spam interface offers spam scores these can be
1488 shown in headline by using the format ‘%$’.
1489 • spamham, spamspam and spamforget will interact with the Bayesian fil‐
1491 ter of the chosen interface and learn the given messages as “ham” or
1492 “spam”, respectively; the last command can be used to cause
1493 “unlearning” of messages; it adheres to their current ‘is-spam’ state
1494 and thus reverts previous teachings.
1495 • spamclear and spamset will simply set and clear, respectively, the
1497 mentioned volatile ‘is-spam’ message flag, without any interface in‐
1498 teraction.
1499 The spamassassin(1) based spam-interface ‘spamc’ requires a running in‐
1501 stance of the spamd(1) server in order to function, started with the op‐
1502 tion --allow-tell shall Bayesian filter learning be possible.
1503 $ spamd -i localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
1505 $ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \
1506 --daemonize [--local] [--allow-tell]
1507 Thereafter S-nail can make use of these interfaces:
1509 $ s-nail -Sspam-interface=spamc -Sspam-maxsize=500000 \
1511 -Sspamc-command=/usr/local/bin/spamc \
1512 -Sspamc-arguments="-U /tmp/.spamsock" -Sspamc-user=
1513 or
1514 $ s-nail -Sspam-interface=spamc -Sspam-maxsize=500000 \
1515 -Sspamc-command=/usr/local/bin/spamc \
1516 -Sspamc-arguments="-d localhost -p 2142" -Sspamc-user=
1517 Using the generic filter approach allows usage of programs like
1519 bogofilter(1). Here is an example, requiring it to be accessible via
1520 PATH:
1521 $ s-nail -Sspam-interface=filter -Sspam-maxsize=500000 \
1523 -Sspamfilter-ham="bogofilter -n" \
1524 -Sspamfilter-noham="bogofilter -N" \
1525 -Sspamfilter-nospam="bogofilter -S" \
1526 -Sspamfilter-rate="bogofilter -TTu 2>/dev/null" \
1527 -Sspamfilter-spam="bogofilter -s" \
1528 -Sspamfilter-rate-scanscore="1;^(.+)$"
1529 Because messages must exist on local storage in order to be scored (or
1531 used for Bayesian filter training), it is possibly a good idea to perform
1532 the local spam check last. Spam can be checked automatically when open‐
1533 ing specific folders by setting a specialized form of the internal vari‐
1534 able folder-hook.
1535 define spamdelhook {
1537 # Server side DCC
1538 spamset (header x-dcc-brand-metrics "bulk")
1539 # Server-side spamassassin(1)
1540 spamset (header x-spam-flag "YES")
1541 del :s # TODO we HAVE to be able to do `spamrate :u ! :sS'
1542 move :S +maybe-spam
1543 spamrate :u
1544 del :s
1545 move :S +maybe-spam
1546 }
1547 set folder-hook-SOMEFOLDER=spamdelhook
1548 See also the documentation for the variables spam-interface,
1550 spam-maxsize, spamc-command, spamc-arguments, spamc-user, spamfilter-ham,
1551 spamfilter-noham, spamfilter-nospam, spamfilter-rate and
1552 spamfilter-rate-scanscore.
1553
1555 S-nail reads input in lines. An unquoted reverse solidus ‘\’ at the end
1556 of a command line “escapes” the newline character: it is discarded and
1557 the next line of input is used as a follow-up line, with all leading
1558 whitespace removed; once an entire line is completed, the whitespace
1559 characters space, tabulator, newline as well as those defined by the
1560 variable ifs are removed from the beginning and end. Placing any white‐
1561 space characters at the beginning of a line will prevent a possible addi‐
1562 tion of the command line to the [Option]al history.
1563 The beginning of such input lines is then scanned for the name of a known
1565 command: command names may be abbreviated, in which case the first com‐
1566 mand that matches the given prefix will be used. Command modifiers may
1567 prefix a command in order to modify its behaviour. A name may also be a
1568 commandalias, which will become expanded until no more expansion is pos‐
1569 sible. Once the command that shall be executed is known, the remains of
1570 the input line will be interpreted according to command-specific rules,
1571 documented in the following.
1572 This behaviour is different to the sh(1)ell, which is a programming lan‐
1574 guage with syntactic elements of clearly defined semantics, and therefore
1575 capable to sequentially expand and evaluate individual elements of a
1576 line. ‘? set one=value two=$one’ for example will never possibly assign
1577 value to one, because the variable assignment is performed no sooner but
1578 by the command (set), long after the expansion happened.
1579 A list of all commands in lookup order is dumped by the command list.
1581 [Option]ally the command help (or ?), when given an argument, will show a
1582 documentation string for the command matching the expanded argument, as
1583 in ‘?t’, which should be a shorthand of ‘?type’; with these documentation
1584 strings both commands support a more verbose listing mode which includes
1585 the argument type of the command and other information which applies; a
1586 handy suggestion might thus be:
1587 ? define __xv {
1589 # Before v15: need to enable sh(1)ell-style on _entire_ line!
1590 localopts yes;wysh set verbose;ignerr eval "${@}";return ${?}
1591 }
1592 ? commandalias xv '\call __xv'
1593 ? xv help set
1594 Command modifiers
1596 Commands may be prefixed by none to multiple command modifiers. Some
1597 command modifiers can be used with a restricted set of commands only, the
1598 verbose version of list will ([Option]ally) show which modifiers apply.
1599 • The modifier reverse solidus \, to be placed first, prevents
1601 commandalias expansions on the remains of the line, for example
1602 ‘\echo’ will always evaluate the command echo, even if an (com‐
1603 mand)alias of the same name exists. commandalias content may itself
1604 contain further command modifiers, including an initial reverse
1605 solidus to prevent further expansions.
1606 • The modifier ignerr indicates that any error generated by the follow‐
1608 ing command should be ignored by the state machine and not cause a
1609 program exit with enabled errexit or for the standardized exit cases
1610 in posix mode. ?, one of the INTERNAL VARIABLES, will be set to the
1611 real exit status of the command regardless.
1612 • local will alter the called command to apply changes only temporar‐
1614 ily, local to block-scope, and can thus only be used inside of a
1615 defined macro or an account definition. Specifying it implies the
1616 modifier wysh. Local variables will not be inherited by macros
1617 deeper in the call chain, and all local settings will be garbage col‐
1618 lected once the local scope is left. To record and unroll changes in
1619 the global scope use the command localopts.
1620 • scope does yet not implement any functionality.
1622 • u does yet not implement any functionality.
1624 • Some commands support the vput modifier: if used, they expect the
1626 name of a variable, which can itself be a variable, i.e., shell ex‐
1627 pansion is applied, as their first argument, and will place their
1628 computation result in it instead of the default location (it is usu‐
1629 ally written to standard output).
1630 The given name will be tested for being a valid sh(1) variable name,
1632 and may therefore only consist of upper- and lowercase characters,
1633 digits, and the underscore; the hyphen-minus may be used as a non-
1634 portable extension; digits may not be used as first, hyphen-minus may
1635 not be used as last characters. In addition the name may either not
1636 be one of the known INTERNAL VARIABLES, or must otherwise refer to a
1637 writable (non-boolean) value variable. The actual put operation may
1638 fail nonetheless, for example if the variable expects a number argu‐
1639 ment only a number will be accepted. Any error during these opera‐
1640 tions causes the command as such to fail, and the error number ! will
1641 be set to ^ERR-NOTSUP, the exit status ? should be set to ‘-1’, but
1642 some commands deviate from the latter, which is documented.
1643 • Last, but not least, the modifier wysh can be used for some old and
1645 established commands to choose the new Shell-style argument quoting
1646 rules over the traditional Old-style argument quoting. This modifier
1647 is implied if v15-compat is set to a non-empty value.
1648 Old-style argument quoting
1650 [v15 behaviour may differ] This section documents the traditional and
1651 POSIX standardized style of quoting non-message list arguments to com‐
1652 mands which expect this type of arguments: whereas still used by the ma‐
1653 jority of such commands, the new Shell-style argument quoting may be
1654 available even for those via wysh, one of the Command modifiers. None‐
1655 theless care must be taken, because only new commands have been designed
1656 with all the capabilities of the new quoting rules in mind, which can,
1657 for example generate control characters.
1658 • An argument can be enclosed between paired double-quotes
1660 ‘"argument"’ or single-quotes ‘'argument'’; any whitespace,
1661 shell word expansion, or reverse solidus characters (except as
1662 described next) within the quotes are treated literally as part
1663 of the argument. A double-quote will be treated literally
1664 within single-quotes and vice versa. Inside such a quoted
1665 string the actually used quote character can be used nonethe‐
1666 less by escaping it with a reverse solidus ‘\’, as in
1667 ‘"y\"ou"’.
1668 • An argument that is not enclosed in quotes, as above, can usu‐
1670 ally still contain space characters if those spaces are reverse
1671 solidus escaped, as in ‘you\ are’.
1672 • A reverse solidus outside of the enclosing quotes is discarded
1674 and the following character is treated literally as part of the
1675 argument.
1676 Shell-style argument quoting
1678 sh(1)ell-style, and therefore POSIX standardized, argument parsing and
1679 quoting rules are used by most commands. [v15 behaviour may differ] Most
1680 new commands only support these new rules and are flagged [Only new quot‐
1681 ing rules], some elder ones can use them with the command modifier wysh;
1682 in the future only this type of argument quoting will remain.
1683 A command line is parsed from left to right and an input token is com‐
1685 pleted whenever an unquoted, otherwise ignored, metacharacter is seen.
1686 Metacharacters are vertical bar |, ampersand &, semicolon ;, as well as
1687 all characters from the variable ifs, and / or space, tabulator, newline.
1688 The additional metacharacters left and right parenthesis (, ) and less-
1689 than and greater-than signs <, > that the sh(1) supports are not used,
1690 and are treated as ordinary characters: for one these characters are a
1691 vivid part of email addresses, and it seems highly unlikely that their
1692 function will become meaningful to S-nail.
1693 Compatibility note: [v15 behaviour may differ] Please note that
1695 even many new-style commands do not yet honour ifs to parse their
1696 arguments: whereas the sh(1)ell is a language with syntactic ele‐
1697 ments of clearly defined semantics, S-nail parses entire input
1698 lines and decides on a per-command base what to do with the rest of
1699 the line. This also means that whenever an unknown command is seen
1700 all that S-nail can do is cancellation of the processing of the re‐
1701 mains of the line.
1702 It also often depends on an actual subcommand of a multiplexer com‐
1704 mand how the rest of the line should be treated, and until v15 we
1705 are not capable to perform this deep inspection of arguments.
1706 Nonetheless, at least the following commands which work with posi‐
1707 tional parameters fully support ifs for an almost shell-compatible
1708 field splitting: call, call_if, read, vpospar, xcall.
1709 Any unquoted number sign ‘#’ at the beginning of a new token starts a
1711 comment that extends to the end of the line, and therefore ends argument
1712 processing. An unquoted dollar sign ‘$’ will cause variable expansion of
1713 the given name, which must be a valid sh(1)ell-style variable name (see
1714 vput): INTERNAL VARIABLES as well as ENVIRONMENT (shell) variables can be
1715 accessed through this mechanism, brace enclosing the name is supported
1716 (i.e., to subdivide a token).
1717 Whereas the metacharacters space, tabulator, newline only complete an in‐
1719 put token, vertical bar |, ampersand & and semicolon ; also act as con‐
1720 trol operators and perform control functions. For now supported is semi‐
1721 colon ;, which terminates a single command, therefore sequencing the com‐
1722 mand line and making the remainder of the line a subject to reevaluation.
1723 With sequencing, multiple command argument types and quoting rules may
1724 therefore apply to a single line, which can become problematic before
1725 v15: e.g., the first of the following will cause surprising results.
1726 ? echo one; set verbose; echo verbose=$verbose.
1728 ? echo one; wysh set verbose; echo verbose=$verbose.
1729 Quoting is a mechanism that will remove the special meaning of metachar‐
1731 acters and reserved words, and will prevent expansion. There are four
1732 quoting mechanisms: the escape character, single-quotes, double-quotes
1733 and dollar-single-quotes:
1734 • The literal value of any character can be preserved by preced‐
1736 ing it with the escape character reverse solidus ‘\’.
1737 • Arguments which are enclosed in ‘'single-quotes'’ retain their
1739 literal value. A single-quote cannot occur within single-
1740 quotes.
1741 • The literal value of all characters enclosed in ‘"double-
1743 quotes"’ is retained, with the exception of dollar sign ‘$’,
1744 which will cause variable expansion, as above, backquote (grave
1745 accent) ‘`’, (which not yet means anything special), reverse
1746 solidus ‘\’, which will escape any of the characters dollar
1747 sign ‘$’ (to prevent variable expansion), backquote (grave ac‐
1748 cent) ‘`’, double-quote ‘"’ (to prevent ending the quote) and
1749 reverse solidus ‘\’ (to prevent escaping, i.e., to embed a re‐
1750 verse solidus character as-is), but has no special meaning oth‐
1751 erwise.
1752 • Arguments enclosed in ‘$'dollar-single-quotes'’ extend normal
1754 single quotes in that reverse solidus escape sequences are ex‐
1755 panded as follows:
1756 ‘\a’ bell control character (ASCII and ISO-10646 BEL).
1758 ‘\b’ backspace control character (ASCII and ISO-10646 BS).
1759 ‘\E’ escape control character (ASCII and ISO-10646 ESC).
1760 ‘\e’ the same.
1761 ‘\f’ form feed control character (ASCII and ISO-10646 FF).
1762 ‘\n’ line feed control character (ASCII and ISO-10646 LF).
1763 ‘\r’ carriage return control character (ASCII and ISO-10646
1764 CR).
1765 ‘\t’ horizontal tabulator control character (ASCII and
1766 ISO-10646 HT).
1767 ‘\v’ vertical tabulator control character (ASCII and
1768 ISO-10646 VT).
1769 ‘\\’ emits a reverse solidus character.
1770 ‘\'’ single quote.
1771 ‘\"’ double quote (escaping is optional).
1772 ‘\NNN’ eight-bit byte with the octal value ‘NNN’ (one to three
1773 octal digits), optionally prefixed by an additional
1774 ‘0’. A 0 byte will suppress further output for the
1775 quoted argument.
1776 ‘\xHH’ eight-bit byte with the hexadecimal value ‘HH’ (one or
1777 two hexadecimal characters, no prefix, see vexpr). A 0
1778 byte will suppress further output for the quoted argu‐
1779 ment.
1780 ‘\UHHHHHHHH’
1781 the Unicode / ISO-10646 character with the hexadecimal
1782 codepoint value ‘HHHHHHHH’ (one to eight hexadecimal
1783 characters) — note that Unicode defines the maximum
1784 codepoint ever to be supported as ‘0x10FFFF’ (in planes
1785 of ‘0xFFFF’ characters each). This escape is only sup‐
1786 ported in locales that support Unicode (see Character
1787 sets), in other cases the sequence will remain unex‐
1788 panded unless the given code point is ASCII compatible
1789 or (if the [Option]al character set conversion is
1790 available) can be represented in the current locale.
1791 The character NUL will suppress further output for the
1792 quoted argument.
1793 ‘\uHHHH’
1794 Identical to ‘\UHHHHHHHH’ except it takes only one to
1795 four hexadecimal characters.
1796 ‘\cX’ Emits the non-printable (ASCII and compatible) C0 con‐
1797 trol codes 0 (NUL) to 31 (US), and 127 (DEL). Print‐
1798 able representations of ASCII control codes can be cre‐
1799 ated by mapping them to a different, visible part of
1800 the ASCII character set. Adding the number 64 achieves
1801 this for the codes 0 to 31, here 7 (BEL): ‘7 + 64 = 71
1802 = G’. The real operation is a bitwise logical XOR with
1803 64 (bit 7 set, see vexpr), thus also covering code 127
1804 (DEL), which is mapped to 63 (question mark):
1805 ‘? vexpr ^ 127 64’.
1806 Whereas historically circumflex notation has often been
1808 used for visualization purposes of control codes, as in
1809 ‘^G’, the reverse solidus notation has been standard‐
1810 ized: ‘\cG’. Some control codes also have standardized
1811 (ISO-10646, ISO C) aliases, as shown above (‘\a’, ‘\n’,
1812 ‘\t’ etc) : whenever such an alias exists it will be
1813 used for display purposes. The control code NUL
1814 (‘\c@’, a non-standard extension) will suppress further
1815 output for the remains of the token (which may extend
1816 beyond the current quote), or, depending on the con‐
1817 text, the remains of all arguments for the current com‐
1818 mand.
1819 ‘\$NAME’
1820 Non-standard extension: expand the given variable name,
1821 as above. Brace enclosing the name is supported.
1822 ‘\`{command}’
1823 Not yet supported, just to raise awareness: Non-stan‐
1824 dard extension.
1825 Caveats:
1827 ? echo 'Quotes '${HOME}' and 'tokens" differ!"# no comment
1829 ? echo Quotes ${HOME} and tokens differ! # comment
1830 ? echo Don"'"t you worry$'\x21' The sun shines on us. $'\u263A'
1831 Message list arguments
1833 Many commands operate on message list specifications, as documented in
1834 Specifying messages. The argument input is first split into individual
1835 tokens via Shell-style argument quoting, which are then interpreted as
1836 the mentioned specifications. If no explicit message list has been spec‐
1837 ified, many commands will search for and use the next message forward
1838 that satisfies the commands' requirements, and if there are no messages
1839 forward of the current message, the search proceeds backwards; if there
1840 are no good messages at all to be found, an error message is shown and
1841 the command is aborted. The verbose output of the command list will in‐
1842 dicate whether a command searches for a default message, or not.
1843 Raw data arguments for codec commands
1845 A special set of commands, which all have the string “codec” in their
1846 name, like addrcodec, shcodec, urlcodec, take raw string data as input,
1847 which means that the content of the command input line is passed com‐
1848 pletely unexpanded and otherwise unchanged: like this the effect of the
1849 actual codec is visible without any noise of possible shell quoting rules
1850 etc., i.e., the user can input one-to-one the desired or questionable
1851 data. To gain a level of expansion, the entire command line can be
1852 evaluated first, for example
1853 ? vput shcodec res encode /usr/Schönes Wetter/heute.txt
1855 ? echo $res
1856 $'/usr/Sch\u00F6nes Wetter/heute.txt'
1857 ? shcodec d $res
1858 $'/usr/Sch\u00F6nes Wetter/heute.txt'
1859 ? eval shcodec d $res
1860 /usr/Schönes Wetter/heute.txt
1861 Filename transformations
1863 Filenames, where expected, and unless documented otherwise, are subse‐
1864 quently subject to the following filename transformations, in sequence:
1865 • If the given name is a registered shortcut, it will be replaced
1867 with the expanded shortcut. This step is mostly taken for
1868 folders only.
1869 • The filename is matched against the following patterns or
1871 strings. But for plus +file folder expansion this step is
1872 mostly taken for folders only.
1873 # (Number sign) is expanded to the previous file.
1875 % (Percent sign) is replaced by the invoking user's pri‐
1876 mary system mailbox, which either is the (itself expand‐
1877 able) inbox if that is set, the standardized absolute
1878 pathname indicated by MAIL if that is set, or a built-in
1879 compile-time default otherwise. When opening a folder
1880 the used name is actively checked for being a primary
1881 mailbox, first against inbox, then against MAIL.
1882 %user Expands to the primary system mailbox of user (and never
1883 the value of inbox, regardless of its actual setting).
1884 & (Ampersand) is replaced with the invoking user's sec‐
1885 ondary mailbox, the MBOX.
1886 +file Refers to a file in the folder directory (if that vari‐
1887 able is set).
1888 %:filespec Expands to the same value as filespec, but has spe‐
1889 cial meaning when used with, for example, the command
1890 folder: the file will be treated as a primary system
1891 mailbox by, among others, the mbox and save commands,
1892 meaning that messages that have been read in the current
1893 session will be moved to the MBOX mailbox instead of
1894 simply being flagged as read.
1895 • Meta expansions may be applied to the resulting filename, as
1897 allowed by the operation and applicable to the resulting access
1898 protocol (also see On URL syntax and credential lookup). For
1899 the file-protocol, a leading tilde ‘~’ character will be re‐
1900 placed by the expansion of HOME, except when followed by a
1901 valid user name, in which case the home directory of the given
1902 user is used instead.
1903 A shell expansion as if specified in double-quotes (see
1905 Shell-style argument quoting) may be applied, so that any oc‐
1906 currence of ‘$VARIABLE’ (or ‘${VARIABLE}’) will be replaced by
1907 the expansion of the variable, if possible; INTERNAL VARIABLES
1908 as well as ENVIRONMENT (shell) variables can be accessed
1909 through this mechanism.
1910 Shell pathname wildcard pattern expansions (glob(7)) may be ap‐
1912 plied as documented. If the fully expanded filename results in
1913 multiple pathnames and the command is expecting only one file,
1914 an error results.
1915 In interactive context, in order to allow simple value accep‐
1917 tance (via “ENTER”), arguments will usually be displayed in a
1918 properly quoted form, so a file ‘diet\ is \curd.txt’ may be
1919 displayed as ‘'diet\ is \curd.txt'’.
1920 Commands
1922 The following commands are available:
1923 ! Executes the SHELL command which follows, replacing unescaped
1925 exclamation marks with the previously executed command if the
1926 internal variable bang is set. This command supports vput as
1927 documented in Command modifiers, and manages the error number
1928 !. A 0 or positive exit status ? reflects the exit status of
1929 the command, negative ones that an error happened before the
1930 command was executed, or that the program did not exit cleanly,
1931 but maybe due to a signal: the error number is ^ERR-CHILD,
1932 then.
1933 In conjunction with the vput modifier the following special
1935 cases exist: a negative exit status occurs if the collected
1936 data could not be stored in the given variable, which is a
1937 ^ERR-NOTSUP error that should otherwise not occur.
1938 ^ERR-CANCELED indicates that no temporary file could be created
1939 to collect the command output at first glance. In case of
1940 catchable out-of-memory situations ^ERR-NOMEM will occur and
1941 S-nail will try to store the empty string, just like with all
1942 other detected error conditions.
1943 # The comment-command causes the entire line to be ignored.
1945 Note: this really is a normal command which' purpose is to dis‐
1946 card its arguments, not a “comment-start” indicating special
1947 character, which means that for example trailing comments on a
1948 line are not possible (except for commands which use
1949 Shell-style argument quoting).
1950 + Goes to the next message in sequence and types it (like
1952 “ENTER”).
1953 - Display the preceding message, or the n'th previous message if
1955 given a numeric argument n.
1956 = Shows the message number of the current message (the “dot”)
1958 when used without arguments, that of the given list otherwise.
1959 Output numbers will be separated from each other with the first
1960 character of ifs, and followed by the first character of if-ws,
1961 if that is not empty and not identical to the first. If that
1962 results in no separation at all a space character is used.
1963 This command supports vput (see Command modifiers), and manages
1964 the error number !.
1965 ? [Option] Show a brief summary of commands. [Option] Given an
1967 argument a synopsis for the command in question is shown in‐
1968 stead; commands can be abbreviated in general and this command
1969 can be used to see the full expansion of an abbreviation in‐
1970 cluding the synopsis, try, for example ‘?h’, ‘?hel’ and ‘?help’
1971 and see how the output changes. To avoid that aliases are re‐
1972 solved the modifier \ can be prepended to the argument, but
1973 note it must be quoted. This mode also supports a more verbose
1974 output, which will provide the information documented for list.
1975 | A synonym for the pipe command.
1977 account, unaccount
1979 (ac, una) Creates, selects or lists (an) account(s). Accounts
1980 are special incarnations of defined macros and group commands
1981 and variable settings which together usually arrange the envi‐
1982 ronment for the purpose of creating an email account. Differ‐
1983 ent to normal macros settings which are covered by localopts –
1984 here by default enabled! – will not be reverted before the
1985 account is changed again. The special account ‘null’ (case-in‐
1986 sensitive) always exists, and all but it can be deleted by the
1987 latter command, and in one operation with the special name ‘*’.
1988 Also for all but it a possibly set on-account-cleanup hook is
1989 called once they are left, also for program exit.
1990 Without arguments a listing of all defined accounts is shown.
1992 With one argument the given account is activated: the system
1993 inbox of that account will be activated (as via folder), a pos‐
1994 sibly installed folder-hook will be run, and the internal vari‐
1995 able account will be updated. The two argument form behaves
1996 identical to defining a macro as via define. Important set‐
1997 tings for accounts include folder, from, hostname, inbox, mta,
1998 password and user (On URL syntax and credential lookup), as
1999 well as things like tls-config-pairs (Encrypted network
2000 communication), and protocol specifics like imap-auth,
2001 pop3-auth, smtp-auth.
2002 account myisp {
2004 set folder=~/mail inbox=+syste.mbox record=+sent.mbox
2005 set from='(My Name) myname@myisp.example'
2006 set mta=smtp://mylogin@smtp.myisp.example
2007 }
2008 addrcodec
2010 Perform email address codec transformations on raw-data argu‐
2011 ment, rather according to email standards (RFC 5322; [v15 be‐
2012 haviour may differ] will furtherly improve). Supports vput
2013 (see Command modifiers), and manages the error number !. The
2014 first argument must be either [+[+[+]]]e[ncode], d[ecode],
2015 s[kin] or skinl[ist] and specifies the operation to perform on
2016 the rest of the line.
2017 Decoding will show how a standard-compliant MUA will display
2019 the given argument, which should be an email address. Please
2020 be aware that most MUAs have difficulties with the address
2021 standards, and vary wildly when (comments) in parenthesis,
2022 “double-quoted” strings, or quoted-pairs, as below, become in‐
2023 volved. [v15 behaviour may differ] S-nail currently does not
2024 perform decoding when displaying addresses.
2025 Skinning is identical to decoding but only outputs the plain
2027 address, without any string, comment etc. components. Another
2028 difference is that it may fail with the error number ! set to
2029 ^ERR-INVAL if decoding fails to find a(n) (valid) email ad‐
2030 dress, in which case the unmodified input will be output again.
2031 skinlist first performs a skin operation, and thereafter checks
2033 a valid address for whether it is a registered mailing list
2034 (see mlist and mlsubscribe), eventually reporting that state in
2035 the error number ! as ^ERR-EXIST. (This state could later be‐
2036 come overwritten by an I/O error, though.)
2037 Encoding supports four different modes, lesser automated ver‐
2039 sions can be chosen by prefixing one, two or three plus signs:
2040 the standard imposes a special meaning on some characters,
2041 which thus have to be transformed to so-called quoted-pairs by
2042 pairing them with a reverse solidus ‘\’ in order to remove the
2043 special meaning; this might change interpretation of the entire
2044 argument from what has been desired, however! Specify one plus
2045 sign to remark that parenthesis shall be left alone, two for
2046 not turning double quotation marks into quoted-pairs, and three
2047 for also leaving any user-specified reverse solidus alone. The
2048 result will always be valid, if a successful exit status is re‐
2049 ported ([v15 behaviour may differ] the current parser fails
2050 this assertion for some constructs). [v15 behaviour may dif‐
2051 fer] Addresses need to be specified in between angle brackets
2052 ‘<’, ‘>’ if the construct becomes more difficult, otherwise the
2053 current parser will fail; it is not smart enough to guess
2054 right.
2055 ? addrc enc "Hey, you",<diet@exam.ple>\ out\ there
2057 "\"Hey, you\", \\ out\\ there" <diet@exam.ple>
2058 ? addrc d "\"Hey, you\", \\ out\\ there" <diet@exam.ple>
2059 "Hey, you", \ out\ there <diet@exam.ple>
2060 ? addrc s "\"Hey, you\", \\ out\\ there" <diet@exam.ple>
2061 diet@exam.ple
2062 alias, unalias
2064 [Only new quoting rules](a, una) Define or list, and remove,
2065 respectively, address aliases, which are a method of creating
2066 personal distribution lists that map a single name to none to
2067 multiple receivers, to be expanded after Compose mode is left;
2068 the expansion correlates with metoo. The latter command re‐
2069 moves all given aliases, the special name asterisk ‘*’ will re‐
2070 move all existing aliases. When used without arguments the
2071 former shows a list of all currently known aliases, with one
2072 argument only the target(s) of the given one. When given two
2073 arguments, hyphen-minus ‘-’ being the first, the target(s) of
2074 the second is/are expanded recursively.
2075 In all other cases the given alias is newly defined, or will be
2077 appended to: arguments must either be themselves valid alias
2078 names, or any other address type (see On sending mail, and non-
2079 interactive mode). Recursive expansion of aliases can be pre‐
2080 vented by prefixing the desired argument with the modifier re‐
2081 verse solidus \. A valid alias name conforms to mta-aliases
2082 syntax, but follow-up characters can also be the number sign
2083 ‘#’, colon ‘:’, commercial at ‘@,’ exclamation mark ‘!’, period
2084 ‘.’ as well as “any character that has the high bit set”. The
2085 dollar sign ‘$’ may be the last character. The number sign ‘#’
2086 may need Shell-style argument quoting.
2087 [v15 behaviour may differ] Unfortunately the colon is currently
2089 not supported, as it interferes with normal address parsing
2090 rules. [v15 behaviour may differ] Such high bit characters
2091 will likely cause warnings at the moment for the same reasons
2092 why colon is unsupported; also, in the future locale dependent
2093 character set validity checks will be performed.
2094 ? alias cohorts bill jkf mark kridle@ucbcory ~/cohorts.mbox
2096 ? alias mark mark@exam.ple
2097 ? set mta-aliases=/etc/aliases
2098 alternates, unalternates
2100 [Only new quoting rules] (alt) Manage a list of alternate ad‐
2101 dresses or names of the active user, members of which will be
2102 removed from recipient lists (except one). There is a set of
2103 implicit alternates which is formed of the values of LOGNAME,
2104 from, sender and reply-to. from will not be used if sender is
2105 set. The latter command removes the given list of alternates,
2106 the special name ‘*’ will discard all existing alternate names.
2107 The former command manages the error number !. It shows the
2109 current set of alternates when used without arguments; in this
2110 mode only it also supports vput (see Command modifiers). Oth‐
2111 erwise the given arguments (after being checked for validity)
2112 are appended to the list of alternate names; in posix mode they
2113 replace that list instead.
2114 answered, unanswered
2116 Take a message lists and mark each message as (not) having been
2117 answered. Messages will be marked answered when being replyd
2118 to automatically if the markanswered variable is set. See the
2119 section Message states.
2120 bind, unbind
2122 [Option][Only new quoting rules] The bind command extends the
2123 MLE (see On terminal control and line editor) with freely con‐
2124 figurable key bindings. The latter command removes from the
2125 given context the given key binding, both of which may be spec‐
2126 ified as a wildcard ‘*’, so that ‘unbind * *’ will remove all
2127 bindings of all contexts. Due to initialization order unbind‐
2128 ing will not work for built-in key bindings upon program
2129 startup, however: please use line-editor-no-defaults for this
2130 purpose instead.
2131 With zero arguments, or with a context name the former command
2133 shows all key bindings (of the given context; an asterisk ‘*’
2134 will iterate over all contexts); a more verbose listing will be
2135 produced if either of debug or verbose are set. With two or
2136 more arguments a specific binding is shown, or (re)established:
2137 the first argument is the context to which the binding shall
2138 apply, the second argument is a comma-separated list of the
2139 “keys” which form the binding. Further arguments will be
2140 joined to form the expansion, and cause the binding to be cre‐
2141 ated or updated. To indicate that a binding shall not be auto-
2142 committed, but that the expansion shall instead be furtherly
2143 editable by the user, a commercial at ‘@’ (that will be re‐
2144 moved) can be placed last in the expansion, from which leading
2145 and trailing whitespace will finally be removed. Reverse
2146 solidus cannot be used as the last character of expansion. An
2147 empty expansion will be rejected.
2148 Contexts define when a binding applies, i.e., a binding will
2150 not be seen unless the context for which it is defined for is
2151 currently active. This is not true for the shared binding
2152 ‘base’, which is the foundation for all other bindings and as
2153 such always applies, its bindings, however, only apply secon‐
2154 darily. The available contexts are the shared ‘base’, the
2155 ‘default’ context which is used in all not otherwise documented
2156 situations, and ‘compose’, which applies only to Compose mode.
2157 Bindings are specified as a comma-separated list of byte-se‐
2159 quences, where each list entry corresponds to one “key”
2160 (press). Byte sequence boundaries will be forcefully termi‐
2161 nated after bind-inter-byte-timeout milliseconds, whereas key
2162 sequences can be timed out via bind-inter-key-timeout. A list
2163 entry may, indicated by a leading colon character ‘:’, also re‐
2164 fer to the name of a terminal capability; several dozen names
2165 are compiled in and may be specified either by their
2166 terminfo(5), or, if existing, by their termcap(5) name, regard‐
2167 less of the actually used [Option]al terminal control library.
2168 But any capability may be used, as long as the name is resolv‐
2169 able by the [Option]al control library, or was defined via the
2170 internal variable termcap. Input sequences are not case-nor‐
2171 malized, an exact match is required to update or remove a bind‐
2172 ing. It is advisable to use an initial escape or other control
2173 character (like ‘\cA’) for user (as opposed to purely terminal
2174 capability based) bindings in order to avoid ambiguities; it
2175 also reduces search time. Examples:
2176 ? bind base a,b echo one
2178 ? bind base $'\E',d mle-snarf-word-fwd # Esc(ape)
2179 ? bind base $'\E',$'\c?' mle-snarf-word-bwd # Esc,Delete
2180 ? bind default $'\cA',:khome,w 'echo Editable binding@'
2181 ? bind default a,b,c rm -irf / @ # Also editable
2182 ? bind default :kf1 File %
2183 ? bind compose :kf1 ~v
2184 Note that the entire comma-separated list is first parsed
2186 (over) as a shell-token with whitespace as the field separator,
2187 then parsed and expanded for real with comma as the field sepa‐
2188 rator, therefore whitespace needs to be properly quoted, see
2189 Shell-style argument quoting. Using Unicode reverse solidus
2190 escape sequences renders a binding defunctional if the locale
2191 does not support Unicode (see Character sets), and using termi‐
2192 nal capabilities does so if no (corresponding) terminal control
2193 support is (currently) available. Adding, deleting or modify‐
2194 ing a key binding invalidates the internal prebuilt lookup
2195 tree, it will be recreated as necessary: this process will be
2196 visualized in most verbose as well as in debug mode.
2197 The following terminal capability names are built-in and can be
2199 used in terminfo(5) or (if available) the two-letter termcap(5)
2200 notation. See the respective manual for a list of capabili‐
2201 ties. The program infocmp(1) can be used to show all the capa‐
2202 bilities of TERM or the given terminal type; using the -x flag
2203 will also show supported (non-standard) extensions.
2204 kbs or kb Backspace.
2206 kdch1 or kD Delete character.
2207 kDC or *4 — shifted variant.
2208 kel or kE Clear to end of line.
2209 kext or @9 Exit.
2210 kich1 or kI Insert character.
2211 kIC or #3 — shifted variant.
2212 khome or kh Home.
2213 kHOM or #2 — shifted variant.
2214 kend or @7 End.
2215 knp or kN Next page.
2216 kpp or kP Previous page.
2217 kcub1 or kl Left cursor (with more modifiers: see below).
2218 kLFT or #4 — shifted variant.
2219 kcuf1 or kr Right cursor (ditto).
2220 kRIT or %i — shifted variant.
2221 kcud1 or kd Down cursor (ditto).
2222 kDN — shifted variant (only terminfo).
2223 kcuu1 or ku Up cursor (ditto).
2224 kUP — shifted variant (only terminfo).
2225 kf0 or k0 Function key 0. Add one for each function key
2226 up to kf9 and k9, respectively.
2227 kf10 or k; Function key 10.
2228 kf11 or F1 Function key 11. Add one for each function key
2229 up to kf19 and F9, respectively.
2230 Some terminals support key-modifier combination extensions,
2232 e.g., ‘Alt+Shift+xy’. For example, the delete key, kdch1: in
2233 its shifted variant, the name is mutated to kDC, then a number
2234 is appended for the states ‘Alt’ (kDC3), ‘Shift+Alt’ (kDC4),
2235 ‘Control’ (kDC5), ‘Shift+Control’ (kDC6), ‘Alt+Control’ (kDC7),
2236 finally ‘Shift+Alt+Control’ (kDC8). The same for the left cur‐
2237 sor key, kcub1: KLFT, KLFT3, KLFT4, KLFT5, KLFT6, KLFT7, KLFT8.
2238 call [Only new quoting rules] Calls the given macro, which must have
2240 been created via define (see there for more), otherwise an
2241 ^ERR-NOENT error occurs. Calling macros recursively will at
2242 some time excess the stack size limit, causing a hard program
2243 abortion; if recursively calling a macro is the last command of
2244 the current macro, consider to use the command xcall, which
2245 will first release all resources of the current macro before
2246 replacing the current macro with the called one.
2247 call_if Identical to call if the given macro has been created via
2249 define, but does not fail nor warn if the macro does not exist.
2250 cd Synonym for chdir.
2252 certsave [Option] Only applicable to S/MIME signed messages. Takes an
2254 optional message list and a filename and saves the certificates
2255 contained within the message signatures to the named file in
2256 both human-readable and PEM format. The certificates can later
2257 be used to send encrypted messages to the respective message
2258 senders by setting smime-encrypt-USER@HOST variables.
2259 charsetalias, uncharsetalias
2261 [Only new quoting rules] Manage alias mappings for (conversion
2262 of) Character sets. Alias processing is not performed for
2263 INTERNAL VARIABLES, for example charset-8bit, and mappings are
2264 ineffective if character set conversion is not available
2265 (features does not announce ‘,+iconv,’). Expansion happens re‐
2266 cursively for cases where aliases point to other aliases
2267 (built-in loop limit: 8).
2268 The latter command deletes all aliases given as arguments, or
2270 all at once when given the asterisk ‘*’. The former shows the
2271 list of all currently defined aliases if used without argu‐
2272 ments, or the target of the given single argument; when given
2273 two arguments, hyphen-minus ‘-’ being the first, the second is
2274 instead expanded recursively. In all other cases the given ar‐
2275 guments are treated as pairs of character sets and their de‐
2276 sired target alias name, creating new or updating already ex‐
2277 isting aliases.
2278 chdir [Only new quoting rules](ch) Change the working directory to
2280 HOME or the given argument. Synonym for cd.
2281 collapse, uncollapse
2283 Only applicable to ‘thread’ed sort mode. Takes a message list
2284 and makes all replies to these messages invisible in header
2285 summaries, except for ‘new’ messages and the “dot”. Also when
2286 a message with collapsed replies is displayed, all of these are
2287 automatically uncollapsed. The latter command undoes collaps‐
2288 ing.
2289 colour, uncolour
2291 [Option][Only new quoting rules] Manage colour mappings of and
2292 for a Coloured display. Without arguments the former shows all
2293 currently defined mappings. Otherwise a colour type is ex‐
2294 pected (case-insensitively), it must be one of ‘256’ for
2295 256-colour terminals, ‘8’, ‘ansi’ or ‘iso’ for the standard
2296 8-colour ANSI / ISO 6429 colour palette, and ‘1’ or ‘mono’ for
2297 monochrome terminals, which only support (some) font at‐
2298 tributes. Without further arguments the list of all currently
2299 defined mappings of the given type is shown (here the special
2300 ‘all’ or ‘*’ also show all currently defined mappings).
2301 Otherwise the second argument defines the mappable slot, the
2303 third argument a (comma-separated list of) colour and font at‐
2304 tribute specification(s), and the optionally supported fourth
2305 argument can be used to specify a precondition: if conditioned
2306 mappings exist they are tested in (creation) order unless a
2307 (case-insensitive) match has been found, and the default map‐
2308 ping (if any has been established) will only be chosen as a
2309 last resort. The types of available preconditions depend on
2310 the mappable slot, the following of which exist:
2311 Mappings prefixed with ‘mle-’ are used for the [Option]al
2313 built-in Mailx-Line-Editor (MLE, see On terminal control and
2314 line editor) and do not support preconditions.
2315 mle-position This mapping is used for the position indicator
2317 that is visible when a line cannot be fully dis‐
2318 played on the screen.
2319 mle-prompt Used for the prompt.
2320 mle-error Used for the occasionally appearing error indi‐
2321 cator that is joined onto prompt. [v15 behav‐
2322 iour may differ] Also used for error messages
2323 written on standard error .
2324 Mappings prefixed with ‘sum-’ are used in header summaries, and
2326 they all understand the preconditions ‘dot’ (the current mes‐
2327 sage) and ‘older’ for elder messages (only honoured in conjunc‐
2328 tion with datefield-markout-older).
2329 sum-dotmark This mapping is used for the “dotmark” that can
2331 be created with the ‘%>’ or ‘%<’ formats of the
2332 variable headline.
2333 sum-header For the complete header summary line except the
2334 “dotmark” and the thread structure.
2335 sum-thread For the thread structure which can be created
2336 with the ‘%i’ format of the variable headline.
2337 Mappings prefixed with ‘view-’ are used when displaying mes‐
2339 sages.
2340 view-from_ This mapping is used for so-called ‘From_’
2342 lines, which are MBOX file format specific
2343 header lines (also see mbox-rfc4155).
2344 view-header For header lines. A comma-separated list of
2345 headers to which the mapping applies may be
2346 given as a precondition; if the [Option]al regu‐
2347 lar expression support is available then if any
2348 of the magic regular expression characters is
2349 seen the precondition will be evaluated as (an
2350 extended) one.
2351 view-msginfo For the introductional message info line.
2352 view-partinfo For MIME part info lines.
2353 The following (case-insensitive) colour definitions and font
2355 attributes are understood, multiple of which can be specified
2356 in a comma-separated list:
2357 ft= a font attribute: ‘bold’, ‘reverse’ or ‘underline’. It is
2359 possible (and often applicable) to specify multiple font
2360 attributes for a single mapping.
2361 fg= foreground colour attribute, in order (numbers 0 - 7)
2363 ‘black’, ‘red’, ‘green’, ‘brown’, ‘blue’, ‘magenta’,
2364 ‘cyan’ or ‘white’. To specify a 256-colour mode a decimal
2365 number colour specification in the range 0 to 255, inclu‐
2366 sive, is supported, and interpreted as follows:
2367 0 - 7 the standard ISO 6429 colours, as above.
2369 8 - 15 high intensity variants of the standard
2370 colours.
2371 16 - 231 216 colours in tuples of 6.
2372 232 - 255 grayscale from black to white in 24 steps.
2373 #!/bin/sh -
2375 fg() { printf "\033[38;5;${1}m($1)"; }
2376 bg() { printf "\033[48;5;${1}m($1)"; }
2377 i=0
2378 while [ $i -lt 256 ]; do fg $i; i=$(($i + 1)); done
2379 printf "\033[0m\n"
2380 i=0
2381 while [ $i -lt 256 ]; do bg $i; i=$(($i + 1)); done
2382 printf "\033[0m\n"
2383 bg= background colour attribute (see fg= for possible values).
2385 The command uncolour will remove for the given colour type (the
2387 special type ‘*’ selects all) the given mapping; if the op‐
2388 tional precondition argument is given only the exact tuple of
2389 mapping and precondition is removed. The special name ‘*’ will
2390 remove all mappings (no precondition allowed), thus ‘uncolour *
2391 *’ will remove all established mappings.
2392 commandalias, uncommandalias
2394 [Only new quoting rules] Define or list, and remove, respec‐
2395 tively, command aliases. An (command)alias can be used every‐
2396 where a normal command can be used, but always takes prece‐
2397 dence: any arguments that are given to the command alias are
2398 joined onto the alias expansion, and the resulting string forms
2399 the command line that is, in effect, executed. The latter com‐
2400 mand removes all given aliases, the special name asterisk ‘*’
2401 will remove all existing aliases. When used without arguments
2402 the former shows a list of all currently known aliases, with
2403 one argument only the expansion of the given one.
2404 With two or more arguments a command alias is defined or up‐
2406 dated: the first argument is the name under which the remaining
2407 command line should be accessible, the content of which can be
2408 just about anything. An alias may itself expand to another
2409 alias, but to avoid expansion loops further expansion will be
2410 prevented if an alias refers to itself or if an expansion depth
2411 limit is reached. Explicit expansion prevention is available
2412 via reverse solidus \, one of the Command modifiers.
2413 ? commandalias xx
2415 s-nail: `commandalias': no such alias: xx
2416 ? commandalias xx echo hello,
2417 ? commandalias xx
2418 commandalias xx 'echo hello,'
2419 ? xx
2420 hello,
2421 ? xx world
2422 hello, world
2423 Copy (C) Similar to copy, but copy the messages to a file named af‐
2425 ter the local part of the sender of the first message instead
2426 of taking a filename argument; outfolder is inspected to decide
2427 on the actual storage location.
2428 copy (c) Copy messages to the named file and do not mark them as be‐
2430 ing saved; otherwise identical to save.
2431 csop [Only new quoting rules] A multiplexer command which provides
2433 C-style string operations on 8-bit bytes without a notion of
2434 locale settings and character sets, effectively assuming ASCII
2435 data. For numeric and other operations refer to vexpr. vput,
2436 one of the Command modifiers, is supported. The error result
2437 is ‘-1’ for usage errors and numeric results, the empty string
2438 otherwise; missing data errors, as for unsuccessful searches,
2439 result in the ! error number being set to ^ERR-NODATA. Where
2440 the question mark ‘?’ modifier suffix is supported, a case-in‐
2441 sensitive (ASCII mapping) operation mode is supported; the key‐
2442 word ‘case’ is optional so that ‘find?’ and ‘find?case’ are
2443 identical.
2444 length Queries the length of the given argument.
2446 hash, hash32 Calculates a hash value of the given argument.
2448 The latter will return a 32-bit result regardless of
2449 host environment. ‘?’ modifier suffix is supported.
2450 These use Chris Torek's hash algorithm, the resulting
2451 hash value is bit mixed as shown by Bret Mulvey.
2452 find Search for the second in the first argument. Shows
2454 the resulting 0-based offset shall it have been
2455 found. ‘?’ modifier suffix is supported.
2456 substring Creates a substring of its first argument. The op‐
2458 tional second argument is the 0-based starting off‐
2459 set, a negative one counts from the end; the optional
2460 third argument specifies the length of the desired
2461 result, a negative length leaves off the given number
2462 of bytes at the end of the original string; by de‐
2463 fault the entire string is used. This operation
2464 tries to work around faulty arguments (set verbose
2465 for error logs), but reports them via the error num‐
2466 ber ! as ^ERR-OVERFLOW.
2467 trim Trim away whitespace characters from both ends of the
2469 argument.
2470 trim-front Trim away whitespace characters from the begin of
2472 the argument.
2473 trim-end Trim away whitespace characters from the end of the
2475 argument.
2476 cwd Show the name of the current working directory, as reported by
2478 getcwd(3). Supports vput (see Command modifiers). The return
2479 status is tracked via ?.
2480 Decrypt [Option] For unencrypted messages this command is identical to
2482 Copy; Encrypted messages are first decrypted, if possible, and
2483 then copied.
2484 decrypt [Option] For unencrypted messages this command is identical to
2486 copy; Encrypted messages are first decrypted, if possible, and
2487 then copied.
2488 define, undefine
2490 The latter command deletes the given macro, the special name
2491 ‘*’ will discard all existing macros. Deletion of (a) macro(s)
2492 can be performed from within running (a) macro(s), including
2493 self-deletion. Without arguments the former command prints the
2494 current list of macros, including their content, otherwise it
2495 defines a macro, replacing an existing one of the same name as
2496 applicable.
2497 A defined macro can be invoked explicitly by using the call,
2499 call_if and xcall commands, or implicitly if a macro hook is
2500 triggered, for example a folder-hook. Execution of a macro
2501 body can be stopped from within by calling return.
2502 Temporary macro block-scope variables can be created or deleted
2504 with the local command modifier in conjunction with the com‐
2505 mands set and unset, respectively. To enforce unrolling of
2506 changes made to (global) INTERNAL VARIABLES the command
2507 localopts can be used instead; its covered scope depends on how
2508 (i.e., “as what”: normal macro, folder hook, hook, account
2509 switch) the macro is invoked.
2510 Inside a called macro, the given positional parameters are im‐
2512 plicitly local to the macro's scope, and may be accessed via
2513 the variables *, @, # and 1 and any other positive unsigned
2514 decimal number less than or equal to #. Positional parameters
2515 can be shifted, or become completely replaced, removed etc. via
2516 vpospar. A helpful command for numeric computation and string
2517 evaluations is vexpr, csop offers C-style byte string opera‐
2518 tions.
2519 define name {
2521 command1
2522 command2
2523 ...
2524 commandN
2525 }
2526 define exmac {
2528 echo Parameter 1 of ${#} is ${1}, all: ${*} / ${@}
2529 return 1000 0
2530 }
2531 call exmac Hello macro exmac!
2532 echo ${?}/${!}/${^ERRNAME}
2533 delete, undelete
2535 (d, u) Marks the given message list as being or not being
2536 ‘deleted’, respectively; if no argument has been specified then
2537 the usual search for a visible message is performed, as docu‐
2538 mented for Message list arguments, showing only the next input
2539 prompt if the search fails. Deleted messages will neither be
2540 saved in the secondary mailbox MBOX nor will they be available
2541 for most other commands. If the autoprint variable is set, the
2542 new “dot” or the last message restored, respectively, is auto‐
2543 matically typed; also see dp, dt.
2544 digmsg [Only new quoting rules] Digging (information out of) messages
2546 is possible through digmsg objects, which can be created for
2547 the given message number; in Compose mode the hyphen-minus ‘-’
2548 will instead open the message that is being composed. If a hy‐
2549 phen-minus is given as the optional third argument then output
2550 will be generated on the standard output channel instead of be‐
2551 ing subject to consumption by the readall (or read and readsh)
2552 command(s). Note: output must be consumed before normal pro‐
2553 cessing can continue; for digmsg objects this means each com‐
2554 mand output has to be read until the end of file (EOF) state
2555 occurs.
2556 The objects may be removed again by giving the same identifier
2558 used for creation; this step could be omitted: objects will be
2559 automatically closed when the active folder (mailbox) or the
2560 compose mode is left, respectively. In all other use cases the
2561 second argument is an object identifier, and the third and all
2562 following arguments are interpreted as via ~^ (see COMMAND
2563 ESCAPES):
2564 ? vput = msgno; digmsg create $msgno
2566 ? digmsg $msgno header list; readall x; echon $x
2567 210 Subject From To Message-ID References In-Reply-To
2568 ? digmsg $msgno header show Subject;readall x;echon $x
2569 212 Subject
2570 'Hello, world'
2571 ? digmsg remove $msgno
2573 discard (di) Identical to ignore. Superseded by the multiplexer
2575 headerpick.
2576 dp, dt Delete the given messages and automatically type the new “dot”
2578 if one exists, regardless of the setting of autoprint.
2579 dotmove Move the “dot” up or down by one message when given ‘+’ or ‘-’
2581 argument, respectively.
2582 draft, undraft
2584 Take message lists and mark each given message as being draft,
2585 or not being draft, respectively, as documented in the section
2586 Message states.
2587 echo [Only new quoting rules](ec) Print the given strings, equiva‐
2589 lent to the shell utility echo(1), that is, Shell-style
2590 argument quoting expansion is performed and, different to the
2591 otherwise identical echon, a trailing newline is echoed. vput
2592 as documented in Command modifiers is supported, and the error
2593 number ! is managed: if data is stored in a variable then the
2594 return value reflects the length of the result string in case
2595 of success and is ‘-1’ on error.
2596 Remarks: this command traditionally (in BSD Mail) also per‐
2598 formed Filename transformations, which is standard incompatible
2599 and hard to handle because quoting transformation patterns is
2600 not possible; the subcommand file-expand of vexpr can be used
2601 to expand filenames.
2602 echoerr [Only new quoting rules] Identical to echo, but the message is
2604 written to standard error, and prefixed by log-prefix. Also
2605 see echoerrn. In interactive sessions the [Option]al message
2606 ring queue for errors will be used instead, if available and
2607 vput was not used.
2608 echon [Only new quoting rules] Identical to echo, but does not write
2610 or store a trailing newline.
2611 echoerrn [Only new quoting rules] Identical to echoerr, but does not
2613 write or store a trailing newline.
2614 edit (e) Point the text EDITOR at each message from the given list
2616 in turn. Modified contents are discarded unless the
2617 writebackedited variable is set, and are not used unless the
2618 mailbox can be written to and the editor returns a successful
2619 exit status. visual can be used instead for a more display
2620 oriented editor.
2621 elif Part of the if (see there for more), elif, else, endif condi‐
2623 tional — if the condition of a preceding if was false, check
2624 the following condition and execute the following block if it
2625 evaluates true.
2626 else (el) Part of the if (see there for more), elif, else, endif
2628 conditional — if none of the conditions of the preceding if and
2629 elif commands was true, the else block is executed.
2630 endif (en) Marks the end of an if (see there for more), elif, else,
2632 endif conditional execution block.
2633 environ [Only new quoting rules] There is a strict separation in be‐
2635 tween INTERNAL VARIABLES and the program ENVIRONMENT, which is
2636 inherited by child processes. Some variables of the latter are
2637 however vivid for program operation, their purpose is known,
2638 therefore they have been integrated transparently into handling
2639 of the former, as accessible via set and unset. To integrate
2640 any other environment variable, and/or to export internal vari‐
2641 ables into the process environment where they normally are not,
2642 a link needs to become established with this command, for exam‐
2643 ple
2644 environ link PERL5LIB TZ
2646 Afterwards changing such variables with set will cause auto‐
2648 matic updates of the environment, too. Sufficient system sup‐
2649 port provided (it was in BSD as early as 1987, and is standard‐
2650 ized since Y2K) removing such variables with unset will remove
2651 them also from the environment, but in any way the knowledge
2652 they ever have been linked will be lost. This implies that
2653 localopts may cause loss of such links.
2654 The subcommand unlink removes an existing link without other‐
2656 wise touching variables, the set and unset subcommands are
2657 identical to set and unset, but additionally update the program
2658 environment accordingly; removing a variable breaks any freely
2659 established link.
2660 errors [Option] As console user interfaces at times scroll error mes‐
2662 sages by too fast and/or out of scope, data can additionally be
2663 sent to an error queue manageable by this command: show or no
2664 argument will display and clear the queue, clear will only
2665 clear it. As the queue becomes filled with errors-limit en‐
2666 tries the eldest entries are being dropped. There are also the
2667 variables ^ERRQUEUE-COUNT and ^ERRQUEUE-EXISTS.
2668 eval [Only new quoting rules] Construct a command by concatenating
2670 the arguments, separated with a single space character, and
2671 then evaluate the result. This command passes through the exit
2672 status ? and error number ! of the evaluated command; also see
2673 call.
2674 define xxx {
2676 echo "xxx arg <$1>"
2677 shift
2678 if $# -gt 0
2679 \xcall xxx "$@"
2680 endif
2681 }
2682 define yyy {
2683 eval "$@ ' ball"
2684 }
2685 call yyy '\call xxx' "b\$'\t'u ' "
2686 call xxx arg <b u>
2687 call xxx arg < >
2688 call xxx arg <ball>
2689 exit (ex or x) Exit from S-nail without changing the active mailbox
2691 and skip any saving of messages in the secondary mailbox MBOX,
2692 as well as a possibly tracked line editor history-file. A pos‐
2693 sibly set on-account-cleanup will be invoked, however. The op‐
2694 tional status number argument will be passed through to
2695 exit(3). [v15 behaviour may differ] For now it can happen that
2696 the given status will be overwritten, later this will only oc‐
2697 cur if a later error needs to be reported onto an otherwise
2698 success indicating status.
2699 File (Fi) Like folder, but open the mailbox read-only.
2701 file (fi) See folder.
2703 filetype, unfiletype
2705 [Only new quoting rules] Define, list, and remove, respec‐
2706 tively, file handler hooks, which provide (shell) commands that
2707 enable S-nail to load and save MBOX files from and to files
2708 with the registered file extensions, as shown and described for
2709 folder. The extensions are used case-insensitively, yet the
2710 auto-completion feature of for example folder will only work
2711 case-sensitively. An intermediate temporary file will be used
2712 to store the expanded data. The latter command will remove
2713 hooks for all given extensions, asterisk ‘*’ will remove all
2714 existing handlers.
2715 When used without arguments the former shows a list of all cur‐
2717 rently defined file hooks, with one argument the expansion of
2718 the given alias. Otherwise three arguments are expected, the
2719 first specifying the file extension for which the hook is
2720 meant, and the second and third defining the load- and save
2721 commands to deal with the file type, respectively, both of
2722 which must read from standard input and write to standard out‐
2723 put. Changing hooks will not affect already opened mailboxes
2724 ([v15 behaviour may differ] except below). [v15 behaviour may
2725 differ] For now too much work is done, and files are oftened
2726 read in twice where once would be sufficient: this can cause
2727 problems if a filetype is changed while such a file is opened;
2728 this was already so with the built-in support of .gz etc. in
2729 Heirloom, and will vanish in v15. [v15 behaviour may differ]
2730 For now all handler strings are passed to the SHELL for
2731 evaluation purposes; in the future a ‘!’ prefix to load and
2732 save commands may mean to bypass this shell instance: placing a
2733 leading space will avoid any possible misinterpretations.
2734 ? filetype bz2 'bzip2 -dc' 'bzip2 -zc' \
2736 gz 'gzip -dc' 'gzip -c' xz 'xz -dc' 'xz -zc' \
2737 zst 'zstd -dc' 'zstd -19 -zc' \
2738 zst.pgp 'gpg -d | zstd -dc' 'zstd -19 -zc | gpg -e'
2739 ? set record=+sent.zst.pgp
2740 flag, unflag
2742 Take message lists and mark the messages as being flagged, or
2743 not being flagged, respectively, for urgent/special attention.
2744 See the section Message states.
2745 Folder (Fold) Like folder, but open the mailbox read-only.
2747 folder (fold) Open a new, or show status information of the current
2749 mailbox. If an argument is given, changes (such as deletions)
2750 will be written out, a new mailbox will be opened, the internal
2751 variables mailbox-resolved and mailbox-display will be updated,
2752 a set according folder-hook is executed, and optionally a sum‐
2753 mary of headers is displayed if the variable header is set.
2754 Filename transformations will be applied to the name argument,
2756 and ‘protocol://’ prefixes are, i.e., URL (see On URL syntax
2757 and credential lookup) syntax is understood, as in
2758 ‘mbox:///tmp/somefolder’. If a protocol prefix is used the
2759 mailbox type is fixated, otherwise opening none-existing
2760 folders uses the protocol defined in newfolders.
2761 For the protocols mbox and file (MBOX database), as well as eml
2763 (electronic mail message [v15 behaviour may differ] read-only)
2764 the list of all registered filetypes is traversed to check
2765 whether hooks shall be used to load (and save) data from (and
2766 to) the given name. Changing hooks will not affect already
2767 opened mailboxes. For example, the following creates hooks for
2768 the gzip(1) compression tool and a combined compressed and en‐
2769 crypted format:
2770 ? filetype \
2772 gzip 'gzip -dc' 'gzip -c' \
2773 zst.pgp 'gpg -d | zstd -dc' 'zstd -19 -zc | gpg -e'
2774 For historic reasons filetypes provide limited (case-sensitive)
2776 auto-completion capabilities. For example ‘mbox.gz’ will be
2777 found for ‘? file mbox’, provided that corresponding handlers
2778 are installed. It will neither find ‘mbox.GZ’ nor ‘mbox.Gz’
2779 however, but an explicit ‘? file mbox.GZ’ will find and use the
2780 handler for ‘gz’. [v15 behaviour may differ] The latter mode
2781 can only be used for MBOX files.
2782 EML files consist of only one mail message, [v15 behaviour may
2784 differ] and can only be opened read-only. When reading MBOX
2785 files tolerant POSIX rules are used by default. Invalid mes‐
2786 sage boundaries that can be found quite often in historic MBOX
2787 files will be complained about (even more with debug): in this
2788 case the method described for mbox-rfc4155 can be used to cre‐
2789 ate a valid MBOX database from the invalid input.
2790 MBOX databases and EML files will always be protected via file-
2792 region locks (fcntl(2)) during file operations to protect
2793 against concurrent modifications. [Option] An MBOX inbox
2794 (MAIL) or primary system mailbox will also be protected by so-
2795 called dotlock files, the traditional way of mail spool file
2796 locking: for any file ‘x’ a lock file ‘x.lock’ will be created
2797 during the synchronization, in the same directory and with the
2798 same user and group identities as the file of interest — as
2799 necessary created by an external privileged dotlock helper.
2800 dotlock-disable disables dotlock files. Also see FAQ: Howto
2801 handle stale dotlock files.
2802 [Option] If no protocol has been fixated, and name refers to a
2804 directory with the subdirectories ‘tmp’, ‘new’ and ‘cur’, then
2805 it is treated as a folder in “Maildir” format. The maildir
2806 format stores each message in its own file, and has been de‐
2807 signed so that file locking is not necessary when reading or
2808 writing files.
2809 [Option]ally URLs can be used to access network resources, se‐
2811 curely via Encrypted network communication, if so supported.
2812 Network communication socket timeouts are configurable via
2813 socket-connect-timeout. All network traffic may be proxied
2814 over a SOCKS server via socks-proxy.
2815 [v15-compat]
2817 protocol://[user[:password]@]host[:port][/path]
2818 [no v15-compat] protocol://[user@]host[:port][/path]
2819 [Option]ally supported network protocols are pop3 (POP3) and
2821 pop3s (POP3 with TLS encrypted transport), imap and imaps. The
2822 [/path] part is valid only for IMAP; there it defaults to
2823 INBOX. Network URLs require a special encoding as documented
2824 in the section On URL syntax and credential lookup.
2825 folders Lists the names of all folders below the given argument or
2827 folder. For file-based protocols LISTER will be used for dis‐
2828 play purposes.
2829 Followup, followup
2831 (Compose mode)(F,fo) Similar to Reply, and reply, respectively,
2832 but save the message in a file named after the local part of
2833 the (first) recipient's address, possibly overwriting record,
2834 and honouring outfolder. Also see Copy and Save.
2835 Forward (Compose mode) Similar to forward, but saves the message in a
2837 file named after the local part of the recipient's address (in‐
2838 stead of in record).
2839 forward (Compose mode) Take a message list and the address of a recipi‐
2841 ent, subject to fullnames, to whom the messages are sent. The
2842 text of the original message is included in the new one, en‐
2843 closed by the values of forward-inject-head and
2844 forward-inject-tail. content-description-forwarded-message is
2845 inspected. The list of included headers can be filtered with
2846 the ‘forward’ slot of the white- and blacklisting command
2847 headerpick. Only the first part of a multipart message is in‐
2848 cluded but for forward-as-attachment.
2849 This may generate the errors ^ERR-DESTADDRREQ if no receiver
2851 has been specified, or was rejected by expandaddr policy,
2852 ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a necessary
2853 character set conversion fails, and ^ERR-INVAL for other er‐
2854 rors. It can also fail with errors of Specifying messages.
2855 Any error stops processing of further messages.
2856 from (f) Takes a list of message specifications and displays a sum‐
2858 mary of their message headers, exactly as via headers, making
2859 the first message of the result the new “dot” (the last message
2860 if showlast is set). An alias of this command is search. Also
2861 see Specifying messages.
2862 Fwd [Obsolete] Alias for Forward.
2864 fwd [Obsolete] Alias for forward.
2866 fwdignore
2868 [Obsolete] Superseded by the multiplexer headerpick.
2869 fwdretain
2871 [Obsolete] Superseded by the multiplexer headerpick.
2872 ghost, unghost
2874 [Obsolete] Replaced by commandalias, uncommandalias.
2875 headerpick, unheaderpick
2877 [Only new quoting rules] Multiplexer command to manage white-
2878 and blacklisting selections of header fields for a variety of
2879 applications. Without arguments the set of contexts that have
2880 settings is displayed. When given arguments, the first argu‐
2881 ment is the context to which the command applies, one of (case-
2882 insensitive) ‘type’ for display purposes (for example type),
2883 ‘save’ for selecting which headers shall be stored persistently
2884 when save, copy, move or even decrypting messages (note that
2885 MIME related etc. header fields should not be ignored in order
2886 to not destroy usability of the message in this case),
2887 ‘forward’ for stripping down messages when forwarding message
2888 (has no effect if forward-as-attachment is set), and ‘top’ for
2889 defining user-defined set of fields for the command top.
2890 The current settings of the given context are displayed if it
2892 is the only argument. A second argument denotes the type of
2893 restriction that is to be chosen, it may be (a case-insensitive
2894 prefix of) ‘retain’ or ‘ignore’ for white- and blacklisting
2895 purposes, respectively. Establishing a whitelist suppresses
2896 inspection of the corresponding blacklist.
2897 If no further argument is given the current settings of the
2899 given type will be displayed, otherwise the remaining arguments
2900 specify header fields, which [Option]ally may be given as regu‐
2901 lar expressions, to be added to the given type. The special
2902 wildcard field (asterisk, ‘*’) will establish a (fast) short‐
2903 hand setting which covers all fields.
2904 The latter command always takes three or more arguments and can
2906 be used to remove selections, i.e., from the given context, the
2907 given type of list, all the given headers will be removed, the
2908 special argument ‘*’ will remove all headers.
2909 headers (h) Show the current group of headers, the size of which de‐
2911 pends on the variable screen in interactive mode, and the for‐
2912 mat of which can be defined with headline. If a message-speci‐
2913 fication is given the group of headers containing the first
2914 message therein is shown and the message at the top of the
2915 screen becomes the new “dot”; the last message is targeted if
2916 showlast is set.
2917 help (hel) A synonym for ?.
2919 history [Option] Without arguments or when given show all history en‐
2921 tries are shown (this mode also supports a more verbose out‐
2922 put). load will replace the list of entries with the content
2923 of history-file, and save will dump all entries to said file,
2924 replacing former content, and clear will delete all entries.
2925 The argument can also be a signed decimal NUMBER, which will
2926 select and evaluate the respective history entry, and move it
2927 to the top of the history; a negative number is used as an off‐
2928 set to the current command so that ‘-1’ will select the last
2929 command, the history top, whereas delete will delete all given
2930 entries (:NUMBER:). Also see On terminal control and line
2931 editor.
2932 hold (ho, also preserve) Takes a message list and marks each message
2934 therein to be saved in the user's system inbox instead of in
2935 the secondary mailbox MBOX. Does not override the delete com‐
2936 mand. S-nail deviates from the POSIX standard with this com‐
2937 mand, because a next command issued after hold will display the
2938 following message, not the current one.
2939 if (i) Part of the if, elif, else, endif conditional execution
2941 construct — if the given condition is true then the encapsu‐
2942 lated block is executed. The POSIX standard only supports the
2943 (case-insensitive) conditions ‘r’eceive and ‘s’end, the remain‐
2944 ing are non-portable extensions. [v15 behaviour may differ] In
2945 conjunction with the wysh command prefix(es) Shell-style
2946 argument quoting and more test operators are available.
2947 if receive
2949 commands ...
2950 else
2951 commands ...
2952 endif
2953 Further (case-insensitive) one-argument conditions are
2955 ‘t’erminal which evaluates to true in interactive terminal ses‐
2956 sions (running with standard input or standard output attached
2957 to a terminal, and none of the “quickrun” command line options
2958 -e, -H and -L have been used), as well as any boolean value
2959 (see INTERNAL VARIABLES for textual boolean representations) to
2960 mark an enwrapped block as “never execute” or “always execute”.
2961 (Remarks: condition syntax errors skip all branches until
2962 endif.)
2963 [no v15-compat] and without wysh: It is possible to check
2965 INTERNAL VARIABLES as well as ENVIRONMENT variables for exis‐
2966 tence or compare their expansion against a user given value or
2967 another variable by using the ‘$’ (“variable next”) conditional
2968 trigger character; a variable on the right hand side may be
2969 signalled using the same mechanism. Variable names may be en‐
2970 closed in a pair of matching braces. When this mode has been
2971 triggered, several operators are available ([v15-compat] and
2972 wysh: they are always available, and there is no trigger: vari‐
2973 ables will have been expanded by the shell-compatible parser
2974 before the if etc. command sees them).
2975 [v15-compat] Two argument conditions. Variables can be tested
2977 for existence and expansion: ‘-N’ will test whether the given
2978 variable exists, so that ‘-N editalong’ will evaluate to true
2979 when editalong is set, whereas ‘-Z editalong’ will if it is
2980 not. ‘-n "$editalong"’ will be true if the variable is set and
2981 expands to a non-empty string, ‘-z $'\$editalong'’ only if the
2982 expansion is empty, whether the variable exists or not. The
2983 remaining conditions take three arguments.
2984 Integer operators treat the arguments on the left and right
2986 hand side of the operator as integral numbers and compare them
2987 arithmetically. It is an error if any of the operands is not a
2988 valid integer, an empty argument (which implies it had been
2989 quoted) is treated as if it were 0. Via the question mark ‘?’
2990 modifier suffix a saturated operation mode is available where
2991 numbers will linger at the minimum or maximum possible value,
2992 instead of overflowing (or trapping), the keyword ‘saturated’
2993 is optional, ‘==?’, ‘==?satu’ and ‘==?saturated’ are therefore
2994 identical. Available operators are ‘-lt’ (less than), ‘-le’
2995 (less than or equal to), ‘-eq’ (equal), ‘-ne’ (not equal),
2996 ‘-ge’ (greater than or equal to), and ‘-gt’ (greater than).
2997 String and regular expression data operators compare the left
2999 and right hand side according to their textual content. Unset
3000 variables are treated as the empty string. Via the question
3001 mark ‘?’ modifier suffix a case-insensitive operation mode is
3002 available, the keyword ‘case’ is optional, ‘==?’ and ‘==?case’
3003 are identical.
3004 Available string operators are ‘<’ (less than), ‘<=’ (less than
3006 or equal to), ‘==’ (equal), ‘!=’ (not equal), ‘>=’ (greater
3007 than or equal to), ‘>’ (greater than), ‘=%’ (is substring of)
3008 and ‘!%’ (is not substring of). By default these operators
3009 work on bytes and (therefore) do not take into account charac‐
3010 ter set specifics. If the case-insensitivity modifier has been
3011 used, case is ignored according to the rules of the US-ASCII
3012 encoding, i.e., bytes are still compared.
3013 When the [Option]al regular expression support is available,
3015 the additional string operators ‘=~’ and ‘!~’ can be used.
3016 They treat the right hand side as an extended regular expres‐
3017 sion that is matched according to the active locale (see
3018 Character sets), i.e., character sets should be honoured cor‐
3019 rectly.
3020 Conditions can be joined via AND-OR lists (where the AND opera‐
3022 tor is ‘&&’ and the OR operator is ‘||’), which have equal
3023 precedence and will be evaluated with left associativity, thus
3024 using the same syntax that is known for the sh(1). It is also
3025 possible to form groups of conditions and lists by enclosing
3026 them in pairs of brackets ‘[ ... ]’, which may be interlocked
3027 within each other, and also be joined via AND-OR lists.
3028 The results of individual conditions and entire groups may be
3030 modified via unary operators: the unary operator ‘!’ will re‐
3031 verse the result.
3032 wysh set v15-compat=yes # with value: automatic "wysh"!
3034 if -N debug;echo *debug* set;else;echo not;endif
3035 if "$ttycharset" == UTF-8 || "$ttycharset" ==?cas UTF8
3036 echo ttycharset is UTF-8, the former case-sensitive!
3037 endif
3038 set t1=one t2=one
3039 if [ "${t1}" == "${t2}" ]
3040 echo These two variables are equal
3041 endif
3042 if "$features" =% ,+regex, && "$TERM" =~?case ^xterm.*
3043 echo ..in an X terminal
3044 endif
3045 if [ [ true ] && [ [ "${debug}" != '' ] || \
3046 [ "$verbose" != '' ] ] ]
3047 echo Noisy, noisy
3048 endif
3049 if true && [ -n "$debug" || -n "${verbose}" ]
3050 echo Left associativity, as is known from the shell
3051 endif
3052 ignore (ig) Identical to discard. Superseded by the multiplexer
3054 headerpick.
3055 list Shows the names of all available commands, in command lookup
3057 order. [Option] In conjunction with a set variable verbose ad‐
3058 ditional information will be provided for each command: the ar‐
3059 gument type will be indicated, the documentation string will be
3060 shown, and the set of command flags will show up:
3061 ‘`local'’ command supports the command modifier local.
3063 ‘`vput'’ command supports the command modifier vput.
3064 ‘*!*’ the error number is tracked in !.
3065 ‘needs-box’ whether the command needs an active mailbox, a
3066 folder.
3067 ‘ok:’ indicators whether command is ...
3068 ‘batch/interactive’
3069 usable in interactive or batch mode
3070 (-#).
3071 ‘send-mode’ usable in send mode.
3072 ‘subprocess’ allowed to be used when running in a
3073 subprocess instance, for example
3074 from within a macro that is called
3075 via on-compose-splice.
3076 ‘not ok:’ indicators whether command is not ...
3077 ‘compose mode’ available in Compose mode.
3078 ‘startup’ available during program startup,
3079 like in Resource files.
3080 ‘gabby’ The command produces history-gabby history en‐
3081 tries.
3082 localopts
3084 Enforce change localization of environ (linked) ENVIRONMENT as
3085 well as (global) INTERNAL VARIABLES, meaning that their state
3086 will be reverted to the former one once the “covered scope” is
3087 left. Just like the command modifier local, which provides
3088 block-scope localization for some commands (instead), it can
3089 only be used inside of macro definition blocks introduced by
3090 account or define. The covered scope of an account is left
3091 once a different account is activated, and some macros, notably
3092 folder-hooks, use their own specific notion of covered scope,
3093 here it will be extended until the folder is left again.
3094 This setting stacks up: i.e., if ‘macro1’ enables change local‐
3096 ization and calls ‘macro2’, which explicitly resets localiza‐
3097 tion, then any value changes within ‘macro2’ will still be re‐
3098 verted when the scope of ‘macro1’ is left. (Caveats: if in
3099 this example ‘macro2’ changes to a different account which sets
3100 some variables that are already covered by localizations, their
3101 scope will be extended, and in fact leaving the account will
3102 (thus) restore settings in (likely) global scope which actually
3103 were defined in a local, macro private context!)
3104 This command takes one or two arguments, the optional first one
3106 specifies an attribute that may be one of scope, which refers
3107 to the current scope and is thus the default, call, which
3108 causes any macro that is being called to be started with local‐
3109 ization enabled by default, as well as call-fixate, which (if
3110 enabled) disallows any called macro to turn off localization:
3111 like this it can be ensured that once the current scope regains
3112 control, any changes made in deeper levels have been reverted.
3113 The latter two are mutually exclusive, and neither affects
3114 xcall. The (second) argument is interpreted as a boolean
3115 (string, see INTERNAL VARIABLES) and states whether the given
3116 attribute shall be turned on or off.
3117 define temporary_settings {
3119 set possibly_global_option1
3120 localopts on
3121 set localized_option1
3122 set localized_option2
3123 localopts scope off
3124 set possibly_global_option2
3125 }
3126 Lfollowup, Lreply
3128 (Compose mode) Reply to messages that come in via known (mlist)
3129 or subscribed (mlsubscribe) mailing lists, or pretend to do so
3130 (see Mailing lists): on top of the usual followup and reply,
3131 respectively, functionality this will actively resort and even
3132 remove message recipients in order to generate a message that
3133 is supposed to be sent to a mailing list. For example it will
3134 also implicitly generate a ‘Mail-Followup-To:’ header if that
3135 seems useful, regardless of the setting of the variable
3136 followup-to. For more documentation please refer to On sending
3137 mail, and non-interactive mode.
3138 This may generate the errors ^ERR-DESTADDRREQ if no receiver
3140 has been specified, ^ERR-PERM if some addressees where rejected
3141 by expandaddr, ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a
3142 necessary character set conversion fails, and ^ERR-INVAL for
3143 other errors. It can also fail with errors of Specifying
3144 messages. Occurrence of some of the errors depend on the value
3145 of expandaddr. Any error stops processing of further messages.
3146 Mail (Compose mode) Similar to mail, but saves the message in a file
3148 named after the local part of the first recipient's address
3149 (instead of in record).
3150 mail (Compose mode)(m) Takes a (list of) recipient address(es) as
3152 (an) argument(s), or asks on standard input if none were given;
3153 then collects the remaining mail content and sends it out. Un‐
3154 less the internal variable fullnames is set recipient addresses
3155 will be stripped from comments, names etc. For more documenta‐
3156 tion please refer to On sending mail, and non-interactive mode.
3157 This may generate the errors ^ERR-DESTADDRREQ if no receiver
3159 has been specified, ^ERR-PERM if some addressees where rejected
3160 by expandaddr, ^ERR-NOTSUP if multiple messages have been spec‐
3161 ified, ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a neces‐
3162 sary character set conversion fails, and ^ERR-INVAL for other
3163 errors. It can also fail with errors of Specifying messages.
3164 Occurrence of some of the errors depend on the value of
3165 expandaddr.
3166 mailcap [Option] When used without arguments or if show has been given
3168 the content of The Mailcap files cache is shown, (re-)initial‐
3169 izing it first (as necessary. If the argument is load then the
3170 cache will only be (re-)initialized, and clear will remove its
3171 contents. Note that S-nail will try to load the files only
3172 once, use ‘mailcap clear’ to unlock further attempts. Loading
3173 and parsing can be made more verbose.
3174 mbox (mb) The given message list is to be sent to the secondary
3176 mailbox MBOX when S-nail is quit; this is the default action
3177 unless the variable hold is set. [v15 behaviour may differ]
3178 This command can only be used in a primary system mailbox.
3179 mimetype, unmimetype
3181 [Only new quoting rules] Without arguments the content of the
3182 MIME type cache will displayed; a more verbose listing will be
3183 produced if either of debug or verbose are set. When given ar‐
3184 guments they will be joined, interpreted as shown in The
3185 mime.types files (also see HTML mail and MIME attachments), and
3186 the resulting entry will be added (prepended) to the cache. In
3187 any event MIME type sources are loaded first as necessary –
3188 mimetypes-load-control can be used to fine-tune which sources
3189 are actually loaded.
3190 The latter command deletes all specifications of the given MIME
3192 type, thus ‘? unmimetype text/plain’ will remove all registered
3193 specifications for the MIME type ‘text/plain’. The special
3194 name ‘*’ will discard all existing MIME types, just as will
3195 ‘reset’, but which also reenables cache initialization via
3196 mimetypes-load-control.
3197 mimeview [v15 behaviour may differ] Only available in interactive mode,
3199 this command allows execution of external MIME type handlers
3200 which do not integrate into the normal type output (see HTML
3201 mail and MIME attachments). ([v15 behaviour may differ] No
3202 syntax to directly address parts, this restriction may vanish.)
3203 The user will be asked for each non-text part of the given mes‐
3204 sage in turn whether the registered handler shall be used to
3205 display the part.
3206 mlist, unmlist
3208 [Only new quoting rules] Manage the list of known Mailing
3209 lists; subscriptions are controlled via mlsubscribe. The lat‐
3210 ter command deletes all given arguments, or all at once when
3211 given the asterisk ‘*’. The former shows the list of all cur‐
3212 rently known lists if used without arguments, otherwise the
3213 given arguments will become known. [Option] In the latter
3214 case, arguments which contain any of the magic regular
3215 expression characters will be interpreted as one, possibly
3216 matching many addresses; these will be sequentially matched via
3217 linked lists instead of being looked up in a dictionary.
3218 mlsubscribe, unmlsubscribe
3220 Building upon the command pair mlist, unmlist, but only manag‐
3221 ing the subscription attribute of mailing lists. (The former
3222 will also create not yet existing mailing lists.)
3223 Move Similar to move, but move the messages to a file named after
3225 the local part of the sender of the first message instead of
3226 taking a filename argument; outfolder is inspected to decide on
3227 the actual storage location.
3228 move Acts like copy but marks the messages for deletion if they were
3230 transferred successfully.
3231 More Like more, but also displays header fields which would not pass
3233 the headerpick selection, and all MIME parts. Identical to
3234 Page.
3235 more Invokes the PAGER on the given messages, even in non-interac‐
3237 tive mode and as long as the standard output is a terminal.
3238 Identical to page.
3239 mtaaliases
3241 [Option] When used without arguments or if show has been given
3242 the content of the mta-aliases cache is shown, (re-)initializ‐
3243 ing it first (as necessary). If the argument is load then the
3244 cache will only be (re-)initialized, and clear will remove its
3245 contents.
3246 netrc [Option] When used without arguments, or when the argument was
3248 show the content of the ~/.netrc cache is shown, initializing
3249 it as necessary. If the argument is load then the cache will
3250 be (re)loaded, whereas clear removes it. Loading and parsing
3251 can be made more verbose. lookup will query the cache for the
3252 URL given as the second argument (‘[USER@]HOST’). See
3253 netrc-lookup, netrc-pipe and the section On URL syntax and
3254 credential lookup; the section The .netrc file documents the
3255 file format in detail.
3256 newmail Checks for new mail in the current folder without committing
3258 any changes before. If new mail is present, a message is
3259 shown. If the header variable is set, the headers of each new
3260 message are also shown. This command is not available for all
3261 mailbox types.
3262 next (n) (like ‘+’ or “ENTER”) Goes to the next message in sequence
3264 and types it. With an argument list, types the next matching
3265 message.
3266 New Same as Unread.
3268 new Same as unread.
3270 noop If the current folder is accessed via a network connection, a
3272 “NOOP” command is sent, otherwise no operation is performed.
3273 Page Like page, but also displays header fields which would not pass
3275 the headerpick selection, and all MIME parts. Identical to
3276 More.
3277 page Invokes the PAGER on the given messages, even in non-interac‐
3279 tive mode and as long as the standard output is a terminal.
3280 Identical to more.
3281 Pipe Like pipe but also pipes header fields which would not pass the
3283 headerpick selection, and all parts of MIME
3284 ‘multipart/alternative’ messages.
3285 pipe (pi) Takes an optional message list and shell command (that de‐
3287 faults to cmd), and pipes the messages through the command. If
3288 the page variable is set, every message is followed by a form‐
3289 feed character.
3290 preserve (pre) A synonym for hold.
3292 Print (P) Alias for Type.
3294 print (p) Research UNIX equivalent of type.
3296 quit (q) Terminates the session, saving all undeleted, unsaved mes‐
3298 sages in the current secondary mailbox MBOX, preserving all
3299 messages marked with hold or preserve or never referenced in
3300 the system inbox, and removing all other messages from the
3301 primary system mailbox. If new mail has arrived during the
3302 session, the message “You have new mail” will be shown. If
3303 given while editing a mailbox file with the command line option
3304 -f, then the edit file is rewritten. A return to the shell is
3305 effected, unless the rewrite of edit file fails, in which case
3306 the user can escape with the exit command. The optional status
3307 number argument will be passed through to exit(3). [v15 behav‐
3308 iour may differ] For now it can happen that the given status
3309 will be overwritten, later this will only occur if a later er‐
3310 ror needs to be reported onto an otherwise success indicating
3311 status.
3312 read [Only new quoting rules] Read a line from standard input, or
3314 the channel set active via readctl, and assign the data, which
3315 will be split as indicated by ifs, to the given variables. The
3316 variable names are checked by the same rules as documented for
3317 vput, and the same error codes will be seen in !; the exit sta‐
3318 tus ? indicates the number of bytes read, it will be ‘-1’ with
3319 the error number ! set to ^ERR-BADF in case of I/O errors, or
3320 ^ERR-NONE upon End-Of-File. If there are more fields than
3321 variables, assigns successive fields to the last given vari‐
3322 able. If there are less fields than variables, assigns the
3323 empty string to the remains.
3324 ? read a b c
3326 H e l l o
3327 ? echo "<$a> <$b> <$c>"
3328 <H> <e> <l l o>
3329 ? wysh set ifs=:; read a b c;unset ifs
3330 hey2.0,:"'you ",:world!:mars.:
3331 ? echo $?/$^ERRNAME / <$a><$b><$c>
3332 0/NONE / <hey2.0,><"'you ",><world!:mars.:><><>
3333 readsh [Only new quoting rules] Like read, but splits on shell token
3335 boundaries (see Shell-style argument quoting) rather than at
3336 ifs. [v15 behaviour may differ] Could become a commandalias,
3337 maybe ‘read --tokenize --’.
3338 readall [Only new quoting rules] Read anything from standard input, or
3340 the channel set active via readctl, and assign the data to the
3341 given variable. The variable name is checked by the same rules
3342 as documented for vput, and the same error codes will be seen
3343 in !; the exit status ? indicates the number of bytes read, it
3344 will be ‘-1’ with the error number ! set to ^ERR-BADF in case
3345 of I/O errors, or ^ERR-NONE upon End-Of-File. [v15 behaviour
3346 may differ] The input data length is restricted to 31-bits.
3347 readctl [Only new quoting rules] Manages input channels for read,
3349 readsh and readall, to be used to avoid complicated or imprac‐
3350 ticable code, like calling read from within a macro in non-in‐
3351 teractive mode. Without arguments, or when the first argument
3352 is show, a listing of all known channels is printed. Channels
3353 can otherwise be created, and existing channels can be set ac‐
3354 tive and removed by giving the string used for creation.
3355 The channel name is expected to be a file descriptor number,
3357 or, if parsing the numeric fails, an input file name that un‐
3358 dergoes Filename transformations. For example (this example
3359 requires a modern shell):
3360 $ printf 'echon "hey, "\nread a\nyou\necho $a' |\
3362 s-nail -R#
3363 hey, you
3364 $ LC_ALL=C printf 'echon "hey, "\nread a\necho $a' |\
3365 LC_ALL=C 6<<< 'you' s-nail -R#X'readctl create 6'
3366 hey, you
3367 remove [Only new quoting rules] Removes the named files or directo‐
3369 ries. If a name refers to a mailbox, say a Maildir mailbox,
3370 then a mailbox type specific removal will be performed, delet‐
3371 ing the complete mailbox. In interactive mode the user is
3372 asked for confirmation.
3373 rename [Only new quoting rules] Takes the name of an existing folder
3375 and the name for the new folder and renames the first to the
3376 second one. Filename transformations including shell pathname
3377 wildcard pattern expansions (glob(7)) are performed on both ar‐
3378 guments. Both folders must be of the same type.
3379 Reply, Respond
3381 (Compose mode)(R) Identical to reply except that it replies to
3382 only the sender of each message of the given list, by using the
3383 first message as the template to quote, for the ‘Subject:’
3384 etc.; setting flipr will exchange this command with reply.
3385 reply, respond
3387 (Compose mode)(r) Take a message (list) and group-respond (to
3388 each in turn) by addressing the sender and all recipients, sub‐
3389 ject to fullnames and alternates processing. followup-to,
3390 followup-to-honour, reply-to-honour as well as recipients-in-cc
3391 influence response behaviour. quote as well as
3392 quote-as-attachment configure whether responded-to message
3393 shall be quoted etc., content-description-quote-attachment may
3394 be used. Setting flipr will exchange this command with Reply.
3395 The command Lreply offers special support for replying to mail‐
3396 ing lists. For more documentation please refer to On sending
3397 mail, and non-interactive mode.
3398 This may generate the errors ^ERR-DESTADDRREQ if no receiver
3400 has been specified, or was rejected by expandaddr policy,
3401 ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a necessary
3402 character set conversion fails, and ^ERR-INVAL for other er‐
3403 rors. It can also fail with errors of Specifying messages.
3404 Any error stops processing of further messages.
3405 Resend Like resend, but does not add any header lines. This is not a
3407 way to hide the sender's identity, but useful for sending a
3408 message again to the same recipients.
3409 resend Takes a list of messages and a name, and sends each message to
3411 the given addressee, which is subject to fullnames.
3412 ‘Resent-From:’ and related header fields are prepended to the
3413 new copy of the message. Saving in record is only performed if
3414 record-resent is set. [v15 behaviour may differ](Compose mode)
3415 is not entered, the only supported hooks are on-resend-enter
3416 and on-resend-cleanup.
3417 This may generate the errors ^ERR-DESTADDRREQ if no receiver
3419 has been specified, or was rejected by expandaddr policy,
3420 ^ERR-IO if an I/O error occurs, ^ERR-NOTSUP if a necessary
3421 character set conversion fails, and ^ERR-INVAL for other er‐
3422 rors. It can also fail with errors of Specifying messages.
3423 Any error stops processing of further messages.
3424 retain (ret) Superseded by the multiplexer headerpick.
3426 return Only available inside of a defined macro or an account, this
3428 command returns control of execution to the outer scope. The
3429 two optional parameters are positive decimal numbers and de‐
3430 fault to 0: the first specifies the 32-bit return value (stored
3431 in ? [v15 behaviour may differ] and later extended to 64-bit),
3432 the second the 32-bit error number (stored in !). As docu‐
3433 mented for ? a non-0 exit status may cause the program to exit.
3434 Save (S) Similar to save, but saves the messages in a file named af‐
3436 ter the local part of the sender of the first message instead
3437 of taking a filename argument; outfolder is inspected to decide
3438 on the actual storage location.
3439 save (s) Takes a message list and a filename and appends each mes‐
3441 sage in turn to the end of the file. Filename transformations
3442 including shell pathname wildcard pattern expansions (glob(7))
3443 is performed on the filename. If no filename is given, the
3444 secondary mailbox MBOX is used. The filename in quotes, fol‐
3445 lowed by the generated character count is echoed on the user's
3446 terminal. If editing a primary system mailbox the messages are
3447 marked for deletion. To filter the saved header fields to the
3448 desired subset use the ‘save’ slot of the white- and blacklist‐
3449 ing command headerpick. Also see Copy.
3450 savediscard
3452 [Obsolete] Superseded by the multiplexer headerpick.
3453 saveignore
3455 [Obsolete] Superseded by the multiplexer headerpick.
3456 saveretain
3458 [Obsolete] Superseded by the multiplexer headerpick.
3459 search Takes a message specification (list) and displays a header sum‐
3461 mary of all matching messages, as via headers. This command is
3462 an alias of from. Also see Specifying messages.
3463 seen Takes a message list and marks all messages as having been
3465 read.
3466 set, unset
3468 (se, [Only new quoting rules] uns) The latter command will
3469 delete all given global variables, or only block-scope local
3470 ones if the local command modifier has been used. The former,
3471 when used without arguments, will show all currently known
3472 variables, being more verbose if either of debug or verbose is
3473 set. Remarks: this list mode will not automatically link-in
3474 (known) ENVIRONMENT variables, this only happens for explicit
3475 addressing, examples are varshow, using a variable in an if
3476 condition or a string passed to echo, explicit setting, as well
3477 as some program-internal use cases (look-ups).
3478 Otherwise the given variables (and arguments) are set or ad‐
3480 justed. Arguments are of the form ‘name=value’ (no space be‐
3481 fore or after ‘=’), or plain ‘name’ if there is no value, i.e.,
3482 a boolean variable. If a name begins with ‘no’, as in ‘set
3483 nosave’, the effect is the same as invoking the unset command
3484 with the remaining part of the variable (‘unset save’). [v15
3485 behaviour may differ] In conjunction with the wysh (or local)
3486 command prefix(es) Shell-style argument quoting can be used to
3487 quote arguments as necessary. [v15 behaviour may differ] Oth‐
3488 erwise quotation marks may be placed around any part of the as‐
3489 signment statement to quote blanks or tabs.
3490 When operating in global scope any ‘name’ that is known to map
3492 to an environment variable will automatically cause updates in
3493 the program environment (unsetting a variable in the environ‐
3494 ment requires corresponding system support) — use the command
3495 environ for further environmental control. If the command mod‐
3496 ifier local has been used to enforce local scoping then the
3497 given user variables will be garbage collected when the local
3498 scope is left; for INTERNAL VARIABLES, however, local behaves
3499 the same as if localopts would have been set (temporarily),
3500 which means that changes are inherited by deeper scopes. Also
3501 see varshow and the sections INTERNAL VARIABLES and
3502 ENVIRONMENT.
3503 ? wysh set indentprefix=' -> '
3505 ? wysh set atab=$'' aspace=' ' zero=0
3506 shcodec Apply shell quoting rules to the given raw-data arguments.
3508 Supports vput (see Command modifiers). The first argument
3509 specifies the operation: [+]e[ncode] or d[ecode] cause shell
3510 quoting to be applied to the remains of the line, and expanded
3511 away thereof, respectively. If the former is prefixed with a
3512 plus-sign, the quoted result will not be roundtrip enabled, and
3513 thus can be decoded only in the very same environment that was
3514 used to perform the encode; also see mle-quote-rndtrip. If the
3515 coding operation fails the error number ! is set to
3516 ^ERR-CANCELED, and the unmodified input is used as the result;
3517 the error number may change again due to output or result stor‐
3518 age errors.
3519 shell [Only new quoting rules] (sh) Invokes an interactive version of
3521 the shell, and returns its exit status.
3522 shortcut, unshortcut
3524 [Only new quoting rules] Manage the file- or pathname shortcuts
3525 as documented for folder. The latter command deletes all
3526 shortcuts given as arguments, or all at once when given the as‐
3527 terisk ‘*’. The former shows the list of all currently defined
3528 shortcuts if used without arguments, the target of the given
3529 with a single argument. Otherwise arguments are treated as
3530 pairs of shortcuts and their desired expansion, creating new or
3531 updating already existing ones.
3532 shift [Only new quoting rules] Shift the positional parameter stack
3534 (starting at 1) by the given number (which must be a positive
3535 decimal), or 1 if no argument has been given. It is an error
3536 if the value exceeds the number of positional parameters. If
3537 the given number is 0, no action is performed, successfully.
3538 The stack as such can be managed via vpospar. Note this com‐
3539 mand will fail in account and hook macros unless the positional
3540 parameter stack has been explicitly created in the current con‐
3541 text via vpospar.
3542 show Like type, but performs neither MIME decoding nor decryption,
3544 so that the raw message text is shown.
3545 size (si) Shows the size in characters of each message of the given
3547 message list.
3548 sleep [Only new quoting rules] Sleep for the specified number of sec‐
3550 onds (and optionally milliseconds), by default interruptible.
3551 If a third argument is given the sleep will be uninterruptible,
3552 otherwise the error number ! will be set to ^ERR-INTR if the
3553 sleep has been interrupted. The command will fail and the er‐
3554 ror number will be ^ERR-OVERFLOW if the given duration(s) over‐
3555 flow the time datatype, and ^ERR-INVAL if the given durations
3556 are no valid integers.
3557 sort, unsort
3559 The latter command disables sorted or threaded mode, returns to
3560 normal message order and, if the header variable is set, dis‐
3561 plays a header summary. The former command shows the current
3562 sorting criterion when used without an argument, but creates a
3563 sorted representation of the current folder otherwise, and
3564 changes the next command and the addressing modes such that
3565 they refer to messages in the sorted order. Message numbers
3566 are the same as in regular mode. If the header variable is
3567 set, a header summary in the new order is also displayed. Au‐
3568 tomatic folder sorting can be enabled by setting the autosort
3569 variable, as in ‘set autosort=thread’. Possible sorting crite‐
3570 rions are:
3571 date Sort the messages by their ‘Date:’ field, that is by
3573 the time they were sent.
3574 from Sort messages by the value of their ‘From:’ field,
3575 that is by the address of the sender. If the showname
3576 variable is set, the sender's real name (if any) is
3577 used.
3578 size Sort the messages by their size.
3579 spam [Option] Sort the message by their spam score, as has
3580 been classified by spamrate.
3581 status Sort the messages by their message status.
3582 subject Sort the messages by their subject.
3583 thread Create a threaded display.
3584 to Sort messages by the value of their ‘To:’ field, that
3585 is by the address of the recipient. If the showname
3586 variable is set, the recipient's real name (if any) is
3587 used.
3588 source [Only new quoting rules] (so) The source command reads commands
3590 from the given file. Filename transformations will be applied.
3591 If the given expanded argument ends with a vertical bar ‘|’
3592 then the argument will instead be interpreted as a shell com‐
3593 mand and S-nail will read the output generated by it. Depen‐
3594 dent on the settings of posix and errexit, and also dependent
3595 on whether the command modifier ignerr had been used, encoun‐
3596 tering errors will stop sourcing of the given input. [v15 be‐
3597 haviour may differ] Note that source cannot be used from within
3598 macros that execute as folder-hooks or accounts, i.e., it can
3599 only be called from macros that were called.
3600 source_if
3602 [Only new quoting rules] The difference to source (beside not
3603 supporting pipe syntax aka shell command input) is that this
3604 command will not generate an error nor warn if the given file
3605 argument cannot be opened successfully.
3606 spamclear
3608 [Option] Takes a list of messages and clears their ‘is-spam’
3609 flag.
3610 spamforget
3612 [Option] Takes a list of messages and causes the spam-interface
3613 to forget it has ever used them to train its Bayesian filter.
3614 Unless otherwise noted the ‘is-spam’ flag of the message is in‐
3615 spected to chose whether a message shall be forgotten to be
3616 “ham” or “spam”.
3617 spamham [Option] Takes a list of messages and informs the Bayesian fil‐
3619 ter of the spam-interface that they are “ham”. This also
3620 clears the ‘is-spam’ flag of the messages in question.
3621 spamrate [Option] Takes a list of messages and rates them using the con‐
3623 figured spam-interface, without modifying the messages, but
3624 setting their ‘is-spam’ flag as appropriate; because the spam
3625 rating headers are lost the rate will be forgotten once the
3626 mailbox is left. Refer to the manual section Handling spam for
3627 the complete picture of spam handling in S-nail.
3628 spamset [Option] Takes a list of messages and sets their ‘is-spam’
3630 flag.
3631 spamspam [Option] Takes a list of messages and informs the Bayesian fil‐
3633 ter of the spam-interface that they are “spam”. This also sets
3634 the ‘is-spam’ flag of the messages in question.
3635 thread [Obsolete] The same as ‘sort thread’ (consider using a
3637 ‘commandalias’ as necessary).
3638 tls [Only new quoting rules] TLS information and management command
3640 multiplexer to aid in Encrypted network communication, mostly
3641 available only if the term ‘,+sockets,’ is included in
3642 features. Commands support vput if so documented (see Command
3643 modifiers). The result that is shown in case of errors is al‐
3644 ways the empty string, errors can be identified via the error
3645 number !. For example, string length overflows are caught and
3646 set ! to ^ERR-OVERFLOW. The TLS configuration is honoured, es‐
3647 pecially tls-verify.
3648 ? vput tls result fingerprint pop3s://ex.am.ple
3650 ? echo $?/$!/$^ERRNAME: $result
3651 certchain Show the complete verified peer certificate chain.
3653 Includes informational fields in conjunction with
3654 verbose.
3655 certificate Show only the peer certificate, without any sign‐
3657 ers. Includes informational fields in conjunction
3658 with verbose.
3659 fingerprint Show the tls-fingerprint-digested fingerprint of
3661 the certificate of the given HOST (‘server:port’,
3662 where the port defaults to the HTTPS port, 443).
3663 tls-fingerprint is actively ignored for the runtime
3664 of this command.
3665 Top Like top but always uses the headerpick ‘type’ slot for white-
3667 and blacklisting header fields.
3668 top (to) Takes a message list and types out the first toplines
3670 lines of each message on the user's terminal. Unless a special
3671 selection has been established for the ‘top’ slot of the
3672 headerpick command, the only header fields that are displayed
3673 are ‘From:’, ‘To:’, ‘Cc:’, and ‘Subject:’. Top will always use
3674 the ‘type’ headerpick selection instead. It is possible to ap‐
3675 ply compression to what is displayed by setting topsqueeze.
3676 Messages are decrypted and converted to the terminal character
3677 set if necessary.
3678 touch (tou) Takes a message list and marks the messages for saving in
3680 the secondary mailbox MBOX. S-nail deviates from the POSIX
3681 standard with this command, as a following next command will
3682 display the following message instead of the current one.
3683 Type (T) Like type but also displays header fields which would not
3685 pass the headerpick selection, and all visualizable parts of
3686 MIME ‘multipart/alternative’ messages.
3687 type (t) Takes a message list and types out each message on the
3689 user's terminal. The display of message headers is selectable
3690 via headerpick. For MIME multipart messages, all parts with a
3691 content type of ‘text’, all parts which have a registered MIME
3692 type handler (see HTML mail and MIME attachments) which pro‐
3693 duces plain text output, and all ‘message’ parts are shown,
3694 others are hidden except for their headers. Messages are de‐
3695 crypted and converted to the terminal character set if neces‐
3696 sary. The command mimeview can be used to display parts which
3697 are not displayable as plain text.
3698 unaccount
3700 See account.
3701 unalias (una) See alias.
3703 unanswered
3705 See answered.
3706 unbind See bind.
3708 uncollapse
3710 See collapse.
3711 uncolour See colour.
3713 undefine See define.
3715 undelete See delete.
3717 undraft See draft.
3719 unflag See flag.
3721 unfwdignore
3723 [Obsolete] Superseded by the multiplexer headerpick.
3724 unfwdretain
3726 [Obsolete] Superseded by the multiplexer headerpick.
3727 unignore Superseded by the multiplexer headerpick.
3729 unmimetype
3731 See mimetype.
3732 unmlist See mlist.
3734 unmlsubscribe
3736 See mlsubscribe.
3737 Unread Same as unread.
3739 unread Takes a message list and marks each message as not having been
3741 read.
3742 unretain Superseded by the multiplexer headerpick.
3744 unsaveignore
3746 [Obsolete] Superseded by the multiplexer headerpick.
3747 unsaveretain
3749 [Obsolete] Superseded by the multiplexer headerpick.
3750 unset [Only new quoting rules] (uns) See set.
3752 unshortcut
3754 See shortcut.
3755 unsort See short.
3757 unthread [Obsolete] Same as unsort.
3759 urlcodec Perform URL percent codec operations on the raw-data argument,
3761 rather according to RFC 3986. The first argument specifies the
3762 operation: e[ncode] or d[ecode] perform plain URL percent en-
3763 and decoding, respectively. p[ath]enc[ode] and p[ath]dec[ode]
3764 perform a slightly modified operation which should be better
3765 for pathnames: it does not allow a tilde ‘~’, and will neither
3766 accept hyphen-minus ‘-’ nor dot ‘’. as an initial character.
3767 The remains of the line form the URL data which is to be con‐
3768 verted. This is a character set agnostic operation, and it may
3769 thus decode bytes which are invalid in the current ttycharset.
3770 Supports vput (see Command modifiers), and manages the error
3772 number !. If the coding operation fails the error number ! is
3773 set to ^ERR-CANCELED, and the unmodified input is used as the
3774 result; the error number may change again due to output or re‐
3775 sult storage errors. [v15 behaviour may differ] This command
3776 does not know about URLs beside what is documented. (vexpr of‐
3777 fers a makeprint subcommand, shall the URL be displayed.)
3778 varshow [Only new quoting rules] This command produces the same output
3780 as the listing mode of set, including verboseity adjustments,
3781 but only for the given variables.
3782 verify [Option] Takes a message list and verifies each message. If a
3784 message is not a S/MIME signed message, verification will fail
3785 for it. The verification process checks if the message was
3786 signed using a valid certificate, if the message sender's email
3787 address matches one of those contained within the certificate,
3788 and if the message content has been altered.
3789 version Shows the version and features of S-nail, optionally in a more
3791 verbose form which also includes the build and running system
3792 environment. This command supports vput (see Command
3793 modifiers).
3794 vexpr [Only new quoting rules] A multiplexer command which offers
3796 signed 64-bit numeric calculations, as well as other, mostly
3797 string-based operations. C-style byte string operations are
3798 available via csop. The first argument defines the number,
3799 type, and meaning of the remaining arguments. An empty number
3800 argument is treated as 0. Supports vput (see Command
3801 modifiers). The result shown in case of errors is ‘-1’ for us‐
3802 age errors and numeric operations, the empty string otherwise;
3803 “soft” errors, like when a search operation failed, will also
3804 set the ! error number to ^ERR-NODATA. Except when otherwise
3805 noted numeric arguments are parsed as signed 64-bit numbers,
3806 and errors will be reported in the error number ! as the nu‐
3807 meric error ^ERR-RANGE.
3808 Numeric operations work on one or two signed 64-bit integers.
3810 Numbers prefixed with ‘0x’ or ‘0X’ are interpreted as hexadeci‐
3811 mal (base 16) numbers, whereas ‘0’ indicates octal (base 8),
3812 and ‘0b’ as well as ‘0B’ denote binary (base 2) numbers. It is
3813 possible to use any base in between 2 and 36, inclusive, with
3814 the ‘BASE#number’ notation, where the base is given as an un‐
3815 signed decimal number, so ‘16#AFFE’ is a different way of spec‐
3816 ifying a hexadecimal number. Unsigned interpretation of a num‐
3817 ber can be enforced by prefixing an ‘u’ (case-insensitively),
3818 as in ‘u-110’; this is not necessary for power-of-two bases (2,
3819 4, 8, 16 and 32), which will be interpreted as unsigned by de‐
3820 fault, but it still makes a difference regarding overflow de‐
3821 tection and overflow constant. It is possible to enforce
3822 signed interpretation by (instead) prefixing a ‘s’ (case-insen‐
3823 sitively). The number sign notation uses a permissive parse
3824 mode and as such supports complicated conditions out of the
3825 box:
3826 ? wysh set ifs=:;read i;unset ifs;echo $i;vexpr pb 2 10#$i
3828 -009
3829 < -009>
3830 0b1001
3831 One integer is expected by assignment (equals sign ‘=’), which
3833 does nothing but parsing the argument, thus detecting validity
3834 and possible overflow conditions, unary not (tilde ‘~’), which
3835 creates the bitwise complement, and unary plus and minus. Two
3836 integers are used by addition (plus sign ‘+’), subtraction (hy‐
3837 phen-minus ‘-’), multiplication (asterisk ‘*’), division
3838 (solidus ‘/’) and modulo (percent sign ‘%’), as well as for the
3839 bitwise operators logical or (vertical bar ‘|’, to be quoted) ,
3840 bitwise and (ampersand ‘&’, to be quoted) , bitwise xor (cir‐
3841 cumflex ‘^’), the bitwise signed left- and right shifts (‘<<’,
3842 ‘>>’), as well as for the unsigned right shift ‘>>>’.
3843 Another numeric operation is pbase, which takes a number base
3845 in between 2 and 36, inclusive, and will act on the second num‐
3846 ber given just the same as what equals sign ‘=’ does, but the
3847 number result will be formatted in the base given, as a signed
3848 64-bit number unless unsigned interpretation of the input num‐
3849 ber had been forced (with an u prefix).
3850 Numeric operations support a saturated mode via the question
3852 mark ‘?’ modifier suffix; the keyword ‘saturated’ is optional,
3853 ‘+?’, ‘+?satu’, and ‘+?saturated’ are therefore identical. In
3854 saturated mode overflow errors and division and modulo by zero
3855 are no longer reported via the exit status, but the result will
3856 linger at the minimum or maximum possible value, instead of
3857 overflowing (or trapping). This is true also for the argument
3858 parse step. For the bitwise shifts, the saturated maximum is
3859 63. Any caught overflow will be reported via the error number
3860 ! as ^ERR-OVERFLOW.
3861 ? vput vexpr res -? +1 -9223372036854775808
3863 ? echo $?/$!/$^ERRNAME:$res
3864 0/75/OVERFLOW:-9223372036854775808
3865 Character set agnostic string functions have no notion of lo‐
3867 cale settings and character sets.
3868 date-utc Outputs the current date and time in UTC (Coordinated
3870 Universal Time) with values named such that ‘vput
3871 vexpr x date-utc; eval wysh set $x’ creates accessi‐
3872 ble variables.
3873 date-stamp-utc Outputs a RFC 3339 internet date/time format of
3875 UTC.
3876 epoch The seconds and nanoseconds since the Unix epoch
3878 (1970-01-01T00:00:00) named ‘epoch_sec’ and
3879 ‘epoch_nsec’ such that ‘vput vexpr x epoch; eval wysh
3880 set $x’ creates accessible variables.
3881 file-expand Performs the usual Filename transformations on its
3883 argument.
3884 file-stat, file-lstat Perform the usual Filename
3886 transformations on the argument, then call stat(2)
3887 and lstat(2), respectively, and output values such
3888 that ‘vput vexpr x file-stat FILE; eval wysh set $x’
3889 creates accessible variables. The variable ‘st_type’
3890 uses solidus ‘/’ to denote directories, commercial at
3891 ‘@’ for links, number sign ‘#’ for block devices,
3892 percent sign ‘%’ for for character devices, vertical
3893 bar ‘|’ for FIFOs, equal sign ‘=’ for sockets, and
3894 the period ‘.’ for the rest.
3895 random Generates a random string of the given length, or of
3897 PATH_MAX bytes (a constant from /usr/include) if the
3898 value 0 is given; the random string will be base64url
3899 encoded according to RFC 4648, and thus be usable as
3900 a (portable) filename.
3901 String operations work, sufficient support provided, according
3903 to the active user's locale encoding and character set (see
3904 Character sets). Where the question mark ‘?’ modifier suffix
3905 is supported, a case-insensitive operation mode is available;
3906 the keyword ‘case’ is optional, ‘regex?’ and ‘regex?case’ are
3907 therefore identical.
3908 makeprint (One-way) Converts the argument to something safely
3910 printable on the terminal.
3911 regex [Option] A string operation that will try to match
3913 the first argument with the regular expression given
3914 as the second argument. ‘?’ modifier suffix is sup‐
3915 ported. If the optional third argument has been
3916 given then instead of showing the match offset a re‐
3917 placement operation is performed: the third argument
3918 is treated as if specified within dollar-single-quote
3919 (see Shell-style argument quoting), and any occur‐
3920 rence of a positional parameter, for example 0, 1
3921 etc. is replaced with the according match group of
3922 the regular expression:
3923 ? vput vexpr res regex bananarama \
3925 (.*)NanA(.*) '\${1}au\$2'
3926 ? echo $?/$!/$^ERRNAME:$res:
3927 1/61/NODATA::
3928 ? vput vexpr res regex?case bananarama \
3929 (.*)NanA(.*) '\${1}uauf\$2'
3930 ? echo $?/$!/$^ERRNAME:$res:
3931 0/0/NONE:bauauframa:
3932 vpospar [Only new quoting rules] Manage the positional parameter stack
3934 (see 1, #, *, @ as well as shift). If the first argument is
3935 ‘clear’, then the positional parameter stack of the current
3936 context, or the global one, if there is none, is cleared. If
3937 it is ‘set’, then the remaining arguments will be used to
3938 (re)create the stack, if the parameter stack size limit is ex‐
3939 cessed an ^ERR-OVERFLOW error will occur.
3940 If the first argument is ‘quote’, a round-trip capable repre‐
3942 sentation of the stack contents is created, with each quoted
3943 parameter separated from each other with the first character of
3944 ifs, and followed by the first character of if-ws, if that is
3945 not empty and not identical to the first. If that results in
3946 no separation at all a space character is used. This mode sup‐
3947 ports vput (see Command modifiers). I.e., the subcommands
3948 ‘set’ and ‘quote’ can be used (in conjunction with eval) to
3949 (re)create an argument stack from and to a single variable
3950 losslessly.
3951 ? vpospar set hey, "'you ", world!
3953 ? echo $#: <${1}><${2}><${3}>
3954 ? vput vpospar x quote
3955 ? vpospar clear
3956 ? echo $#: <${1}><${2}><${3}>
3957 ? eval vpospar set ${x}
3958 ? echo $#: <${1}><${2}><${3}>
3959 visual (v) Takes a message list and invokes the VISUAL display editor
3961 on each message. Modified contents are discarded unless the
3962 writebackedited variable is set, and are not used unless the
3963 mailbox can be written to and the editor returns a successful
3964 exit status. edit can be used instead for a less display ori‐
3965 ented editor.
3966 write (w) For conventional messages the body without all headers is
3968 written. The original message is never marked for deletion in
3969 the originating mail folder. The output is decrypted and con‐
3970 verted to its native format as necessary. If the output file
3971 exists, the text is appended. If a message is in MIME multi‐
3972 part format its first part is written to the specified file as
3973 for conventional messages, handling of the remains depends on
3974 the execution mode. No special handling of compressed files is
3975 performed.
3976 In interactive mode the user is consecutively asked for the
3978 filenames of the processed parts. For convenience saving of
3979 each part may be skipped by giving an empty value, the same re‐
3980 sult as writing it to /dev/null. Shell piping the part content
3981 by specifying a leading vertical bar ‘|’ character for the
3982 filename is supported. Other user input undergoes the usual
3983 Filename transformations, including shell pathname wildcard
3984 pattern expansions (glob(7)) and shell variable expansion for
3985 the message as such, not the individual parts, and contents of
3986 the destination file are overwritten if the file previously ex‐
3987 isted. Character set conversion to ttycharset is performed
3988 when saving text data.
3989 [v15 behaviour may differ] In non-interactive mode any part
3991 which does not specify a filename is ignored, and suspicious
3992 parts of filenames of the remaining parts are URL percent en‐
3993 coded (as via urlcodec) to prevent injection of malicious char‐
3994 acter sequences, resulting in a filename that will be written
3995 into the current directory. Existing files will not be over‐
3996 written, instead the part number or a dot are appended after a
3997 number sign ‘#’ to the name until file creation succeeds (or
3998 fails due to other reasons).
3999 xcall [Only new quoting rules] The sole difference to call is that
4001 the new macro is executed in place of the current one, which
4002 will not regain control: all resources of the current macro
4003 will be released first. This implies that any setting covered
4004 by localopts will be forgotten and covered variables will be‐
4005 come cleaned up. If this command is not used from within a
4006 called macro it will silently be (a more expensive variant of)
4007 call.
4008 xit (x) A synonym for exit.
4010 z [Only new quoting rules] S-nail presents message headers in
4012 screenfuls as described under the headers command. Without ar‐
4013 guments this command scrolls to the next window of messages,
4014 likewise if the argument is ‘+’. An argument of ‘-’ scrolls to
4015 the last, ‘^’ scrolls to the first, and ‘$’ to the last screen
4016 of messages. A number argument prefixed by ‘+’ or ‘-’ indi‐
4017 cates that the window is calculated in relation to the current
4018 position, and a number without a prefix specifies an absolute
4019 position.
4020 Z [Only new quoting rules] Similar to z, but scrolls to the next
4022 or previous window that contains at least one ‘new’ or flagged
4023 message.
4024
4026 Command escapes are available in Compose mode during interactive usage,
4027 when explicitly requested via -~, and in batch mode (-#). They perform
4028 special functions, like editing headers of the message being composed,
4029 calling normal COMMANDS, yielding a shell, etc. Command escapes are only
4030 recognized at the beginning of lines, and consist of an escape followed
4031 by a command character. The default escape character is the tilde ‘~’.
4032 Unless otherwise documented command escapes ensure proper updates of the
4034 error number ! and the exit status ?. The variable errexit controls
4035 whether a failed operation errors out message compose mode and causes
4036 program exit. Escapes may be prefixed by none to multiple single charac‐
4037 ter command modifiers, interspersed whitespace is ignored:
4038 • An effect equivalent to the command modifier ignerr can be achieved
4040 with hyphen-minus ‘-’, overriding errexit.
4041 • The modifier dollar ‘$’ evaluates the remains of the line; also see
4043 Shell-style argument quoting. [v15 behaviour may differ] For now the
4044 entire input line is evaluated as a whole; to avoid that control op‐
4045 erators like semicolon ; are interpreted unintentionally, they must
4046 be quoted.
4047 Addition of the command line to the [Option]al history can be prevented
4049 by placing whitespace directly after escape. The [Option]al key bindings
4050 support a compose mode specific context. The following command escapes
4051 are supported:
4052 ~~ string
4054 Insert the string of text in the message prefaced by a single
4055 ‘~’. (If the escape character has been changed, that character
4056 must be doubled instead.)
4057 ~! command
4059 Execute the indicated shell command which follows, replacing
4060 unescaped exclamation marks with the previously executed com‐
4061 mand if the internal variable bang is set, then return to the
4062 message.
4063 ~. End compose mode and send the message. The hooks
4065 on-compose-splice-shell and on-compose-splice, in order, will
4066 be called when set, after which, in interactive mode askatend
4067 (leading to askcc, askbcc) and askattach will be checked as
4068 well as asksend, after which a set on-compose-leave hook will
4069 be called, autocc and autobcc will be joined in if set, finally
4070 a given message-inject-tail will be incorporated, after which
4071 the compose mode is left.
4072 ~: S-nail-command or ~_ S-nail-command
4074 Can be used to execute COMMANDS (which are allowed in compose
4075 mode).
4076 ~< filename
4078 Identical to ~r.
4079 ~<! command
4081 command is executed using the shell. Its standard output is
4082 inserted into the message.
4083 ~? [Option] Write a summary of command escapes.
4085 ~@ [filename...]
4087 Append or edit the list of attachments. Does not manage the
4088 error number ! and the exit status ? (please use ~^ if error
4089 handling is necessary). The append mode expects a list of
4090 filename arguments as shell tokens (see Shell-style argument
4091 quoting; token-separating commas are ignored, too), to be in‐
4092 terpreted as documented for the command line option -a, with
4093 the message number exception as below.
4094 Without filename arguments the attachment list is edited, entry
4096 by entry; if a filename is left empty, that attachment is
4097 deleted from the list; once the end of the list is reached ei‐
4098 ther new attachments may be entered or the session can be quit
4099 by committing an empty “new” attachment. In non-interactive
4100 mode or in batch mode (-#) the list of attachments is effec‐
4101 tively not edited but instead recreated; again, an empty input
4102 ends list creation.
4103 For all modes, if a given filename solely consists of the num‐
4105 ber sign ‘#’ followed by either a valid message number of the
4106 currently active mailbox, or by a period ‘.’, referring to the
4107 current message of the active mailbox, the so-called “dot”,
4108 then the given message is attached as a ‘message/rfc822’ MIME
4109 message part. The number sign must be quoted to avoid misin‐
4110 terpretation as a shell comment character.
4111 ~| command
4113 Pipe the message text through the specified filter command. If
4114 the command gives no output or terminates abnormally, retain
4115 the original text of the message. The command fmt(1) is often
4116 used as a rejustifying filter.
4117 If the first character of the command is a vertical bar, then
4119 the entire message including header fields is subject to the
4120 filter command, so ‘~|| echo Fcc: /tmp/test; cat’ will prepend
4121 a file-carbon-copy message header. Also see ~e, ~v.
4122 ~^ cmd [subcmd [arg3 [arg4]]]
4124 Inspect and modify the message using the semantics of digmsg,
4125 therefore arguments are evaluated according to Shell-style
4126 argument quoting. Error number ! and exit status ? are not
4127 managed: errors are handled via the protocol, and hard errors
4128 like I/O failures cannot be handled.
4129 The protocol consists of command lines followed by (a) response
4131 line(s). The first field of the response line represents a
4132 status code which specifies whether a command was successful or
4133 not, whether result data is to be expected, and if, the format
4134 of the result data. Response data will be shell quoted as nec‐
4135 essary for consumption by readsh, or eval and vpospar, to name
4136 a few. Error status code lines may optionally contain addi‐
4137 tional context:
4138 ‘210’ Status ok; the remains of the line are the result.
4140 ‘211’ Status ok; the rest of the line is optionally used
4141 for more status. What follows are lines of result
4142 addresses, terminated by an empty line. All the in‐
4143 put, including the empty line, must be consumed be‐
4144 fore further commands can be issued. Address lines
4145 consist of two token, first the plain network ad‐
4146 dress, e.g., ‘bob@exam.ple’, followed by the (quoted)
4147 full address as known: ‘'(Lovely) Bob
4148 <bob@exam.ple>'’. Non-network addresses use the
4149 first field to indicate the type (hyphen-minus ‘-’
4150 for files, vertical bar ‘|’ for pipes, and number
4151 sign ‘#’ for names which will undergo alias process‐
4152 ing) instead, the actual value will be in the second
4153 field.
4154 ‘212’ Status ok; the rest of the line is optionally used
4155 for more status. What follows are lines of furtherly
4156 unspecified (quoted) string content, terminated by an
4157 empty line. All the input, including the empty line,
4158 must be consumed before further commands can be is‐
4159 sued.
4160 ‘500’ Syntax error; invalid command.
4161 ‘501’ Syntax error or otherwise invalid parameters or argu‐
4162 ments.
4163 ‘505’ Error: an argument fails verification. For example
4164 an invalid address has been specified (also see
4165 expandaddr), or an attempt was made to modify any‐
4166 thing in S-nail's own namespace, or a modifying sub‐
4167 command has been used on a read-only message.
4168 ‘506’ Error: an otherwise valid argument is rendered in‐
4169 valid due to context. For example, a second address
4170 is added to a header which may consist of a single
4171 address only.
4172 If a command indicates failure then the message will have re‐
4174 mained unmodified. Most commands can fail with ‘500’ if re‐
4175 quired arguments are missing, or excessive arguments have been
4176 given (false command usage). ([v15 behaviour may differ] The
4177 latter does not yet occur regularly, because as stated in
4178 Shell-style argument quoting our argument parser is not yet
4179 smart enough to work on subcommand base; for example one might
4180 get excess argument error for a three argument subcommand that
4181 receives four arguments, but not for a four argument subcommand
4182 which receives six arguments: here excess will be joined.) The
4183 following (case-insensitive) commands are supported:
4184 attachment This command allows listing, removal and addition of
4186 message attachments. The second argument specifies
4187 the subcommand to apply, one of:
4188 attribute This uses the same search mechanism as de‐
4190 scribed for remove and prints any known at‐
4191 tributes of the first found attachment via
4192 ‘212’ upon success or ‘501’ if no such at‐
4193 tachment can be found. The attributes are
4194 written as lines with a keyword and a value
4195 token.
4196 attribute-at This uses the same search mechanism as
4198 described for remove-at and is otherwise
4199 identical to attribute.
4200 attribute-set This uses the same search mechanism as
4202 described for remove, and will set the at‐
4203 tribute given as the fourth to the value
4204 given as the fifth token argument. If the
4205 value is an empty token, then the given at‐
4206 tribute is removed, or reset to a default
4207 value if existence of the attribute is cru‐
4208 cial.
4209 It returns via ‘210’ upon success, with the
4211 index of the found attachment following,
4212 ‘505’ for message attachments or if the
4213 given keyword is invalid, and ‘501’ if no
4214 such attachment can be found. The following
4215 keywords may be used (case-insensitively):
4216 ‘filename’ Sets the filename of the MIME
4218 part, i.e., the name that is
4219 used for display and when (sug‐
4220 gesting a name for) saving (pur‐
4221 poses).
4222 ‘content-description’ Associate some de‐
4223 scriptive information to the at‐
4224 tachment's content, used in
4225 favour of the plain filename by
4226 some MUAs.
4227 ‘content-id’ May be used for uniquely iden‐
4228 tifying MIME entities in several
4229 contexts; this expects a special
4230 reference address format as de‐
4231 fined in RFC 2045 and generates
4232 a ‘505’ upon address content
4233 verification failure.
4234 ‘content-type’ Defines the media type/sub‐
4235 type of the part, which is man‐
4236 aged automatically, but can be
4237 overwritten.
4238 ‘content-disposition’ Automatically set to
4239 the string ‘attachment’.
4240 attribute-set-at This uses the same search mechanism
4242 as described for remove-at and is otherwise
4243 identical to attribute-set.
4244 insert Adds the attachment given as the third argu‐
4246 ment, specified exactly as documented for
4247 the command line option -a, and supporting
4248 the message number extension as documented
4249 for ~@. This reports ‘210’ upon success,
4250 with the index of the new attachment follow‐
4251 ing, ‘505’ if the given file cannot be
4252 opened, ‘506’ if an on-the-fly performed
4253 character set conversion fails, otherwise
4254 ‘501’ is reported; this is also reported if
4255 character set conversion is requested but
4256 not available.
4257 list List all attachments via ‘212’, or report
4259 ‘501’ if no attachments exist. This command
4260 is the default command of attachment if no
4261 second argument has been given.
4262 remove This will remove the attachment given as the
4264 third argument, and report ‘210’ upon suc‐
4265 cess or ‘501’ if no such attachment can be
4266 found. If there exists any path component
4267 in the given argument, then an exact match
4268 of the path which has been used to create
4269 the attachment is used directly, but if only
4270 the basename of that path matches then all
4271 attachments are traversed to find an exact
4272 match first, and the removal occurs after‐
4273 wards; if multiple basenames match, a ‘506’
4274 error occurs. Message attachments are
4275 treated as absolute pathnames.
4276 If no path component exists in the given ar‐
4278 gument, then all attachments will be
4279 searched for ‘filename=’ parameter matches
4280 as well as for matches of the basename of
4281 the path which has been used when the at‐
4282 tachment has been created; multiple matches
4283 result in a ‘506’.
4284 remove-at This will interpret the third argument as a
4286 number and remove the attachment at that
4287 list position (counting from one!), report‐
4288 ing ‘210’ upon success or ‘505’ if the argu‐
4289 ment is not a number or ‘501’ if no such at‐
4290 tachment exists.
4291 header This command allows listing, inspection, and editing
4293 of message headers. Header name case is not normal‐
4294 ized, so that case-insensitive comparison should be
4295 used when matching names. The second argument speci‐
4296 fies the subcommand to apply, one of:
4297 insert Create a new or an additional instance of
4299 the header given in the third argument, with
4300 the header body content as given in the
4301 fourth token. It may return ‘501’ if the
4302 third argument specifies a free-form header
4303 field name that is invalid, or if body con‐
4304 tent extraction fails to succeed, ‘505’ if
4305 any extracted address does not pass syntax
4306 and/or security checks or on S-nail name‐
4307 space violations, and ‘506’ to indicate pre‐
4308 vention of excessing a single-instance
4309 header — note that ‘Subject:’ can be ap‐
4310 pended to (a space separator will be added
4311 automatically first). ‘To:’, ‘Cc:’ and
4312 ‘Bcc:’ support the ‘?single’ modifier to en‐
4313 force treatment as a single addressee, for
4314 example ‘header insert To?single: 'exa,
4315 <m@ple>'’; the word ‘single’ is optional.
4316 ‘210’ is returned upon success, followed by
4318 the name of the header and the list position
4319 of the newly inserted instance. The list
4320 position is always 1 for single-instance
4321 header fields. All free-form header fields
4322 are managed in a single list; also see
4323 customhdr.
4324 list Without a third argument a list of all yet
4326 existing headers is given via ‘210’; this
4327 command is the default command of header if
4328 no second argument has been given. A third
4329 argument restricts output to the given
4330 header only, which may fail with ‘501’ if no
4331 such field is defined.
4332 remove This will remove all instances of the header
4334 given as the third argument, reporting ‘210’
4335 upon success, ‘501’ if no such header can be
4336 found, and ‘505’ on S-nail namespace viola‐
4337 tions.
4338 remove-at This will remove from the header given as
4340 the third argument the instance at the list
4341 position (counting from one!) given with the
4342 fourth argument, reporting ‘210’ upon suc‐
4343 cess or ‘505’ if the list position argument
4344 is not a number or on S-nail namespace vio‐
4345 lations, and ‘501’ if no such header in‐
4346 stance exists.
4347 show Shows the content of the header given as the
4349 third argument. Dependent on the header
4350 type this may respond with ‘211’ or ‘212’;
4351 any failure results in ‘501’.
4352 In compose-mode read-only access to optional pseudo
4354 headers in the S-nail private namespace is available:
4355 ‘Mailx-Command:’
4357 The name of the command that generates the
4358 message, one of ‘forward’, ‘Lreply’, ‘mail’,
4359 ‘Reply’, ‘reply’, ‘resend’. This pseudo
4360 header always exists (in compose-mode).
4361 ‘Mailx-Raw-To:’
4362 ‘Mailx-Raw-Cc:’
4363 ‘Mailx-Raw-Bcc:’
4364 Represent the frozen initial state of these
4365 headers before any transformation (alias,
4366 alternates, recipients-in-cc etc.) took
4367 place.
4368 ‘Mailx-Orig-Sender:’
4369 ‘Mailx-Orig-From:’
4370 ‘Mailx-Orig-To:’
4371 ‘Mailx-Orig-Cc:’
4372 ‘Mailx-Orig-Bcc:’
4373 The values of said headers of the original
4374 message which has been addressed by any of
4375 reply, forward, resend. The sender field is
4376 special as it is filled in with the sole
4377 sender according to RFC 5322 rules, it may
4378 thus be equal to the from field.
4379 help, ? Show an abstract of the above commands via ‘211’.
4381 version This command will print the protocol version via
4383 ‘210’.
4384 ~A The same as ‘~i Sign’.
4386 ~a The same as ‘~i sign’.
4388 ~b name ...
4390 Add the given names to the list of blind carbon copy recipi‐
4391 ents.
4392 ~c name ...
4394 Add the given names to the list of carbon copy recipients.
4395 ~d Read the file specified by the DEAD variable into the message.
4397 ~e Invoke the text EDITOR on the message collected so far, then
4399 return to compose mode. ~v can be used for a more display ori‐
4400 ented editor, and ~|| offers a pipe-based editing approach.
4401 ~F messages
4403 Read the named messages into the message being sent, including
4404 all message headers and MIME parts, and honouring
4405 forward-add-cc as well as forward-inject-head and
4406 forward-inject-tail. If no messages are specified, read in the
4407 current message, the “dot”.
4408 ~f messages
4410 Read the named messages into the message being sent. If no
4411 messages are specified, read in the current message, the “dot”.
4412 Strips down the list of header fields according to the
4413 ‘forward’ (with posix: ‘type’) white- and blacklist selection
4414 of headerpick, and honours forward-add-cc as well as
4415 forward-inject-head and forward-inject-tail. For MIME multi‐
4416 part messages, only the first displayable part is included.
4417 ~H In interactive mode, edit the message header fields ‘From:’,
4419 ‘Reply-To:’ and ‘Sender:’ by typing each one in turn and allow‐
4420 ing the user to edit the field. The default values for these
4421 fields originate from the from, reply-to and sender variables.
4422 In non-interactive mode this sets ^ERR-NOTTY.
4423 ~h In interactive mode, edit the message header fields ‘To:’,
4425 ‘Cc:’, ‘Bcc:’ and ‘Subject:’ by typing each one in turn and al‐
4426 lowing the user to edit the field. In non-interactive mode
4427 this sets ^ERR-NOTTY.
4428 ~I variable
4430 Insert the value of the specified variable into the message.
4431 The message remains unaltered if the variable is unset or
4432 empty. Any embedded character sequences ‘\t’ horizontal tabu‐
4433 lator and ‘\n’ line feed are expanded in posix mode; otherwise
4434 the expansion should occur at set time ([v15 behaviour may dif‐
4435 fer] by using the command modifier wysh).
4436 ~i variable
4438 Like ~I, but appends a newline character.
4439 ~M messages
4441 Read the named messages into the message being sent, indented
4442 by indentprefix. If no messages are specified, read the cur‐
4443 rent message, the “dot”. Honours forward-add-cc as well as
4444 forward-inject-head and forward-inject-tail.
4445 ~m messages
4447 Read the named messages into the message being sent, indented
4448 by indentprefix. If no messages are specified, read the cur‐
4449 rent message, the “dot”. Strips down the list of header fields
4450 according to the ‘type’ white- and blacklist selection of
4451 headerpick. Honours forward-add-cc as well as
4452 forward-inject-head and forward-inject-tail. For MIME multi‐
4453 part messages, only the first displayable part is included.
4454 ~p Display the message collected so far, prefaced by the message
4456 header fields and followed by the attachment list, if any.
4457 ~Q Read in the given / current message(s) using the algorithm of
4459 quote (except that is implicitly assumed, even if not set),
4460 honouring quote-add-cc.
4461 ~q Abort the message being sent, copying it to the file specified
4463 by the DEAD variable if save is set.
4464 ~R filename
4466 Identical to ~r, but indent each line that has been read by
4467 indentprefix.
4468 ~r filename [HERE-delimiter]
4470 Read the named file, object to Filename transformations exclud‐
4471 ing shell globs and variable expansions, into the message; if
4472 filename is the hyphen-minus ‘-’ then standard input is used
4473 (for pasting, for example). Only in this latter mode
4474 HERE-delimiter may be given: if it is data will be read in un‐
4475 til the given HERE-delimiter is seen on a line by itself, and
4476 encountering EOF is an error; the HERE-delimiter is a required
4477 argument in non-interactive mode; if it is single-quote quoted
4478 then the pasted content will not be expanded, [v15 behaviour
4479 may differ] otherwise a future version of S-nail may perform
4480 shell-style expansion on the content.
4481 ~s string
4483 Cause the named string to become the current subject field.
4484 Newline (NL) and carriage-return (CR) bytes are invalid and
4485 will be normalized to space (SP) characters.
4486 ~t name ...
4488 Add the given name(s) to the direct recipient list.
4489 ~U messages
4491 Read in the given / current message(s) excluding all headers,
4492 indented by indentprefix. Honours forward-add-cc as well as
4493 forward-inject-head and forward-inject-tail.
4494 ~u messages
4496 Read in the given / current message(s), excluding all headers.
4497 Honours forward-add-cc as well as forward-inject-head and
4498 forward-inject-tail.
4499 ~v Invoke the VISUAL editor on the message collected so far, then
4501 return to compose mode. ~e can be used for a less display ori‐
4502 ented editor, and ~|| offers a pipe-based editing approach.
4503 ~w filename
4505 Write the message onto the named file, which is object to the
4506 usual Filename transformations. If the file exists, the mes‐
4507 sage is appended to it.
4508 ~x Same as ~q, except that the message is not saved at all.
4510
4512 Internal S-nail variables are controlled via the set and unset commands;
4513 prefixing a variable name with the string ‘no’ and calling set has the
4514 same effect as using unset: ‘unset crt’ and ‘set nocrt’ do the same
4515 thing. varshow will give more insight on the given variable(s), and set,
4516 when called without arguments, will show a listing of all variables.
4517 Both commands support a more verbose listing mode. Some well-known vari‐
4518 ables will also become inherited from the program ENVIRONMENT implicitly,
4519 others can be imported explicitly with the command environ and henceforth
4520 share said properties.
4521 Two different kinds of internal variables exist, and both of which can
4523 also form chains. There are boolean variables, which can only be in one
4524 of the two states “set” and “unset”, and value variables with a(n op‐
4525 tional) string value. For the latter proper quoting is necessary upon
4526 assignment time, the introduction of the section COMMANDS documents the
4527 supported quoting rules.
4528 ? wysh set one=val\ 1 two="val 2" \
4530 three='val "3"' four=$'val \'4\''; \
4531 varshow one two three four; \
4532 unset one two three four
4533 Dependent upon the actual option string values may become interpreted as
4535 colour names, command specifications, normal text, etc. They may be
4536 treated as numbers, in which case decimal values are expected if so docu‐
4537 mented, but otherwise any numeric format and base that is valid and un‐
4538 derstood by the vexpr command may be used, too.
4539 There also exists a special kind of string value, the “boolean string”,
4541 which must either be a decimal integer (in which case ‘0’ is false and
4542 ‘1’ and any other value is true) or any of the (case-insensitive) strings
4543 ‘off’, ‘no’, ‘n’ and ‘false’ for a false boolean and ‘on’, ‘yes’, ‘y’ and
4544 ‘true’ for a true boolean; a special kind of boolean string is the
4545 “quadoption”: it can optionally be prefixed with the (case-insensitive)
4546 term ‘ask-’, as in ‘ask-yes’; in interactive mode the user will be
4547 prompted, otherwise the actual boolean is used.
4548 Variable chains extend a plain ‘variable’ with ‘variable-HOST’ and
4550 ‘variable-USER@HOST’ variants. Here ‘HOST’ will be converted to all low‐
4551 ercase when looked up (but not when the variable is set or unset!), [Op‐
4552 tion]ally IDNA converted, and indeed means ‘server:port’ if a ‘port’ had
4553 been specified in the contextual Uniform Resource Locator URL, see On URL
4554 syntax and credential lookup. Even though this mechanism is based on
4555 URLs no URL percent encoding may be applied to neither of ‘USER’ nor
4556 ‘HOST’, variable chains need to be specified using raw data; the men‐
4557 tioned section contains examples. Variables which support chains are ex‐
4558 plicitly documented as such, and S-nail treats the base name of any such
4559 variable special, meaning that users should not create custom names like
4560 ‘variable-xyz’ in order to avoid false classifications and treatment of
4561 such variables.
4562 Initial settings
4564 The standard POSIX 2008/Cor 2-2016 mandates the following initial vari‐
4565 able settings: noallnet, noappend, asksub, noaskbcc, noautoprint, nobang,
4566 nocmd, nocrt, nodebug, nodot, escape set to ‘~’, noflipr, nofolder,
4567 header, nohold, noignore, noignoreeof, nokeep, nokeepsave, nometoo,
4568 nooutfolder, nopage, prompt set to ‘? ’, noquiet, norecord, save,
4569 nosendwait, noshowto, noSign, nosign, toplines set to ‘5’.
4570 However, S-nail has built-in some initial (and some default) settings
4572 which (may) diverge, others may become adjusted by one of the Resource
4573 files. Displaying the former is accomplished via set: ‘$ s-nail -:/ -v
4574 -Xset -Xx’. In general this implementation sets (and has extended the
4575 meaning of) sendwait, and does not support the noonehop variable – use
4576 command line options or mta-arguments to pass options through to a mta.
4577 The default global resource file sets, among others, the variables hold,
4578 keep and keepsave, establishes a default headerpick selection etc., and
4579 should thus be taken into account.
4580 Variables
4582 ? (Read-only) The exit status of the last command, or the return
4583 value of the macro called last. This status has a meaning in
4584 the state machine: in conjunction with errexit any non-0 exit
4585 status will cause a program exit, and in posix mode any error
4586 while loading (any of the) resource files will have the same
4587 effect. ignerr, one of the Command modifiers, can be used to
4588 instruct the state machine to ignore errors.
4589 ! (Read-only) The current error number (errno(3)), which is set
4591 after an error occurred; it is also available via ^ERR, and the
4592 error name and documentation string can be queried via ^ERRNAME
4593 and ^ERRDOC. [v15 behaviour may differ] This machinery is new
4594 and the error number is only really usable if a command explic‐
4595 itly states that it manages the variable !, for others errno
4596 will be used in case of errors, or ^ERR-INVAL if that is 0: it
4597 thus may or may not reflect the real error. The error number
4598 may be set with the command return.
4599 ^ (Read-only) This is a multiplexer variable which performs dy‐
4601 namic expansion of the requested state or condition, of which
4602 there are:
4603 ^ERR, ^ERRDOC, ^ERRNAME
4605 The number, documentation, and name of the current
4606 errno(3), respectively, which is usually set after an
4607 error occurred. The documentation is an [Option],
4608 the name is used if not available. [v15 behaviour
4609 may differ] This machinery is new and is usually re‐
4610 liable only if a command explicitly states that it
4611 manages the variable !, which is effectively identi‐
4612 cal to ^ERR. Each of those variables can be suffixed
4613 with a hyphen minus followed by a name or number, in
4614 which case the expansion refers to the given error.
4615 Note this is a direct mapping of (a subset of) the
4616 system error values:
4617 define work {
4619 eval echo \$1: \$^ERR-$1:\
4620 \$^ERRNAME-$1: \$^ERRDOC-$1
4621 vput vexpr i + "$1" 1
4622 if [ $i -lt 16 ]
4623 \xcall work $i
4624 end
4625 }
4626 call work 0
4627 ^ERRQUEUE-COUNT, ^ERRQUEUE-EXISTS
4629 The number of messages in the [Option]al queue of
4630 errors, and a string indicating queue state: empty or
4631 (translated) “ERROR”. Always 0 and the empty string,
4632 respectively, unless features includes ‘,+errors,’.
4633 * (Read-only) Expands all positional parameters (see 1), sepa‐
4635 rated by the first character of the value of ifs. [v15 behav‐
4636 iour may differ] The special semantics of the equally named
4637 special parameter of the sh(1) are not yet supported.
4638 @ (Read-only) Expands all positional parameters (see 1), sepa‐
4640 rated by a space character. If placed in double quotation
4641 marks, each positional parameter is properly quoted to expand
4642 to a single parameter again.
4643 # (Read-only) Expands to the number of positional parameters,
4645 i.e., the size of the positional parameter stack in decimal.
4646 0 (Read-only) Inside the scope of a defined and called macro this
4648 expands to the name of the calling macro, or to the empty
4649 string if the macro is running from top-level. For the [Op‐
4650 tion]al regular expression search and replace operator of vexpr
4651 this expands to the entire matching expression. It represents
4652 the program name in global context.
4653 1 (Read-only) Access of the positional parameter stack. All fur‐
4655 ther parameters can be accessed with this syntax, too, ‘2’, ‘3’
4656 etc.; positional parameters can be shifted off the stack by
4657 calling shift. The parameter stack contains, for example, the
4658 arguments of a called defined macro, the matching groups of the
4659 [Option]al regular expression search and replace expression of
4660 vexpr, and can be explicitly created or overwritten with the
4661 command vpospar.
4662 account (Read-only) Is set to the active account.
4664 add-file-recipients
4666 (Boolean) When file or pipe recipients have been specified,
4667 mention them in the corresponding address fields of the message
4668 instead of silently stripping them from their recipient list.
4669 By default such addressees are not mentioned.
4670 allnet (Boolean) Causes only the local part to be evaluated when com‐
4672 paring addresses.
4673 append (Boolean) Causes messages saved in the secondary mailbox MBOX
4675 to be appended to the end rather than prepended. This should
4676 always be set.
4677 askatend (Boolean) Causes the prompts for ‘Cc:’ and ‘Bcc:’ lists to ap‐
4679 pear after the message has been edited.
4680 askattach
4682 (Boolean) If set, S-nail asks an interactive user for files to
4683 attach at the end of each message; An empty line finalizes the
4684 list.
4685 askcc (Boolean) Causes the interactive user to be prompted for carbon
4687 copy recipients (at the end of each message if askatend or
4688 bsdcompat are set).
4689 askbcc (Boolean) Causes the interactive user to be prompted for blind
4691 carbon copy recipients (at the end of each message if askatend
4692 or bsdcompat are set).
4693 asksend (Boolean) Causes the interactive user to be prompted for con‐
4695 firmation to send the message or reenter compose mode after
4696 having been shown a preliminary envelope summary.
4697 asksign (Boolean)[Option] Causes the interactive user to be prompted if
4699 the message is to be signed at the end of each message. The
4700 smime-sign variable is ignored when this variable is set.
4701 asksub (Boolean) Causes S-nail to prompt the interactive user for the
4703 subject upon entering compose mode unless a subject already ex‐
4704 ists.
4705 attrlist A sequence of characters to display in the ‘attribute’ column
4707 of the headline as shown in the display of headers; each for
4708 one type of messages (see Message states), with the default be‐
4709 ing ‘NUROSPMFAT+-$~’ or ‘NU *HMFAT+-$~’ if the bsdflags vari‐
4710 able is set, in the following order:
4711 ‘N’ new.
4713 ‘U’ unread but old.
4714 ‘R’ new but read.
4715 ‘O’ read and old.
4716 ‘S’ saved.
4717 ‘P’ preserved.
4718 ‘M’ mboxed.
4719 ‘F’ flagged.
4720 ‘A’ answered.
4721 ‘T’ draft.
4722 ‘+’ [v15 behaviour may differ] start of a (collapsed)
4723 thread in threaded mode (see autosort, thread);
4724 ‘-’ [v15 behaviour may differ] an uncollapsed thread in
4725 threaded mode; only used in conjunction with -L.
4726 ‘$’ classified as spam.
4727 ‘~’ classified as possible spam.
4728 autobcc Specifies a list of recipients to which a blind carbon copy of
4730 each outgoing message will be sent automatically.
4731 autocc Specifies a list of recipients to which a carbon copy of each
4733 outgoing message will be sent automatically.
4734 autocollapse
4736 (Boolean) Causes threads to be collapsed automatically when .Ql
4737 thread Ns ed sort mode is entered (see the collapse command).
4738 autoprint
4740 (Boolean) Enable automatic typeing of a(n existing)
4741 “successive” message after delete and undelete commands: the
4742 message that becomes the new “dot” is shown automatically, as
4743 via dp or dt.
4744 autosort Causes sorted mode (see the sort command) to be entered auto‐
4746 matically with the value of this variable as sorting method
4747 when a folder is opened, for example ‘set autosort=thread’.
4748 bang (Boolean) Enables the substitution of all not (reverse-solidus)
4750 escaped exclamation mark ‘!’ characters by the contents of the
4751 last executed command for the ! shell escape command and ~!,
4752 one of the compose mode COMMAND ESCAPES. If this variable is
4753 not set no reverse solidus stripping is performed.
4754 bind-timeout
4756 [Obsolete] Predecessor of bind-inter-byte-timeout. [v15 behav‐
4757 iour may differ] Setting this automatically sets the successor.
4758 bind-inter-byte-timeout
4760 [Option] Terminals may generate multi-byte sequences for spe‐
4761 cial function keys, for example, but these sequences may not
4762 become read as a unit. And multi-byte sequences can be defined
4763 freely via bind. This variable specifies the timeout in mil‐
4764 liseconds that the MLE (see On terminal control and line
4765 editor) waits for more bytes to arrive unless it considers a
4766 sequence “complete”. The default is 200, the maximum is about
4767 10 seconds. In the following example the comments state which
4768 sequences are affected by this timeout:
4769 ? bind base abc echo 0 # abc
4771 ? bind base ab,c echo 1 # ab
4772 ? bind base abc,d echo 2 # abc
4773 ? bind base ac,d echo 3 # ac
4774 ? bind base a,b,c echo 4
4775 ? bind base a,b,c,d echo 5
4776 ? bind base a,b,cc,dd echo 6 # cc and dd
4777 bind-inter-key-timeout
4779 [Option] Multi-key bind sequences do not time out by default.
4780 If this variable is set, then the current key sequence is
4781 forcefully terminated once the timeout (in milliseconds) trig‐
4782 gers. The value should be (maybe significantly) larger than
4783 bind-inter-byte-timeout, but may not excess the maximum, too.
4784 bsdcompat
4786 (Boolean) Sets some cosmetical features to traditional BSD
4787 style; has the same affect as setting askatend and all other
4788 variables prefixed with ‘bsd’; it also changes the behaviour of
4789 emptystart (which does not exist in BSD).
4790 bsdflags (Boolean) Changes the letters shown in the first column of a
4792 header summary to traditional BSD style.
4793 bsdheadline
4795 (Boolean) Changes the display of columns in a header summary to
4796 traditional BSD style.
4797 bsdmsgs (Boolean) Changes some informational messages to traditional
4799 BSD style.
4800 bsdorder (Boolean) Causes the ‘Subject:’ field to appear immediately af‐
4802 ter the ‘To:’ field in message headers and with the ~h COMMAND
4803 ESCAPES.
4804 build-cc, build-ld, build-os, build-rest
4806 (Read-only) The build environment, including the compiler, the
4807 linker, the operating system S-nail has been build for, usually
4808 taken from uname(1) via ‘uname -s’, and then lowercased, as
4809 well as all the possibly interesting rest of the configuration
4810 and build environment. This information is also available in
4811 the verbose output of the command version.
4812 charset-7bit
4814 The value that should appear in the ‘charset=’ parameter of
4815 ‘Content-Type:’ MIME header fields when no character set con‐
4816 version of the message data was performed. This defaults to
4817 US-ASCII, and the chosen character set should be US-ASCII com‐
4818 patible.
4819 charset-8bit
4821 [Option] The default 8-bit character set that is used as an im‐
4822 plicit last member of the variable sendcharsets. This defaults
4823 to UTF-8 if character set conversion capabilities are avail‐
4824 able, and to ISO-8859-1 otherwise (unless the operating system
4825 environment is known to always and exclusively support UTF-8
4826 locales), in which case the only supported character set is
4827 ttycharset and this variable is effectively ignored.
4828 charset-unknown-8bit
4830 [Option] RFC 1428 specifies conditions when internet mail gate‐
4831 ways shall “upgrade” the content of a mail message by using a
4832 character set with the name ‘unknown-8bit’. Because of the un‐
4833 classified nature of this character set S-nail will not be ca‐
4834 pable to convert this character set to any other character set.
4835 If this variable is set any message part which uses the charac‐
4836 ter set ‘unknown-8bit’ is assumed to really be in the character
4837 set given in the value, otherwise the (final) value of
4838 charset-8bit is used for this purpose.
4839 This variable will also be taken into account if a MIME type
4841 (see The mime.types files) of a MIME message part that uses the
4842 ‘binary’ character set is forcefully treated as text.
4843 cmd The default value for the pipe command.
4845 colour-disable
4847 (Boolean)[Option] Forcefully disable usage of colours. Also
4848 see the section Coloured display.
4849 colour-pager
4851 (Boolean)[Option] Whether colour shall be used for output that
4852 is paged through PAGER. Note that pagers may need special com‐
4853 mand line options, for example less(1) requires the option -R
4854 and lv(1) the option -c in order to support colours. Often do‐
4855 ing manual adjustments is unnecessary since S-nail may perform
4856 adjustments dependent on the value of the environment variable
4857 PAGER (see there for more).
4858 contact-mail, contact-web
4860 (Read-only) Addresses for contact per email and web, respec‐
4861 tively, for bug reports, suggestions, or anything else regard‐
4862 ing S-nail. The former can be used directly: ‘? eval mail
4863 $contact-mail’.
4864 content-description-forwarded-message,
4866 content-description-quote-attachment,
4867 content-description-smime-message,
4868 content-description-smime-signature
4869 [Option](partially) Strings which will be placed in according
4870 ‘Content-Description:’ headers if non-empty. They all have de‐
4871 fault values, for example ‘Forwarded message’.
4872 crt In a(n interactive) terminal session, then if this valued vari‐
4874 able is set it will be used as a threshold to determine how
4875 many lines the given output has to span before it will be dis‐
4876 played via the configured PAGER; Usage of the PAGER can be
4877 forced by setting this to the value ‘0’, setting it without a
4878 value will deduce the current height of the terminal screen to
4879 compute the threshold (see LINES, screen and stty(1)). [v15
4880 behaviour may differ] At the moment this uses the count of
4881 lines of the message in wire format, which, dependent on the
4882 mime-encoding of the message, is unrelated to the number of
4883 display lines. (The software is old and historically the rela‐
4884 tion was a given thing.)
4885 customhdr
4887 Define a set of custom headers to be injected into newly com‐
4888 posed or forwarded messages. A custom header consists of the
4889 field name followed by a colon ‘:’ and the field content body.
4890 Standard header field names cannot be overwritten by a custom
4891 header, with the exception of ‘Comments:’ and ‘Keywords:’.
4892 Different to the command line option -C the variable value is
4893 interpreted as a comma-separated list of custom headers: to in‐
4894 clude commas in header bodies they need to become escaped with
4895 reverse solidus ‘\’. Headers can be managed more freely in
4896 Compose mode via ~^.
4897 ? set customhdr='Hdr1: Body1-1\, Body1-2, Hdr2: Body2'
4899 datefield
4901 Controls the appearance of the ‘%d’ date and time format speci‐
4902 fication of the headline variable, that is used, for example,
4903 when viewing the summary of headers. If unset, then the local
4904 receiving date is used and displayed unformatted, otherwise the
4905 message sending ‘Date:’. It is possible to assign a
4906 strftime(3) format string and control formatting, but embedding
4907 newlines via the ‘%n’ format is not supported, and will result
4908 in display errors. The default is ‘%Y-%m-%d %H:%M’, and also
4909 see datefield-markout-older.
4910 datefield-markout-older
4912 Only used in conjunction with datefield. Can be used to create
4913 a visible distinction of messages dated more than a day in the
4914 future, or older than six months, a concept comparable to the
4915 -l option of the POSIX utility ls(1). If set to the empty
4916 string, then the plain month, day and year of the ‘Date:’ will
4917 be displayed, but a strftime(3) format string to control for‐
4918 matting can be assigned. The default is ‘%Y-%m-%d’.
4919 debug (Boolean) (Almost) Enter a debug-only sandbox mode which gener‐
4921 ates many log messages, disables the actual delivery of mes‐
4922 sages, and also implies norecord as well as nosave. Also see
4923 verbose.
4924 disposition-notification-send
4926 (Boolean)[Option] Emit a ‘Disposition-Notification-To:’ header
4927 (RFC 3798) with the message. This requires the from variable
4928 to be set.
4929 dot (Boolean) When dot is set, a period ‘.’ on a line by itself
4931 during message input in (interactive or batch -#) Compose mode
4932 will be treated as end-of-message (in addition to the normal
4933 end-of-file condition). This behaviour is implied in posix
4934 mode with a set ignoreeof.
4935 dotlock-disable
4937 (Boolean)[Option] Disable creation of dotlock files for MBOX
4938 databases.
4939 dotlock-ignore-error
4941 [Obsolete](Boolean)[Option] Ignore failures when creating
4942 dotlock files. Please use dotlock-disable instead.
4943 editalong
4945 If this variable is set then the editor is started automati‐
4946 cally when a message is composed in interactive mode. If the
4947 value starts with the letter ‘v’ then this acts as if ~v, oth‐
4948 erwise as if ~e (see COMMAND ESCAPES) had been specified. The
4949 editheaders variable is implied for this automatically spawned
4950 editor session.
4951 editheaders
4953 (Boolean) When a message is edited while being composed, its
4954 header is included in the editable text.
4955 emptystart
4957 (Boolean) When entering interactive mode S-nail normally writes
4958 “No mail for user” and exits immediately if a mailbox is empty
4959 or does not exist. If this variable is set S-nail starts even
4960 with an empty or non-existent mailbox (the latter behaviour
4961 furtherly depends upon bsdcompat, though).
4962 errexit (Boolean) Let each command with a non-0 exit status, including
4964 every called macro which returns a non-0 status, cause a pro‐
4965 gram exit unless prefixed by ignerr (see Command modifiers).
4966 This also affects COMMAND ESCAPES, but which use a different
4967 modifier for ignoring the error. Please refer to the variable
4968 ? for more on this topic.
4969 errors-limit
4971 [Option] Maximum number of entries in the errors queue.
4972 escape The first character of this value defines the escape character
4974 for COMMAND ESCAPES in Compose mode. The default value is the
4975 character tilde ‘~’. If set to the empty string, command es‐
4976 capes are disabled.
4977 expandaddr
4979 If unset only user name and email address recipients are al‐
4980 lowed On sending mail, and non-interactive mode. If set with‐
4981 out value all possible recipient types will be accepted. A
4982 value is parsed as a comma-separated list of case-insensitive
4983 strings, and if that contains ‘restrict’ behaviour equals the
4984 former except when in interactive mode or if COMMAND ESCAPES
4985 were enabled via -~ or -#, in which case it equals the latter,
4986 allowing all address types. ‘restrict’ really acts like
4987 ‘restrict,-all,+name,+addr’, so care for ordering issues must
4988 be taken.
4989 Recipient types can be added and removed with a plus sign ‘+’
4991 or hyphen-minus ‘-’ prefix, respectively. By default invalid
4992 or disallowed types are filtered out and cause a warning, hard
4993 send errors need to be enforced by including ‘fail’. The value
4994 ‘all’ covers all types, ‘fcc’ whitelists ‘Fcc:’ header targets
4995 regardless of other settings, ‘file’ file targets (it includes
4996 ‘fcc’), ‘pipe’ command pipeline targets, ‘name’ user names
4997 still unexpanded after alias and mta-aliases processing and
4998 thus left for expansion by the mta (invalid for the built-in
4999 SMTP one), and ‘addr’ network addresses. Targets are inter‐
5000 preted in the given order, so that ‘restrict,fail,+file,-all,
5001 +addr’ will cause hard errors for any non-network address re‐
5002 cipient address unless running interactively or having been
5003 started with the option -~ or -#; in the latter case(s) any
5004 type may be used.
5005 User name receivers addressing valid local users can be ex‐
5007 panded to fully qualified network addresses (also see hostname)
5008 by including ‘nametoaddr’ in the list. Historically invalid
5009 recipients were stripped off without causing errors, this can
5010 be changed by making ‘failinvaddr’ an entry of the list (it re‐
5011 ally acts like ‘failinvaddr,+addr’). Likewise, ‘domaincheck’
5012 (really ‘domaincheck,+addr’) compares address domain names
5013 against a whitelist and strips off (‘fail’ for hard errors) ad‐
5014 dressees which fail this test; the domain name ‘localhost’ and
5015 the non-empty value of hostname (the real hostname otherwise)
5016 are always whitelisted, expandaddr-domaincheck can be set to
5017 extend this list. Finally some address providers (for example
5018 -b, -c and all other command line recipients) will be evaluated
5019 as if specified within dollar-single-quotes (see Shell-style
5020 argument quoting) if the value list contains the string
5021 ‘shquote’.
5022 expandaddr-domaincheck
5024 Can be set to a comma-separated list of domain names which
5025 should be whitelisted for the evaluation of the ‘domaincheck’
5026 mode of expandaddr. IDNA encoding is not automatically per‐
5027 formed, addrcodec can be used to prepare the domain (of an ad‐
5028 dress).
5029 expandargv
5031 Unless this variable is set additional mta (Mail-Transfer-
5032 Agent) arguments from the command line, as can be given after a
5033 -- separator, results in a program termination with failure
5034 status. The same can be accomplished by using the special
5035 (case-insensitive) value ‘fail’. A lesser strict variant is
5036 the otherwise identical ‘restrict’, which does accept such ar‐
5037 guments in interactive mode, or if tilde commands were enabled
5038 explicitly by using one of the command line options -~ or -#.
5039 The empty value will allow unconditional usage.
5040 features (Read-only) String giving a list of optional features. Fea‐
5042 tures are preceded with a plus sign ‘+’ if they are available,
5043 with a hyphen-minus ‘-’ otherwise. To ease substring matching
5044 the string starts and ends with a comma. The output of the
5045 command version includes this information in a more pleasant
5046 output.
5047 flipr (Boolean) This setting reverses the meanings of a set of reply
5049 commands, turning the lowercase variants, which by default ad‐
5050 dress all recipients included in the header of a message
5051 (reply, respond, followup) into the uppercase variants, which
5052 by default address the sender only (Reply, Respond, Followup)
5053 and vice versa.
5054 folder The default path under which mailboxes are to be saved: file‐
5056 names that begin with the plus sign ‘+’ will have the plus sign
5057 replaced with the value of this variable if set, otherwise the
5058 plus sign will remain unchanged when doing Filename
5059 transformations; also see folder for more on this topic, and
5060 know about standard imposed implications of outfolder. The
5061 value supports a subset of transformations itself, and if the
5062 non-empty value does not start with a solidus ‘/’, then the
5063 value of HOME will be prefixed automatically. Once the actual
5064 value is evaluated first, the internal variable folder-resolved
5065 will be updated for caching purposes.
5066 folder-hook-FOLDER, folder-hook
5068 Names a defined macro which will be called whenever a folder is
5069 opened. The macro will also be invoked when new mail arrives,
5070 but message lists for commands executed from the macro only in‐
5071 clude newly arrived messages then. localopts are activated by
5072 default in a folder hook, causing the covered settings to be
5073 reverted once the folder is left again.
5074 The specialized form will override the generic one if ‘FOLDER’
5076 matches the file that is opened. Unlike other folder specifi‐
5077 cations, the fully expanded name of a folder, without metachar‐
5078 acters, is used to avoid ambiguities. However, if the mailbox
5079 resides under folder then the usual ‘+’ specification is tried
5080 in addition, so that if folder is “mail” (and thus relative to
5081 the user's home directory) then /home/usr1/mail/sent will be
5082 tried as ‘folder-hook-/home/usr1/mail/sent’ first, but then
5083 followed by ‘folder-hook-+sent’.
5084 folder-resolved
5086 (Read-only) Set to the fully resolved path of folder once that
5087 evaluation has occurred; rather internal.
5088 followup-to
5090 (Boolean) Controls whether a ‘Mail-Followup-To:’ header is gen‐
5091 erated when sending messages to known mailing lists. The user
5092 as determined via from (or, if that contains multiple ad‐
5093 dresses, sender) will be placed in there if any list addressee
5094 is not a subscribed list. Also see followup-to-honour and the
5095 commands mlist, mlsubscribe, reply and Lreply.
5096 followup-to-add-cc
5098 (Boolean) Controls whether the user will be added to the mes‐
5099 sages' ‘Cc:’ list in addition to placing an entry in
5100 ‘Mail-Followup-To:’ (see followup-to).
5101 followup-to-honour
5103 Controls whether a ‘Mail-Followup-To:’ header is honoured when
5104 group-replying to a message via reply or Lreply. This is a
5105 quadoption; if set without a value it defaults to “yes”, and
5106 see followup-to.
5107 forward-add-cc
5109 (Boolean) Whether senders of messages forwarded via ~F, ~f, ~m,
5110 ~U or ~u shall be made members of the carbon copies ‘Cc:’ list.
5111 forward-as-attachment
5113 (Boolean) Original messages are normally sent as inline text
5114 with the forward command, and only the first part of a multi‐
5115 part message is included. With this setting enabled messages
5116 are sent as unmodified MIME ‘message/rfc822’ attachments with
5117 all of their parts included.
5118 forward-inject-head, forward-inject-tail
5120 The strings to put before and after the text of a message with
5121 the forward command, respectively. The former defaults to
5122 ‘-------- Original Message --------\n’. Special format direc‐
5123 tives in these strings will be expanded if possible, and if so
5124 configured the output will be folded according to quote-fold;
5125 for more please refer to quote-inject-head. Injections will
5126 not be performed by forward if the variable
5127 forward-as-attachment is set — the COMMAND ESCAPES ~F, ~f, ~M,
5128 ~m, ~U, ~u always inject.
5129 from The address (or a list of addresses) to put into the ‘From:’
5131 field of the message header, quoting RFC 5322: the author(s) of
5132 the message, that is, the mailbox(es) of the person(s) or sys‐
5133 tem(s) responsible for the writing of the message. According
5134 to that RFC setting the sender variable is required if from
5135 contains more than one address. [v15 behaviour may differ]
5136 Please expect automatic management of the from and sender rela‐
5137 tionship. Dependent on the context these addresses are handled
5138 as if they were in the list of alternates.
5139 If a file-based MTA is used, then from (or, if that contains
5141 multiple addresses, sender) can nonetheless be used as the en‐
5142 velope sender address at the MTA protocol level (the RFC 5321
5143 reverse-path), either via the -r command line option (without
5144 argument; see there for more), or by setting r-option-implicit.
5145 If the machine's hostname is not valid at the Internet (for ex‐
5147 ample at a dialup machine), then either this variable or
5148 hostname ([v15-compat] a SMTP-based mta adds even more fine-
5149 tuning capabilities with smtp-hostname) have to be set: if so
5150 the message and MIME part related unique ID fields
5151 ‘Message-ID:’ and ‘Content-ID:’ will be created (except when
5152 disallowed by message-id-disable or stealthmua).
5153 fullnames
5155 (Boolean) Due to historical reasons comments and name parts of
5156 email addresses are removed by default when sending mail, re‐
5157 plying to or forwarding a message. If this variable is set
5158 such stripping is not performed.
5159 fwdheading
5161 [Obsolete] Predecessor of forward-inject-head.
5162 header (Boolean) Causes the header summary to be written at startup
5164 and after commands that affect the number of messages or the
5165 order of messages in the current folder. Unless in posix mode
5166 a header summary will also be displayed on folder changes. The
5167 command line option -N can be used to set noheader.
5168 headline A format string to use for the summary of headers. Format
5170 specifiers in the given string start with a percent sign ‘%’
5171 and may be followed by an optional decimal number indicating
5172 the field width — if that is negative, the field is to be left-
5173 aligned. Names and addresses are subject to modifications ac‐
5174 cording to showname and showto. Valid format specifiers are:
5175 ‘%%’ A plain percent sign.
5177 ‘%>’ “Dotmark”: a space character but for the current mes‐
5178 sage (“dot”), for which it expands to ‘>’ (dependent
5179 on headline-plain).
5180 ‘%<’ “Dotmark”: a space character but for the current mes‐
5181 sage (“dot”), for which it expands to ‘<’ (dependent
5182 on headline-plain).
5183 ‘%$’ [Option] The spam score of the message, as has been
5184 classified via the command spamrate. Shows only a
5185 replacement character if there is no spam support.
5186 ‘%a’ Message attribute character (status flag); the actual
5187 content can be adjusted by setting attrlist.
5188 ‘%d’ The date found in the ‘Date:’ header of the message
5189 when datefield is set (the default), otherwise the
5190 date when the message was received. Formatting can
5191 be controlled by assigning a strftime(3) format
5192 string to datefield (and datefield-markout-older).
5193 ‘%e’ The indenting level in ‘thread’ed sort mode.
5194 ‘%f’ The address of the message sender.
5195 ‘%i’ The message thread tree structure. (Note that this
5196 format does not support a field width, and honours
5197 headline-plain.)
5198 ‘%L’ Mailing list status: is the addressee of the message
5199 a known ‘l’ (mlist) or ‘L’ mlsubscribed mailing list?
5200 The letter ‘P’ announces the presence of a RFC 2369
5201 ‘List-Post:’ header, which makes a message a valuable
5202 target of Lreply.
5203 ‘%l’ The number of lines of the message, if available.
5204 ‘%m’ Message number.
5205 ‘%o’ The number of octets (bytes) in the message, if
5206 available.
5207 ‘%S’ Message subject (if any) in double quotes.
5208 ‘%s’ Message subject (if any).
5209 ‘%t’ The position in threaded/sorted order.
5210 ‘%U’ The value 0 except in an IMAP mailbox, where it ex‐
5211 pands to the UID of the message.
5212 The default is ‘%>%a%m %-18f %16d %4l/%-5o %i%-s’, or
5214 ‘%>%a%m %20-f %16d %3l/%-5o %i%-S’ if bsdcompat is set. Also
5215 see attrlist, headline-plain and headline-bidi.
5216 headline-bidi
5218 Bidirectional text requires special treatment when displaying
5219 headers, because numbers (in dates or for file sizes etc.) will
5220 not affect the current text direction, in effect resulting in
5221 ugly line layouts when arabic or other right-to-left text is to
5222 be displayed. On the other hand only a minority of terminals
5223 is capable to correctly handle direction changes, so that user
5224 interaction is necessary for acceptable results. Note that ex‐
5225 tended host system support is required nonetheless, e.g., de‐
5226 tection of the terminal character set is one precondition; and
5227 this feature only works in an Unicode (i.e., UTF-8) locale.
5228 In general setting this variable will cause S-nail to encapsu‐
5230 late text fields that may occur when displaying headline (and
5231 some other fields, like dynamic expansions in prompt) with spe‐
5232 cial Unicode control sequences; it is possible to fine-tune the
5233 terminal support level by assigning a value: no value (or any
5234 value other than ‘1’, ‘2’ and ‘3’) will make S-nail assume that
5235 the terminal is capable to properly deal with Unicode version
5236 6.3, in which case text is embedded in a pair of U+2068 (FIRST
5237 STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE) charac‐
5238 ters. In addition no space on the line is reserved for these
5239 characters.
5240 Weaker support is chosen by using the value ‘1’ (Unicode 6.3,
5242 but reserve the room of two spaces for writing the control se‐
5243 quences onto the line). The values ‘2’ and ‘3’ select Unicode
5244 1.1 support (U+200E, LEFT-TO-RIGHT MARK); the latter again re‐
5245 serves room for two spaces in addition.
5246 headline-plain
5248 (Boolean) On Unicode (UTF-8) aware terminals enhanced graphical
5249 symbols are used by default for certain entries of headline.
5250 If this variable is set only basic US-ASCII symbols will be
5251 used.
5252 history-file
5254 [Option] The (expandable) location of a permanent history file
5255 for the MLE line editor (On terminal control and line editor).
5256 Also see history-size.
5257 history-gabby
5259 [Option] Add more entries to the MLE history as is normally
5260 done. A comma-separated list of case-insensitive strings can
5261 be used to fine-tune which gabby entries shall be allowed. If
5262 it contains ‘errors’, erroneous commands will also be added.
5263 ‘all’ adds all optional entries, and is the fallback chattiness
5264 identifier of on-history-addition.
5265 history-gabby-persist
5267 (Boolean)[Option] The history-gabby entries will not be saved
5268 in persistent storage unless this variable is set. The knowl‐
5269 edge of whether a persistent entry was gabby is not lost. Also
5270 see history-file.
5271 history-size
5273 [Option] Setting this variable imposes a limit on the number of
5274 concurrent history entries. If set to the value 0 then no fur‐
5275 ther history entries will be added, and loading and incorpora‐
5276 tion of the history-file upon program startup can also be sup‐
5277 pressed by doing this. Runtime changes will not be reflected
5278 before the history is saved or loaded (again).
5279 hold (Boolean) This setting controls whether messages are held in
5281 the system inbox, and it is set by default.
5282 hostname Used instead of the value obtained from uname(3) and
5284 getaddrinfo(3) as the hostname when expanding local addresses,
5285 for example in ‘From:’ (also see On sending mail, and non-
5286 interactive mode, for expansion of addresses that have a valid
5287 user-, but no domain name in angle brackets). If either of
5288 from or this variable is set the message and MIME part related
5289 unique ID fields ‘Message-ID:’ and ‘Content-ID:’ will be cre‐
5290 ated (except when disallowed by message-id-disable or
5291 stealthmua). If the [Option]al IDNA support is available (see
5292 idna-disable) variable assignment is aborted when a necessary
5293 conversion fails.
5294 Setting it to the empty string will cause the normal hostname
5296 to be used, but nonetheless enables creation of said ID fields.
5297 [v15-compat] in conjunction with the built-in SMTP mta
5298 smtp-hostname also influences the results: one should produce
5299 some test messages with the desired combination of hostname,
5300 and/or from, sender etc. first.
5301 idna-disable
5303 (Boolean)[Option] Can be used to turn off the automatic conver‐
5304 sion of domain names according to the rules of IDNA (interna‐
5305 tionalized domain names for applications). Since the IDNA code
5306 assumes that domain names are specified with the ttycharset
5307 character set, an UTF-8 locale charset is required to represent
5308 all possible international domain names (before conversion,
5309 that is).
5310 ifs The input field separator that is used ([v15 behaviour may dif‐
5312 fer] by some functions) to determine where to split input data.
5313 1. Unsetting is treated as assigning the default value,
5315 ‘ \t\n’.
5316 2. If set to the empty value, no field splitting will be
5317 performed.
5318 3. If set to a non-empty value, all whitespace charac‐
5319 ters are extracted and assigned to the variable
5320 ifs-ws.
5321 a. ifs-ws will be ignored at the beginning and end of
5323 input. Diverging from POSIX shells default white‐
5324 space is removed in addition, which is owed to the
5325 entirely different line content extraction rules.
5326 b. Each occurrence of a character of ifs will cause
5327 field-splitting, any adjacent ifs-ws characters will
5328 be skipped.
5329 ifs-ws (Read-only) Automatically deduced from the whitespace charac‐
5331 ters in ifs.
5332 ignore (Boolean) Ignore interrupt signals from the terminal while en‐
5334 tering messages; instead echo them as ‘@’ characters and dis‐
5335 card the current line.
5336 ignoreeof
5338 (Boolean) Ignore end-of-file conditions (‘control-D’) in
5339 Compose mode on message input and in interactive command input.
5340 If set an interactive command input session can only be left by
5341 explicitly using one of the commands exit and quit, and message
5342 input in compose mode can only be terminated by entering a pe‐
5343 riod ‘.’ on a line by itself or by using the ~. COMMAND
5344 ESCAPES; Setting this implies the behaviour that dot describes
5345 in posix mode.
5346 inbox If this is set to a non-empty string it will specify the user's
5348 primary system mailbox, overriding MAIL and the system-depen‐
5349 dent default, and (thus) be used to replace ‘%’ when doing
5350 Filename transformations; also see folder for more on this
5351 topic. The value supports a subset of transformations itself.
5352 indentprefix
5354 String used by the ~m, ~M and ~R COMMAND ESCAPES and by the
5355 quote option for indenting messages, in place of the POSIX man‐
5356 dated default tabulator character ‘\t’. Also see quote-chars.
5357 keep (Boolean) If set, an empty primary system mailbox file is not
5359 removed. Note that, in conjunction with posix mode any empty
5360 file will be removed unless this variable is set. This may im‐
5361 prove the interoperability with other mail user agents when us‐
5362 ing a common folder directory, and prevents malicious users
5363 from creating fake mailboxes in a world-writable spool direc‐
5364 tory. [v15 behaviour may differ] Only local regular (MBOX)
5365 files are covered, Maildir and other mailbox types will never
5366 be removed, even if empty.
5367 keep-content-length
5369 (Boolean) When (editing messages and) writing MBOX mailbox
5370 files S-nail can be told to keep the ‘Content-Length:’ and
5371 ‘Lines:’ header fields that some MUAs generate by setting this
5372 variable. Since S-nail does neither use nor update these non-
5373 standardized header fields (which in itself shows one of their
5374 conceptual problems), stripping them should increase interoper‐
5375 ability in between MUAs that work with with same mailbox files.
5376 Note that, if this is not set but writebackedited, as below,
5377 is, a possibly performed automatic stripping of these header
5378 fields already marks the message as being modified. [v15 be‐
5379 haviour may differ] At some future time S-nail will be capable
5380 to rewrite and apply an mime-encoding to modified messages, and
5381 then those fields will be stripped silently.
5382 keepsave (Boolean) When a message is saved it is usually discarded from
5384 the originating folder when S-nail is quit. This setting
5385 causes all saved message to be retained.
5386 line-editor-cpl-word-breaks
5388 [Option] List of bytes which are used by the mle-complete tabu‐
5389 lator completion to decide where word boundaries exist, by de‐
5390 fault ‘"'@=;|:’ [v15 behaviour may differ] This mechanism is
5391 yet restricted.
5392 line-editor-disable
5394 (Boolean) Turn off any line editing capabilities (from S-nails
5395 POW, see On terminal control and line editor for more).
5396 line-editor-no-defaults
5398 (Boolean)[Option] Do not establish any default key binding.
5399 log-prefix
5401 Error log message prefix string (‘s-nail: ’).
5402 mailbox-display
5404 (Read-only) The name of the current mailbox (folder), possibly
5405 abbreviated for display purposes.
5406 mailbox-resolved
5408 (Read-only) The fully resolved path of the current mailbox.
5409 mailcap-disable
5411 (Boolean)[Option] Turn off consideration of MIME type handlers
5412 from, and implicit loading of The Mailcap files.
5413 mailx-extra-rc
5415 An additional startup file that is loaded as the last of the
5416 Resource files. Use this file for commands that are not under‐
5417 stood by other POSIX mailx(1) implementations, i.e., mostly
5418 anything which is not covered by Initial settings.
5419 markanswered
5421 (Boolean) When a message is replied to and this variable is
5422 set, it is marked as having been answered. See the section
5423 Message states.
5424 mbox-fcc-and-pcc
5426 (Boolean) By default all file and pipe message receivers (see
5427 expandaddr) will be fed valid MBOX database entry message data
5428 (see folder, mbox-rfc4155), and existing file targets will be‐
5429 come extended in compliance to RFC 4155. If this variable is
5430 unset then a plain standalone RFC 5322 message will be written,
5431 and existing file targets will be overwritten.
5432 mbox-rfc4155
5434 (Boolean) When opening MBOX mailbox databases, and in order to
5435 achieve compatibility with old software, the very tolerant
5436 POSIX standard rules for detecting message boundaries (so-
5437 called ‘From_’ lines) are used instead of the stricter rules
5438 from the standard RFC 4155. This behaviour can be switched by
5439 setting this variable.
5440 This may temporarily be handy when S-nail complains about in‐
5442 valid ‘From_’ lines when opening a MBOX: in this case setting
5443 this variable and re-opening the mailbox in question may cor‐
5444 rect the result. If so, copying the entire mailbox to some
5445 other file, as in ‘copy * SOME-FILE’, will perform proper, all-
5446 compatible ‘From_’ quoting for all detected messages, resulting
5447 in a valid MBOX mailbox. ([v15 behaviour may differ] The bet‐
5448 ter and non-destructive approach is to re-encode invalid mes‐
5449 sages, as if it would be created anew, instead of mangling the
5450 ‘From_’ lines; this requires the structural code changes of the
5451 v15 rewrite.) Finally the variable can be unset again:
5452 define mboxfix {
5454 localopts yes; wysh set mbox-rfc4155;\
5455 wysh File "${1}"; copy * "${2}"
5456 }
5457 call mboxfix /tmp/bad.mbox /tmp/good.mbox
5458 memdebug (Boolean) Internal development variable. (Keeps memory debug
5460 enabled even if debug is not set.)
5461 message-id-disable
5463 (Boolean) By setting this variable the generation of
5464 ‘Message-ID:’ and ‘Content-ID:’ message and MIME part headers
5465 can be completely suppressed, effectively leaving this task up
5466 to the mta (Mail-Transfer-Agent) or the SMTP server. Note that
5467 according to RFC 5321 a SMTP server is not required to add this
5468 field by itself, so it should be ensured that it accepts mes‐
5469 sages without ‘Message-ID’.
5470 message-inject-head
5472 A string to put at the beginning of each new message, followed
5473 by a newline. [Obsolete] The escape sequences tabulator ‘\t’
5474 and newline ‘\n’ are understood (use the wysh prefix when
5475 setting the variable(s) instead).
5476 message-inject-tail
5478 A string to put at the end of each new message, followed by a
5479 newline. [Obsolete] The escape sequences tabulator ‘\t’ and
5480 newline ‘\n’ are understood (use the wysh prefix when setting
5481 the variable(s) instead). Also see on-compose-leave.
5482 metoo (Boolean) Usually, when an alias expansion contains the sender,
5484 the sender is removed from the expansion. Setting this option
5485 suppresses these removals. Note that a set metoo also causes a
5486 ‘-m’ option to be passed through to the mta (Mail-Transfer-
5487 Agent); though most of the modern MTAs no longer document this
5488 flag, no MTA is known which does not support it (for historical
5489 compatibility).
5490 mime-allow-text-controls
5492 (Boolean) When sending messages, each part of the message is
5493 MIME-inspected in order to classify the ‘Content-Type:’ and
5494 ‘Content-Transfer-Encoding:’ (see mime-encoding) that is re‐
5495 quired to send this part over mail transport, i.e., a computa‐
5496 tion rather similar to what the file(1) command produces when
5497 used with the ‘--mime’ option.
5498 This classification however treats text files which are encoded
5500 in UTF-16 (seen for HTML files) and similar character sets as
5501 binary octet-streams, forcefully changing any ‘text/plain’ or
5502 ‘text/html’ specification to ‘application/octet-stream’: If
5503 that actually happens a yet unset charset MIME parameter is set
5504 to ‘binary’, effectively making it impossible for the receiving
5505 MUA to automatically interpret the contents of the part.
5506 If this variable is set, and the data was unambiguously identi‐
5508 fied as text data at first glance (by a ‘.txt’ or ‘.html’ file
5509 extension), then the original ‘Content-Type:’ will not be over‐
5510 written.
5511 mime-alternative-favour-rich
5513 (Boolean) If this variable is set then rich MIME alternative
5514 parts (e.g., HTML) will be preferred in favour of included
5515 plain text versions when displaying messages, provided that a
5516 handler exists which produces output that can be (re)integrated
5517 into S-nail's normal visual display.
5518 mime-counter-evidence
5520 Normally the ‘Content-Type:’ field is used to decide how to
5521 handle MIME parts. Some MUAs, however, do not use The
5522 mime.types files (also see HTML mail and MIME attachments) or a
5523 similar mechanism to correctly classify content, but specify an
5524 unspecific MIME type (‘application/octet-stream’) even for
5525 plain text attachments. If this variable is set then S-nail
5526 will try to re-classify such MIME message parts, if possible,
5527 for example via a possibly existing attachment filename. A
5528 non-empty value may also be given, in which case a number is
5529 expected, actually a carrier of bits, best specified as a bi‐
5530 nary value, like ‘0b1111’.
5531 • If bit two is set (counting from 1, decimal 2) then the de‐
5533 tected mimetype will be carried along with the message and
5534 be used for deciding which MIME handler is to be used, for
5535 example; when displaying such a MIME part the part-info
5536 will indicate the overridden content-type by showing a plus
5537 sign ‘+’.
5538 • If bit three is set (decimal 4) then the counter-evidence
5539 is always produced and a positive result will be used as
5540 the MIME type, even forcefully overriding the parts given
5541 MIME type.
5542 • If bit four is set (decimal 8) as a last resort the actual
5543 content of ‘application/octet-stream’ parts will be in‐
5544 spected, so that data which looks like plain text can be
5545 treated as such. This mode is even more relaxed when data
5546 is to be displayed to the user or used as a message quote
5547 (data consumers which mangle data for display purposes,
5548 which includes masking of control characters, for example).
5549 mime-encoding
5551 The MIME ‘Content-Transfer-Encoding’ to use in outgoing text
5552 messages and message parts, where applicable (7-bit clean text
5553 messages are without an encoding if possible):
5554 ‘8bit’ (Or ‘8b’.) 8-bit transport effectively causes the
5556 raw data be passed through unchanged, but may cause
5557 problems when transferring mail messages over chan‐
5558 nels that are not ESMTP (RFC 1869) compliant. Also,
5559 several input data constructs are not allowed by the
5560 specifications and may cause a different transfer-en‐
5561 coding to be used. By established rules and popular
5562 demand occurrences of ‘^From_’ (see mbox-rfc4155)
5563 will be MBOXO quoted (prefixed with greater-than sign
5564 ‘>’) instead of causing a non-destructive encoding
5565 like ‘quoted-printable’ to be chosen, unless context
5566 (like message signing) requires otherwise.
5567 ‘quoted-printable’
5568 (Or ‘qp’.) Quoted-printable encoding is 7-bit clean
5569 and has the property that ASCII characters are passed
5570 through unchanged, so that an english message can be
5571 read as-is; it is also acceptable for other single-
5572 byte locales that share many characters with ASCII,
5573 for example ISO-8859-1. The encoding will cause a
5574 large overhead for messages in other character sets:
5575 for example it will require up to twelve (12) bytes
5576 to encode a single UTF-8 character of four (4) bytes.
5577 It is the default encoding.
5578 ‘base64’ (Or ‘b64’.) This encoding is 7-bit clean and will
5579 always be used for binary data. This encoding has a
5580 constant input:output ratio of 3:4, regardless of the
5581 character set of the input data it will encode three
5582 bytes of input to four bytes of output. This trans‐
5583 fer-encoding is not human readable without performing
5584 a decoding step.
5585 mime-force-sendout
5587 (Boolean)[Option] Whenever it is not acceptable to fail sending
5588 out messages because of non-convertible character content this
5589 variable may be set. It will, as a last resort, classify the
5590 part content as ‘application/octet-stream’. Please refer to
5591 the section Character sets for the complete picture of charac‐
5592 ter set conversion, and HTML mail and MIME attachments for how
5593 to internally or externally handle part content.
5594 mimetypes-load-control
5596 Can be used to control which of The mime.types files are
5597 loaded: if the letter ‘u’ is part of the option value, then the
5598 user's personal ~/.mime.types file will be loaded (if it ex‐
5599 ists); likewise the letter ‘s’ controls loading of the system
5600 wide /etc/mime.types; directives found in the user file take
5601 precedence, letter matching is case-insensitive. If this vari‐
5602 able is not set S-nail will try to load both files. Incorpora‐
5603 tion of the S-nail-built-in MIME types cannot be suppressed,
5604 but they will be matched last (the order can be listed via
5605 mimetype).
5606 More sources can be specified by using a different syntax: if
5608 the value string contains an equals sign ‘=’ then it is instead
5609 parsed as a comma-separated list of the described letters plus
5610 ‘f=FILENAME’ pairs; the given filenames will be expanded and
5611 loaded, and their content may use the extended syntax that is
5612 described in the section The mime.types files. Directives
5613 found in such files always take precedence (are prepended to
5614 the MIME type cache).
5615 mta Select an alternate Mail-Transfer-Agent by either specifying
5617 the full pathname of an executable (a ‘file://’ prefix may be
5618 given), or [Option]ally a SMTP aka SUBMISSION protocol URL
5619 [v15-compat]:
5620 submissions://[user[:password]@]server[:port]
5622 ([no v15-compat]: ‘[smtp://]server[:port]’.) The default has
5624 been chosen at compile time. MTA data transfers are always
5625 performed in asynchronous child processes, and without supervi‐
5626 sion unless either the sendwait or the verbose variable is set.
5627 Also see mta-bcc-ok. [Option]ally expansion of aliases(5) can
5628 be performed by setting mta-aliases.
5629 For testing purposes there is the ‘test’ pseudo-MTA, which
5631 dumps to standard output or optionally to a file, and honours
5632 mbox-fcc-and-pcc:
5633 $ echo text | s-nail -:/ -Smta=test -s ubject ex@am.ple
5635 $ </dev/null s-nail -:/ -Smta=test://./xy ex@am.ple
5636 For a file-based MTA it may be necessary to set mta-argv0 in in
5638 order to choose the right target of a modern mailwrapper(8) en‐
5639 vironment. It will be passed command line arguments from sev‐
5640 eral possible sources: from the variable mta-arguments if set,
5641 from the command line if given and the variable expandargv al‐
5642 lows their use. Argument processing of the MTA will be termi‐
5643 nated with a -- separator.
5644 The otherwise occurring implicit usage of the following MTA
5646 command line arguments can be disabled by setting the boolean
5647 variable mta-no-default-arguments (which will also disable
5648 passing -- to the MTA): -i (for not treating a line with only a
5649 dot ‘.’ character as the end of input), -m (shall the variable
5650 metoo be set) and -v (if the verbose variable is set); in con‐
5651 junction with the -r command line option or r-option-implicit
5652 -f as well as possibly -F will (not) be passed.
5653 [Option]ally S-nail can send mail over SMTP aka SUBMISSION net‐
5655 work connections to a single defined smart host by setting this
5656 variable to a SMTP or SUBMISSION URL (see On URL syntax and
5657 credential lookup). An authentication scheme can be specified
5658 via the variable chain smtp-auth. Encrypted network connec‐
5659 tions are [Option]ally available, the section Encrypted network
5660 communication should give an overview and provide links to more
5661 information on this. Note that with some mail providers it may
5662 be necessary to set the smtp-hostname variable in order to use
5663 a specific combination of from, hostname and mta. Network com‐
5664 munication socket timeouts are configurable via
5665 socket-connect-timeout. All generated network traffic may be
5666 proxied over a SOCKS socks-proxy, it can be logged by setting
5667 verbose twice. The following SMTP variants may be used:
5668 • The plain SMTP protocol (RFC 5321) that normally lives on
5670 the server port 25 and requires setting the
5671 smtp-use-starttls variable to enter a TLS encrypted session
5672 state. Assign a value like [v15-compat]
5673 ‘smtp://[user[:password]@]server[:port]’ ([no v15-compat]
5674 ‘smtp://server[:port]’) to choose this protocol.
5675 • The so-called SMTPS which is supposed to live on server
5677 port 465 and is automatically TLS secured. Unfortunately
5678 it never became a standardized protocol and may thus not be
5679 supported by your hosts network service database – in fact
5680 the port number has already been reassigned to other proto‐
5681 cols!
5682 SMTPS is nonetheless a commonly offered protocol and thus
5684 can be chosen by assigning a value like [v15-compat]
5685 ‘smtps://[user[:password]@]server[:port]’ ([no v15-compat]
5686 ‘smtps://server[:port]’); due to the mentioned problems it
5687 is usually necessary to explicitly specify the port as
5688 ‘:465’, however.
5689 • The SUBMISSION protocol (RFC 6409) lives on server port 587
5691 and is identically to the SMTP protocol from S-nail's point
5692 of view; it requires setting smtp-use-starttls to enter a
5693 TLS secured session state; e.g., [v15-compat]
5694 ‘submission://[user[:password]@]server[:port]’.
5695 • The SUBMISSIONS protocol (RFC 8314) that lives on server
5697 port 465 and is TLS secured by default. It can be chosen
5698 by assigning a value like [v15-compat]
5699 ‘submissions://[user[:password]@]server[:port]’. Due to
5700 the problems mentioned for SMTPS above and the fact that
5701 SUBMISSIONS is new and a successor that lives on the same
5702 port as the historical engineering mismanagement named
5703 SMTPS, it is usually necessary to explicitly specify the
5704 port as ‘:465’.
5705 mta-aliases
5707 [Option] If set to a path pointing to a text file in valid MTA
5708 (Postfix) aliases(5) format, the file is loaded and cached
5709 (manageable with mtaaliases), and henceforth plain ‘name’ (see
5710 expandaddr) message receiver names are recursively expanded as
5711 a last expansion step, after the distribution lists which can
5712 be created with alias. Constraints on aliases(5) content sup‐
5713 port: only local addresses (names) which are valid usernames
5714 (‘[a-z_][a-z0-9_-]*[$]?’) are treated as expandable aliases,
5715 and [v15 behaviour may differ] ‘:include:/file/name’ directives
5716 are not supported. By including ‘-name’ in expandaddr it can
5717 be asserted that only expanded names (mail addresses) are
5718 passed through to the MTA.
5719 mta-arguments
5721 Arguments to pass through to a file-based mta (Mail-Transfer-
5722 Agent), parsed according to Shell-style argument quoting into
5723 an array of arguments which will be joined onto MTA options
5724 from other sources, for example ‘? wysh set mta-arguments='-t
5725 -X "/tmp/my log"'’.
5726 mta-no-default-arguments
5728 (Boolean) Avoids passing standard command line options to a
5729 file-based mta (please see there).
5730 mta-no-receiver-arguments
5732 (Boolean) By default all receiver addresses will be passed as
5733 command line options to a file-based mta. Setting this vari‐
5734 able disables this behaviour to aid those MTAs which employ
5735 special treatment of such arguments. Doing so can make it nec‐
5736 essary to pass a -t via mta-arguments, to testify the MTA that
5737 it should use the passed message as a template.
5738 mta-argv0
5740 Many systems use a so-called mailwrapper(8) environment to en‐
5741 sure compatibility with sendmail(1). This works by inspecting
5742 the name that was used to invoke the mail delivery system. If
5743 this variable is set then the mailwrapper (the program that is
5744 actually executed when calling the file-based mta) will treat
5745 its contents as that name.
5746 mta-bcc-ok
5748 (Boolean) In violation of RFC 5322 some MTAs do not remove
5749 ‘Bcc:’ header lines from transported messages after having
5750 noted the respective receivers for addressing purposes. (The
5751 MTAs Exim and Courier for example require the command line op‐
5752 tion -t to enforce removal.) Unless this is set corresponding
5753 receivers are addressed by protocol-specific means or MTA com‐
5754 mand line options only, the header itself is stripped before
5755 being sent over the wire.
5756 netrc-lookup-USER@HOST, netrc-lookup-HOST, netrc-lookup
5758 (Boolean)[v15-compat][Option] Used to control usage of the
5759 user's ~/.netrc file for lookup of account credentials, as doc‐
5760 umented in the section On URL syntax and credential lookup and
5761 for the command netrc; the section The .netrc file documents
5762 the file format. Also see netrc-pipe.
5763 netrc-pipe
5765 [v15-compat][Option] When ~/.netrc is loaded (see netrc and
5766 netrc-lookup) then S-nail will read the output of a shell pipe
5767 instead of the user's ~/.netrc file if this variable is set (to
5768 the desired shell command). This can be used to, for example,
5769 store ~/.netrc in encrypted form: ‘? set netrc-pipe='gpg -qd
5770 ~/.netrc.pgp'’.
5771 newfolders
5773 [Option] If this variable has the value ‘maildir’, newly cre‐
5774 ated local folders will be in Maildir instead of MBOX format.
5775 newmail Checks for new mail in the current folder each time the prompt
5777 is shown. A Maildir folder must be re-scanned to determine if
5778 new mail has arrived. If this variable is set to the special
5779 value ‘nopoll’ then a Maildir folder will not be rescanned com‐
5780 pletely, but only timestamp changes are detected. Maildir
5781 folders are [Option]al.
5782 outfolder
5784 (Boolean) Causes a non-absolute filename specified in record,
5785 as well as the sender-based filenames of the Copy, Save,
5786 Followup and followup commands to be interpreted relative to
5787 the folder directory rather than relative to the current direc‐
5788 tory.
5789 on-account-cleanup-ACCOUNT, on-account-cleanup
5791 Macro hook which will be called once an account is left, as the
5792 very last step before unrolling per-account localopts. This
5793 hook is run even in case of fatal errors, including those gen‐
5794 erated by switching to the account as such, and it is advisable
5795 to perform only absolutely necessary actions, like cleaning up
5796 alternates, for example. The specialized form is used in
5797 favour of the generic one if found.
5798 on-compose-cleanup
5800 Macro hook which will be called after the message has been sent
5801 (or not, in case of failures), as the very last step before un‐
5802 rolling compose mode localopts. This hook is run even in case
5803 of fatal errors, and it is advisable to perform only absolutely
5804 necessary actions, like cleaning up alternates, for example.
5805 For compose mode hooks that may affect the message content
5807 please see on-compose-enter, on-compose-leave,
5808 on-compose-splice. [v15 behaviour may differ] This hook exists
5809 because alias, alternates, commandalias, shortcut, to name a
5810 few, are neither covered by localopts nor by local: changes ap‐
5811 plied in compose mode will continue to be in effect thereafter.
5812 on-compose-enter, on-compose-leave
5814 Macro hooks which will be called once compose mode is entered,
5815 and after composing has been finished, respectively; the exact
5816 order of the steps taken is documented for ~., one of the
5817 COMMAND ESCAPES. Context about the message being worked on can
5818 be queried via digmsg. localopts are enabled for these hooks,
5819 and changes on variables will be forgotten after the message
5820 has been sent. on-compose-cleanup can be used to perform other
5821 necessary cleanup steps.
5822 Here is an example that injects a signature via
5824 message-inject-tail; instead using on-compose-splice to simply
5825 inject the file of desire via ~< or ~<! may be a better ap‐
5826 proach.
5827 define t_ocl {
5829 vput ! i cat ~/.mysig
5830 if $? -eq 0
5831 vput csop message-inject-tail trim-end $i
5832 end
5833 # Alternatively
5835 readctl create ~/.mysig
5836 if $? -eq 0
5837 readall i
5838 if $? -eq 0
5839 vput csop message-inject-tail trim-end $i
5840 end
5841 readctl remove ~/.mysig
5842 end
5843 }
5844 set on-compose-leave=t_ocl
5845 on-compose-splice, on-compose-splice-shell
5847 These hooks run once the normal compose mode is finished, but
5848 before the on-compose-leave macro hook is called etc. Both
5849 hooks will be executed in a subprocess, with their input and
5850 output connected to S-nail such that they can act as if they
5851 would be an interactive user. The difference in between them
5852 is that the latter is a SHELL command, whereas the former is a
5853 normal defined macro, but which is restricted to a small set of
5854 commands (the verbose output of for example list will indicate
5855 said capability). localopts are enabled for these hooks (in
5856 the parent process), causing any setting to be forgotten after
5857 the message has been sent; on-compose-cleanup can be used to
5858 perform other cleanup as necessary.
5859 During execution of these hooks S-nail will temporarily forget
5861 whether it has been started in interactive mode, (a restricted
5862 set of) COMMAND ESCAPES will always be available, and for guar‐
5863 anteed reproducibilities sake escape and ifs will be set to
5864 their defaults. The compose mode command ~^ has been espe‐
5865 cially designed for scriptability (via these hooks). The first
5866 line the hook will read on its standard input is the protocol
5867 version of said command escape, currently “0 0 2”: backward in‐
5868 compatible protocol changes have to be expected.
5869 Care must be taken to avoid deadlocks and other false control
5871 flow: if both involved processes wait for more input to happen
5872 at the same time, or one does not expect more input but the
5873 other is stuck waiting for consumption of its output, etc.
5874 There is no automatic synchronization of the hook: it will not
5875 be stopped automatically just because it, e.g., emits ‘~x’.
5876 The hooks will however receive a termination signal if the par‐
5877 ent enters an error condition. [v15 behaviour may differ] Pro‐
5878 tection against and interaction with signals is not yet given;
5879 it is likely that in the future these scripts will be placed in
5880 an isolated session, which is signalled in its entirety as nec‐
5881 essary.
5882 define ocs_signature {
5884 read version
5885 echo '~< ~/.mysig' # '~<! fortune pathtofortunefile'
5886 }
5887 set on-compose-splice=ocs_signature
5888 wysh set on-compose-splice-shell=$'\
5890 read version;\
5891 printf "hello $version! Headers: ";\
5892 echo \'~^header list\';\
5893 read status result;\
5894 echo "status=$status result=$result";\
5895 '
5896 define ocsm {
5898 read version
5899 echo Splice protocol version is $version
5900 echo '~^h l'; read hl; vput csop es subs "${hl}" 0 1
5901 if "$es" != 2
5902 echoerr 'Cannot read header list'; echo '~x'; xit
5903 endif
5904 if "$hl" !%?case ' cc'
5905 echo '~^h i cc "Diet is your <mirr.or>"'; read es;\
5906 vput csop es substring "${es}" 0 1
5907 if "$es" != 2
5908 echoerr 'Cannot insert Cc: header'; echo '~x'
5909 # (no xit, macro finishes anyway)
5910 endif
5911 endif
5912 }
5913 set on-compose-splice=ocsm
5914 on-history-addition
5916 This hook will be called if an entry is about to be added to
5917 the history of the MLE, as documented in On terminal control
5918 and line editor. It will be called with three arguments: the
5919 first is the name of the input context (see bind), the second
5920 is either an empty string or the matching history-gabby type,
5921 and the third being the complete command line to be added. The
5922 entry will not be added to history if the hook uses a non-0
5923 return. [v15 behaviour may differ] A future version will give
5924 the expanded command name as the third argument, followed by
5925 the tokenized command line as parsed in the remaining argu‐
5926 ments, the first of which is the original unexpanded command
5927 name; i.e., one may do ‘shift 4’ and will then be able to ac‐
5928 cess the positional parameters as usual via *, #, 1 etc.
5929 on-main-loop-tick
5931 This hook will be called whenever the program's main event loop
5932 is about to read the next input line. Note variable and other
5933 changes it performs are not scoped as via localopts!
5934 on-program-exit
5936 This hook will be called when the program exits, whether via
5937 exit or quit, or because the send mode is done. Note: this
5938 runs late and so terminal settings etc. are already teared
5939 down.
5940 on-resend-cleanup
5942 [v15 behaviour may differ] Identical to on-compose-cleanup, but
5943 is only triggered by resend.
5944 on-resend-enter
5946 [v15 behaviour may differ] Identical to on-compose-enter, but
5947 is only triggered by resend; currently there is no digmsg sup‐
5948 port, for example.
5949 page (Boolean) If set, each message feed through the command given
5951 for pipe is followed by a formfeed character ‘\f’.
5952 password-USER@HOST, password-HOST, password
5954 [v15-compat] Variable chain that sets a password, which is used
5955 in case none has been given in the protocol and account-spe‐
5956 cific URL; as a last resort S-nail will ask for a password on
5957 the user's terminal if the authentication method requires a
5958 password. Specifying passwords in a startup file is generally
5959 a security risk; the file should be readable by the invoking
5960 user only.
5961 password-USER@HOST
5963 [no v15-compat] (see the chain above for [v15-compat]) Set the
5964 password for ‘USER’ when connecting to ‘HOST’. If no such
5965 variable is defined for a host, the user will be asked for a
5966 password on standard input. Specifying passwords in a startup
5967 file is generally a security risk; the file should be readable
5968 by the invoking user only.
5969 piperaw (Boolean) Send messages to the pipe command without performing
5971 MIME and character set conversions.
5972 pipe-EXTENSION
5974 Identical to pipe-TYPE/SUBTYPE except that ‘EXTENSION’ (normal‐
5975 ized to lowercase using character mappings of the ASCII
5976 charset) denotes a file extension, for example ‘xhtml’. Han‐
5977 dlers registered using this method take precedence.
5978 pipe-TYPE/SUBTYPE
5980 A MIME message part identified as ‘TYPE/SUBTYPE’ (case-insensi‐
5981 tive, normalized to lowercase using character mappings of the
5982 ASCII charset) is displayed or quoted, its text is filtered
5983 through the value of this variable interpreted as a shell com‐
5984 mand. Unless noted only parts displayable as inline plain text
5985 (see copiousoutput) are covered, other MIME parts will only be
5986 considered by and for mimeview.
5987 The special value question mark ‘?’ forces interpretation of
5989 the message part as plain text, for example ‘set
5990 pipe-application/xml=?’. (This can also be achieved by adding
5991 a MIME type-marker via mimetype.) [Option]ally MIME type han‐
5992 dlers may be defined via The Mailcap files to which should be
5993 referred to for documentation of flags like copiousoutput.
5994 Question mark is indeed a trigger character to indicate flags
5995 that adjust behaviour and usage of the rest of the value, the
5996 shell command, for example:
5997 ? set pipe-X/Y='?!++=? vim ${MAILX_FILENAME_TEMPORARY}'
5999 ‘*’ The command output can be reintegrated into this
6001 MUA's normal processing: copiousoutput. Implied when
6002 using a plain ‘’.
6003 ‘#’ Only use this handler for display, not for quoting a
6004 message: x-mailx-noquote.
6005 ‘&’ Run the command asynchronously, do not wait for the
6006 handler to exit: x-mailx-async. The standard output
6007 of the command will go to /dev/null.
6008 ‘!’ The command must be run on an interactive terminal,
6009 the terminal will temporarily be released for it to
6010 run: needsterminal.
6011 ‘+’ Request creation of a zero-sized temporary file, the
6012 absolute pathname of which will be made accessible
6013 via the environment variable
6014 MAILX_FILENAME_TEMPORARY: x-mailx-tmpfile. If given
6015 twice then the file will be unlinked automatically by
6016 S-nail when the command loop is entered again at lat‐
6017 est: x-mailx-tmpfile-unlink; it is an error to use
6018 automatic deletion in conjunction with x-mailx-async.
6019 ‘=’ Normally the MIME part content is passed to the han‐
6020 dler via standard input; with this the data will in‐
6021 stead be written into MAILX_FILENAME_TEMPORARY
6022 (x-mailx-tmpfile-fill), the creation of which is im‐
6023 plied; in order to cause automatic deletion of the
6024 temporary file two plus signs ‘++’ still have to be
6025 used.
6026 ‘t’ Text type-marker: display this as normal plain text
6027 (for type-markers: The mime.types files). Identical
6028 to only giving plain ‘?’, implies copiousoutput.
6029 ‘h’ [Option] HTML type-marker: display via built-in HTML-
6030 to-text filter. Implies copiousoutput.
6031 ‘?’ To avoid ambiguities with normal shell command con‐
6032 tent another question mark can be used to forcefully
6033 terminate interpretation of remaining characters.
6034 (Any character not in this list will have the same
6035 effect.)
6036 Some information about the MIME part to be displayed is embed‐
6038 ded into the environment of the shell command:
6039 MAILX_CONTENT The MIME content-type of the part, if
6041 known, the empty string otherwise.
6042 MAILX_CONTENT_EVIDENCE If mime-counter-evidence includes the
6043 carry-around-bit (2), then this will
6044 be set to the detected MIME content-
6045 type; not only then identical to
6046 MAILX_CONTENT otherwise.
6047 MAILX_EXTERNAL_BODY_URL MIME parts of type
6048 ‘message/external-body
6049 access-type=url’ will store the access
6050 URL in this variable, it is empty oth‐
6051 erwise. URL targets should not be ac‐
6052 tivated automatically, without super‐
6053 vision.
6054 MAILX_FILENAME The filename, if any is set, the empty
6055 string otherwise.
6056 MAILX_FILENAME_GENERATED
6057 A random string.
6058 MAILX_FILENAME_TEMPORARY
6059 If temporary file creation has been
6060 requested through the command prefix
6061 this variable will be set and contain
6062 the absolute pathname of the temporary
6063 file.
6064 pop3-auth-USER@HOST, pop3-auth-HOST, pop3-auth
6066 [Option][v15-compat] Variable chain that sets the POP3 authen‐
6067 tication method. Supported are the default ‘plain’, [v15-com‐
6068 pat] ‘oauthbearer’ (see FAQ entry But, how about XOAUTH2 /
6069 OAUTHBEARER?), as well as [v15-compat] ‘external’ and
6070 ‘externanon’ for TLS secured connections which pass a client
6071 certificate via tls-config-pairs. There may be the [Option]al
6072 method [v15-compat] ‘gssapi’. ‘externanon’ does not need any
6073 user credentials, ‘external’ and ‘gssapi’ need a user, the re‐
6074 mains also require a password. ‘externanon’ solely builds upon
6075 the credentials passed via a client certificate, and is usually
6076 the way to go since tested servers do not actually follow RFC
6077 4422, and fail if additional credentials are actually passed.
6078 Unless pop3-no-apop is set the ‘plain’ method will [Option]ally
6079 be replaced with APOP if possible (see there).
6080 pop3-bulk-load-USER@HOST, pop3-bulk-load-HOST, pop3-bulk-load
6082 (Boolean)[Option] When accessing a POP3 server S-nail loads the
6083 headers of the messages, and only requests the message bodies
6084 on user request. For the POP3 protocol this means that the
6085 message headers will be downloaded twice. If this variable is
6086 set then S-nail will download only complete messages from the
6087 given POP3 server(s) instead.
6088 pop3-keepalive-USER@HOST, pop3-keepalive-HOST, pop3-keepalive
6090 [Option] POP3 servers close the connection after a period of
6091 inactivity; the standard requires this to be at least 10 min‐
6092 utes, but practical experience may vary. Setting this variable
6093 to a numeric value greater than ‘0’ causes a ‘NOOP’ command to
6094 be sent each value seconds if no other operation is performed.
6095 pop3-no-apop-USER@HOST, pop3-no-apop-HOST, pop3-no-apop
6097 (Boolean)[Option] Unless this variable is set the MD5 based
6098 ‘APOP’ authentication method will be used instead of a chosen
6099 ‘plain’ pop3-auth when connecting to a POP3 server that adver‐
6100 tises support. The advantage of ‘APOP’ is that only a single
6101 packet is sent for the user/password tuple. (Originally also
6102 that the password is not sent in clear text over the wire, but
6103 for one MD5 does not any longer offer sufficient security, and
6104 then today transport is almost ever TLS secured.) Note that
6105 pop3-no-apop-HOST requires [v15-compat].
6106 pop3-use-starttls-USER@HOST, pop3-use-starttls-HOST, pop3-use-starttls
6108 (Boolean)[Option] Causes S-nail to issue a ‘STLS’ command to
6109 make an unencrypted POP3 session TLS encrypted. This function‐
6110 ality is not supported by all servers, and is not used if the
6111 session is already encrypted by the POP3S method. Note that
6112 pop3-use-starttls-HOST requires [v15-compat].
6113 posix (Boolean) This flag enables POSIX mode, which changes behaviour
6115 of S-nail where that deviates from standardized behaviour. It
6116 is automatically squared with the environment variable
6117 POSIXLY_CORRECT, changing the one will adjust the other. The
6118 following behaviour is covered and enforced by this mechanism:
6119 • In non-interactive mode, any error encountered while load‐
6121 ing resource files during program startup will cause a pro‐
6122 gram exit, whereas in interactive mode such errors will
6123 stop loading of the currently loaded (stack of) file(s,
6124 i.e., recursively). These exits can be circumvented on a
6125 per-command base by using ignerr, one of the Command
6126 modifiers, for each command which shall be allowed to fail.
6127 • alternates will replace the list of alternate addresses in‐
6128 stead of appending to it. In addition alternates will only
6129 be honoured for any sort of message reply, and for aliases.
6130 • The variable inserting COMMAND ESCAPES ~A, ~a, ~I and ~i
6131 will expand embedded character sequences ‘\t’ horizontal
6132 tabulator and ‘\n’ line feed. [v15 behaviour may differ]
6133 For compatibility reasons this step will always be per‐
6134 formed.
6135 • Reading in messages via ~f (COMMAND ESCAPES) will use the
6136 ‘type’ not the ‘forward’ headerpick selection.
6137 • Upon changing the active folder no summary of headers will
6138 be displayed even if header is set.
6139 • Setting ignoreeof implies the behaviour described by dot.
6140 • The variable keep is extended to cover any empty mailbox,
6141 not only empty primary system mailboxes: they will be re‐
6142 moved when they are left in empty state otherwise.
6143 • Each command has an exit ? and error ! status that over‐
6144 writes that of the last command. In POSIX mode the program
6145 exit status will signal failure regardless unless all mes‐
6146 sages were successfully sent out to the mta; also see
6147 sendwait.
6148 print-alternatives
6150 (Boolean) When a MIME message part of type
6151 ‘multipart/alternative’ is displayed and it contains a subpart
6152 of type ‘text/plain’, other parts are normally discarded. Set‐
6153 ting this variable causes all subparts to be displayed, just as
6154 if the surrounding part was of type ‘multipart/mixed’.
6155 prompt The string used as a prompt in interactive mode. Whenever the
6157 variable is evaluated the value is treated as if specified
6158 within dollar-single-quotes (see Shell-style argument quoting).
6159 This (post-assignment, i.e., second) expansion can be used to
6160 embed status information, for example ?, !, account or
6161 mailbox-display.
6162 In order to embed characters which should not be counted when
6164 calculating the visual width of the resulting string, enclose
6165 the characters of interest in a pair of reverse solidus escaped
6166 brackets: ‘\[\E[0m\]’; a slot for coloured prompts is also
6167 available with the [Option]al command colour. Prompting may be
6168 prevented by setting this to the null string (aka ‘set
6169 noprompt’).
6170 prompt2 This string is used for secondary prompts, but is otherwise
6172 identical to prompt. The default is ‘.. ’.
6173 quiet (Boolean) Suppresses the printing of the version when first in‐
6175 voked.
6176 quote If set messages processed by variants of followup and reply
6178 will start with the original message, lines of which prefixed
6179 by indentprefix, taking into account quote-chars and
6180 quote-fold. No headers will be quoted when set without value
6181 or for ‘noheading’, for ‘headers’ the ‘type’ headerpick selec‐
6182 tion will be included in the quote, ‘allbodies’ embeds the
6183 (body) contents of all MIME parts, and ‘allheaders’ also in‐
6184 cludes all headers. The quoted message will be enclosed by the
6185 expansions of quote-inject-head and quote-inject-tail. Also
6186 see quote-add-cc, quote-as-attachment and ~Q, one of the
6187 COMMAND ESCAPES.
6188 quote-add-cc
6190 (Boolean) Whether senders of messages quoted via ~Q shall be
6191 made members of the carbon copies ‘Cc:’ list.
6192 quote-as-attachment
6194 (Boolean) Add the original message in its entirety as a
6195 ‘message/rfc822’ MIME attachment when replying to a message.
6196 Note this works regardless of the setting of quote.
6197 quote-chars
6199 Can be set to a string consisting of non-whitespace ASCII char‐
6200 acters which shall be treated as quotation leaders, the default
6201 being ‘>|}:’.
6202 quote-fold
6204 [Option] Can be set in addition to indentprefix, and creates a
6205 more fancy quotation in that leading quotation characters
6206 (quote-chars) are compressed and overlong lines are folded.
6207 quote-fold can be set to either one, two or three (space sepa‐
6208 rated) numeric values, which are interpreted as the maximum
6209 (goal) and the minimum line length, respectively, in a spirit
6210 rather equal to the fmt(1) program, but line- instead of para‐
6211 graph-based. The third value is used as the maximum line
6212 length instead of the first if no better break point can be
6213 found; it is ignored unless it is larger than the minimum and
6214 smaller than the maximum. If not set explicitly the minimum
6215 will reflect the goal algorithmically. The goal cannot be
6216 smaller than the length of indentprefix plus some additional
6217 pad; necessary adjustments take place silently.
6218 quote-inject-head, quote-inject-tail
6220 The strings to put before and after the text of a quoted mes‐
6221 sage, if non-empty, and respectively. The former defaults to
6222 ‘%f wrote:\n\n’. Special format directives will be expanded if
6223 possible, and if so configured the output will be folded ac‐
6224 cording to quote-fold. Format specifiers in the given strings
6225 start with a percent sign ‘%’ and expand values of the original
6226 message, unless noted otherwise. Note that names and addresses
6227 are not subject to the setting of showto. Valid format speci‐
6228 fiers are:
6229 ‘%%’ A plain percent sign.
6231 ‘%a’ The address(es) of the sender(s).
6232 ‘%d’ The date found in the ‘Date:’ header of the message
6233 when datefield is set (the default), otherwise the
6234 date when the message was received. Formatting can
6235 be controlled by assigning a strftime(3) format
6236 string to datefield (and datefield-markout-older).
6237 ‘%f’ The full name(s) (name and address, as given) of the
6238 sender(s).
6239 ‘%i’ The ‘Message-ID:’.
6240 ‘%n’ The real name(s) of the sender(s) if there is one and
6241 showname allows usage, the address(es) otherwise.
6242 ‘%r’ The senders real name(s) if there is one, the ad‐
6243 dress(es) otherwise.
6244 r-option-implicit
6246 (Boolean) Setting this option evaluates the contents of from
6247 (or, if that contains multiple addresses, sender) and passes
6248 the results onto the used (file-based) MTA as described for the
6249 -r option (empty argument case).
6250 recipients-in-cc
6252 (Boolean) When doing a reply, the original ‘From:’ and ‘To:’ as
6253 well as addressees which possibly came in via ‘Reply-To:’ and
6254 ‘Mail-Followup-To:’ are by default merged into the new ‘To:’.
6255 If this variable is set a sensitive algorithm tries to place in
6256 ‘To:’ only the sender of the message being replied to, others
6257 are placed in ‘Cc:’.
6258 record Unless this variable is defined, no copies of outgoing mail
6260 will be saved. If defined it gives the pathname, subject to
6261 the usual Filename transformations, of a folder where all new,
6262 replied-to or forwarded messages are saved: when saving to this
6263 folder fails the message is not sent, but instead saved to
6264 DEAD. The standard defines that relative (fully expanded)
6265 paths are to be interpreted relative to the current directory
6266 (cwd), to force interpretation relative to folder outfolder
6267 needs to be set in addition.
6268 record-files
6270 (Boolean) If this variable is set the meaning of record will be
6271 extended to cover messages which target only file and pipe re‐
6272 cipients (see expandaddr). These address types will not appear
6273 in recipient lists unless add-file-recipients is also set.
6274 record-resent
6276 (Boolean) If this variable is set the meaning of record will be
6277 extended to also cover the resend and Resend commands.
6278 reply-in-same-charset
6280 (Boolean) If this variable is set S-nail first tries to use the
6281 same character set of the original message for replies. If
6282 this fails, the mechanism described in Character sets is evalu‐
6283 ated as usual.
6284 reply-strings
6286 Can be set to a comma-separated list of (case-insensitive ac‐
6287 cording to ASCII rules) strings which shall be recognized in
6288 addition to the built-in strings as ‘Subject:’ reply message
6289 indicators – built-in are ‘Re:’, which is mandated by RFC 5322,
6290 as well as the german ‘Aw:’, ‘Antw:’, and the ‘Wg:’ which often
6291 has been seen in the wild; I.e., the separating colon has to be
6292 specified explicitly.
6293 reply-to A list of addresses to put into the ‘Reply-To:’ field of the
6295 message header. Members of this list are handled as if they
6296 were in the alternates list.
6297 replyto [Obsolete] Variant of reply-to.
6299 reply-to-honour
6301 Controls whether a ‘Reply-To:’ header is honoured when replying
6302 to a message via reply or Lreply. This is a quadoption; if set
6303 without a value it defaults to “yes”.
6304 reply-to-swap-in
6306 Standards like DKIM and (in conjunction with) DMARC caused many
6307 Mailing lists to use sender address rewriting in the style of
6308 ‘Name via List <list@address>’, where the original sender ad‐
6309 dress often being placed in ‘Reply-To:’. If this is set and a
6310 ‘Reply-To:’ exists, and consists of only one addressee (!),
6311 then that is used in place of the pretended sender. This works
6312 independently from reply-to-honour. The optional value, a
6313 comma-separated list of strings, offers more fine-grained con‐
6314 trol on when swapping shall be used; for now supported is
6315 mlist, here swapping occurs if the sender is a mailing-list as
6316 defined by mlist.
6317 rfc822-body-from_
6319 (Boolean) This variable can be used to force displaying a so-
6320 called ‘From_’ line for messages that are embedded into an en‐
6321 velope mail via the ‘message/rfc822’ MIME mechanism, for more
6322 visual convenience, also see mbox-rfc4155.
6323 save (Boolean) Enable saving of (partial) messages in DEAD upon in‐
6325 terrupt or delivery error.
6326 screen The number of lines that represents a “screenful” of lines,
6328 used in headers summary display, from searching, message
6329 topline display and scrolling via z. If this variable is not
6330 set S-nail falls back to a calculation based upon the detected
6331 terminal window size and the baud rate: the faster the termi‐
6332 nal, the more will be shown. Overall screen dimensions and
6333 pager usage is influenced by the environment variables COLUMNS
6334 and LINES and the variable crt.
6335 searchheaders
6337 (Boolean) Expand message list specifiers in the form ‘/x:y’ to
6338 all messages containing the substring “y” in the header field
6339 ‘x’. The string search is case insensitive.
6340 sendcharsets
6342 [Option] A comma-separated list of character set names that can
6343 be used in outgoing internet mail. The value of the variable
6344 charset-8bit is automatically appended to this list of charac‐
6345 ter sets. If no character set conversion capabilities are com‐
6346 piled into S-nail then the only supported charset is
6347 ttycharset. Also see sendcharsets-else-ttycharset and refer to
6348 the section Character sets for the complete picture of charac‐
6349 ter set conversion in S-nail.
6350 sendcharsets-else-ttycharset
6352 (Boolean)[Option] If this variable is set, but sendcharsets is
6353 not, then S-nail acts as if sendcharsets had been set to the
6354 value of the variable ttycharset. In effect this combination
6355 passes through the message data in the character set of the
6356 current locale encoding: therefore mail message text will be
6357 (assumed to be) in ISO-8859-1 encoding when send from within a
6358 ISO-8859-1 locale, and in UTF-8 encoding when send from within
6359 an UTF-8 locale.
6360 The 8-bit fallback charset-8bit never comes into play as
6362 ttycharset is implicitly assumed to be 8-bit and capable to
6363 represent all files the user may specify (as is the case when
6364 no character set conversion support is available in S-nail and
6365 the only supported character set is ttycharset, see Character
6366 sets). This might be a problem for scripts which use the sug‐
6367 gested ‘LC_ALL=C’ setting, since in this case the character set
6368 is US-ASCII by definition, so that it is better to also over‐
6369 ride ttycharset, then; and/or do something like the following
6370 in the resource file:
6371 # Avoid ASCII "propagates to 8-bit" when scripting
6373 \if ! t && "$LC_ALL" != C && "$LC_CTYPE" != C
6374 \set sendcharsets-else-ttycharset
6375 \end
6376 sender An address that is put into the ‘Sender:’ field of outgoing
6378 messages, quoting RFC 5322: the mailbox of the agent responsi‐
6379 ble for the actual transmission of the message. This field
6380 should normally not be used unless the from field contains more
6381 than one address, on which case it is required. [v15 behaviour
6382 may differ] Please expect automatic management of the from and
6383 sender relationship. Dependent on the context this address is
6384 handled as if it were in the list of alternates. Also see -r,
6385 r-option-implicit.
6386 sendmail [Obsolete] Predecessor of mta.
6388 sendmail-arguments
6390 [Obsolete] Predecessor of mta-arguments.
6391 sendmail-no-default-arguments
6393 [Obsolete](Boolean) Predecessor of mta-no-default-arguments.
6394 sendmail-progname
6396 [Obsolete] Predecessor of mta-argv0.
6397 sendwait Sending messages to the chosen mta or to command-pipe receivers
6399 (see On sending mail, and non-interactive mode) will be per‐
6400 formed asynchronously. This means that only startup errors of
6401 the respective program will be recognizable, but no delivery
6402 errors. Also, no guarantees can be made as to when the respec‐
6403 tive program will actually run, as well as to when they will
6404 have produced output.
6405 If this variable is set then child program exit is waited for,
6407 and its exit status code is used to decide about success. Re‐
6408 marks: in conflict with the POSIX standard this variable is
6409 built-in to be initially set. Another difference is that it
6410 can have a value, which is interpreted as a comma-separated
6411 list of case-insensitive strings naming specific subsystems for
6412 which synchronousness shall be ensured (only). Possible values
6413 are ‘mta’ for mta delivery, and ‘pcc’ for command-pipe re‐
6414 ceivers.
6415 showlast (Boolean) This setting causes S-nail to start at the last mes‐
6417 sage instead of the first one when opening a mail folder, as
6418 well as with from and headers.
6419 showname (Boolean) Causes S-nail to use the sender's real name instead
6421 of the plain address in the header field summary and in message
6422 specifications.
6423 showto (Boolean) Causes the recipient of the message to be shown in
6425 the header summary if the message was sent by the user.
6426 Sign The value backing ~A, one of the COMMAND ESCAPES. Also see
6428 message-inject-tail, on-compose-leave and on-compose-splice.
6429 sign The value backing ~a, one of the COMMAND ESCAPES. Also see
6431 message-inject-tail, on-compose-leave and on-compose-splice.
6432 signature
6434 [Obsolete] Please use on-compose-splice or
6435 on-compose-splice-shell or on-compose-leave and (if necessary)
6436 message-inject-tail instead!
6437 skipemptybody
6439 (Boolean) If an outgoing message has an empty first or only
6440 message part, do not send, but discard it, successfully (also
6441 see the command line option -E).
6442 smime-ca-dir, smime-ca-file
6444 [Option] Specify the location of trusted CA certificates in PEM
6445 (Privacy Enhanced Mail) for the purpose of verification of
6446 S/MIME signed messages. tls-ca-dir documents the necessary
6447 preparation steps to use the former. The set of CA certifi‐
6448 cates which are built into the TLS library can be explicitly
6449 turned off by setting smime-ca-no-defaults, and further fine-
6450 tuning is possible via smime-ca-flags.
6451 smime-ca-flags
6453 [Option] Can be used to fine-tune behaviour of the X509 CA cer‐
6454 tificate storage, and the certificate verification that is
6455 used. The actual values and their meanings are documented for
6456 tls-ca-flags.
6457 smime-ca-no-defaults
6459 (Boolean)[Option] Do not load the default CA locations that are
6460 built into the used to TLS library to verify S/MIME signed mes‐
6461 sages.
6462 smime-cipher-USER@HOST, smime-cipher
6464 [Option] Specifies the cipher to use when generating S/MIME en‐
6465 crypted messages (for the specified account). RFC 5751 man‐
6466 dates a default of ‘aes128’ (AES-128 CBC). Possible values are
6467 (case-insensitive and) in decreasing cipher strength: ‘aes256’
6468 (AES-256 CBC), ‘aes192’ (AES-192 CBC), ‘aes128’ (AES-128 CBC),
6469 ‘des3’ (DES EDE3 CBC, 168 bits; default if ‘aes128’ is not
6470 available) and ‘des’ (DES CBC, 56 bits).
6471 The actually available cipher algorithms depend on the crypto‐
6473 graphic library that S-nail uses. [Option] Support for more
6474 cipher algorithms may be available through dynamic loading via
6475 EVP_get_cipherbyname(3) (OpenSSL) if S-nail has been compiled
6476 to support this.
6477 smime-crl-dir
6479 [Option] Specifies a directory that contains files with CRLs in
6480 PEM format to use when verifying S/MIME messages.
6481 smime-crl-file
6483 [Option] Specifies a file that contains a CRL in PEM format to
6484 use when verifying S/MIME messages.
6485 smime-encrypt-USER@HOST
6487 [Option] If this variable is set, messages send to the given
6488 receiver are encrypted before sending. The value of the vari‐
6489 able must be set to the name of a file that contains a certifi‐
6490 cate in PEM format.
6491 If a message is sent to multiple recipients, each of them for
6493 whom a corresponding variable is set will receive an individu‐
6494 ally encrypted message; other recipients will continue to re‐
6495 ceive the message in plain text unless the
6496 smime-force-encryption variable is set. It is recommended to
6497 sign encrypted messages, i.e., to also set the smime-sign vari‐
6498 able. content-description-smime-message will be inspected for
6499 messages which become encrypted.
6500 smime-force-encryption
6502 (Boolean)[Option] Causes S-nail to refuse sending unencrypted
6503 messages.
6504 smime-sign
6506 (Boolean)[Option] S/MIME sign outgoing messages with the user's
6507 (from) private key and include the users certificate as a MIME
6508 attachment. Signing a message enables a recipient to verify
6509 that the sender used a valid certificate, that the email ad‐
6510 dresses in the certificate match those in the message header
6511 and that the message content has not been altered. It does not
6512 change the message text, and people will be able to read the
6513 message as usual. content-description-smime-signature will be
6514 inspected. Also see smime-sign-cert, smime-sign-include-certs
6515 and smime-sign-digest.
6516 smime-sign-cert-USER@HOST, smime-sign-cert
6518 [Option] Points to a file in PEM format. For the purpose of
6519 signing and decryption this file needs to contain the user's
6520 private key, followed by his certificate.
6521 For message signing ‘USER@HOST’ is always derived from the
6523 value of from (or, if that contains multiple addresses,
6524 sender). For the purpose of encryption the recipients public
6525 encryption key (certificate) is expected; the command certsave
6526 can be used to save certificates of signed messages (the sec‐
6527 tion Signed and encrypted messages with S/MIME gives some de‐
6528 tails). This mode of operation is usually driven by the spe‐
6529 cialized form.
6530 When decrypting messages the account is derived from the recip‐
6532 ient fields (‘To:’ and ‘Cc:’) of the message, which are
6533 searched for addresses for which such a variable is set.
6534 S-nail always uses the first address that matches, so if the
6535 same message is sent to more than one of the user addresses us‐
6536 ing different encryption keys, decryption might fail.
6537 Password-encrypted keys may be used for signing and decryption.
6539 Automated password lookup is possible via the “pseudo-hosts”
6540 ‘USER@HOST.smime-cert-key’ for the private key, and
6541 ‘USER@HOST.smime-cert-cert’ for the certificate stored in the
6542 same file. For example, the hypothetical address
6543 ‘bob@exam.ple’ could be driven with a private key / certificate
6544 pair path defined in smime-sign-cert-bob@exam.ple, and the
6545 needed passwords would then be looked up as
6546 ‘bob@exam.ple.smime-cert-key’ and
6547 ‘bob@exam.ple.smime-cert-cert’. When decrypting the value of
6548 from will be tried as a fallback to provide the necessary
6549 ‘USER@HOST’. To include intermediate certificates, use
6550 smime-sign-include-certs. The possible password sources are
6551 documented in On URL syntax and credential lookup.
6552 smime-sign-digest-USER@HOST, smime-sign-digest
6554 [Option] Specifies the message digest to use when signing
6555 S/MIME messages. Please remember that for this use case
6556 ‘USER@HOST’ refers to the variable from (or, if that contains
6557 multiple addresses, sender). The available algorithms depend
6558 on the used cryptographic library, but at least one usable
6559 built-in algorithm is ensured as a default. If possible the
6560 standard RFC 5751 will be violated by using ‘SHA512’ instead of
6561 the mandated ‘SHA1’ due to security concerns. This variable is
6562 ignored for very old (released before 2010) cryptographic li‐
6563 braries which do not offer the necessary interface: it will be
6564 logged if that happened.
6565 S-nail will try to add built-in support for the following mes‐
6567 sage digests, names are case-insensitive: ‘BLAKE2b512’,
6568 ‘BLAKE2s256’, ‘SHA3-512’, ‘SHA3-384’, ‘SHA3-256’, ‘SHA3-224’,
6569 as well as the widely available ‘SHA512’, ‘SHA384’, ‘SHA256’,
6570 ‘SHA224’, and the proposed insecure ‘SHA1’, finally ‘MD5’.
6571 More digests may [Option]ally be available through dynamic
6572 loading via the OpenSSL function EVP_get_digestbyname(3).
6573 smime-sign-include-certs-USER@HOST, smime-sign-include-certs
6575 [Option] If used, this is supposed to a consist of a comma-sep‐
6576 arated list of files, each of which containing a single cer‐
6577 tificate in PEM format to be included in the S/MIME message in
6578 addition to the smime-sign-cert certificate. This can be used
6579 to include intermediate certificates of the certificate author‐
6580 ity, in order to allow the receiver's S/MIME implementation to
6581 perform a verification of the entire certificate chain, start‐
6582 ing from a local root certificate, over the intermediate cer‐
6583 tificates, down to the smime-sign-cert. Even though top level
6584 certificates may also be included in the chain, they will not
6585 be used for the verification on the receiver's side.
6586 For the purpose of the mechanisms involved here, ‘USER@HOST’
6588 refers to the content of the internal variable from (or, if
6589 that contains multiple addresses, sender). The pseudo-host
6590 ‘USER@HOST.smime-include-certs’ will be used for performing
6591 password lookups for these certificates, shall they have been
6592 given one, therefore the lookup can be automated via the mecha‐
6593 nisms described in On URL syntax and credential lookup.
6594 smime-sign-message-digest-USER@HOST, smime-sign-message-digest
6596 [Obsolete][Option] Predecessor(s) of smime-sign-digest.
6597 smtp [Obsolete][Option] To use the built-in SMTP transport, specify
6599 a SMTP URL in mta. [v15 behaviour may differ] For compatibil‐
6600 ity reasons a set smtp is used in preference of mta.
6601 smtp-auth-USER@HOST, smtp-auth-HOST, smtp-auth
6603 [Option] Variable chain that controls the SMTP mta authentica‐
6604 tion method, possible values are ‘none’ ([no v15-compat] de‐
6605 fault), ‘plain’ ([v15-compat] default), ‘login’, [v15-compat]
6606 ‘oauthbearer’ (see FAQ entry But, how about XOAUTH2 /
6607 OAUTHBEARER?) as well as [v15-compat] ‘external’ and
6608 ‘externanon’ for TLS secured connections which pass a client
6609 certificate via tls-config-pairs. There may be the [Option]al
6610 methods ‘cram-md5’ and ‘gssapi’. ‘none’ and ‘externanon’ do
6611 not need any user credentials, ‘external’ and ‘gssapi’ require
6612 a user name, and all other methods require a user name and a
6613 password. ‘externanon’ solely builds upon the credentials
6614 passed via a client certificate, and is usually the way to go
6615 since tested servers do not actually follow RFC 4422 aka RFC
6616 4954, and fail if additional credentials are passed. Also see
6617 mta. Note that smtp-auth-HOST is [v15-compat]. ([no v15-com‐
6618 pat] Requires smtp-auth-password and smtp-auth-user. Note for
6619 smtp-auth-USER@HOST: may override dependent on sender address
6620 in the variable from.)
6621 smtp-auth-password
6623 [Option][no v15-compat] Sets the global fallback password for
6624 SMTP authentication. If the authentication method requires a
6625 password, but neither smtp-auth-password nor a matching
6626 smtp-auth-password-USER@HOST can be found, S-nail will ask for
6627 a password on the user's terminal.
6628 smtp-auth-password-USER@HOST
6630 [no v15-compat] Overrides smtp-auth-password for specific val‐
6631 ues of sender addresses, dependent upon the variable from.
6632 smtp-auth-user
6634 [Option][no v15-compat] Sets the global fallback user name for
6635 SMTP authentication. If the authentication method requires a
6636 user name, but neither smtp-auth-user nor a matching
6637 smtp-auth-user-USER@HOST can be found, S-nail will ask for a
6638 user name on the user's terminal.
6639 smtp-auth-user-USER@HOST
6641 [no v15-compat] Overrides smtp-auth-user for specific values of
6642 sender addresses, dependent upon the variable from.
6643 smtp-hostname
6645 [Option][v15-compat] Normally S-nail uses the variable from to
6646 derive the necessary ‘USER@HOST’ information in order to issue
6647 a ‘MAIL FROM:<>’ SMTP mta command. Setting smtp-hostname can
6648 be used to use the ‘USER’ from the SMTP account (mta or the
6649 user variable chain) and the given ‘HOST’ (hostname if the
6650 empty string is given, or the local hostname as a last resort).
6651 This often allows using an address that is itself valid but
6652 hosted by a provider other than from which (in from) the mes‐
6653 sage is sent. Setting this variable also influences generated
6654 ‘Message-ID:’ and ‘Content-ID:’ header fields. If the [Op‐
6655 tion]al IDNA support is available (see idna-disable) variable
6656 assignment is aborted when a necessary conversion fails.
6657 smtp-use-starttls-USER@HOST, smtp-use-starttls-HOST, smtp-use-starttls
6659 (Boolean)[Option] Causes S-nail to issue a ‘STARTTLS’ command
6660 to make an SMTP mta session TLS encrypted, i.e., to enable
6661 transport layer security.
6662 socket-connect-timeout
6664 [Option] A positive number that defines the timeout to wait for
6665 establishing a socket connection before forcing ^ERR-TIMEDOUT.
6666 socks-proxy-USER@HOST, socks-proxy-HOST, socks-proxy
6668 [Option] If set to the URL of a SOCKS5 server then all network
6669 activities are proxied through it, except for the single DNS
6670 name lookup necessary to resolve the proxy URL (unnecessary
6671 when given an already resolved IP address). It is automati‐
6672 cally squared with the environment variable SOCKS5_PROXY,
6673 changing the one will adjust the other. This example creates a
6674 local SOCKS5 proxy on port 10000 that forwards to the machine
6675 ‘HOST’ (with identity ‘USER’), and from which actual network
6676 traffic happens:
6677 $ ssh -D 10000 USER@HOST
6679 $ s-nail -Ssocks-proxy=[socks5://]localhost:10000
6680 # or =localhost:10000; no local DNS: =127.0.0.1:10000
6681 spam-interface
6683 [Option] In order to use any of the spam-related commands (like
6684 spamrate) the desired spam interface must be defined by setting
6685 this variable. Please refer to the manual section Handling
6686 spam for the complete picture of spam handling in S-nail. All
6687 or none of the following interfaces may be available:
6688 ‘spamc’ Interaction with spamc(1) from the spamassassin(1)
6690 (SpamAssassin: http://spamassassin.apache.org) suite.
6691 Different to the generic filter interface S-nail will
6692 automatically add the correct arguments for a given
6693 command and has the necessary knowledge to parse the
6694 program's output. A default value for spamc-command
6695 will have been compiled into the S-nail binary if
6696 spamc(1) has been found in PATH during compilation.
6697 Shall it be necessary to define a specific connection
6698 type (rather than using a configuration file for
6699 that), the variable spamc-arguments can be used as in
6700 for example ‘-d server.example.com -p 783’. It is
6701 also possible to specify a per-user configuration via
6702 spamc-user. Note that this interface does not in‐
6703 spect the ‘is-spam’ flag of a message for the command
6704 spamforget.
6705 ‘filter’ generic spam filter support via freely configurable
6707 hooks. This interface is meant for programs like
6708 bogofilter(1) and requires according behaviour in re‐
6709 spect to the hooks' exit status for at least the com‐
6710 mand spamrate (‘0’ meaning a message is spam, ‘1’ for
6711 non-spam, ‘2’ for unsure and any other return value
6712 indicating a hard error); since the hooks can include
6713 shell code snippets diverting behaviour can be inter‐
6714 cepted as necessary. The hooks are spamfilter-ham,
6715 spamfilter-noham, spamfilter-nospam, spamfilter-rate
6716 and spamfilter-spam; the manual section Handling spam
6717 contains examples for some programs. The process en‐
6718 vironment of the hooks will have the variable
6719 MAILX_FILENAME_GENERATED set. Note that spam score
6720 support for spamrate is not supported unless the [Op‐
6721 tion]tional regular expression support is available
6722 and the spamfilter-rate-scanscore variable is set.
6723 spam-maxsize
6725 [Option] Messages that exceed this size will not be passed
6726 through to the configured spam-interface. If unset or 0, the
6727 default of 420000 bytes is used.
6728 spamc-command
6730 [Option] The path to the spamc(1) program for the ‘spamc’
6731 spam-interface. Note that the path is not expanded, but used
6732 “as is”. A fallback path will have been compiled into the
6733 S-nail binary if the executable had been found during compila‐
6734 tion.
6735 spamc-arguments
6737 [Option] Even though S-nail deals with most arguments for the
6738 ‘spamc’ spam-interface automatically, it may at least sometimes
6739 be desirable to specify connection-related ones via this vari‐
6740 able, for example ‘-d server.example.com -p 783’.
6741 spamc-user
6743 [Option] Specify a username for per-user configuration files
6744 for the ‘spamc’ spam-interface. If this is set to the empty
6745 string then S-nail will use the name of the current user.
6746 spamfilter-ham, spamfilter-noham, spamfilter-nospam, spamfilter-rate,
6748 spamfilter-spam
6749 [Option] Command and argument hooks for the ‘filter’
6750 spam-interface. The manual section Handling spam contains ex‐
6751 amples for some programs.
6752 spamfilter-rate-scanscore
6754 [Option] Because of the generic nature of the ‘filter’
6755 spam-interface spam scores are not supported for it by default,
6756 but if the [Option]nal regular expression support is available
6757 then setting this variable can be used to overcome this re‐
6758 striction. It is interpreted as follows: first a number (dig‐
6759 its) is parsed that must be followed by a semicolon ‘;’ and an
6760 extended regular expression. Then the latter is used to parse
6761 the first output line of the spamfilter-rate hook, and, in case
6762 the evaluation is successful, the group that has been specified
6763 via the number is interpreted as a floating point scan score.
6764 ssl-ca-dir-USER@HOST, ssl-ca-dir-HOST, ssl-ca-dir, ssl-ca-file-USER@HOST,
6766 ssl-ca-file-HOST, ssl-ca-file
6767 [Obsolete][Option] Predecessors of tls-ca-file, tls-ca-dir.
6768 ssl-ca-flags-USER@HOST, ssl-ca-flags-HOST, ssl-ca-flags
6770 [Obsolete][Option] Predecessor of tls-ca-flags.
6771 ssl-ca-no-defaults-USER@HOST, ssl-ca-no-defaults-HOST, ssl-ca-no-defaults
6773 [Obsolete](Boolean)[Option] Predecessor of tls-ca-no-defaults.
6774 ssl-cert-USER@HOST, ssl-cert-HOST, ssl-cert
6776 [Obsolete][Option] Please use the Certificate slot of
6777 tls-config-pairs.
6778 ssl-cipher-list-USER@HOST, ssl-cipher-list-HOST, ssl-cipher-list
6780 [Obsolete][Option] Please use the CipherString slot of
6781 tls-config-pairs.
6782 ssl-config-file
6784 [Obsolete][Option] Predecessor of tls-config-file.
6785 ssl-config-module-USER@HOST, ssl-config-module-HOST, ssl-config-module
6787 [Obsolete][Option] Predecessor of tls-config-module.
6788 ssl-config-pairs-USER@HOST, ssl-config-pairs-HOST, ssl-config-pairs
6790 [Obsolete][Option] Predecessor of tls-config-pairs.
6791 ssl-crl-dir, ssl-crl-file
6793 [Obsolete][Option] Predecessors of tls-crl-dir, tls-crl-file.
6794 ssl-curves-USER@HOST, ssl-curves-HOST, ssl-curves
6796 [Obsolete][Option] Please use the Curves slot of
6797 tls-config-pairs.
6798 ssl-features
6800 [Obsolete][Option](Read-only) Predecessor of tls-features.
6801 ssl-key-USER@HOST, ssl-key-HOST, ssl-key
6803 [Obsolete][Option] Please use the PrivateKey slot of
6804 tls-config-pairs.
6805 ssl-method-USER@HOST, ssl-method-HOST, ssl-method
6807 [Obsolete][Option] Please use the Protocol slot of
6808 tls-config-pairs.
6809 ssl-protocol-USER@HOST, ssl-protocol-HOST, ssl-protocol
6811 [Obsolete][Option] Please use the Protocol slot of
6812 tls-config-pairs.
6813 ssl-rand-file
6815 [Obsolete][Option] Predecessor of tls-rand-file.
6816 ssl-verify-USER@HOST, ssl-verify-HOST, ssl-verify
6818 [Obsolete][Option] Predecessor of tls-verify.
6819 stealthmua
6821 If only set without an assigned value, then this setting in‐
6822 hibits the generation of the ‘Message-ID:’, ‘Content-ID:’ and
6823 ‘User-Agent:’ header fields that include obvious references to
6824 S-nail. There are two pitfalls associated with this: First,
6825 the message id of outgoing messages is not known anymore. Sec‐
6826 ond, an expert may still use the remaining information in the
6827 header to track down the originating mail user agent. If set
6828 to the value ‘noagent’, then the mentioned ‘Message-ID:’ and
6829 ‘Content-ID:’ suppression does not occur.
6830 system-mailrc
6832 (Read-only) The compiled in path of the system wide initializa‐
6833 tion file one of the Resource files: s-nail.rc.
6834 termcap ([Option]) This specifies a comma-separated list of Terminal
6836 Information Library (libterminfo, -lterminfo) and/or Termcap
6837 Access Library (libtermcap, -ltermcap) capabilities (see On
6838 terminal control and line editor, escape commas with reverse
6839 solidus ‘\’) to be used to overwrite or define entries. Note
6840 this variable will only be queried once at program startup and
6841 can thus only be specified in resource files or on the command
6842 line. It will always be inspected, regardless of whether
6843 features denotes termcap/terminfo library support via
6844 ‘,+termcap,’.
6845 String capabilities form ‘cap=value’ pairs and are expected un‐
6847 less noted otherwise. Numerics have to be notated as
6848 ‘cap#number’ where the number is expected in normal decimal no‐
6849 tation. Finally, booleans do not have any value but indicate a
6850 true or false state simply by being defined or not; this indeed
6851 means that S-nail does not support undefining an existing bool‐
6852 ean. String capability values will undergo some expansions be‐
6853 fore use: for one notations like ‘^LETTER’ stand for
6854 ‘control-LETTER’, and for clarification purposes ‘\E’ can be
6855 used to specify ‘escape’ (the control notation ‘^[’ could lead
6856 to misreadings when a left bracket follows, which it does for
6857 the standard CSI sequence); finally three letter octal se‐
6858 quences, as in ‘\061’, are supported. To specify that a termi‐
6859 nal supports 256-colours, and to define sequences that home the
6860 cursor and produce an audible bell, one might write:
6861 ? set termcap='Co#256,home=\E[H,bel=^G'
6863 The following terminal capabilities are or may be meaningful
6865 for the operation of the built-in line editor or S-nail in gen‐
6866 eral:
6867 am auto_right_margin: boolean which indicates if the
6869 right margin needs special treatment; the xenl capa‐
6870 bility is related, for more see COLUMNS. This capa‐
6871 bility is only used when backed by library support.
6872 clear or cl
6873 clear_screen: clear the screen and home cursor.
6874 (Will be simulated via ho plus cd.)
6875 colors or Co
6876 max_colors: numeric capability specifying the maximum
6877 number of colours. Note that S-nail does not actu‐
6878 ally care about the terminal beside that, but always
6879 emits ANSI / ISO 6429 escape sequences; also see
6880 colour.
6881 cr carriage_return: move to the first column in the cur‐
6882 rent row. The default built-in fallback is ‘\r’.
6883 cub1 or le
6884 cursor_left: move the cursor left one space (non-de‐
6885 structively). The default built-in fallback is ‘\b’.
6886 cuf1 or nd
6887 cursor_right: move the cursor right one space (non-
6888 destructively). The default built-in fallback is
6889 ‘\E[C’, which is used by most terminals. Less often
6890 occur ‘\EC’ and ‘\EOC’.
6891 ed or cd clr_eos: clear the screen.
6892 el or ce clr_eol: clear to the end of line. (Will be simu‐
6893 lated via ch plus repetitions of space characters.)
6894 home or ho
6895 cursor_home: home cursor.
6896 hpa or ch
6897 column_address: move the cursor (to the given column
6898 parameter) in the current row. (Will be simulated
6899 via cr plus nd.)
6900 rmcup or te / smcup or ti
6901 exit_ca_mode and enter_ca_mode, respectively: exit
6902 and enter the alternative screen ca-mode, effectively
6903 turning S-nail into a fullscreen application. This
6904 must be enabled explicitly by setting
6905 termcap-ca-mode.
6906 smkx or ks / rmkx or ke
6907 keypad_xmit and keypad_local, respectively: enable
6908 and disable the keypad. This is always enabled if
6909 available, because it seems even keyboards without
6910 keypads generate other key codes for, e.g., cursor
6911 keys in that case, and only if enabled we see the
6912 codes that we are interested in.
6913 xenl or xn
6914 eat_newline_glitch: boolean which indicates whether a
6915 newline written in the last column of an
6916 auto_right_margin indicating terminal is ignored.
6917 With it the full terminal width is available even on
6918 autowrap terminals. This will be inspected even
6919 without ‘,+termcap,’ features.
6920 Many more capabilities which describe key-sequences are docu‐
6922 mented for bind.
6923 termcap-ca-mode
6925 [Option] Allow usage of the exit_ca_mode and enter_ca_mode
6926 termcapabilities in order to enter an alternative exclusive
6927 screen, the so-called ca-mode; this usually requires special
6928 configuration of the PAGER, also dependent on the value of crt.
6929 Note this variable will only be queried once at program startup
6930 and can thus only be specified in resource files or on the com‐
6931 mand line.
6932 termcap-disable
6934 [Option] Disable any interaction with a terminal control li‐
6935 brary. If set only some generic fallback built-ins and possi‐
6936 bly the content of termcap describe the terminal to S-nail.
6937 Note this variable will only be queried once at program startup
6938 and can thus only be specified in resource files or on the com‐
6939 mand line.
6940 tls-ca-dir-USER@HOST, tls-ca-dir-HOST, tls-ca-dir, tls-ca-file-USER@HOST,
6942 tls-ca-file-HOST, tls-ca-file
6943 [Option] Directory and file, respectively, for pools of trusted
6944 CA certificates in PEM (Privacy Enhanced Mail) format, for the
6945 purpose of verification of TLS server certificates. Concurrent
6946 use is possible, the file is loaded once needed first, the di‐
6947 rectory lookup is performed anew as a last resort whenever nec‐
6948 essary. The CA certificate pool built into the TLS library can
6949 be disabled via tls-ca-no-defaults, further fine-tuning is pos‐
6950 sible via tls-ca-flags. The directory search requires special
6951 filename conventions, please see
6952 SSL_CTX_load_verify_locations(3) and verify(1) (or
6953 c_rehash(1)).
6954 tls-ca-flags-USER@HOST, tls-ca-flags-HOST, tls-ca-flags
6956 [Option] Can be used to fine-tune behaviour of the X509 CA cer‐
6957 tificate storage, and the certificate verification that is used
6958 (also see tls-verify). The value is expected to consist of a
6959 comma-separated list of configuration directives, with any in‐
6960 tervening whitespace being ignored. The directives directly
6961 map to flags that can be passed to X509_STORE_set_flags(3),
6962 which are usually defined in a file openssl/x509_vfy.h, and the
6963 availability of which depends on the used TLS library version:
6964 a directive without mapping is ignored (error log subject to
6965 debug). Directives currently understood (case-insensitively)
6966 include:
6967 no-alt-chains
6969 If the initial chain is not trusted, do not attempt
6970 to build an alternative chain. Setting this flag
6971 will make OpenSSL certificate verification match that
6972 of older OpenSSL versions, before automatic building
6973 and checking of alternative chains has been imple‐
6974 mented; also see trusted-first.
6975 no-check-time
6976 Do not check certificate/CRL validity against current
6977 time.
6978 partial-chain
6979 By default partial, incomplete chains which cannot be
6980 verified up to the chain top, a self-signed root cer‐
6981 tificate, will not verify. With this flag set, a
6982 chain succeeds to verify if at least one signing cer‐
6983 tificate of the chain is in any of the configured
6984 trusted stores of CA certificates. The OpenSSL man‐
6985 ual page SSL_CTX_load_verify_locations(3) gives some
6986 advise how to manage your own trusted store of CA
6987 certificates.
6988 strict Disable workarounds for broken certificates.
6989 trusted-first
6990 Try building a chain using issuers in the trusted
6991 store first to avoid problems with server-sent legacy
6992 intermediate certificates. Newer versions of OpenSSL
6993 support alternative chain checking and enable it by
6994 default, resulting in the same behaviour; also see
6995 no-alt-chains.
6996 tls-ca-no-defaults-USER@HOST, tls-ca-no-defaults-HOST, tls-ca-no-defaults
6998 (Boolean)[Option] Do not load the default CA locations that are
6999 built into the used to TLS library to verify TLS server cer‐
7000 tificates.
7001 tls-config-file
7003 [Option] If this variable is set CONF_modules_load_file(3) (if
7004 announced via ‘,+modules-load-file,’ in tls-features) is used
7005 to allow resource file based configuration of the TLS library.
7006 This happens once the library is used first, which may also be
7007 early during startup (logged with verbose)! If a non-empty
7008 value is given then the given file, after performing Filename
7009 transformations, will be used instead of the TLS libraries
7010 global default, and it is an error if the file cannot be
7011 loaded. The application name will always be passed as
7012 ‘s-nail’. Some TLS libraries support application-specific con‐
7013 figuration via resource files loaded like this, please see
7014 tls-config-module.
7015 tls-config-module-USER@HOST, tls-config-module-HOST, tls-config-module
7017 [Option] If file based application-specific configuration via
7018 tls-config-file is available, announced as ‘,+ctx-config,’ by
7019 tls-features, indicating availability of SSL_CTX_config(3),
7020 then, it becomes possible to use a central TLS configuration
7021 file for all programs, including s-nail, for example
7022 # Register a configuration section for s-nail
7024 s-nail = mailx_master
7025 # The top configuration section creates a relation
7026 # in between dynamic SSL configuration and an actual
7027 # program specific configuration section
7028 [mailx_master]
7029 ssl_conf = mailx_tls_config
7030 # And that program specific configuration section now
7031 # can map diverse tls-config-module names to sections,
7032 # as in: tls-config-module=account_xy
7033 [mailx_tls_config]
7034 account_xy = mailx_account_xy
7035 account_yz = mailx_account_yz
7036 [mailx_account_xy]
7037 MinProtocol = TLSv1.2
7038 Curves=P-521
7039 [mailx_account_yz]
7040 CipherString = TLSv1.2:!aNULL:!eNULL:
7041 MinProtocol = TLSv1.1
7042 Options = Bugs
7043 tls-config-pairs-USER@HOST, tls-config-pairs-HOST, tls-config-pairs
7045 [Option] The value of this variable chain will be interpreted
7046 as a comma-separated list of directive/value pairs. Directives
7047 and values need to be separated by equals signs ‘=’, any white‐
7048 space surrounding pair members is removed. Keys are (usually)
7049 case-insensitive. Different to when placing these pairs in a
7050 tls-config-module section of a tls-config-file, commas ‘,’ need
7051 to be escaped with a reverse solidus ‘\’ when included in
7052 pairs; also different: if the equals sign ‘=’ is preceded with
7053 an asterisk ‘*’ Filename transformations will be performed on
7054 the value; it is an error if these fail. Unless proper support
7055 is announced by tls-features (‘,+conf-ctx,’) only the keys be‐
7056 low are supported, otherwise the pairs will be used directly as
7057 arguments to the function SSL_CONF_cmd(3).
7058 Certificate Filename of a TLS client certificate (chain) re‐
7060 quired by some servers. Fallback support via
7061 SSL_CTX_use_certificate_chain_file(3). Filename
7062 transformations are performed. PrivateKey will
7063 be set to the same value if not initialized ex‐
7064 plicitly. Some services support so-called
7065 ‘external’ authentication if a TLS client cer‐
7066 tificate was successfully presented during con‐
7067 nection establishment (“connecting is
7068 authenticating”).
7069 CipherString A list of ciphers for TLS connections, see
7070 ciphers(1). By default no list of ciphers is
7071 set, resulting in a Protocol-specific list of ci‐
7072 phers (the protocol standards define lists of ac‐
7073 ceptable ciphers; possibly cramped by the used
7074 TLS library). Fallback support via
7075 SSL_CTX_set_cipher_list(3).
7076 Ciphersuites A list of ciphers used for TLSv1.3 connections,
7077 see ciphers(1). These will be joined onto the
7078 list of ciphers from CipherString. Available if
7079 tls-features announces ‘,+ctx-set-ciphersuites,’,
7080 as necessary via SSL_CTX_set_ciphersuites(3).
7081 Curves A list of supported elliptic curves, if applica‐
7082 ble. By default no curves are set. Fallback
7083 support via SSL_CTX_set1_curves_list(3), if
7084 available.
7085 MaxProtocol, MinProtocol
7086 The maximum and minimum supported TLS versions,
7087 respectively. Available if tls-features an‐
7088 nounces ‘,+ctx-set-maxmin-proto,’, as necessary
7089 via SSL_CTX_set_max_proto_version(3) and
7090 SSL_CTX_set_min_proto_version(3); these fallbacks
7091 use an internal parser which understands the
7092 strings ‘SSLv3’, ‘TLSv1’, ‘TLSv1.1’, ‘TLSv1.2’,
7093 ‘TLSv1.3’, and the special value ‘None’, which
7094 disables the given limit.
7095 Options Various flags to set. Fallback via
7096 SSL_CTX_set_options(3), in which case any other
7097 value but (exactly) ‘Bugs’ results in an error.
7098 PrivateKey Filename of the private key in PEM format of a
7099 TLS client certificate. If unset, the value of
7100 Certificate is used. Filename transformations
7101 are performed. Fallback via
7102 SSL_CTX_use_PrivateKey_file(3).
7103 Protocol The used TLS protocol. If tls-features announces
7104 ‘,+conf-ctx,’ or ‘ctx-set-maxmin-proto’ then us‐
7105 ing MaxProtocol and MinProtocol is preferable.
7106 Fallback is SSL_CTX_set_options(3), driven via an
7107 internal parser which understands the strings
7108 ‘SSLv3’, ‘TLSv1’, ‘TLSv1.1’, ‘TLSv1.2’,
7109 ‘TLSv1.3’, and the special value ‘ALL’. Multiple
7110 protocols may be given as a comma-separated list,
7111 any whitespace is ignored, an optional plus sign
7112 ‘+’ prefix enables, a hyphen-minus ‘-’ prefix
7113 disables a protocol, so that ‘-ALL, TLSv1.2’ en‐
7114 ables only the TLSv1.2 protocol.
7115 tls-crl-dir, tls-crl-file
7117 [Option] Specify a directory / a file, respectively, that con‐
7118 tains a CRL in PEM format to use when verifying TLS server cer‐
7119 tificates.
7120 tls-features
7122 [Option](Read-only) This expands to a comma-separated list of
7123 the TLS library identity and optional features. To ease sub‐
7124 string matching the string starts and ends with a comma. Cur‐
7125 rently supported identities are ‘libressl’ (LibreSSL) ,
7126 ‘libssl-0x30000’ (OpenSSL v3.0.0 series), ‘libssl-0x10100’
7127 (OpenSSL v1.1.x series) and ‘libssl-0x10000’ (elder OpenSSL se‐
7128 ries, other clones). Optional features are preceded with a
7129 plus sign ‘+’ when available, and with a hyphen-minus ‘-’ oth‐
7130 erwise.
7131 Currently known features are ‘conf-ctx’ (tls-config-pairs),
7133 ‘ctx-config’ (tls-config-module), ‘ctx-set-ciphersuites’
7134 (Ciphersuites slot of tls-config-pairs), ‘ctx-set-maxmin-proto’
7135 (tls-config-pairs), ‘modules-load-file’ (tls-config-file), and
7136 ‘tls-rand-file’ (tls-rand-file).
7137 tls-fingerprint-USER@HOST, tls-fingerprint-HOST, tls-fingerprint
7139 [Option] It is possible to replace the verification of the con‐
7140 nection peer certificate against the entire local pool of CAs
7141 (for more see Encrypted network communication) with the compar‐
7142 ison against a precalculated certificate message digest, the
7143 so-called fingerprint, to be specified as the used
7144 tls-fingerprint-digest. This fingerprint can for example be
7145 calculated with ‘tls fingerprint HOST’.
7146 tls-fingerprint-digest-USER@HOST, tls-fingerprint-digest-HOST,
7148 tls-fingerprint-digest
7149 [Option] The message digest to be used when creating TLS cer‐
7150 tificate fingerprints, the defaults, if available, in test or‐
7151 der, being ‘BLAKE2s256’, ‘SHA256’. For the complete list of
7152 digest algorithms refer to smime-sign-digest.
7153 tls-rand-file
7155 [Option] If tls-features announces ‘,+tls-rand-file,’ then this
7156 will be queried to find a file with random entropy data which
7157 can be used to seed the P(seudo)R(andom)N(umber)G(enerator),
7158 see RAND_load_file(3). The default filename
7159 (RAND_file_name(3), normally ~/.rnd) will be used if this vari‐
7160 able is not set or empty, or if the Filename transformations
7161 fail. Shall seeding the PRNG have been successful,
7162 RAND_write_file(3) will be called to update the entropy. Re‐
7163 marks: libraries which do not announce this feature seed the
7164 PRNG by other means.
7165 tls-verify-USER@HOST, tls-verify-HOST, tls-verify
7167 [Option] Variable chain that sets the action to be performed if
7168 an error occurs during TLS server certificate validation
7169 against the specified or default trust stores tls-ca-dir,
7170 tls-ca-file, or the TLS library built-in defaults (unless usage
7171 disallowed via tls-ca-no-defaults), and as fine-tuned via
7172 tls-ca-flags. Valid (case-insensitive) values are ‘strict’
7173 (fail and close connection immediately), ‘ask’ (ask whether to
7174 continue on standard input), ‘warn’ (show a warning and con‐
7175 tinue), ‘ignore’ (do not perform validation). The default is
7176 ‘ask’.
7177 toplines If defined, gives the number of lines of a message to be dis‐
7179 played with the command top; if unset, the first five lines are
7180 printed, if set to 0 the variable screen is inspected. If the
7181 value is negative then its absolute value will be used for un‐
7182 signed right shifting (see vexpr) the screen height.
7183 topsqueeze
7185 (Boolean) If set then the top command series will strip adja‐
7186 cent empty lines and quotations.
7187 ttycharset
7189 The character set of the terminal S-nail operates on, and the
7190 one and only supported character set that S-nail can use if no
7191 character set conversion capabilities have been compiled into
7192 it, in which case it defaults to ISO-8859-1. Otherwise it de‐
7193 faults to UTF-8. Sufficient locale support provided the de‐
7194 fault will be preferably deduced from the locale environment if
7195 that is set (for example LC_CTYPE, see there for more); runtime
7196 locale changes will be reflected by ttycharset except during
7197 the program startup phase and if -S had been used to freeze the
7198 given value. Refer to the section Character sets for the com‐
7199 plete picture about character sets.
7200 typescript-mode
7202 (Boolean) A special multiplex variable that disables all vari‐
7203 ables and settings which result in behaviour that interferes
7204 with running S-nail in script(1); it sets colour-disable,
7205 line-editor-disable and (before startup completed only)
7206 termcap-disable. Unsetting it does not restore the former
7207 state of the covered settings.
7208 umask For a safe-by-default policy the process file mode creation
7210 mask umask(2) will be set to ‘0077’ on program startup after
7211 the resource files have been loaded, and unless this variable
7212 is set. By assigning this an empty value the active setting
7213 will not be changed, otherwise the given value will be made the
7214 new file mode creation mask. Child processes inherit the file
7215 mode creation mask of their parent.
7216 user-HOST, user
7218 [v15-compat] Variable chain that sets a global fallback user
7219 name, used in case none has been given in the protocol and ac‐
7220 count-specific URL. This variable defaults to the name of the
7221 user who runs S-nail.
7222 v15-compat
7224 Enable upward compatibility with S-nail version 15.0 in respect
7225 to which configuration options are available and how they are
7226 handled. If set to a non-empty value the command modifier wysh
7227 is implied and thus enforces Shell-style argument quoting over
7228 Old-style argument quoting for all commands which support both.
7229 This manual uses [v15-compat] and [no v15-compat] to refer to
7230 the new and the old way of doing things, respectively.
7231 verbose Verbose mode enables logging of informational context messages.
7233 Historically a (Boolean) variable, this can either be set mul‐
7234 tiple times (what the command line option -v uses), or be as‐
7235 signed a numeric value in order to increase verbosity. Assign‐
7236 ing the value 0 disables verbosity and thus (almost) equals
7237 unset. The maximum number is 3. Also see debug.
7238 version, version-date, version-hexnum, version-major, version-minor,
7240 version-update
7241 (Read-only) S-nail version information: the first variable is a
7242 string with the complete version identification, the second the
7243 release date in ISO 8601 notation without time. The third is a
7244 32-bit hexadecimal number with the upper 8 bits storing the ma‐
7245 jor, followed by the minor and update version numbers which oc‐
7246 cupy 12 bits each. The latter three variables contain only
7247 decimal digits: the major, minor and update version numbers.
7248 The output of the command version will include this informa‐
7249 tion.
7250 writebackedited
7252 If this variable is set messages modified using the edit or
7253 visual commands are written back to the current folder when it
7254 is quit; it is only honoured for writable folders in MBOX for‐
7255 mat, though. Note that the editor will be pointed to the raw
7256 message content in that case, i.e., neither MIME decoding nor
7257 decryption will have been performed, and proper mbox-rfc4155
7258 ‘From_’ quoting of newly added or edited content is also left
7259 as an exercise to the user.
7260
7262 The term “environment variable” should be considered an indication that
7263 these variables are either standardized as vivid parts of process envi‐
7264 ronments, or that they are commonly found in there. The process environ‐
7265 ment is inherited from the sh(1) once S-nail is started, and unless oth‐
7266 erwise explicitly noted handling of the following variables transparently
7267 integrates into that of the INTERNAL VARIABLES from S-nail's point of
7268 view. This means they can be managed via set and unset, causing auto‐
7269 matic program environment updates (to be inherited by newly created child
7270 processes).
7271 In order to integrate other environment variables equally they need to be
7273 imported (linked) with the command environ. This command can also be
7274 used to set and unset non-integrated environment variables from scratch,
7275 sufficient system support provided. The following example, applicable to
7276 a POSIX shell, sets the COLUMNS environment variable for S-nail only, and
7277 beforehand exports the EDITOR in order to affect any further processing
7278 in the running shell:
7279 $ EDITOR="vim -u ${HOME}/.vimrc"
7281 $ export EDITOR
7282 $ COLUMNS=80 s-nail -R
7283 COLUMNS The user's preferred width in column positions for the terminal
7285 screen. Queried and used once on program startup in interac‐
7286 tive or batch (-#) mode, actively managed for child processes
7287 and the MLE (see On terminal control and line editor) in inter‐
7288 active mode thereafter. Non-interactive mode always uses, and
7289 the fallback default is a compile-time constant, by default 80
7290 columns. If in batch mode COLUMNS and LINES are both set but
7291 not both are usable (empty, not a number, or 0) at program
7292 startup, then the real terminal screen size will be (tried to
7293 be) determined once. (Normally the sh(1) manages these vari‐
7294 ables, and unsets them for pipe specifications etc.)
7295 DEAD The name of the (mailbox) folder to use for saving aborted mes‐
7297 sages if save is set; this defaults to ~/dead.letter. If the
7298 variable debug is set no output will be generated, otherwise
7299 the contents of the file will be replaced. Except shell globs
7300 Filename transformations (also see folder) will be performed.
7301 EDITOR Pathname of the text editor to use for the edit command and ~e
7303 (see COMMAND ESCAPES); VISUAL is used for a more display ori‐
7304 ented editor.
7305 HOME The user's home directory. This variable is only used when it
7307 resides in the process environment. The calling user's home
7308 directory will be used instead if this directory does not ex‐
7309 ist, is not accessible or cannot be read; it will always be
7310 used for the root user. (No test for being writable is per‐
7311 formed to allow usage by non-privileged users within read-only
7312 jails, but dependent on settings this directory is a default
7313 write target for, for example, DEAD, MBOX and more.)
7314 LC_ALL, LC_CTYPE, LANG
7316 [Option] The (names in lookup order of the) locale(7) (and / or
7317 see setlocale(3)) which indicates the used Character sets.
7318 Runtime changes trigger automatic updates of the entire locale
7319 system, which includes updating ttycharset (except during
7320 startup if the variable has been frozen via -S).
7321 LINES The user's preferred number of lines for the terminal screen.
7323 The behaviour is as described for COLUMNS, yet the compile-time
7324 constant used in non-interactive mode and as a fallback de‐
7325 faults to 24 (lines).
7326 LISTER Pathname of the directory lister to use in the folders command
7328 when operating on local mailboxes. Default is ls(1) (path
7329 search through SHELL).
7330 LOGNAME Upon startup S-nail will actively ensure that this variable
7332 refers to the name of the user who runs S-nail, in order to be
7333 able to pass a verified name to any newly created child
7334 process.
7335 MAIL Is used as the user's primary system mailbox unless inbox is
7337 set. If the environmental fallback is also not set, a built-in
7338 compile-time default is used. This is assumed to be an abso‐
7339 lute pathname.
7340 MAILCAPS [Option] Override the default path search of The Mailcap files:
7342 any existing file therein will be loaded in sequence, appending
7343 any content to the list of MIME type handler directives. The
7344 RFC 1524 standard imposed default value is assigned otherwise:
7345 ‘~/.mailcap:/etc/mailcap:/usr/etc/mailcap:
7346 /usr/local/etc/mailcap’. (The default value is a compile-time
7347 [Option].)
7348 MAILRC Is used as a startup file instead of ~/.mailrc if set. In or‐
7350 der to avoid side-effects from configuration files scripts
7351 should either set this variable to /dev/null or the -: command
7352 line option should be used.
7353 MAILX_NO_SYSTEM_RC
7355 If this variable is set then reading of s-nail.rc (aka
7356 system-mailrc) at startup is inhibited, i.e., the same effect
7357 is achieved as if S-nail had been started up with the option -:
7358 (and according argument) or -n. This variable is only used
7359 when it resides in the process environment.
7360 MBOX The name of the user's secondary mailbox file. A logical sub‐
7362 set of the special Filename transformations (also see folder)
7363 are supported. The default is ~/mbox. Traditionally this MBOX
7364 is used as the file to save messages from the primary system
7365 mailbox that have been read. Also see Message states.
7366 NETRC [v15-compat][Option] This variable overrides the default loca‐
7368 tion of the user's ~/.netrc file.
7369 PAGER Pathname of the program to use for backing the command more,
7371 and when the crt variable enforces usage of a pager for output.
7372 The default paginator is more(1) (path search through SHELL).
7373 S-nail inspects the contents of this variable: if its contains
7375 the string “less” then a non-existing environment variable LESS
7376 will be set to (the portable) ‘RI’, likewise for “lv” LV will
7377 optionally be set to ‘-c’. Also see colour-pager.
7378 PATH A colon-separated list of directories that is searched by the
7380 shell when looking for commands, for example
7381 ‘/bin:/usr/bin:/usr/local/bin’.
7382 POSIXLY_CORRECT
7384 This environment entry is automatically squared with posix.
7385 SHELL The shell to use for the commands !, shell, the ~! COMMAND
7387 ESCAPES and when starting subprocesses. A default shell is
7388 used if this environment variable is not defined.
7389 SOCKS5_PROXY
7391 This environment entry is automatically squared with
7392 socks-proxy.
7393 SOURCE_DATE_EPOCH
7395 Specifies a time in seconds since the Unix epoch (1970-01-01)
7396 to be used in place of the current time. This variable is
7397 looked up upon program startup, and its existence will switch
7398 S-nail to a reproducible mode (https://reproducible-builds.org)
7399 which uses deterministic random numbers, a special fixated
7400 pseudo LOGNAME and more. This operation mode is used for de‐
7401 velopment and by software packagers. [v15 behaviour may dif‐
7402 fer] Currently an invalid setting is only ignored, rather than
7403 causing a program abortion.
7404 $ SOURCE_DATE_EPOCH=`date +%s` s-nail
7406 TERM [Option] The terminal type for which output is to be prepared.
7408 For extended colour and font control please refer to Coloured
7409 display, and for terminal management in general to On terminal
7410 control and line editor.
7411 TMPDIR Except for the root user this variable defines the directory
7413 for temporary files to be used instead of /tmp (or the given
7414 compile-time constant) if set, existent, accessible as well as
7415 read- and writable. This variable is only used when it resides
7416 in the process environment, but S-nail will ensure at startup
7417 that this environment variable is updated to contain a usable
7418 temporary directory.
7419 USER Identical to LOGNAME (see there), but this variable is not
7421 standardized, should therefore not be used, and is only cor‐
7422 rected if already set.
7423 VISUAL Pathname of the text editor to use for the visual command and
7425 ~v (see COMMAND ESCAPES); EDITOR is used for a less display
7426 oriented editor.
7427
7429 ~/.mailcap, /etc/mailcap
7430 [Option] Personal and system-wide MIME type handler definition
7431 files, see The Mailcap files. (The shown names are part of the
7432 RFC 1524 standard search path MAILCAPS.)
7433 ~/.mailrc, s-nail.rc
7435 User-specific and system-wide files giving initial commands,
7436 the Resource files. (The used filenames come from MAILRC and
7437 system-mailrc, respectively.)
7438 ~/mbox The default value for MBOX.
7440 ~/.mime.types, /etc/mime.types
7442 Personal and system-wide MIME types, see The mime.types files.
7443 ~/.netrc [v15-compat][Option] The default location of the user's .netrc
7445 file – the section The .netrc file documents the file format.
7446 The used path can be set via NETRC.
7447 /dev/null
7449 The data sink null(4).
7450 ~/.rnd [Option] Possible location for persistent random entropy seed
7452 storage, see tls-rand-file.
7453 Resource files
7455 Upon startup S-nail reads in several resource files, in order:
7456 s-nail.rc
7458 System wide initialization file (system-mailrc). Reading of
7459 this file can be suppressed, either by using the -: (and ac‐
7460 cording argument) or -n command line options, or by setting the
7461 ENVIRONMENT variable MAILX_NO_SYSTEM_RC.
7462 ~/.mailrc
7464 File giving initial commands. A different file can be chosen
7465 by setting the ENVIRONMENT variable MAILRC. Reading of this
7466 file can be suppressed with the -: command line option.
7467 mailx-extra-rc
7469 Defines a startup file to be read after all other resource
7470 files. It can be used to specify settings that are not under‐
7471 stood by other mailx(1) implementations, for example.
7472 The content of these files is interpreted as follows:
7474 • The whitespace characters space, tabulator and newline, as well as
7476 those defined by the variable ifs, are removed from the beginning and
7477 end of input lines.
7478 • Empty lines are ignored.
7479 • Any other line is interpreted as a command. It may be spread over
7480 multiple input lines if the newline character is “escaped” by placing
7481 a reverse solidus character ‘\’ as the last character of the line;
7482 whereas any leading whitespace of follow lines is ignored, trailing
7483 whitespace before a escaped newline remains in the input.
7484 • If the line (content) starts with the number sign ‘#’ then it is a
7485 comment-command and also ignored. (The comment-command is a real
7486 command, which does nothing, and therefore the usual follow lines
7487 mechanism applies!)
7488 Errors while loading these files are subject to the settings of errexit
7490 and posix. More files with syntactically equal content can be sourceed.
7491 The following, saved in a file, would be an examplary content:
7492 # This line is a comment command. And y\
7494 es, it is really continued here.
7495 set debug \
7496 verbose
7497 set editheaders
7498 The mime.types files
7500 As stated in HTML mail and MIME attachments S-nail needs to learn about
7501 MIME (Multipurpose Internet Mail Extensions) media types in order to
7502 classify message and attachment content. One source for them are
7503 mime.types files, the loading of which can be controlled by setting the
7504 variable mimetypes-load-control. Another is the command mimetype, which
7505 also offers access to S-nails MIME type cache. mime.types files have the
7506 following syntax:
7507 type/subtype extension [extension ...]
7509 # For example text/html html htm
7510 where ‘type/subtype’ define the MIME media type, as standardized in RFC
7512 2046: ‘type’ is used to declare the general type of data, while the
7513 ‘subtype’ specifies a specific format for that type of data. One or mul‐
7514 tiple filename ‘extension’s, separated by whitespace, can be bound to the
7515 media type format. Comments may be introduced anywhere on a line with a
7516 number sign ‘#’, causing the remaining line to be discarded. S-nail also
7517 supports an extended, non-portable syntax in especially crafted files,
7518 which can be loaded via the alternative value syntax of
7519 mimetypes-load-control, and prepends an optional ‘type-marker’:
7520 [type-marker ]type/subtype extension [extension ...]
7522 The following type markers are supported:
7524 ? Treat message parts with this content as plain text.
7526 ?t The same as plain ?.
7527 ?h Treat message parts with this content as HTML tagsoup. If the
7528 [Option]al HTML-tagsoup-to-text converter is not available
7529 treat the content as plain text instead.
7530 ?H Likewise ?h, but instead of falling back to plain text require
7531 an explicit content handler to be defined.
7532 ?q If no handler can be found a text message is displayed which
7533 says so. This can be annoying, for example signatures serve a
7534 contextual purpose, their content is of no use by itself. This
7535 marker will avoid displaying the text message.
7536 Further reading: for sending messages: mimetype,
7538 mime-allow-text-controls, mimetypes-load-control. For reading etc. mes‐
7539 sages: HTML mail and MIME attachments, The Mailcap files, mimetype,
7540 mime-counter-evidence, mimetypes-load-control, pipe-TYPE/SUBTYPE,
7541 pipe-EXTENSION.
7542 The Mailcap files
7544 [Option] RFC 1524 defines a “User Agent Configuration Mechanism” to be
7545 used to inform mail user agent programs about the locally installed fa‐
7546 cilities for handling various data formats, i.e., about commands and how
7547 they can be used to display, edit et cetera MIME part contents, as well
7548 as a default path search that includes multiple possible locations of re‐
7549 source files, and the MAILCAPS environment variable to overwrite that.
7550 Handlers found from doing the path search will be cached, the command
7551 mailcap operates on that cache, and the variable mailcap-disable will
7552 suppress automatic loading, and usage of any mailcap handlers. HTML mail
7553 and MIME attachments gives a general overview of how MIME types are han‐
7554 dled.
7555 “Mailcap” files consist of a set of newline separated entries. Comment
7557 lines start with a number sign ‘#’ (in the first column!) and are ig‐
7558 nored. Empty lines are ignored. All other lines are interpreted as
7559 mailcap entries. An entry definition may be split over multiple lines by
7560 placing the reverse solidus character ‘\’ last in all but the final line.
7561 The standard does not specify how leading whitespace of successive lines
7562 is to be treated, therefore they are retained.
7563 “Mailcap” entries consist of a number of semicolon ‘;’ separated fields.
7565 The first two fields are mandatory and must occur in the specified order,
7566 the remaining fields are optional and may appear in any order. Leading
7567 and trailing whitespace of field content is ignored (removed). The re‐
7568 verse solidus ‘\’ character can be used to escape any following character
7569 including semicolon and itself in the content of the second field, and in
7570 value parts of any optional key/value field.
7571 The first field defines the MIME ‘TYPE/SUBTYPE’ the entry is about to
7573 handle (case-insensitively). If the subtype is specified as an asterisk
7574 ‘*’ the entry is meant to match all subtypes of the named type, e.g.,
7575 ‘audio/*’ would match any audio type. The second field is the view shell
7576 command used to display MIME parts of the given type.
7577 Data consuming shell commands will be fed message (MIME part) data on
7579 standard input unless one or more instances of the (unquoted) string ‘%s’
7580 are used: these formats will be replaced with a temporary file(name) that
7581 has been prefilled with the parts data. Data producing shell commands
7582 are expected to generata data on their standard output unless that format
7583 is used. In all cases any given ‘%s’ format is replaced with a properly
7584 shell quoted filename. When a command requests a temporary file via ‘%s’
7585 then that will be removed again, as if the x-mailx-tmpfile and
7586 x-mailx-tmpfile-fill flags had been set; unless the command requests
7587 x-mailx-async the x-mailx-tmpfile-unlink flag is also implied; see below
7588 for more.
7589 Optional fields define single-word flags (case-insensitive), or key /
7591 value pairs consisting of a case-insensitive keyword, an equals sign ‘=’,
7592 and a shell command; whitespace surrounding the equals sign is removed.
7593 Optional fields include the following:
7594 compose A program that can be used to compose a new body or body part
7596 in the given format. (Currently unused.)
7597 composetyped
7599 Similar to the compose field, but is to be used when the com‐
7600 posing program needs to specify the ‘Content-type:’ header
7601 field to be applied to the composed data. (Currently unused.)
7602 copiousoutput
7604 A flag field which indicates that the output of the view com‐
7605 mand is integrable into S-nails normal visual display. It is
7606 mutually exclusive with needsterminal.
7607 description
7609 A textual description that describes this type of data. The
7610 text may optionally be enclosed within double quotation marks
7611 ‘"’.
7612 edit A program that can be used to edit a body or body part in the
7614 given format. (Currently unused.)
7615 nametemplate
7617 This field specifies a filename format for the ‘%s’ format used
7618 in the shell command fields, in which ‘%s’ will be replaced by
7619 a random string. (The filename is also stored in and passed to
7620 subprocesses via MAILX_FILENAME_TEMPORARY.) The standard says
7621 this is “only expected to be relevant in environments where
7622 filename extensions are meaningful”, and so this field is ig‐
7623 nored unless the ‘%s’ is a prefix, optionally followed by
7624 (ASCII) alphabetic and numeric characters, the underscore and
7625 the period. For example, to specify that a JPG file is to be
7626 passed to an image viewer with a name ending in ‘.jpg’,
7627 ‘nametemplate=%s.jpg’ can be used.
7628 needsterminal
7630 This flag field indicates that the given shell command must be
7631 run on an interactive terminal. S-nail will temporarily re‐
7632 lease the terminal to the given command in interactive mode, in
7633 non-interactive mode this entry will be entirely ignored; this
7634 flag implies x-mailx-noquote.
7635 print A program that can be used to print a message or body part in
7637 the given format. (Currently unused.)
7638 test Specifies a program to be run to test some condition, for exam‐
7640 ple, the machine architecture, or the window system in use, to
7641 determine whether or not this mailcap entry applies. If the
7642 test fails, a subsequent mailcap entry should be sought; also
7643 see x-mailx-test-once. Standard I/O of the test program is
7644 redirected from and to /dev/null, and the format ‘%s’ is not
7645 supported (the data does not yet exist).
7646 textualnewlines
7648 A flag field which indicates that this type of data is line-
7649 oriented and that, if encoded in ‘base64’, all newlines should
7650 be converted to canonical form (CRLF) before encoding, and will
7651 be in that form after decoding. (Currently unused.)
7652 x11-bitmap
7654 Names a file, in X11 bitmap (xbm) format, which points to an
7655 appropriate icon to be used to visually denote the presence of
7656 this kind of data. This field is not used by S-nail.
7657 x-mailx-async
7659 Extension flag field that denotes that the given view command
7660 shall be executed asynchronously, without blocking S-nail.
7661 Cannot be used in conjunction with needsterminal; the standard
7662 output of the command will go to /dev/null.
7663 x-mailx-noquote
7665 An extension flag field that indicates that even a
7666 copiousoutput view command shall not be used when quoteing mes‐
7667 sages, as it would by default.
7668 x-mailx-test-once
7670 Extension flag which denotes whether the given test command
7671 shall be evaluated once only with its exit status being cached.
7672 This is handy if some global unchanging condition is to be
7673 queried, like “running under the X Window System”.
7674 x-mailx-tmpfile
7676 Extension flag field that requests creation of a zero-sized
7677 temporary file, the name of which is to be placed in the envi‐
7678 ronment variable MAILX_FILENAME_TEMPORARY. It is an error to
7679 use this flag with commands that include a ‘%s’ format (because
7680 that is implemented by means of this temporary file).
7681 x-mailx-tmpfile-fill
7683 Normally the MIME part content is passed to the handler via
7684 standard input; if this flag is set then the data will instead
7685 be written into the implied x-mailx-tmpfile. In order to cause
7686 deletion of the temporary file you will have to set
7687 x-mailx-tmpfile-unlink explicitly! It is an error to use this
7688 flag with commands that include a ‘%s’ format.
7689 x-mailx-tmpfile-unlink
7691 Extension flag field that requests that the temporary file
7692 shall be deleted automatically when the command loop is entered
7693 again at latest. It is an error to use this flag with commands
7694 that include a ‘%s’ format, or in conjunction with
7695 x-mailx-async. x-mailx-tmpfile is implied.
7696 x-mailx-last-resort
7698 An extension flag that indicates that this handler shall only
7699 be used as a last resort, when no other source (see HTML mail
7700 and MIME attachments) provides a MIME handler.
7701 x-mailx-ignore
7703 An extension that enforces that this handler is not used at
7704 all.
7705 The standard includes the possibility to define any number of additional
7707 fields, prefixed by ‘x-’. Flag fields apply to the entire “Mailcap” en‐
7708 try — in some unusual cases, this may not be desirable, but differentia‐
7709 tion can be accomplished via separate entries, taking advantage of the
7710 fact that subsequent entries are searched if an earlier one does not pro‐
7711 vide enough information. For example, if a view command needs to specify
7712 the needsterminal flag, but the compose command shall not, the following
7713 will help out the latter:
7714 application/postscript; ps-to-terminal %s; needsterminal
7716 application/postscript; ps-to-terminal %s; compose=idraw %s
7717 In value parts of command fields any occurrence of the format string ‘%t’
7719 will be replaced by the ‘TYPE/SUBTYPE’ specification. Any named parame‐
7720 ter from a messages' ‘Content-type:’ field may be embedded into the com‐
7721 mand line using the format ‘%{’ followed by the parameter name and a
7722 closing brace ‘}’ character. The entire parameter should appear as a
7723 single command line argument, regardless of embedded spaces, shell quot‐
7724 ing will be performed by the RFC 1524 processor, thus:
7725 # Message
7727 Content-type: multipart/mixed; boundary=42
7728 # Mailcap file
7730 multipart/*; /usr/local/bin/showmulti \
7731 %t %{boundary} ; composetyped = /usr/local/bin/makemulti
7732 # Executed shell command
7734 /usr/local/bin/showmulti multipart/mixed 42
7735 Note that S-nail does not support handlers for multipart MIME parts as
7737 shown in this example (as of today). It does not support the additional
7738 formats ‘%n’ and ‘%F’. An example file, also showing how to properly
7739 deal with the expansion of ‘%s’, which includes any quotes that are nec‐
7740 essary to make it a valid shell argument by itself and thus will cause
7741 undesired behaviour when placed in additional user-provided quotes:
7742 # Comment line
7744 text/richtext; richtext %s; copiousoutput
7745 text/x-perl; perl -cWT %s; nametemplate = %s.pl
7747 # Exit EX_TEMPFAIL=75 on signal
7749 application/pdf; \
7750 infile=%s\; \
7751 trap "rm -f ${infile}" EXIT\; \
7752 trap "exit 75" INT QUIT TERM\; \
7753 mupdf "${infile}"; \
7754 test = [ -n "${DISPLAY}" ]; \
7755 nametemplate = %s.pdf; x-mailx-async
7756 application/pdf; pdftotext -layout - -; copiousoutput
7757 application/*; echo "This is \\"%t\\" but \
7759 is 50 \% Greek to me" \; < %s head -c 512 | cat -vet; \
7760 copiousoutput; x-mailx-noquote; x-mailx-last-resort
7761 Further reading: HTML mail and MIME attachments, The mime.types files,
7763 mimetype, MAILCAPS, mime-counter-evidence, pipe-TYPE/SUBTYPE,
7764 pipe-EXTENSION.
7765 The .netrc file
7767 User credentials for machine accounts (see On URL syntax and credential
7768 lookup) can be placed in the .netrc file, which will be loaded and cached
7769 when requested by netrc-lookup. The default location ~/.netrc may be
7770 overridden by the NETRC environment variable. As long as syntax con‐
7771 straints are honoured the file source may be replaced with the output of
7772 the shell command set in netrc-pipe, to load an encrypted file, for exam‐
7773 ple. The cache can be managed with the command netrc.
7774 The file consists of space, tabulator or newline separated tokens. This
7776 parser implements a superset of the original BSD syntax, but users should
7777 nonetheless be aware of portability glitches, shall their .netrc be us‐
7778 able across multiple programs and platforms:
7779 • BSD only supports double quotation marks, for example ‘password "pass
7781 with spaces"’.
7782 • BSD (only?) supports escaping of single characters via a reverse
7783 solidus (a space could be escaped via ‘\ ’), in- as well as outside
7784 of a quoted string. This method is assumed to be present, and will
7785 actively be used to quote double quotation marks ‘"’ and reverse
7786 solidus ‘\’ characters inside the login and password tokens, for ex‐
7787 ample for display purposes.
7788 • BSD does not require a final quotation mark of the last user input
7789 token.
7790 • The original BSD (Berknet) parser also supported a format which al‐
7791 lowed tokens to be separated with commas – whereas at least Hewlett-
7792 Packard still seems to support this syntax, this parser does not!
7793 • As a non-portable extension some widely-used programs support shell-
7794 style comments: if an input line starts, after any amount of white‐
7795 space, with a number sign ‘#’, then the rest of the line is ignored.
7796 • Whereas other programs may require that the .netrc file is accessible
7797 by only the user if it contains a password token for any other login
7798 than “anonymous”, this parser will always require these strict per‐
7799 missions.
7800 Of the following list of supported tokens this parser uses (and caches)
7802 machine, login and password. An existing default entry will not be used.
7803 machine name
7805 The hostname of the entries' machine, lowercase-normalized be‐
7806 fore use. Any further file content, until either end-of-file
7807 or the occurrence of another machine or a default first-class
7808 token is bound (only related) to the machine name.
7809 As an extension that should not be the cause of any worries
7811 this parser supports a single wildcard prefix for name:
7812 machine *.example.com login USER password PASS
7814 machine pop3.example.com login USER password PASS
7815 machine smtp.example.com login USER password PASS
7816 which would match ‘xy.example.com’ as well as
7818 ‘pop3.example.com’, but neither ‘example.com’ nor
7819 ‘local.smtp.example.com’. In the example neither
7820 ‘pop3.example.com’ nor ‘smtp.example.com’ will be matched by
7821 the wildcard, since the exact matches take precedence (it is
7822 however faster to specify it the other way around).
7823 default This is the same as machine except that it is a fallback entry
7825 that is used shall none of the specified machines match; only
7826 one default token may be specified, and it must be the last
7827 first-class token.
7828 login name
7830 The user name on the remote machine.
7831 password string
7833 The user's password on the remote machine.
7834 account string
7836 Supply an additional account password. This is merely for FTP
7837 purposes.
7838 macdef name
7840 Define a macro. A macro is defined with the specified name; it
7841 is formed from all lines beginning with the next line and con‐
7842 tinuing until a blank line is (consecutive newline characters
7843 are) encountered. (Note that macdef entries cannot be utilized
7844 by multiple machines, too, but must be defined following the
7845 machine they are intended to be used with.) If a macro named
7846 init exists, it is automatically run as the last step of the
7847 login process. This is merely for FTP purposes.
7848
7850 An example configuration
7851 # This example assumes v15.0 compatibility mode
7852 set v15-compat
7853 # Request strict TLL transport layer security checks
7855 set tls-verify=strict
7856 # Where are the up-to-date TLS certificates?
7858 # (Since we manage up-to-date ones explicitly, do not use any,
7859 # possibly outdated, default certificates shipped with OpenSSL)
7860 #set tls-ca-dir=/etc/ssl/certs
7861 set tls-ca-file=/etc/ssl/certs/ca-certificates.crt
7862 set tls-ca-no-defaults
7863 #set tls-ca-flags=partial-chain
7864 wysh set smime-ca-file="${tls-ca-file}" \
7865 smime-ca-no-defaults #smime-ca-flags="${tls-ca-flags}"
7866 # This could be outsourced to a central configuration file via
7868 # tls-config-file plus tls-config-module if the used library allows.
7869 # CipherString: explicitly define the list of ciphers, which may
7870 # improve security, especially with protocols older than TLS v1.2.
7871 # See ciphers(1). Possibly best to only use tls-config-pairs-HOST
7872 # (or -USER@HOST), as necessary, again..
7873 # Note that TLSv1.3 uses Ciphersuites= instead, which will join
7874 # with CipherString (if protocols older than v1.3 are allowed)
7875 # Curves: especially with TLSv1.3 curves selection may be desired.
7876 # MinProtocol,MaxProtocol: do not use protocols older than TLS v1.2.
7877 # Change this only when the remote server does not support it:
7878 # maybe use chain support via tls-config-pairs-HOST / -USER@HOST
7879 # to define such explicit exceptions, then, e.g.,
7880 # MinProtocol=TLSv1.1
7881 if "$tls-features" =% ,+ctx-set-maxmin-proto,
7882 wysh set tls-config-pairs='\
7883 CipherString=TLSv1.2:!aNULL:!eNULL:@STRENGTH,\
7884 Curves=P-521:P-384:P-256,\
7885 MinProtocol=TLSv1.1'
7886 else
7887 wysh set tls-config-pairs='\
7888 CipherString=TLSv1.2:!aNULL:!eNULL:@STRENGTH,\
7889 Curves=P-521:P-384:P-256,\
7890 Protocol=-ALL\,+TLSv1.1 \, +TLSv1.2\, +TLSv1.3'
7891 endif
7892 # Essential setting: select allowed character sets
7894 set sendcharsets=utf-8,iso-8859-1
7895 # A very kind option: when replying to a message, first try to
7897 # use the same encoding that the original poster used herself!
7898 set reply-in-same-charset
7899 # When replying, do not merge From: and To: of the original message
7901 # into To:. Instead old From: -> new To:, old To: -> merge Cc:.
7902 set recipients-in-cc
7903 # When sending messages, wait until the Mail-Transfer-Agent finishs.
7905 # Only like this you will be able to see errors reported through the
7906 # exit status of the MTA (including the built-in SMTP one)!
7907 set sendwait
7908 # Only use built-in MIME types, no mime.types(5) files
7910 set mimetypes-load-control
7911 # Default directory where we act in (relative to $HOME)
7913 set folder=mail
7914 # A leading "+" (often) means: under *folder*
7915 # *record* is used to save copies of sent messages
7916 set MBOX=+mbox.mbox DEAD=+dead.txt \
7917 record=+sent.mbox record-files record-resent
7918 # Make "file mymbox" and "file myrec" go to..
7920 shortcut mymbox %:+mbox.mbox myrec +sent.mbox
7921 # Not really optional, e.g., for S/MIME
7923 set from='Your Name <address@exam.ple>'
7924 # It may be necessary to set hostname and/or smtp-hostname
7926 # if the "SERVER" of mta and "domain" of from do not match.
7927 # The `urlencode' command can be used to encode USER and PASS
7928 set mta=(smtps?|submissions?)://[USER[:PASS]@]SERVER[:PORT] \
7929 smtp-auth=login/plain... \
7930 smtp-use-starttls
7931 # Never refuse to start into interactive mode, and more
7933 set emptystart \
7934 colour-pager crt= \
7935 followup-to followup-to-honour=ask-yes fullnames \
7936 history-file=+.s-nailhist history-size=-1 history-gabby \
7937 mime-counter-evidence=0b1111 \
7938 prompt='?\$?!\$!/\$^ERRNAME[\$account#\$mailbox-display]? ' \
7939 reply-to-honour=ask-yes \
7940 umask=
7941 # Only include the selected header fields when typing messages
7943 headerpick type retain from_ date from to cc subject \
7944 message-id mail-followup-to reply-to
7945 # ...when forwarding messages
7946 headerpick forward retain subject date from to cc
7947 # ...when saving message, etc.
7948 #headerpick save ignore ^Original-.*$ ^X-.*$
7949 # Some mailing lists
7951 mlist '@xyz-editor\.xyz$' '@xyzf\.xyz$'
7952 mlsubscribe '^xfans@xfans\.xyz$'
7953 # Handle a few file extensions (to store MBOX databases)
7955 filetype bz2 'bzip2 -dc' 'bzip2 -zc' \
7956 gz 'gzip -dc' 'gzip -c' xz 'xz -dc' 'xz -zc' \
7957 zst 'zstd -dc' 'zstd -19 -zc' \
7958 zst.pgp 'gpg -d | zstd -dc' 'zstd -19 -zc | gpg -e'
7959 # A real life example of a very huge free mail provider
7961 # Instead of directly placing content inside `account',
7962 # we `define' a macro: like that we can switch "accounts"
7963 # from within *on-compose-splice*, for example!
7964 define XooglX {
7965 set folder=~/spool/XooglX inbox=+syste.mbox sent=+sent
7966 set from='Your Name <address@examp.ple>'
7967 set pop3-no-apop-pop.gmXil.com
7969 shortcut pop %:pop3s://pop.gmXil.com
7970 shortcut imap %:imaps://imap.gmXil.com
7971 # Or, entirely IMAP based setup
7972 #set folder=imaps://imap.gmail.com record="+[Gmail]/Sent Mail" \
7973 # imap-cache=~/spool/cache
7974 set mta=smtp://USER:PASS@smtp.gmXil.com smtp-use-starttls
7976 # Alternatively:
7977 set mta=smtps://USER:PASS@smtp.gmail.com:465
7978 }
7979 account XooglX {
7980 \call XooglX
7981 }
7982 # Here is a pretty large one which does not allow sending mails
7984 # if there is a domain name mismatch on the SMTP protocol level,
7985 # which would bite us if the value of from does not match, e.g.,
7986 # for people who have a sXXXXeforge project and want to speak
7987 # with the mailing list under their project account (in from),
7988 # still sending the message through their normal mail provider
7989 define XandeX {
7990 set folder=~/spool/XandeX inbox=+syste.mbox sent=+sent
7991 set from='Your Name <address@exam.ple>'
7992 shortcut pop %:pop3s://pop.yaXXex.com
7994 shortcut imap %:imaps://imap.yaXXex.com
7995 set mta=smtps://USER:PASS@smtp.yaXXex.com:465 \
7997 hostname=yaXXex.com smtp-hostname=
7998 }
7999 account XandeX {
8000 \call Xandex
8001 }
8002 # Create some new commands so that, e.g., `ls /tmp' will..
8004 commandalias lls '!ls ${LS_COLOUR_FLAG} -aFlrS'
8005 commandalias llS '!ls ${LS_COLOUR_FLAG} -aFlS'
8006 set pipe-message/external-body='?* echo $MAILX_EXTERNAL_BODY_URL'
8008 # We do not support gpg(1) directly yet. But simple --clearsign'd
8010 # message parts can be dealt with as follows:
8011 define V {
8012 localopts yes
8013 wysh set pipe-text/plain=$'?*#++=?\
8014 < "${MAILX_FILENAME_TEMPORARY}" awk \
8015 -v TMPFILE="${MAILX_FILENAME_TEMPORARY}" \'\
8016 BEGIN{done=0}\
8017 /^-----BEGIN PGP SIGNED MESSAGE-----/,/^$/ {\
8018 if(done++ != 0)\
8019 next;\
8020 print "--- GPG --verify ---";\
8021 system("gpg --verify " TMPFILE " 2>&1");\
8022 print "--- GPG --verify ---";\
8023 print "";\
8024 next;\
8025 }\
8026 /^-----BEGIN PGP SIGNATURE-----/,\
8027 /^-----END PGP SIGNATURE-----/{\
8028 next;\
8029 }\
8030 {print}\
8031 \''
8032 print
8033 }
8034 commandalias V '\'call V
8035 When storing passwords in ~/.mailrc appropriate permissions should be set
8037 on this file with ‘$ chmod 0600 ~/.mailrc’. If the [Option]al
8038 netrc-lookup is available user credentials can be stored in the central
8039 ~/.netrc file instead; e.g., here is a different version of the example
8040 account that sets up SMTP and POP3:
8041 define XandeX {
8043 set folder=~/spool/XandeX inbox=+syste.mbox sent=+sent
8044 set from='Your Name <address@exam.ple>'
8045 set netrc-lookup
8046 # Load an encrypted ~/.netrc by uncommenting the next line
8047 #set netrc-pipe='gpg -qd ~/.netrc.pgp'
8048 set mta=smtps://smtp.yXXXXx.ru:465 \
8050 smtp-hostname= hostname=yXXXXx.com
8051 set pop3-keepalive=240 pop3-no-apop-pop.yXXXXx.ru
8052 commandalias xp fi pop3s://pop.yXXXXx.ru
8053 }
8054 account XandeX {
8055 \call XandeX
8056 }
8057 and, in the ~/.netrc file:
8059 machine *.yXXXXx.ru login USER password PASS
8061 This configuration should now work just fine:
8063 $ echo text | s-nail -dvv -AXandeX -s Subject user@exam.ple
8065 S/MIME step by step
8067 [Option] The first thing that is needed for Signed and encrypted messages
8068 with S/MIME is a personal certificate, and a private key. The certifi‐
8069 cate contains public information, in particular a name and email ad‐
8070 dress(es), and the public key that can be used by others to encrypt mes‐
8071 sages for the certificate holder (the owner of the private key), and to
8072 verify signed messages generated with that certificate('s private key).
8073 Whereas the certificate is included in each signed message, the private
8074 key must be kept secret. It is used to decrypt messages that were previ‐
8075 ously encrypted with the public key, and to sign messages.
8076 For personal use it is recommended to get a S/MIME certificate from one
8078 of the major CAs on the Internet. Many CAs offer such certificates for
8079 free. Usually offered is a combined certificate and private key in
8080 PKCS#12 format which S-nail does not accept directly. To convert it to
8081 PEM format, the following shell command can be used; please read on for
8082 how to use these PEM files.
8083 $ openssl pkcs12 -in cert.p12 -out certpem.pem -clcerts -nodes
8085 $ # Alternatively
8086 $ openssl pkcs12 -in cert.p12 -out cert.pem -clcerts -nokeys
8087 $ openssl pkcs12 -in cert.p12 -out key.pem -nocerts -nodes
8088 There is also https://www.CAcert.org which issues client and server cer‐
8090 tificates to members of their community for free; their root certificate
8091 (https://www.cacert.org/certs/root.crt) is often not in the default set
8092 of trusted CA root certificates, though, which means their root certifi‐
8093 cate has to be downloaded separately, and needs to be part of the S/MIME
8094 certificate validation chain by including it in smime-ca-dir or as a
8095 vivid member of the smime-ca-file. But let us take a step-by-step tour
8096 on how to setup S/MIME with a certificate from CAcert.org despite this
8097 situation!
8098 First of all you will have to become a member of the CAcert.org commu‐
8100 nity, simply by registrating yourself via the web interface. Once you
8101 are, create and verify all email addresses you want to be able to create
8102 signed and encrypted messages for/with using the corresponding entries of
8103 the web interface. Now ready to create S/MIME certificates, so let us
8104 create a new “client certificate”, ensure to include all email addresses
8105 that should be covered by the certificate in the following web form, and
8106 also to use your name as the “common name”.
8107 Create a private key and a certificate request on your local computer
8109 (please see the manual pages of the used commands for more in-depth
8110 knowledge on what the used arguments etc. do):
8111 $ openssl req -nodes -newkey rsa:4096 -keyout key.pem -out creq.pem
8113 Afterwards copy-and-paste the content of “creq.pem” into the certificate-
8115 request (CSR) field of the web form on the CAcert.org website (you may
8116 need to unfold some “advanced options” to see the corresponding text
8117 field). This last step will ensure that your private key (which never
8118 left your box) and the certificate belong together (through the public
8119 key that will find its way into the certificate via the certificate-re‐
8120 quest). You are now ready and can create your CAcert certified certifi‐
8121 cate. Download and store or copy-and-paste it as “pub.crt”.
8122 Yay. In order to use your new S/MIME setup a combined private key/public
8124 key (certificate) file has to be created:
8125 $ cat key.pem pub.crt > ME@HERE.com.paired
8127 This is the file S-nail will work with. If you have created your private
8129 key with a passphrase then S-nail will ask you for it whenever a message
8130 is signed or decrypted, unless this operation has been automated as de‐
8131 scribed in Signed and encrypted messages with S/MIME. Set the following
8132 variables to henceforth use S/MIME (setting smime-ca-file is of interest
8133 for verification only):
8134 ? set smime-ca-file=ALL-TRUSTED-ROOT-CERTS-HERE \
8136 smime-sign-cert=ME@HERE.com.paired \
8137 smime-sign-digest=SHA512 \
8138 smime-sign from=myname@my.host
8139 Using CRLs with S/MIME or TLS
8141 [Option] Certification authorities (CAs) issue certificate revocation
8142 lists (CRLs) on a regular basis. These lists contain the serial numbers
8143 of certificates that have been declared invalid after they have been is‐
8144 sued. Such usually happens because the private key for the certificate
8145 has been compromised, because the owner of the certificate has left the
8146 organization that is mentioned in the certificate, etc. To seriously use
8147 S/MIME or TLS verification, an up-to-date CRL is required for each
8148 trusted CA. There is otherwise no method to distinguish between valid
8149 and invalidated certificates. S-nail currently offers no mechanism to
8150 fetch CRLs, nor to access them on the Internet, so they have to be re‐
8151 trieved by some external mechanism.
8152 S-nail accepts CRLs in PEM format only; CRLs in DER format must be con‐
8154 verted, like, e.g.:
8155 $ openssl crl -inform DER -in crl.der -out crl.pem
8157 To tell S-nail about the CRLs, a directory that contains all CRL files
8159 (and no other files) must be created. The smime-crl-dir or tls-crl-dir
8160 variables, respectively, must then be set to point to that directory.
8161 After that, S-nail requires a CRL to be present for each CA that is used
8162 to verify a certificate.
8163
8165 In general it is a good idea to turn on debug (-d) and / or verbose (-v,
8166 twice) if something does not work well. Very often a diagnostic message
8167 can be produced that leads to the problems' solution.
8168 S-nail shortly hangs on startup
8170 This can have two reasons, one is the necessity to wait for a file lock
8171 and cannot be helped, the other being that S-nail calls the function
8172 uname(2) in order to query the nodename of the box (sometimes the real
8173 one is needed instead of the one represented by the internal variable
8174 hostname). One may have varying success by ensuring that the real host‐
8175 name and ‘localhost’ have entries in /etc/hosts, or, more generally, that
8176 the name service is properly setup – and does hostname(1) return the ex‐
8177 pected value? Does this local hostname have a domain suffix? RFC 6762
8178 standardized the link-local top-level domain ‘.local’, try again after
8179 adding an (additional) entry with this extension.
8180 I cannot login to Google mail (via OAuth)
8182 Since 2014 some free service providers classify programs as “less secure”
8183 unless they use a special authentication method (OAuth 2.0) which was not
8184 standardized for non-HTTP protocol authentication token query until Au‐
8185 gust 2015 (RFC 7628).
8186 Different to Kerberos / GSSAPI, which is developed since the mid of the
8188 1980s, where a user can easily create a local authentication ticket for
8189 her- and himself with the locally installed kinit(1) program, that proto‐
8190 col has no such local part but instead requires a world-wide-web query to
8191 create or fetch a token; since there is no local cache this query would
8192 have to be performed whenever S-nail is invoked (in interactive sessions
8193 situation may differ).
8194 S-nail does not directly support OAuth. It, however, supports XOAUTH2 /
8196 OAUTHBEARER, see But, how about XOAUTH2 / OAUTHBEARER? If that is not
8197 used it is necessary to declare S-nail a “less secure app” (on the
8198 providers account web page) in order to read and send mail. However, it
8199 also seems possible to take the following steps instead:
8200 1. give the provider the number of a mobile phone,
8202 2. enable “2-Step Verification”,
8203 3. create an application specific password (16 characters), and
8204 4. use that special password instead of the real Google account pass‐
8205 word in S-nail (for more on that see the section On URL syntax and
8206 credential lookup).
8207 But, how about XOAUTH2 / OAUTHBEARER?
8209 Following up I cannot login to Google mail (via OAuth) one OAuth-based
8210 authentication method is available: the OAuth 2.0 bearer token usage as
8211 standardized in RFC 6750 (according SASL mechanism in RFC 7628), also
8212 known as XOAUTH2 and OAUTHBEARER, allows fetching a temporary access to‐
8213 ken via the web that can locally be used as a password. The protocol is
8214 simple and extendable, token updates or even password changes via a sim‐
8215 ple TLS secured server login would be possible in theory, but today a web
8216 browser and an external support tool are prerequisites for using this au‐
8217 thentication method. The token times out and must be periodically re‐
8218 freshed via the web.
8219 Some hurdles must be taken before being able to use this method. Using
8221 GMail as an example, an application (that is a name) must be registered,
8222 for which credentials, a “client ID” and a “client secret”, need to be
8223 created and saved locally (in a secure way). These initial configuration
8224 steps can be performed at
8225 https://console.developers.google.com/apis/credentials Thereafter a re‐
8226 fresh token can be requested; a python program to do this for GMail ac‐
8227 counts is https://github.com/google/gmail-oauth2-tools/raw/master/python/
8228 oauth2.py:
8229 $ python oauth2.py --user=EMAIL \
8231 --client-id=THE-ID --client-secret=THE-SECRET \
8232 --generate_oauth2_token
8233 To authorize token, visit this url and follow the directions:
8234 https://accounts.google.com/o/oauth2/auth?client_id=...
8235 Enter verification code: ...
8236 Refresh Token: ...
8237 Access Token: ...
8238 Access Token Expiration Seconds: 3600
8239 $ # Of which the last three are actual token responses.
8240 $ # Thereafter access tokens can regularly be refreshed
8241 $ # via the created refresh token (read on)
8242 The generated refresh token must also be saved locally (securely). The
8244 procedure as a whole can be read at https://github.com/google/gmail-
8245 oauth2-tools/wiki/OAuth2DotPyRunThrough Since periodic timers are not yet
8246 supported, keeping an access token up-to-date (from within S-nail) can
8247 only be performed via the hook on-main-loop-tick, or (for sending only)
8248 on-compose-enter (for more on authentication please see the section On
8249 URL syntax and credential lookup):
8250 set on-main-loop-tick=o-m-l-t on-compose-enter=o-c-e
8252 define o-m-l-t {
8253 xcall update_access_token
8254 }
8255 define o-c-e {
8256 xcall update_access_token
8257 }
8258 set access_token_=0
8260 define update_access_token {
8261 local set i epoch_sec epoch_nsec
8262 vput vexpr i epoch
8263 eval set $i # set epoch_sec/_nsec of vexpr epoch
8264 vput vexpr i + $access_token_ 2100
8265 if $epoch_sec -ge $i
8266 vput ! password python oauth2.py --user=EMAIL \
8267 --client-id=THE-ID --client-secret=THE-SECRET \
8268 --refresh-token=THE-REFRESH-TOKEN |\
8269 sed '1b PASS;d; :PASS s/^.\{1,\}:\(.\{1,\}\)$/\1/'
8270 vput csop password trim "$password"
8271 if -n "$verbose"
8272 echo password is <$password>
8273 endif
8274 set access_token_=$epoch_sec
8275 endif
8276 }
8277 Not "defunctional", but the editor key does not work
8279 Two thinkable situations: the first is a shadowed sequence; setting
8280 debug, or the most possible verbose mode, causes a printout of the bind
8281 tree after that is built; being a cache, this happens only upon startup
8282 or after modifying bindings.
8283 Or second, terminal libraries (see On terminal control and line editor,
8285 bind, termcap) may report different codes than the terminal really sends,
8286 rendering bindings dysfunctional because expected and received data do
8287 not match; the verbose listing of bindings will show the byte sequences
8288 that are expected. (One common source of problems is that the — possibly
8289 even non-existing — keypad is not turned on, and the resulting layout re‐
8290 ports the keypad control codes for the normal keyboard keys.)
8291 To overcome the situation use for example the program cat(1) with its op‐
8293 tion -v, if available, to see the byte sequences which are actually pro‐
8294 duced by keypresses, and use the variable termcap to make S-nail aware of
8295 them. The terminal this is typed on produces some unexpected sequences,
8296 here for an example the shifted home key:
8297 ? set verbose
8299 ? bind*
8300 # 1B 5B=[ 31=1 3B=; 32=2 48=H
8301 bind base :kHOM z0
8302 ? x
8303 $ cat -v
8304 ^[[H
8305 $ s-nail -v -Stermcap='kHOM=\E[H'
8306 ? bind*
8307 # 1B 5B=[ 48=H
8308 bind base :kHOM z0
8309 Can S-nail git-send-email?
8311 Yes. Put (at least parts of) the following in your ~/.gitconfig:
8312 [sendemail]
8314 smtpserver = /usr/bin/s-nail
8315 smtpserveroption = -t
8316 #smtpserveroption = -Sexpandaddr
8317 smtpserveroption = -Athe-account-you-need
8318 ##
8319 suppresscc = all
8320 suppressfrom = false
8321 assume8bitEncoding = UTF-8
8322 #to = /tmp/OUT
8323 confirm = always
8324 chainreplyto = true
8325 multiedit = false
8326 thread = true
8327 quiet = true
8328 annotate = true
8329 Newer git(1) versions (v2.33.0) added the option sendmailCmd. Patches
8331 can also be send directly, for example:
8332 $ git format-patch -M --stdout HEAD^ |
8334 s-nail -A the-account-you-need -t RECEIVER
8335 Howto handle stale dotlock files
8337 folder sometimes fails to open MBOX mail databases because creation of
8338 dotlock files is impossible due to existing but unowned lock files.
8339 S-nail does not offer an option to deal with those files, because it is
8340 considered a site policy what counts as unowned, and what not. The site
8341 policy is usually defined by administrator(s), and expressed in the con‐
8342 figuration of a locally installed MTA (for example Postfix
8343 ‘stale_lock_time=500s’). Therefore the suggestion:
8344 $ </dev/null s-nail -s 'MTA: be no frog, handle lock' $LOGNAME
8346 By sending a mail to yourself the local MTA can use its normal queue
8348 mechanism to try the delivery multiple times, finally decide a lock file
8349 has become stale, and remove it.
8350
8352 [Option]ally there is IMAP client support available. This part of the
8353 program is obsolete and will vanish in v15 with the large MIME and I/O
8354 layer rewrite, because it uses old-style blocking I/O and makes excessive
8355 use of signal based long code jumps. Support can hopefully be readded
8356 later based on a new-style I/O, with SysV signal handling. In fact the
8357 IMAP support had already been removed from the codebase, but was rein‐
8358 stantiated on user demand: in effect the IMAP code is at the level of
8359 S-nail v14.8.16 (with imapcodec being the sole exception), and should be
8360 treated with some care.
8361 IMAP uses the ‘imap://’ and ‘imaps://’ protocol prefixes, and an IMAP-
8363 based folder may be used. IMAP URLs (paths) undergo inspections and pos‐
8364 sible transformations before use (and the command imapcodec can be used
8365 to manually apply them to any given argument). Hierarchy delimiters are
8366 normalized, a step which is configurable via the imap-delim variable
8367 chain, but defaults to the first seen delimiter otherwise. S-nail sup‐
8368 ports internationalised IMAP names, and en- and decodes the names from
8369 and to the ttycharset as necessary and possible. If a mailbox name is
8370 expanded (see Filename transformations) to an IMAP mailbox, all names
8371 that begin with `+' then refer to IMAP mailboxes below the folder target
8372 box, while folder names prefixed by `@' refer to folders below the hier‐
8373 archy base, so the following will list all folders below the current one
8374 when in an IMAP mailbox: ‘folders @’.
8375 Note: some IMAP servers do not accept the creation of mailboxes in the
8377 hierarchy base, but require that they are created as subfolders of `IN‐
8378 BOX' – with such servers a folder name of the form
8379 imaps://mylogin@imap.myisp.example/INBOX.
8381 should be used (the last character is the server's hierarchy delimiter).
8383 The following IMAP-specific commands exist:
8384 cache Only applicable to cached IMAP mailboxes; takes a message list
8386 and reads the specified messages into the IMAP cache.
8387 connect If operating in disconnected mode on an IMAP mailbox, switch to
8389 online mode and connect to the mail server while retaining the
8390 mailbox status. See the description of the disconnected vari‐
8391 able for more information.
8392 disconnect
8394 If operating in online mode on an IMAP mailbox, switch to dis‐
8395 connected mode while retaining the mailbox status. See the de‐
8396 scription of the disconnected variable for more. A list of
8397 messages may optionally be given as argument; the respective
8398 messages are then read into the cache before the connection is
8399 closed, thus ‘disco *’ makes the entire mailbox available for
8400 disconnected use.
8401 imap Sends command strings directly to the current IMAP server.
8403 S-nail operates always in IMAP `selected state' on the current
8404 mailbox; commands that change this will produce undesirable re‐
8405 sults and should be avoided. Useful IMAP commands are:
8406 create Takes the name of an IMAP mailbox as an
8408 argument and creates it.
8409 getquotaroot (RFC 2087) Takes the name of an IMAP mail‐
8411 box as an argument and prints the quotas
8412 that apply to the mailbox. Not all IMAP
8413 servers support this command.
8414 namespace (RFC 2342) Takes no arguments and prints
8416 the Personal Namespaces, the Other User's
8417 Namespaces and the Shared Namespaces.
8418 Each namespace type is printed in paren‐
8419 theses; if there are multiple namespaces
8420 of the same type, inner parentheses sepa‐
8421 rate them. For each namespace a prefix
8422 and a hierarchy separator is listed. Not
8423 all IMAP servers support this command.
8424 imapcodec
8426 Perform IMAP path transformations. Supports vput (see Command
8427 modifiers), and manages the error number !. The first argument
8428 specifies the operation: e[ncode] normalizes hierarchy delim‐
8429 iters (see imap-delim) and converts the strings from the locale
8430 ttycharset to the internationalized variant used by IMAP,
8431 d[ecode] performs the reverse operation. Encoding will honour
8432 the (global) value of imap-delim.
8433 The following IMAP-specific internal variables exist:
8435 disconnected
8437 (Boolean) When an IMAP mailbox is selected and this variable is
8438 set, no connection to the server is initiated. Instead, data
8439 is obtained from the local cache (see imap-cache). Mailboxes
8440 that are not present in the cache and messages that have not
8441 yet entirely been fetched from the server are not available; to
8442 fetch all messages in a mailbox at once, the command `copy *
8443 /dev/null' can be used while still in connected mode. Changes
8444 that are made to IMAP mailboxes in disconnected mode are queued
8445 and committed later when a connection to that server is made.
8446 This procedure is not completely reliable since it cannot be
8447 guaranteed that the IMAP unique identifiers (UIDs) on the
8448 server still match the ones in the cache at that time. Data is
8449 saved to DEAD when this problem occurs.
8450 disconnected-USER@HOST
8452 The specified account is handled as described for the
8453 disconnected variable above, but other accounts are not af‐
8454 fected.
8455 imap-auth-USER@HOST, imap-auth
8457 Sets the IMAP authentication method. Supported are the default
8458 ‘login’ (called ‘plain’ by some servers), [v15-compat]
8459 ‘oauthbearer’ (see FAQ entry But, how about XOAUTH2 /
8460 OAUTHBEARER?), [v15-compat] ‘external’ and ‘externanon’ (for
8461 TLS secured connections which pass a client certificate via
8462 tls-config-pairs), as well as the [Option]al ‘cram-md5’ and
8463 ‘gssapi’. All methods need a user and a password except
8464 ‘gssapi’ and ‘external’, which only need the former.
8465 ‘externanon’ solely builds upon the credentials passed via a
8466 client certificate, and is usually the way to go since tested
8467 servers do not actually follow RFC 4422, and fail if additional
8468 credentials are actually passed.
8469 imap-cache
8471 Enables caching of IMAP mailboxes. The value of this variable
8472 must point to a directory that is either existent or can be
8473 created by S-nail. All contents of the cache can be deleted by
8474 S-nail at any time; it is not safe to make assumptions about
8475 them.
8476 imap-delim-USER@HOST, imap-delim-HOST, imap-delim
8478 The hierarchy separator used by the IMAP server. Whenever an
8479 IMAP path is specified it will undergo normalization. One of
8480 the normalization steps is the squeezing and adjustment of hi‐
8481 erarchy separators. If this variable is set, any occurrence of
8482 any character of the given value that exists in the path will
8483 be replaced by the first member of the value; an empty value
8484 will cause the default to be used, it is ‘/.’. If not set, we
8485 will reuse the first hierarchy separator character that is dis‐
8486 covered in a user-given mailbox name.
8487 imap-keepalive-USER@HOST, imap-keepalive-HOST, imap-keepalive
8489 IMAP servers may close the connection after a period of inac‐
8490 tivity; the standard requires this to be at least 30 minutes,
8491 but practical experience may vary. Setting this variable to a
8492 numeric `value' greater than 0 causes a `NOOP' command to be
8493 sent each `value' seconds if no other operation is performed.
8494 imap-list-depth
8496 When retrieving the list of folders on an IMAP server, the
8497 folders command stops after it has reached a certain depth to
8498 avoid possible infinite loops. The value of this variable sets
8499 the maximum depth allowed. The default is 2. If the folder
8500 separator on the current IMAP server is a slash `/', this vari‐
8501 able has no effect and the folders command does not descend to
8502 subfolders.
8503 imap-use-starttls-USER@HOST, imap-use-starttls-HOST, imap-use-starttls
8505 Causes S-nail to issue a `STARTTLS' command to make an unen‐
8506 crypted IMAP session TLS encrypted. This functionality is not
8507 supported by all servers, and is not used if the session is al‐
8508 ready encrypted by the IMAPS method.
8509
8511 bogofilter(1), gpg(1), more(1), newaliases(1), openssl(1), sendmail(1),
8512 sh(1), spamassassin(1), iconv(3), setlocale(3), aliases(5), termcap(5),
8513 terminfo(5), locale(7), mailaddr(7), re_format(7) (or regex(7)),
8514 mailwrapper(8), sendmail(8)
8515
8517 M. Douglas McIlroy writes in his article “A Research UNIX Reader:
8518 Annotated Excerpts from the Programmer's Manual, 1971-1986” that a
8519 mail(1) command already appeared in First Edition UNIX in 1971:
8520 Electronic mail was there from the start. Never satisfied with its
8522 exact behavior, everybody touched it at one time or another: to as‐
8523 sure the safety of simultaneous access, to improve privacy, to sur‐
8524 vive crashes, to exploit uucp, to screen out foreign freeloaders,
8525 or whatever. Not until v7 did the interface change (Thompson).
8526 Later, as mail became global in its reach, Dave Presotto took
8527 charge and brought order to communications with a grab-bag of ex‐
8528 ternal networks (v8).
8529 BSD Mail, in large parts compatible with UNIX mail, was written in 1978
8531 by Kurt Shoens and developed as part of the BSD UNIX distribution until
8532 1995. This manual page is derived from “The Mail Reference Manual” that
8533 Kurt Shoens wrote for Mail 1.3, included in 3BSD in 1980. The common
8534 UNIX and BSD denominator became standardized as mailx(1) in the X/Open
8535 Portability Guide Issue 2 (January 1987). After the rise of Open Source
8536 BSD variants Mail saw continuous development in the individual code
8537 forks, noticeably by Christos Zoulas in NetBSD. Based upon this Nail,
8538 later Heirloom Mailx, was developed by Gunnar Ritter in the years 2000
8539 until 2008. Since 2012 S-nail is maintained by Steffen Nurpmeso.
8540 Electronic mail exchange in general is a concept even older. The earli‐
8542 est well documented electronic mail system was part of the Compatible
8543 Time Sharing System (CTSS) at MIT, its MAIL command had been proposed in
8544 a staff planning memo at the end of 1964 and was implemented in mid-1965
8545 when Tom Van Vleck and Noel Morris wrote the necessary code. Similar
8546 communication programs were built for other timesharing systems. One of
8547 the most ambitious and influential was Murray Turoff's EMISARI. Created
8548 in 1971 for the United States Office of Emergency Preparedness, EMISARI
8549 combined private electronic messages with a chat system, public postings,
8550 voting, and a user directory.
8551 During the 1960s it was common to connect a large number of terminals to
8553 a single, central computer. Connecting two computers together was rela‐
8554 tively unusual. This began to change with the development of the
8555 ARPANET, the ancestor of today's Internet. In 1971 Ray Tomlinson adapted
8556 the SNDMSG program, originally developed for the University of California
8557 at Berkeley timesharing system, to give it the ability to transmit a mes‐
8558 sage across the network into the mailbox of a user on a different com‐
8559 puter. For the first time it was necessary to specify the recipient's
8560 computer as well as an account name. Tomlinson decided that the under‐
8561 used commercial at ‘@’ would work to separate the two.
8562 Sending a message across the network was originally treated as a special
8564 instance of transmitting a file, and so a MAIL command was included in
8565 RFC 385 on file transfer in 1972. Because it was not always clear when
8566 or where a message had come from, RFC 561 in 1973 aimed to formalize
8567 electronic mail headers, including “from”, “date”, and “subject”. In
8568 1975 RFC 680 described fields to help with the transmission of messages
8569 to multiple users, including “to”, “cc”, and “bcc”. In 1977 these fea‐
8570 tures and others went from best practices to a binding standard in RFC
8571 733. Queen Elizabeth II of England became the first head of state to
8572 send electronic mail on March 26 1976 while ceremonially opening a build‐
8573 ing in the British Royal Signals and Radar Establishment (RSRE) in
8574 Malvern.
8575
8577 Kurt Shoens, Edward Wang, Keith Bostic, Christos Zoulas, Gunnar Ritter.
8578 S-nail is developed by Steffen Nurpmeso <s-mailx@lists.sdaoden.eu>.
8579
8581 [v15 behaviour may differ] Interrupting an operation via SIGINT aka
8582 ‘control-C’ from anywhere else but a command prompt is very problematic
8583 and likely to leave the program in an undefined state: many library func‐
8584 tions cannot deal with the siglongjmp(3) that this software (still) per‐
8585 forms; even though efforts have been taken to address this, no sooner but
8586 in v15 it will have been worked out: interruptions have not been disabled
8587 in order to allow forceful breakage of hanging network connections, for
8588 example (all this is unrelated to ignore).
8589 The SMTP and POP3 protocol support of S-nail is very basic. Also, if it
8591 fails to contact its upstream SMTP server, it will not make further at‐
8592 tempts to transfer the message at a later time (setting save and sendwait
8593 may be useful). If this is a concern, it might be better to set up a lo‐
8594 cal SMTP server that is capable of message queuing.
8595
8597 When a network-based mailbox is open, directly changing to another net‐
8598 work-based mailbox of a different protocol (i.e., from POP3 to IMAP or
8599 vice versa) will cause a “deadlock”.
8600 After deleting some message of a POP3 mailbox the header summary falsely
8602 claims that there are no messages to display, one needs to perform a
8603 scroll or dot movement to restore proper state.
8604 In ‘thread’ed sort mode a power user may encounter crashes very occasion‐
8606 ally (this is may and very).
8607 Please report bugs to the contact-mail address, for example from within
8609 s-nail: ‘? eval mail $contact-mail’. Including the verbose output of the
8610 command version may be helpful:
8611 ? wysh set escape=! verbose; vput version xy; unset verbose;\
8613 eval mail $contact-mail
8614 Bug subject
8615 !I xy
8616 !.
8617 Information on the web at ‘$ s-nail -X 'echo $contact-web; x'’.
8619BSD March 26, 2022 BSD