This plain ∞ groff(1) HTML output has only been fixed slightly — i am sorry for false list indentions etc.!
S-nail [v14.10.0-alpha, "Mountains O' Things"] — send and receive Internet mail
s-nail [−DdEFinv˜#] [−: spec] [−A account] [:−a attachment:] [:−b bcc-addr:] [:−C "field: body":] [:−c cc-addr:] [−q file | −t] [−r from-addr] [
:−S var[
=value]: ] [−s subject]
[:−T "field: addr":]
[:−X cmd:]
[:−Y cmd:] [−.] ([
):to-addr:( ])
[−− :mta-option:]
s-nail [−DdEeHiNnRv˜#] [−: spec] [−A account] [:−C "field: body":] [−L spec] [−r from-addr] [
:−S var[
=value]: ] [−u user]
[:−X cmd:]
[:−Y cmd:]
[−− :mta-option:]
s-nail [−DdEeHiNnRv˜#] [−: spec] [−A account] [:−C "field: body":] −f [−L spec] [−r from-addr] [
:−S var[
=value]: ] [:−X cmd:]
[:−Y cmd:] [file]
[−− :mta-option:]
s-nail
−h | −−help
s-nail −V | −−version
s-nail −−copyright
TABLE OF
CONTENTS
NAME†
SYNOPSIS†
TABLE OF CONTENTS†
DESCRIPTION†
Options†
A starter†
Sending mail, and non-interactive
mode†
Compose mode†
Reading mail, and more on interactive
mode†
HTML mail and MIME attachments†
Mailing lists†
Character sets†
Message states†
Specifying messages†
Terminal control and line editor†
Coloured display†
Signed and encrypted messages with
S/MIME†
URL syntax and credential lookup†
Encrypted network communication†
Handling spam†
COMMANDS†
Command modifiers†
Old-style argument quoting†
Shell-style argument quoting†
Shell-style expansions†
Message list arguments†
Raw data arguments for codec
commands†
Filename transformations†
Commands†
COMMAND ESCAPES†
INTERNAL VARIABLES†
Initial settings†
Built-in variables†
ENVIRONMENT†
FILES†
Resource files†
The mime.types files†
The Mailcap files†
The .netrc file†
EXAMPLES†
S/MIME step by step†
Using CRLs with S/MIME or TLS†
FAQ†
S-nail shortly hangs on startup†
Not "defunctional", but the editor key does not
work†
Can S-nail git-send-email?†
How to handle stale dotlock files†
How to loop†
IMAP CLIENT†
SEE ALSO†
HISTORY†
AUTHORS†
CAVEATS†
BUGS†
Warning! v15-compat† (with value) is default since v14.10.0, and the manual expects this context; Most old (other context) documentation has been removed. S-nail (S-nail) will see major changes until v15.0 (circa 2028). Some backward incompatibilities cannot be avoided, for example COMMANDS† will change to Shell-style argument quoting† .
S-nail provides a simple and friendly environment for sending and receiving mail. It is intended to provide the functionality of the POSIX.1-2024 mailx(1) command, is MIME capable, and optionally offers extensions for line editing, S/MIME, SMTP and POP3, among others. Through many COMMANDS† and INTERNAL VARIABLES† users are given tools for email appraisal and management, as well as increasingly powerful, reliable scripting capabilities.
Controls loading (as via source† ) of Resource files† . spec consists of case-insensitive letters: ‘s’ for the system-wide s-nail.rc† , ‘u’ for the personal file MAILRC† (˜/.mailrc† ). The letters ‘-’ or ‘/’ clear the list of files to be loaded. The default is ‘su’. This option overrides −n† .
Assign name to account† ; activate account† name after Resource files† are loaded, but with −X† commands etc. to follow; switch to its primary system mailbox† (inbox† ) once startup is completed. Failures cause exit† s if used non-interactively, or if any of errexit† or posix† are set.
−a
file[
=[
!]input-charset[
#[
!]output-charset]], −−attach=..
(Send mode) Attach file, subject to tilde expansion (see Filename transformations† and folder† ). In Compose mode† the COMMAND ESCAPES† ˜@† and ˜ˆ† (scriptable) provide alternatives for attaching files.
If file is inaccessible, but contains an equal-sign ‘=’, a specification of Character sets† is “split off”. Only an input one causes fixation without conversion; an empty, or the special string hyphen-minus ‘-’ means ttycharset† . If an output one is given the conversion is performed on-the-fly, not considering file type nor content; however, empty string or hyphen-minus ‘-’ enforce the “default conversion” (‘-a file’, ‘-a file=#’, and ‘-a file=-#-’ are identical), performed after MIME-classifying file (HTML mail and MIME attachments† , The mime.types files† ); Only this variant exists without ‘,+iconv,’ support in features† , or with iconv-disable† set† . Character set names prefixed with exclamation mark ‘!’ enforce base64 mime-encoding† over-the-wire.
(Send mode) Add addr to the list of blind (invisible) carbon copy recipients. May be used multiple times. (Also see Sending mail, and non-interactive mode† ).
−C "name: content", −−custom-header=..
Create a constant custom header field name. Content follows after a colon ‘:’, for example ‘-C "Blah: Neminem laede; imo omnes, quantum potes, juva"’. May be used multiple times; name may not be a standard header field. Adjustable custom headers can be created via customhdr† , and in Compose mode† ˜ˆ† (COMMAND ESCAPES† ).
(Send mode) Like −b† , but adds carbon copies (visible recipients).
−−copyright
Print a copyright summary and exit.
[Option] Startup with disconnected† set† .
Enter a debug-only sandbox mode by setting debug† , as via ‘−S† debug’ or ‘set† debug’. Also see −v† .
Startup with skipemptybody† set† .
If any messages (matching −L† ) exist in folder† (dependent on −u† , inbox† or MAIL† , or as specified via −f† ), then exit with status 0, with non-zero otherwise.
(Send mode) Save the message in a file named after the local part of the first recipient’s address, overwriting record† , but honouring outfolder† .
Open the user’s secondary mailbox† MBOX† , or a given argument file, instead of the primary system mailbox† (note hold† , keepsave† ); file is not an option argument, but taken from the command line after option processing is completed. It equals using the folder† command, so file is inspected for protocol specifications and undergoes Filename transformations† ; Hyphen-minus ‘-’ denotes standard input (in MBOX or EML format), can be a pipe instead of a regular file, but requires read-only mode (−R† ).
Display a (−L† : configurable) summary of message headers† in folder† (dependent on −u† , inbox† or MAIL† , or as specified via −f† ), then exit. showlast† is ignored. Quickrun: does not open an interactive session. Tip: COLUMNS† are honoured in batch mode (−#† ).
Show a brief usage summary; use −−long-help to list long options.
Like −H† , but only show what matches spec (Specifying messages† ). In conjunction with −e† display is suppressed.
Startup with header† unset† to inhibit summary of headers† display when opening a folder† .
Inhibit reading system-wide s-nail.rc† (Resource files† ).
(Send mode) Initialize message body from file; only non-interactively this may denote standard input (hyphen-minus ‘-’). Also see −t† .
Any mailbox will be opened read-only as via Folder† .
−r from-addr, −−from-address=..
The RFC 5321 reverse-path used for relaying and delegating messages, for example to report back delivery errors, is derived from from† (or sender† ), but a file-based (local) mta† (Message-Transfer-Agent) uses LOGNAME† . This option assigns from-addr to from† , and in addition file-based mta† s are invoked with a ‘−f from-addr’ option; with fullnames† , and if from-addr includes non-address components, those are passed via ‘−F name’. If from-addr is an empty string from† (or sender† ) is evaluated whenever mta† is invoked; also see r-option-implicit† . Even though not a recipient the ‘shquote’ expandaddr† flag is supported.
Remarks: many MTA installations and sites disallow setting an explicit reverse-path but for members of dedicated user groups, or after MTA reconfiguration.
set† (or, with a ‘no’ prefix as documented in INTERNAL VARIABLES† , unset† ) variable and optionally assign value, if supported, evaluated as if specified within dollar-single-quotes (Shell-style argument quoting† ). Upon failure the program will exit if any of errexit† or posix† is set. Settings established via −S cannot be changed from within Resource files† , or an −A† ccount switch; they become mutable again for −X† commands.
(Send mode) Specify a message subject. Newline (NL) and carriage-return (CR) are normalized to space (SP).
(Send mode) Add addr, parsed like a message header address field (see −t† ), and supporting the same modifiers, to the list of recipients targeted by field: supported are ‘bcc’, ‘cc’, ‘fcc’, and ‘to’. Field and body (address) are separated by a colon ‘:’ and optionally blank (space, tabulator) characters. The ‘shquote’ expandaddr† flag is supported. This option may be used multiple times.
(Send mode) Standard input is expected to contain one or multiple plain text message header fields, an empty line, and the message body. [v15 behavior may differ] Readily prepared MIME mail messages cannot be passed. Header fields are parsed as follows. A line starting with number sign ‘#’ in the first column is ignored. A header field can span multiple consecutive lines if follow lines start with (ignored) whitespace.
Recipients will be expandaddr† checked, and added onto the command line ones: ‘To:’, ‘Cc:’, ‘Bcc:’; ‘Fcc:’ is supported (see Compose mode† ). A subject specified via ‘Subject:’ is used in favour of the command line option −s† .
More optional header fields are ‘Reply-To:’ (possibly overriding reply-to† ), ‘Sender:’ (sender† ), ‘From:’ (from† and / or option −r† ). Normally created automatically, but used if specified are ‘Message-ID:’ ‘In-Reply-To:’, ‘References:’ and ‘Mail-Followup-To:’. All other (custom) header fields (see −C† , customhdr† , ˜ˆ† ) are passed through as-is, and in conjunction with the options −˜† or −#† COMMAND ESCAPES† are evaluated. Also see −q† .
Open the primary system mailbox† of user, appropriate privileges presumed; identical to ‘−f %user’.
Print version† and exit. The command version† will also show features† : ‘$ s-nail -:/ -#v -Xversion -Xx’.
set† verbose† . (Multiple levels.) Also see −d† .
Add (the multiline) cmd (block) to a list evaluated before normal operation starts, as via source† . Correlates with −#† and errexit† .
Add (the multiline) cmd (block) to a list evaluated after normal operation has started. It is evaluated successively in the given order, and as if given on the program’s standard input — before interactive prompting begins in interactive mode, after standard input has been consumed otherwise.
Enable COMMAND ESCAPES† in Compose mode† , even in non-interactive use cases. This can for example be used to format the composed message text:
$ ( echo
’line one. Word. Word2.’;
echo ’˜| /usr/bin/fmt -tuw11’ ) |
LC_ALL=C s-nail -˜ -:/ -Smta=test x@exam.ple
Enable batch mode: standard input is made line buffered, all (interactive) commands are made available, processing of COMMAND ESCAPES† is enabled in Compose mode† , and diverse INTERNAL VARIABLES† are adjusted for batch necessities, exactly as via −S† : emptystart† , noerrexit† , noheader† , noposix† , quiet† , sendwait† , typescript-mode† . The following are instead set† to /dev/null† : MAIL† , MBOX† and inbox† . (Without an −A† ccount switch a later −f† will avoid “opening” /dev/null† in receive mode.) The values of COLUMNS† and LINES† are acted upon. For example :
$ for name in
bob alice@exam.ple lisa@exam.ple; do
printf ’mail %s\n˜s
ubject\nText\n˜.\n’ "${name}"
done |
LC_ALL=C s-nail -#:/ -Smta=test -Sttycharset-detect \
-X’alias bob bob@exam.ple’
Force termination of option processing (prevent “option injection” attacks), and forcefully enter send mode.
Different to mta-arguments† the setting of expandargv† is checked before mta-option arguments given after a ‘--’ command line separator will be passed to file-based mta† s (Message-Transfer-Agent) during the session. The ‘shquote’ constraint of expandaddr† applies to recipient addresses on the command line. For more see Sending mail, and non-interactive mode† .
$ s-nail -#:/ -X ’addrcodec enc <silver@go> Hey, ho’ -Xx
A
starter
NAME†
SYNOPSIS† TABLE OF
CONTENTS† S-nail is a direct
descendant of BSD Mail, itself a successor to the Research
UNIX mail which “was there from the start”
according to HISTORY† . As a
message user agent (MUA) it represents the user side of the
UNIX mail system, the traditional server
Message-Transfer-Agent (MTA) was sendmail(8), and for
compatibility a binary of this name usually exists to this
day. If features† announces
the [option]al SMTP mta†
message delivery does not require the server side.
This program strives for POSIX.1-2024 mailx(1) compliance, however posix† (INTERNAL VARIABLES† ) or its environ† mental equivalent POSIXLY_CORRECT† (ENVIRONMENT† ) needs to be set to tweak behavior accordingly. There is an important deviation: POSIX Shell-style argument quoting† is ([v15 behavior may differ] increasingly) used instead of POSIX mailx’s Old-style argument quoting† , which is believed to be a feature. And some built-in settings bend standard imposed settings.
For example, even if the opened folder† is empty interactive mode is entered due to emptystart† , in Compose mode† editheaders† enables header field editing and fullnames† avoids address skinning, when reply† ing responded messages are quote† d, prefixed with a non-standard indentprefix† , and followup-to-honour† and reply-to-honour† are set to comply to sender address desires. Fully enabled is mime-counter-evidence† .
User credentials and settings are easily addressable by grouping them in account† s. The file mode creation mask can be managed with umask† . Files and shell pipe output can be source† d for eval† uation, also during startup from within the Resource files† . Informational context may be available by set† ting verbose† or debug† (as via −v† , −d† ). Many ‘un*’ commands, like unaccount† , unalias† , unalternates† , uncommandalias† etc. support an asterisk ‘*’ wildcard argument that matches all covered settings.
Sending mail,
and non-interactive mode
To send a message to one or more people specify email
addresses (fullnames† )
and/or (blind) carbon copy recipients via
−b† and
−c† on the command
line When delivered through a local
mta†
(Message-Transfer-Agent) plain system-local user names can
be addressed. The message text will be read from standard
input — if the standard input and output I/O channels
do not both point to a terminal, non-interactive mode is
entered:
# Via test MTA
$ echo Hello, world | s-nail -:/ -Smta=test -s test
$LOGNAME
# Via
sendmail(1) MTA
$ </dev/null s-nail -:/ -s test $LOGNAME
# Debug dry-run
mode:
$ </dev/null LC_ALL=C s-nail -d -:/ \
-Sttycharset=utf8 -Sfullnames \
-b bcc@exam.ple -c cc@exam.ple -. \
’(Lovely) Bob <bob@exam.ple>’
ex@am.ple
# Compose-mode
snoopy
$ s-nail -:/ -Smta=test -Sttycharset-detect \
-s test -Y ’˜?’ -Y ’˜x’
ex@am.ple
# With SMTP (no
real sending due to -d debug dry-run)
$ LC_ALL=C s-nail -d -:/ -Sttycharset-detect \
-S mta=smtps://me@exam.ple:465 -Ssmtp-config=-auth \
-S from=scriptreply@exam.ple \
--attach /etc/passwd --end-options \
ex@am.ple < /tmp/letter.txt
Plain user names and metoo† (alternates† ) are expanded through alias† and mta-aliases† . A valid local user (or “postmaster”: case-insensitively via RFC 5321 section 2.3.5) ‘<name>’ in angle brackets (an invalid address) expands to a qualified address if hostname† is not set or non-empty; if empty conversion is responsibility of the mta† . expandaddr† offers control over allowed recipients (and more), which are classified as follows:
•
Any name that starts with a vertical bar ‘|’ specifies a pipe: the SHELL† evaluates the (best quoted) “address”; pipes honour sendwait† .
•
Other than that hyphen-minus ‘-’ or any name that starts with solidus ‘/’ or dot solidus ‘./’ is treated as a file.
•
Any other name containing commercial at ‘@’ is an (email) address.
•
Any other name which starts with a plus sign ‘+’, or which contains a solidus ‘/’ but no exclamation mark ‘!’ or percent sign ‘%’ before that (Filename transformations† ) is a mailbox folder† name.
•
What remains is treated as an (email) address. Classification can be avoided by using a ‘Fcc:’ header field, see Compose mode† .
File and pipe recipients honour mbox-fcc-and-pcc† . Examples:
$ echo bla |
s-nail -S expandaddr -s test ./mbox.mbox
$ echo bla | s-nail -Sexpandaddr -stest ’|cat >>
./mbox.mbox’
$ echo safe | LC_ALL=C s-nail -:/ -Smta=test \
--set expandaddr=fail,-all,+addr,failinvaddr \
-Sttycharset-detect -S fullnames \
-s test -. ’Imagine John
<cold@turk.ey>’
A lot of configuration can be set† generally. The envelope sender address for example via from† , especially with the built-in SMTP mta† a hostname† must be set. Character sets† for message text and MIME part content are configurable via sendcharsets† , input data is expected to be in ttycharset† , but active ttycharset-detect† ion is available. Emails need a mime-encoding† , MIME parts aka attachments need a mimetype† , usually taken out of The mime.types files† . Saving copies of sent messages in a record† mailbox may be desirable.
account† s aid in arranging complete configurations. Alternatively so-called variable chains that automatically pick ‘USER@HOST’ or ‘HOST’ context-dependent variants could be sufficient: for example ‘set† mta† =smtp://yaa@exam.ple’ would find smtp-config-yaa@exam.ple, smtp-config-exam.ple and smtp-config† , in order. More on that under URL syntax and credential lookup† and INTERNAL VARIABLES† .
To avoid environmental noise scripts should be isolated by excluding configuration files via −:† , and use repetitions of −S† to specify variables, in case no dedicated Resource files† are possible:
$ env LC_ALL=C
s-nail -:/ \
-Sttycharset-detect=latin1 \
-Smime-force-sendout \
-Sexpandaddr=fail,-all,failinvaddr \
-S mta=smtps://me@exam.ple:465 -Ssmtp-config=-allmechs,plain
\
-S from=scriptreply@exam.ple \
-s ’Subject to go’ -a attachment_file \
-Sfullnames --end-options \
’Recipient 1 <rec1@exam.ple>’
rec2@exam.ple \
< content_file
As shown scripts can fake a locale ENVIRONMENT† , the above specifies the all-compatible 7-bit clean LC_ALL† “C”, but nonetheless takes and sends UTF-8 message text via ttycharset† ; active classification via ttycharset-detect† might be an even better option, reflecting reality.
If character set conversion is available (features† includes ‘,+iconv,’, iconv-disable† not set) invalid (according to input character set) input causes errors: mime-force-sendout† , as a last resort, classifies input as binary data, and allows message creation to succeed. (Such content can be inspected either by installing a pipe-TYPE/SUBTYPE† handler for ‘application/octet-stream’, or possibly automatically through mime-counter-evidence† ).
Compose
mode
In compose mode of interactive sessions, or when requested
via −˜† or
−#† , lines beginning
with ‘˜’ (the value of
escape† in fact) are
COMMAND ESCAPES† . For
example ˜v† will start
VISUAL† and
˜e†
EDITOR† to revise the message,
including header fields with
editheaders† (setting
fullnames† avoids address
skinning), the potent
˜ˆ† can manage
attachments and header fields more scriptable than
˜@† . [Option]ally
˜?† shows a summary of
available command escapes.
Via ˜ˆ† ‘Fcc:’ header fields can be created that are not mangled like other recipients, so names with vertical bars, or commercial ats, or other special characters can be used; they are still subject to expandaddr† checks, undergo Filename transformations† , and are then interpreted like a folder† target. Any local file and pipe command recipient honours mbox-fcc-and-pcc† .
on-compose-enter† , on-compose-embed† , on-compose-leave† and on-compose-cleanup† are hooks that may each be set to a define† d Macro† : on-compose-embed† itself can operate on messages like a user and directly use COMMAND ESCAPES† , digmsg† may also be used by on-compose-enter† and on-compose-leave† . ([v15 behavior may differ] The compose mode hooks work for forward† , mail† , reply† and variants; resend† and Resend† only provide the hooks on-resend-enter† and on-resend-cleanup† , which are pretty restricted due to the nature of the operation.)
Once ready ˜.† leaves compose mode, which involves invoking a set on-compose-embed† hook; in interactive mode askatend† (leading to askcc† , askbcc† ) and askattach† will be checked, then asksend† is honoured: choosing to reenter compose mode will not run the on-compose-enter† hook again; Thereafter a set on-compose-leave† hook may perform final message adjustments via digmsg† ; finally autocc† and autobcc† are joined into receiver lists, and a given message-inject-tail† will be inserted. Unless ignoreeof† is set typing end-of-transmission (EOT) ‘control-D’ (‘ˆD’) at the beginning of an empty line has the same effect. ˜x† or ˜q† abort message composition, the latter saves the message draft in DEAD† unless nosave† is set. Typing end-of-text (ETX) twice via ‘control-C’ (‘ˆC’) equals ˜q† .
COMMANDS† which enter compose mode support a local† scope† (Command modifiers† ): covered changes will be reverted once compose mode is left.
Reading mail,
and more on interactive mode
When invoked without recipients “receive mode”
is entered, and if the standard input and output I/O
channels both point to a terminal, in interactive mode with
Terminal control and line
editor† . Through many
COMMANDS† mail can be read,
sent and managed in this mode. It starts into a mailbox as
via folder† : either the
primary system mailbox† (of
−u† user), or,
with the option −f† ,
a given file or the secondary
MBOX† . If this initial mailbox is
empty the program quit† s
unless emptystart† is
set† .
With header† a screen† ful of headline† s of headers† is then shown, sort† ed according to autosort† . z† will move through the summary. Messages are uniquely identified by numbers counting from 1; the current – named “dot” – will either be the first new, the first unread, or the first (showlast† : the last) message of the mailbox, in view. By Specifying messages† selective search† results can be created.
At the prompt† list† shows all built-in COMMANDS† in lookup order, commandalias† es can be defined and listed. A overall summary help† is available, and [option]ally also for a given command (expansion). help† and list† may react upon verbose† .
help reply
#..
set verbose=2; help reply; unset verbose
type† (alias print† ) displays header fields and text content of specified messages or the dot. Technical message information is displayed if quiet† is not set. Whether and when PAGER† is used for display instead of dumping to the screen† is controlled by crt† , whereas more† always uses PAGER† . top† shows only the first toplines† of messages, topsqueeze† d. Setting mime-counter-evidence† can improve real-life display experience, and also see HTML mail and MIME attachments† .
type :nu # new
and unread
#..
type @didgeridoo # (search Subject:s for substring
By default all message header fields are type† d, but they may be retain† ed or ignore† d for a variety of applications via headerpick† , for example, to restrict what is forward† ed: ‘headerpick† forward retain from to cc subject’. In order to display all header fields of a message regardless of currently active ignore or retain lists use Type† and Top† . The displayed headerorder† is configurable. For raw, undecrypted and unconverted message content, use show† .
Automatic message moving: out of HISTORY† there is a notion of a primary system mailbox† , and a secondary mailbox† . The former are inbox† , MAIL† , and all folder† s (also via −f† ) opened with ‘%:’ prefix, the latter is MBOX† . When leaving a primary mailbox, (also via normal program termination, quit† ) dependent upon Message states† , which there can also be enforced or overwritten with the COMMANDS† hold† , mbox† , touch† , automatic deletion and moving happens dependent on the settings of hold† , keep† , keepsave† . Deviating from the standard these are set† , so automatic message moving does not occur. Manually move† ing or copy† ing messages is possible, write† saves selected message parts.
One may reply† ‘r’ to the sender and all recipients (also placed in ‘To:’ unless recipients-in-cc† is set) of a message, or Reply† ‘R’ exclusively to the sender. To comply with the sender’s desired reply address the quadoption† s followup-to-honour† and reply-to-honour† should usually be set. A special recipient massage for Mailing lists† is applied by Lreply† and Lfollowup† . The message being replied to can be quote† d (value defines style). forward† ing a message includes the original message in the message body instead. It is possible to resend† or Resend† messages, the former only will add a series of ‘Resent-’ header fields; different to newly created messages editing is not possible and no copy will be saved in record† unless record-resent† is set† .
Messages can be delete† ‘d’ and undelete† d. The S-nail session is ended quickly via exit† or xit† , a full program exit that includes mailbox state and line editor history-file† updates among others is performed by quit† .
HTML mail and
MIME attachments
Messages with only a HTML part, or MIME (Multipurpose
Internet Mail Extensions) alternative messages with only a
useful HTML type part become more and more common. And there
are MIME attachments containing numerous data types. No
knowledge of those is necessary for saving message parts via
write† , for other purposes
a notion of MIME types is required. A small set of types is
built-in, onto which The mime.types
files† are added under
mimetypes-load-control† .
mimetype† controls types
dynamically.
mime-counter-evidence†
tries to address the faulty MIME part declarations of real
life by possibly providing better fitting MIME types.
A simple HTML-to-text filter is [option]ally (features† contains ‘,+filter-html-tagsoup,’) built-in, but other non-text MIME types cannot be handled directly: handlers need to be registered that either convert data to (re-)integratable plain text (called copiousoutput† mode), or display it externally, for example in a graphical window: this latter kind is not considered when messages are type† d, but only by mimeview† .
To install a handler for a MIME type an according pipe-TYPE/SUBTYPE† variable must be set, alternatively the higher-ranked per file extension pipe-EXTENSION† can be used. [Option] Standard mail user agent configuration (RFC 1524) and The Mailcap files† preferably share MIME handler knowledge in between many programs. mimetype† type-markers are inspected last. Except with mime-alternative-favour-rich† plain text alternatives are used.
# Easy view
HTML alternative parts (needs built-in HTML viewer)
define showhtml {
local set mime-alternative-favour-rich pipe-text/html=?h?
type "$@"
}
commandalias html ’call showhtml’
Mailing
lists
Mailing lists can be flagged in the summary of
headers†
(headline† :
‘%L’), and gain special treatment when sending
mails: followup-to-honour†
ensures ‘Mail-Followup-To:’ header fields are
honoured when replying
(reply† ,
followup† ,
Lreply† ,
Lfollowup† ), and
followup-to† creates this
header field when mail† ing
messages with a proper user setup
(from† ,
sender† ); it may be
created automatically, for example when list-replying via
Lreply† or
Lfollowup† , when
followup† or
reply† is used and
‘Mail-Followup-To:’ is honoured etc.
mlist† and mlsubscribe† manage the correlation of email addresses and mailing lists. With the [option]al regular expression support addresses which contain any of the magic regular expression characters (‘ˆ[*+?|$’; see re_format(7) or regex(7), dependent on host system) can then match many addresses. It is not possible to escape the “magic”: in order to match special characters as-is, bracket expressions must be used, for example ‘search† @subject@’[[]open bracket’’.
set followup-to
followup-to-honour=ask-yes \
reply-to-honour=ask-yes
mlist a1@b1.c1 a2@b2.c2 ’.*@lists\.c3$’
mlsubscribe a4@b4.c4 exact@lists.c3
Known and subscribed lists differ in that for the latter user addresses are not included in generated ‘Mail-Followup-To:’. There are exceptions, for example if multiple lists are addressed and not all have the subscription attribute. When replying to a message its list address (‘List-Post:’ header field) is temporarily treated like a known mlist† ; dependent on reply-to-honour† an existing ‘Reply-To:’ is used instead (if it is a single address on the same domain as ‘List-Post:’) in order to accept a list administrator’s wish that is supposed to have been manifested like that.
For convenience and compatibility with mail programs that do not honour the non-standard M-F-T an automatic user entry in ‘Cc:’ can be created via followup-to-add-cc† whenever the user is placed in ‘Mail-Followup-To:’, but is not a regular recipient of the message. reply-to-swap-in† tries to deal with the address rewriting that many mailing-lists nowadays perform to work around DMARC etc. standard imposed problems.
Character
sets
[Option] The user’s locale is detected by looking at
the LC_ALL† (see also
LC_CTYPE† ,
LANG† )
ENVIRONMENT† variable
(deriving and storing the according character set in
charset-locale† ), and
ttycharset† : the latter
character set is targeted when displaying data, and any user
input data is by default expected to be in it, too.
When creating messages character input data is inspected. 7-bit clean data is classified as charset-7bit† . [Option]ally 8-bit data is classified as ttycharset† unless ttycharset-detect† ion was enabled, and will be converted repeatedly into members of sendcharsets† until a character set conversion succeeds; charset-8bit† is the implied last member of this list. If no member of sendcharsets† is capable to represent the ttycharset† (or ttycharset-detect† ) data, no message will be sent, and its text will optionally be save† d in DEAD† . However, sending of non-convertible data as ‘application/octet-stream’ binary content can be enforced with mime-force-sendout† (recipients then may inspect content for example via mime-counter-evidence† ).
If the [option]al character set conversion is not available (features† misses ‘,+iconv,’, or iconv-disable† set† ), ttycharset† (or ttycharset-detect† ) is the only supported character set for non 7-bit clean data, and it is simply assumed it can be used to exchange 8-bit messages.
ttycharset† may also be given an explicit value to send mail in a completely “faked” locale, for example generate and send 8-bit UTF-8 input data in a pure 7-bit US-ASCII ‘LC_ALL=C’ ENVIRONMENT† (as shown in Sending mail, and non-interactive mode† ). Unfortunate: due to lack of programming interfaces reading mail will not truly work here: whereas ttycharset† might be addressable, any output will be made safely printable, as via vexpr† makeprint, according to the actual locale, which is not affected by ttycharset.
Classifying 7-bit clean data as charset-7bit† is a problem if the input character set (ttycharset† , ttycharset-detect† ) is a multibyte character set that is itself 7-bit clean. For example, the Japanese character set ISO-2022-JP is, but is capable to encode the rich set of Japanese Kanji, Hiragana and Katakana characters: in order to notify recipients of this character set the mail message must be MIME encoded so that the character set ISO-2022-JP can be advertised, otherwise an invalid email message would result! To achieve this, the variable charset-7bit† can be set to ISO-2022-JP. (Today a better approach regarding email is the usage of UTF-8, which uses 8-bit bytes for non-US-ASCII data.)
When replying to a message and reply-in-same-charset† is set the character set of the message being replied to is tried first as a target character set (still being a subject of charsetalias† filtering, however). Another opportunity is sendcharsets-else-ttycharset† to reflect the user’s locale automatically, it will treat ttycharset† as an implied member of (an unset) sendcharsets† .
[Option] When reading messages, text data is converted into ttycharset† as necessary. Unprintable characters and invalid byte sequences are detected and replaced by substitution characters. Character set mappings for source character sets can be established with charsetalias† , which may be handy to work around faulty or incomplete character set catalogues (one could for example add a missing LATIN1 to ISO-8859-1 mapping), or to enforce treatment of one character set as another one (“interpret LATIN1 as CP1252”). Also see charset-unknown-8bit† for another hairy aspect of message interpretation.
In general, if a message saying “cannot convert from a to b” appears, either some characters are not appropriate for the currently selected (terminal) character set, or the needed conversion is not supported by the system. In the first case, it is necessary to set an appropriate LC_ALL† locale and/or the variable ttycharset† . The best results are usually achieved when running in a UTF-8 locale on a UTF-8 capable terminal, in which case the full Unicode spectrum of characters is available. In this setup characters from various countries can be displayed, only restricted by the used font, while it is still possible to use more simple character sets for sending to retain maximum compatibility with older mail clients.
On the other hand the POSIX.1-2024 standard defines a locale-independent 7-bit “portable character set” that should be used when overall portability is an issue, the even more restricted subset named “portable filename character set” consists of A-Z, a-z, 0-9, period ‘.’, underscore ‘_’ and hyphen-minus ‘-’.
Message
states
Several message states are distinguished. The state of a
message is shown by its
headline† in the summary of
headers† , and
Specifying messages† by
their state is possible.
‘new’
Neither read nor moved to another state. Retained even in a primary system mailbox† .
‘unread’
Neither read nor moved to another state, but already present when the folder† was opened. Retained even in a primary system mailbox† .
‘read’
Processed by one of ˜f† , ˜m† , ˜F† , ˜M† , copy† , mbox† , More† , more† , next† , pipe† , Print† , print† , top† , Type† , type† , undelete† . dp† and dt† try to automatically “step” and type† the “next” logical message, and may thus mark multiple messages as read, delete† will do so if the internal variable autoprint† is set.
Except when left via exit† , ‘read’ messages of a primary system mailbox† are saved to the secondary mailbox† MBOX† unless hold† it set.
‘deleted’
Processed by one of delete† , dp† and dt† . It may be undelete† d, but other than that disappeared.
‘preserved’
Only available in a primary system mailbox† : marked via hold† (or preserve† ), and will be retained.
‘saved’
Processed by save† or write† . The flag may be cleared by undelete† . Unless overwritten by hold† , and except when left via exit† , ‘saved’ messages of a primary system mailbox† are deleted; they are instead saved to the secondary mailbox† MBOX† if keepsave† is set.
In addition to these states, otherwise meaningless flags that may be set exist; they are addressable when Specifying messages† . They are persistently saved with messages, and are portable between a set of widely used MUAs:
answered†
Mark as having been answered.
draft†
Mark as being a draft.
flag†
Mark for special attention.
Specifying
messages
[Only new quoting rules] Some
COMMANDS† take Message
list arguments† , for example
copy† ,
delete† ,
search† , and
type† , and can perform
actions on a number of messages at once.
For example, ‘delete 1 2’ deletes the messages 1 and 2 (validity presumed), whereas ‘delete 1-5’ will delete messages 1 through 5. In sorted mode (sort† , autosort† ) ‘delete 1-5’ will delete all messages that are located in between (and including) messages 1 through 5 in the sorted order, as shown by headers† .
Errors that occur are tracked by the INTERNAL VARIABLES† !† , ˆERR† and companions, as well as the command exit status ?† . For example ˆERR† -BADMSG when requesting an invalid message, ˆERR† -NOMSG if no applicable message can be found, ˆERR† -CANCELED for missing informational data (mostly thread-related). ˆERR† -INVAL for invalid syntax as well as ˆERR† -IO for input/output errors can happen.
.
The current message, the so-called “dot”. Many commands use it if no specification was given.
;
The previously current message; needs to be quoted.
,
The dot’s parent message. This is the message with the Message-ID given in the ‘In-Reply-To:’ field, or the last entry of the ‘References:’ field of the current message.
-
The previous undeleted message, or the previous deleted one for undelete† . In sort† ed mode, the previous such message in the according order.
+
The next undeleted message, or the next deleted one for undelete† . In sort† ed mode, the next such message in the according order.
ˆ
The first undeleted message, or the first deleted one for undelete† . In sort† ed mode, the first such message in the according order.
$
The last message. In sort† ed mode, the last such one in the according order. Needs to be quoted.
&[x]
Selects the message addressed with x in threaded sort† mode, where x is any other message specification, and all messages from the thread that begins at it. Otherwise identical to x. Omitting x equals using dot.
*
All messages.
‘
All messages matched by the Message list arguments† of the previous command. (Tip: to read all new messages ‘search :n’ them, then successively type ‘‘’ to invoke the default command next† ; showlast† must be set for this to work.)
x-y
An inclusive range of message numbers. Selectors that may also be used as endpoints include any of ‘.;-+ˆ$’.
address
Case-insensitive “any substring matches” search for ‘From:’ fields. It matches addresses even if showname† is set (and POSIX.1-2024 says “any address shown in a header summary shall be matchable in this form”); However, if the allnet† variable is set, only the local part of the address is evaluated, not ignoring case, and showname† is completely ignored. For finer control and match boundaries, and substrings starting with numbers, instead use ‘@’.
/string
All messages that contain string in the subject field (case ignored according to locale). Also see searchheaders† . An empty string equals the last one used by this specification.
[@name-list]@expr
A case-insensitive search expression. If expr contains a commercial at ‘@’ name-list is effectively non-optional, but can be empty. name-list specifies a comma-separated list of header fields, without it only the ‘Subject:’ is searched. [Option] expr and name-list are interpreted as extended regular expressions if they contain magic regular expression characters† .
An empty search expression tests for existence of the given header fields (compare digmsg† ). Some header fields may be abbreviated: ‘a’, ‘f’, ‘t’, ‘c’, ‘b’ and ‘s’ will match ‘Author:’, ‘From:’, ‘To:’, ‘Cc:’, ‘Bcc:’ and ‘Subject:’, respectively, and case-insensitively. But for the existence test ‘Author’ indeed means all of ‘Author:’, ‘From:’, and ‘Sender:’.
The special header fields ‘header’ or ‘<’ can be used to search in (all of) the header field(s), and ‘body’ or ‘>’ and ‘text’ or ‘=’ will perform full text searches – whereas the former searches only the body, the latter also searches the message header ([v15 behavior may differ] this mode yet brute force searches over the entire decoded content of messages, including administrativa strings).
Even with regular expression support it is almost impossible to safely match only a specific address domain. To match only email addresses (skinned from name and comment parts, see addrcodec† ) of address header fields (the mentioned ‘a’, ‘f’, ‘t’, ‘c’, ‘b’) against expr, prefix name-list with a tilde ‘˜’:
@˜f,c@@a\.safe\.domain\.match$
:c
All messages of state or with matching condition ‘c’, where ‘c’ is one or multiple of the following colon modifiers:
a
answered† messages (markanswered† ).
d
‘deleted’ messages (only for undelete† and from† ).
f
flag† ged messages.
L
Messages with recipients that match mlsubscribe† d addresses.
l
Messages with recipients that match mlist† ed addresses.
N
‘newest’ messages, for example joined in via newmail† .
n
‘new’ messages.
o
Old messages (any not in state ‘read’ or ‘new’).
r
‘read’ messages.
S
[Option] Messages with unsure spam classification (see Handling spam† ).
s
[Option] Messages classified as spam.
t
Messages marked as draft† .
u
‘unread’ messages.
[Option] IMAP-style SEARCH expressions may be used. These consist of keywords and criterions, and because Message list arguments† are split into tokens according to Shell-style argument quoting† it is necessary to quote the entire IMAP search expression in order to ensure that it remains a single token.
This addressing mode is available with all types of mailbox folder† s, a local search is performed as necessary. Strings must be enclosed by double quotation marks ‘"’ in their entirety if they contain whitespace or parentheses; within the quotes, only reverse solidus ‘\’ is recognized as an escape character. All string searches are case-insensitive. When the description indicates that the “envelope” representation of an address field is used, it means the search string is checked against both a list constructed as
’("name" "source" "local-part" "domain-part")’
for each address, and the addresses without real names from the respective header field. These search expressions can be nested using parentheses, see below for examples.
(criterion)
All messages that satisfy the given criterion.
(criterion1 criterion2 ... criterionN)
All messages that satisfy all of the given criteria.
(or criterion1 criterion2)
All messages that satisfy any of criterion1 or criterion2. To connect more than two criteria using ‘or’ specifications have to be nested using additional parentheses, as with ‘(or a (or b c))’, since ‘(or a b c)’ really means ‘((a or b) and c)’. For a simple ‘or’ operation of independent criteria on the lowest nesting level, it is possible to achieve similar effects by using three separate criteria, as with ‘(a) (b) (c)’.
(not criterion)
All messages that do not satisfy criterion.
(bcc "string"), (cc "string"), (from "string"), (subject "string"), (to "string")
All messages that contain string in the given header field.
(header name "string")
All messages that contain string in the ‘name:’ field.
(body "string")
All messages that contain string in their body.
(text "string")
All messages that contain string in their header or body.
(larger size), (smaller size)
All messages that are larger/smaller than size (in bytes).
(before date), (on date), (since date), (sentbefore date), (senton date), (sentsince date)
All messages received/sent before/on/since date, which must be in the form ‘d[d]-mon-yyyy’, where ‘d’ denotes the day of the month as one or two digits, ‘mon’ is the name of the month – one of ‘Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec’, and ‘yyyy’ is the year as four digits, for example ‘28-Dec-2012’.
()
The same criterion as for the previous search. This specification cannot be used as part of another criterion. If the previous command line contained more than one independent criterion then the last of those criteria is used.
Terminal
control and line editor
[Option] Terminal control depends on the standard UNIX
libraries Termcap Access Library (libtermcap,
−ltermcap) or Terminal Information Library
(libterminfo, −lterminfo), and enhances or enables
interactive usage aspects, like Coloured
display† ,
and understanding of cursor and function keys for the
Mailx-Line-Editor MLE for the
TERM† inal found in the
ENVIRONMENT† . Library
interaction can be disabled via
termcap-disable† , whereas
termcap† is always
inspected to learn about terminal capabilities.
[Option] The built-in Mailx-Line-Editor (MLE) should work in all environments which comply to the ISO C standard ISO/IEC 9899/AMD1:1995 (“ISO C90, Amendment 1”), and supports wide glyphs if possible (necessary functionality was removed from ISO C, but is included in X/Open Portability Guide Issue 4 (“XPG4”)). It offers some colour† support, and is tunable to an extend via line-editor-config† . Especially without terminal control some keys may be problematic, corrections via termcap† help – an example is shown in the FAQ† entry Not "defunctional", but the editor key does not work† . line-editor-disable† controls usage of the line editor.
[Option] Input from line editor prompts can be saved in a list of searchable and expandable history† entries; Any amount of leading whitespace prevents this saving. Aspects of history like size and persistancy can be configured via history-file† , history-gabby† , history-gabby-persist† and history-size† ; the Macro† hook on-history-addition† allows fine-grained control.
The MLE supports a set of editing and control commands. By default (as) many (as possible) of these will be assigned to a set of single-letter control codes. These should work on any terminal, and can be generated by holding the “control” key while simultaneously pressing the key of desire, for example ‘control-D’.
[Option] Custom key bind† ings that map MLE or other commands to key sequences can be established. If so, the MLE will itself use bind† to install the built-in set from above, plus, unless prevented via line-editor-no-defaults† . If supported by the TERM† inal mle-be-bd-ps† (see there) is enabled regardless of this setting.
In the following list keys are shown via Shell-style argument quoting† and MLE command names in parenthesis.
‘\cA’
Go to the start of the line (mle-go-home ).
‘\cB’
Move the cursor backward one character (mle-go-bwd ).
‘\cC’
raise(3) ‘SIGINT’ (mle-raise-int ).
‘\cD’
Forward delete the character under the cursor; quit† s if used on an empty line unless ignoreeof† is set (mle-del-fwd ).
‘\cE’
Go to the end of the line (mle-go-end ).
‘\cF’
Move the cursor forward one character (mle-go-fwd ).
‘\cG’
Cancel current operation, full reset. An active history search or tabulator expansion is reset first, restoring former line content: a second invocation is needed for a full reset, then. (mle-reset ).
‘\cH’
Backspace: backward delete one character (mle-del-bwd ).
‘\cI’
[Only new quoting rules] Horizontal tabulator: try to expand the word before the cursor, supporting the usual Filename transformations† (mle-complete ; affected by mle-quote-rndtrip† and line-editor-cpl-word-breaks† ).
‘\cJ’
Newline: complete input line (mle-commit ).
‘\cK’
Cut all characters from the cursor to the end of the line (mle-snarf-end ).
‘\cL’
Repaint the line (mle-repaint ).
‘\cN’
[Option] Go to the next history entry (mle-hist-fwd ).
‘\cO’
([Option]ally context-dependent) Invokes the command dt† .
‘\cP’
[Option] Go to the previous history entry (mle-hist-bwd ).
‘\cQ’
Toggle roundtrip mode shell quotes, where produced, on and off (mle-quote-rndtrip ). The default is configurable via line-editor-config† ; also see shcodec† .
‘\cR’
[Option] Complete line content from (the remaining) older history entries (mle-hist-srch-bwd ). Search behavior is configurable via line-editor-config† .
‘\cS’
[Option] Complete line content from (the remaining) newer history entries (mle-hist-srch-fwd ). Search behavior is configurable via line-editor-config† .
‘\cT’
Paste the snarf buffer (mle-paste ).
‘\cU’
The same as ‘\cA’ followed by ‘\cK’ (mle-snarf-line ).
‘\cV’
Prompts for a Unicode character (hexadecimal number without prefix, see number syntax rules† ) to be inserted (mle-prompt-char ). Note this needs to be assigned to a single-letter control code in order to become recognized and executed during input of a key-sequence (only three single-letter control codes can be used for that shortcut purpose); this control code is special-treated, then, and cannot be part of any other sequence (because it will trigger the mle-prompt-char function immediately).
‘\cW’
Cut the characters from the one preceding the cursor to the preceding word boundary (mle-snarf-word-bwd ).
‘\cX’
Move the cursor forward one word boundary (mle-go-word-fwd ).
‘\cY’
Move the cursor backward one word boundary (mle-go-word-bwd ).
‘\cZ’
raise(3) ‘SIGTSTP’ (mle-raise-tstp ).
‘\c[’
Escape: reset a possibly used multibyte character input state machine and [option]ally a lingering, incomplete key binding (mle-cancel ). Note this needs to be assigned to a single-letter control code in order to become recognized and executed during input of a key-sequence (only three single-letter control codes can be used for that shortcut purpose). The control code may also be part of a multibyte sequence, but if a sequence is active and the very control code is currently also an expected input, then the active sequence takes precedence and will consume the control code.
‘\c\’
([Option]ally context-dependent) Invokes the command ‘z† +’.
‘\c]’
([Option]ally context-dependent) Invokes the command ‘z† $’.
‘\cˆ’
([Option]ally context-dependent) Invokes the command ‘z† 0’.
‘\c_’
Cut the characters from the one after the cursor to the succeeding word boundary (mle-snarf-word-fwd ).
‘\c?’
Backspace: mle-del-bwd† .
–
mle-bell : ring the audible bell.
–
[Option] mle-clear-screen : move the cursor home and clear the screen.
–
mle-fullreset : different to mle-reset† this will immediately reset a possibly active search etc.
–
mle-go-screen-bwd : move the cursor backward one screen width.
–
mle-go-screen-fwd : move the cursor forward one screen width.
–
mle-raise-quit: raise(3) ‘SIGQUIT’.
–
[Option] mle-be-bd-ps : if “bracketed-paste” is supported by the TERM† inal (see termcap† ), enabled regardless of line-editor-no-defaults† to prevent undesired interpretation of pasted (clipboard) content. An implementation detail though documented and shown by bind† .
Coloured
display
[Option] Colours and font attributes through ANSI aka ISO
6429 SGR (select graphic rendition) escape sequences solely
depend upon capabilities of the
TERM† inal (see Terminal
control and line editor† ), and
are configurable via
colour† and
uncolour† . It may be
necessary to pass special command line options to make the
PAGER† interpret the escape
sequences correctly.
colour-disable† controls
usage of established colour mappings.
Colour setup could be conditionalized on interactive mode via if† (‘terminal’ indeed means “interactive”):
if terminal
&& $features =% ,+colour,
colour iso view-msginfo ft=bold,fg=green
colour iso view-header ft=bold,fg=red (from|subject) # regex
colour iso view-header fg=red
uncolour iso
view-header from,subject
colour iso view-header ft=bold,fg=magenta,bg=cyan
colour 256 view-header ft=bold,fg=208,bg=230
"subject,from"
colour mono view-header ft=bold
colour mono view-header ft=bold,ft=reverse subject,from
endif
Signed and
encrypted messages with S/MIME
[Option] S/MIME provides two central mechanisms: message
signing and message encryption. Signing allows recipients to
verify the message sender, and message encryption provides
end-to-end security that reveals the clear text of a message
only to the sender and the recipient.
A message is signed with a private key. This adds some data to the regular content which can be used to verify it was sent using a valid certificate, that the sender address is covered by the certificate, and that the content has not been altered. A signed message is received as clear text and can be handled without restrictions.
Encryption, in contrast, uses a public encryption key to make the message text invisible for all people except those who have access to a secret decryption key. The public encryption key must have been retrieved by other means, for example from previous communication, from securely visited web sites, from public key directories, etc. Because of the publicity messages should be signed before they become encrypted.
A central concept of S/MIME are certification authorities (CAs). These are trusted institutions which issue certificates that correlate a user’s private decryption and signing key (and its public variant) with the CA’s own by means of a certificate request. This makes it cryptographically possible to verify the key correlation of a CA and a user: verification will succeed if a CA certificate is found that is a(n in)direct signer of (a) presented user certificate(s).
A set of CA certificates is usually available from the distributor of the operating system, or comes shipped with the used cryptographical library: reasonable security for S/MIME on the Internet is provided if the source that provides the set is trusted. A certificate cannot be more secure than the method its CA certificate has been retrieved with. A personal set of trusted certificates can be specified via smime-ca-file† and/or (with special preparation) smime-ca-dir† . Setting smime-ca-no-defaults† disables (additional) usage of the default certificate set.
The set of CA certificates is used by the command verify† to ensure the given S/MIME message(s) can be trusted. If so, verified sender certificates that were embedded in signed messages can be saved locally with certsave† , and henceforth be used to encrypt further communication:
certsave
FILENAME
#..
set smime-encrypt-USER@HOST=FILENAME \
smime-cipher-USER@HOST=AES-256-CBC
To sign outgoing messages a personal S/MIME certificate is required. S/MIME step by step† shows exemplarily how a personal S/MIME certificate can be obtained. In general, if the private key plus certificate “pair” is available, all that needs to be done is to set some variables, in particular smime-sign-cert† :
set
smime-sign-cert=myname@exam.ple.paired \
smime-sign-digest=SHA512 \
smime-sign from=myname@exam.ple
Variables of interest for S/MIME in general are smime-ca-dir† , smime-ca-file† , smime-ca-flags† , smime-ca-no-defaults† , smime-crl-dir† , smime-crl-file† . For S/MIME signing of interest are smime-sign† , smime-sign-cert† , smime-sign-include-certs† and smime-sign-digest† . Additional variables of interest for S/MIME en- and decrypt† ion: smime-cipher† and smime-encrypt-USER@HOST† . Variables of secondary interest may be content-description-smime-message† and content-description-smime-signature† . S/MIME is available if ‘,+smime,’ is included in features† .
[v15 behavior may differ] Note that neither S/MIME signing nor encryption applies to message subjects or other header fields yet. Thus they may not contain sensitive information for encrypted messages, and cannot be trusted even if the message content has been verified. When sending signed messages, it is recommended to repeat any important header information in the message text.
URL syntax
and credential lookup
For accessing protocol-specific resources Uniform Resource
Locators (URL, RFC 3986) have become omnipresent. Here they
are expected in a “normalized” variant that is
not used in data exchange, but only meant as a compact,
easy-to-use way of defining and representing information in
a well-known notation; as such they do not conform to any
real standard. Optional parts in brackets ‘[]’
are optional either because other ways exist to define the
information, or because the part is protocol specific.
‘/path’ for example is used by [option]al
Maildir†
folder† s and IMAP, but not
by POP3. Note ‘USER’ and ‘PASSWORD’
within an URL must be URL percent encoded (RFC 3986), see
urlcodec† .
PROTOCOL://[USER[:PASSWORD]@]server[:port][/path]
Often INTERNAL VARIABLES† exist in “variable chains”: the plain ‘variable’ as well as ‘variable-HOST’ and ‘variable-USER@HOST’. If a port was specified ‘HOST’ really means ‘server:port’, not ‘server’. And this ‘USER’ is never in URL percent encoded form. For example, whether the hypothetical ‘smtp://hey%2Bhey:wings%3Aof@a.dove’ including user and password was used, or whether it was ‘smtp://a.dove’ and they came from a different sources, to lookup the chain tls-config-pairs† first ‘tls- config-pairs-hey+hey@a.dove’ is looked up, then ‘tls-config-pairs− a.dove’, then the plain variable at last.
The logic to collect credentials (of an account† ) is as follows:
•
A user is always required. If no ‘USER’ has been given in the URL user-HOST and user† are looked up.
[Option] Thereafter, when allowed by netrc-lookup-HOST or netrc-lookup† , The .netrc file† (of LOGNAME† ) will be searched for an unambiguous (one possible match) ‘HOST’ entry with a ‘login’ name.
If there is still no ‘USER’ the verified, valid LOGNAME† is used.
•
Authentication: unless otherwise noted the chain PROTOCOL-auth-USER@HOST, PROTOCOL-auth-HOST, PROTOCOL-auth is checked, falling back to a protocol-specific default as necessary.
•
If no ‘PASSWORD’ has been given in the URL, then if the ‘USER’ has been found through the [option]al netrc-lookup† , that may have also provided the password. Otherwise the chain password-USER@HOST, password-HOST, password† is looked up.
[Option] Thereafter the (now complete) chain netrc-lookup-USER@HOST, netrc-lookup-HOST, netrc-lookup† is checked, if set the netrc† cache is searched for a password only (multiple user accounts for a single machine may exist as well as a fallback entry without user but with a password).
If at that point a password is required but not available, then in interactive mode the user will be prompted.
Note: S/MIME verification works relative to the values found in the ‘From:’ (or ‘Sender:’) header field(s), therefore smime-sign† , smime-sign-cert† , smime-sign-include-certs† and smime-sign-digest† will not be looked up using above’s ‘USER’ and ‘HOST’ chains, but instead use values from the message that is being worked on. If no address matches from† is used. In unusual cases multiple and different ‘USER’ and ‘HOST’ combinations may therefore be involved – on the other hand those unusual cases become possible. The usual case is as short as:
set
mta=smtp://USER:PASS@HOST smtp-config=-starttls \
smime-sign smime-sign-cert=+smime.pair \
from=myname@my.host
Encrypted
network communication
[Option] SSL (Secure Sockets Layer) aka its successor TLS
(Transport Layer Security) are protocols which aid in
securing communication by providing a safely initiated and
encrypted network connection. As part of each connection
setup a set of certificates will be exchanged through which
the identity of the network peer can be cryptographically
verified against a local set of trusted certificates. If
possible the TLS/SNI (ServerNameIndication) extension will
be enabled to allow servers fine-grained control over the
presented certificates.
A central concept of TLS are certification authorities (CAs). These are trusted institutions which issue certificates that correlate a partie’s private key (and its public variant) with the CA’s own by means of a certificate request. This makes it cryptographically possible to verify the key correlation of a CA and a party: verification will succeed if a CA certificate is found that is a(n in)direct signer of (a) presented party certificate(s).
A set of CA certificates is usually available from the distributor of the operating system, or comes shipped with the used cryptographical library: reasonable security for TLS on the Internet is provided if the source that provides the set is trusted. A certificate cannot be more secure than the method its CA certificate has been retrieved with. A personal set of trusted certificates can be specified via tls-ca-file† and/or (with special preparation) tls-ca-dir† . Setting tls-ca-no-defaults† disables (additional) usage of the default certificate set.
For inspection or other purposes, the certificate of a server (as seen when connecting to it) can be fetched with the command tls† (port can usually be the protocol name, too, and tls-verify† is taken into account here):
$ s-nail -vX ’tls certchain SERVER-URL[:PORT]; x’
Server certificates can also be verified through their fingerprint, eliminating the need for a local set of CA certificates: a message digest will be calculated and compared against tls-fingerprint† . A digest (algorithm) can be configured via tls-fingerprint-digest† ; tls† can again be used:
$ s-nail -X ’set verbose; tls fingerprint SERVER-URL[:PORT]; x’
It depends on the protocol whether encrypted communication is available, and which configuration steps have to be taken to enable it. Some protocols, like POP3S, are implicitly encrypted, others, like POP3, can upgrade a plain text connection if so requested. For example, to use the ‘STLS’ that POP3 offers pop3-use-starttls† needs to be set; here with a convenient shortcut† :
shortcut encpop1 pop3s://pop1.exam.ple
shortcut
encpop2 pop3://pop2.exam.ple
set pop3-use-starttls-pop2.exam.ple
set
mta=smtps://smtp.exam.ple:465
# Automatically upgrades unless smtp-config=-starttls
set mta=smtp://smtp.exam.ple
TLS libraries try to provide safe defaults, plenty of knobs however exist to adjust settings. For example certificate verification can be fine-tuned via tls-ca-flags† , and TLS configuration basics are accessible via tls-config-pairs† , for example to control protocol versions or cipher lists. Here an example that enforces only top-modern (as of 2022) forward-secrecy ciphers:
set
tls-config-pairs=’MinProtocol=TLSv1.2,\
CipherString=\
EECDH+AESGCM:EECDH+AES256:EDH+AESGCM:CHACHA20:\
!DHE:!AESCCM8’#!TLSv1’
The OpenSSL program ciphers(1) should be referred to when creating a custom cipher list. Variables of interest for TLS in general are tls-ca-dir† , tls-ca-file† , tls-ca-flags† , tls-ca-no-defaults† , tls-config-file† , tls-config-module† , tls-config-pairs† , tls-crl-dir† , tls-crl-file† , tls-rand-file† as well as tls-verify† . Also see tls-features† . TLS is available if ‘,+tls,’ is included in features† .
Handling
spam
[Option] Several
spam-interface† s for
dealing with spam messages are configurable. The volatile
‘is-spam’ state of classified messages can
appear in the attrlist† of
their headline† in the
summary of headers† , and
‘:s’ and ‘:S’ select
them when Specifying
messages† .
•
spamrate† rates the given messages and sets their ‘is-spam’ flag accordingly. If the spam interface offers spam scores these can be shown in headline† by using the format ‘%$’.
•
spamham† , spamspam† and spamforget† interact with the Bayesian filter of the chosen interface.
•
spamclear† and spamset† simply set and clear, respectively, the mentioned volatile ‘is-spam’ message flag, they do not interact with spam-interface† .
The spamassassin(1) based spam-interface† ‘spamc’ requires a running instance of the spamd(1) server in order to function, started with the option −-allow-tell shall Bayesian filter learning be possible.
$ spamd -i
localhost:2142 -i /tmp/.spamsock -d [-L] [-l]
$ spamd --listen=localhost:2142 --listen=/tmp/.spamsock \
--daemonize [--local] [--allow-tell]
Thereafter these interfaces can be used:
$ s-nail
-Sspam-interface=spamc -Sspam-maxsize=500000 \
-Sspamc-command=/usr/local/bin/spamc \
-Sspamc-arguments="-U /tmp/.spamsock"
-Sspamc-user=
# or
$ s-nail -Sspam-interface=spamc -Sspam-maxsize=500000 \
-Sspamc-command=/usr/local/bin/spamc \
-Sspamc-arguments="-d localhost -p 2142"
-Sspamc-user=
Using the generic filter approach allows usage of programs like bogofilter(1). Here is an example that assumes the program in PATH† :
$ s-nail
-Sspam-interface=filter -Sspam-maxsize=500000 \
-Sspamfilter-ham="bogofilter -n" \
-Sspamfilter-noham="bogofilter -N" \
-Sspamfilter-nospam="bogofilter -S" \
-Sspamfilter-rate="bogofilter -TTu 2>/dev/null"
\
-Sspamfilter-spam="bogofilter -s" \
-Sspamfilter-rate-scanscore="1;ˆ(.+)$"
Messages must be locally present for scoring or Bayesian filter training purposes. Spam can be checked automatically when switching to folder† s by setting a specialized form of on-mailbox-event† .
define
spamdelhook {
if $1 != open && $1 != newmail
return
end
# Server side DCC
spamset (header x-dcc-brand-metrics "bulk")
# Server-side spamassassin(1)
spamset (header x-spam-flag "YES")
del :s # TODO we HAVE to be able to do ‘spamrate :u !
:sS’
move :S +maybe-spam
spamrate :u
del :s
move :S +maybe-spam
}
set on-mailbox-event-SOMEFOLDER=spamdelhook
See also spam-interface† , spam-maxsize† , spamc-command† , spamc-arguments† , spamc-user† , spamfilter-ham† , spamfilter-noham† , spamfilter-nospam† , spamfilter-rate† and spamfilter-rate-scanscore† .
In normal input mode (compare: Compose mode† ) input is read in lines. An unquoted reverse solidus ‘\’ at the end of a line “escapes” the newline character: it is discarded, and the next line of input is used as a follow-up line, with all leading whitespace removed. Once a line is completed, the whitespace characters space, tabulator, newline as well as those defined by ifs† are removed from both ends. [Option] Any preceded whitespace however prevents addition to history† .
The line is then scanned for a command name, possibly prepended by Command modifiers† . Names may be abbreviated in “first substring match wins” mode; POSIX.1-2024 standardized certain abbreviations, shown in parenthesis in the list below, and resulting in diverse rule deviations. A name may also be a commandalias† , it is then recursively expanded first; such aliases cannot be abbreviated. Once the command that shall be evaluated is known, the remains of the line will be interpreted according to command-specific rules, most often Shell-style argument quoting† . In interactive mode a command-less line (with optional arguments) invokes next† .
Remarks: this behavior is different to the SHELL† programming language with its syntactic elements of clearly defined semantics, capable to sequentially expand and evaluate individual elements of a line. For us ‘? set one=spoon two=$one’ for example will never assign ‘spoon’ to two, because the command set† itself performs the assignment, long after the expansion has happened.
When a command returns its exit status is available in the variable ?† ; in error cases an error number is announced in !† (and accompanies) ([v15 behavior may differ] Yet too often the umbrella value ˆERR† -INVAL will be seen). A non-0 exit status has a meaning in the state machine: a set† errexit† will cause a program exit, just like any error while loading Resource files† in posix† mode. ignerr† , one of the Command modifiers† , instructs the state machine to ignore errors; COMMAND ESCAPES† offer a similar mechanism.
A list of all commands in lookup order is dumped by list† . help† (alias: ?† ) shows an abstract for its argument, as in ‘?t’, short for ‘? type’; both commands support a verbose† mode that prints argument types and some more information which applies; a handy suggestion may thus be:
define xverbose
{
\local set verbose; eval ignerr local pp "$@";
\return $?
}
commandalias xv ’\call xverbose’
xv ? set
#..
Command
modifiers
Modifiers adjust behavior of argument processing and
Commands† . None to multiple
may be prepended (case-insensitively) to a command, the
order of which is insignificant, except for scopes.
Expansions of eval† uation
and commandalias† es may
contain them. Some modifiers apply to only specific
COMMANDS† , as shown in
verbose†
list† mode.
Up to three different scopes may apply to a command invocation, each either local† , our† or global† : pp† for positional parameter processing (and during eval† uation), >† for result storage, and finally for the command and its side-effects as such; commands with the sole purpose of creating result storage, like read† or readall† , may have no >† , but only command-scope. “Scope” may mean different things, please see our† .
The following, most complicated possible example accesses the global† positional parameter stack via vpospar† , stores the result in our† variable ‘i2’, and creates a local† temporary variable during argument option processing:
define hi {
local pp our >i$((i = 1 + 1)) global vpospar quote
xcall t "$@"
}
define t {
echo "args<$*> i2<$i2> i<$i>"
}
vpospar set three four
call hi one two
#-> args<one two> i2<three four> i<>
varshow i i2 *
#-> #unset: i
#-> #unset: i2
#-> #*=’three four’
Reverse solidus prevents commandalias† expansion (that may contain additional modifiers), for example ‘\echo’ always evaluates the echo† command, even if such an alias exists. Need not be whitespace-separated from other modifiers or command names.
Redirect command output to variable name instead of the default location (usually written to standard output). The name expansion is pp† scoped, the name must comply to SHELL† variable name rules and consist only of upper- and lowercase characters, digits, and the underscore; hyphen-minus may be used as a non-portable extension. Leading digits and hyphen-minus, as well as a trailing hyphen-minus are not allowed. Variables linked to the ENVIRONMENT† may not use extensions. INTERNAL VARIABLES† other than writable (non-(Boolean)) value variables may not be used; a failure may occur nonetheless for unsatisfied content constraints. Any test or storage error causes failure, with !† set to ˆERR† -NOTSUP and ?† set to ‘-1’, but some commands deviate, then documented.
>msgno =;
echo "$msgno"
#-> 1
>i$((i = 1 + 1)) echon some output; ec
"i2<$i2>, i<$i>".
#-> i2<some output>, i<2>.
Repeatedly concatenate arguments, expanded according to Shell-style argument quoting† , thereafter separated by single space characters, as often as used. A scope can be enforced via pp† .
set i=hey
j=’$i’
echo ’$j’
#-> $j
eval echo ’$j’
#-> $i
eval eval echo ’$j’
#-> hey
define xxx {
ec "<$1>"
shift; if $# -gt 0; \xcall xxx "$@"; end
}
define yyy {
eval "$@ ’ ball"
}
call yyy ’\call xxx’ "b\$’\t’u
’ "
#..
call xxx arg <b u>
#..
call xxx arg <ball>
#..
Select global scope (when supported).
Ignore errors, and do neither quit† the program with errexit† nor for the standardized exit cases of posix† mode. ?† will contain the real exit status of the command regardless.
Select local scope (when supported). For set† and unset† any change is reverted once the current scope is left. For scope introducing commands like call† , call_if† and xcall† , but also for example mail† , reply† and all other Commands† which enter Compose mode† , change localization applies to the newly created scope.
Remarks: whereas localized free-form user INTERNAL VARIABLES† are only visible within the macro (define† , account† ) in which they are declared, and “shadow” all other names, for ENVIRONMENT† and Built-in variables† local† effectively equals our† .
Select our scope (when supported): changes are visible in the current as well as all scopes deeper in the call† chain. “Current scope” usually means the body of the currently evaluated Macro† , but it extends until a different account is activated for account† , and some macros, notably on-mailbox-event† s, use their own specific notion, here it will be extended until the folder† is left again.
Use (and reset) previous scope modifier for any positional parameter eval† uation. In the example the variable ‘j’ will be created in local† scope (with value 4).
define x {
local set i=’3 + 1’
local pp echo hello $((j = $i + 1))
}
call x
[v15 behavior may differ] Does not yet implement any functionality. When supported command arguments are interpreted as UTF-8 character data, regardless of ttycharset† (aka LC_ALL† ).
Can be used for some old and established commands to choose the new Shell-style argument quoting† rules over the traditional Old-style argument quoting† . This modifier is implied if v15-compat† is set to a non-empty value, which now is the default. This modifier will first become a no-op, and later be removed.
Old-style
argument quoting
[v15 behavior may differ] This section documents the
traditional and POSIX.1-2024 standardized style of quoting
non-message list arguments to commands which expect this
type of arguments: whereas still used by the majority of
such commands, the new Shell-style argument
quoting† may be available even
for those via wysh† .
Nonetheless care must be taken, because only new commands
have been designed with all the capabilities of the new
quoting rules in mind, which can, for example, generate
control characters.
•
An argument can be enclosed between paired double-quotes ‘"argument"’ or single-quotes ‘’argument’’; any whitespace, shell word expansion, or reverse solidus characters (except as described next) within the quotes are treated literally as part of the argument. A double-quote will be treated literally within single-quotes and vice versa. Inside such a quoted string the actually used quote character can be used nonetheless by escaping it with a reverse solidus ‘\’, as in ‘"y\"ou"’.
•
An argument that is not enclosed in quotes, as above, can usually still contain space characters if those spaces are reverse solidus escaped, as in ‘you\ are’.
•
A reverse solidus outside of the enclosing quotes is discarded and the following character is treated literally as part of the argument.
Shell-style
argument quoting
SHELL† -style, and therefore
POSIX.1-2024 standardized argument parsing, expansion, and
quoting rules are used by most commands. ([v15 behavior may
differ] Most new commands already support these and are
flagged [Only new quoting rules], some elder can optionally
use them via wysh† .) The
command line that resulted from input scanning as described
for COMMANDS† is parsed from
left to right, and an input token is completed whenever an
unquoted, otherwise ignored, metacharacter is seen.
Metacharacters are vertical bar |, semicolon ;, as well as all characters from the variable ifs† , and/or space, tabulator, newline. The additional SHELL† metacharacters ampersand &, left and right parenthesis (, ) and less-than and greater-than signs <, >† are treated as ordinary characters: they are either vivid parts of email addresses or Filename transformations† . Any unquoted number sign ‘#’ that begins a new token starts a comment that extends to the end of the line, and therefore ends argument processing. An unquoted dollar sign ‘$’ starts Shell-style expansions† .
Different to the metacharacters space, tabulator, newline that only complete an input token, vertical bar | and semicolon ; also act as control operators and perform control functions. For now supported is semicolon ;, it terminates a single command, therefore sequencing the line, and making the remainder of it subject to reevaluation. With sequencing, multiple command argument types and quoting rules may therefore apply to a single line, which can be problematic before v15 and without v15-compat† ; for example, the first of the following will cause surprising results:
? echo one; set
verbose; echo "verbose=$verbose."
? echo one; wysh set verbose; echo
"verbose=$verbose."
Quoting is a mechanism that removes the special meaning of metacharacters and reserved words, and prevents expansion. There are four quoting mechanisms: the escape character, single-quotes, double-quotes and dollar-single-quotes:
•
The literal value of any character can be preserved by preceding it with the escape character reverse solidus ‘\’.
•
Arguments which are enclosed in ‘’single-quotes’’ retain their literal value. A single-quote cannot occur within single-quotes.
•
The literal value of all characters enclosed in ‘"double- quotes"’ is retained, with the exception of dollar sign ‘$’ that causes Shell-style expansions† , backquote (grave accent) ‘‘’ (which not yet means anything special), reverse solidus ‘\’ that escapes any of the characters dollar sign ‘$’, backquote (grave accent) ‘‘’, double-quote ‘"’ (to prevent ending the quote), and reverse solidus ‘\’ (to prevent escaping, that is, to embed a reverse solidus character as-is), but has no special meaning otherwise.
•
Arguments enclosed in ‘$’dollar-single-quotes’’ extend normal single quotes in that reverse solidus escape sequences are expanded as follows:
‘\a’
bell control character (ASCII and ISO-10646 BEL).
‘\b’
backspace control character (ASCII and ISO-10646 BS).
‘\E’
escape control character (ASCII and ISO-10646 ESC).
‘\e’
the same.
‘\f’
form feed control character (ASCII and ISO-10646 FF).
‘\n’
line feed control character (ASCII and ISO-10646 LF).
‘\r’
carriage return control character (ASCII and ISO-10646 CR).
‘\t’
horizontal tabulator control character (ASCII and ISO-10646 HT).
‘\v’
vertical tabulator control character (ASCII and ISO-10646 VT).
‘\\’
emits a reverse solidus character.
‘\’’
single quote.
‘\"’
double quote (need not be escaped, but can).
‘\NNN’
eight-bit byte with the octal value ‘NNN’ (one to three octal digits), optionally prefixed by an additional ‘0’. A 0 byte will suppress further output for the quoted argument.
‘\xHH’
eight-bit byte with the hexadecimal value ‘HH’ (one or two hexadecimal characters, no prefix, see number syntax rules† ). A 0 byte will suppress further output for the quoted argument.
‘\UHHHHHHHH’
the Unicode / ISO-10646 character with the hexadecimal codepoint value ‘HHHHHHHH’ (one to eight hexadecimal characters) — note that Unicode defines the maximum codepoint ever to be supported as ‘0x10FFFF’ (in planes of ‘0xFFFF’ characters each). This escape is only supported in locales that support Unicode (see Character sets† ), in other cases the sequence will remain unexpanded unless the given code point is ASCII compatible or (if the [option]al character set conversion is available) can be represented in the current locale. The character NUL will suppress further output for the quoted argument.
‘\uHHHH’
Identical to ‘\UHHHHHHHH’ except it takes only one to four hexadecimal characters.
‘\cX’
Emits the non-printable (ASCII and compatible) C0 control codes 0 (NUL) to 31 (US), and 127 (DEL). Printable representations of ASCII control codes can be created by mapping them to a different, visible part of the ASCII character set. Adding the number 64 achieves this for the codes 0 to 31, here 7 (BEL): ‘7 + 64 = 71 = G’. The real operation is a bitwise logical XOR with 64 (bit 7 set, see Shell-style expansions† ), thus also covering code 127 (DEL), which is mapped to 63 (question mark): ‘? echo $((127 ˆ 64))’.
Whereas historically circumflex notation has often been used for visualization purposes of control codes, as in ‘ˆG’, the reverse solidus notation has been standardized: ‘\cG’. Some control codes also have standardized (ISO-10646, ISO C) aliases, as shown above (‘\a’, ‘\n’, ‘\t’ etc): whenever such an alias exists it will be used for display purposes. The control code NUL (‘\c@’, a non-standard extension) will suppress further output for the remains of the token (which may extend beyond the current quote), or, context-dependent, the remains of all arguments for the current command.
‘\$expression’
Non-standard extension to embed Shell-style expansions† .
‘\‘{command}’
Not yet supported, just to raise awareness: Non-standard extension.
Caveats:
echo
’Quotes ’${HOME}’ and ’tokens"
differ!"# no comment
echo Quotes ${HOME} and tokens differ! # comment
echo Don"’"t you worry$’\x21’
The sun shines on us. $’\u263A’
define xy {
ec "$# 1<$1> 2<$2> 3<$3>
<$*>"
}
se x=’one two three’
call xy $x four
#-> 4 1<one> 2<two> 3<three> <one
two three four>
call xy "$x" four
#-> 2 1<one two three> 2<four> 3<>
<one two three four>
Shell-style
expansions
When and how these expansions occur is documented in
Shell-style argument
quoting† . An unquoted dollar
sign ‘$’ triggers expression expansions. The
simplemost expression is an optionally curly bracket
enclosed variable name, for example ‘$NAME’ or
‘${NAME}’, which must honour variable name
rules† : INTERNAL
VARIABLES† as well as
ENVIRONMENT† (shell)
variables can be accessed and expanded through this
mechanism. Shell-style field
splitting† is performed on
non-empty such expansions unless quoting is active, or
COMMANDS† explicitly mention
[No field splitting].
Within pairs of double parenthesis ‘$(( ))’ 64-bit signed integer arithmetic expansions are performed. Different to vexpr† no saturated mode is available (overflow constants will result), and errors are not trackable: a syntactically invalid expression causes the context (COMMANDS† ) to fail due to invalid arguments. Variable NAMEs can be referenced: unset or empty values expand to 0, otherwise the value is interpreted as a self-contained expression to expand arithmetically first. Numbers prefixed with ‘0x’ or ‘0X’ denote hexadecimal (base 16) numbers, ‘0’ indicates octal (base 8), and ‘0b’ as well as ‘0B’ denote binary (base 2) numbers. A permissive ‘NUMBER’ parse mode (see example) is used for the ‘BASE#NUMBER’ notation; ‘BASE’ is an unsigned decimal in the range 2 and 64, inclusive. (Beware: ‘008’ is an invalid octal number, parsed as 0 and the string 8; better is ‘10#008’.) Power-of-two bases are parsed as unsigned integers (making for overflow constant differences). The following list of operators is sorted in decreasing precedence.
Remarks: Recall that different to the shell hyphen-minus ‘-’ is a valid part of NAMEs, therefore contractions like ‘J-I’ reference a name ‘J-I’ instead of subtracting the name ‘I’ from ‘J’!
set i=0; echo
$((i + i)), $((i+=1)), $((i + i)); varshow i
#-> 0, 1, 2
#-> set i=1
set i=-2; echo $(( 10# $i))
#-> -2
Compatibility note: [v15 behavior may differ] Of the following, only “The result is treated as the arithmetic expression to be evaluated” is true: The expression is treated as if it were within double quotes, but a double quote inside the parentheses is not treated specially. All tokens in the expression undergo parameter and variable expansion, command substitution, and quote removal. The result is treated as the arithmetic expression to be evaluated. Arithmetic expansions may be nested.
(, )
Parenthesis can be used to form sub-expressions which are evaluated with the highest precedence.
VAR++, VAR--
Postfix increment and decrement, for variables.
+, -
Unary plus and minus.
++VAR, --VAR
Prefix increment and decrement, for variables.
!, ˜
Logical and bitwise negation.
**
Exponentiation.
*, /, %
Multiplication, division, remainder (modulo).
+, -
Addition and subtraction.
<<, >>, >>>
Bitwise shifts, the last performs an unsigned right shift. (Only the 6 least significant bits of the shift operand are used.)
<=, >=, <, >
Comparison.
==, !=
Equality and inequality.
&
Bitwise AND.
ˆ
Bitwise XOR.
|
Bitwise OR.
&&
Logical AND.
||
Logical OR.
EXPR0 ? EXPR1 : EXPR2
Conditional operator: if EXPR0 is true evalute EXPR1, otherwise evaluate EXPR2; this can be nested. Precedence note: for example ‘1?crt=10:crt=5’ is an error because it really is ‘(1?(crt=10):crt)=5’; ‘1?crt=10:(crt=5)’ is ok.
**=, *=, /=, %=, +=, -=, <<=, >>=, >>>=, &=, ˆ=, |=, =
Assignment. It is subject to scoping rules; local† ly set† ting a variable before arithmetically expanding it is an option.
EXPR1 , EXPR2
Comma (sequential evaluation).
Message list
arguments
Many commands operate on message lists as documented in
Specifying messages† . Input
is first split into individual tokens via Shell-style
argument quoting† , and then
interpreted as said. If no explicit message list has been
specified, many commands will search for and use the next
message forward that satisfies the commands’
requirements, and if there are no messages forward of the
current message, the search proceeds backwards; if there are
no good messages at all to be found, and the default
(“dot”) is not applicable, an error message is
shown instead. The verbose†
output of list† will
indicate when no default is used.
Raw data
arguments for codec commands
A special set of commands, all of which with
“codec” in their name, like
addrcodec† ,
shcodec† ,
urlcodec† , take raw string
data as input, which means that the input line is taken
literally: like this the effect of the actual codec is
visible without any noise of possible shell quoting rules
etc., that is, the user can input one-to-one the desired or
questionable data. To gain a level of expansion, the entire
command line can be eval†
uated first, for example
>res shcodec
encode /usr/Schönes Wetter/heute.txt
echo "$res"
#-> $’/usr/Sch\u00F6nes Wetter/heute.txt’
shcodec d "$res"
#-> $’/usr/Sch\u00F6nes Wetter/heute.txt’
eval shcodec d "$res"
#-> /usr/Schönes Wetter/heute.txt
Filename
transformations
Filenames, where expected, and unless documented otherwise,
are subject to the following transformations, in
sequence:
•
If the name is a registered shortcut† it will be expanded. This step is mostly taken by folder† s only.
•
The name is matched against the following patterns or strings. But for plus +file folder† expansion this step is mostly taken by folder† s only.
#
(Number sign) is expanded to the previous file.
%
(Percent sign) is replaced by the primary system mailbox, which either is the (itself expandable) inbox† if set, the standardized absolute pathname indicated by MAIL† if set, or a built-in compile-time default otherwise. When opening a folder† the name is checked for being a primary mailbox, first inbox, then MAIL† ; automatic message moving† does apply.
%user
Expands to the primary system mailbox of user (and never the value of inbox† , regardless of its actual setting).
&
(Ampersand) is replaced with the secondary mailbox, the MBOX† .
+file
Refers to a file in the folder† directory (if set† , and see outfolder† ).
%:filespec
Expands to the same value as filespec, but has special meaning when used with, for example, folder† : the file will be treated as a primary system mailbox by, among others, the mbox† and save† commands, meaning that messages that have been read in the current session will be moved to the MBOX† mailbox instead of simply being flagged as read.
•
Meta expansions may be applied to the resulting pathname, as allowed by the operation and applicable to the resulting access protocol (also see URL syntax and credential lookup† ). For the file-protocol, a leading tilde ‘˜’ character will be replaced by the expansion of HOME† , except when followed by a valid user name, in which case the home directory of the given user is used instead.
A shell expansion as if specified in double-quotes (see Shell-style argument quoting† ) may be applied, so that any occurrence of ‘$VARIABLE’ (or ‘${VARIABLE}’) will be replaced by the expansion of the variable, if possible; INTERNAL VARIABLES† as well as ENVIRONMENT† (shell) variables can be accessed through this mechanism.
Shell pathname wildcard pattern expansions (glob(7)) may be applied as documented. If the full expansion results in multiple pathnames, and the command is expecting only one file, an error results.
In interactive context, in order to allow simple value acceptance (via “ENTER”), arguments will usually be displayed in a properly quoted form, so a file ‘diet\ is \curd.txt’ may be displayed as ‘’diet\ is \curd.txt’’.
Invoke the given SHELL† command. May expand bang† when set (see there; reverse solidus has no other special meaning). >† (Command modifiers† ) is supported. A 0 or positive exit status ?† reflects the exit status of the command, negative ones either an error during execution setup, or an unclean program exit: ˆERR† -CHILD is the error number then.
Special cases with negative exit status exist in conjunction with >† : if storing the collected data in the variable fails ˆERR† -NOTSUP occurs, whereas a temporary data collection file creation failure causes ˆERR† -CANCELED; In case of catchable out-of-memory situations it is ˆERR† -NOMEM. Detected error conditions create an empty string result.
The comment-command causes the entire line to be ignored. This is a normal command which’ purpose is to discard its arguments. Shell-style argument quoting† is required for shell-style comments.
“dotquery”: query the unique number of the current message (the “dot”). With Message list arguments† show the resulting list of numbers, separated by the first byte of ifs† , and followed by the first byte of if-ws if non-empty and not identical. If this results in no separation at all a space is used. Note neither is “dot” moved (see dotmove† ), nor are Message states† updated. >† is supported.
[No field splitting] No-effect command: does nothing but expanding arguments. Remarks: as a command-less line invokes the default command (next† ) this conflicts the : argument (Specifying messages† ), but compatibility to the well-known sh(1) : command deemed more important than this special case.
Show a brief summary of commands. Given an optionally abbreviated name the according synopsis is shown instead, try for example ‘?h’, ‘?hel’ and ‘?help’, and see how the output changes. To avoid that commandalias† es are resolved the (quoted!) modifier \† can be prepended. A more verbose† output is supported.
A synonym for the pipe† command.
Create, select or list, and delete, respectively, those Macro† s that bundle settings for email account creation, covered by a specific scope† that extends until another account is activated. When left, also for a regular program quit† or when the account macro cannot be switched to successully, the hook on-account-cleanup† is called. There is a special read-only ‘null’ account for the purpose of changing to global scope.
Without arguments a list of all accounts is shown. With one argument the given one is activated: after the macro body has been evaluated its system inbox† is opened as via folder† , a possibly installed on-mailbox-event† will be run, and account† will be updated. An early use will have its system mailbox open delayed until program startup is completed (see −A† ); it cannot be called via −X† . The two argument form creates a new account macro as via define† .
Important settings for accounts include folder† , from† , hostname† , inbox† , mta† , record† , also password and user† (URL syntax and credential lookup† ), as well as things like smime-sign-cert† (Signed and encrypted messages with S/MIME† ), tls-config-pairs† (Encrypted network communication† ), and protocol specifics like imap-auth† , pop3-auth† , smtp-config† .
account myisp {
set folder=˜/mail inbox=+syste.mbox record=+sent.mbox
set from=’(My Name) myname@myisp.example’
set mta=smtp://me@smtp.myisp.example
}
Perform email address codec transformations on raw-data argument, rather according to email standards (RFC 5322; [v15 behavior may differ] will furtherly improve). Supports >† . The first argument must be any unique substring one of [+[+[+]]]encode, decode, skin, skinlist, and normalize. The last parses the data as a potential list of multiple email addresses (including comments etc), and normalizes them to make them accessible in result set† accessors ˆ#† , ˆ0† , ˆ1† etc; ˆ0† is the rejoined list of normalized data.
Decoding will show how a standard-compliant MUA will display the data. MUAs have varying support for address standards regarding comments, parenthesis, double-quoted strings, or so-called quoted-pairs. [v15 behavior may differ] S-nail currently does not perform decoding when displaying addresses.
Skinning parses the data as a single email address, strips any comments and name parts and outputs the address only. It may fail with !† set to ˆERR† -INVAL for invalid data, in which case the unmodified input is output again.
skinlist performs a skin operation, and on success tests whether the result is known by mlist† or mlsubscribe† , reporting the result via !† as ˆERR† -EXIST.
Encoding supports four different modes: the more plus signs, the lesser standard imposed special bytes are converted to so-called quoted-pairs. One plus sign to leave alone parenthesis, two for double quotation marks, three for also leaving reverse solidus alone. The result will be valid if a successful exit status is reported ([v15 behavior may differ] the current parser fails this assertion for some constructs). [v15 behavior may differ] Addresses need to be specified in between angle brackets ‘<’, ‘>’ if the construct becomes more difficult, otherwise the current parser will fail; it is not smart enough to guess right.
addrc enc
"Hey, you",<diet@exam.ple>\ out\ there
#-> "\"Hey, you\", \\ out\\ there"
<diet@exam.ple>
addrc d "\"Hey, you\", \\ out\\ there"
<diet@exam.ple>
#-> "Hey, you", \ out\ there
<diet@exam.ple>
addrc s "\"Hey, you\", \\ out\\ there"
<diet@exam.ple>
#-> diet@exam.ple
[Only new quoting rules](a, una) Define or list, and remove, respectively, address aliases: personal distribution lists that map single names to none to multiple names (recipients), expanded recursively according to metoo† after Compose mode† is left. (Unsupported the undocumented BSD Mail / System V10 mailx “trick” that implies metoo† if an alias that contains itself as only member.) Without arguments the former shows a list of all aliases, one per line, with one only its unexpanded value. With two arguments, the first being one of ‘-’, ‘--’, or ‘-+’, a recursive expansion of the second is shown: according to metoo† for the first, “as without” metoo† for the second, “as with” metoo† for the third.
In all other cases the given alias is created or appended to: arguments must be valid alias names or other address types (see Sending mail, and non-interactive mode† ). The later recursive expansion can be prevented by prefixing the desired name with reverse solidus ‘\’. A valid alias name conforms to mta-aliases† syntax, but follow-up characters can also be the number sign ‘#’, colon ‘:’, commercial at ‘@’, exclamation mark ‘!’, period ‘.’ as well as “any character that has the high bit set”. The dollar sign ‘$’ may be the last character. The number sign ‘#’ may need Shell-style argument quoting† .
[v15 behavior may differ] Unfortunately the colon is currently not supported, as it interferes with normal address parsing rules. [v15 behavior may differ] High bit characters will likely cause warnings at the moment for the same reasons why colon is unsupported; also, in the future locale dependent character set validity checks will be performed.
alias cohorts
bill \mark exa@m.ple ˜/cohorts.mbox
alias mark mark-exa@m.ple
set mta-aliases=/etc/aliases
[Only new quoting rules](alt) Manage a list of alternate addresses or names for the user: all such names are removed from recipient lists when reply† ing to messages, and always depending on metoo† from alias† expansions; implicitly added are LOGNAME† , from† or sender† , and reply-to† . The former shows the current list without arguments, then it supports >† . Otherwise the arguments are appended to the alternate list; in posix† mode they instead replace that list. The latter removes the given addresses, asterisk ‘*’ removes all.
Take a message list and mark each member as (not) having been answered. Dependent on markanswered† this is set automatically by reply† . See Message states† .
[Option][Only new quoting rules] Configure M(ailx)-L(ine)-E(ditor) key bindings (Terminal control and line editor† ). The latter removes from the given context the given key binding, both may be the wildcard ‘*’: ‘unbind * *’ removes all bindings from all contexts. Due to initialization order issues built-in sequences cannot become unbound upon program startup, instead see line-editor-no-defaults† . Bindings are context-sensitive except for the shared ‘base’ foundation. Contexts are ‘default’ (used unless otherwise documented), and ‘compose’ (used in Compose mode† ).
With zero arguments, or with only a context name (may be wildcard ‘*’) the former lists key bindings (verbose† ly). With two or more arguments a specific binding is shown or (re)established: the first is the context to which it shall apply, the second a comma-separated list of “keys” that make up the binding. All further arguments are joined to form the expansion, and cause the binding to be created or updated.
Normally the expansion of a triggered binding is immediately committed as an input line, shall the user instead have an editing option the last byte of the expansion must be a commercial at ‘@’. Reverse solidus cannot be the last character of an expansion. An empty expansion will be rejected.
Bindings are specified as a comma-separated sequence of keys. Each key list entry consists of a sequence of one or more bytes. Byte sequence input is forcefully terminated after bind-inter-byte-timeout† milliseconds, whereas key sequences can be timed out via bind-inter-key-timeout† , which allows to share an identical key prefix in between many bindings. Key list entries that start with colon ‘:’ name terminal capabilities: many names are built-in and may be specified either by their terminfo(5), or, if existing, termcap(5) name, regardless of the actually used terminal control library. But any capability resolvable via the control library or termcap† may be used.
bind default
a,b echo one
bind default a,b,c echo two
bind default ab,c echo notbush!
bind base $’\E’,d mle-snarf-word-fwd # Esc(ape)
bind base $’\E’,$’\c?’
mle-snarf-word-bwd # Esc,Delete
bind default $’\cA’,:khome,w ’echo User
editable@’
bind default a,b,c,d rm -irf / @ # Also editable
bind default :kf1 File %
bind compose :kf1 ˜v
define kb-clear
{
# Careful to re-bind mle-commit in same line!
\unbind * *;\
\bind base $’\n’ mle-commit;\
\bind base $’\c?’ mle-del-bwd;\
\bind base $’\cE’ mle-go-end
}
Notes. The comma-separated key list is first parsed (over) as a shell-token with whitespace as the field separator, then parsed and expanded for real, separated with comma, therefore whitespace must be properly quoted (Shell-style argument quoting† )! Using Unicode escape sequences renders bindings defunctional if the locale does not support Unicode (Character sets† ). Unresolvable terminal capabilities render bindings defunctional, too. Adding, deleting or modifying key bindings invalidates the internal prebuilt lookup tree, it will be recreated as necessary: in ‘verbose† =3’ mode the resulting tree will be dumped. It is advisable to use an initial escape or other control character (like ‘\cA’) for user bindings in order to avoid ambiguities and reduce search time.
The following terminal capability names are built-in and can be used in terminfo(5) or (if available) the two-letter termcap(5) notation. See the respective manual for a list of capabilities. The program infocmp(1) can be used to show all the capabilities of TERM† , it’s −x option shows supported extensions.
kbs / kb
Backspace.
kdch1 / kD
Delete character.
kDC / *4
— shifted variant.
kel / kE
Clear to end of line.
kext / @9
Exit.
kich1 / kI
Insert character.
kIC / #3
— shifted variant.
khome / kh
Home.
kHOM / #2
— shifted variant.
kend / @7
End.
knp / kN
Next page.
kpp / kP
Previous page.
kcub1 / kl
Left cursor (with more modifiers: see below).
kLFT / #4
— shifted variant.
kcuf1 / kr
Right cursor (ditto).
kRIT / %i
— shifted variant.
kcud1 / kd
Down cursor (ditto).
kDN
— shifted variant (only terminfo).
kcuu1 / ku
Up cursor (ditto).
kUP
— shifted variant (only terminfo).
kf0 / k0
Function key 0. Add one for each function key up to kf9 and k9, respectively.
kf10 / k;
Function key 10.
kf11 / F1
Function key 11. Add one for each function key up to kf19 and F9, respectively.
Some terminals support key-modifier combination extensions like ‘Alt+Shift+xy’. For example, the delete key, kdch1: in its shifted variant, the name is mutated to kDC, then a number is appended for the states ‘Alt’ (kDC3), ‘Shift+Alt’ (kDC4), ‘Control’ (kDC5), ‘Shift+Control’ (kDC6), ‘Alt+Control’ (kDC7), finally ‘Shift+Alt+Control’ (kDC8). The same for the left cursor key, kcub1: KLFT, KLFT3, KLFT4, KLFT5, KLFT6, KLFT7, KLFT8.
[Only new quoting rules] Evaluate the given define† d Macro† (ˆERR† -NOENT if non-existing). Calling macros recursively excesses the stack size limit at some point, resulting in a program abortion; if applicable this can be avoided via xcall† . Both commands support the local† and our† scope† .
Does not fail for non-existing macros, otherwise identical to call† .
Synonym for chdir† .
[Option] Takes optionally Message list arguments† , and a pathname, and saves the message certificate(s) to the named file in both human-readable and PEM format, usable for, for example, smime-encrypt-USER@HOST† .
[Only new quoting rules] Manage Character sets† alias mappings. The former lists all mappings without, or a given one with one argument(s). With two arguments, hyphen-minus ‘-’ being the first, the second is expanded recursively. In all other cases the arguments are treated as pairs of source and target character sets, creating new or updating existing mappings. Mappings do not apply to INTERNAL VARIABLES† like charset-8bit† , and are generally ignored if character set conversion is not available. Mappings are expanded recursively when used (recursion limit: 8).
[Only new quoting rules](ch) Change the working directory to the given argument or HOME† . Synonym for cd† .
Takes a message list and hides all replies to these messages (for headers† ), except for ‘new’ messages and the “dot”. Also when a message with collapsed replies is displayed, these are automatically uncollapsed. The latter command undoes collapsing. Only applicable to threaded sort† mode.
[Option][Only new quoting rules] Manage Coloured display† . Without arguments the former shows all defined colour mappings, otherwise a (case-insensitive) colour type is expected, one of ‘256’ for 256-colour terminals, ‘8’, ‘ansi’ or ‘iso’ for the standard 8-colour ANSI / ISO 6429 colour palette, and ‘1’ or ‘mono’ for monochrome terminals: these only support (some) font attributes. Without further arguments the list of all defined mappings of the given type is shown.
Otherwise the second argument defines a slot name, the third a (comma-separated list of) colour and font attribute(s), and the optionally supported fourth argument can be used to specify a precondition: if conditioned mappings exist they are tested in (creation) order unless a (case-insensitive) match has been found, and the default mapping (if it exists) will only be chosen as a last resort. Preconditions depend on slots, the following of which exist:
Slot names prefixed with ‘mle-’ are used for the [Option]al built-in Mailx-Line-Editor MLE† (see Terminal control and line editor† ), and do not support preconditions.
mle-position
The position indicator that is visible when a line cannot be fully displayed on the screen.
mle-prompt
prompt† .
mle-prompt2
prompt2† .
mle-promptx
Used for certain interactive prompts.
mle-error
[v15 behavior may differ] Used for error messages written on standard error only.
Slot names prefixed with ‘sum-’ are used by headers† . Preconditions are ‘dot’ (current message) and ‘older’ for elder messages (only in conjunction with datefield-markout-older† ).
sum-dotmark
Used for “dotmark” creatable with the headline† formats ‘%>’ or ‘%<’.
sum-header
For all summary line content except “dotmark” and the threaded sort† tree.
sum-thread
For the threaded sort† tree creatable with the headline† format ‘%i’.
Slot names prefixed with ‘view-’ are used when messages are type† d.
view-from_
Used for so-called ‘From_’ lines, which are MBOX file format (see folder† ) specific header lines
view-header
For header lines. A comma-separated list of header fields to which the mapping shall apply may be given as a precondition; if the [option]al regular expression support is available then it is evaluated as one if it contains magic regular expression characters† .
view-msginfo
For the introductional message info line.
view-partinfo
For MIME part info lines.
The following (case-insensitive) colour definitions and font attributes are understood, multiple of which can be specified in a comma-separated list:
ft=
a font attribute: ‘bold’, ‘reverse’ or ‘underline’.
fg=
foreground colour attribute, in order (numbers 0 - 7) ‘black’, ‘red’, ‘green’, ‘brown’, ‘blue’, ‘magenta’, ‘cyan’ or ‘white’. To specify a 256-colour mode a decimal number colour specification in the range 0 to 255, inclusive, is supported, and interpreted as follows:
0 - 7
the standard ISO 6429 colours, as above.
8 - 15
high intensity variants of the standard colours.
16 - 231
216 colours in tuples of 6.
232 - 255
grayscale from black to white in 24 steps.
#!/bin/sh -
fg() { printf "\033[38;5;${1}m($1)"; }
bg() { printf "\033[48;5;${1}m($1)"; }
i=0
while [ $i -lt 256 ]; do fg $i; i=$((i + 1)); done
printf "\033[0m\n"
i=0
while [ $i -lt 256 ]; do bg $i; i=$((i + 1)); done
printf "\033[0m\n"
bg=
background colour attribute (same values as fg=).
The command uncolour† will remove for the given colour type (or all with ‘*’) the given mapping; if the optional precondition argument is given only the exact tuple of mapping and precondition is removed. The special name ‘*’ will remove all mappings (no precondition allowed), thus ‘uncolour * *’ will remove all established mappings.
[Only new quoting rules] Define or list, and remove, respectively, command aliases. Aliases can be used whenever a command name is expected, and all arguments are joined onto the alias’s expansion. The former lists all aliases without, or a given one with one argument(s). With two or more arguments an alias is (re)created: the first is the name, the remains can be just about anything. An alias may expand to another alias, but same-name expansion is prevented (after first level), and there is a recursion depth limit. Expansion can be prevented with a reverse solidus \† (Command modifiers† ). Unlike COMMANDS† aliases cannot be abbreviated.
commandalias xx
#-> s-nail: ‘commandalias’: no such alias: xx
commandalias xx echo hello,
commandalias xx
#-> commandalias xx ’echo hello,’
xx world
#-> hello, world
commandalias q q; commandalias x q; help x
#-> x -> q -> q (quit): Exit session [.]
(C) Similar to copy† , but copy messages to a file named after the local part of the sender of the first message instead of taking a pathname argument; outfolder† is honoured.
(c) Copy messages to the named file and do not mark them as being saved; otherwise identical to save† .
[Option][Only new quoting rules] 8-bit US-ASCII byte string operation multiplexer (no notion of Character sets† ). For file operations refer to fop† , for numeric and other operations to vexpr† . >† (Command modifiers† ) is supported. The error result is ‘-1’ for usage errors and numeric results, the empty string otherwise; missing data errors, as for unsuccessful searches, set !† to ˆERR† -NODATA. When the modifier suffix question mark ‘?’ is supported, a case-insensitive mode is supported; the keyword ‘case’ is optional so that ‘find?’ and ‘find?case’ are identical.
length
Query the argument length.
hash, hash32
Calculate a (32-bit) hash of the argument. ‘?’ modifier is supported. These use Chris Torek’s hash algorithm, the resulting hash value is bit mixed as shown by Bret Mulvey.
find
Search for the second in the first argument, show 0-based offset upon success. ‘?’ modifier is supported.
substring
Create a substring of the first argument. The optional second argument could specify a 0-based starting offset, a negative one counts from the end. The optional third argument defines the desired result length, a negative one leaves off the given number of bytes at the end of the original string; by default the entire string is used. This operation tries to work around faulty arguments (set† verbose† for error logs), but reports them via the error number !† as ˆERR† -OVERFLOW.
trim
Trim away whitespace from both ends of the argument.
trim-front
Trim away whitespace from the begin of the argument.
trim-end
Trim away whitespace from the end of the argument.
Show the current working directory name as reported by getcwd(3). Supports >† (Command modifiers† ). The return status is tracked via ?† .
[Option] For unencrypted messages identical to Copy† ; Encrypted messages are first decrypted, if possible, and then copied.
The latter deletes the given macro, ‘*’ discards all existing ones. Deletion, including self-deletion, is always possible. The former lists all or only the given macro(s); with two arguments, left curly bracket ‘{’ being second, it defines or replaces a macro, formed of all lines until a right curly bracket ‘}’ is seen. Macro names are free-form but must form a single token (Shell-style argument quoting† ). Remarks: [v15 behavior may differ] macros cannot be defined in Compose mode† , neither can local (inner) macros, and the closing ‘}’ must be placed on a line of its own.
Macros can be evaluated by call† , call_if† or xcall† , optionally with a scope† . Inside a running macro positional parameters can be accessed via *† , @† , #† and 1† as well as any positive unsigned decimal number less than or equal to #† ; they can be shift† ed away, and become exchanged via vpospar† . return† can be used to explicitly give back control to the caller.
? unset prompt
define name {
command1
...
commandN
}
define exmac {
echo "Parameter 1 of $# is $1, all: $* / $@"
return 1000 0
}
call exmac Hello macro exmac!
#..
echo "$?/$!/$ˆERRNAME"
(d, u) Mark the Message list arguments† (not) ‘deleted’, one of the Message states† . With the former, if autoprint† is set, the new “dot” or the last message restored, respectively, is automatically type† d; also see dp† , dt† . The latter clears the ‘saved’ message state.
[Only new quoting rules][No field splitting](first two arguments) An interface object for message inspection and modification. An object can be created for a given message number; in Compose mode† hyphen-minus ‘-’ addresses the message draft. Objects can be removed to release resources; leaving their folder† does so automatically. The optional third argument selects an output mode: circumflex ‘ˆ’ stores results in the ˆ† multiplexer sub-variables ˆ#† , ˆ0† , ˆ1† etc, ‘-’ selects standard output (an interactive user mode). Because errors are handled by the I/O protocol, !† and exit status ?† are not managed; hard errors like I/O failures cannot be handled. The compose mode object (also see ˜ˆ† ) may be used directly, without create (or after remove): it places results in the ˆ† multiplexer. In all other use cases the first argument is the object identifier.
The protocol consists of a command line followed by (a) response line(s), or according ˆ† multiplexer assignments. The first field of the first response line represents a status code which denotes success, whether result data is to be expected, and if, the format of the result data. Response data is quoted as necessary for consumption by readsh† , or vpospar† and eval† , to name a few. Remarks: In I/O mode responses must be fully consumed before further commands can be issued in order to avoid deadlocks! In multiplexer assignment mode ˆ0† stores the status code, the remains are those sequential fields that otherwise make up lines, “missing” optional fields are stored as empty results, also meaning that ˆ1† may hold what would make up optional status code line remains; values are not quoted, ˆ@† is to be expanded within double quotes to achieve this result. The status codes are:
‘210’
Status ok; the remains of the line are the result.
‘211’
Status ok; more status may optionally be appended. None to multiple address lines follow, terminated by an empty line. Address lines consist of two shell tokens, the plain address, for example ‘bob@exam.ple’, followed by the unstripped address (see fullnames† ): ‘’(Lovely) Bob <bob@exam.ple>’’. Non-addresses are indicated via the first token: hyphen-minus ‘-’ for files, vertical bar ‘|’ for pipes, and number sign ‘#’ for names which will undergo alias† processing; the second token will be the value.
‘212’
Status ok; more status may optionally be appended. What follows are lines of one furtherly unspecified string token each, terminated by an empty line.
‘500’
Syntax error; invalid command.
‘501’
Syntax error or otherwise invalid parameters or arguments.
‘505’
Error: an argument fails verification. For example an invalid address has been specified (also see expandaddr† ), or a modifying subcommand has been used on a read-only message, or an attempt was made to modify virtual, auto-generated, read-only data.
‘506’
Error: an otherwise valid argument is contextually invalid. For example, a second address is added to a header field which may consist of a single address only.
All ‘50x’ status codes may show additional data on the rest of the line. The message remains unmodified upon error. Most commands can fail with ‘500’ if required arguments are missing, or on otherwise false command usage. The following (case-insensitive) commands and sub-commands are supported, abbreviating is possible:
attachment
Manage message attachments. The second argument specifies the subcommand, one of:
attribute
Uses the same search mechanism as described for remove, and prints all attributes of the first found attachment via ‘212’ upon success, or ‘501’ if no such attachment can be found. The none to multiple success result lines consist of a keyword and a value token, terminated by an empty line.
attribute-at
Uses the same search mechanism as described for remove-at and is otherwise identical to attribute.
attribute-set
Uses the same search mechanism as described for remove, and sets the attribute given as the fourth to the value given as the fifth token argument. An empty value causes the given attribute to be removed, or reset to a default if existence of the attribute is crucial. Upon success ‘210’ with the index of the found attachment following is returned, ‘505’ for message attachments or if the given keyword is invalid, and ‘501’ if no such attachment can be found. The following keywords may be used (case-insensitively):
‘creation-name’
(Read-only) Value used when creating the attachment.
‘open-path’
(Read-only) Path that will be used when reading the file to be attached.
‘filename’
Sets the filename of the MIME part, that is, the name that is used for display and when (suggesting a name for) saving (purposes).
‘content-description’
Associate some descriptive information to the attachment’s content, used in favour of the plain filename by some MUAs.
‘content-id’
May be used for uniquely identifying MIME entities in several contexts; this expects a special reference address format as defined in RFC 2045 and generates a ‘505’ upon address content verification failure.
‘content-type’
Defines the media type/subtype of the part, which is managed automatically, but can be overwritten.
‘content-disposition’
Automatically set to the string ‘attachment’.
attribute-set-at
Uses the same search mechanism as described for remove-at and is otherwise identical to attribute-set.
insert
Add the attachment given as the third argument, specified exactly as documented for the command line option −a† , and supporting the message number extension as documented for ˜@† (COMMAND ESCAPES† ). Reports ‘210’ upon success, with the index of the new attachment following, ‘505’ if the given file cannot be opened, ‘506’ if an on-the-fly performed character set conversion fails, otherwise ‘501’ is reported; this is also reported if character set conversion is requested but not available.
list
List all attachments via ‘212’, or report ‘501’ if no attachments exist. This command is the default command of attachment without second argument.
remove
Remove the attachment given as the third argument, and report ‘210’ upon success or ‘501’ if no such attachment can be found. If the given argument contains path components, an exact match of the path used to create the attachment is taken immediately, but the plain path basename will also be found by traversing all attachments if only one match results; if multiple basenames match, a ‘506’ error occurs. Message attachments are treated as absolute pathnames. If no path component exists then all attachments will be searched for ‘filename=’ parameter matches as well as for matches of the basename of the path which has been used for attachment creation; multiple matches result in a ‘506’.
remove-at
Interprets the third argument as a number and removes the attachment at that list position (counting from one!), reporting ‘210’ upon success or ‘505’ if the argument is not a number or ‘501’ if no such attachment exists.
header
Manage message header fields. Header name case is not normalized, so that case-insensitive comparison should be used when matching names. The second argument specifies the subcommand to apply, one of:
insert
Create a new or another instance of the header given in the third token, with the content value as given in the fourth token. (Tabulators, line feeds and carriage-returns, aka ‘\t’, ‘\n’, ‘\r’ are normalized to space; other control characters cause error.) Returns ‘501’ if the header name is invalid, or if content extraction fails to succeed, ‘505’ if any extracted address does not pass syntax and/or security checks, or an attempt was made to modify virtual, read-only data, and ‘506’ to indicate prevention of excessing a single-instance header — note that ‘Subject:’ can be appended to (a space separator will be added automatically first). ‘To:’, ‘Cc:’ and ‘Bcc:’ support the ‘?single’ modifier to enforce treatment as a single recipient, for example ‘header insert To?single: ’exa, <m@ple>’’; the word ‘single’ is optional.
‘210’ is returned upon success, followed by the name of the header and the list position of the newly inserted instance. The list position is always 1 for single-instance header fields. All free-form header fields are managed in a single list; also see customhdr† .
headerpick
Takes the name of a headerpick† context and filters accordingly, giving ‘210’ on success, and ‘505’ for read-only messages, and ‘501’ for an invalid context.
list
Without third argument a list of all header fields is generated via ‘210’, otherwise only the given one is listed, a non-existing one gives ‘501’. This is the default subcommand of header.
remove
Remove all instances of the header given as the third token, reporting ‘210’ upon success, ‘501’ if no such header can be found, and ‘505’ when trying to remove a virtual, auto-generated, or read-only header.
remove-at
Remove from the header given as the third argument the instance at the list position (counting from one!) given in the fourth token, reporting ‘210’ upon success or ‘505’ if the position is not a number, or is inaccessible, and ‘501’ if no such header instance exists.
show
Show content of the header field given third. The content will be converted to ttycharset† ([v15 behavior may differ] and then be made printable according to LC_ALL† ). Dependent on the header type this may respond with ‘211’ or ‘212’; any failure results in ‘501’.
Compose mode† offers read-only access to optional, virtual, read-only header fields:
‘Mailx-Command:’
The name of the command that generates the message, one of ‘forward’, ‘Lreply’, ‘mail’, ‘Reply’, ‘reply’, ‘resend’. This pseudo header always exists.
‘Mailx-Edited-Sender:’
‘Mailx-Edited-Origin:’
Different to the RFC 5322 originator fields of the otherwise identical ‘-Orig-’ series below these might take into account reply-to-honour† and reply-to-swap-in† . This sender field will however be identical to ‘Mailx-Orig-Sender:’ unless the edited (replaced) originator field is unambiguous.
‘Mailx-Orig-Sender:’
‘Mailx-Orig-From:’
‘Mailx-Orig-To:’
‘Mailx-Orig-Cc:’
‘Mailx-Orig-Bcc:’
The values of said headers of the original message which has been addressed by any of reply† , forward† , resend† . The sender field is filled in according to what is described for from† .
‘Mailx-Raw-To:’
‘Mailx-Raw-Cc:’
‘Mailx-Raw-Bcc:’
Represent the frozen initial state of these headers before any transformation (alias† , alternates† , recipients-in-cc† etc.) took place.
epoch
The message date as seconds since the UNIX epoch (1970-01-01T00:00:00) via ‘210’. Error for an invalid date is ‘501’, for using this command in Compose mode† ‘505’. vexpr† can be used to convert times, for example:
dig cre 1
ˆ
dig 1 epo
if $ˆ0 -eq 210
vex date-utc "$ˆ1"
en
dig rem 1
#-> dutc_year=2023 [..]
help, ?
Show a command abstract via ‘212’.
version
Print the protocol version via ‘210’.
A few examples:
>msgno =
digmsg create
$msgno
digm $msgno header list; readall x; echo $x
#-> 210 ’Subject From To Message-ID
References’
digm $msgno header show Subject;readall x;ec $x
#-> 212 Subject ’Hello, world’
digm remove $msgno
digm cr $msgno
-
digm $msgno hea l
#-> 210 ’Subject From To Message-ID
References’
digm $msgno hea sho Subject
#-> 212 Subject
#-> ’Hello, world’
#->
digm rem $msgno
digm c $msgno
ˆ
digm $msgno h l; ec
$ˆ#,$ˆ0,$ˆ1,$ˆ2,$ˆ*
#-> 1,210,Subject...,,Subject...
digm $msgno h s subject; ec
$ˆ#,$ˆ0,$ˆ1,$ˆ2,$ˆ*
#-> 2,212,Subject,Hello, world,Subject Hello, world,
digm r $msgno
(di) Identical to ignore† . Superseded by the multiplexer headerpick† .
Delete given messages and thereafter type† a possible new “dot” regardless of autoprint† .
Move the “dot” up ‘+’ or down ‘-’ by one message if possible, then update headers† .
Mark each given message as (not) being a draft (Message states† ).
[Only new quoting rules](ec) Print arguments after expanding their Shell-style argument quoting† , then a newline. >† (Command modifiers† ) is supported; with it the result length is returned on success, ‘-1’ on error. Remarks: in BSD Mail this command also performed Filename transformations† , which is standard incompatible and hard to handle because quoting transformation patterns is not possible; the fop† subcommand expand expands pathnames.
[Only new quoting rules] Like echo† , but write to standard error and prefix lines by log-prefix† . Does not support >† . Also see echoerrn† . [Option] In interactive sessions messages are duplicated into the queue of errors† .
[Only new quoting rules] Like echo† , but do not append a newline.
[Only new quoting rules] like echoerr† , but do not append a newline.
(e) Successively open EDITOR† on each entry of the given message list. Modified contents are discarded unless writebackedited† is set, the mailbox can be written to, and the editor returned success. visual† may be used instead for a more display oriented editor. [v15 behavior may differ] Editing takes place on raw, non-decoded MIME content.
Part of the if† (see there), elif† , else† , endif† conditional. An else-if block is evaluated if former blocks were not and its’ condition is true.
(el) Part of the if† (see there), elif† , else† , endif† conditional. An else block is evaluated only if none of the condition blocks matched.
(en) Marks the end of an if† (see there), elif† , else† , endif† conditional execution block.
[Only new quoting rules][No field splitting] The process ENVIRONMENT† and INTERNAL VARIABLES† usually live in distinct namespaces (for example varshow† does not find the former, echo† will), but they can be linked together as long as SHELL† variable name rules† are honoured. Changes may have our† scope† .
The subcommands set and unset create und remove such links inclusive value updates, meaning that ‘environ set myvar’ also set† ‘myvar’, and ‘environ unset myvar’ also unset† s.
To the contrary link and unlink only manage state: when linking and an according internal variable exists the ENVIRONMENT† is synchronized, otherwise it is tried to import (and set† ) an environment variable, else an error occurs; unlinking breaks previously established links. All given variables are worked, errors are remembered and cause ˆERR† -INVAL.
The subcommand lookup looks up the given variable in the process environment only; it supports >† and sets !† to ˆERR† -NOENT upon lookup failure. (It may be handy because local† ly set† free-form variables shadow anything else.)
# With
*errexit*, do not exit if PERL5LIB does not exist
ignerr environ link PERL5LIB
if $? -ne 0
echoerr PERL5LIB not in environment, using ˜/.perl5
environ set PERL5LIB=˜/.perl5
endif
set PERL5LIB=$PERL5LIB:/home/shared/perl5
>storvar environ lookup PERL5LIB; echo
"$storvar"
[Option] Access the interactive session error message queue. (As error messages sometimes fly by and scroll off the screen too fast, here they are duplicated into.) show or no argument displays and clears the queue, clear only clears it. Of interest may be errors-limit† , ˆERRQUEUE-COUNT† , ˆERRQUEUE-EXISTS† .
(ex) also xit (x) Exit without performing management tasks, like updating of the active mailbox, automatic message moving† , saving of the history-file† , among others. on-account-cleanup† is evaluated when set. The optional exit status number argument is passed through to exit(3). [v15 behavior may differ] For now it can happen that the given status will be overwritten, later this will only occur if a later error needs to be reported onto an otherwise success indicating status.
(Fi) Identical to folder† .
(fi) Identical to folder† .
[Only new quoting rules] Define, list, and remove, file handler hooks. These provide (shell) commands that enable loading and saving MBOX files from and to files with registered file extensions, as shown and described for folder† . The extensions are used case-insensitively (US-ASCII), yet the auto-completion feature of for example folder† will only work case-sensitively. An intermediate temporary file will be used to store the expanded data. The latter command removes hooks for the given extensions, asterisk ‘*’ will remove all existing handlers.
When used without arguments the former shows a list of all types, with one argument the expansion of the given one. Otherwise tuples of three arguments are expected: the first specifies the file extension, the second and third define load- and save commands; both must read from standard input and write to standard output. Changing hooks will not affect already opened mailboxes ([v15 behavior may differ] except below). [v15 behavior may differ] For now too much work is done, and files are oftened read in twice where once would be sufficient: this can cause problems if a filetype is changed while such a file is opened; this was already so with the built-in support of .gz etc. in Heirloom, and will vanish in v15. [v15 behavior may differ] For now all handler strings are passed to the SHELL† for evaluation purposes; in the future a ‘!’ prefix to load and save commands may mean to bypass this shell instance: placing a leading space will avoid any possible misinterpretations.
filetype bz2
’bzip2 -dc’ ’bzip2 -zc’ \
gz ’gzip -dc’ ’gzip -c’ \
xz ’xz -dc’ ’xz -zc’ \
zst ’zstd -dc’ ’zstd -19 -zc’ \
gz.pgp ’gpg -d | gz -dc’ ’gz -zc | gpg
-e’
set record=+sent.gz.pgp
Take message lists and mark entries as being or not being flagged for urgent/special attention, respectively. See Message states† .
(Fold) Like folder† , but open the mailbox read-only.
(fold) Shows information about the current mailbox without arguments. Otherwise an open mailbox is closed, Filename transformations† on the argument are performed, with URL ‘mailbox-type://’ “protocols” (URL syntax and credential lookup† ) being understood, as in ‘mbox:///tmp/somefolder’, or, in general:
protocol://[user[:password]@]host[:port][/path]
When no protocol was specified opening non-existing folders† asserts newfolders† . Once opened the variables mailbox-basename† , mailbox-display† , mailbox-resolved† as well as mailbox-read-only† are updated, a set on-mailbox-event† is evaluated, and optionally a summary of headers† is displayed if header† is set.
For the “protocols” mbox (equal: file), smbox or xmbox (MBOX variants), as well as eml ((a single) electronic mail message; [v15 behavior may differ] only read-only support) the list of all registered filetype† s is traversed to check whether hooks shall be used to load (and save) data from (and to) the mailbox, except for the “-” standard input case (as documented for −f† ). Remarks: changing hooks will not affect already opened mailboxes.
[Obsolete] For historical reasons filetype† s provide limited (case-sensitive) auto-completion capabilities. For example ‘mbox.gz’ will be found for ‘file mbox’, provided that corresponding handlers are installed. It will neither find ‘mbox.GZ’ nor ‘mbox.Gz’ however, but an explicit ‘? file mbox.GZ’ will find and use the handler for ‘gz’. [v15 behavior may differ] Auto-completion will vanish in v15!
When reading MBOX files POSIX.1-2024 parse rules are used by default; The often invalid message boundaries of elder MBOX files cause warnings: the method described for mbox-rfc4155† may be used to create a new and valid MBOX.
During file operations MBOX and EML files are protected by file-region locks (fcntl(2)). [Option] Unless dotlock-disable† d an MBOX inbox† (MAIL† ) and any primary system mailbox† are additionally protected by so-called dotlock files, the traditional way of mail spool file locking: for any file ‘x’ a lock file ‘x.lock’ will be created during the synchronization, in the same directory and with the same user and group identities as the file of interest — as necessary created by an external privileged dotlock helper. Also see FAQ† : Howto handle stale dotlock files.
[Option] If no explicit protocol was given, and the folder refers to a directory with the subdirectories ‘tmp’, ‘new’ and ‘cur’, then it is treated as a “Maildir” mailbox. The maildir format stores each message in its own file, and has been designed so that file locking is not necessary when reading or writing files. [v15 behavior may differ] Operations on maildir mailboxes temporarily switch the working directory; it is advisable to avoid addressing other mailboxes relatively when using them.
[Option] Network mail protocol resources may be addressed, securely via Encrypted network communication† if so supported: pop3 (POP3) and pop3s (POP3 via TLS), see pop3-auth† , as well as imap and imaps (IMAP via TLS), see IMAP CLIENT† . For IMAP the [/path] URL part defaults to ‘INBOX’. All network traffic may be proxied over a SOCKS5 server via socks-proxy† . Network communication socket timeouts are configurable via socket-connect-timeout† .
[Only new quoting rules] Lists the names of all folders below the given argument or folder† . For file-based protocols LISTER† will be used for display purposes.
(Compose mode)(F,fo) Similar to Reply† aka reply† , but save the message in a file named after the local part of the first recipient’s address (like −F† ), overwriting record† , but honouring outfolder† . Also see Copy† and Save† .
[Option][Only new quoting rules] A multiplexer command for file operations. For C-style byte string operations refer to csop† , for numeric and other operations to vexpr† . The first argument defines the number, type, and meaning of the remaining ones. Unless otherwise noted subcommands expect file descriptors opened via flock, lflock, lock, llock, open and echo success as documented there; standard input and output are accepted, regardless of their validity for the operation. Supports >† (see Command modifiers† ). Except when otherwise noted errors will be reported via !† , and the error result is the empty string. Pathname arguments undergo Filename transformations† .
close
Close the given file descriptor. Standard descriptors cannot be closed.
expand
Only perform name transformations.
ftruncate
Truncate the given file descriptor to its current file position (also see rewind).
flock, lflock, lock, llock
Open the given pathname, then apply a shared read (‘R, r’), or an exclusive read and (appending) write (‘W, w, A, a’) lock according to mode argument (second); uppercase variants log retries to gain the lock, writer ones create the file first as necessary, they will truncate the file to zero size first if a ‘0’ is part of the mode; further operation-success-echoes on the open descriptor can be suppressed by adding a circumflex ‘ˆ’ (for example ‘fop lock ./a-file.txt A0ˆ’). On success the descriptor number is printed, and must be closed again explicitly; the descriptor is not inherited by child processes. llock differs by not following symbolic links.
[Option](features† includes ‘,+flock,’) Different to the fcntl(2) based locks flock uses the system call flock(2), and creates locks which are inherited by child processes. (lflock does not follow symbolic links.) A third argument changes behavior: it is passed to a newly spawned SHELL† (via −c) that inherits the descriptor as standard input for shared locks, as standard input and output otherwise; If the shell could be started its exit status code is returned, and the normal result is suppressed but for >† ; the descriptor will be closed automatically.
glob
glob(7) expands all arguments; upon success it makes none to many results accessible in result set† accessors ˆ#† , ˆ0† , ˆ1† etc; ˆ0† holds the argument(s as a space-separated string). Without fnmatch(3) support in the operating system environment the error is ˆERR† -NOSYS.
mkdir
Create the given directory. An optional second argument defines the mode (default 0777), an optional third is a boolean† that denotes whether parent directories shall be created as necessary.
mktemp
Create a temporary file and output its name. The optional first (and non-empty) argument will be used as a pathname suffix, the (optional) second a target directory to be used instead of TMPDIR† .
open
Open the given file with the mode given second, either in read-only (‘r’), or read- and (appending) write (‘W, w, A, a’) mode; writer ones create the file first as necessary, uppercase versions fail if the file already exists, otherwise, the file will be truncated to zero size first if a ‘0’ is part of the mode; further operation-success-echoes on the open descriptor can be suppressed by adding a circumflex ‘ˆ’ (for example ‘fop open ./a-file.txt A0ˆ’). On success the descriptor number is printed, and must be closed again explicitly; the descriptor is inherited by child processes.
pass
Takes two file descriptor arguments to be passed as standard I/O to the SHELL† command given third; beside the usual numbered ones the hyphen-minus ‘-’ for passing through the according standard I/O, or commercial at ‘@’ for /dev/null† ; passing standard descriptors via number is not supported. If the shell could be started its exit status code is returned, the normal result is suppressed but for >† .
rename
rename(2). Remarks: the first argument is the destination, the second the source.
rewind
rewind(3) the file descriptor with the given number.
rm
unlink(2).
rmdir
rmdir(2).
stat, lstat
stat(2) the given file and output values such that ‘>x fop stat FILE; eval set $x’ creates accessible variables. lstat differs by not following symbolic links when opening a file. The time fields are named ‘st_Xtime’ for the second, and ‘st_Xtimensec’ for the nanosecond (maybe 0), where ‘X’ is one of a(ccess), c(hange) and m(odification). ‘st_type’ uses solidus ‘/’ to denote directories, commercial at ‘@’ for links, number sign ‘#’ for block devices, percent sign ‘%’ for for character devices, vertical bar ‘|’ for FIFOs, equal sign ‘=’ for sockets, and the period ‘.’ for the rest.
touch, ltouch
Update file times, creating the file first as necessary. ltouch differs by not following symbolic links when creating the file.
(Compose mode) Similar to forward† , but save the message in a file named after the local part of the first recipient’s address, overwriting record† , but honouring outfolder† .
(Compose mode) Takes a message list and the address of a recipient, subject to fullnames† , to whom the messages shall be sent. The text of the original message is included in the new one, enclosed by the values of forward-inject-head† and forward-inject-tail† . content-description-forwarded-message† is inspected. The list of included header fields can be filtered with the ‘forward’ slot of headerpick† , headerorder† is honoured. Only the first part of a MIME multipart message is included but for forward-as-attachment† .
This may generate the errors ˆERR† -DESTADDRREQ if no recipient has been specified, or was rejected by expandaddr† policy, ˆERR† -IO if an I/O error occurs, ˆERR† -NOTSUP if a necessary character set conversion fails, and ˆERR† -INVAL for other errors. It can also fail with errors of Specifying messages† . Any error stops processing of further messages.
(f) Takes a message list, and displays a summary as via headers† , making the first (the last with showlast† ) message of the result the new “dot”. An alias of this command is search† . Also see Specifying messages† .
[Only new quoting rules] The former shows the order list without arguments, then it supports >† . Otherwise the arguments are appended to the header field order list that is honoured when displaying (type† ) or quoting (forward† , reply† , quote† ) messages; unordered header fields are shown last in natural order. The latter removes the given header fields from the list, asterisk ‘*’ removes all. Matching is case-insensitive.
[Only new quoting rules] Multiplexer that manages header field selection. The latter always takes three or more arguments and removes from the given context and the given type the given headers, all headers with ‘*’. Without arguments the former shows established settings of all contexts. Otherwise the first argument is the context, one of (case-insensitive) ‘type’ for display purposes (for example type† ), ‘save’ for selecting which header fields shall be stored persistently (save† , copy† , move† , decrypt† ; note: ignoring MIME related etc. header fields destroys message usability), ‘forward’ for forward† ed (except with forward-as-attachment† ), messages, and ‘top’ for defining a user-defined list of fields for top† .
With only a context the current settings are shown. A restriction type may be given second, (a case-insensitive prefix of) ‘retain’ for positive or ‘ignore’ for negative filtering, inspected only if no positive one exists. Again, without further arguments the current settings are shown. Further arguments specify header fields, [option]ally specified as regular expressions, to be added to the given type. The special wildcard field (asterisk, ‘*’) will establish a (fast) shorthand setting which covers all fields.
headerpick supports creation and usage of user specified contexts, applicable to certain other commands (for example digmsg† ), by giving (a case-insensitive prefix of) the “context names” create, remove, assign, join; the real, case-insensitive (US-ASCII) name is next, it must not shadow a built-in name, and has to adhere to variable name rules† . Trying to create a context a second time is an error. The name of another, constant template context is given third to assign and join: whereas the former clears the target context first, the latter does not; in case of errors both clear the target context.
(h) Show the current group of header fields, the size of which depends on screen† in interactive mode, and the format of which can be defined with headline† . Without a message list argument the group surrounding the “dot” is shown, otherwise the first (the last with showlast† ) message becomes the new “dot”.
(hel) A synonym for ?† .
[Option] Without arguments or when given show all history entries are shown (possibly more verbose† ely). load replaces the history with the content of history-file† , and save dumps the history to said file, replacing former content; clear deletes all entries. The argument can also be a signed decimal NUMBER, the respective history entry is then evaluated; a negative number describes an offset to the current command so that ‘-1’ selects the last command, the history top. Lastly delete the given entries (:NUMBER:). Also see Terminal control and line editor† .
(ho) Also preserve (pre); Allowed only in a primary system mailbox† . Marks the given message list to be preserved in the current folder† , as if hold† were set; overrides a former deletion of the given messages; only the delete† , dp† , dt† as well as mbox† and touch† commands will remove the preserve mark.
[Only new quoting rules][No field splitting](i) Part of the if, elif† , else† , endif† conditional execution: if the given expression(s) evaluate to true the encapsulated block is executed. All arguments (values, operators, metacharacters for groups, AND-OR lists etc.) must be separate tokens (Shell-style argument quoting† ). Expressions are parsed much like the ‘[[ .. ]]’ construct of some sh(1)ells; quoting literals that equal syntax elements, especially ‘[’ and unary operators, avoids syntax ambiguities. Syntax errors cause blocks to be skipped (as no-ops) until endif† .
Remarks: In a whiteout (skipped block) the modifier eval† does not work, even for the conditional command that toggles that state. As documented in COMMANDS† if will act on a fully expanded command line: all tokens are evaluated, even if their position in an AND-OR list will not be reached.
i[f] expression
[commands ...]
eli[f] expression
[commands ...]
el[se]
[commands ...]
en[dif]
set i=!
if r && $i == !; echo yes; else; echo no; end
set i=
i -z $i; ec y; en
i $i = $i; ec y; en
set i=-n
if -n == && ’-n’ == -n; echo yes; end
yes
i -n == && \-n == -n; ec yes; en
yes
i -n == && $i == -n; ec yes; en
yes
i -n == && -n == -n; ec yes; en
..this is an error
The only portable operators are r (receive mode) and s (send mode), used on a line by themselves without variable expressions, anything else is an extension. This includes case-insensitivity, and the (partially) spelled-out receive and send. Further no-argument operators are t (any word beginning with ‘t’ not equal to ‘true’) that matches interactive terminal sessions (running attached to a terminal, and none of the “quickrun” command line options −e† , −H† and −L† were used), as well as any boolean† . Non-argument operators are detected as a last ressort.
Unary test operators are -N and -Z which test whether the given variable exists or not, so that ‘-N editalong’ is true when editalong† is set, whereas ‘-Z editalong’ is if it is not. -n and -z test whether the length of the given string is nonzero or zero.
Integer binary operators interpret arguments as integral signed 64-bit numbers, and compare them arithmetically. Invalid numbers are errors, unset variables and the empty string equal 0. Operators may be suffixed with the question mark ? modifier to enforce ‘saturated’ operation mode, here numbers linger at the minimum or maximum value instead of causing an error; the keyword is optional, ‘-lt?’, ‘-lt?satu’ and ‘-lt?saturated’ are identical. The operators are -lt (less than), -le (less than or equal to), -eq (equal), -ne (not equal), -ge (greater than or equal to), and -gt (greater than), for example ‘if 3 -gt 2;ec yes;en’.
8-bit US-ASCII byte and regular expression binary operators interpret arguments textually. Unset variables expand to the empty string. Operators can be suffixed with the question mark ? modifier to choose a ‘case-insensitive’ operation mode, the keyword is optional, ‘==?’, ‘==?case’ and ‘==?case-insensitive’ are identical. Available 8-bit US-ASCII byte binary operators are < (less than), <= (less than or equal to), == (equal; for SHELL† compatibility there is also =), != (not equal), >= (greater than or equal to), >† (greater than), as well as =% (is substring of) and !% (is not substring of), for example ‘if Water =% at;ec yes;end’.
[Option] Regular expression binary operators work in the active locale (see Character sets† ). =˜ and !˜ interpret the right hand side argument as an extended regular expression. Match groups (in parenthesis, see re_format(7) or regex(7), dependent on host system) are stored in result set† accessors ˆ#† , ˆ0† , ˆ1† etc, for example ‘if knoedel =˜? .*(OEDE).*; ec yes, $ˆ1 is in $ˆ0; en’.
Unary file operators test an aspect of the given pathname argument. Filename transformations† are not performed (use fop† expand). Unless noted the same ‘saturated’ question mark ? modifier as for integer binary operators may be given to ignore the argument and (re)use the file status cache that persists until expression evaluation ends. A non-existing cache is treated like a non-existing file. Without modifier the cache is updated. The operators are -b (file exists and is block special), -c (exists, character special), -d (exists, directory), -e (exists), -f (exists, regular file), -g (exists, set-group-ID), -k (exists, sticky bit set), -L (exists, symbolic link), -O (exists, owned by effective user ID), -p (exists, named pipe), -r (exists, user can read, no modifier), -S (exists, socket), -s (exists, size greater than zero), -t (file descriptor number argument is open on a terminal, no modifier), -u (exists, set-user-ID), -w (exists, user can write, no modifier), -x (exists, user can execute / search, no modifier). All operators resolve symbolic links except -L. For example ‘if -f /etc/motd && -s? ’’; ec yes; en’.
Binary file operators interpret the left and right hand side arguments as pathnames. Filename transformations† are not performed. The operators are -ef (both files refer to same device and inode), -nt (left hand modification is newer, or it exists and right hand does not), -ot (left hand modification is older, or it does not exist and right hand side does). All operators resolve symbolic links. For example ‘if /etc/passwd -nt /etc/shadow; ec yes; en’.
Expressions can be joined via AND-OR lists (where AND is && and OR is ||), which have equal precedence and left associativity. Further groups can be created via interlockable pairs of brackets [ ... ], themselve joinable with AND-OR lists. The unary operator ! reverses the result of individual expressions or entire groups.
i -N debug; ec
*debug* set; el; ec not; en
if $ttycharset == UTF-8 || $ttycharset ==?cas UTF8
echo ttycharset is UTF-8, the former case-sensitive!
endif
set t1=one t2=one
i ${t1} == ${t2}
ec The non-empty variables are byte-wise equal
en
if $features =% ,+regex, && $TERM =˜?case
ˆxterm.*
ec ..in an X terminal
en
if [ [ true ] && [ [ $t1 != ’’ ] || \
[ $t2 != ’’ ] ] ]
echo Noisy, noisy
endif
i true && [ -n $t1 || -n $t2 ]
ec Left associativity as known from the shell
en
(ig) Superseded by the multiplexer headerpick† .
Shows all built-in COMMANDS† in lookup order (diverse alphabetical deviations due to POSIX.1-2024 standardized abbreviations). [Option] In verbose† mode argument types and documentation abstracts, flags and supported Command modifiers† are shown:
‘global’
supports global† .
‘local’
supports local† .
‘our’
supports our† .
‘>’
supports >† .
‘*!*’
the error number is tracked in !† .
‘command yay:’
‘active-mailbox’
usable with a current folder† .
‘batch/interactive’
usable in interactive or batch mode (−#† ).
‘send-mode’
usable in send mode.
‘macro/account’
(only) usable in a define† d macro or an account† .
‘command nay:’
‘compose-mode’
enters Compose mode† , non-recursively.
‘startup-conf’
not available during program startup before −X† commands run, for example in Resource files† .
‘startup’
not available during program startup (usable via −Y† at earliest).
‘read-only-mailbox’
cannot be used in a read-only Folder† .
‘history:gabby’
produces history-gabby† history† entries.
‘history:ignored’
does not generate history† entries.
localopts
[Obsolete] Please just use a local† or our† scope† , as in ‘local set’, ‘local environ set’ or ‘our call’.
(Compose mode) Reply to messages that come in via known (mlist† ) or subscribed (mlsubscribe† ) mailing lists, or pretend to do so (RFC 2369 ‘List-Post:’ header field, see Mailing lists† ): on top of the followup† and reply† functionality actively resort and even remove message recipients. Implicitly generate a ‘Mail-Followup-To:’ header field if that seems useful, regardless of followup-to† . For more documentation refer to Sending mail, and non-interactive mode† .
May generate ˆERR† -DESTADDRREQ if no recipient has been specified, ˆERR† -PERM if some recipients where rejected by expandaddr† , ˆERR† -IO if an I/O error occurs, ˆERR† -NOTSUP if a necessary character set conversion fails, and ˆERR† -INVAL for other errors, like those of Specifying messages† . Any error stops processing of further messages.
(Compose mode) Similar to mail† , but save the message in a file named after the local part of the first recipient’s address, overwriting record† , but honouring outfolder† .
(Compose mode)(m) Send mail to given (or asked for) list of recipients. Unless fullnames† is set recipient addresses are skinned, and see Sending mail, and non-interactive mode† ; supports local† .
May generate ˆERR† -DESTADDRREQ if no recipient has been specified, ˆERR† -PERM if some recipients where rejected by expandaddr† , ˆERR† -NOTSUP if multiple messages have been specified, ˆERR† -IO if an I/O error occurs, ˆERR† -NOTSUP if a necessary character set conversion fails, and ˆERR† -INVAL for other errors, like those of Specifying messages† .
[Option] Without arguments, or with only show, the content of The Mailcap files† cache is shown, (re-)initializing it as necessary. If it is load the cache will only be (re-)initialized, and clear will remove its contents. Only one attempt to load the files is made, clear has to be used for a retry. The load and parse step reacts upon verbose† .
(mb) Allowed only in a primary system mailbox† . Mark the given message list as a subject to automatic message moving† to the secondary mailbox† MBOX† folder† , overriding a set hold† ; overrides a former hold† request.
[Only new quoting rules] Without arguments the MIME type cache is shown (verbose† ly). Otherwise arguments are joined, and interpreted as shown in The mime.types files† (also see HTML mail and MIME attachments† ), and the result will be prepended (last in first out) to the cache. In any event MIME type sources are loaded first as necessary – mimetypes-load-control† fine-tunes loading.
The latter command deletes all entries of the given MIME types, asterisk ‘*’ discards all defined MIME types, just like ‘reset’, but that also reenables cache initialization via mimetypes-load-control† .
[v15 behavior may differ] Only available in interactive mode, this command allows execution of external MIME type handlers which do not integrate into the normal type† output (HTML mail and MIME attachments† ). [v15 behavior may differ] Message parts cannot be addressed directly. The user will be asked for each supported part in turn whether the registered handler shall be used to display the part.
[Only new quoting rules] Manage the list of known Mailing lists† ; subscriptions are controlled via mlsubscribe† . The former shows all currently known lists if used without arguments, otherwise the given ones become known. [Option] Many addresses can be matched with a single one containing magic regular expression characters† (matched sequentially via linked lists instead of dictionaries, though). The latter deletes all given specifications, or all with asterisk ‘*’.
Building upon the command pair mlist† , unmlist† , but only managing the subscription attribute of mailing lists. (The former creates yet unknown lists.)
Similar to move† , but move messages to a file named after the local part of the sender of the first message instead of taking a pathname argument; outfolder† is honoured.
Acts like copy† , but marks the messages for deletion if they were transferred successfully.
Like more† , but display all header fields and MIME parts. Identical to Page† .
Show the given messages in PAGER† , even in non-interactive mode (only ‘if† terminal’). Identical to page† , and see type† for more.
[Option] Without an argument or with show the mta-aliases† cache is initialized if necessary and then shown; the output is normalized and properly quoted and fitted to COLUMNS† ; it is usable as an aliases(5) input file. If the argument is clear the cache is removed, whereas load will also reinitialize it. Otherwise the expansion of the given MTA alias is shown in one line. With two arguments, hyphen-minus ‘-’ being the first, show the recursive expansion of the second.
[Option] Without arguments or with show the ˜/.netrc† cache is shown, initializing it (as necessary). If the argument is load the cache is initialized, clear removes its contents. Loading and parsing can be made more verbose† . lookup will query the cache for the URL given as the second argument (‘[USER@]HOST’). See netrc-lookup† , netrc-pipe† and the section URL syntax and credential lookup† ; the section The .netrc file† documents the file format in detail.
Checks for new mail in the current folder† ; if header† is set the headers† of new messages are shown. This command is not available for all folder† types; it emits an on-mailbox-event† .
(n) Go to the next (the first matching) message, and type† it on success. This is the default command for an empty interactive input line.
Same as Unread† .
Same as unread† .
If the current folder† is accessed via a network connection, a no-op(eration) command is sent over the wire (for keep-alive purposes).
Like page† , but display all header fields and MIME parts. Identical to More† .
Show the given messages in PAGER† , even in non-interactive mode (only ‘if† terminal’). Identical to more† , and see type† for more context.
Different to pipe† the raw message content, neither MIME decoded nor decrypted, is passed.
(pi) Takes an optional message list, and a (lesser) optional shell command (else, or if empty, cmd† ), and pipes the messages in the same visual form as type† , through the command (via SHELL† ). Every message is followed by a formfeed character if page† is set.
preserve†
(pre) A synonym for hold† .
(P) Alias for Type† .
(p) Research UNIX equivalent of type† .
(q) Initiate program termination, optionally with an exit status number, and perform all management tasks that exit† (see there) bypasses. Unless ignoreeof† is set typing end-of-transmission (EOT) ‘control-D’ (‘ˆD’) at the beginning of an empty line has the same effect. If new mail has arrived during the session, the message “You have new mail” will be shown.
[Only new quoting rules] Read a line from standard input, or the readctl† activated descriptor, and split as indicated by ifs† into to the given variable(s), which must honour variable name rules† (!† error codes apply). With only a circumflex ‘ˆ’ argument it instead creates a result set† with accessors ˆ#† , ˆ0† , ˆ1† etc.
The exit status ?† reports the number of bytes read (duplicated into ˆ0† with result set), or ‘-1’ on error, with !† set to ˆERR† -BADF in case of I/O errors, or ˆERR† -NONE upon End-Of-File (with no more bytes to read). Except with result sets, more fields than variables assign successive data to the last, and less fields than variables assign empty strings to unused ones. (Behaves like SHELL† s read(1) command with −r† option used.) Also see readall† , readsh† .
read a b c
#-> H e l l o
echo "$? <$a> <$b> <$c>"
#-> 16 <H> <e> <l l o>
set ifs=:; read
a b c;unset ifs
hey2.0,:"’you ",:world!:mars.:
echo "<$a><$b><$c><$d>"
#-> <hey2.0,><"’you
",><world!:mars.:><>
read ˆ
#-> H e l l o
ec "$ˆ# <$ˆ0> <$ˆ5>
<$ˆ*>"
#-> 5 <11> <o> <H e l l o>
[Only new quoting rules] Read anything unexpanded from standard input, or the readctl† activated descriptor, into to the given variable, which must honour variable name rules† (!† error codes apply); the exit status ?† reports the number of bytes read, or ‘-1’ on error, with !† set to ˆERR† -BADF in case of I/O errors, or ˆERR† -NONE upon End-Of-File (with no more bytes to read). [v15 behavior may differ] The input data length is restricted to 31-bits.
[Only new quoting rules] Manage input channels for read† , readsh† and readall† . Channel names are first checked for standard input hyphen-minus ‘-’, which always exists, then for a numeric file descriptor number, otherwise a pathname is assumed; filename based channels undergo minimal Filename transformations† (no meta expansion are performed).
Without arguments known channels are listed, as with show. New active ones can be created, existing ones can be set active and removed by giving their name. Shared (fcntl(2)) locks can be applied but to standard I/O channels: this is tried several times and can thus block and fail, an uppercase first letter will log iterations (case-insensitivity still applies besides). [Option](features† includes ‘,+flock,’) The otherwise identical flock lock type uses flock(2). Also see fop† .
$ printf
’echon "hey, "\nread a\nyou\necho $a’
|\
s-nail -R#
hey, you
$ LC_ALL=C
printf ’echon "hey, "\nread a\necho
$a’ |\
LC_ALL=C 6<<< ’you’ s-nail
-R#X’readctl create 6’
hey, you
set
fn=/tmp/members.dat
readctl create "$fn"
set rv=$? es=$! ed=$ˆERRDOC
if $rv -eq 0
readctl Lock "$fn" # ignore error
call .read-and-handle-until-eof "$fn"
readctl remove "$fn"
else
echoerr $’Cannot read file \$fn: \$ed’
endif
[Only new quoting rules] Like read† , but splits on shell token boundaries in a special mode where number sign ‘#’ is an ordinary character and Shell-style expansions† are not performed (Shell-style argument quoting† ), rather than at ifs† .
[Only new quoting rules] Remove named folders† . The given names are mailbox type classified, and type specific removal will be applied; removal of unknown types is refused. In interactive mode the user is asked for confirmation. [v15 behavior may differ] Removing a Maildir† mailboxes may be partial in case any of the subdirectories (tmp,new,cur) cannot be removed.
[Only new quoting rules] Rename the folder† given first to the name given second. Filename transformations† including shell pathname wildcard pattern expansions (glob(7)) are performed on both arguments. Both mailboxes must be of the same type.
(Compose mode)(R) Identical to reply† except that it replies to only the senders of the given messages, by using the first message as the template to quote, for the ‘Subject:’ etc.; setting flipr† will exchange this command with reply† .
(Compose mode)(r) Successively group reply to each of the given messages by addressing the sender and all recipients, subject to fullnames† and alternates† processing. followup-to† , followup-to-honour† , reply-to-honour† as well as recipients-in-cc† influence response behavior. quote† as well as quote-as-attachment† configure whether responded-to messages shall be quoted etc. record† controls saving the response message. Setting flipr† will exchange this command with Reply† . Lreply† offers special support for replying to mailing lists. For more documentation refer to Sending mail, and non-interactive mode† .
This may generate the errors ˆERR† -DESTADDRREQ if no recipient has been specified, or was rejected by expandaddr† policy, ˆERR† -IO if an I/O error occurs, ˆERR† -NOTSUP if a necessary character set conversion fails, and ˆERR† -INVAL for other errors. It can also fail with errors of Specifying messages† . Any error stops processing of further messages.
Like resend† , but does not add any header field. This is not a way to hide the sender’s identity, but useful for sending a bounced message again to the same recipients.
Send all given messages to the given recipient (fullnames† ). ‘Resent-From:’ and related header fields are prepended to sent messages. Saving in record† is only performed if record-resent† is set. [v15 behavior may differ](Compose mode) is not entered, the only supported hooks are on-resend-enter† and on-resend-cleanup† .
This may generate the errors ˆERR† -DESTADDRREQ if no recipient has been specified, or was rejected by expandaddr† policy, ˆERR† -IO if an I/O error occurs, ˆERR† -NOTSUP if a necessary character set conversion fails, and ˆERR† -INVAL for other errors. It can also fail with errors of Specifying messages† . Any error stops processing of further messages.
(ret) Superseded by the multiplexer headerpick† .
[Only new quoting rules][No field splitting] Returns control of execution to the outer scope of a Macro† (or account† ). All arguments are optional. Up to two positive decimal numbers, a 32-bit ([v15 behavior may differ] later 64-bit) return value (?† ), and a 32-bit error number (!† ), both defaulting to 0; as documented for ?† a non-0 exit status may cause a program exit. After a separating circumflex ‘ˆ’ any number of arguments can be made accessible to the callee’s result set† , then announced via ˆ?† : ˆ0† is set to the macro name, ˆ#† indicates arguments (ˆ1† etc); on excess !† as ˆERR† -OVERFLOW occurs.
(S) Similar to save, but save messages to a file named after the local part of the sender of the first message instead of taking a pathname argument; outfolder† is honoured.
(s) Append the given messages to the given pathname, which undergoes Filename transformations† including shell pathname wildcard pattern expansions (glob(7)). If no pathname is given, the secondary mailbox† MBOX† folder† is used. The quoted pathname and the generated byte count is shown on success. If editing a primary system mailbox† the messages are marked for deletion (but see keepsave† ). The ‘save’ slot of headerpick† filters out header fields not to be saved. Also see Copy† .
Displays a header summary of all messages given, as via headers† . This is an alias of from† . Also see Specifying messages† .
Marks all given messages as having been read.
[Only new quoting rules][No field splitting](se, uns) Manage (set and clear) Built-in variables† and free-form user custom INTERNAL VARIABLES† . Without arguments the former lists currently existing ones, with debug† or verbose† attributes are shown. With arguments the given ‘name’s or ‘name=value’ pairs (no space before or after the equal sign ‘=’) are set or adjusted. Prefixing ‘no’, for example ‘set noname’, equals calling ‘unset name’. Both commands support the scope† Command modifiers† local† and our† : for Built-in variables† and ENVIRONMENT† variables local† equals our† .
set atab=$’\t’ aspace=’ ’ zero=0 noprompt
commandalias e
’echon "x=$x y=$y z=$z, "; env look x’
define l1 {
e; our se x=x2 y=y2 z=z2; e; xcall l2
}
define l2 {
e
}
environ set x=x1; set y=y1; e; call l1; e;
#..
List mode does not automatically establish ‘environ† link’s for built-in ENVIRONMENT† variables: only explicit addressing via varshow† (with arguments), usage in an if† condition, or an argument to echo† , explicit setting (not necessarily via environ† ), as well as some program-internal use cases (look-ups) do this.
Set the “dot” to the given message.
Apply [+]e[ncode] or d[ecode] shell quoting rules to the following raw-data. The result of ‘+encode’ is not roundtrip enabled (Unicode etc.: only local decode); also see mle-quote-rndtrip† . On error !† is set to ˆERR† -CANCELED, and the unmodified input is the result. (Error may change again due to output or result storage errors.) Supports >† (Command modifiers† ).
(sh) Invokes an interactive SHELL† , then returns its exit status.
[Only new quoting rules] Manage shortcuts for Filename transformations† of folder† . The latter deletes all shortcuts given as arguments (all with asterisk ‘*’). Without arguments the former shows all currently defined shortcuts, with one the target of the given. Otherwise arguments specify pairs of shortcut names and expansions, creating new or updating already existing ones.
[Only new quoting rules][No field splitting] Shift positional parameters (so former 2 becomes 1† etc.) by 1 or the given number of positions. Positive numbers remove at the front, negative at the back. 0 does nothing, successfully. Shifting more than #† is an error. The stack as such can be managed via vpospar† . If the first argument is a circumflex ‘ˆ’ the scope’s result set† is instead addressed.
Show raw message data (like type† , but perform neither MIME decoding nor decryption).
(si) For all given messages, show their number, and the lines and bytes of the raw message content.
[Only new quoting rules] Sleep the given number of seconds. An optional non-empty second argument adds milliseconds. A non-empty third argument makes the sleep uninterruptible, otherwise !† will be set to ˆERR† -INTR upon interruption. If the given duration(s) overflow the time datatype an ˆERR† -OVERFLOW error occurs, invalid integers cause ˆERR† -INVAL.
Without arguments the former only shows, otherwise it sets the sorting criterion; the latter equals ‘sort none’. The criterion affects the folder† headers† visualization, addressing modes when Specifying messages† , and the meaning of next† ; The message numbers are not affected. If header† is set the headers† are shown accordingly, and see autosort† and autocollapse† . Possible sorting criterions are:
date
Sort by ‘Date:’ field (message send time).
from
Sort by ‘From:’ field (address of sender). The sender’s real name (if any) is used if showname† is set.
none
Do not sort (same as unsort).
size
Sort by size.
spam
[Option] Sort by spamrate† classified spam score.
status
Sort by Message states† .
subject
Sort by subject.
thread
Create a threaded display. autocollapse† may be set to collapse† threads automatically.
to
Sort by ‘To:’ field (recipient address). The recipient’s real name (if any) is used if showname† is set.
[Only new quoting rules](so) Read commands from the given file after doing Filename transformations† . A pathname with a trailing vertical bar ‘|’ is interpreted as a SHELL† command, the output of which will be read. Dependent on posix† and errexit† , as well as on the modifier ignerr† , encountered errors will stop reading, or cause program exit.
[Only new quoting rules] Different to source† (beside not supporting pipe aka shell command input) is that no error is generated if the given file cannot be opened successfully.
[Option] Clears the ‘is-spam’ flag of the given messages.
[Option] Pass the given messages to the spam-interface† so that it can un-train its Bayesian filter. Unless otherwise noted the ‘is-spam’ flag is inspected to decide what shall be forgotten, “ham” or “spam”.
[Option] Pass the given messages to the spam-interface† to inform it they are “ham”. This also clears the ‘is-spam’ flag.
[Option] Pass the given messages to the spam-interface† for rating purposes, without modifying messages, but only setting the ‘is-spam’ accordingly. The rating and flag will be forgotten once the folder† is left. Handling spam† shows the complete picture.
[Option] Sets the ‘is-spam’ flag of the given messages.
[Option] Pass the given messages to the spam-interface† to inform it they are “spam”. This also sets the flag ‘is-spam’.
[Option][Only new quoting rules] TLS information and management command multiplexer to aid in Encrypted network communication† with the given URL (URL syntax and credential lookup† ). The port of the URL’s ‘server:port’ defaults to HTTPS (443); only protocols which establish TLS directly are supported, not those which upgrade an insecure channel. Subcommands support >† (Command modifiers† ). The error result is the empty string, the error itself is stored in !† . For example, string length overflows are caught and set !† to ˆERR† -OVERFLOW. The TLS configuration is honoured, for example tls-verify† and tls-config-pairs† .
>result tls
fingerprint pop3s://ex.am.ple
echo "$?/$!/$ˆERRNAME: $result"
certchain
Show the complete verified peer certificate chain of the given URL. Includes informational fields in conjunction with verbose† .
certificate
Show only the peer certificate, without any signers, of the given URL. Includes informational fields in conjunction with verbose† .
fingerprint
Show the tls-fingerprint-digest† ed fingerprint of the certificate of the given URL. tls-fingerprint† is actively ignored for the runtime of this command.
Like top† but uses the headerpick† ‘type’ slot for white- and blacklisting header fields.
(to) type† s out the first toplines† lines of each of the given messages. Unless ‘top’ selection has been established with headerpick† , only ‘From:’, ‘To:’, ‘Cc:’, and ‘Subject:’ are shown. The message content display can be compressed via topsqueeze† .
(tou) Allowed only in a primary system mailbox† . Touch the given message list, and mark messages therein as a subject to automatic message moving† to the secondary mailbox† MBOX† folder† unless overriden by a set hold† ; overrides a former hold† request.
(T) Like type† but do not filter header fields through headerpick† , and visualize all parts of MIME ‘multipart/alternative’ messages.
(t) Show the given messages. Whether and when PAGER† is used for display instead of the screen† is controlled by crt† . (more† and page† alway use PAGER† .) Message header fields are filtered as chosen by the ‘type’ selection of headerpick† . For MIME multipart messages all ‘text’ message parts, all parts with a registered MIME type handler (HTML mail and MIME attachments† ) that produces copiousoutput† , and all ‘message’ parts are shown, others are hidden except for their header fields. Messages are decrypted and converted to ttycharset† as necessary. mimeview† can be used to display parts of other sort.
unaccount†
See account† .
unalias†
(una) See alias† .
unanswered†
See answered† .
unbind†
See bind† .
uncollapse†
See collapse† .
uncolour†
See colour† .
undefine†
See define† .
undelete†
See delete† .
undraft†
See draft† .
unflag†
See flag† .
Superseded by the multiplexer headerpick† .
unmimetype†
See mimetype† .
unmlist†
See mlist† .
unmlsubscribe†
See mlsubscribe† .
Same as unread† .
Marks all given messages as not being read (Message states† ).
Superseded by the multiplexer headerpick† .
unset†
[Only new quoting rules](uns) See set† .
unshortcut†
See shortcut† .
unsort†
See sort† .
Apply e[ncode], d[ecode], p[ath]enc[ode] or p[ath]dec[ode] URL percent codec (RFC 3986) operations on the following raw-data. The latter two are slightly modified to better adhere to pathnames: tilde ‘˜’ is not allowed, and the initial character can neither be hyphen-minus ‘-’ nor dot ‘’. ([v15 behavior may differ] The path-aware decoder is yet identical to the normal one.) This is a character set agnostic operation which could decode bytes that are invalid in the current ttycharset† .
Supports >† (see Command modifiers† ). If the operation fails !† is set to ˆERR† -CANCELED, and the unmodified input is the result (error number may change again due to output or result storage errors). [v15 behavior may differ] This command does not know about URLs beside what is documented. (vexpr† offers a makeprint subcommand, shall the URL be displayed.)
[Only new quoting rules] Show only the given variables, or all INTERNAL VARIABLES† . In the latter case local† scope settings are not, and vpospar† and other positional parameters are never covered. The output is subject to verbose† .
[Option] Verifies Signed and encrypted messages with S/MIME† . If a message is not a signed message, verification will fail for it. Verified is the message presented certificate, that the sender is mentioned in it, and that the message content is unchanged.
Show version† and features† , optionally in a more verbose† form that includes build and running system environment informations. Supports >† (Command modifiers† ).
[Option][Only new quoting rules] Multiplexer which offers checked signed 64-bit numeric calculations, as well as other, mostly string-based operations. C-style byte string operations are available via csop† , and file operations via fop† . The first argument defines number, type, and meaning of the remaining arguments. An empty number argument is treated as 0. Supports >† (Command modifiers† ). The result in case of errors is ‘-1’ for usage errors and numeric operations, the empty string otherwise; “soft” errors, like when a search operation failed, will also set !† to ˆERR† -NODATA. Except when otherwise noted numeric arguments are parsed as signed 64-bit numbers, errors cause a ˆERR† -RANGE !† .
Numeric operations work on one or two signed 64-bit integers according to number syntax rules† ; compared to arithmetic Shell-style expansions† they offer more control. Unsigned interpretation of a number can be enforced with an ‘u’ prefix (case-insensitive), as in ‘u-110’; power-of-two bases (2,4,8,16,32,64) are unsigned by default, but regarding overflow detection and error constants it still makes a difference. To enforce signed interpretation (instead) prefix ‘s’ (case-insensitive).
One integer is expected by assignment (equals sign ‘=’), which does nothing but validity and overflow detection, unary not (tilde ‘˜’), which creates the bitwise complement, and unary plus and minus. Two integers are used by addition (plus sign ‘+’), subtraction (hyphen-minus ‘-’), multiplication (asterisk ‘*’), division (solidus ‘/’) and modulo (percent sign ‘%’), as well as for the bitwise operators logical or (vertical bar ‘|’, to be quoted) , bitwise and (ampersand ‘&’), bitwise xor (circumflex ‘ˆ’), the bitwise signed left- and right shifts (‘<<’, ‘>>’), as well as for the unsigned right shift ‘>>>’.
Numeric operations support a saturated mode via the operator question mark ‘?’ modifier suffix; the keyword ‘saturated’ is optional, ‘+?’, ‘+?satu’, and ‘+?saturated’ are identical. In saturated mode overflow errors and division and modulo by zero are no longer reported via the return status, but the result will linger at the minimum or maximum possible value, instead of overflowing (or trapping). This is true also for the argument parse step. For the bitwise shifts, the saturated maximum is 63. Any caught overflow sets !† to ˆERR† -OVERFLOW.
>res vexpr
-? +1 -9223372036854775808
echo "$?/$!/$ˆERRNAME:$res"
#-> 0/75/OVERFLOW:-9223372036854775808
Another numeric operation is pbase, which takes a number base in between 2 and 64, inclusive, and will act on the second number given just the same as what equals sign ‘=’ does, but the number result will be formatted in the base given, as a signed 64-bit number unless unsigned interpretation of the input number had been forced.
Character set agnostic string functions have no notion of locale settings and character sets.
date-utc
Outputs the current date and time in UTC (Coordinated Universal Time) with values named such that ‘>x vexpr date-utc; eval set $x’ creates accessible variables. An optional argument denotes the UNIX seconds-since-the-epoch to be used instead of the current time. (The algorithm does not know about leap seconds and works until 65535-12-31T23:59:59.)
date-stamp-utc
Outputs the current UTC time in RFC 3339 internet date/time format.
epoch
The seconds and nanoseconds since the Unix epoch (1970-01-01T00:00:00) named ‘epoch_sec’ and ‘epoch_nsec’ such that ‘>x vexpr epoch; eval set $x’ creates accessible variables. May be given one to six optional arguments naming (in order) year, month, day (of month), hour, minute and second to be used instead of the current time. (The algorithm works until 65535-12-31T23:59:59.)
seconds
Like epoch, but outputs only the seconds directly as a numeric value.
rands, randu
Generate a(n un)signed 64-bit random number.
random
Generates a random string of the given length, or of PATH_MAX bytes (a constant from /usr/include) if the value 0 is given; the random string will be base64url encoded according to RFC 4648, and thus be usable as a (portable) pathname.
String operations work, sufficient support provided, according to the active user’s locale encoding and character set (Character sets† ). Where the question mark ‘?’ modifier suffix is supported, a case-insensitive operation mode is available; the keyword ‘case’ is optional, ‘regex?’ and ‘regex?case’ are identical.
makeprint
(One-way) Converts the argument to something safely printable on the terminal.
regex
[Option] A string operation that tries to match the first argument with the regular expression (re_format(7) or regex(7), dependent on host system) given as the second argument. ‘?’ modifier suffix is supported. With and within the optional third argument the result set† accessors ˆ#† , ˆ0† , ˆ1† are set for successful matches, and the argument is interpreted as if specified within dollar-single-quote (Shell-style argument quoting† ):
>res vexpr
regex bananarama \
(.*)NanA(.*) ’\${ˆ1}au\$ˆ2’
echo "$?/$!/$ˆERRNAME:$res:"
#-> 1/61/NODATA::
>res vexpr regex?case bananarama \
(.*)NanA(.*) ’\${ˆ1}uauf\$ˆ2’
echo "$?/$!/$ˆERRNAME:$res:"
#-> 0/0/NONE:bauauframa:
[Only new quoting rules] Manage the scope’s positional parameters (see 1† , #† , *† , @† as well as shift† ); if the first argument is a circumflex ‘ˆ’ the scope’s result set† is instead addressed; ˆ0† is unused (empty). With the global† modifier the global scope may be addressed. The argument ‘clear’ erases the stack. For ‘set’ remaining arguments will be used to (re)create the stack, if that excesses its size limit an ˆERR† -OVERFLOW error will occur. ‘evalset’ acts likewise, but only takes one argument to furtherly eval† uate in a special mode where number sign ‘#’ is an ordinary character and Shell-style expansions† are not performed (Shell-style argument quoting† ).
If the first argument is ‘quote’, a round-trip capable representation of the stack contents is created, with each quoted parameter separated from each other with the first character of ifs† , and followed by the first character of ifs-ws† , if non-empty and not equal to the first. If that results in no separation at all a space character is used. This mode supports >† (Command modifiers† ). The subcommands ‘set’ and ‘quote’ can be used (in conjunction with eval† ) to losslessly (re)create an argument stack from and to a single variable.
vpospar set
hey, "’you ", world!
ec "$#: <$1><$2><$3>"
#-> 3: <hey,><’you ,><world!>
>x vpospar quote
vpospar clear;
ec "$#: <$1><$2><$3>"
#-> 0: <><><>
eval vpospar
ˆ set "$x"
ec "$ˆ#:
<$ˆ1><$ˆ2><$ˆ3>"
#-> 3: <hey,><’you ,><world!>
se e=E x=$’a b\n#c d\n$e f\n’
se
ifs=$’\n’; vpospar set "$x"; uns ifs
ec "$#: <$1><$2><$3>"
#-> 1: <a b
#-> #c d
#-> $e f
#-> ><><>
se
ifs=$’\n’; eval vpospar set "$x"; uns
ifs
ec "$#: <$1><$2><$3>"
#-> 2: <a><b><>
se
ifs=$’\n’; vpospar evalset "$x"; uns
ifs
ec "$#: <$1><$2><$3>"
#-> 3: <a b><#c d><$e f>
vpospar evalset
"$x"
ec "$#:
<$1><$2><$3><$4><$5><$6>"
#-> 6:
<a><b><#c><d><$e><f>
(v) Successively invoke the VISUAL† display editor on the given messages. Modified contents are discarded unless writebackedited† is set, and are not used unless the mailbox can be written to, and the editor returns a successful exit status. edit† can be used instead for a less display oriented editor.
(w) Writes out the message bodies of the given messages (or the “dot”) to the given file (or /dev/null† ). Decryption etc is performed. Deletion or automatic message moving† does not kick in. Character set conversion to ttycharset† is performed when saving text data.
In interactive mode pathnames for MIME parts are consecutively asked for, an empty input equals /dev/null† , and the filename possibly given to write itself makes up a prefix; existing output files are appended to. Shell pipe targets may be indicated via a leading vertical bar ‘|’; Other user input undergoes the usual Filename transformations† , including shell pathname wildcard pattern expansions (glob(7)) and shell variable expansion.
[v15 behavior may differ] In non-interactive mode the same applies, but suspicious parts of pathnames of the remaining parts are URL percent encoded (as via urlcodec† ) to prevent injection of malicious character sequences, resulting in a filename that will be written into the current directory. Existing files will not be overwritten, instead the part number or a dot are appended after a number sign ‘#’ to the name until file creation succeeds (or fails due to other reasons).
[Only new quoting rules] Tail-call optimized variant of call† : the new Macro† is executed in place of the current one, which will not regain control: all resources of the current macro will be released first, except the re-parented settings covered by our† scoping. If this command is not used from within a call† ed macro it will silently be (a more expensive variant of) call† ; likewise the our† modifier is supported but silently turned into local† .
xit†
(x) A synonym for exit† .
[Only new quoting rules] Message headers† are shown in screen† fuls. Without arguments the next screen of messages is scrolled into view, like with ‘+’. An argument of ‘-’ scrolls to the previous, ‘ˆ’ scrolls to the first, and ‘$’ to the last screen. A number argument prefixed by ‘+’ or ‘−’ indicates a relative to the current position, a number without prefix an absolute position.
[Only new quoting rules] Similar to z† , but scrolls to the next or previous screen† that contains at least one ‘new’ or flag† ged message.
In interactive Compose mode† , within on-compose-embed† , or when requested via −˜† or batch mode (−#† ) command escapes offer attachment management, header field editing, COMMANDS† access and more. Whenever supported, an unquoted reverse solidus ‘\’ at the end of any input line “escapes” the newline character: it is discarded, and the next line of input is used as a follow-up line, with all leading whitespace removed. Escapes are only recognized in the leftmost column, and consist of the escape† character (default tilde ‘˜’), optional Command modifiers† , and a command character. Interspersed whitespace is ignored. To write an escape† in the leftmost column, double it. Addition to the [option]al history† is avoided by whitespace after escape† . The [option]al key bind† ings support a Compose mode† specific context. Modifiers:
•
Hyphen-minus ‘-’ acts like ignerr† does for COMMANDS† , and overrides errexit† .
set errexit;
reply .
˜ - : bad
#-> s-nail: bad: unknown command
˜:bad
#-> s-nail: bad: unknown command
#-> s-nail: Failed to prepare composed message
$
•
Dollar ‘$’ eval† uates the remains of the line as often as it is used (Shell-style argument quoting† ). [v15 behavior may differ] For now the entire input line is evaluated as a whole; to avoid that control operators like semicolon ; are interpreted unintentionally, they must be quoted.
set
var=’bla bla bla’; reply .
˜:echo ’$var’
#-> $var
˜$:echo ’$var’
#-> bla bla bla
Unless otherwise documented escapes also manage the error number !† and the exit/return status ?† ; errexit† may cause leaving compose mode and program exits.
Invoke the given SHELL† command. May expand bang† when set (see there; reverse solidus has no other special meaning).
Compose mode† (see there) is left, and the message is sent.
Can be used to execute COMMANDS† (not all are allowed in compose mode).
Identical to ˜r† .
command is executed using the SHELL† , and its standard output is inserted into the message.
[Option] Write a summary of command escapes.
Append to, or edit the list of attachments. Does not manage error number !† and exit status ?† (˜ˆ† offers fine grained control). The append mode expects a list of filename arguments as shell tokens (Shell-style argument quoting† ; token-separating commas are also ignored), to be interpreted as documented for the command line option −a† , with the message number exception as below.
Without filename arguments the attachment list is edited, entry by entry; if a filename is left empty, that attachment is deleted from the list; once the end of the list is reached either new attachments may be entered or the session can be quit by committing an empty input. In non-interactive as well as in batch mode (−#† ) the list of attachments is effectively not edited but instead recreated; again, an empty input ends list creation.
For all modes, if a given filename solely consists of the number sign ‘#’ followed by either a valid message number of the currently active mailbox, or by a period ‘.’, referring to the current message of the active mailbox folder† , the so-called “dot”, the given message is attached as a ‘message/rfc822’ MIME message part. The number sign must be quoted to avoid misinterpretation as a shell comment character.
Filter the message text through a SHELL† command; its standard output forms the new message text. If no output or a non-0 exit status is generated, the original message text is retained. The command fmt(1) is often used as a rejustifying filter (‘˜| /usr/bin/fmt -tuw11’).
‘˜||’ instead filters the entire message including header fields, so that ‘˜|| echo Fcc: /tmp/test; cat’ will prepend a file-carbon-copy message header. Also see ˜e† , ˜v† .
˜ˆ
cmd [
subcmd [
arg3 [
arg4]]], ˜ˆˆ
..
An easy accessor of digmsg† , for inspection and modification of the message draft. Aguments are evaluated according to Shell-style argument quoting† . Error number !† and exit status ?† are not managed: errors are handled by the I/O protocol, and hard errors like I/O failures cannot be handled.
˜ˆˆ does not use the I/O protocol, but stores results in the ˆ† multiplexer sub-variables ˆ#† , ˆ0† , ˆ1† etc: ˆ0† holds the status code, the remains are those sequential fields that otherwise make up lines, “missing” optional fields are stored as empty results, also meaning that ˆ1† may hold what would make up optional status code line remains. Variable values are not quoted, ˆ@† is to be expanded to achieve this result.
˜ˆheader
insert to The Bob <by@example.net>
#-> 210 To 1
˜ˆh show to
#-> 211 To
#-> by@example.net ’The Bob
<by@example.net>’
˜ˆˆ
h rem subject
˜:ec $ˆ0,$ˆ1,$ˆ*
#-> 210,Subject,Subject
˜ˆˆ h show subject
˜: ec $ˆ0,$ˆ1,$ˆ*
#-> 501,Subject,Subject
˜ˆˆ h i subject bla
˜: ec $ˆ0,$ˆ1,$ˆ*
#-> 210,Subject,Subject 1
˜ˆ ˆ h show subject
˜: ec $ˆ0,$ˆ1,$ˆ*
#-> 212,Subject,Subject bla
Add blind carbon copy recipients.
Add carbon copy recipients.
Paste the contents of DEAD† .
Invoke EDITOR† on the message draft, including header fields if editheaders† is set, then return to compose mode. ˜v† instead uses a more display oriented editor, and ˜|† pipe-based editing.
Read in messages or the “dot”, including all message header fields and MIME parts; forward-add-cc† as well as forward-inject-head† and forward-inject-tail† are honoured, as is cols† .
Read in messages or the “dot”. Strips down the header fields according to the ‘forward’ (‘type’ with posix† ) selection of headerpick† ; For MIME multipart messages, only the first displayable part is used; forward-add-cc† as well as forward-inject-head† and forward-inject-tail† are honoured, as is cols† .
In interactive mode, edit header fields ‘From:’, ‘Reply-To:’ and ‘Sender:’. The default values for these come from from† , reply-to† and sender† . In non-interactive mode this sets ˆERR† -NOTTY.
In interactive mode, edit header fields ‘To:’, ‘Cc:’, ‘Bcc:’ and ‘Subject:’. In non-interactive mode this sets ˆERR† -NOTTY.
Insert the value of variable. If empty or unset the message remains unaltered. Any embedded character sequences ‘\t’ horizontal tabulator and ‘\n’ line feed are expanded in posix† mode; otherwise the expansion should occur at set† time (v15-compat† , wysh† ).
Like ˜I† , but appends a newline character.
Read in messages or the “dot”, indented by indentprefix† . Honours forward-add-cc† as well as forward-inject-head† , forward-inject-tail† , and cols† .
Read in messages or the “dot”, indented by indentprefix† . Strips down the header fields according to the ‘type’ selection of headerpick† ; For MIME multipart messages, only the first displayable part is used; forward-add-cc† as well as forward-inject-head† and forward-inject-tail† are honoured, as is cols† .
Display the message draft, prefaced by the message header fields, and followed by the attachment list, if any.
Read in messages or the “dot”, using the algorithm of quote† (or a default if unset), honouring quote-add-cc† and cols† .
Abort composing, copying the draft to DEAD† if save† is set.
Identical to ˜r† , but indent each line that has been read by indentprefix† .
Read in filename, object to Filename transformations† excluding shell globs and variable expansions; if filename is the hyphen-minus ‘-’ then standard input is used: only then HERE-delimiter may be used to denote a marker that will stop reading if seen on a line by itself (an earlier EOF is an error); the HERE-delimiter is a required argument in non-interactive mode. A single-quoted delimiter will avoid Shell-style expansions† of data read ([v15 behavior may differ] expansion-caused variable not yet encapsulated). If the delimiter starts with hyphen-minus ‘-’ any leading tabs of data read until and including the delimiter itself is discarded: like this natural indentation in source files is possible.
Set the ‘Subject:’. Newline (NL) and carriage-return (CR) are normalized to space (SP).
Add direct recipients.
Read in messages or the “dot”, excluding all header fields, indented by indentprefix† . Honours forward-add-cc† as well as forward-inject-head† and forward-inject-tail† .
Read in messages or the “dot”, excluding all header fields. Honours forward-add-cc† as well as forward-inject-head† and forward-inject-tail† .
Invoke VISUAL† on the message draft, including header fields if editheaders† is set, then return to compose mode. ˜e† instead uses a less display oriented editor, and ˜|† pipe-based editing.
Write (append) the message draft onto the named file, subject to Filename transformations† .
Same as ˜q† , except the message draft is never saved.
Variables can be created or changed with set† , and erased with unset† . Built-in variables† may have typed values and attributes, custom variables with optional (string) values may be freely defined. varshow† will inspect all built-in, or the given variables, set† without arguments all currently existing ones; both can be more verbose† . Some built-in variables are synchronized from and with the program ENVIRONMENT† , others can be linked or created with environ† to henceforth have said property; these have to honour SHELL† variable name rules† .
set one=val\ 1
two="val 2" \
three=’val "3"’ four=$’val
\’4\’’; \
environ set FIVE=val\ 5; \
varshow one two three four FIVE; \
unset one two three four FIVE; \
varshow one two three four FIVE
Shell-style argument quoting† is necessary when assigning values; Built-in variables† may be interpreted as colour names, command specifications, normal text, be treated as numbers (decimal if so documented, otherwise number syntax rules† apply), etc. Boolean variables have no value, they are either “set” or “unset”, but there exists a special “boolean string”: either a decimal integer (with ‘0’ being false and ‘1’ or any other value being true), or one of the (case-insensitive) strings ‘off’, ‘no’, ‘n’ and ‘false’ for a false boolean and ‘on’, ‘yes’, ‘y’ and ‘true’ for a true boolean. A special kind of boolean string is the “quadoption” that is optionally prefixed with the (case-insensitive) term ‘ask-’, as in ‘ask-yes’: in interactive mode the user will be prompted, otherwise the actual boolean is used.
Some built-in variables exist as so-called “chains” which extend the plain ‘variable’ with ‘variable-HOST’ and ‘variable-USER@HOST’ variants. Here ‘HOST’ will be converted to all lowercase when looked up (but not when the variable is set or unset!), [option]ally IDNA converted, and indeed means ‘server:port’ if a ‘port’ had been specified in the contextual Uniform Resource Locator URL, see URL syntax and credential lookup† . Even though this mechanism is based on URLs no URL percent encoding (urlcodec† ) may be applied to neither of ‘USER’ nor ‘HOST’: variable chains need to be specified using raw data; the mentioned section contains examples. Chains are explicitly documented, and because they are special users should not create customs like ‘name-xyz’.
Initial
settings
The standard POSIX.1-2024 mandates these initial settings
(unsupported in brackets, deviations in parenthesis):
noallnet† ,
[noappend], asksub†
, noaskbcc† ,
noaskcc† ,
noautoprint† ,
nobang† ,
nocmd† ,
(no)crt† ,
nodebug† ,
nodot† ,
escape†
=’˜’,
noflipr† ,
nofolder† ,
header† ,
(no)hold† ,
noignore† ,
noignoreeof† ,
indentprefix†
=$’\t’ (‘’> ’’),
(no)keep† ,
(no)keepsave† ,
nometoo† ,
[noonehop],
nooutfolder† ,
nopage† ,
prompt† =’? ’,
noquiet† ,
norecord† ,
save† ,
noscreen† ,
(no)sendwait† ,
(no)showto† ,
noSign† ,
nosign† ,
toplines† =5.
This implementation sets sendwait† (with extended meaning), and does not support the noappend (worked (correctly) only for MBOX mailboxes) and noonehop (use command line options or mta-arguments† to pass mta† options) variables. The built-in defaults set, among others, hold† , keep† and keepsave† , and the system-wide resource file as shipped establishes a default headerpick† selection and more. The full list of defaults can be seen via set† : ‘$ s-nail -:/ -v -Xset -Xx’.
(Read-only) The exit status of the last of COMMANDS† , or the return† value of the last call† ed Macro† .
(Read-only) The errno(3); also available via ˆERR† , the name and documentation via ˆERRNAME† and ˆERRDOC† . Macro† s may signal an error number via return† .
(Read-only) A multiplexer for and of:
ˆ? , ˆ* , ˆ@ , ˆ# , ˆ0 , ˆ1 , ..
Result set access, in the local† -most scope† : extended return† values of the last Macro† call† ed (if ˆ? is true), regular expression match groups as created for example by if† and vexpr† , as well as other dedicated (documented) result sets, for example of fop† glob, the circumflex mode of digmsg† and ˜ˆ† , or read† and readsh† . ˆ# holds the number of accessible values (ˆ1 etc). For return values ˆ0 stores the macro name, for regular expressions the entire match, per-command documentation applies otherwise. ˆ* and ˆ@ behave like *† and @† .
define x {
if abrakadabra =˜ (.+)ka.*(b.+)a
echo "$ˆ#: <$ˆ0> <$ˆ1>
<$ˆ2>"
return ˆ says $ˆ2
end
}
call x; echo "$ˆ?, $ˆ#, $ˆ0 $ˆ1
$ˆ2"
#-> 3: <abrakadabra> <abra> <br>
#-> 1, 3, x says br
The number, documentation, and name, respectively, of the current errno(3); the first mirrors !† . Each may be suffixed with a hyphen minus followed by a name or number, in which case the expansion refers to the given error. Errors directly map to (a subset of) the system error values, with (high numbered) fallbacks for unsupported constants:
define work {
\eval echo \"\$1: \$ˆERR-$1: \
\$ˆERRNAME-$1: \$ˆERRDOC-$1\"
\if $1 -lt 16
\eval xcall work \$(("$1" + 1))
\end
}
\call work "$ˆERR-NONE"
ˆERRQUEUE-COUNT , ˆERRQUEUE-EXISTS
Number of messages in the [option]al queue of errors† , and a queue state indicator: empty or (translated) “ERROR”; 0 and the empty string unless features† includes ‘,+errors,’.
(Read-only) Expands all positional parameters (see 1† ), separated by the first character of ifs† in quoted mode (see Shell-style argument quoting† ).
(Read-only) Expands all positional parameters (see 1† ), separated by a space character. When placed in double quotation marks (Shell-style argument quoting† ) each parameter expands to a separate properly quoted token. (For example, to recreate arguments when call† ing a Macro† .)
(Read-only) The number of positional parameters, see 1† .
(Read-only) At top-level the program’s name, “compose mode” in Compose mode† . In call† ed Macro† scope† the calling macro’s name, or the empty string for top-level, but also inside a hook. [Obsolete] vexpr† used to use it as ˆ0† .
(Read-only) Positional parameter access; further positions are accessible with ‘2’, ‘3’ etc.; they can be shift† ed from the front, so former 2 becomes 1 etc. Positional parameters mostly exist within call† ed Macro† s; they can be managed directly with vpospar† . [Obsolete] vexpr† used to use it as ˆ1† etc.
(Read-only) Name of the active account† . The command line option −A† sets this in advance to flag the later account switch.
(Boolean) If set address comparisons use only the local part (ignore domains).
(Boolean) Instead prompts (interactively) for ‘Cc:’ and ‘Bcc:’ lists when leaving Compose mode† .
(Boolean) Prompt (interactively) for files to attach before leaving Compose mode† ; an empty line finalizes the list.
(Boolean) Prompt (interactively) for blind carbon copy recipients (when leaving Compose mode† with askatend† or bsdcompat† ).
(Boolean) Prompt (interactively) for carbon copy recipients (when leaving Compose mode† with askatend† or bsdcompat† ).
(Boolean) Prompt (interactively) for send confirmation before leaving Compose mode† after having been shown a preliminary envelope summary.
(Boolean)[Option] Prompt (interactively) for whether a message is to be signed (Signed and encrypted messages with S/MIME† ); smime-sign† is ignored when this is set.
(Boolean) Prompt (interactively) for a subject unless one already exists. (For POSIX.1-2024 compatibility ask actively maps to this.)
Defines Message states† dependent display characters for the ‘attribute’ column of headline† as shown for headers† , in the following order (the default is ‘NUROSPMFAT+−$˜’, or ‘NU *HMFAT+−$˜’ if bsdflags† is set):
‘N’
New.
‘U’
Unread but old.
‘R’
New but read.
‘O’
Read and old.
‘S’
Saved.
‘P’
Preserved.
‘M’
MBOX† ed.
‘F’
Flagged.
‘A’
Answered.
‘T’
Draft.
‘+’
[v15 behavior may differ] A (collapsed) thread in threaded sort† mode;
‘-’
[v15 behavior may differ] An uncollapsed thread in threaded sort† mode; only used in conjunction with −L† .
‘$’
Classified as spam.
‘˜’
classified as possible spam.
A list of blind carbon copy recipients that shall be added to each outgoing message.
A list of carbon copy recipients that shall be added to each outgoing message.
(Boolean) Automatically collapse† threads in sort† ‘thread’ mode.
(Boolean) type† the new “dot” after delete† and undelete† , if any, as via dp† or dt† .
Enter the given sort† ed mode when opening a folder† , for example ‘set autosort=thread autocollapse’.
(Boolean) !† (COMMANDS† ) and ˜!† (Compose mode† COMMAND ESCAPES† ) invoke SHELL† to run a command, and save that in bang-data† . If enabled, any non-reverse-solidus ‘\’ escaped exclamation mark ‘!’ character in the command string is replaced with bang-data† after normal operation has started (see −X† ), and if not executing a Macro† , nor loading files via source† , but processing input lines (also via −Y† ).
(Read-only) Current bang† expansion.
[Option] Often terminals generate multibyte sequences for diverse keys, yet these cannot be read as a unit. (Such sequences can also be freely defined via bind† .) This specifies a timeout in milliseconds that the MLE† (Terminal control and line editor† ) waits for more bytes to arrive unless it treats a sequence as completed. The default is 200, the maximum is about 10000 (10 seconds). The comments mention affected sequences in this example:
bind base abc
echo 0 # abc
bind base ab,c echo 1 # ab
bind base abc,d echo 2 # abc
bind base ac,d echo 3 # ac
bind base a,b,c echo 4
[Option] Multi-key bind† sequences (for example ‘a,b,c’) do not time out unless this is set like for (and (much) larger as) bind-inter-byte-timeout† .
(Boolean) Some cosmetical adjustments towards traditional BSD style; has the same affect as setting askatend† and all other variables prefixed with ‘bsd’; it also changes the behavior of emptystart† (but which does not exist in BSD).
(Boolean) Shift attrlist† towards traditional BSD style.
(Boolean) Shift headline† towards traditional BSD style.
(Boolean) Changes some informational messages towards traditional BSD style.
(Boolean) Causes the ‘Subject:’ field to appear immediately after the ‘To:’ field in message header fields and with the ˜h† COMMAND ESCAPES† .
build-cc , build-ld , build-os , build-rest
(Read-only) The build environment: operating system (usually taken from uname(1)), compiler, linker and a possible (configuration) rest. Much of this information is shown in version† s verbose† output.
[Option] If non-empty (‘+dotlock’ in features† ), the path to our priviledged dotlock helper (see folder† ).
[Option] If non-empty (‘+oauth-helper’ in features† ), the path to our OAuth helper script that may be capable to gain and manage OAuth credentials for ‘oauthbearer’ and ‘xoauth2’ authentication mechanisms (for more see according entries of smtp-config† ).
7-bit character set; defaults to US-ASCII, and should be US-ASCII compatible (to comply to email standards); will appear as ‘charset=’ in ‘Content-Type:’ MIME header fields for 7-bit clean message data.
[Option] 8-bit character set used as an implicit last member of sendcharsets† Defaults to UTF-8 if character set conversion is available (see Character sets† ), to ISO-8859-1 otherwise (unless UTF-8 is always supported).
(Read-only)[Option] Set to the character set of the user’s locale; see Character sets† .
[Option] RFC 1428 specifies conditions when internet mail gateways shall “upgrade” mail message content to a character set named ‘unknown-8bit’: because of its unclassified nature conversion to ttycharset† is impossible. If set ‘unknown-8bit’ is assumed to really be the given character set instead of charset-8bit† . Also taken into account when a ‘binary’ MIME message part (The mime.types files† ) is forcefully treated as text.
The default command for pipe† .
A positive number used instead of COLUMNS† at times if set (and representable). (For example by the [option]al HTML-tagsoup-to-text converter.) ([v15 behavior may differ] Conformance will improve.)
(Boolean)[Option] Disable usage of colours. Also see Coloured display† .
[Obsolete](Boolean)[Option] (Now an implied setting when colour-disable† is not set!)
(Read-only) Email and web contact addresses for bug reports, suggestions etc: ‘? eval† mail† $contact-mail’.
content-description-forwarded-message , content-description-quote-attachment , content-description-smime-message , content-description-smime-signature
[Option](partially) Optional ‘Content-Description:’ content (with default values).
Output line limit that enforces usage of PAGER† . Inherent usage can be enforced via ‘0’, if set without value the (current) TERM† inal LINES† are used to compute the limit (see screen† and stty(1)). [v15 behavior may differ] As of today the message line count is based upon wire format and mime-encoding† , therefore often unrelated to display lines. (The software is old and historically the relation was a given thing.)
Comma-separated list of custom header fields to be injected into newly composed messages, each consisting of a name, a colon ‘:’ and body content; commas in the latter need to be reverse solidus ‘\’ escaped. Standard names other than ‘Comments:’ and ‘Keywords:’ cannot be overwritten. In Compose mode† ˜ˆ† and digmsg† offer a more flexible header management; also see −C† .
? set customhdr=’Hdr1: Body1-1\, Body1-2, Hdr2: Body2’
Control appearance of the headline† format ‘%d’ to display the message ‘Date:’. The value is a strftime(3) format string (‘%n’ is unsupported, and causes display errors), default is ‘%Y-%m-%d %H:%M’. Also see datefield-markout-older† . If unset the local receive date is used unformatted.
Only used in conjunction with datefield† to create a visible distinction of messages dated more than one day in the future, or older than six months. If empty the month, day and year of ‘Date:’ will be displayed, the default initial strftime(3) format is ‘%Y-%m-%d’.
(Boolean) Enter noisy sandbox mode that disables message delivery and implies norecord† as well as nosave† . Also see verbose† .
(Boolean)[Option] Emit a ‘Disposition-Notification-To:’ header field (RFC 3798) with the message. This requires the from† variable to be set.
(Boolean) When set a period ‘.’ on a (interactive or batch −#† ) Compose mode† input line by itself is treated as end-of-message just like end-of-file (‘control-D’) is. It is implied in posix† mode when ignoreeof† is set.
(Boolean)[Option] Disable usage of dotlock files† for folder† .
Directly start with implied editheaders† into EDITOR† as via ˜e† , or VISUAL† as via ˜v† , when entering interactive Compose mode† . The latter is used only with the value ‘v’.
(Boolean) Include message header fields when editing message drafts in Compose mode† .
(Boolean) Unless set starting into receive mode on an empty or non-existing folder† prints “No mail for user” (but for bsdcompat† ), and exits the program.
(Boolean) If set any command or call† ed Macro† that exits non-0 causes a program exit unless prefixed with ignerr† (Command modifiers† ). Also affects COMMAND ESCAPES† except for modifier notation. For more on this see ?† .
[Option] Maximum number of entries in the queue ring (oldest fall off) of errors† .
The COMMAND ESCAPES† escape character (first byte). Default is tilde ‘˜’. An empty value disables command escapes.
Unless set only name and email address recipients are allowed (Sending mail, and non-interactive mode† ), otherwise all possible recipient types. May be set to a comma-separated case-insensitive list that is interpreted left-to-right. A member ‘restrict’ means name-and-address (really ‘restrict, -all,+name,+addr’!), except in interactive mode or with COMMAND ESCAPES† enabled via −˜† or −#† , in which case all types are allowed.
Recipient types may be added via a plus sign ‘+’, and removed via hyphen-minus ‘-’ prefix: all types via ‘all’, ‘fcc’ whitelists ‘Fcc:’ header targets regardless of other settings, ‘file’ file recipients (includes ‘fcc’), ‘pipe’ command pipelines, ‘name’ user names still unexpanded after alias† and mta-aliases† processing (left for expansion by the mta† — invalid at times, for example with a SMTP MTA unless ‘forcename’ is set: it implies ‘name’ (which excludes ‘forcename’!), and ‘addr’ email addresses. Unless hard errors are enforced via ‘fail’ disallowed types are filtered out with warning. Syntactically invalid addresses are silently filtered out, but ‘failinvaddr’ (really ‘failinvaddr,+addr’) enforces errors.
Name recipients addressing valid local users can be expanded to fully qualified network addresses (also see hostname† ) by including ‘nametoaddr’. ‘domaincheck’ (really ‘domaincheck, +addr’) compares address domain names against a whitelist and strips off (‘fail’ for hard errors) other recipients; ‘localhost’ and the non-empty value of hostname† (otherwise real hostname) are always allowed, other come in via expandaddr-domaincheck† . Finally some address providers (for example −b† , −c† and all other command line recipients) will be evaluated as if specified within dollar-single-quotes (Shell-style argument quoting† ) when ‘shquote’ is included.
Comma-separated list of whitelisted domain names for the ‘domaincheck’ of expandaddr† . IDNA encoding is not automatically performed, addrcodec† can be used to prepare names.
Unless set additional mta† arguments from the command line (specified after a separating −-) result in a program error exit; a case-insensitive ‘fail’ makes this explicit; ‘restrict’ allows them only in interactive mode, or with COMMAND ESCAPES† enabled via −˜† or −#† (like expandaddr† ). The empty value unconditionally allows MTA arguments.
(Boolean) Towards a quiet† , unchatty user interface: for power users and old hands. (To be extended on request.)
(Read-only) Optional feature string. Available when preceded by plus sign ‘+’, preceded by hyphen-minus ‘-’ otherwise, each feature is surrounded by commas to ease substring matches. version† prepares the information more human-friendly.
(Boolean) Flip the meaning of the lowercase reply† , respond† , followup† , which address all recipients, into their uppercase sender-only variants Reply† , Respond† , Followup† , and vice versa.
The default folder† save path: when set filenames with leading plus sign ‘+’ will have that replaced during Filename transformations† . A subset of transformations may be used, non-absolute paths get prefixed by HOME† . When evaluated first the folder-resolved† cache is set† . Note standard imposed implications of outfolder† .
folder-hook-FOLDER, folder-hook
[Obsolete] Predecessor of on-mailbox-event† . (With a different scope† !)
(Read-only) The fully resolved path of folder† .
(Boolean) Whether ‘Mail-Followup-To:’ shall be generated when contacting Mailing lists† (mlist† , mlsubscribe† ). The user (from† , sender† ) is placed if any list recipient is not a subscribed list.
(Boolean) Whether the user (from† , sender† ) shall be added to ‘Cc:’ in addition to a placing in ‘Mail-Followup-To:’.
Whether ‘Mail-Followup-To:’ is honoured when reply† ing or Lreply† ing. This is a quadoption† , the default without value is “yes”.
(Boolean) Whether senders of messages forwarded via the COMMAND ESCAPES† ˜F† , ˜f† , ˜m† , ˜U† and ˜u† shall be added to ‘Cc:’.
(Boolean) forward† ing messages places a (the first text part of a MIME) message copy as inline text; if set the complete message is attached via MIME ‘message/rfc822’.
forward-inject-head , forward-inject-tail
When placing forward† ed messages (also via COMMAND ESCAPES† ˜F† , ˜f† , ˜M† , ˜m† , ˜U† , ˜u† ) as inline text these are written before and after, respectively. The former defaults to ‘-------- Original Message --------\n’. The same format directives as for quote-inject-head† are understood, folded according to quote-fold† .
An email address (a mailbox); mostly only necessary with a [option]al SMTP mta† . Quoting RFC 5322: “the author(s) of the message, that is, the mailbox(es) of the person(s) or system(s) responsible for the writing of the message.” If ‘From:’ contains multiple addresses specifying ‘Sender:’ (sender† ) is required according to that RFC. alias† es are expanded instantly with senders kept (metoo† ); Contextually these addresse(es) are alternates† .
With a file-based mta† from (or sender) may still be used as the envelope sender address (the RFC 5321 reverse-path) via an empty −r† command line argument, or by setting r-option-implicit† .
If the machine is not resolvable in the network usually hostname† and/or this have to be set (a SMTP-based mta† adds onto this smtp-from† ). With either set unique ‘Message-ID:’ and MIME part ‘Content-ID:’ header fields are created (unless disallowed by message-id-disable† or stealthmua† , and see message-id† ).
(Boolean) Avoid skinning down email addresses (the stripping of names etc).
(Boolean) Show headers† at startup. Unless posix† is set extend this to changing folder† , sort† order etc. (Also see −N† .)
Format string to style and layout headers† . Contains normal used as-is text and expandable conversions, which consist of a percent sign ‘%’, an optional field width (decimal; negative numbers, or only hyphen-minus in the last field, indicate left-alignment), and a conversion specifier. Names and addresses are subject to showname† and showto† , and see headline-plain† and headline-bidi† . The default is ‘%>%a%m %-18f %-16d %4l/%-5o %i%-s’ (bsdcompat† : ‘%>%a%m %-20f %16d %4l/%-5o %i%-S’); conversions are:
‘%%’
Double it to avoid expansion.
‘%>’
“Dotmark”: a space; ‘>’ for “dot” (current message).
‘%<’
“Dotmark”: a space; ‘<’ for “dot”.
‘%$’
[Option] Message spam score as classified by spamrate† (or a replacement character).
‘%a’
Message states† indicator to be expanded via attrlist† .
‘%d’
Formatted ‘Date:’ header field according to datefield† if set (default), otherwise the unformatted message receive date.
‘%e’
Indent level in threaded sort† mode.
‘%f’
Message sender address.
‘%i’
Message thread tree structure. (Field width unsupported; honours headline-plain† .)
‘%L’
Mailing list status: is a recipient a ‘l’ (mlist† ) or ‘L’ mlsubscribe† d mailing list? As last resort ‘P’ announces presence of a RFC 2369 ‘List-Post:’ header field, making a message a valuable target of Lreply† .
‘%l’
Number of message lines, if available.
‘%m’
Unique message number.
‘%o’
Number of message bytes, if available.
‘%S’
Message subject (if any) in double quotes.
‘%s’
Message subject (if any).
‘%t’
The position in sorted order.
‘%U’
The value 0 except in an IMAP folder† , there the UID of the message.
Bidirectional text requires special treatment when displaying headers, because numbers (in dates or for file sizes etc.) will not affect the current text direction, in effect resulting in ugly line layouts when arabic or other right-to-left text is to be displayed. On the other hand only a minority of terminals is capable to correctly handle direction changes, so that user interaction is necessary for acceptable results. Note that extended host system support is required nonetheless, for example detection of the terminal character set is one precondition; and this feature only works in an Unicode (that is UTF-8) locale.
Setting this causes encapsulation of some text fields of headline† (and some other, like dynamic expansions in prompt† ) with special Unicode control sequences. Fine-tune terminal support level by assigning a value: no value indicates the terminal can properly deal with Unicode version 6.3 (or above), in which case text is embedded in the pair U+2068 (FIRST STRONG ISOLATE) and U+2069 (POP DIRECTIONAL ISOLATE); in addition no space on the line is reserved for these characters. Weaker support is chosen via ‘1’ (Unicode 6.3, but reserve room of two spaces for the pair). The values ‘2’ and ‘3’ select Unicode 1.1 support (U+200E, LEFT-TO-RIGHT MARK); the latter again reserves room for two additional spaces.
(Boolean) On Unicode (UTF-8) aware terminals enhanced graphical symbols are used by default for certain entries of headline† . If set only 7-bit US-ASCII symbols are instead used.
[Option] Location of a permanent history† file for the MLE† line editor (Terminal control and line editor† ). Filename transformations† are performed. Also see history-size† .
[Option] Add gabby entries to MLE† history† . A comma-separated list of case-insensitive keywords may be given: ‘errors’ adds erroneous commands, ‘fuzz’ certain usage forms, for example message number or string arguments instead of fixed, reproducable keywords and/or colon modifiers when Specifying messages† ([v15 behavior may differ] more subcommand use cases will be covered), and ‘all’ for anything (default). Complete control is available via on-history-addition† .
(Boolean)[Option] Added history-gabby† entries are not saved to persistent storage unless set. The gabby state persists.
[Option] Impose a limit on history† entries. If 0 no further entries are added, and loading the history-file† upon startup is suppressed. Value runtime changes are not reflected unless history† is saved or (re)loaded.
(Boolean) Control toggle for standardized automatic message moving† , and see keep† , keepsave† .
Used instead of asking uname(3) / getaddrinfo(3) for local ‘From:’ etc. addresses (context: Sending mail, and non-interactive mode† ) if non-empty. If set (even empty) unique ‘Message-ID:’ and MIME part ‘Content-ID:’ header fields are created (unless disallowed by message-id-disable† or stealthmua† ); also see from† and message-id† . [Option] If IDNA conversion is necessary but fails assignment is aborted (idna-disable† ). One should produce some test messages with the desired combination of hostname, and/or from† , sender† , smtp-from† .
(Boolean)[Option] Turn off conversion of Character sets† .
(Boolean)[Option] Turn off IDNA (internationalized domain names for applications) conversions. ttycharset† is assumed for domain names (the UTF-8 character set is required to represent all non-converted IDNs), for context see Character sets† .
addrcodec enc
root@äpfel.example
#-> root@xn--pfel-koa.example
Input field separators used for field splitting (see Shell-style argument quoting† , and also posix† for compatibility issues), and for the read† command to split lines into words.
•
unset† (re)establishes the default value ‘ \t\n’.
•
No field splitting occurs when set to the empty value.
•
The first byte has special meaning for how field splitting is performed; it is also used as a separator for quoted forms of *† , for example.
•
Whitespace characters of the value are assigned to ifs-ws† .
•
COMMANDS† which mention [No field splitting] explicitly suppress field splitting.
(Read-only) Deduced from whitespace within ifs† .
(Boolean) Ignore interrupt signals in Compose mode† ; instead echo them as ‘@’, and discard the current line.
(Boolean) Ignore end-of-file conditions (‘control-D’) in Compose mode† and in interactive input of COMMANDS† : when set only ˜.† (or dot† , even implied with posix† !), can leave the former, and only exit† or quit† can exit the session.
The user’s primary system mailbox† , overriding MAIL† and the system-dependent default, and used to replace ‘%’ when doing Filename transformations† ; also see folder† . The value only supports a subset of the transformations itself (‘+’ not).
String used by the ˜m† , ˜M† and ˜R† COMMAND ESCAPES† , by the quote† option for message indentation, and the [option]al HTML-tagsoup-to-text converter. The POSIX.1-2024 default is tabulator ‘\t’. Also see quote-chars† .
(Boolean) Do not remove an empty primary system mailbox† (posix† mode: any empty folder† ). (Re-) Creating files in a (world-writeable / sticky) MAIL† folder† could result in undesired file modes (relates umask† ). [v15 behavior may differ] Applies only to local MBOX and maildir mailboxes, nothing else will be removed, even if empty; note a Maildir† remove† may be partial in case of errors.
(Boolean) Preserve messages save† d from a primary system mailbox† like inbox† into other folder† s during automatic message moving† .
[Option] MLE† configuration, a case-insensitive comma-separated list: ‘quote-rndtrip’ (mle-quote-rndtrip† default), ‘srch-case’ (case-insensitive mle-hist-srch-bwd† and mle-hist-srch-fwd† matches), ‘srch-any’ (match any substring instead of exact entry); [Option]ally ‘srch-regex’ matches via regular expressions (mutual with ‘srch-any’). ‘srch-pos0’ moves the cursor to the prompt† when long history† matches would move “off” screen† .
[Option] List of bytes mle-complete† uses to detect word boundaries, by default ‘:"’@=;|’ (whitespace is automatically included; some shells use ‘\t\n"\’‘@$><=;|&{(’). [v15 behavior may differ] This mechanism is yet restricted.
(Boolean) Turn off line editing capabilities (Terminal control and line editor† ).
(Boolean)[Option] Do not establish default key bind† ings.
Error log message prefix string (‘s-nail: ’).
(Read-only) Last name component of current folder† .
(Read-only) Name of current folder† , possibly abbreviated for display purposes (screen† ).
(Read-only)(Boolean) Whether current folder† is read-only.
(Read-only) Fully resolved path of current folder† . Note: not reproducible (see SOURCE_DATE_EPOCH† ).
(Boolean)[Option] Turn off consideration of MIME type handlers from, and implicit loading of The Mailcap files† .
Additional startup file loaded last among the Resource files† . A good place for non-portable, non-POSIX.1-2024 mailx(1) features.
(Boolean) When set any message reply† marks it answered† . See Message states† .
(Boolean) File and pipe recipients (expandaddr† ) receive a one-message MBOX file (folder† ), already existing (MBOX) files are appended to. If unset a plain RFC 5322 (EML) message is instead received, and existing files are overwritten.
(Boolean) For compatibility with old software opening a MBOX folder† uses tolerant POSIX.1-2024 instead of the stricter RFC 4155 rules for message boundary detection (so-called ‘From_’ lines), unless this is set. May be handy temporarily when opening complains about an invalid MBOX: setting it and reopening the folder may be a saveable corrective ([v15 behavior may differ]: no MIME re-encode yet):
define mboxfix
{
local set mbox-rfc4155; File "$1"; copy *
"$2"
}
call mboxfix /tmp/bad.mbox /tmp/good.mbox
(Boolean) Internal, development related, auto-enabled with debug† .
When set ‘Message-ID:’ and ‘Content-ID:’ MIME (part) will be generated (but also see from† , hostname† , message-id-disable† , stealthmua† ). If non-empty generation honours the given format string, which consists of normal text and expandable conversions of a percent sign ‘%’ and a conversion specifier. If unset or empty, or if results are shorter 10 bytes or without randoms ‘%Y%m%d%H%M%S.%r%r@%a’ is used. Date and time are in UTC (Coordinated Universal Time).
‘%%’
Doubling avoids expansion.
‘%a’
Sender address, with ‘@’ replaced by ‘%’ because some spam detectors trigger otherwise for unknown reasons. If unavailable equals ‘%h’.
‘%d’
Two-digit day.
‘%H’
Two-digit hour (24-hour notation).
‘%h’
Either hostname† or the real hostname; if unavailable equals ‘%r%r’.
‘%M’
Two-digit minute.
‘%m’
Two-digit month.
‘%r’
A base64-URL (RFC 4648) encoded random string of size four (4).
‘%S’
Two-digit second.
‘%Y’
Four-digit year.
(Boolean) Suppress generation of ‘Message-ID:’ and ‘Content-ID:’ MIME (part) header fields, leaving this up to the mta† (according to RFC 5321 a SMTP server is not required to do so). Manually created such header fields are never stripped.
message-inject-head , message-inject-tail
Strings to insert at the top and bottom of each generated message. [Obsolete] The escape sequences tabulator ‘\t’ and newline ‘\n’ are understood (instead expand via Shell-style argument quoting† at set† time). Also see on-compose-leave† .
set
Sign=$’\n Tony\n I am fixing things!’
set message-inject-tail=${Sign}
(Boolean) Suppress deletion of the sender (from† , sender† , LOGNAME† , and contextually alternates† ; compared according to allnet† ) when performing alias† expansion. (Implied for blind carbon copy recipients ‘Bcc:’.) Also passes file-based mta† s the option ‘-m’ except with mta-no-default-arguments† (mostly undocumented, but no MTA is known that does not support it).
(Boolean)[v15 behavior may differ] This is a “hack”! Upon message creation and ‘Content-Type:’ plus ‘Content-Transfer-Encoding:’ (see mime-encoding† ) detection text files encoded in the UTF-16 and other “wide” character sets are identified as binary data. (Wide means that each character is stored in a datatype that is larger than a byte, for UTF-16 the number stands for the bits of the datatype; possibly multiple such are needed to represent the character. Byte-based multibyte character sets, like UTF-8, are (also) capable to store all characters of the world, but form byte sequences that are not detected as binary data.) If set, and if the data was unambiguously identified as text at first glance, for example via ‘.txt’ or ‘.html’ file extensions, then (and only then) no binary data is presumed. In the future (maybe v15) the first few bytes of a file may be looked upon to check for B(yte)O(rder)M(ark) markers: correctly marked UTF-8 and UTF-16 files would then be automatically treated accordingly.
(Boolean) If set “rich” MIME alternative parts (for example HTML) are preferred over plain text versions when displaying messages, provided that a copiousoutput† MIME handler exists (HTML mail and MIME attachments† ).
MIME part content is identified by ‘Content-Type:’ header fields. Yet content is often incorrectly classified (compare The mime.types files† and HTML mail and MIME attachments† ), resulting in unspecific MIME types (‘application/octet-stream’) even for plain text attachments. If set MIME message part reclassification may be attempted, a positive number configures a behavior subset:
•
Bit two (‘$((1 << 1))’) remembers a counter-detected mimetype† , to select MIME handlers when type† ing for example (the part-info indicates such by showing a plus sign ‘+’).
•
Bit three (‘$((1 << 2))’) always generates a counter-evidence, and uses that detected MIME type.
•
Bit four (‘$((1 << 3))’) causes content data inspection of ‘application/octet-stream’ part content. (This mode is even more relaxed when data is to be displayed to the user or used as a quoted message, since all code paths are under control and control characters etc can do no harm.)
An equivalence to an empty value can achieved via ‘set mime-counter-evidence=0b1110’ or ‘set mime-counter-evidence=$((2 | 4 | 8))’).
The MIME ‘Content-Transfer-Encoding’ to use in outgoing text messages and message parts, where applicable (7-bit clean text messages are without an encoding if possible):
‘8bit’
(Or ‘8b’.) 8-bit transport effectively causes the raw data be passed through unchanged, but may cause problems when transferring mail messages over channels that are not ESMTP (RFC 1869) compliant. Also, several input data constructs are not allowed by the specifications and may cause a different transfer-encoding to be used. By established rules (MBOX file protection, see folder† ), and popular demand occurrences of ‘ˆFrom_’ will be “MBOXO” quoted (prefixed with greater-than sign ‘>’) instead of causing a non-destructive encoding like ‘quoted-printable’ to be chosen, unless context (like message signing) requires otherwise.
‘quoted-printable’
(Or ‘qp’.) Quoted-printable encoding is 7-bit clean and has the property that ASCII characters are passed through unchanged, so that an english message can be read as-is; it is also acceptable for other single-byte locales that share many characters with ASCII, for example ISO-8859-1. The encoding will cause a large overhead for messages in other character sets: for example it will require up to twelve (12) bytes to encode a single UTF-8 character of four (4) bytes. It is the default encoding.
‘base64’
(Or ‘b64’.) This encoding is 7-bit clean and will always be used for binary data. This encoding has a constant input:output ratio of 3:4, regardless of the character set of the input data it will encode three bytes of input to four bytes of output. This transfer-encoding is not human readable without performing a decoding step.
(Boolean)[Option] When failing to send out messages because of non-convertible character content is not acceptible setting this will, as a last resort, classify data as ‘application/octet-stream’; the receiver can then still inspect the data (even automatically via mime-counter-evidence† ). Refer to the section Character sets† for the complete picture of character set conversion, and HTML mail and MIME attachments† for how to internally or externally handle part content. Does not apply to header content, like filenames. Set by default.
Can be used to control which of The mime.types files† are loaded: if the letter ‘u’ is part of the option value, then the user’s personal ˜/.mime.types† file will be loaded (if it exists); likewise the letter ‘s’ controls loading of the system-wide /etc/mime.types† ; directives found in the user file take precedence, letter matching is case-insensitive. If this variable is not set S-nail will try to load both files. Incorporation of the S-nail-built-in MIME types cannot be suppressed, but they will be matched last (the order can be listed via mimetype† ).
More sources can be specified by using a different syntax: if the value string contains an equals sign ‘=’ then it is instead parsed as a comma-separated list of the described letters plus ‘f=FILENAME’ pairs; the given filenames will be expanded and loaded, and their content may use the extended syntax that is described in the section The mime.types files† . Directives found in such files always take precedence (are prepended to the MIME type cache).
Select an alternate Message-Transfer-Agent by either specifying the full pathname of an executable (a ‘file://’ prefix may be given), or [option]ally a SMTP aka SUBMISSION protocol URL:
submissions://[user[:password]@]server[:port]
The default has been chosen at compile time. MTA data transfers are always performed in asynchronous child processes, and without supervision unless either the sendwait† or the verbose† variable is set. Also see mta-bcc-ok† . [Option]ally expansion of aliases(5) can be performed by setting mta-aliases† .
For testing purposes there is the ‘test’ pseudo-MTA, which dumps to standard output or optionally to a file, and honours mbox-fcc-and-pcc† :
$ echo text |
s-nail -:/ -Smta=test -s ubject ex@am.ple
$ </dev/null s-nail -:/ -Smta=test://./xy ex@am.ple
For a file-based MTA it may be necessary to set mta-argv0† in in order to choose the right target of a modern mailwrapper(8) environment. It will be passed command line arguments from several possible sources: from the variable mta-arguments† if set, from the command line if given and the variable expandargv† allows their use. Argument processing of the MTA will be terminated with a −- separator.
The otherwise occurring implicit usage of the following MTA command line arguments can be disabled by setting the boolean variable mta-no-default-arguments† (which will also disable passing −- to the MTA): −i (for not treating a line with only a dot ‘.’ character as the end of input), −m (shall the variable metoo† be set) and −v (if the verbose† variable is set); in conjunction with the −r† command line option or r-option-implicit† −f as well as possibly −F will (not) be passed.
[Option]ally S-nail can send mail over SMTP aka SUBMISSION network connections to a single defined smart host by setting this variable to a corresponding URL (see URL syntax and credential lookup† ). Server interaction (TLS, authentication type, etc.) is configurable via smtp-config† . An overview on TLS and links to more information can be found under Encrypted network communication† . Note that with some mail providers it may be necessary to set the smtp-from† variable in order to use a specific combination of from† , hostname† and mta† . Network communication socket timeouts are configurable via socket-connect-timeout† . All generated network traffic may be proxied over a SOCKS socks-proxy† , it can be logged by setting verbose† twice. The following SMTP variants may be used:
•
The plain SMTP protocol (RFC 5321) that normally lives on the server port 25, which will [option]ally be upgraded to a TLS encrypted session unless disallowed by smtp-config† . Assign a value like ‘smtp://[user[:password]@]server[:port]’ to choose this protocol.
•
[Option] The so-called SMTPS which is supposed to live on server port 465 and is automatically TLS secured. Unfortunately it never became a standardized protocol and may thus not be supported by your hosts network service database – in fact the port number has already been reassigned to other protocols!
SMTPS is nonetheless a commonly offered protocol and thus can be chosen by assigning a value like ‘smtps://[user[:password]@]server[:port]’; due to the mentioned problems it is usually necessary to explicitly specify the port as ‘:465’, however.
•
The SUBMISSION protocol (RFC 6409) lives on server port 587 and shares the semantics with SMTP from S-nail’s point of view: ‘submission://[user[:password]@]server[:port]’.
•
[Option] The SUBMISSIONS protocol (RFC 8314) that lives on server port 465 and is TLS secured by default. It can be chosen by assigning a value like ‘submissions://[user[:password]@]server[:port]’. Due to the problems mentioned for SMTPS above and the fact that SUBMISSIONS is new and a successor that lives on the same port as the historical engineering mismanagement named SMTPS, it is usually necessary to explicitly specify the port as ‘:465’.
[Option] If set to a path pointing to a text file in valid MTA (Postfix) aliases(5) format, the file is loaded and cached (manageable with mtaaliases† ), and henceforth plain ‘name’ (see expandaddr† ) message recipient names are recursively expanded as a last expansion step, after the distribution lists which can be created with alias† . Constraints on aliases(5) content support: only local addresses (names) which are valid usernames (‘[a-z_][a-z0-9_-]*[$]?’) are treated as expandable aliases, and [v15 behavior may differ] ‘:include:/file/name’ directives are not supported. By including ‘-name’ in expandaddr† it can be asserted that only expanded names (mail addresses) are passed through to the MTA.
Arguments to pass through to a file-based mta† , parsed according to Shell-style argument quoting† into an array of arguments which will be joined onto MTA options from other sources, for example ‘? set mta-arguments=’-t -X "/tmp/my log"’’.
(Boolean) Avoids passing standard command line options to a file-based mta† (see there).
(Boolean) By default all recipient addresses will be passed as command line options to a file-based mta† . Setting this variable disables this behavior to aid those MTAs which employ special treatment of such arguments. Doing so can make it necessary to pass a −t via mta-arguments† , to testify the MTA that it should use the passed message as a template.
Many systems use a so-called mailwrapper(8) environment to ensure compatibility with sendmail(1). This works by inspecting the name that was used to invoke the mail delivery system. If this variable is set then the mailwrapper (the program that is actually executed when calling the file-based mta† ) will treat its contents as that name.
(Boolean) Only affects file-based mta† s: in violation of RFC 5322 some do not remove ‘Bcc:’ header lines from messages after having noted respective recipients for addressing purposes automatically. (Exim and Courier for example remove only with the command line option −t.) Unless set corresponding recipients are only passed via command line (this prepares a cleaned message copy).
netrc-lookup-USER@HOST, netrc-lookup-HOST, netrc-lookup
(Boolean)[Option] Used to control usage of the user’s ˜/.netrc† file for lookup of account credentials, as documented in the section URL syntax and credential lookup† and for the command netrc† ; the section The .netrc file† documents the file format. Also see netrc-pipe† .
[Option] When ˜/.netrc† is loaded (see netrc† and netrc-lookup† ) then S-nail will read the output of a shell pipe instead of the user’s ˜/.netrc† file if this variable is set (to the desired shell command). This can be used to, for example, store ˜/.netrc† in encrypted form: ‘? set netrc-pipe=’gpg -qd ˜/.netrc.pgp’’.
[Option] If this variable has the value ‘maildir’, newly created local mailbox folder† s will be in Maildir† instead of MBOX format.
Checks for new mail in the current mailbox each time the prompt is shown. [Option] A Maildir† mailbox folder† must be re-scanned to determine if new mail has arrived. If this variable is set to the special value ‘nopoll’ then a Maildir mailbox will not be rescanned completely, but only timestamp changes are detected.
Configure minimum version in version-hexnum† format of obsoletion messages to show. Current minimum and maximum are ‘0x0E009019’ (v14.9.25) and ‘0x0E00A000’ (v14.10.0).
(Boolean) Causes non-absolute pathnames (compare Filename transformations† ) specified in record† , or as sender-based arguments of Copy† , Save† , Followup† and followup† to be interpreted relative to folder† instead of the current directory (cwd† ).
on-account-cleanup-ACCOUNT, on-account-cleanup
Macro† hook which will be called once an account† is left, as the very last step before unrolling the per-account scope† . This hook is run even in case of fatal errors, including those generated by switching to the account as such, and it is advisable to perform only absolutely necessary actions, like cleaning up alternates† , for example. The specialized form is used in favour of the generic one if found.
Macro† hook called as the last step inside Compose mode† scope† . It is run even in case of fatal errors, and it is advisable to perform only absolutely necessary actions. [v15 behavior may differ] This hook mostly exists because alias† , alternates† , commandalias† , shortcut† , to name a few, are not yet covered by scopes: changes applied in Compose mode† will continue to be in effect thereafter.
Macro† hook that is invoked once the Compose mode† user interaction has ended (but see asksend† ). It runs in COMMAND ESCAPES† mode and can act like an interactive user. The s-nail-config(7) manual provides examples.
Macro† hook that is invoked once Compose mode† is entered; digmsg† may access the message.
Macro† hook which is run before Compose mode† is left; the message can still be accessed via digmsg† . The s-nail-config(7) manual provides examples.
Executes with three arguments before a MLE† history† entry is to be added (see Terminal control and line editor† ): the bind† input context name, the history-gabby† type (or the empty string), finally the entry as one token. If the hook return† s 0 the entry is added as-is, with 2 it is added as history-gabby† , with 3 gabbyness is removed; any other value rejects the addition. [v15 behavior may differ] A future version will return more than 3 arguments: the expanded command name as the third, followed by individual tokens of the command line, including the used command name as the first; that is, after ‘shift† 4’ the positional parameters will be accessable as *† , #† , 1† etc.
se
on-history-addition=oha
def oha {
if $2 == fuzz || $2 == errors; return 1; en
if $# -eq 3
if " $3" =% ’ set ’ || " $3"
=% ’ unset ’; return 3; en
if " $3" =% ’ chdir ’; return 2; en
el
ec v15
en
return 1
}
on-mailbox-event-FOLDER, on-mailbox-event
Macro† s invoked upon the folder† events “open”, “enter”, “leave”, and “close”, and the newmail† event “newmail” (the colon modifier ‘:N’ addresses new mail when Specifying messages† ), as indicated by the first argument. mailbox-basename† , mailbox-display† , mailbox-resolved† identify the mailbox. Settings are in scope† when the mailbox is current. Not all COMMANDS† are usable within hooks. The specialization is matched against the fully expanded name, without metacharacters; however, if ‘FOLDER’ resides under folder† the usual ‘+’ (Filename transformations† ) is also tried: for example, if folder is “mail” (therefore relative to HOME† ) then /home/usr1/mail/sent will be tried as ‘on-mailbox-event-/home/usr1/mail/sent’ first, followed by ‘on-mailbox-event-+sent’ (and lastly ‘on-mailbox-event’).
Macro† invoked un-scope† d before the main event loop reads an input line. Remarks: the main event loop never ticks in (Send mode), on-compose-enter† can be used instead.
This hook will be called when the program exits, whether via exit† or quit† , or because the send mode is done. Note: this runs very late, without active account† or folder† .
[v15 behavior may differ] Identical to on-compose-cleanup† , but is only triggered by resend† .
[v15 behavior may differ] Identical to on-compose-enter† , but is only triggered by resend† ; currently there is no digmsg† support, for example.
(Boolean) If set, each message feed through the command given for pipe† is followed by a formfeed character ‘\f’.
password-USER@HOST, password-HOST, password
Variable chain that sets a password, which is used in case none has been given in the protocol and account-specific URL; as a last resort S-nail will ask for a password on the user’s terminal if the authentication method requires a password. Specifying passwords in a startup file is generally a security risk; the file should be readable by the invoking user only.
[Obsolete](Boolean) Please use Pipe† instead of pipe† .
Identical to pipe-TYPE/SUBTYPE† except that ‘EXTENSION’ (normalized to lowercase using character mappings of the ASCII charset) denotes a file extension, for example ‘xhtml’. Handlers registered using this method take precedence.
Whenever a ‘TYPE/SUBTYPE’ (case-insensitive, normalized to lowercase using character mappings of the ASCII charset) MIME message part is displayed or quoted, its data is filtered through the given value interpreted as a shell command. Unless noted only copiousoutput† parts (see The Mailcap files† ) are covered, other parts are solely considered by mimeview† .
The value question mark ‘?’ forces plain text interpretation of the part, for example ‘set pipe-application/xml=?’. (mimetype† type-markers achieve the same.) [Option]ally MIME type handlers may be defined via The Mailcap files† . It is indeed also a trigger character to indicate the following flags:
set
pipe-text/html=’?* lynx -stdin -dump
-force_html’
set pipe-X/Y=’?!++=? vim
$MAILX_FILENAME_TEMPORARY’
‘*’
The command output is reintegratable: see copiousoutput† . Implied when using a plain ‘’.
‘#’
Only use this handler for display, not for quoting a message: x-mailx-noquote† .
‘&’
Run the command asynchronously, do not wait for the handler to exit: x-mailx-async† . The standard output of the command will go to /dev/null† .
‘!’
The command must be run on an interactive terminal, the terminal will temporarily be released for it to run: needsterminal† .
‘+’
Request creation of a zero-sized temporary file, the absolute pathname of which will be made accessible via the environment variable MAILX_FILENAME_TEMPORARY† : x-mailx-tmpfile† . If given twice the file will be unlinked automatically: x-mailx-tmpfile-unlink† ; it is an error to use automatic deletion in conjunction with x-mailx-async† .
‘=’
by default part content is passed to the handler via standard input; if set data is written into MAILX_FILENAME_TEMPORARY† (x-mailx-tmpfile-fill† ) instead, the creation of which is implied. Automatic deletion still requires two plus signs ‘++’!
‘t’
Plain text display type-marker (for type-markers: The mime.types files† ). Implies copiousoutput† .
‘h’
[Option] HTML type-marker: display via built-in HTML-to-text filter. Implies copiousoutput† .
‘?’
To avoid ambiguities a second question mark can be used to forcefully terminate interpretation of the remaining characters as flags. (Any character not in this list will have the same effect.)
Some information about the MIME part to be displayed is embedded into the environment of the shell command:
The MIME content-type of the part, if known, the empty string otherwise.
The detected MIME content-type if the carry-around-bit (2) is set in mime-counter-evidence† , identical to MAILX_CONTENT otherwise.
MIME parts of type ‘message/external-body access-type=url’ will store the access URL in this variable, it is empty otherwise. URL targets should not be activated automatically, without supervision.
The pathname, if any is set, the empty string otherwise.
A random string.
If temporary file creation was requested it will contain the absolute pathname of the temporary file.
pop3-auth-USER@HOST, pop3-auth-HOST, pop3-auth
[Option] Variable chain that sets the POP3 authentication method. Supported are the default ‘plain’, ‘oauthbearer’ and ‘xoauth2’ (see the according entries of smtp-config† ), as well as ‘external’ and ‘externanon’ for TLS secured connections which pass a client certificate via tls-config-pairs† . There may be the [option]al method ‘gssapi’. ‘externanon’ does not need any user credentials, ‘external’ and ‘gssapi’ need a user† , the remains also require a password† . Unless pop3-no-apop† is set the ‘plain’ method will [option]ally be replaced with APOP if possible (see there).
pop3-bulk-load-USER@HOST, pop3-bulk-load-HOST, pop3-bulk-load
(Boolean)[Option] When accessing a POP3 server S-nail loads the headers of the messages, and only requests the message bodies on user request. For the POP3 protocol this means that the message headers will be downloaded twice. If this variable is set then S-nail will download only complete messages from the given POP3 server(s) instead.
pop3-keepalive-USER@HOST, pop3-keepalive-HOST, pop3-keepalive
[Option] POP3 servers close the connection after a period of inactivity; the standard requires this to be at least 10 minutes, but practical experience may vary. Setting this variable to a numeric value greater than ‘0’ causes a ‘NOOP’ command to be sent each value seconds if no other operation is performed.
pop3-no-apop-USER@HOST, pop3-no-apop-HOST, pop3-no-apop
(Boolean)[Option] Unless this variable is set the MD5 based ‘APOP’ authentication method will be used instead of a chosen ‘plain’ pop3-auth† when connecting to a POP3 server that advertises support. The advantage of ‘APOP’ is that only a single packet is sent for the user/password tuple. (Originally also that the password is not sent in clear text over the wire, but for one MD5 does not any longer offer sufficient security, and then today transport is almost ever TLS secured.)
pop3-use-starttls-USER@HOST, pop3-use-starttls-HOST, pop3-use-starttls
(Boolean)[Option] Causes S-nail to issue a ‘STLS’ command to make an unencrypted POP3 session TLS encrypted. This functionality is not supported by all servers. Directly using encrypted communication channels should be preferred.
(Boolean) This flag enables POSIX.1-2024 mode, which is a best-effort behavior change towards the POSIX.1-2024 standard. However, as mentioned in A starter† , Shell-style argument quoting† is used instead of the standardized Old-style argument quoting† : this is believed not to be an insurmountable problem if the program is used in a standard-compliant way. The variable as such is automatically squared with the ENVIRONMENT† variable POSIXLY_CORRECT† , changing one will update the other. The following behavior is covered and enforced by this mechanism:
•
In non-interactive mode, any error encountered while loading resource files during program startup will cause a program exit, whereas in interactive mode such errors will stop loading of the currently loaded (stack of) file(s, i.e., recursively). These exits can be circumvented on a per-command base by using ignerr† , one of the Command modifiers† , for each command which shall be allowed to fail.
•
alternates† will replace the list of alternate addresses instead of appending to it.
•
The variable inserting COMMAND ESCAPES† ˜A† , ˜a† , ˜I† and ˜i† will expand embedded character sequences ‘\t’ horizontal tabulator and ‘\n’ line feed. [v15 behavior may differ] For compatibility reasons this step will always be performed.
•
Reading in messages via ˜f† (COMMAND ESCAPES† ) will use the ‘type’ not the ‘forward’ headerpick† selection.
•
Upon changing the active folder† no summary of headers† will be displayed even if header† is set.
•
Setting ignoreeof† implies the behavior described by dot† .
•
The variable keep† is extended to cover any empty mailbox, not only empty primary system mailbox† es: they will be removed when they are left in empty state otherwise.
•
The exit ?† (and error !† ) status of each command replaces that of the former, the last becomes the exit status of the program itself. In POSIX.1-2024 mode the program exit status will instead have bit 2 (value 4) set unless all sent messages were successfully sent out to the mta† ; also see sendwait† .
•
Shell-style field splitting† according to ifs† will follow ksh93 instead of ksh88 behavior as used by the popular bash(1) shell, among others. This only affects the variables *† and @† , and only if ifs† is set to a non-empty string which begins with non-whitespace: in this case a field other than the last one which ends with a non-whitespace character included in ifs† will not generate an extra empty field.
(Boolean) When a MIME message part of type ‘multipart/alternative’ is displayed and it contains a subpart of type ‘text/plain’, other parts are normally discarded. Setting this variable causes all subparts to be displayed, just as if the surrounding part was of type ‘multipart/mixed’.
The string used as a prompt in interactive mode. Whenever the variable is evaluated the value is treated as if specified within dollar-single-quotes (see Shell-style argument quoting† ). This (post-assignment, i.e., second) expansion can be used to embed status information, for example ?† , !† , account† or mailbox-display† .
In order to embed characters which should not be counted when calculating the visual width of the resulting string, enclose the characters of interest in a pair of reverse solidus escaped brackets: ‘\[\E[0m\]’; a slot for coloured prompts is also available with the [option]al command colour† . Prompting may be prevented by setting this to the null string (aka ‘set noprompt’).
This string is used for secondary prompts, but is otherwise identical to prompt† . The default is ‘.. ’.
(Boolean) Reduce user interface chattiness (for expert† s):
•
do not show version† upon startup.
•
minimize / hide technical MIME information of type† etc.
•
do no include informational comments when editing the message draft (˜e† , ˜v† , etc) in Compose mode† with editheaders† set.
If set messages processed by variants of followup† and reply† will start with the original message, lines of which prefixed by indentprefix† , taking into account quote-chars† and quote-fold† . No header fields will be quoted when set without value or for ‘noheading’, for ‘headers’ the ‘type’ headerpick† selection will be included in the quote, in headerorder† ; ‘allbodies’ embeds the (body) contents of all MIME parts, and ‘allheaders’ also includes all header fields. The quoted message will be enclosed by the expansions of quote-inject-head† and quote-inject-tail† . Also see quote-add-cc† , quote-as-attachment† and ˜Q† , one of the COMMAND ESCAPES† .
(Boolean) Whether senders of messages quoted via ˜Q† shall be made members of the carbon copies ‘Cc:’ list.
(Boolean) Add the original message in its entirety as a ‘message/rfc822’ MIME attachment when replying to a message, announced as content-description-quote-attachment† . This works regardless of the setting of quote† .
Can be set to a string consisting of non-whitespace ASCII characters which shall be treated as quotation leaders, the default being ‘>|}:’.
[Option] A more fancy quotation that compresses leading quotation characters (quote-chars† ), and optionally (with arguments) folds overlong lines on top of indentprefix† . (Only a decimal 0 argument is “ignored”.) With arguments, if the value ends with a non-digit, that denotes the line-break indicator; the empty string is used for hyphen-minus ‘-’; moreover one, two or three (space separated) positive numbers are expected, interpreted as maximum (goal) and minimum line lengths, as well as an alternative maximum to be used whenever no better break point (whitespace) can be found (ignored unless it is larger than the minimum and smaller than the maximum). The goal cannot really be smaller than the length of indentprefix† plus some additional pad. For example: ‘set quote-fold="50 20 44 +"’.
quote-inject-head , quote-inject-tail
The strings to put before and after the text of a quote† d message, if non-empty, and respectively. The former defaults to ‘%f wrote:\n\n’. Special format directives will be expanded if possible, and if so configured the output will be folded according to quote-fold† . Format specifiers in the given strings start with a percent sign ‘%’ and expand values of the original message, unless noted otherwise. Note that names and addresses are not subject to the setting of showto† . Valid format specifiers are:
‘%%’
A plain percent sign.
‘%a’
The address(es) of the sender(s).
‘%d’
The date found in the ‘Date:’ header field of the message when datefield† is set (the default), otherwise the date when the message was received. Formatting can be controlled by assigning a strftime(3) format string to datefield† (and datefield-markout-older† ).
‘%f’
The full name(s) (name and address, as given) of the sender(s).
‘%i’
The ‘Message-ID:’.
‘%n’
The real name(s) of the sender(s) if there is one and showname† allows usage, the address(es) otherwise.
‘%r’
The senders real name(s) if there is one, the address(es) otherwise.
(Boolean) Setting this option evaluates the contents of from† (or, if that contains multiple addresses, sender† ) and passes the results onto the used (file-based) MTA as described for the −r† option (empty argument case).
(Boolean) When doing a reply† , the original ‘From:’ and ‘To:’ as well as recipients which possibly came in via ‘Reply-To:’ and ‘Mail-Followup-To:’ are by default merged into the new ‘To:’. If this variable is set a sensitive algorithm tries to place in ‘To:’ only the sender of the message being replied to, others are placed in ‘Cc:’.
Unless this variable is defined, no copies of outgoing mail will be saved. If defined it gives the pathname, subject to the usual Filename transformations† , of a mailbox where all new, replied-to or forwarded messages are saved: when saving to this mailbox fails the message is not sent, but instead save† d to DEAD† . Relative paths are interpreted relative to the current directory (cwd† ) unless, outfolder† forces usage of folder† .
(Boolean) If this variable is set the meaning of record† will be extended to cover messages which target only file and pipe recipients (see expandaddr† ). These address types will not appear in recipient lists unless add-file-recipients is also set.
(Boolean) If this variable is set the meaning of record† will be extended to also cover the resend† and Resend† commands.
(Boolean) If this variable is set S-nail first tries to use the same character set of the original message for replies. If this fails, the mechanism described in Character sets† is evaluated as usual.
Can be set to a comma-separated list of (case-insensitive according to ASCII rules) strings which shall be recognized in addition to the built-in strings as ‘Subject:’ reply message indicators – built-in are ‘Re:’, which is mandated by RFC 5322, as well as the german ‘Aw:’, ‘Antw:’, and the ‘Wg:’ which often has been seen in the wild; I.e., the separating colon has to be specified explicitly.
A list of addresses to put into ‘Reply-To:’ header field; alias† es are expanded instantly with senders kept (metoo† ); all list members are alternates† .
Controls whether a ‘Reply-To:’ header field is honoured when replying to a message via reply† or Lreply† . This is a quadoption† ; if set without a value it defaults to “yes”.
Standards like DKIM and (in conjunction with) DMARC caused many Mailing lists† to use sender address rewriting in the style of ‘Name via List <list@address>’, where the original sender address often being placed in ‘Reply-To:’. If this is set and a ‘Reply-To:’ exists, and consists of only one recipient (!), then that is used in place of the pretended sender. This works independently from reply-to-honour† . The optional value, a comma-separated list of strings, offers more fine-grained control on when swapping shall be used; for now supported is mlist, here swapping occurs if the sender is a mailing-list as defined by mlist† .
(Boolean) Display a so-called ‘From_’ line for messages that are embedded into an envelope mail via the ‘message/rfc822’ MIME mechanism, as is usual for MBOX files (see folder† ).
(Boolean) Enable saving of (partial) messages in DEAD† upon interrupt or delivery error.
The number of lines that represents a “screenful” of lines, used in headers† summary display, from† search† ing, message top† line display and scrolling via z† . If this variable is not set a calculation based upon the detected terminal window size and the baud rate is used: the faster the terminal, the more will be shown. Overall screen dimensions and pager usage is influenced by the environment variables COLUMNS† and LINES† and the variable crt† .
(Boolean) Expand message list specifiers in the form ‘/x:y’ to all messages containing the substring “y” in the header field ‘x’. The string search is case insensitive.
[Option] A comma-separated list of character set names that can be used in outgoing internet mail. The value of the variable charset-8bit† is automatically appended to this list of character sets. If no character set conversion capabilities are compiled into S-nail then the only supported charset is ttycharset† (or ttycharset-detect† ). Also see sendcharsets-else-ttycharset† and refer to the section Character sets† for the complete picture of character set conversion in S-nail.
(Boolean)[Option] If set, but sendcharsets† is not, it is acted as if sendcharsets† had been set to the value of ttycharset† : in effect this passes through message data in the character set of the current locale encoding. For example message text appears as ISO-8859-1 when sent from within a ISO-8859-1 locale, and in UTF-8 when sent from within an UTF-8 locale. Note the charset-8bit† fallback never comes into play as ttycharset† is implicitly assumed to be 8-bit: this might be a problem for scripts which use the suggested ‘LC_ALL=C’ setting, since then ttycharset† is US-ASCII, and should be actively overwritten. A modern, better alternative is ttycharset-detect† .
An address that is put into the ‘Sender:’ field of outgoing messages, quoting the standard RFC 5322: the mailbox of the agent responsible for the actual transmission of the message. For example, if Mary sends a mail for Alice, then Alice should be in ‘From:’ whereas Mary should be present in ‘Sender:’. According to the standard this variable must be set if from† contains multiple addresses. [v15 behavior may differ] Expect automatic management of the from† and sender† relationship: the first address of from† will automatically be used as the sender (this goes in line with what for example the RFC 6376 DKIM standard implicitly performs). alias† es are expanded instantly with senders kept; Contextually this address is a member of alternates† . Also see −r† , r-option-implicit† .
The mta† and command-pipe recipients (see Sending mail, and non-interactive mode† ) are executed asynchronously: only startup errors are detected, not delivery errors; there is no guarantee on when actual execution happens and ends, at which time temporary data(files) cease to exist. Setting this synchronizes execution, with the child process exit status indicating error or success.
Remarks: conflicting POSIX.1-2024 this is built-in set† , and has an optional value, a comma-separated list of case-insensitive subsystems to synchronize: ‘mta’ for mta† delivery, and ‘pcc’ for command-pipe recipients (SHELL† output is not redirected to /dev/null† in synchronous mode).
(Boolean) This setting causes S-nail to start at the last message instead of the first one when opening a mailbox, as well as with from† and headers† .
(Boolean) Show the sender’s real name instead of the email address in the header field summary and in message specifications.
(Boolean) Causes the recipient of the message to be shown in the header field summary if the message was sent by the user.
The value backing ˜A† , one of the COMMAND ESCAPES† . Also see message-inject-tail† , on-compose-embed† .
The value backing ˜a† , one of the COMMAND ESCAPES† . Also see message-inject-tail† , on-compose-embed† .
(Boolean) Discard outgoing messages with an empty body part (ignoring other MIME parts / attachments), successfully. (Also see −E† .)
[Option] Specify the location of trusted CA certificates in PEM (Privacy Enhanced Mail) for the purpose of verification of S/MIME signed messages. tls-ca-dir† documents the necessary preparation steps to use the former. The set of CA certificates which are built into the TLS library can be explicitly turned off by setting smime-ca-no-defaults† , and further fine-tuning is possible via smime-ca-flags† .
[Option] Can be used to fine-tune behavior of the X509 CA certificate storage, and the certificate verification that is used. The actual values and their meanings are documented for tls-ca-flags† .
(Boolean)[Option] Do not load the default CA locations that are built into the used to TLS library to verify S/MIME signed messages.
smime-cipher-USER@HOST, smime-cipher
[Option] Specifies the cipher to use when generating S/MIME encrypted messages (for the specified account). Whereas RFC 5751 as of 2010 mandated a default of ‘aes128’ (AES-128-CBC) we follow OpenSSL 3.5.0 (2025) and default to ‘aes256’ (AES-256-CBC). Possible values are (case-insensitive and) in decreasing cipher strength: ‘aes256’ (AES-256-CBC), ‘aes192’ (AES-192-CBC), ‘aes128’ (AES-128-CBC), ‘des3’ (DES-EDE3-CBC, 168 bits; default if ‘aes128’ is not available) and ‘des’ (DES CBC, 56 bits).
The actually available cipher algorithms depend on the cryptographic library that S-nail uses. [Option] Support for more cipher algorithms may be available through dynamic loading via EVP_get_cipherbyname(3) (OpenSSL) if S-nail has been compiled to support this.
[Option] Specifies a directory that contains files with CRLs in PEM format to use when verifying S/MIME messages.
[Option] Specifies a file that contains a CRL in PEM format to use when verifying S/MIME messages.
[Option] If this variable is set, messages send to the given recipient are encrypted before sending. The value of the variable must be set to the name of a file that contains a certificate in PEM format.
If a message is sent to multiple recipients, each of them for whom a corresponding variable is set will receive an individually encrypted message; other recipients will continue to receive the message in plain text unless the smime-force-encryption† variable is set. It is recommended to sign encrypted messages, i.e., to also set the smime-sign† variable. content-description-smime-message† will be inspected for messages which become encrypted.
(Boolean)[Option] Causes S-nail to refuse sending unencrypted messages.
(Boolean)[Option] S/MIME sign outgoing messages with the user’s (from† ) private key and include the users certificate as a MIME attachment. Signing a message enables a recipient to verify that the sender used a valid certificate, that the email addresses in the certificate match those in the message header and that the message content has not been altered. It does not change the message text, and people will be able to read the message as usual. content-description-smime-signature† will be inspected. Also see smime-sign-cert† , smime-sign-include-certs† and smime-sign-digest† .
smime-sign-cert-USER@HOST, smime-sign-cert
[Option] Points to a file in PEM format. For the purpose of signing and decryption this file needs to contain the user’s private key followed by the certificate.
For message signing ‘USER@HOST’ is always derived from the value of from† (or, if that contains multiple addresses, sender† ). For the purpose of encryption the recipients public encryption key (certificate) is expected; the command certsave† can be used to save certificates of signed messages (the section Signed and encrypted messages with S/MIME† gives some details). This mode of operation is usually driven by the specialized form.
When decrypting messages the account is derived from the recipient fields (‘To:’ and ‘Cc:’) of the message, which are searched for addresses for which such a variable is set. S-nail always uses the first address that matches, so if the same message is sent to more than one of the user addresses using different encryption keys, decryption might fail.
Password-encrypted keys may be used for signing and decryption. Automated password lookup is possible via the “pseudo-hosts” ‘USER@HOST.smime-cert-key’ for the private key, and ‘USER@HOST.smime-cert-cert’ for the certificate stored in the same file. For example, the hypothetical address ‘bob@exam.ple’ could be driven with a private key / certificate pair path defined in smime-sign-cert-bob@exam.ple, and the needed passwords would then be looked up as ‘bob@exam.ple.smime-cert-key’ and ‘bob@exam.ple.smime-cert-cert’. When decrypting the value of from† will be tried as a fallback to provide the necessary ‘USER@HOST’. To include intermediate certificates, use smime-sign-include-certs† . The possible password sources are documented in URL syntax and credential lookup† .
smime-sign-digest-USER@HOST, smime-sign-digest
[Option] Specifies the message digest to use when signing S/MIME messages. Please remember that here ‘USER@HOST’ refers to from† (or even sender† ). The available algorithms depend on the used cryptographic library, but at least one usable built-in algorithm is ensured as a default: here the standard RFC 5751 is violated by using either ‘SHA3-256’, ‘SHA512’ or ‘SHA256’ instead of the mandated ‘SHA1’ due to security concerns if possible. It will be tried to add built-in support for these message digests, with case-insensitive names, in test order: ‘SHA3-512’, ‘SHA3-384’, ‘SHA3-256’, ‘SHA3-224’, as well as the widely available ‘SHA512’, ‘SHA384’, ‘SHA256’, ‘SHA224’, and the proposed insecure ‘SHA1’, finally ‘MD5’. More digests may [option]ally be available through dynamic loading via EVP_get_digestbyname(3). Remarks: this variable is ignored for very old (released before 2010) cryptographic libraries which do not offer the necessary interface: it will be logged if that happened.
smime-sign-include-certs-USER@HOST, smime-sign-include-certs
[Option] If used, this is supposed to a consist of a comma-separated list of files, each of which containing a single certificate in PEM format to be included in the S/MIME message in addition to the smime-sign-cert† certificate. This can be used to include intermediate certificates of the certificate authority, in order to allow the recipient’s S/MIME implementation to perform a verification of the entire certificate chain, starting from a local root certificate, over the intermediate certificates, down to the smime-sign-cert† . Even though top level certificates may also be included in the chain, they will not be used for the verification on the recipient’s side.
For the purpose of the mechanisms involved here, ‘USER@HOST’ refers to the content of the internal variable from† (or, if that contains multiple addresses, sender† ). The pseudo-host ‘USER@HOST.smime-include-certs’ will be used for performing password lookups for these certificates, shall they have been given one, therefore the lookup can be automated via the mechanisms described in URL syntax and credential lookup† .
smtp-auth-USER@HOST, smtp-auth-HOST, smtp-auth
[Option][Obsolete] Use the authentication slots of smtp-config† .
smtp-config-USER@HOST, smtp-config-HOST, smtp-config
[Option] When a SMTP based mta† is contacted a list of supported SMTP service extensions will (optionally) be announced by the server. This comma-separated (case-insensitive) list configures which extensions shall be used, and which of the available ones shall not. Order matters, whitespace is ignored, an optional plus sign ‘+’ prefix enables, a hyphen-minus ‘-’ prefix disables usage of an extension, for example ‘-all, ehlo,+starttls, gssapi’.
all
This special word enables (default) or disables all extensions. Disabling it also disables all the below authentication mechanisms.
ehlo
Service Extensions (RFC 1869) added the notion of extensions to the SMTP protocol; when disabled, all other extensions are also disabled (for auth only the master switch is toggled, not the individual mechanisms), enabling any extension (re-)implies this.
8bitmime
8-bit MIME Transport (RFC 6152) enables usage of the ‘8bit’ mime-encoding† . If disabled or not supported by the server, SMTP will not send a ‘8bit’ message, and optionally save† the text in DEAD† ; as this happens late the message will also have been record† ed.
pipelining
Command Pipelining (RFC 2920) helps saving packet roundtrips by allowing successive commands without waiting for respective server responses.
starttls
Secure SMTP over TLS (Transport Layer Security, RFC 3207) allows upgrading an unencrypted (SMTP not SMTPS) connection to use private, authenticated communication. To improve security and provide a safety measure against man-in-the-middle attacks this is always performed — even if the server does not announce it — unless explicitly turned off. Directly using encrypted transport channels should be preferred, as it saves network traffic.
auth
Authentication (RFC 4954) allows account credentials to be passed. This word disables all authentication mechanisms, but enables only those which can be managed automatically without external help; for example GSSAPI requires an externally granted ticket to exist, and is therefore excluded by the default automatic selection, as is EXTERNAL etc.: these mechanisms have to be enabled explicitly. The default selection depends upon the (im- or explicit) presence of TLS.
If multiple authentication mechanisms are available, an automatic selection of the “best” method is performed, preferring the non-automatic mechanisms. The used list can be fine-tuned, any non-empty list implies auth. For example, ‘smtp-config=-allmechs,gssapi,external,plain’ will favour external over gssapi, and use plain as a last resort only. Beware, in the following example ‘plain’ would still be used as a last ressort, sending credentials in clear (unless the transport is of an encrypted type): ‘smtp-config=-all,,gssapi, plain’. The following mechanisms are known:
allmechs
Special word which covers all authentication methods (where “all” means all for disabling, and all supported ones for enabling).
cram-md5
[Option] Challenge-Response authentication mechanism (CRAM; included in RFC 2195), needs user† and password† .
external
[Option] Included in the simple authentication and security layer (SASL; RFC 4422). Authentication happens through a TLS client certificate (see tls-config-pairs† , Certificate) on the transport layer, therefore not automatic. Needs a user† .
externanon
[Option] Likewise, but an empty user name is passed, as it is expected that the server extracts the name from the certificate. Not compliant with RFC 4422 / RFC 4954, but has been seen in the wild.
gssapi
[Option] The Kerberos V5 ("GSSAPI") mechanism (RFC 4752). Needs an external ticket (to be granted by kinit(1)), therefore not automatic. Needs a user† .
login
The LOGIN mechanism (draft-murchison-sasl-login-00.txt). It requires three packet roundtrips, has been obsoleted by the IETF, and should only be used as a last resort. Needs user† and password† .
oauthbearer
A set of mechanisms for OAuth (RFC 7628). One packet roundtrip. Needs user† and password† . The password is a temporary bearer token instead of the real password, and therefore this mechanism is not automatic; build-oauth-helper† , if installed, may be capable to gain and manage the token, as shown in s-nail-config(7).
plain
The PLAIN mechanism (RFC 4616). One packet roundtrip, needs user† and password† .
xoauth2
A popular slightly different variant of the later standardized oauthbearer.
smtp-from-USER@HOST, smtp-from-HOST, smtp-from
[Option] Dedicated ‘USER@HOST’ information for ‘MAIL FROM:<>’ SMTP mta† commands; alias† es are expanded instantly with senders kept (metoo† ). If unset from† is used, otherwise user† and hostname† .
smtp-hostname-USER@HOST, smtp-hostname-HOST, smtp-hostname
[Option][Obsolete] Use the more powerful successor smtp-from† .
smtp-use-starttls-USER@HOST, smtp-use-starttls-HOST, smtp-use-starttls
(Boolean)[Option][Obsolete] Use smtp-config† . (Forcing TLS has become a default setting.)
[Option] A positive number that defines the timeout to wait for establishing a socket connection before forcing ˆERR† -TIMEDOUT.
socks-proxy-USER@HOST, socks-proxy-HOST, socks-proxy
[Option] If set to the URL of a SOCKS5 server then all network activities are proxied through it, except for the single DNS name lookup necessary to resolve the proxy URL (unnecessary when given an already resolved IP address). It is automatically squared with the environment variable SOCKS5_PROXY† , changing the one will adjust the other. This example creates a local SOCKS5 proxy on port 10000 that forwards to the machine ‘HOST’ (with identity ‘USER’), and from which actual network traffic happens:
$ ssh -D 10000
USER@HOST
$ s-nail -Ssocks-proxy=[socks5://]localhost:10000
# or =localhost:10000; no local DNS: =127.0.0.1:10000
[Option] In order to use any of the spam-related commands (like spamrate† ) the desired spam interface must be defined by setting this variable. Refer to the manual section Handling spam† for the complete picture of spam handling in S-nail. All or none of the following interfaces may be available:
‘spamc’
Interaction with spamc(1) from the spamassassin(1) (SpamAssassin: http://spamassassin.apache.org) suite. Different to the generic filter interface S-nail will automatically add the correct arguments for a given command and has the necessary knowledge to parse the program’s output. A default value for spamc-command† will have been compiled into the S-nail binary if spamc(1) has been found in PATH† during compilation. Shall it be necessary to define a specific connection type (rather than using a configuration file for that), the variable spamc-arguments† can be used as in for example ‘-d server.example.com -p 783’. It is also possible to specify a per-user configuration via spamc-user† . Note that this interface does not inspect the ‘is-spam’ flag of a message for the command spamforget† .
‘filter’
generic spam filter support via freely configurable hooks. This interface is meant for programs like bogofilter(1) and requires according behavior in respect to the hooks’ exit status for at least the command spamrate† (‘0’ meaning a message is spam, ‘1’ for non-spam, ‘2’ for unsure and any other return value indicating a hard error); since the hooks can include shell code snippets diverting behavior can be intercepted as necessary. The hooks are spamfilter-ham† , spamfilter-noham† , spamfilter-nospam† , spamfilter-rate† and spamfilter-spam† ; the manual section Handling spam† contains examples for some programs. The process environment of the hooks will have the variable MAILX_FILENAME_GENERATED† set. Note that spam score support for spamrate† is not supported unless spamfilter-rate-scanscore† variable is set.
[Option] Messages that exceed this size will not be passed through to the configured spam-interface† . If unset or 0, the default of 420000 bytes is used.
[Option] The path to the spamc(1) program for the ‘spamc’ spam-interface† . Note that the path is not expanded, but used “as is”. A fallback path will have been compiled into the S-nail binary if the executable had been found during compilation.
[Option] Even though S-nail deals with most arguments for the ‘spamc’ spam-interface† automatically, it may at least sometimes be desirable to specify connection-related ones via this variable, for example ‘-d server.example.com -p 783’.
[Option] Specify a username for per-user configuration files for the ‘spamc’ spam-interface† . If this is set to the empty string then S-nail will use the name of the current user† .
spamfilter-ham , spamfilter-noham , spamfilter-nospam , spamfilter-rate , spamfilter-spam
[Option] Command and argument hooks for the ‘filter’ spam-interface† . The manual section Handling spam† contains examples for some programs.
[Option] Spam scores are not supported for the ‘filter’ spam-interface† unless set. If the [option]nal regular expression support is available then it will be interpreted as a number, followed by semicolon ‘;’ and an extended regular expression. The first output line of the spamfilter-rate† hook is then evaluated accordingly: upon success the regex group given by the number is interpreted as a floating point scan score. For example ‘-S spamfilter-rate-scanscore="1;ˆ(.+)$"’ simply interprets the entire output line as one.
If only set without an assigned value, then this setting inhibits the generation of the ‘Message-ID:’, ‘Content-ID:’ and ‘User-Agent:’ header fields that include obvious references to S-nail. There are two pitfalls associated with this: First, the message id of outgoing messages is not known anymore. Second, an expert may still use the remaining information in the header to track down the originating mail user agent. If set to the value ‘noagent’, then the mentioned ‘Message-ID:’ and ‘Content-ID:’ suppression does not occur.
(Read-only) The compiled-in path of s-nail.rc† , the system-wide of the Resource files† .
([Option]) This specifies a comma-separated list of Terminal Information Library (libterminfo, −lterminfo) and/or Termcap Access Library (libtermcap, −ltermcap) capabilities (see Terminal control and line editor† , escape commas with reverse solidus ‘\’) to be used to overwrite or define entries. Note: this variable will only be queried once at program startup and can thus only be specified in resource files or on the command line. It will always be inspected, regardless of whether features† denotes termcap/terminfo library support via ‘,+termcap,’.
String capabilities form ‘cap=value’ pairs and are expected unless noted otherwise. Numerics have to be notated as ‘cap#number’ where the number is expected in normal decimal notation. Finally, booleans have no value but are defined or not: undefining booleans is not supported. String capability values will undergo some expansions before use: for one notations like ‘ˆLETTER’ stand for ‘control-LETTER’, and for clarification purposes ‘\E’ can be used to specify ‘escape’ (the control notation ‘ˆ[’ could lead to misreadings when a left bracket follows, which it does for the standard CSI sequence); finally three letter octal sequences, as in ‘\061’, are supported. Here a terminal with 256-colour support, home key and audible bell:
set termcap=’Co#256,home=\E[H,bel=ˆG’
The following terminal capabilities are or may be meaningful for the operation of the built-in line editor MLE, and terminal usage in general:
am
auto_right_margin: boolean which indicates if the right margin needs special treatment; the xenl capability is related, for more see COLUMNS† . This capability is only used when backed by library support.
clear or cl
clear_screen: clear the screen and home cursor. (Will be simulated via ho plus cd.)
colors or Co
max_colors: numeric capability specifying the maximum number of colours. Note that S-nail does not actually care about the terminal beside that, but always emits ANSI / ISO 6429 escape sequences; also see colour† .
cr
carriage_return: move to the first column in the current row. The default built-in fallback is ‘\r’.
cub1 or le
cursor_left: move the cursor left one space (non-destructively). The default built-in fallback is ‘\b’.
cuf1 or nd
cursor_right: move the cursor right one space (non-destructively). The default built-in fallback is ‘\E[C’, which is used by most terminals. Less often occur ‘\EC’ and ‘\EOC’.
ed or cd
clr_eos: clear the screen.
el or ce
clr_eol: clear to the end of line. (Will be simulated via ch plus repetitions of space characters.)
home or ho
cursor_home: home cursor.
hpa or ch
column_address: move the cursor (to the given column parameter) in the current row. (Will be simulated via cr plus nd.)
rmcup or te / smcup or ti
exit_ca_mode and enter_ca_mode, respectively: exit and enter the alternative screen ca-mode (cursor-addressing; fullscreen mode). This must be enabled explicitly by setting termcap-ca-mode† .
smkx or ks / rmkx or ke
keypad_xmit and keypad_local, respectively: enable and disable the keypad. This is always enabled if available, because it seems even keyboards without keypads generate other key codes for, e.g., cursor keys in that case, and only if enabled we see the codes that we are interested in.
xenl or xn
eat_newline_glitch: boolean which indicates whether a newline written in the last column of an auto_right_margin indicating terminal is ignored. With it the full terminal width is available even on autowrap terminals. This will be inspected even without ‘,+termcap,’ features† .
BE, BD, PS, PE
These capabilities yet specific to the Terminal Information Library (libterminfo, −lterminfo) define and control bracketed paste: the former two request the TERM† inal to enable and disable this mode, causing it to embed any pasted clipboard (paste buffer) data in between the latter two. The MLE will use this mode automatically, and bind† mle-be-bd-ps† to PS in order to prevent undesired interpretation of pasted clipboard content. The TERM† inal needs to support this extension.
Many more capabilities which describe key-sequences are documented for bind† .
[Option] Allow usage of the exit_ca_mode and enter_ca_mode (cursor-addressing; fullscreen mode) termcap† abilities in order to enter an alternative exclusive screen; this usually requires special configuration of the PAGER† , also dependent on the value of crt† . If set to a non-empty value the alternative screen is cleared before it is left, as via mle-clear-screen† . Note: this variable will only be queried once at program startup and can thus only be specified in resource files or on the command line.
(Boolean)[Option] Disable any interaction with a terminal control library. If set only some generic fallback built-ins and possibly the content of termcap† describe the terminal. Note: this variable will only be queried once at program startup and can thus only be specified in resource files or on the command line.
tls-ca-dir-USER@HOST, tls-ca-dir-HOST, tls-ca-dir , tls-ca-file-USER@HOST, tls-ca-file-HOST, tls-ca-file
[Option] Directory and file, respectively, for pools of trusted CA certificates in PEM (Privacy Enhanced Mail) format, for the purpose of verification of TLS server certificates. Concurrent use is possible, the file is loaded once needed first, the directory lookup is performed anew as a last resort whenever necessary. The CA certificate pool built into the TLS library can be disabled via tls-ca-no-defaults† , further fine-tuning is possible via tls-ca-flags† . The directory search requires special filename conventions, see SSL_CTX_load_verify_locations(3) and verify(1) (or c_rehash(1)).
tls-ca-flags-USER@HOST, tls-ca-flags-HOST, tls-ca-flags
[Option] Can be used to fine-tune behavior of the X509 CA certificate storage, and the certificate verification that is used (also see tls-verify† ). The value is expected to consist of a comma-separated list of configuration directives, with any intervening whitespace being ignored. The directives directly map to flags that can be passed to X509_STORE_set_flags(3), which are usually defined in a file openssl/x509_vfy.h, and the availability of which depends on the used TLS library version: a directive without mapping is ignored (error log subject to debug† ). Directives currently understood (case-insensitively) include:
no-alt-chains
If the initial chain is not trusted, do not attempt to build an alternative chain. Setting this flag will make OpenSSL certificate verification match that of older OpenSSL versions, before automatic building and checking of alternative chains has been implemented; also see trusted-first.
no-check-time
Do not check certificate/CRL validity against current time.
partial-chain
By default partial, incomplete chains which cannot be verified up to the chain top, a self-signed root certificate, will not verify. With this flag set, a chain succeeds to verify if at least one signing certificate of the chain is in any of the configured trusted stores of CA certificates. The OpenSSL manual page SSL_CTX_load_verify_locations(3) gives some advise how to manage your own trusted store of CA certificates.
strict
Disable workarounds for broken certificates.
trusted-first
Try building a chain using issuers in the trusted store first to avoid problems with server-sent legacy intermediate certificates. Newer versions of OpenSSL support alternative chain checking and enable it by default, resulting in the same behavior; also see no-alt-chains.
tls-ca-no-defaults-USER@HOST, tls-ca-no-defaults-HOST, tls-ca-no-defaults
(Boolean)[Option] Do not load the default CA locations that are built into the used to TLS library to verify TLS server certificates.
[Option] If this variable is set CONF_modules_load_file(3) (if announced via ‘,+modules-load-file,’ in tls-features† ) is used to allow resource file based configuration of the TLS library. This happens once the library is used first, which may also be early during startup (logged with verbose† )! If a non-empty value is given then the given file, after performing Filename transformations† , will be used instead of the TLS libraries global default, and it is an error if the file cannot be loaded. The application name will always be passed as ‘s-nail’. Some TLS libraries support application-specific configuration via resource files loaded like this, see tls-config-module† .
tls-config-module-USER@HOST, tls-config-module-HOST, tls-config-module
[Option] If file based application-specific configuration via tls-config-file† is available, announced as ‘,+ctx-config,’ by tls-features† , indicating availability of SSL_CTX_config(3), then, it becomes possible to use a central TLS configuration file for all programs, including s-nail, for example
# Register a
configuration section for s-nail
s-nail = mailx_master
# The top configuration section creates a relation
# in between dynamic SSL configuration and an actual
# program specific configuration section
[mailx_master]
ssl_conf = mailx_tls_config
# And that program specific configuration section now
# can map diverse tls-config-module names to sections,
# as in: tls-config-module=account_xy
[mailx_tls_config]
account_xy = mailx_account_xy
account_yz = mailx_account_yz
[mailx_account_xy]
MinProtocol = TLSv1.2
Curves=P-521
[mailx_account_yz]
CipherString = TLSv1.2:!aNULL:!eNULL:
MinProtocol = TLSv1.1
Options = Bugs
tls-config-pairs-USER@HOST, tls-config-pairs-HOST, tls-config-pairs
[Option] The value of this variable chain will be interpreted as a comma-separated list of directive/value pairs. Directives and values need to be separated by equals signs ‘=’, any whitespace surrounding pair members is removed. Keys are (usually) case-insensitive. Different to when placing these pairs in a tls-config-module† section of a tls-config-file† , commas ‘,’ need to be escaped with a reverse solidus ‘\’ when included in pairs (‘Options=-Bugs\,KTLS,Certificate=˜/.cert’); also different: if the equals sign ‘=’ is preceded with an asterisk ‘*’ Filename transformations† will be performed on the value; it is an error if these fail. Unless proper support is announced by tls-features† (‘,+conf-ctx,’) only the keys below are supported, otherwise the pairs will be used directly as arguments to the function SSL_CONF_cmd(3).
Certificate
Pathname of a TLS client certificate (chain) required by some servers. Fallback support via SSL_CTX_use_certificate_chain_file(3). Filename transformations† are performed. PrivateKey will be set to the same value if not initialized explicitly. Some services support so-called ‘external’ authentication if a TLS client certificate was successfully presented during connection establishment (“connecting is authenticating”).
CipherString
A list of ciphers for TLS connections, see ciphers(1). By default no list of ciphers is set, resulting in a Protocol-specific list of ciphers (the protocol standards define lists of acceptable ciphers; possibly cramped by the used TLS library). Fallback support via SSL_CTX_set_cipher_list(3).
Ciphersuites
A list of ciphers used for TLSv1.3 connections, see ciphers(1). These will be joined onto the list of ciphers from CipherString. Available if tls-features† announces ‘,+ctx-set-ciphersuites,’, as necessary via SSL_CTX_set_ciphersuites(3).
Curves
A list of supported elliptic curves, if applicable. By default no curves are set. Fallback support via SSL_CTX_set1_curves_list(3), if available.
MaxProtocol, MinProtocol
The maximum and minimum supported TLS versions, respectively. Available if tls-features† announces ‘,+ctx-set-maxmin-proto,’, as necessary via SSL_CTX_set_max_proto_version(3) and SSL_CTX_set_min_proto_version(3); these fallbacks use an internal parser which understands the strings ‘SSLv3’, ‘TLSv1’, ‘TLSv1.1’, ‘TLSv1.2’, ‘TLSv1.3’, and the special value ‘None’, which disables the given limit.
Options
Various flags to set. Fallback via SSL_CTX_set_options(3) and SSL_CTX_clear_options(3): value is a (escaped!) comma-separated list; whitespace is ignored. An option is cleared if the first character is hyphen-minus ‘-’; understood options are ‘Bugs’ and ‘KTLS’ (tls-features† : ‘,+option-ktls,’).
PrivateKey
Pathname of the private key in PEM format of a TLS client certificate. If unset, the value of Certificate is used. Filename transformations† are performed. Fallback via SSL_CTX_use_PrivateKey_file(3).
Protocol
The used TLS protocol. If tls-features† announces ‘,+conf-ctx,’ or ‘ctx-set-maxmin-proto’ then using MaxProtocol and MinProtocol is preferable. Fallback is SSL_CTX_set_options(3), driven via an internal parser which understands the strings ‘SSLv3’, ‘TLSv1’, ‘TLSv1.1’, ‘TLSv1.2’, ‘TLSv1.3’, and the special value ‘ALL’. Multiple protocols may be given as a comma-separated list, any whitespace is ignored, an optional plus sign ‘+’ prefix enables, a hyphen-minus ‘-’ prefix disables a protocol, so that ‘-ALL, TLSv1.2’ enables only the TLSv1.2 protocol.
[Option] Specify a directory / a file, respectively, that contains a CRL in PEM format to use when verifying TLS server certificates.
[Option](Read-only) This expands to a comma-separated list of the TLS library identity and optional features. To ease substring matching the string starts and ends with a comma. Currently supported identities are ‘libressl’ (LibreSSL) , ‘libssl-0x30000’ (OpenSSL v3.0.0 series), ‘libssl-0x10100’ (OpenSSL v1.1.x series) and ‘libssl-0x10000’ (elder OpenSSL series, other clones). Optional features are preceded with a plus sign ‘+’ when available, and with a hyphen-minus ‘-’ otherwise.
Currently known features are ‘conf-ctx’ (tls-config-pairs† ), ‘ctx-config’ (tls-config-module† ), ‘ctx-set-ciphersuites’ (Ciphersuites slot of tls-config-pairs† ), ‘ctx-set-maxmin-proto’ (tls-config-pairs† ), ‘modules-load-file’ (tls-config-file† ), and ‘tls-rand-file’ (tls-rand-file† ).
tls-fingerprint-USER@HOST, tls-fingerprint-HOST, tls-fingerprint
[Option] It is possible to replace the verification of the connection peer certificate against the entire local pool of CAs (for more see Encrypted network communication† ) with the comparison against a precalculated certificate message digest, the so-called fingerprint, to be specified as the used tls-fingerprint-digest† . This fingerprint can for example be calculated with ‘tls† fingerprint HOST’.
tls-fingerprint-digest-USER@HOST, tls-fingerprint-digest-HOST, tls-fingerprint-digest
[Option] Specifies the message digest to use when creating a tls-fingerprint† . The available algorithms depend on the used cryptographic library, but at least one usable built-in algorithm is ensured as a default, either ‘SHA3-256’, ‘BLAKE2s256’, ‘SHA256’ or ‘SHA1’. It will be tried to add built-in support for these message digests, with case-insensitive names, in test order: ‘SHA3-512’, ‘SHA3-384’, ‘SHA3-256’, ‘SHA3-224’, the at times unsupported ‘BLAKE2b512’ and ‘BLAKE2s256’, as well as the widely available ‘SHA512’, ‘SHA384’, ‘SHA256’, ‘SHA224’, and the proposed insecure ‘SHA1’, finally ‘MD5’. More digests may [option]ally be available through dynamic loading via EVP_get_digestbyname(3).
[Option] If tls-features† announces ‘,+tls-rand-file,’ then this will be queried to find a file with random entropy data which can be used to seed the P(seudo)R(andom)N(umber)G(enerator), see RAND_load_file(3). The default pathname (RAND_file_name(3), normally ˜/.rnd† ) will be used if this variable is not set or empty, or if the Filename transformations† fail. Shall seeding the PRNG have been successful, RAND_write_file(3) will be called to update the entropy. Remarks: libraries which do not announce this feature seed the PRNG by other means.
tls-verify-USER@HOST, tls-verify-HOST, tls-verify
[Option] Variable chain that sets the action to be performed if an error occurs during TLS server certificate validation against the specified or default trust stores tls-ca-dir† , tls-ca-file† , or the TLS library built-in defaults (unless usage disallowed via tls-ca-no-defaults† ), and as fine-tuned via tls-ca-flags† . Valid (case-insensitive) values are ‘strict’ (fail and close connection immediately), ‘ask’ (ask whether to continue on standard input), ‘warn’ (show a warning and continue), ‘ignore’ (do not perform validation). The default is ‘ask’.
If defined, gives the number of lines of a message to be displayed with the command top† ; if unset, the first five lines are printed, if set to 0 the variable screen† is inspected. If the value is negative then its absolute value will be used for unsigned right shifting (see vexpr† ) the screen† height.
(Boolean) If set then the top† command series will strip adjacent empty lines and quotations.
The character set of the terminal S-nail operates on, and the one and only supported character set that S-nail can use if no character set conversion capabilities have been compiled into it, in which case it defaults to ISO-8859-1. Otherwise it defaults to UTF-8. Sufficient locale support provided the default will be preferably deduced from the locale environment if that is set (for example LC_CTYPE† , see there for more); runtime locale changes will be reflected by ttycharset except during the program startup phase and if −S† had been used to freeze the given value. Refer to the section Character sets† for the complete picture about character sets.
By default any input text data is expected to be in ttycharset† (Character sets† ). If set active UTF-8 classification is performed: nothing changes for 7-bit, but if 8-bit input is valid UTF-8 that character set is assumed; if set with value non-UTF-8 8-bit input uses it instead.
$ echo
$’\u263A’ > uni.txt
$ echo $’Hey \u263A’ | \
LC_ALL=C s-nail -:/ -Smta=test \
-S ttycharset-detect=LATIN1 \
-a uni.txt -s Kn$’\366’del bob@exam.ple
(Boolean) A special multiplex variable that disables all variables and settings which result in behavior that interferes with running S-nail in script(1); it sets colour-disable† , line-editor-disable† and (before startup completed only) termcap-disable† . Unsetting it does not restore the former state of the covered settings.
For a safe-by-default policy the process file mode creation mask umask(2) will be set to ‘0077’ on program startup after the resource files have been loaded, and unless this variable is set. By assigning this an empty value the active setting will not be changed, otherwise the given value will be made the new file mode creation mask. Child processes inherit the file mode creation mask of their parent.
Variable chain that sets a global fallback user name, used in case none has been given in the protocol and account-specific URL. This variable defaults to the name of the user who runs S-nail.
Enable upward compatibility with S-nail version 15.0 in respect to which configuration options are available and how they are handled. If set to a non-empty value (the default) the command modifier wysh† is implied and thus enforces Shell-style argument quoting† over Old-style argument quoting† for all commands which support both.
Verbose mode enables logging of informational context messages. Historically a (Boolean) variable, this can either be set multiple times (what the command line option −v† uses), or be assigned a numeric value in order to increase verbosity. Assigning the value 0 disables verbosity and thus (almost) equals unset† . The maximum number is 3. Also see debug† .
version , version-date , version-hexnum , version-major , version-minor , version-update
(Read-only) Variables with specific version† information. The first is the complete version identification, by convention not containing hyphen-minus ‘-’ for mainline releases; “alpha”, “beta” or similar may follow thereafter otherwise. The second is the release date in ISO 8601 notation without time. The third is a 32-bit hexadecimal number with the upper 8 bits storing the major, followed by the minor and update version numbers which occupy 12 bits each. The latter three variables contain only decimal digits: the major, minor and update version numbers. An example to create the hexadecimal variant:
vexpr pbase 16
\
$(( (version-major << 24) | (version-minor <<
12) | \
version-update ))
#-> ...
#-> 0xE009019
If this variable is set messages modified using the edit† or visual† commands are written back to the current mailbox when it is quit; it is only honoured for writable mailboxes in MBOX format, though. Note that the editor will be pointed to the raw message content in that case, i.e., neither MIME decoding nor decryption will have been performed, and proper ‘From_’ quoting of newly added or edited content is also left as an exercise to the user.
The term “environment variable” should be considered an indication that these variables are either standardized as vivid parts of process environments, or are commonly found in there. There is a strict separation in between INTERNAL VARIABLES† and the process environment that is inherited from the SHELL† upon program startup (and passed along to subprocesses). The separation can be resolved, meaning variables can transparently be used like INTERNAL VARIABLES† : when set† or unset† the process environment is updated automatically, for example; this includes change scope† coverage. (Removal requires sufficient system support: available in BSD since 1987, standardized since Y2K.) The list of resolved built-in variables follows, the command environ† can be used to resolve other variables. varshow† , without arguments and in verbose† mode, lists the resolve state.
The user’s preferred width in column positions for the terminal screen. Queried and used once on program startup in interactive or batch (−#† ) mode on a (pseudo-) terminal. Actively managed (‘SIGWINCH’) for child processes and the MLE† (Terminal control and line editor† ) in interactive mode thereafter. Non-interactive mode always uses, and the fallback default is a compile-time constant, by default 80 columns. If in batch mode (on (pseudo-) terminal) COLUMNS and LINES† are both set but not both are usable (empty, not a number, or 0) at program startup, then the real terminal screen size will be (tried to be) determined once. (Normally the SHELL† manages these variables, and unsets them for pipe specifications etc.) Also see cols† .
The name of the mailbox folder† to use for saving aborted messages if save† is set; this defaults to ˜/dead.letter. If the variable debug† is set no output will be generated, otherwise the contents of the file will be replaced. Except shell globs Filename transformations† (also see folder† ) will be performed.
Pathname of the text editor to use for the edit† command and ˜e† (see COMMAND ESCAPES† ); VISUAL† is used for a more display oriented editor.
The user’s home directory. This variable is only used when it resides in the process environment. The calling user’s home directory will be used instead if this directory does not exist, is not accessible or cannot be read; it will always be used for the root user. (No test for being writable is performed to allow usage by non-privileged users within read-only jails, but dependent on settings this directory is a default write target for, for example, DEAD† , MBOX† and more.)
[Option] The (names in lookup order of the) locale(7) (and / or see setlocale(3)) which indicates the used Character sets† . Runtime changes trigger automatic updates of the entire locale system, which includes updating ttycharset† (except during startup if the variable has been frozen via −S† ).
The user’s preferred number of lines for the terminal screen. The behavior is as described for COLUMNS† , yet the compile-time constant used in non-interactive mode and as a fallback defaults to 24 (lines).
Pathname of the directory lister to use in the folders† command when operating on local mailboxes. Default is ls(1) (path search through SHELL† ).
Upon startup S-nail will actively ensure that this variable refers to the name of the user who runs S-nail, in order to be able to pass a verified name to any newly created child process.
Is used as the user’s primary system mailbox† unless inbox† is set. If the environmental fallback is also not set, a built-in compile-time default is used. This is assumed to be an absolute pathname.
[Option] Override the default path search of The Mailcap files† : any existing file therein will be loaded in sequence, appending any content to the list of MIME type handler directives. The RFC 1524 standard imposed default value is assigned otherwise: ‘˜/.mailcap:/etc/mailcap:/usr/etc/mailcap: /usr/local/etc/mailcap’. (The default value is a compile-time [option].)
Is used as a startup file instead of ˜/.mailrc† if set. In order to avoid side-effects from configuration files scripts should either set this variable to /dev/null† or the −:† command line option should be used.
If this variable is set then reading of s-nail.rc† (aka system-mailrc† ) at startup is inhibited, i.e., the same effect is achieved as if S-nail had been started up with the option −:† (and according argument) or −n† . This variable is only used when it resides in the process environment.
The name of the user’s secondary mailbox† file. A logical subset of the special Filename transformations† (also see folder† ) are supported. The default is ˜/mbox† . Traditionally this MBOX is used as the file to save messages from the primary system mailbox† that have been read. Also see Message states† .
[Option] This variable overrides the default location of the user’s ˜/.netrc† file.
Pathname of the paging program backing more† and crt† induced pager usage. The default paginator is more(1) (path search through SHELL† ).
The content of this variable is inspected: if it contains “less” then a non-existing environment variable LESS is temporarily set to the portable ‘RIFE’ (the latter two excessively), whereas for “lv” LV will temporarily be set to ‘-c’. Also see Coloured display† and colour-disable† .
A colon-separated list of directories that is searched by the shell when looking for commands, for example ‘/bin:/usr/bin:/usr/local/bin’.
This environment entry is automatically squared with posix† .
The POSIX.1-2024 compatible sh(1) to use for the commands !† , pipe† , and shell† , the COMMAND ESCAPES† ˜!† and ˜|† , and when starting subprocesses. A compile-time default shell is used if this variable is not defined. ‘$SHELL -c -- ’echo du’’ is required to print ‘du’ (POSIX issue #1440).
This environment entry is automatically squared with socks-proxy† .
Specifies a time in seconds since the Unix epoch (1970-01-01) to be used in place of the current time. If set upon program startup a reproducible operation mode (https://reproducible-builds.org) which uses deterministic random numbers, a special fixated pseudo LOGNAME† , log-prefix† and a bit more is used. This is meant for development and software packager testing purposes. [v15 behavior may differ] Currently an invalid setting is only ignored, rather than causing a program abortion.
$ SOURCE_DATE_EPOCH=‘date +%s‘ TZ=UTC s-nail
[Option] The terminal type for which output is to be prepared. For extended colour and font control refer to Coloured display† , and for terminal management in general to Terminal control and line editor† .
Except for the root user this variable defines the directory for temporary files to be used instead of /tmp (or the given compile-time constant) if set, existent, accessible as well as read- and writable. This variable is only used when it resides in the process environment, but S-nail will ensure at startup that this environment variable is updated to contain a usable temporary directory.
Defines the timezone(3) for local standard time and date(1). (System-dependent, often there is also a /etc/localtime.)
Identical to LOGNAME† (see there), but this variable is not standardized, should therefore not be used, and is only corrected if already set.
Pathname of the text editor to use for the visual† command and ˜v† (see COMMAND ESCAPES† ); EDITOR† is used for a less display oriented editor.
FILES
˜/.mailcap ,
/etc/mailcap
[Option] Personal and system-wide MIME type handler definition files, see The Mailcap files† . (The shown names are part of the RFC 1524 standard search path MAILCAPS† .)
User-specific and system-wide files giving initial commands, the Resource files† . (The used pathnames come from MAILRC and system-mailrc† , respectively.)
The default value for MBOX† .
˜/.mime.types , /etc/mime.types
Personal and system-wide MIME types, see The mime.types files† .
[Option] The default location of the user’s .netrc file – the section The .netrc file† documents the file format. The used path can be set via NETRC† .
The data sink null(4).
[Option] Possible location for persistent random entropy seed storage, see tls-rand-file† .
Resource
files
Upon startup several resource files are read, in order:
System-wide resource file (system-mailrc† ). Reading of this file can be suppressed, either by using the −:† (and according argument) or −n† command line options, or by setting the ENVIRONMENT† variable MAILX_NO_SYSTEM_RC† .
File giving initial commands. A different file can be chosen by setting the ENVIRONMENT† variable MAILRC† . Reading of this file can be suppressed with the −:† command line option.
mailx-extra-rc†
Defines a startup file to be read after all other resource files. It can be used to specify settings that are not understood by other mailx(1) implementations, for example.
The content of these files is interpreted as for COMMANDS† , with the exception that history† is never tracked. Errors while loading these files are subject to the settings of errexit† and posix† . More files with syntactically equal content can be source† ed. The following, saved in a file, would be an exemplary content:
# This line is
a comment command. And y\
es, it is really continued here.
set debug \
verbose=2
set editheaders
The
mime.types files
As stated in HTML mail and MIME
attachments† MIME (Multipurpose
Internet Mail Extensions) media types needs to be registered
in order to be able to classify message and attachment
content. One source for them are mime.types files,
the loading of which can be controlled by setting the
variable
mimetypes-load-control† .
Another is the command
mimetype† , which also
offers access to the MIME type cache. mime.types
files have the following syntax:
type/subtype
extension [extension ...]
# For example: text/html html htm
where ‘type/subtype’ denotes the MIME media type, as standardized in RFC 2046: ‘type’ is used to declare the general type of data, while the ‘subtype’ specifies a specific format for that type of data. One or multiple filename ‘extension’s, separated by whitespace, and specified without leading dot ‘.’, can be bound to the media type format. Comments may be introduced anywhere on a line with a number sign ‘#’, causing the remaining line to be discarded.
An extended (non-portable) syntax prepending an optional ‘type-marker’ to the above is offered by the command mimetype† , and is supported also in especially crafted files which can be loaded via the alternative value syntax of mimetypes-load-control† :
[?type-marker ]type/subtype extension [extension ...]
The ‘type-marker’ is interpreted as a comma-separated list of a type and flags. The following mutually exclusive types are supported:
t
Treat this media type as plain text; effectively optional unless the type-marker contains flags (see below). This is implied for any ‘text/’ subtype.
h
Treat message parts with this content as HTML tagsoup. If the [option]al HTML-tagsoup-to-text converter is not available treat the content as plain text instead.
H
Likewise h, but instead of falling back to plain text require an explicit MIME content handler.
q
If no handler can be found a text message is displayed which says so. This can be annoying, for example signatures serve a contextual purpose, their content is of no use by itself. This marker will avoid displaying the text message.
The type-marker can include flags. If it does, the type is no longer optional, but must be given explicitly, if so desired:
only-handler, o
The given MIME media type shall only be matched when looking for handlers (for type† etc), not when classifying attachments (−a† ) and other content to create messages. IANA MIME registry standards do not know about “extension chains”: ‘tar.gz’ is thus a gzip(1) compressed file. Because MIME media type handlers, like those defined in The Mailcap files† , match media types, non-standardized fictional types like ‘x-tar-gz’ are used in the wild as MIME environments become configured. The sane solution of recursively unpacking until no more MIME media type unpacking is possible is not available. This flag may be used alongside other type-markers, and is especially useful in conjunction with mime-counter-evidence† . Mutual exclusive with send-text.
?only-handler application/x-tar-xz txz tar.xz
|
application/x-xz |
xz txz |
send-text, s
When attaching (see −a† ) data matching this MIME type, enforce a reclassification as ‘text/plain’; Makes sense only for non-‘text/’ types (and is ignored if binary data is encountered). Because Character sets† are only honoured for ‘text/’ attachments, this can support perceiving MUAs to save data in a localized character set. Mutual exclusive with only-handler.
When classifying, all registered MIME types are searched, and the longest matching extension will be used. A filename of only an ‘extension’ will match, for example README is matched by ‘mimetype ? text/unix-readme NEWS README’, empty filenames are not matched, so for example .x.tar does not match ‘application/x-fun x.tar’ but rather ‘application/x-tar tar’.
Further reading: for sending messages: mimetype† , (mime-allow-text-controls† ), mimetypes-load-control† . For reading etc. messages: HTML mail and MIME attachments† , The Mailcap files† , mimetype† , mime-counter-evidence† , mimetypes-load-control† , pipe-TYPE/SUBTYPE† , pipe-EXTENSION† .
The Mailcap
files
[Option] RFC 1524 defines a “User Agent Configuration
Mechanism” to be used to inform mail user agent
programs about the locally installed facilities for handling
various data formats, i.e., about commands and how they can
be used to display, edit et cetera MIME part contents, as
well as a default path search that includes multiple
possible locations of resource files, and the
MAILCAPS† environment variable to
overwrite that. Handlers found from doing the path search
will be cached, the command
mailcap† operates on that
cache, and the variable
mailcap-disable† will
suppress automatic loading, and usage of any mailcap
handlers. HTML mail and MIME
attachments† gives a general
overview of how MIME types are handled.
“Mailcap” files consist of a set of newline separated entries. Comment lines start with a number sign ‘#’ (in the first column!) and are ignored. Empty lines are ignored. All other lines are interpreted as mailcap entries. An entry definition may be split over multiple lines by placing the reverse solidus character ‘\’ last in all but the final line. The standard does not specify how leading whitespace of successive lines is to be treated, therefore they are retained.
“Mailcap” entries consist of a number of semicolon ‘;’ separated fields. The first two fields are mandatory and must occur in the specified order, the remaining fields are optional and may appear in any order. Leading and trailing whitespace of field content is ignored (removed). The reverse solidus ‘\’ character can be used to escape any following character including semicolon and itself in the content of the second field, and in value parts of any optional key/value field.
The first field defines the MIME ‘TYPE/SUBTYPE’ the entry is about to handle (case-insensitively). If the subtype is specified as an asterisk ‘*’ the entry is meant to match all subtypes of the named type, e.g., ‘audio/*’ would match any audio type. The second field is the view shell command used to display MIME parts of the given type.
Data consuming shell commands will be fed message (MIME part) data on standard input unless one or more instances of the (unquoted) string ‘%s’ are used: these formats will be replaced with a temporary file(name) that has been prefilled with the parts data, as if the x-mailx-tmpfile† and x-mailx-tmpfile-fill† flags had been set; any given ‘%s’ format is replaced with a properly shell quoted pathname; unless x-mailx-async† was requested the x-mailx-tmpfile-unlink† flag is also implied, and the temporary file is removed. Data producing shell commands are expected to generata data on their standard output unless the ‘%s’ format is used, or the x-mailx-async† flag is set.
Optional fields define single-word flags (case-insensitive), or key / value pairs consisting of a case-insensitive keyword, an equals sign ‘=’, and a shell command; whitespace surrounding the equals sign is removed. Optional fields include the following:
compose
A program that can be used to compose a new body or body part in the given format. (Currently unused.)
composetyped
Similar to the compose field, but is to be used when the composing program needs to specify the ‘Content-type:’ header field to be applied to the composed data. (Currently unused.)
A flag field which indicates that the output of the view command is integrable into S-nails normal visual display. It is mutually exclusive with needsterminal† .
description
A textual description that describes this type of data. The text may optionally be enclosed within double quotation marks ‘"’.
edit
A program that can be used to edit a body or body part in the given format. (Currently unused.)
nametemplate
This field specifies a filename format for the ‘%s’ format used in the shell command fields, in which ‘%s’ will be replaced by a random string. (The filename is also stored in and passed to subprocesses via MAILX_FILENAME_TEMPORARY† .) The standard says this is “only expected to be relevant in environments where filename extensions are meaningful”, and so this field is ignored unless the ‘%s’ is a prefix, optionally followed by (ASCII) alphabetic and numeric characters, the underscore and the period. For example, to specify that a JPG file is to be passed to an image viewer with a name ending in ‘.jpg’, ‘nametemplate=%s.jpg’ can be used.
This flag field indicates that the given shell command must be run on an interactive terminal. S-nail will temporarily release the terminal to the given command in interactive mode, in non-interactive mode this entry will be entirely ignored; this flag implies x-mailx-noquote† .
A program that can be used to print a message or body part in the given format. (Currently unused.)
test
Specifies a program to be run to test some condition, for example, the machine architecture, or the window system in use, to determine whether or not this mailcap entry applies. If the test fails, a subsequent mailcap entry should be sought; also see x-mailx-test-once† . Standard I/O of the test program is redirected from and to /dev/null† , and the format ‘%s’ is not supported (the data does not yet exist).
textualnewlines
A flag field which indicates that this type of data is line-oriented and that, if encoded in ‘base64’, all newlines should be converted to canonical form (CRLF) before encoding, and will be in that form after decoding. (Currently unused.)
x11-bitmap
Names a file, in X11 bitmap (xbm) format, which points to an appropriate icon to be used to visually denote the presence of this kind of data. This field is not used by S-nail.
Extension flag field that denotes that the given view command shall be executed asynchronously, without blocking S-nail. Cannot be used in conjunction with needsterminal† ; the standard output of the command will go to /dev/null† .
An extension flag field that indicates that even a copiousoutput† view command shall not be used when quote† ing messages, as it would by default.
Extension flag which denotes whether the given test command shall be evaluated once only with its exit status being cached. This is handy if some global unchanging condition is to be queried, like “running under the X Window System”.
Extension flag field that requests creation of a zero-sized temporary file, the name of which is to be placed in the environment variable MAILX_FILENAME_TEMPORARY† . It is an error to use this flag with commands that include a ‘%s’ format (because that is implemented by means of this temporary file).
Normally the MIME part content is passed to the handler via standard input; if this flag is set then the data will instead be written into the implied x-mailx-tmpfile† . In order to cause deletion of the temporary file you will have to set x-mailx-tmpfile-unlink† explicitly! It is an error to use this flag with commands that include a ‘%s’ format.
Extension flag field that requests that the temporary file shall be deleted automatically when the command loop is entered again at latest. It is an error to use this flag with commands that include a ‘%s’ format, or in conjunction with x-mailx-async† . x-mailx-tmpfile† is implied.
An extension flag that indicates that this handler shall only be used as a last resort, when no other source (see HTML mail and MIME attachments† ) provides a MIME handler.
An extension that enforces that this handler is not used at all.
The standard includes the possibility to define any number of additional fields, prefixed by ‘x-’. Flag fields apply to the entire “Mailcap” entry — in some unusual cases, this may not be desirable, but differentiation can be accomplished via separate entries, taking advantage of the fact that subsequent entries are searched if an earlier one does not provide enough information. For example, if a view command needs to specify the needsterminal† flag, but the compose command shall not, the following will help out the latter:
application/postscript;
ps-to-terminal %s; needsterminal
application/postscript; ps-to-terminal %s; compose=idraw
%s
In value parts of command fields any occurrence of the format string ‘%t’ will be replaced by the ‘TYPE/SUBTYPE’ specification. Any named parameter from a messages’ ‘Content-type:’ field may be embedded into the command line using the format ‘%{’ followed by the parameter name and the closing curly bracket ‘}’ character. The entire parameter should appear as a single command line argument, regardless of embedded spaces, shell quoting will be performed by the RFC 1524 processor, thus:
# Message
Content-type: multipart/mixed; boundary=42
# Mailcap file
multipart/*; /usr/local/bin/showmulti \
%t %{boundary} ; composetyped = /usr/local/bin/makemulti
# Executed
shell command
/usr/local/bin/showmulti multipart/mixed 42
Note that S-nail does not support handlers for multipart MIME parts as shown in this example (as of today). It does not support the additional formats ‘%n’ and ‘%F’. An example file, also showing how to properly deal with the expansion of ‘%s’, which includes any quotes that are necessary to make it a valid shell argument by itself and thus will cause undesired behavior when placed in additional user-provided quotes:
# Comment line
text/richtext; richtext %s; copiousoutput
text/x-perl; perl -cWT %s; nametemplate = %s.pl
# Exit
EX_TEMPFAIL=75 on signal
application/pdf; \
infile=%s\; \
trap "rm -f ${infile}" EXIT\; \
trap "exit 75" INT QUIT TERM\; \
mupdf "${infile}"; \
test = [ -n "${DISPLAY}" ]; \
nametemplate = %s.pdf; x-mailx-async
application/pdf; pdftotext -layout - -; copiousoutput
application/*;
echo "This is \\"%t\\" but \
is 50 \% Greek to me" \; < %s head -c 512 | cat
-vet; \
copiousoutput; x-mailx-noquote; x-mailx-last-resort
Further reading: HTML mail and MIME attachments† , The mime.types files† , mimetype† , MAILCAPS† , mime-counter-evidence† , pipe-TYPE/SUBTYPE† , pipe-EXTENSION† .
The .netrc
file
User credentials for machine accounts (see URL syntax and
credential lookup† ) can be
placed in the .netrc file, which will be loaded and
cached when requested by
netrc-lookup† . The default
location ˜/.netrc† may
be overridden by the NETRC†
environment variable. As long as syntax constraints are
honoured the file source may be replaced with the output of
the shell command set in
netrc-pipe† , to load an
encrypted file, for example. The cache can be managed with
the command netrc† .
The file consists of space, tabulator or newline separated tokens. This parser implements a superset of the original BSD syntax, but users should nonetheless be aware of portability glitches, shall their .netrc be usable across multiple programs and platforms:
•
BSD only supports double quotation marks, for example ‘password "pass with spaces"’.
•
BSD (only?) supports escaping of single characters via a reverse solidus (a space could be escaped via ‘\ ’), in- as well as outside of a quoted string. This method is assumed to be present, and will actively be used to quote double quotation marks ‘"’ and reverse solidus ‘\’ characters inside the login and password tokens, for example for display purposes.
•
BSD does not require a final quotation mark of the last user input token.
•
The original BSD (Berknet) parser also supported a format which allowed tokens to be separated with commas – whereas at least Hewlett-Packard still seems to support this syntax, this parser does not!
•
As a non-portable extension some widely-used programs support shell-style comments: if an input line starts, after any amount of whitespace, with a number sign ‘#’, then the rest of the line is ignored.
•
Whereas other programs may require that the .netrc file is accessible by only the user if it contains a password token for any other login than “anonymous”, this parser will always require these strict permissions.
Of the following list of supported tokens this parser uses (and caches) machine, login and password. An existing default entry will not be used.
machine name
The hostname of the entries’ machine, lowercase-normalized before use. Any further file content, until either end-of-file or the occurrence of another machine or a default first-class token is bound (only related) to the machine name.
As an extension that should not be the cause of any worries this parser supports a single wildcard prefix for name:
machine
*.example.com login USER password PASS
machine pop3.example.com login USER password PASS
machine smtp.example.com login USER password PASS
which would match ‘xy.example.com’ as well as ‘pop3.example.com’, but neither ‘example.com’ nor ‘local.smtp.example.com’. In the example neither ‘pop3.example.com’ nor ‘smtp.example.com’ will be matched by the wildcard, since the exact matches take precedence (it is however faster to specify it the other way around).
default
This is the same as machine except that it is a fallback entry that is used shall none of the specified machines match; only one default token may be specified, and it must be the last first-class token.
login name
The user name on the remote machine.
password string
The user’s password on the remote machine.
account string
Supply an additional account password. This is merely for FTP purposes.
macdef name
Define a macro. A macro is defined with the specified name; it is formed from all lines beginning with the next line and continuing until a blank line is (consecutive newline characters are) encountered. (Note that macdef entries cannot be utilized by multiple machines, too, but must be defined following the machine they are intended to be used with.) If a macro named init exists, it is automatically run as the last step of the login process. This is merely for FTP purposes.
S/MIME step by
step
[Option] The first thing that is needed for Signed and
encrypted messages with S/MIME†
is a personal certificate, and a private key. The
certificate contains public information, in particular a
name and email address(es), and the public key that can be
used by others to encrypt messages for the certificate
holder (the owner of the private key), and to
verify† signed messages
generated with that certificate(’s private key).
Whereas the certificate is included in each signed message,
the private key must be kept secret. It is used to decrypt
messages that were previously encrypted with the public key,
and to sign messages.
For personal use it is recommended to get a S/MIME certificate from one of the major CAs on the Internet. Many CAs offer such certificates for free. Usually offered is a combined certificate and private key in PKCS#12 format which S-nail does not accept directly. To convert it to PEM format, the following shell command can be used; Read on for how to use these PEM files.
$ openssl
pkcs12 -in cert.p12 -out certpem.pem -clcerts -nodes
$ # Alternatively
$ openssl pkcs12 -in cert.p12 -out cert.pem -clcerts -nokeys
$ openssl pkcs12 -in cert.p12 -out key.pem -nocerts
-nodes
There is also https://www.CAcert.org which issues client and server certificates to members of their community for free; their root certificate (https://www.cacert.org/certs/root.crt) is often not in the default set of trusted CA root certificates, though, which means their root certificate has to be downloaded separately, and needs to be part of the S/MIME certificate validation chain by including it in smime-ca-dir† or as a vivid member of the smime-ca-file† . But let us take a step-by-step tour on how to setup S/MIME with a certificate from CAcert.org despite this situation!
First of all you will have to become a member of the CAcert.org community, simply by registering yourself via the web interface. Once you are, create and verify all email addresses you want to be able to create signed and encrypted messages for/with using the corresponding entries of the web interface. Now ready to create S/MIME certificates, so let us create a new “client certificate”, ensure to include all email addresses that should be covered by the certificate in the following web form, and also to use your name as the “common name”.
Create a private key and a certificate request on your local computer (see the manual pages of the used commands for more in-depth knowledge on what the used arguments etc. do):
$ openssl req -noenc -newkey rsa:4096 -keyout key.pem -out creq.pem
Afterwards copy-and-paste the content of “creq.pem” into the certificate-request (CSR) field of the web form on the CAcert.org website (you may need to unfold some “advanced options” to see the corresponding text field). This last step will ensure that your private key (which never left your box) and the certificate belong together (through the public key that will find its way into the certificate via the certificate-request). You are now ready and can create your CAcert certified certificate. Download and store or copy-and-paste it as “pub.crt”.
Yay. In order to use your new S/MIME setup a combined private key/public key (certificate) file has to be created:
$ cat key.pem pub.crt > ME@HERE.com.paired
This is the file S-nail will work with. If you have created your private key with a passphrase then S-nail will ask you for it whenever a message is signed or decrypted, unless this operation has been automated as described in Signed and encrypted messages with S/MIME† . Set the following variables to henceforth use S/MIME (setting smime-ca-file† is of interest for verification only):
set
smime-ca-file=ALL-TRUSTED-ROOT-CERTS-HERE \
smime-sign-cert=ME@HERE.com.paired \
smime-sign-digest=SHA512 \
smime-sign from=myname@my.host
Using CRLs
with S/MIME or TLS
[Option] Certification authorities (CAs) issue certificate
revocation lists (CRLs) on a regular basis. These lists
contain the serial numbers of certificates that have been
declared invalid after they have been issued. Such usually
happens because the private key for the certificate has been
compromised, because the owner of the certificate has left
the organization that is mentioned in the certificate, etc.
To seriously use S/MIME or TLS verification, an up-to-date
CRL is required for each trusted CA. There is otherwise no
method to distinguish between valid and invalidated
certificates. S-nail currently offers no mechanism to fetch
CRLs, nor to access them on the Internet, so they have to be
retrieved by some external mechanism.
S-nail accepts CRLs in PEM format only; CRLs in DER format must be converted, like, e.g.:
$ openssl crl −inform DER −in crl.der −out crl.pem
To tell S-nail about the CRLs, a directory that contains all CRL files (and no other files) must be created. The smime-crl-dir† or tls-crl-dir† variables, respectively, must then be set to point to that directory. After that, S-nail requires a CRL to be present for each CA that is used to verify a certificate.
In general it is a good idea to turn on debug† (−d† ) and / or verbose† (−v† , twice) if something does not work well. Very often a diagnostic message can be produced that leads to the problems’ solution.
S-nail
shortly hangs on startup
This can have two reasons, one is the necessity to wait for
a file lock and cannot be helped, the other being that
S-nail calls the function uname(2) in order to query the
nodename of the box (sometimes the real one is needed
instead of the one represented by the internal variable
hostname† ). One may have
varying success by ensuring that the real hostname and
‘localhost’ have entries in /etc/hosts,
or, more generally, that the name service is properly setup
– and does hostname(1) return the expected value? Does
this local hostname have a domain suffix? RFC 6762
standardized the link-local top-level domain
‘.local’, try again after adding an (additional)
entry with this extension.
Not
"defunctional", but the editor key does not
work
Maybe a sequence is shadowed; setting
debug† or maximum
verbose† causes a
bind† tree dump after
(re-)build (upon startup or after modifying bindings).
Or the terminal library (see Terminal control and line editor† , bind† , termcap† ) reports different codes than TERM† generates, causing dysfunctional bindings because of mismatches. (One common source of this is that the — possibly even non-existing — keypad is not turned on, and the resulting layout reports codes for the normal keyboard keys.) The expected code sequences are shown by bind† in verbose† mode, the MLE† loggs the generated ones if debug† is set in conjunction with maximum verbose† . After detecting the correct codes these can be placed in termcap† . Here a hypothetic HOME key example (with redundancy removed):
set verbose;
bind*
#-> # 1B 5B=[ 31=1 3B=; 32=2 48=H
#-> bind base :khome mle-go-home
set verbose=3 debug
#<- ..pressing HOME key
#-> s-nail: \x1B/?
#-> s-nail: \x5B/[
#-> s-nail: \x48/H
#..
set noverbose nodebug termcap=’khome=\E[H’;
bind*
#-> # 1B 5B=[ 48=H
#-> bind base :khome mle-go-home
Can S-nail
git-send-email?
Yes. Put (at least parts of) the following in your
˜/.gitconfig:
[sendemail]
smtpserver = /usr/bin/s-nail
smtpserveroption = -˜:/
#smtpserveroption = -˜A THE-ACCOUNT-YOU-NEED
smtpserveroption = -Smta=test:///tmp/xxx
smtpserveroption = -t
smtpserveroption = -Sexpandaddr
suppresscc = all
suppressfrom = false
# need! (-t not yet MIME message aware)
assume8bitEncoding = UTF-8
transferEncoding = 8bit
xmailer = false
#to = /tmp/OUT
confirm = always
chainreplyto = true
multiedit = false
thread = true
quiet = true
annotate = true
Newer git(1) versions (v2.33.0) added the option sendmailCmd. Patches can also be send directly, for example:
$ git
format-patch -M --stdout HEADˆ |
s-nail -A the-account-you-need -t RECIPIENT
How to handle
stale dotlock files
folder† sometimes fails to
open MBOX mail files because creation of dotlock
files† is impossible due to
existing but unowned lock files. S-nail does not offer an
option to deal with those files, because it is considered a
site policy what counts as unowned, and what not. The site
policy is usually defined by administrator(s), and expressed
in the configuration of a locally installed MTA (for example
postfix(1): ‘stale_lock_time=500s’).
$ </dev/null s-nail -s ’MTA: be no frog, handle lock’ $LOGNAME
By sending a mail to yourself the local MTA can use its normal queue mechanism to try the delivery multiple times, finally decide a lock file has become stale, and remove it.
How to
loop
Unfortunately loop control structures are not yet supported.
One can make use of manual tail-call
xcall† with a callback to
(uncomfortably) work around this until they are available,
for example:
\define foreach_call {
|
\if $# -le 1; \retu; \en |
||
|
\call "$1" "$2" |
||
|
\local se f="$1" |
||
|
\shift 2 |
||
|
\xcall foreach_call "$f" "$@" |
}
commandalias foreach_call \\call foreach_call
define e {
echo "$@"
}
foreach_call e hello world
[Option]ally there is IMAP client support available. This part of the program is obsolete and will vanish in v15 with the large MIME and I/O layer rewrite, because it uses old-style blocking I/O and makes excessive use of signal based long code jumps. Support can hopefully be readded later based on a new-style I/O, with SysV signal handling. In fact the IMAP support had already been removed from the codebase, but was reinstantiated on user demand: in effect the IMAP code is at the level of S-nail v14.8.16 (with imapcodec† being the sole exception), and should be treated with some care.
IMAP uses the ‘imap://’ and ‘imaps://’ protocol prefixes, and an IMAP-based folder† may be used. IMAP URLs (paths) undergo inspections and possible transformations before use (and the command imapcodec† can be used to manually apply them to any given argument). Hierarchy delimiters are normalized, a step which is configurable via the imap-delim† variable chain, but defaults to the first seen delimiter otherwise. S-nail supports internationalised IMAP names, and en- and decodes the names from and to the ttycharset† as necessary and possible. If a mailbox name is expanded (see Filename transformations† ) to an IMAP mailbox, all names that begin with ‘+’ then refer to IMAP mailboxes below the folder† target box, while mailbox names prefixed by ‘@’ refer to folders below the hierarchy base, so the following will list all folders below the current one when in an IMAP mailbox: ‘folders @’.
Note: some IMAP servers do not accept the creation of mailboxes in the hierarchy base, but require that they are created as subfolders of ‘INBOX’ – with such servers a mailbox name of the form
imaps://me@imap.myisp.example/INBOX.
should be used (the last character is the server’s hierarchy delimiter). The following IMAP-specific commands exist:
Only applicable to cached IMAP mailboxes; takes a message list and reads the specified messages into the IMAP cache.
If operating in disconnected mode on an IMAP mailbox, switch to online mode and connect to the mail server while retaining the mailbox status. See the description of the disconnected† variable for more information.
If operating in online mode on an IMAP mailbox, switch to disconnected mode while retaining the mailbox status. See the description of the disconnected† variable for more. A list of messages may optionally be given as argument; the respective messages are then read into the cache before the connection is closed, thus ‘disco *’ makes the entire mailbox available for disconnected use.
Sends command strings directly to the current IMAP server. S-nail operates always in IMAP ‘selected state’ on the current mailbox; commands that change this will produce undesirable results and should be avoided. Useful IMAP commands are:
create
Takes the name of an IMAP mailbox as an argument and creates it.
getquotaroot
(RFC 2087) Takes the name of an IMAP mailbox as an argument and prints the quotas that apply to the mailbox. Not all IMAP servers support this command.
namespace
(RFC 2342) Takes no arguments and prints the Personal Namespaces, the Other User’s Namespaces and the Shared Namespaces. Each namespace type is printed in parentheses; if there are multiple namespaces of the same type, inner parentheses separate them. For each namespace a prefix and a hierarchy separator is listed. Not all IMAP servers support this command.
Perform IMAP path transformations. Supports >† (see Command modifiers† ). The first argument specifies the operation: e[ncode] normalizes hierarchy delimiters (see imap-delim† ) and converts the strings from the locale ttycharset† to the internationalized variant used by IMAP, d[ecode] performs the reverse operation. Encoding will honour the (global) value of imap-delim† .
The following IMAP-specific internal variables exist:
(Boolean) When an IMAP mailbox is selected and this variable is set, no connection to the server is initiated. Instead, data is obtained from the local cache (see imap-cache† ). Mailboxes that are not present in the cache and messages that have not yet entirely been fetched from the server are not available; to fetch all messages in a mailbox at once, the command ‘copy * /dev/null’ can be used while still in connected mode. Changes that are made to IMAP mailboxes in disconnected mode are queued and committed later when a connection to that server is made. This procedure is not completely reliable since it cannot be guaranteed that the IMAP unique identifiers (UIDs) on the server still match the ones in the cache at that time. Data is saved to DEAD† when this problem occurs.
disconnected-USER@HOST
The specified account is handled as described for the disconnected† variable above, but other accounts are not affected.
imap-auth-USER@HOST, imap-auth
Sets the IMAP authentication method. Supported are the default ‘login’, ‘plain’, ‘oauthbearer’ and ‘xoauth2’ (see the according entries of smtp-config† ), ‘external’ and ‘externanon’ (for TLS secured connections which pass a client certificate via tls-config-pairs† ), as well as the [option]al ‘cram-md5’ and ‘gssapi’. All methods need a user† and a password† except ‘gssapi’ and ‘external’, which only need the former. ‘externanon’ only uses data from the client certificate.
Enables caching of IMAP mailboxes. The value of this variable must point to a directory that is either existent or can be created by S-nail. All contents of the cache can be deleted by S-nail at any time; it is not safe to make assumptions about them.
imap-delim-USER@HOST, imap-delim-HOST, imap-delim
The hierarchy separator used by the IMAP server. Whenever an IMAP path is specified it will undergo normalization. One of the normalization steps is the squeezing and adjustment of hierarchy separators. If this variable is set, any occurrence of any character of the given value that exists in the path will be replaced by the first member of the value; an empty value will cause the default to be used, it is ‘/.’. If not set, we will reuse the first hierarchy separator character that is discovered in a user-given mailbox name.
imap-keepalive-USER@HOST, imap-keepalive-HOST, imap-keepalive
IMAP servers may close the connection after a period of inactivity; the standard requires this to be at least 30 minutes, but practical experience may vary. Setting this variable to a numeric ‘value’ greater than 0 causes a ‘NOOP’ command to be sent each ‘value’ seconds if no other operation is performed.
When retrieving the list of folders on an IMAP server, the folders† command stops after it has reached a certain depth to avoid possible infinite loops. The value of this variable sets the maximum depth allowed. The default is 2. If the folder separator on the current IMAP server is a slash ‘/’, this variable has no effect and the folders† command does not descend to subfolders.
imap-use-starttls-USER@HOST, imap-use-starttls-HOST, imap-use-starttls
Causes S-nail to issue a ‘STARTTLS’ command to make an unencrypted IMAP session TLS encrypted. This functionality is not supported by all servers, and is not used if the session is already encrypted by the IMAPS method. Directly using encrypted communication channels should be preferred.
bogofilter(1), gpg(1), more(1), newaliases(1), openssl(1), sendmail(1), sh(1), spamassassin(1), iconv(3), setlocale(3), aliases(5), termcap(5), terminfo(5), locale(7), mailaddr(7), s-nail-config(7), re_format(7) (or regex(7)), mailwrapper(8), sendmail(8)
M. Douglas McIlroy writes in his article “A Research UNIX Reader: Annotated Excerpts from the Programmer’s Manual, 1971-1986” that a mail(1) command already appeared in First Edition UNIX in 1971:
Electronic mail was there from the start. Never satisfied with its exact behavior, everybody touched it at one time or another: to assure the safety of simultaneous access, to improve privacy, to survive crashes, to exploit uucp, to screen out foreign freeloaders, or whatever. Not until v7 did the interface change (Thompson). Later, as mail became global in its reach, Dave Presotto took charge and brought order to communications with a grab-bag of external networks (v8).
BSD Mail, in large parts compatible with UNIX mail, was written in 1978 by Kurt Shoens and developed as part of the BSD UNIX distribution until 1995. This manual page is derived from “The Mail Reference Manual” that Kurt Shoens wrote for Mail 1.3, included in 3BSD in 1980. The common UNIX and BSD denominator became standardized as mailx(1) in the X/Open Portability Guide Issue 2 (January 1987). After the rise of Open Source BSD variants Mail saw continuous development in the individual code forks, noticeably by Christos Zoulas in NetBSD. Based upon this Nail, later Heirloom Mailx, was developed by Gunnar Ritter in the years 2000 until 2008. Since 2012 S-nail is maintained by Steffen Nurpmeso.
Electronic mail exchange in general is a concept even older. The earliest well documented electronic mail system was part of the Compatible Time Sharing System (CTSS) at MIT, its MAIL command had been proposed in a staff planning memo at the end of 1964 and was implemented in mid-1965 when Tom Van Vleck and Noel Morris wrote the necessary code. Similar communication programs were built for other timesharing systems. One of the most ambitious and influential was Murray Turoff’s EMISARI. Created in 1971 for the United States Office of Emergency Preparedness, EMISARI combined private electronic messages with a chat system, public postings, voting, and a user directory.
During the 1960s it was common to connect a large number of terminals to a single, central computer. Connecting two computers together was relatively unusual. This began to change with the development of the ARPANET, the ancestor of today’s Internet. In 1971 Ray Tomlinson adapted the SNDMSG program, originally developed for the University of California at Berkeley timesharing system, to give it the ability to transmit a message across the network into the mailbox of a user on a different computer. For the first time it was necessary to specify the recipient’s computer as well as an account name. Tomlinson decided that the underused commercial at ‘@’ would work to separate the two.
Sending a message across the network was originally treated as a special instance of transmitting a file, and so MAIL and MLFL commands were introduced with RFC 385 as an extension to the file transfer protocol FTP of RFC 354, both in 1972. Until early 1973 many discussions and meetings around FTP occurred, and whereas RFC 475 paved a way towards standardization of mail via FTP, RFC 524 proposed a specialized mail protocol, an opinion that was officially picked up by the FTP RFC 542. Still, for many years, ARPANET mail was sent via FTP.
Because it was not always clear when or where a message had come from, RFC 561 in 1973 aimed to formalize electronic mail headers, including “from”, “date”, and “subject”. In 1975 RFC 680 described fields to help with the transmission of messages to multiple users, including “to”, “cc”, and “bcc”. In 1977 these features and others went from best practices to a binding standard in RFC 733. In September 1980, with RFC 772, the M(ail) T(ransfer) P(rotocol) was introduced, which had “strong similarities to portions of the File Transfer Protocol”. RFC 821 in August 1982 then introduced the refined S(imple) M(ail) T(ransfer) P(rotocol) in use, and usable, almost 42 years later, accompanied by RFC 822 that moved from “ARPA network text” to “internet text message”. Queen Elizabeth II of England became the first head of state to send electronic mail on March 26 1976 while ceremonially opening a building in the British Royal Signals and Radar Establishment (RSRE) in Malvern.
Kurt Shoens, Edward Wang, Keith Bostic, Christos Zoulas, Gunnar Ritter. S-nail is developed by Steffen Nurpmeso <s-mailx@lists.sdaoden.eu>.
[v15 behavior may differ] Interrupting an operation via SIGINT aka ‘control-C’ from anywhere else but a command prompt is very problematic and likely to leave the program in an undefined state: many library functions cannot deal with the siglongjmp(3) that this software (still) performs; even though efforts have been taken to address this, no sooner but in v15 it will have been worked out: interruptions have not been disabled in order to allow forceful breakage of hanging network connections, for example (all this is unrelated to ignore† ).
The SMTP and POP3 protocol support of S-nail is very basic. Also, if it fails to contact its upstream SMTP server, it will not make further attempts to transfer the message at a later time (setting save† and sendwait† may be useful). If this is a concern, it might be better to set up a local SMTP server that is capable of message queuing.
When a network-based mailbox is open, directly changing to another network-based mailbox of a different protocol (i.e., from POP3 to IMAP or vice versa) will cause a “deadlock”.
After deleting some message of a POP3 mailbox the header summary falsely claims that there are no messages to display, one needs to perform a scroll or dot movement to restore proper state.
Please report bugs to the contact-mail† address, for example from within s-nail: ‘? eval† mail† $contact-mail’. Including the verbose† output of the command version† may be helpful:
set escape=!
verbose; >xy version; unset verbose;\
eval mail "$contact-mail"
Bug subject
!I xy
!.
Information on the web at ‘$ s-nail -X ’echo $contact-web† ; x’’.
Copyright (c) 1997 - 2024, Steffen Nurpmeso <steffen@sdaoden.eu>
@(#)site/code-nail-alpha.html-w42 1.1 2026-04-08T15:55:01+0000