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.

 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 to 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 is 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 is the default place to find them. As messages are read, they will 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 HOME directory of the user (see MBOX in the ENVIRONMENT VARIABLES section for a description of this file). Messages remain in this file until explicitly removed. When the -f option is used to read mail messages from secondary files, messages will 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 supports the XBD specification, Utility Syntax Guidelines  .

The following options are supported:

-e

Test for the presence of mail in the system mailbox. The mailx utility will 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 the 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 initialise 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 will appear in the delivered message. The results are unspecified if subject is longer than {LINE_MAX} - 10 bytes or contains a newline character.

-u user

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

 OPERANDS

The following operands are supported:

address

Addressee of message. When -n is specified and no user start-up files are accessed (see the EXTENDED DESCRIPTION section), this must be 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 is 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 must be the message to be delivered to the specified addresses. In both Send and Receive Modes, standard-input lines beginning with the escape character (usually tilde (^)) affect processing as described in Command Escapes in mailx .

 INPUT FILES

When mailx is used as described by this specification, the file option-argument (see the -f option) and the mbox must 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 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 is dead.letter in the directory named by the HOME variable.

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 ed.

HOME

Determine the pathname of the user's home directory.

LANG

Provide a default value for the internationalisation variables that are unset or null. If LANG is unset or null, the corresponding value from the implementation-dependent default locale will be used. If any of the internationalisation variables contains an invalid setting, the utility will behave as if none of the variables had been defined.

LC_ALL

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

LC_CTYPE

Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single- 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 is valid. If this variable is null or not set, the output command will be ls. The default value is unset.

MAILRC

Determine the pathname of the start-up file. The default is .mailrc in the HOME directory.

MBOX

Determine a pathname of the file to save messages from the system mailbox that have been read. The exit command overrides this function, as will saving the message explicitly in another file. The default is in the directory named by the HOME variable.

NLSPATH

Determine the location of message catalogues 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 is valid. When standard output is a terminal device, the message output will 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 will be either more or another paginator utility documented in the system documentation.

SHELL

Determine the name of a preferred command interpreter. The default is sh.

TERM

Determine the name of the terminal type, to indicate in an unspecified manner, if the internal variable screen is not specified, the number of lines in a screenful of headers. If TERM is not set or is set to null, an unspecified default terminal type will be used and the value of a screenful is unspecified.

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 will be vi.

 ASYNCHRONOUS EVENTS

When mailx is in Send Mode and standard input is not a terminal, it takes 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, will be aborted, and a command-mode prompt will be written.

2. If in input mode:

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

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

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

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

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

The mailx utility takes the standard action for all other signals.

 STDOUT

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

 STDERR

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 specification, these files will 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 is not 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 will be empty. The format of a message body line is also unspecified, except that no line following an empty line can start with From <space>; mailx will 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-dependent how such a message is stored in files written by mailx.

 EXTENDED DESCRIPTION

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-internationalised 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 will write the page of header-summary lines (see below) containing the first new message (if -N is not specified), or the first unread message if there are no new messages, or the first message if there are no new or unread messages, followed by a prompt indicating mailx can accept regular commands (see Commands in mailx ); this is termed command mode. 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 will be written. At this point mailx is in input mode. This input mode is also 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. When the message is typed and the end of message is encountered, the message will 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 Command Escapes in mailx for a summary of these commands.

Note:

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

At any time, the behaviour of mailx is 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, print is assumed. In input mode, commands are recognised by the escape character, and lines not treated as commands are taken as input for the message.

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

All messages have a state that affects 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, marked by a ">" at the beginning of a line in the header summary. All messages are 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 will 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 will 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 will 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 will be retained in their current location.

deleted

The message has been processed by one of the following commands: delete, dp, dt. A message processed by save will be in state deleted unless the internal variable keepsave was set. Messages in state deleted when mailx quits will be deleted.

preserved

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

The header-summary line for each message will 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 characters, 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 will be matchable in this form.

/string

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

:c

All messages of type c, where c must 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 will 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 will 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 initialise 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 are 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 will 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 is 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 noname commands can be used to erase variables.

In the following list, variables shown as:

variable

represent Boolean values. Variables shown as:

variable=value

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

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

allnet

All network names whose login name components match are treated as identical. This causes the msglist message specifications to behave similarly. The default is 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 is noappend. This variable will not affect the save command when saving to the 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 will refer to asksub and noasksub in its messages, but will accept ask and noask as user input to mean asksub and noasksub. It is not possible to set both ask and noasksub, or noask and asksub. The default is asksub, but no prompting will be done if standard input is not a terminal.

askbcc

Prompt for the blind copy list. The default is noaskbcc.

askcc

Prompt for the copy list. The default is noaskcc.

autoprint

