Ubuntu Manpage: mailx - process messages

NAME

       mailx - process messages

SYNOPSIS

   Send Mode
              mailx [-s subject] address...

   Receive Mode
              mailx -e

              mailx [-HiNn][-F][-u user]

              mailx -f[-HiNn][-F][file]

DESCRIPTION

The mailx utility provides a message sending and receiving facility. It has two major modes, selected by
the options used: Send Mode and Receive Mode.

On systems that do not support the User Portability Utilities option, an application using mailx shall
have the ability to send messages in an unspecified manner (Send Mode). Unless the first character of one
or more lines is tilde ( '~' ), all characters in the input message shall appear in the delivered
message, but additional characters may be inserted in the message before it is retrieved.

On systems supporting the User Portability Utilities option, mail-receiving capabilities and other
interactive features, Receive Mode, described below, also shall be enabled.

Send Mode
Send Mode can be used by applications or users to send messages from the text in standard input.

Receive Mode
Receive Mode is more oriented towards interactive users. Mail can be read and sent in this interactive
mode.

When reading mail, mailx provides commands to facilitate saving, deleting, and responding to messages.
When sending mail, mailx allows editing, reviewing, and other modification of the message as it is
entered.

Incoming mail shall be stored in one or more unspecified locations for each user, collectively called the
system mailbox for that user. When mailx is invoked in Receive Mode, the system mailbox shall be the
default place to find new mail. As messages are read, they shall be marked to be moved to a secondary
file for storage, unless specific action is taken. This secondary file is called the mbox and is normally
located in the directory referred to by the HOME environment variable (see MBOX in the ENVIRONMENT
VARIABLES section for a description of this file). Messages shall remain in this file until explicitly
removed. When the -f option is used to read mail messages from secondary files, messages shall be
retained in those files unless specifically removed. All three of these locations-system mailbox, mbox,
and secondary file-are referred to in this section as simply "mailboxes", unless more specific
identification is required.

OPTIONS

The mailx utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2,
Utility Syntax Guidelines.

The following options shall be supported. (Only the -s subject option shall be required on all systems.
The other options are required only on systems supporting the User Portability Utilities option.)

-e Test for the presence of mail in the system mailbox. The mailx utility shall write nothing and
exit with a successful return code if there is mail to read.

-f Read messages from the file named by the file operand instead of the system mailbox. (See also
folder.) If no file operand is specified, read messages from mbox instead of the system mailbox.

-F Record the message in a file named after the first recipient. The name is the login-name portion
of the address found first on the To: line in the mail header. Overrides the record variable, if
set (see Internal Variables in mailx .)

-H Write a header summary only.

-i Ignore interrupts. (See also ignore.)

-n Do not initialize from the system default start-up file. See the EXTENDED DESCRIPTION section.

-N Do not write an initial header summary.

-s subject
Set the Subject header field to subject. All characters in the subject string shall appear in the
delivered message. The results are unspecified if subject is longer than {LINE_MAX} - 10 bytes or
contains a <newline>.

-u user
Read the system mailbox of the login name user. This shall only be successful if the invoking user
has the appropriate privileges to read the system mailbox of that user.

OPERANDS

       The following operands shall be supported:

       address
              Addressee of message. When -n is specified and no  user  start-up  files  are  accessed  (see  the
              EXTENDED  DESCRIPTION section), the user or application shall ensure this is an address to pass to
              the mail delivery system. Any system or user start-up files may enable aliases  (see  alias  under
              Commands  in  mailx ) that may modify the form of address before it is passed to the mail delivery
              system.

       file   A pathname of a file to be read instead of the system mailbox when -f is specified. The meaning of
              the file option-argument shall be affected by the contents of the folder  internal  variable;  see
              Internal Variables in mailx .

STDIN

       When  mailx  is invoked in Send Mode (the first synopsis line), standard input shall be the message to be
       delivered to the specified addresses. When in Receive Mode, user commands shall be accepted  from  stdin.
       If  the User Portability Utilities option is not supported, standard input lines beginning with a tilde (
       '~' ) character produce unspecified results.

       If the User Portability Utilities option is supported, then in both  Send  and  Receive  Modes,  standard
       input  lines  beginning  with  the  escape  character  (usually tilde ( '~' )) shall affect processing as
       described in Command Escapes in mailx .

INPUT FILES

       When mailx is used as described by this volume of IEEE Std 1003.1-2001, the file option-argument (see the
       -f option) and the mbox shall be text files containing mail  messages,  formatted  as  described  in  the
       OUTPUT FILES section. The nature of the system mailbox is unspecified; it need not be a file.

ENVIRONMENT VARIABLES

The following environment variables shall affect the execution of mailx:

DEAD Determine the pathname of the file in which to save partial messages in case of interrupts or
delivery errors. The default shall be dead.letter in the directory named by the HOME variable. The
behavior of mailx in saving partial messages is unspecified if the User Portability Utilities
option is not supported and DEAD is not defined with the value /dev/null.

EDITOR Determine the name of a utility to invoke when the edit (see Commands in mailx ) or ~e (see
Command Escapes in mailx ) command is used. The default editor is unspecified. On XSI-conformant
systems it is ed. The effects of this variable are unspecified if the User Portability Utilities
option is not supported.

