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