Enable automatic writing of messages after delete and undelete commands. The default is 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 is 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 is nocmd.

crt=number

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

debug

Enable verbose diagnostics for debugging. Messages are not delivered. The default is nodebug.

dot

When dot is set, a period on a line by itself during message input from a terminal also signifies end-of-file (in addition to normal end-of-file). The default is nodot. If ignoreeof is set (see below), a setting of nodot will 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 is tilde. If escape is unset, tilde will be used; if it is set to null, command escaping will be disabled.

flipr

Reverse the meanings of the R and r commands. The default is noflipr.

folder=directory

The default directory for saving mail files. User-specified filenames beginning with a plus sign (+) will 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 will be prefixed to it. The default is nofolder. If folder is unset or set to null, user-specified filenames beginning with "+" 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 is header.

hold

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

ignore

Ignore interrupts while entering messages. The default is 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 is noignoreeof. See also dot above.

indentprefix=string

A string that will be prefixed to each line that is inserted into the message by the ~m command escape. This variable defaults to one tab character.

keep

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

keepsave

Keep messages that have been saved in other files in the system mailbox instead of deleting them. The default is 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 is 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 is 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 is nooutfolder. See the record variable.

page

Insert a form-feed after each message sent through the pipe created by the pipe command. The default is nopage.

prompt=string

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

quiet

Refrain from writing the opening message and version when entering mailx. The default is noquiet.

record=file

Record all outgoing mail in the file with the pathname file. The default is 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 is 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 will be used.

sendmail=shell-command

Alternative command for delivering messages. The default is implementation-dependent. (LEGACY)

sendwait

Wait for the background mailer to finish before returning. The default is 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 is noshowto.

sign=string

Set the variable inserted into the text of a message when the ~a command escape is given. The default is nosign. The character sequences \t and \n are recognised in the variable as tab and newline characters, 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 is noSign. The character sequences \t and \n will be recognised in the variable as tab and newline characters, respectively.

toplines=number

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

 Commands in mailx

The following mailx commands are 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 will be treated literally as part of the argument. A double-quote will be treated literally within single-quotes and vice versa. These special properties of the quote marks occur only when they are paired at the beginning and end of the argument.

• A backslash outside of the enclosing quotes is discarded and the following character treated literally as part of the argument.

• An unquoted backslash at the end of a command line is discarded and the next line continues the command.

Filenames, where expected, are subjected to the process of shell word expansions (see Word Expansions ); if more than a single pathname results and the command is expecting one file, the effects are unspecified. If the filename begins with an unquoted plus sign, it will not be expanded, but treated as the named file (less the leading plus) in the folder directory. (See the folder variable.)

 Declare Aliases

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

Add the given addresses to the alias specified by alias. The names will 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 will not be substituted in this manner). Mail address alias substitution applies 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...

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

 Change Current Directory

Synopsis: cd [directory]
Synopsis: ch[dir] [directory]

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

 Copy Messages

Synopsis: c[opy] [file]
Synopsis: c[opy] [msglist] file
Synopsis: C[opy] [msglist]

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

In the capitalised 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 is equivalent to the Save command.

 Delete Messages

Synopsis: d[elete] [msglist]

Mark messages for deletion from the mailbox. The deletions will not occur until mailx quits (see the quit command) or changes mailboxes (see the folder command). If autoprint is set, the next message after the last one deleted will be written; if there is no subsequent message, the previous message, if it exists, will be written. In the case of no subsequent or previous message, or when noautoprint is set, the mailx prompt will be written.

 Discard Header Fields

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

Suppress the specified header fields when writing messages. Specified header-fields will be added to the list of suppressed header fields. Examples of header fields to ignore are status and cc. The fields will be included when the message is saved. The Print and Type commands override this command. The comparison of header fields is 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 are ignored.

 Delete Messages and Display

Synopsis: dp [msglist]
Synopsis: dt [msglist]

Delete the specified messages from the mailbox and write the next message after the last one deleted. If there is no subsequent message, the mailx prompt will be written.

 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 will be placed in a temporary file and the utility named by the EDITOR variable will be invoked to edit the file.

The edit command merely edits the specified messages in a temporary file. It does not modify the contents of those messages in the mailbox.

 Exit

Synopsis: ex[it]
Synopsis: x[it]

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

 Change Folder

Synopsis: fi[le] [file]
Synopsis: 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 will be written.

Several unquoted special characters are recognised 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 is the current mailbox.

 Display List of Folders

Synopsis: folders

Write the names of the files in the directory set by the folder variable.

 Follow up Specified Messages

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

In the lower-case form, respond to a message, recording the response in a file whose name is derived from the author of the message. Overrides the record variable, if set. See also the save and copy commands and outfolder.

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

 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. The screen variable sets the number of headers per page. See also the z command.

 Help