HOME Determine the pathname of the user's home directory.

LANG Provide a default value for the internationalization variables that are unset or null. (See the
Base Definitions volume of IEEE Std 1003.1-2001, Section 8.2, Internationalization Variables for
the precedence of internationalization variables used to determine the values of locale
categories.)

LC_ALL If set to a non-empty string value, override the values of all the other internationalization
variables.

LC_CTYPE
Determine the locale for the interpretation of sequences of bytes of text data as characters (for
example, single-byte as opposed to multi-byte characters in arguments and input files) and the
handling of case-insensitive address and header-field comparisons.

LC_TIME
Determine the format and contents of the date and time strings written by mailx.

LC_MESSAGES
Determine the locale that should be used to affect the format and contents of diagnostic messages
written to standard error and informative messages written to standard output.

LISTER Determine a string representing the command for writing the contents of the folder directory to
standard output when the folders command is given (see folders in Commands in mailx ). Any string
acceptable as a command_string operand to the sh -c command shall be valid. If this variable is
null or not set, the output command shall be ls. The effects of this variable are unspecified if
the User Portability Utilities option is not supported.

MAILRC Determine the pathname of the start-up file. The default shall be .mailrc in the directory
referred to by the HOME environment variable. The behavior of mailx is unspecified if the User
Portability Utilities option is not supported and MAILRC is not defined with the value /dev/null.

MBOX Determine a pathname of the file to save messages from the system mailbox that have been read. The
exit command shall override this function, as shall saving the message explicitly in another file.
The default shall be mbox in the directory named by the HOME variable. The effects of this
variable are unspecified if the User Portability Utilities option is not supported.

NLSPATH
Determine the location of message catalogs for the processing of LC_MESSAGES .

PAGER Determine a string representing an output filtering or pagination command for writing the output
to the terminal. Any string acceptable as a command_string operand to the sh -c command shall be
valid. When standard output is a terminal device, the message output shall be piped through the
command if the mailx internal variable crt is set to a value less the number of lines in the
message; see Internal Variables in mailx . If the PAGER variable is null or not set, the paginator
shall be either more or another paginator utility documented in the system documentation. The
effects of this variable are unspecified if the User Portability Utilities option is not
supported.

SHELL Determine the name of a preferred command interpreter. The default shall be sh. The effects of
this variable are unspecified if the User Portability Utilities option is not supported.

TERM If the internal variable screen is not specified, determine the name of the terminal type to
indicate in an unspecified manner the number of lines in a screenful of headers. If TERM is not
set or is set to null, an unspecified default terminal type shall be used and the value of a
screenful is unspecified. The effects of this variable are unspecified if the User Portability
Utilities option is not supported.

TZ This variable may determine the timezone used to calculate date and time strings written by mailx.
If TZ is unset or null, an unspecified default timezone shall be used.

VISUAL Determine a pathname of a utility to invoke when the visual command (see Commands in mailx ) or ~v
command-escape (see Command Escapes in mailx ) is used. If this variable is null or not set, the
full-screen editor shall be vi. The effects of this variable are unspecified if the User
Portability Utilities option is not supported.

ASYNCHRONOUS EVENTS

When mailx is in Send Mode and standard input is not a terminal, it shall take the standard action for
all signals.

In Receive Mode, or in Send Mode when standard input is a terminal, if a SIGINT signal is received:

1. If in command mode, the current command, if there is one, shall be aborted, and a command-mode prompt
shall be written.

2. If in input mode:

a. If ignore is set, mailx shall write "@\n" , discard the current input line, and continue
processing, bypassing the message-abort mechanism described in item 2b.

b. If the interrupt was received while sending mail, either when in Receive Mode or in Send Mode, a
message shall be written, and another subsequent interrupt, with no other intervening characters
typed, shall be required to abort the mail message. If in Receive Mode and another interrupt is
received, a command-mode prompt shall be written. If in Send Mode and another interrupt is
received, mailx shall terminate with a non-zero status.

In both cases listed in item b, if the message is not empty:

i. If save is enabled and the file named by DEAD can be created, the message shall be
written to the file named by DEAD . If the file exists, the message shall be written to
replace the contents of the file.

ii. If save is not enabled, or the file named by DEAD cannot be created, the message shall
not be saved.

The mailx utility shall take the standard action for all other signals.

STDOUT

       In  command  and  input  modes,  all output, including prompts and messages, shall be written to standard
       output.

STDERR

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES

       Various mailx commands and command escapes can create or add to files,  including  the  mbox,  the  dead-
       letter   file,   and   secondary   mailboxes.  When  mailx  is  used  as  described  in  this  volume  of
       IEEE Std 1003.1-2001, these files shall  be  text  files,  formatted  as  follows:  line  beginning  with
       From<space>
       [one or more header-lines; see Commands in mailx ]
        empty line
        [zero or more body lines
       empty line]
       [line beginning with From<space>...]

       where  each  message begins with the From <space> line shown, preceded by the beginning of the file or an
       empty line. (The From <space> line is considered to be part of the message header, but  not  one  of  the
       header-lines referred to in Commands in mailx ; thus, it shall not be affected by the discard, ignore, or
       retain  commands.)  The formats of the remainder of the From <space> line and any additional header lines
       are unspecified, except that none shall be empty. The format of a message body line is also  unspecified,
       except  that  no  line following an empty line shall start with From <space>; mailx shall modify any such
       user-entered message body lines (following an empty line and beginning with From <space>) by  adding  one
       or  more  characters  to precede the 'F' ; it may add these characters to From <space> lines that are not
       preceded by an empty line.

       When a message from the system mailbox or entered by the user is not a text file, it  is  implementation-
       defined how such a message is stored in files written by mailx.

EXTENDED DESCRIPTION

The entire EXTENDED DESCRIPTION section shall apply only to implementations supporting the User
Portability Utilities option.

The mailx utility cannot guarantee support for all character encodings in all circumstances. For example,
inter-system mail may be restricted to 7-bit data by the underlying network, 8-bit data need not be
portable to non-internationalized systems, and so on. Under these circumstances, it is recommended that
only characters defined in the ISO/IEC 646:1991 standard International Reference Version (equivalent to
ASCII) 7-bit range of characters be used.

When mailx is invoked using one of the Receive Mode synopsis forms, it shall write a page of header-
summary lines (if -N was not specified and there are messages, see below), followed by a prompt
indicating that mailx can accept regular commands (see Commands in mailx ); this is termed command mode.
The page of header-summary lines shall contain the first new message if there are new messages, or the
first unread message if there are unread messages, or the first message. When mailx is invoked using the
Send Mode synopsis and standard input is a terminal, if no subject is specified on the command line and
the asksub variable is set, a prompt for the subject shall be written. At this point, mailx shall be in
input mode. This input mode shall also be entered when using one of the Receive Mode synopsis forms and a
reply or new message is composed using the reply, Reply, followup, Followup, or mail commands and
standard input is a terminal. When the message is typed and the end of the message is encountered, the
message shall be passed to the mail delivery software. Commands can be entered by beginning a line with
the escape character (by default, tilde ( '~' )) followed by a single command letter and optional
arguments. See Commands in mailx for a summary of these commands. It is unspecified what effect these
commands will have if standard input is not a terminal when a message is entered using either the Send
Mode synopsis, or the Read Mode commands reply, Reply, followup, Followup, or mail.

Note: For notational convenience, this section uses the default escape character, tilde, in all
references and examples.

At any time, the behavior of mailx shall be governed by a set of environmental and internal variables.
These are flags and valued parameters that can be set and cleared via the mailx set and unset commands.

Regular commands are of the form:

[command] [msglist] [argument ...]

If no command is specified in command mode, next shall be assumed. In input mode, commands shall be
recognized by the escape character, and lines not treated as commands shall be taken as input for the
message.

In command mode, each message shall be assigned a sequential number, starting with 1.

All messages have a state that shall affect how they are displayed in the header summary and how they are
retained or deleted upon termination of mailx. There is at any time the notion of a current message,
which shall be marked by a '>' at the beginning of a line in the header summary. When mailx is invoked
using one of the Receive Mode synopsis forms, the current message shall be the first new message, if
there is a new message, or the first unread message if there is an unread message, or the first message
if there are any messages, or unspecified if there are no messages in the mailbox. Each command that
takes an optional list of messages (msglist) or an optional single message (message) on which to operate
shall leave the current message set to the highest-numbered message of the messages specified, unless the
command deletes messages, in which case the current message shall be set to the first undeleted message
(that is, a message not in the deleted state) after the highest-numbered message deleted by the command,
if one exists, or the first undeleted message before the highest-numbered message deleted by the command,
if one exists, or to an unspecified value if there are no remaining undeleted messages. All messages
shall be in one of the following states:

new The message is present in the system mailbox and has not been viewed by the user or moved to any
other state. Messages in state new when mailx quits shall be retained in the system mailbox.

unread The message has been present in the system mailbox for more than one invocation of mailx and has
not been viewed by the user or moved to any other state. Messages in state unread when mailx quits
shall be retained in the system mailbox.

read The message has been processed by one of the following commands: ~f, ~m, ~F, ~M, copy, mbox, next,
pipe, print, Print, top, type, Type, undelete. The delete, dp, and dt commands may also cause the
next message to be marked as read, depending on the value of the autoprint variable. Messages
that are in the system mailbox and in state read when mailx quits shall be saved in the mbox,
unless the internal variable hold was set. Messages that are in the mbox or in a secondary mailbox
and in state read when mailx quits shall be retained in their current location.

deleted
The message has been processed by one of the following commands: delete, dp, dt. Messages in state
deleted when mailx quits shall be deleted. Deleted messages shall be ignored until mailx quits or
changes mailboxes or they are specified to the undelete command; for example, the message
specification / string shall only search the subject lines of messages that have not yet been
deleted, unless the command operating on the list of messages is undelete. No deleted message or
deleted message header shall be displayed by any mailx command other than undelete.

preserved
The message has been processed by a preserve command. When mailx quits, the message shall be
retained in its current location.

saved The message has been processed by one of the following commands: save or write. If the current
mailbox is the system mailbox, and the internal variable keepsave is set, messages in the state
saved shall be saved to the file designated by the MBOX variable (see the ENVIRONMENT VARIABLES
section). If the current mailbox is the system mailbox, messages in the state saved shall be
deleted from the current mailbox, when the quit or file command is used to exit the current
mailbox.