Synopsis: hel[p]
Synopsis: ?

Write a summary of commands.

 Hold Messages

Synopsis: ho[ld] [msglist]
Synopsis: pre[serve] [msglist]

Mark the messages in msglist to be retained in the mailbox when mailx terminates. This overrides 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 will 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 ifs will execute the following mail-commands, up to an else or endif, if the program is in Send Mode, and ifr will 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 is 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]

Go to the next message matching message.

 Pipe Message

Synopsis: pi[pe] [[msglist] command]
Synopsis: | [[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 command must be given as a single argument. Quoting, described previously, can be used to accomplish this. If no arguments are given, the current message will be piped through the command specified by the value of the cmd variable. If the page variable is set, a form-feed character will be inserted after each message.

 Display Message with Headers

Synopsis: P[rint] [msglist]
Synopsis: 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 will be paged through the command specified by the PAGER environment variable.

 Display Message

Synopsis: p[rint] [msglist]
Synopsis: 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 will be paged through the command specified by the PAGER environment variable.

 Quit

Synopsis: q[uit]
Synopsis: 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]
Synopsis: R[espond] [msglist]

Mail a reply message to the sender of each message in the msglist. The subject line will 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 will be saved at the end of that file.

See also the flipr variable.

 Reply to a Message

Synopsis: r[eply] [message]
Synopsis: r[espond] [message]

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

See also the flipr variable.

 Retain Header Fields

Synopsis: ret[ain] [header-field...]

Retain the specified header fields when writing messages. This command will override all discard and ignore commands. The comparison of header fields is in a case-insensitive manner. If no arguments are specified, write a list of the currently retained header fields to standard output; the listing need not reflect the same order of header fields that were entered.

 Save Messages

Synopsis: s[ave] [file]
Synopsis: s[ave] [msglist] file
Synopsis: S[ave] [msglist]

Save the specified messages in the file named by the pathname file, or the mbox if the file argument is omitted. The file will be created if it does not exist; otherwise, the messages will be appended to the file. The message will be deleted from the mailbox when mailx terminates unless keepsave is set.

In the capitalised form, save the specified messages in a file whose name is derived from the author of the first message. The name of the file is taken to be the author's name with all network addressing stripped off. See also the Copy, followup and Followup commands and outfolder variable.

 Set Variables

Synopsis: se[t] [name[=[string]] ...] [name=number ...] [noname ...]

Define one or more variables called name. The variable can be given a null, string or numeric value. Quoting and backslash escapes can occur anywhere in string, as described previously, as if the string portion of the argument were the entire argument. The forms name and name= are equivalent to name="" for variables that take string values. The set command without arguments will write a list of all defined variables and their values. The noname form is equivalent to unset name.

 Invoke a Shell

Synopsis: sh[ell]

Invoke an interactive command interpreter (see also SHELL ).

 Display Message Size

Synopsis: si[ze] [msglist]

Write the size in bytes of each of the specified messages.

 Read mailx Commands From a File

Synopsis: so[urce] file

Read and execute commands from the file named by the pathname file and return to command mode.

 Display Beginning of Messages

Synopsis: to[p] [msglist]

Write the top few lines of each of the specified messages. If the toplines variable is set, it is taken as the number of lines to write. The default is 5.

 Touch Messages

Synopsis: tou[ch] [msglist]

Touch the specified messages. If any message in msglist is not specifically deleted nor saved in a file, it will be placed in the mbox upon normal termination. See exit and quit.

 Delete Aliases

Synopsis: una[lias] [alias]...

Delete the specified alias names. If a specified alias does not exist, the results are unspecified.

 Undelete Messages

Synopsis: u[ndelete] [msglist]

Remove the deleted markings from the specified messages. If autoprint is set, the last message of those restored will be written. If msglist is not specified, it defaults to the first deleted message following the current message that has not been undeleted if there is one, or the last deleted message preceding the current message that has not been undeleted otherwise.

 Unset Variables

Synopsis: uns[et] name...

Cause the specified variables to be erased.

 Edit Message with Full-screen Editor

Synopsis: v[isual] [msglist]

Edit the given messages with a screen editor. The messages are placed in a temporary file, and the utility named by the VISUAL variable will be invoked to edit the file. The default editor is vi.

The visual command merely edits the specified messages in a temporary file. It does not modify the contents of those messages in the mailbox.

 Write Messages to a File

Synopsis: w[rite] [msglist] file

Write the given messages to the file specified by the pathname file, minus the message header. Otherwise, it is equivalent to the save command.

 Scroll Header Display

Synopsis: z[+|-]

Scroll the header display forward (if "+" is specified or if no option is specified) or backward (if "-" is specified) one screenful. The number of headers written is set by the screen variable.

 Invoke Shell Command

Synopsis: !command

Invoke the command interpreter specified by SHELL with two arguments: -c and command. (See also sh -c.) If the bang variable is set, each unescaped occurrence of "!" in command is replaced with the command executed by the previous "!" command or ~! command escape.

 Null Command

Synopsis: # comment

This null command (comment) will be ignored by mailx.

 Display Current Message Number

Synopsis: =

Write the current message number.

 Command Escapes in mailx

The following commands can be entered only from input mode, by beginning a line with the escape character (by default, tilde (~)). See the escape variable description for changing this special character. The format for the commands is:

 

<ESC><command-char><separator>[<arguments>]

where the <separator> can be zero or more blank characters.

In the following descriptions, the argument command (but not mailx-command) must be a shell command string. Any string acceptable to the command interpreter specified by the SHELL variable when it is invoked as -c command_string is valid. The command can be presented as multiple arguments (that is, quoting is not required).

Command escapes that are listed with msglist or mailx-command arguments are invalid in Send Mode and produce unspecified results.

~! command

Invoke the command interpreter specified by SHELL with two arguments: -c and command; and then return to input mode. If the bang variable is set, each unescaped occurrence of "!" in command is replaced with the command executed by the previous "!" command or ~! command escape.

~.

Simulate end-of-file (terminate message input).

~: mailx-command

~_ mailx-command

Perform the command-level request.

~?

Write a summary of command escapes.

~A

This is equivalent to iSign.

~a

This is equivalent to isign.

~b name...

Add the names to the blind carbon copy (Bcc) list.

~c name...

Add the names to the carbon copy (Cc) list.

~d

Read in the dead-letter file. See DEAD for a description of this file.

~e

Invoke the editor, as specified by the EDITOR environment variable, on the partial message.

~f [msglist]

Forward the specified messages. The specified messages will be inserted into the current message without alteration. This command escape will also insert message headers into the message with field selection affected by the discard, ignore and retain commands.

~F [msglist]

This will be the equivalent of the ~f command escape, except that all headers will be included in the message, regardless of previous discard, ignore and retain commands.

~h

If standard input is a terminal, prompt for a Subject line and the To, Cc and Bcc lists. Other implementation-dependent headers may also be presented for editing. If the field is written with an initial value, it can be edited as if it had just been typed.

~i string

Insert the value of the named variable, followed by a newline character, into the text of the message. If the string is unset or null, the message will not be changed.

~m [msglist]

Insert the specified messages into the message, prefixing non-empty lines with the string in the indentprefix variable. This command escape will also insert message headers into the message, with field selection affected by the discard, ignore and retain commands.

~M [msglist]

This will be the equivalent of the ~m command escape, except that all headers will be included in the message, regardless of previous discard, ignore and retain commands.

~p

Write the message being entered. If the message is longer than crt lines (see Internal Variables in mailx ), the output will be paginated as described for the PAGER variable.

~q

Quit (see the quit command) from input mode by simulating an interrupt. If the body of the message is not empty, the partial message will be saved in the dead-letter file. See DEAD for a description of this file.

~r file

~< file

~< !command

Read in the file specified by the pathname file. If the argument begins with an exclamation-mark (!), the rest of the string is taken as an arbitrary system command; the command interpreter specified by SHELL will be invoked with two arguments: -c and command. The standard output of command will be inserted into the message.

~s string

Set the subject line to string.

~t name...

Add the given names to the To list.

~v

Invoke the full-screen editor, as specified by the VISUAL environment variable, on the partial message.

~w file

Write the partial message, without the header, onto the file named by the pathname file. The file will be created or the message will be appended to it if the file exists.

~x

Exit as with ~q, except the message will not be saved in the dead-letter file.

~| command

Pipe the body of the message through the given command by invoking the command interpreter specified by SHELL with two arguments: -c and command. If the command returns a successful exit status, the standard output of the command will replace the message. Otherwise the message will remain unchanged. If the command fails, an error message giving the exit status will be written.

 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 will be written to standard error, and the message being composed may be modified, but this condition will not prevent the message from being sent.

• Other errors will prevent the sending of the message.

When in command mode:

• Default.

 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 specification 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 50 kilobytes because many mail gateways impose message-length restrictions.

The format of the system mailbox is intentionally unspecified. Not all systems will 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 are specified with the historical format from Version 7, but only after they have been saved in some file other than the system mailbox. This was done so that many historical applications expecting text-file mailboxes will not be 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-dependent 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.

 FUTURE DIRECTIONS

The IEEE PASC 1003.2 Interpretations Committee has forwarded concerns about parts of this interface definition to the IEEE PASC Shell and Utilities Working Group which is identifying the corrections. A future revision of this specification will align with IEEE Std. 1003.2b when finalised.

 SEE ALSO

ed, ls, mail, more, vi.