The header-summary line for each message shall indicate the state of the message.

Many commands take an optional list of messages ( msglist) on which to operate, which defaults to the
current message. A msglist is a list of message specifications separated by <blank>s, which can include:

n Message number n.

+ The next undeleted message, or the next deleted message for the undelete command.

- The next previous undeleted message, or the next previous deleted message for the undelete
command.

. The current message.

^ The first undeleted message, or the first deleted message for the undelete command.

$ The last message.

* All messages.

n-m An inclusive range of message numbers.

address
All messages from address; any address as shown in a header summary shall be matchable in this
form.

/string
All messages with string in the subject line (case ignored).

:c All messages of type c, where c shall be one of:

d
Deleted messages.

n
New messages.

o
Old messages (any not in state read or new).

r
Read messages.

u
Unread messages.

Other commands take an optional message ( message) on which to operate, which defaults to the current
message. All of the forms allowed for msglist are also allowed for message, but if more than one message
is specified, only the first shall be operated on.

Other arguments are usually arbitrary strings whose usage depends on the command involved.

Start-Up in mailx
At start-up time, mailx shall take the following steps in sequence:

1. Establish all variables at their stated default values.

2. Process command line options, overriding corresponding default values.

3. Import any of the DEAD , EDITOR , MBOX , LISTER , PAGER , SHELL , or VISUAL variables that are
present in the environment, overriding the corresponding default values.

4. Read mailx commands from an unspecified system start-up file, unless the -n option is given, to
initialize any internal mailx variables and aliases.

5. Process the start-up file of mailx commands named in the user MAILRC variable.

Most regular mailx commands are valid inside start-up files, the most common use being to set up initial
display options and alias lists. The following commands shall be invalid in the start-up file: !, edit,
hold, mail, preserve, reply, Reply, shell, visual, Copy, followup, and Followup. Any errors in the start-
up file shall either cause mailx to terminate with a diagnostic message and a non-zero status or to
continue after writing a diagnostic message, ignoring the remainder of the lines in the start-up file.

A blank line in a start-up file shall be ignored.

Internal Variables in mailx
The following variables are internal mailx variables. Each internal variable can be set via the mailx set
command at any time. The unset and set no name commands can be used to erase variables.

In the following list, variables shown as:

variable

represent Boolean values. Variables shown as:

variable=value

shall be assigned string or numeric values. For string values, the rules in Commands in mailx concerning
filenames and quoting shall also apply.

The defaults specified here may be changed by the implementation-defined system start-up file unless the
user specifies the -n option.

allnet All network names whose login name components match shall be treated as identical. This shall
cause the msglist message specifications to behave similarly. The default shall be noallnet. See
also the alternates command and the metoo variable.

append Append messages to the end of the mbox file upon termination instead of placing them at the
beginning. The default shall be noappend. This variable shall not affect the save command when
saving to mbox.

ask, asksub
Prompt for a subject line on outgoing mail if one is not specified on the command line with the -s
option. The ask and asksub forms are synonyms; the system shall refer to asksub and noasksub in
its messages, but shall accept ask and noask as user input to mean asksub and noasksub. It shall
not be possible to set both ask and noasksub, or noask and asksub. The default shall be asksub,
but no prompting shall be done if standard input is not a terminal.

askbcc Prompt for the blind copy list. The default shall be noaskbcc.

askcc Prompt for the copy list. The default shall be noaskcc.

autoprint
Enable automatic writing of messages after delete and undelete commands. The default shall be
noautoprint.

bang Enable the special-case treatment of exclamation marks ( '!' ) in escape command lines; see the
escape command and Command Escapes in mailx . The default shall be nobang, disabling the expansion
of '!' in the command argument to the ~! command and the ~<! command escape.

cmd=command

Set the default command to be invoked by the pipe command. The default shall be nocmd.

crt=number
Pipe messages having more than number lines through the command specified by the value of the
PAGER variable. The default shall be nocrt. If it is set to null, the value used is
implementation-defined.

debug Enable verbose diagnostics for debugging. Messages are not delivered. The default shall be
nodebug.

dot When dot is set, a period on a line by itself during message input from a terminal shall also
signify end-of-file (in addition to normal end-of-file). The default shall be nodot. If ignoreeof
is set (see below), a setting of nodot shall be ignored and the period is the only method to
terminate input mode.

escape=c
Set the command escape character to be the character 'c' . By default, the command escape
character shall be tilde. If escape is unset, tilde shall be used; if it is set to null, command
escaping shall be disabled.

flipr Reverse the meanings of the R and r commands. The default shall be noflipr.

folder=directory

The default directory for saving mail files. User-specified filenames beginning with a plus sign (
'+' ) shall be expanded by preceding the filename with this directory name to obtain the real
pathname. If directory does not start with a slash ( '/' ), the contents of HOME shall be prefixed
to it. The default shall be nofolder. If folder is unset or set to null, user-specified filenames
beginning with '+' shall refer to files in the current directory that begin with the literal '+'
character. See also outfolder below. The folder value need not affect the processing of the files
named in MBOX and DEAD .

header Enable writing of the header summary when entering mailx in Receive Mode. The default shall be
header.

hold Preserve all messages that are read in the system mailbox instead of putting them in the mbox save
file. The default shall be nohold.

ignore Ignore interrupts while entering messages. The default shall be noignore.

ignoreeof
Ignore normal end-of-file during message input. Input can be terminated only by entering a period
( '.' ) on a line by itself or by the ~. command escape. The default shall be noignoreeof. See
also dot above.

indentprefix=string

A string that shall be added as a prefix to each line that is inserted into the message by the ~m
command escape. This variable shall default to one <tab>.

keep When a system mailbox, secondary mailbox, or mbox is empty, truncate it to zero length instead of
removing it. The default shall be nokeep.

keepsave
Keep the messages that have been saved from the system mailbox into other files in the file
designated by the variable MBOX , instead of deleting them. The default shall be nokeepsave.

metoo Suppress the deletion of the login name of the user from the recipient list when replying to a
message or sending to a group. The default shall be nometoo.

onehop When responding to a message that was originally sent to several recipients, the other recipient
addresses are normally forced to be relative to the originating author's machine for the response.
This flag disables alteration of the recipients' addresses, improving efficiency in a network
where all machines can send directly to all other machines (that is, one hop away). The default
shall be noonehop.

outfolder
Cause the files used to record outgoing messages to be located in the directory specified by the
folder variable unless the pathname is absolute. The default shall be nooutfolder. See the record
variable.

page Insert a <form-feed> after each message sent through the pipe created by the pipe command. The
default shall be nopage.

prompt=string

Set the command-mode prompt to string. If string is null or if noprompt is set, no prompting shall
occur. The default shall be to prompt with the string "? " .

quiet Refrain from writing the opening message and version when entering mailx. The default shall be
noquiet.

record=file
Record all outgoing mail in the file with the pathname file. The default shall be norecord. See
also outfolder above.

save Enable saving of messages in the dead-letter file on interrupt or delivery error. See the variable
DEAD for the location of the dead-letter file. The default shall be save.

screen=number

Set the number of lines in a screenful of headers for the headers and z commands. If screen is not
specified, a value based on the terminal type identified by the TERM environment variable, the
window size, the baud rate, or some combination of these shall be used.

sendwait
Wait for the background mailer to finish before returning. The default shall be nosendwait.

showto When the sender of the message was the user who is invoking mailx, write the information from the
To: line instead of the From: line in the header summary. The default shall be noshowto.

sign=string
Set the variable inserted into the text of a message when the ~a command escape is given. The
default shall be nosign. The character sequences '\t' and '\n' shall be recognized in the variable
as <tab>s and <newline>s, respectively. (See also ~i in Command Escapes in mailx .)

Sign=string
Set the variable inserted into the text of a message when the ~A command escape is given. The
default shall be noSign. The character sequences '\t' and '\n' shall be recognized in the variable
as <tab>s and <newline>s, respectively.

toplines=number

Set the number of lines of the message to write with the top command. The default shall be 5.

Commands in mailx
The following mailx commands shall be provided. In the following list, header refers to lines from the
message header, as shown in the OUTPUT FILES section. Header-line refers to lines within the header that
begin with one or more non-white-space characters, immediately followed by a colon and white space and
continuing until the next line beginning with a non-white-space character or an empty line. Header-field
refers to the portion of a header line prior to the first colon in that line.

For each of the commands listed below, the command can be entered as the abbreviation (those characters
in the Synopsis command word preceding the '[' ), the full command (all characters shown for the command
word, omitting the '[' and ']' ), or any truncation of the full command down to the abbreviation. For
example, the exit command (shown as ex[it] in the Synopsis) can be entered as ex, exi, or exit.

The arguments to commands can be quoted, using the following methods:

* An argument can be enclosed between paired double-quotes ( "" ) or single-quotes ( '' ); any white
space, shell word expansion, or backslash characters within the quotes shall be treated literally as
part of the argument. A double-quote shall be treated literally within single-quotes and vice versa.
These special properties of the quote marks shall occur only when they are paired at the beginning and
end of the argument.

* A backslash outside of the enclosing quotes shall be discarded and the following character treated
literally as part of the argument.

* An unquoted backslash at the end of a command line shall be discarded and the next line shall continue
the command.

Filenames, where expected, shall be subjected to the following transformations, in sequence:

* If the filename begins with an unquoted plus sign, and the folder variable is defined (see the folder
variable), the plus sign shall be replaced by the value of the folder variable followed by a slash. If
the folder variable is unset or is set to null, the filename shall be unchanged.

* Shell word expansions shall be applied to the filename (see Word Expansions ). If more than a single
pathname results from this expansion and the command is expecting one file, the effects are
unspecified.

Declare Aliases
Synopsis:

a[lias] [alias [address...]]g[roup] [alias [address...]]

Add the given addresses to the alias specified by alias. The names shall be substituted when alias is
used as a recipient address specified by the user in an outgoing message (that is, other recipients
addressed indirectly through the reply command shall not be substituted in this manner). Mail address
alias substitution shall apply only when the alias string is used as a full address; for example, when
hlj is an alias, hlj@posix.com does not trigger the alias substitution. If no arguments are given, write
a listing of the current aliases to standard output. If only an alias argument is given, write a listing
of the specified alias to standard output. These listings need not reflect the same order of addresses
that were entered.

Declare Alternatives
Synopsis:

alt[ernates] name...

(See also the metoo command.) Declare a list of alternative names for the user's login. When responding
to a message, these names shall be removed from the list of recipients for the response. The comparison
of names shall be in a case-insensitive manner. With no arguments, alternates shall write the current
list of alternative names.

Change Current Directory
Synopsis:

cd [directory]ch[dir] [directory]

Change directory. If directory is not specified, the contents of HOME shall be used.

Copy Messages
Synopsis:

c[opy] [file]c[opy] [msglist] fileC[opy] [msglist]

Copy messages to the file named by the pathname file without marking the messages as saved. Otherwise, it
shall be equivalent to the save command.

In the capitalized form, save the specified messages in a file whose name is derived from the author of
the message to be saved, without marking the messages as saved. Otherwise, it shall be equivalent to the
Save command.

Delete Messages
Synopsis:

d[elete] [msglist]

Mark messages for deletion from the mailbox. The deletions shall not occur until mailx quits (see the
quit command) or changes mailboxes (see the folder command). If autoprint is set and there are messages
remaining after the delete command, the current message shall be written as described for the print
command (see the print command); otherwise, the mailx prompt shall be written.

Discard Header Fields
Synopsis:

di[scard] [header-field...]ig[nore] [header-field...]

Suppress the specified header fields when writing messages. Specified header-fields shall be added to the
list of suppressed header fields. Examples of header fields to ignore are status and cc. The fields shall
be included when the message is saved. The Print and Type commands shall override this command. The
comparison of header fields shall be in a case-insensitive manner. If no arguments are specified, write a
list of the currently suppressed header fields to standard output; the listing need not reflect the same
order of header fields that were entered.

If both retain and discard commands are given, discard commands shall be ignored.

Delete Messages and Display
Synopsis:

dp [msglist]dt [msglist]

Delete the specified messages as described for the delete command, except that the autoprint variable
shall have no effect, and the current message shall be written only if it was set to a message after the
last message deleted by the command. Otherwise, an informational message to the effect that there are no
further messages in the mailbox shall be written, followed by the mailx prompt.

Echo a String
Synopsis:

ec[ho] string ...

Echo the given strings, equivalent to the shell echo utility.

Edit Messages
Synopsis:

e[dit] [msglist]

Edit the given messages. The messages shall be placed in a temporary file and the utility named by the
EDITOR variable is invoked to edit each file in sequence. The default EDITOR is unspecified.

The edit command does not modify the contents of those messages in the mailbox.

Exit
Synopsis:

ex[it]x[it]

Exit from mailx without changing the mailbox. No messages shall be saved in the mbox (see also quit).

Change Folder
Synopsis:

fi[le] [file]fold[er] [file]

Quit (see the quit command) from the current file of messages and read in the file named by the pathname
file. If no argument is given, the name and status of the current mailbox shall be written.

Several unquoted special characters shall be recognized when used as file names, with the following
substitutions:

% The system mailbox for the invoking user.

%user The system mailbox for user.

# The previous file.

& The current mbox.

+file The named file in the folder directory. (See the folder variable.)

The default file shall be the current mailbox.

Display List of Folders
Synopsis:

folders

Write the names of the files in the directory set by the folder variable. The command specified by the
LISTER environment variable shall be used (see the ENVIRONMENT VARIABLES section).

Follow Up Specified Messages
Synopsis:

fo[llowup] [message]F[ollowup] [msglist]

In the lowercase form, respond to a message, recording the response in a file whose name is derived from
the author of the message. See also the save and copy commands and outfolder.

In the capitalized form, respond to the first message in the msglist, sending the message to the author
of each message in the msglist. The subject line shall be taken from the first message and the response
shall be recorded in a file whose name is derived from the author of the first message. See also the Save
and Copy commands and outfolder.

Both forms shall override the record variable, if set.

Display Header Summary for Specified Messages
Synopsis:

f[rom] [msglist]

Write the header summary for the specified messages.

Display Header Summary
Synopsis:

h[eaders] [message]

Write the page of headers that includes the message specified. If the message argument is not specified,
the current message shall not change. However, if the message argument is specified, the current message
shall become the message that appears at the top of the page of headers that includes the message
specified. The screen variable sets the number of headers per page. See also the z command.

Help
Synopsis:

hel[p]?

Write a summary of commands.

Hold Messages
Synopsis:

ho[ld] [msglist]pre[serve] [msglist]

Mark the messages in msglist to be retained in the mailbox when mailx terminates. This shall override any
commands that might previously have marked the messages to be deleted. During the current invocation of
mailx, only the delete, dp, or dt commands shall remove the preserve marking of a message.

Execute Commands Conditionally
Synopsis:

i[f] s|r
mail-commands
el[se]
mail-commands
en[dif]

Execute commands conditionally, where if s executes the following mail-commands, up to an else or endif,
if the program is in Send Mode, and if r shall cause the mail-commands to be executed only in Receive
Mode.

List Available Commands
Synopsis:

l[ist]

Write a list of all commands available. No explanation shall be given.

Mail a Message
Synopsis:

m[ail] address...

Mail a message to the specified addresses or aliases.

Direct Messages to mbox
Synopsis:

mb[ox] [msglist]

Arrange for the given messages to end up in the mbox save file when mailx terminates normally. See MBOX .
See also the exit and quit commands.

Process Next Specified Message
Synopsis:

n[ext] [message]

If the current message has not been written (for example, by the print command) since mailx started or
since any other message was the current message, behave as if the print command was entered. Otherwise,
if there is an undeleted message after the current message, make it the current message and behave as if
the print command was entered. Otherwise, an informational message to the effect that there are no
further messages in the mailbox shall be written, followed by the mailx prompt.

Pipe Message
Synopsis:

pi[pe] [[msglist] command]| [[msglist] command]

Pipe the messages through the given command by invoking the command interpreter specified by SHELL with
two arguments: -c and command. (See also sh -c.) The application shall ensure that the command is given
as a single argument. Quoting, described previously, can be used to accomplish this. If no arguments are
given, the current message shall be piped through the command specified by the value of the cmd variable.
If the page variable is set, a <form-feed> shall be inserted after each message.

Display Message with Headers
Synopsis:

P[rint] [msglist]T[ype] [msglist]

Write the specified messages, including all header lines, to standard output. Override suppression of
lines by the discard, ignore, and retain commands. If crt is set, the messages longer than the number of
lines specified by the crt variable shall be paged through the command specified by the PAGER environment
variable.

Display Message
Synopsis:

p[rint] [msglist]t[ype] [msglist]

Write the specified messages to standard output. If crt is set, the messages longer than the number of
lines specified by the crt variable shall be paged through the command specified by the PAGER environment
variable.

Quit
Synopsis:

q[uit]
end-of-file

Terminate mailx, storing messages that were read in mbox (if the current mailbox is the system mailbox
and unless hold is set), deleting messages that have been explicitly saved (unless keepsave is set),
discarding messages that have been deleted, and saving all remaining messages in the mailbox.

Reply to a Message List
Synopsis:

R[eply] [msglist]R[espond] [msglist]

Mail a reply message to the sender of each message in the msglist. The subject line shall be formed by
concatenating Re: <space> (unless it already begins with that string) and the subject from the first
message. If record is set to a filename, the response shall be saved at the end of that file.

EXIT STATUS

       When the -e option is specified, the following exit values are returned:

        0     Mail was found.

       >0     Mail was not found or an error occurred.

       Otherwise, the following exit values are returned:

        0     Successful  completion; note that this status implies that all messages were sent, but it gives no
              assurances that any of them were actually delivered.

       >0     An error occurred.

CONSEQUENCES OF ERRORS

       When in input mode (Receive Mode) or Send Mode:

        * If an error is encountered processing a command escape (see Command Escapes in mailx ),  a  diagnostic
          message  shall  be written to standard error, and the message being composed may be modified, but this
          condition shall not prevent the message from being sent.

        * Other errors shall prevent the sending of the message.

       When in command mode:

        * Default.

       The following sections are informative.

APPLICATION USAGE

Delivery of messages to remote systems requires the existence of communication paths to such systems.
These need not exist.

Input lines are limited to {LINE_MAX} bytes, but mailers between systems may impose more severe line-
length restrictions. This volume of IEEE Std 1003.1-2001 does not place any restrictions on the length of
messages handled by mailx, and for delivery of local messages the only limitations should be the normal
problems of available disk space for the target mail file. When sending messages to external machines,
applications are advised to limit messages to less than 100000 bytes because some mail gateways impose
message-length restrictions.

The format of the system mailbox is intentionally unspecified. Not all systems implement system mailboxes
as flat files, particularly with the advent of multimedia mail messages. Some system mailboxes may be
multiple files, others records in a database. The internal format of the messages themselves is specified
with the historical format from Version 7, but only after the messages have been saved in some file other
than the system mailbox. This was done so that many historical applications expecting text-file mailboxes
are not broken.

Some new formats for messages can be expected in the future, probably including binary data, bit maps,
and various multimedia objects. As described here, mailx is not prohibited from handling such messages,
but it must store them as text files in secondary mailboxes (unless some extension, such as a variable or
command line option, is used to change the stored format). Its method of doing so is implementation-
defined and might include translating the data into text file-compatible or readable form or omitting
certain portions of the message from the stored output.

The discard and ignore commands are not inverses of the retain command. The retain command discards all
header-fields except those explicitly retained. The discard command keeps all header-fields except those
explicitly discarded. If headers exist on the retained header list, discard and ignore commands are
ignored.

EXAMPLES

       None.

RATIONALE

The standard developers felt strongly that a method for applications to send messages to specific users
was necessary. The obvious example is a batch utility, running non-interactively, that wishes to
communicate errors or results to a user. However, the actual format, delivery mechanism, and method of
reading the message are clearly beyond the scope of this volume of IEEE Std 1003.1-2001.

The intent of this command is to provide a simple, portable interface for sending messages non-
interactively. It merely defines a "front-end" to the historical mail system. It is suggested that
implementations explicitly denote the sender and recipient in the body of the delivered message. Further
specification of formats for either the message envelope or the message itself were deliberately not
made, as the industry is in the midst of changing from the current standards to a more internationalized
standard and it is probably incorrect, at this time, to require either one.

Implementations are encouraged to conform to the various delivery mechanisms described in the CCITT X.400
standards or to the equivalent Internet standards, described in Internet Request for Comment (RFC)
documents RFC 819, RFC 822, RFC 920, RFC 921, and RFC 1123.

Many historical systems modified each body line that started with From by prefixing the 'F' with '>' .
It is unnecessary, but allowed, to do that when the string does not follow a blank line because it cannot
be confused with the next header.

The edit and visual commands merely edit the specified messages in a temporary file. They do not modify
the contents of those messages in the mailbox; such a capability could be added as an extension, such as
by using different command names.

The restriction on a subject line being {LINE_MAX}-10 bytes is based on the historical format that
consumes 10 bytes for Subject: and the trailing <newline>. Many historical mailers that a message may
encounter on other systems are not able to handle lines that long, however.

Like the utilities logger and lp, mailx admittedly is difficult to test. This was not deemed sufficient
justification to exclude this utility from this volume of IEEE Std 1003.1-2001. It is also arguable that
it is, in fact, testable, but that the tests themselves are not portable.

When mailx is being used by an application that wishes to receive the results as if none of the User
Portability Utilities option features were supported, the DEAD environment variable must be set to
/dev/null. Otherwise, it may be subject to the file creations described in mailx ASYNCHRONOUS EVENTS.
Similarly, if the MAILRC environment variable is not set to /dev/null, historical versions of mailx and
Mail read initialization commands from a file before processing begins. Since the initialization that a
user specifies could alter the contents of messages an application is trying to send, such applications
must set MAILRC to /dev/null.

The description of LC_TIME uses "may affect" because many historical implementations do not or cannot
manipulate the date and time strings in the incoming mail headers. Some headers found in incoming mail do
not have enough information to determine the timezone in which the mail originated, and, therefore, mailx
cannot convert the date and time strings into the internal form that then is parsed by routines like
strftime() that can take LC_TIME settings into account. Changing all these times to a user-specified
format is allowed, but not required.

The paginator selected when PAGER is null or unset is partially unspecified to allow the System V
historical practice of using pg as the default. Bypassing the pagination function, such as by declaring
that cat is the paginator, would not meet with the intended meaning of this description. However, any
"portable user" would have to set PAGER explicitly to get his or her preferred paginator on all systems.
The paginator choice was made partially unspecified, unlike the VISUAL editor choice (mandated to be vi)
because most historical pagers follow a common theme of user input, whereas editors differ dramatically.

Options to specify addresses as cc (carbon copy) or bcc (blind carbon copy) were considered to be format
details and were omitted.

A zero exit status implies that all messages were sent, but it gives no assurances that any of them were
actually delivered. The reliability of the delivery mechanism is unspecified and is an appropriate
marketing distinction between systems.

In order to conform to the Utility Syntax Guidelines, a solution was required to the optional file
option-argument to -f. By making file an operand, the guidelines are satisfied and users remain portable.
However, it does force implementations to support usage such as:

mailx -fin mymail.box

The no name method of unsetting variables is not present in all historical systems, but it is in System V
and provides a logical set of commands corresponding to the format of the display of options from the
mailx set command without arguments.

The ask and asksub variables are the names selected by BSD and System V, respectively, for the same
feature. They are synonyms in this volume of IEEE Std 1003.1-2001.

The mailx echo command was not documented in the BSD version and has been omitted here because it is not
obviously useful for interactive users.

The default prompt on the System V mailx is a question mark, on BSD Mail an ampersand. Since this volume
of IEEE Std 1003.1-2001 chose the mailx name, it kept the System V default, assuming that BSD users would
not have difficulty with this minor incompatibility (that they can override).

The meanings of r and R are reversed between System V mailx and SunOS Mail. Once again, since this volume
of IEEE Std 1003.1-2001 chose the mailx name, it kept the System V default, but allows the SunOS user to
achieve the desired results using flipr, an internal variable in System V mailx, although it has not been
documented in the SVID.

The indentprefix variable, the retain and unalias commands, and the ~F and ~M command escapes were
adopted from 4.3 BSD Mail.

The version command was not included because no sufficiently general specification of the version
information could be devised that would still be useful to a portable user. This command name should be
used by suppliers who wish to provide version information about the mailx command.

The "implementation-specific (unspecified) system start-up file" historically has been named
/etc/mailx.rc, but this specific name and location are not required.

The intent of the wording for the next command is that if any command has already displayed the current
message it should display a following message, but, otherwise, it should display the current message.
Consider the command sequence:

next 3
delete 3
next

where the autoprint option was not set. The normative text specifies that the second next command should
display a message following the third message, because even though the current message has not been
displayed since it was set by the delete command, it has been displayed since the current message was
anything other than message number 3. This does not always match historical practice in some
implementations, where the command file address followed by next (or the default command) would skip the
message for which the user had searched.

FUTURE DIRECTIONS

       None.

COPYRIGHT

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2003 Edition,
       Standard  for  Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of Electrical and Electronics Engineers,
       Inc and The Open Group. In the event of any discrepancy between this version and the  original  IEEE  and
       The  Open  Group  Standard,  the  original  IEEE and The Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group                                   2003                                              MAILX(P)