path: root/usr/src/man/man1/mail.1

.\"
.\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
.\" permission to reproduce portions of its copyrighted documentation.
.\" Original documentation from The Open Group can be obtained online at
.\" http://www.opengroup.org/bookstore/.
.\"
.\" The Institute of Electrical and Electronics Engineers and The Open
.\" Group, have given us permission to reprint portions of their
.\" documentation.
.\"
.\" In the following statement, the phrase ``this text'' refers to portions
.\" of the system documentation.
.\"
.\" Portions of this text are reprinted and reproduced in electronic form
.\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
.\" Standard for Information Technology -- Portable Operating System
.\" Interface (POSIX), The Open Group Base Specifications Issue 6,
.\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
.\" Engineers, Inc and The Open Group.  In the event of any discrepancy
.\" between these versions 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" The contents of this file are subject to the terms of the
.\" Common Development and Distribution License (the "License").
.\" You may not use this file except in compliance with the License.
.\"
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
.\" or http://www.opensolaris.org/os/licensing.
.\" See the License for the specific language governing permissions
.\" and limitations under the License.
.\"
.\" When distributing Covered Code, include this CDDL HEADER in each
.\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
.\" If applicable, add the following below this CDDL HEADER, with the
.\" fields enclosed by brackets "[]" replaced with your own identifying
.\" information: Portions Copyright [yyyy] [name of copyright owner]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved
.\"
.TH MAIL 1 "Jul 24, 2008"
.SH NAME
mail, rmail \- read mail or send mail to users
.SH SYNOPSIS
.SS "Sending Mail"
.LP
.nf
\fBmail\fR [\fB-tw\fR] [\fB-m\fR \fImessage_type\fR] \fIrecipient\fR...
.fi

.LP
.nf
\fBrmail\fR [\fB-tw\fR] [\fB-m\fR \fImessage_type\fR] \fIrecipient\fR...
.fi

.SS "Reading Mail"
.LP
.nf
\fBmail\fR [\fB-ehpPqr\fR] [\fB-f\fR \fIfile\fR]
.fi

.SS "Debugging"
.LP
.nf
\fBmail\fR [\fB-x\fR \fIdebug_level\fR] [\fIother_mail_options\fR] \fIrecipient\fR...
.fi

.SH DESCRIPTION
.sp
.LP
A \fIrecipient\fR is usually a domain style address
("\fIuser\fR@\fImachine\fR") or a user name recognized by \fBlogin\fR(1). When
\fIrecipient\fRs are named, \fBmail\fR assumes a message is being sent. It
reads from the standard input up to an end-of-file (Control-d) or, if reading
from a terminal device, until it reads a line consisting of just a period. When
either of those indicators is received, \fBmail\fR adds the \fIletter\fR to the
\fImailfile\fR for each \fIrecipient\fR.
.sp
.LP
A \fIletter\fR is composed of some \fIheader lines\fR followed by a blank line
followed by the \fImessage content\fR. The \fIheader lines\fR section of the
letter consists of one or more UNIX postmarks:
.sp
.in +2
.nf
\fBFrom\fR \fIsender date_and_time\fR [\fBremote from\fR \fIremote_system_name\fR]
.fi
.in -2
.sp

.sp
.LP
followed by one or more standardized message header lines of the form:
.sp
.in +2
.nf
\fIkeyword-name\fR\fB:\fR [\fIprintable text\fR]
.fi
.in -2
.sp

.sp
.LP
where \fIkeyword-name\fR is comprised of any printable, non-whitespace
characters other than colon (`\fB:\fR'). A \fBMIME-version:\fR header line
indicates that the message is formatted as described in RFC 2045. A
\fBContent-Length:\fR header line, indicating the number of bytes in the
\fImessage content\fR, is always present unless the letter consists of only
header lines with no message content. A \fBContent-Type:\fR header line that
describes the type of the \fImessage content\fR (such as text/plain,
application/octet-stream, and so on) is also present, unless the letter
consists of only header lines with no message content. Header lines may be
continued on the following line if that line starts with white space.
.SH OPTIONS
.SS "Sending Mail"
.sp
.LP
The following command-line arguments affect sending mail:
.sp
.ne 2
.na
\fB\fB-m\fR \fImessage_type\fR\fR
.ad
.RS 19n
A \fBMessage-Type:\fR line is added to the message header with the value of
\fImessage_type\fR.
.RE

.sp
.ne 2
.na
\fB\fB-t\fR\fR
.ad
.RS 19n
A \fBTo:\fR line is added to the message header for each of the intended
\fIrecipient\fRs.
.RE

.sp
.ne 2
.na
\fB\fB-w\fR\fR
.ad
.RS 19n
A letter is sent to a remote recipient without waiting for the completion of
the remote transfer program.
.RE

.sp
.LP
If a letter is found to be undeliverable, it is returned to the sender with
diagnostics that indicate the location and nature of the failure. If \fBmail\fR
is interrupted during input, the message is saved in the file \fBdead.letter\fR
to allow editing and resending. \fBdead.letter\fR is always appended to, thus
preserving any previous contents. The initial attempt to append to (or create)
\fBdead.letter\fR is in the current directory. If this fails, \fBdead.letter\fR
is appended to (or created in) the user's login directory. If the second
attempt also fails, no \fBdead.letter\fR processing is done.
.sp
.LP
\fBrmail\fR only permits the sending of mail; \fBuucp\fR(1C) uses \fBrmail\fR
as a security precaution. Any application programs that generate mail messages
should be sure to invoke \fBrmail\fR rather than \fBmail\fR for message
transport and/or delivery.
.sp
.LP
If the local system has the Basic Networking Utilities installed, mail can be
sent to a recipient on a remote system. There are numerous ways to address mail
to recipients on remote systems depending on the transport mechanisms available
to the local system. The two most prevalent addressing schemes are Domain-style
and UUCP-style.
.sp
.ne 2
.na
\fBDomain-style addressing\fR
.ad
.RS 27n
Remote recipients are specified by appending an `\fB@\fR' and domain (and
possibly sub-domain) information to the recipient name (such as
\fBuser@sf.att.com\fR). (The local system administrator should be consulted for
details on which addressing conventions are available on the local system.)
.RE

.sp
.ne 2
.na
\fBUUCP-style addressing\fR
.ad
.RS 27n
Remote recipients are specified by prefixing the recipient name with the remote
system name and an exclamation point, such as \fBsysa!user.\fR If \fBcsh\fR(1)
is the default shell, \fBsysa\e!user\fR should be used. A series of system
names separated by exclamation points can be used to direct a letter through an
extended network (such as \fBsysa!sysb!sysc!user\fR or
\fBsysa\e!sysb\e!sysc\e!user\fR).
.RE

.SS "Reading Mail"
.sp
.LP
The following command-line arguments affect reading mail:
.sp
.ne 2
.na
\fB\fB-e\fR\fR
.ad
.RS 11n
Test for the presence of mail. \fBmail\fR prints nothing.
.sp
An exit status of \fB0\fR is returned if the user has mail. Otherwise, an exit
status of \fB1\fR is returned.
.RE

.sp
.ne 2
.na
\fB\fB-E\fR\fR
.ad
.RS 11n
Similar to \fB-e\fR, but tests only for the presence of \fBnew\fR mail.
.sp
An  exit  status  of \fB0\fR is returned if the user has new            mail
to read,  an exit status of \fB1\fR is returned if the            user  has no
mail,  or an exit status of \fB2\fR is returned            if the user has mail
which has already been read.
.RE

.sp
.ne 2
.na
\fB\fB-h\fR\fR
.ad
.RS 11n
A window of headers are initially displayed rather than the latest message. The
display is followed by the \fB?\fR prompt.
.RE

.sp
.ne 2
.na
\fB\fB-p\fR\fR
.ad
.RS 11n
All messages are printed without prompting for disposition.
.RE

.sp
.ne 2
.na
\fB\fB-P\fR\fR
.ad
.RS 11n
All messages are printed with \fIall\fR header lines displayed, rather than the
default selective header line display.
.RE

.sp
.ne 2
.na
\fB\fB-q\fR\fR
.ad
.RS 11n
\fBmail\fR terminates after interrupts. Normally an interrupt causes only the
termination of the message being printed.
.RE

.sp
.ne 2
.na
\fB\fB-r\fR\fR
.ad
.RS 11n
Messages are printed in first-in, first-out order.
.RE

.sp
.ne 2
.na
\fB\fB-f\fR \fIfile\fR\fR
.ad
.RS 11n
\fBmail\fR uses \fIfile\fR (such as \fBmbox\fR) instead of the default
\fImailfile\fR.
.RE

.sp
.LP
\fBmail\fR, unless otherwise influenced by command-line arguments, prints a
user's mail messages in last-in, first-out order. The default mode for printing
messages is to display only those header lines of immediate interest. These
include, but are not limited to, the UNIX \fBFrom\fR and \fB>From\fR postmarks,
\fBFrom:\fR, \fBDate:\fR, \fBSubject:\fR, and \fBContent-Length:\fR header
lines, and any recipient header lines such as \fBTo:\fR, \fBCc:\fR, \fBBcc:\fR,
and so forth. After the header lines have been displayed, \fBmail\fR displays
the contents (body) of the message only if it contains no unprintable
characters. Otherwise, \fBmail\fR issues a warning statement about the message
having binary content and \fBnot\fR display the content. This can be overridden
by means of the \fBp\fR command.
.sp
.LP
For each message, the user is prompted with a \fB?\fR and a line is read from
the standard input. The following commands are available to determine the
disposition of the message:
.sp
.ne 2
.na
\fB\fB#\fR\fR
.ad
.RS 22n
Print the number of the current message.
.RE

.sp
.ne 2
.na
\fB\fB\(mi\fR\fR
.ad
.RS 22n
Print previous message.
.RE

.sp
.ne 2
.na
\fB<new-line>,\fB+\fR, or \fBn\fR\fR
.ad
.RS 22n
Print the next message.
.RE

.sp
.ne 2
.na
\fB\fB!\fR\fIcommand\fR\fR
.ad
.RS 22n
Escape to the shell to do \fIcommand\fR.
.RE

.sp
.ne 2
.na
\fB\fBa\fR\fR
.ad
.RS 22n
Print message that arrived during the \fBmail\fR session.
.RE

.sp
.ne 2
.na
\fB\fBd\fR, or \fBdp\fR\fR
.ad
.RS 22n
Delete the current message and print the next message.
.RE

.sp
.ne 2
.na
\fB\fBd\fR \fIn\fR\fR
.ad
.RS 22n
Delete message number \fIn\fR. Do not go on to next message.
.RE

.sp
.ne 2
.na
\fB\fBdq\fR\fR
.ad
.RS 22n
Delete message and quit \fBmail\fR.
.RE

.sp
.ne 2
.na
\fB\fBh\fR\fR
.ad
.RS 22n
Display a window of headers around current message.
.RE

.sp
.ne 2
.na
\fB\fBh\fR\fIn\fR\fR
.ad
.RS 22n
Display a window of headers around message number \fIn\fR.
.RE

.sp
.ne 2
.na
\fB\fBh a\fR\fR
.ad
.RS 22n
Display headers of all messages in the user's \fImailfile\fR.
.RE

.sp
.ne 2
.na
\fB\fBh d\fR\fR
.ad
.RS 22n
Display headers of messages scheduled for deletion.
.RE

.sp
.ne 2
.na
\fB\fBm\fR [ \fIpersons\fR ]\fR
.ad
.RS 22n
Mail (and delete) the current message to the named \fIpersons\fR.
.RE

.sp
.ne 2
.na
\fB\fIn\fR\fR
.ad
.RS 22n
Print message number \fIn\fR.
.RE

.sp
.ne 2
.na
\fB\fBp\fR\fR
.ad
.RS 22n
Print current message again, overriding any indications of binary (that is,
unprintable) content.
.RE

.sp
.ne 2
.na
\fB\fBP\fR\fR
.ad
.RS 22n
Override default brief mode and print current message again, displaying all
header lines.
.RE

.sp
.ne 2
.na
\fB\fBq\fR, or Control-d\fR
.ad
.RS 22n
Put undeleted mail back in the \fImailfile\fR and quit \fBmail\fR.
.RE

.sp
.ne 2
.na
\fB\fBr\fR [ \fIusers\fR ]\fR
.ad
.RS 22n
Reply to the sender, and other \fIusers\fR, then delete the message.
.RE

.sp
.ne 2
.na
\fB\fBs\fR [ \fIfiles\fR ]\fR
.ad
.RS 22n
Save message in the named \fIfiles\fR (\fBmbox\fR is default) and delete the
message.
.RE

.sp
.ne 2
.na
\fB\fBu\fR [ \fIn\fR ]\fR
.ad
.RS 22n
Undelete message number \fIn\fR (default is last read).
.RE

.sp
.ne 2
.na
\fB\fBw\fR [ \fIfiles\fR ]\fR
.ad
.RS 22n
Save message contents, without any header lines, in the named \fIfiles\fR
(\fBmbox\fR is default) and delete the message.
.RE

.sp
.ne 2
.na
\fB\fBx\fR\fR
.ad
.RS 22n
Put all mail back in the \fImailfile\fR unchanged and exit \fBmail\fR.
.RE

.sp
.ne 2
.na
\fB\fBy\fR [ \fIfiles\fR ]\fR
.ad
.RS 22n
Same as \fB-w\fR option.
.RE

.sp
.ne 2
.na
\fB\fB?\fR\fR
.ad
.RS 22n
Print a command summary.
.RE

.sp
.LP
When a user logs in, the presence of mail, if any, is usually indicated. Also,
notification is made if new mail arrives while using \fBmail\fR.
.sp
.LP
The permissions of \fImailfile\fR can be manipulated using \fBchmod\fR(1) in
two ways to alter the function of \fBmail\fR. The other permissions of the file
can be read-write (\fB0666\fR), read-only (\fB0664\fR), or neither read nor
write (\fB0660\fR) to allow different levels of privacy. If changed to other
than the default (mode \fB0660\fR), the file is preserved even when empty to
perpetuate the desired permissions. (The administrator can override this file
preservation using the \fBDEL_EMPTY_MAILFILE\fR option of \fBmailcnfg\fR.)
.sp
.LP
The group \fBID\fR of the mailfile must be \fBmail\fR to allow new messages to
be delivered, and the mailfile must be writable by group \fBmail\fR.
.SS "Debugging"
.sp
.LP
The following command-line arguments cause \fBmail\fR to provide debugging
information:
.sp
.ne 2
.na
\fB\fB-x\fR \fIdebug_level\fR\fR
.ad
.RS 18n
\fBmail\fR creates a trace file containing debugging information.
.RE

.sp
.LP
The \fB-x\fR option causes \fBmail\fR to create a file named
\fB/tmp/MLDBG\fR\fIprocess_id\fR that contains debugging information relating
to how \fBmail\fR processed the current message. The absolute value of
\fIdebug_level\fR controls the verboseness of the debug information. \fB0\fR
implies no debugging. If \fIdebug_level\fR is greater than \fB0\fR, the debug
file is retained \fIonly\fR if \fBmail\fR encountered some problem while
processing the message. If \fIdebug_level\fR is less than \fB0\fR, the debug
file is always be retained. The \fIdebug_level\fR specified via \fB-x\fR
overrides any specification of \fBDEBUG\fR in \fB/etc/mail/mailcnfg\fR. The
information provided by the \fB-x\fR option is esoteric and is probably only
useful to system administrators.
.SS "Delivery Notification"
.sp
.LP
Several forms of notification are available for mail by including one of the
following lines in the message header.
.sp
.LP
\fBTransport-Options:\fR [ \fB/\fR\fIoptions\fR ]
.sp
.LP
\fBDefault-Options:\fR [ \fB/\fR\fIoptions\fR ]
.sp
.LP
\fB>To:\fR \fIrecipient\fR [ \fB/\fR\fIoptions\fR ]
.sp
.LP
Where the "/\fIoptions\fR" can be one or more of the following:
.sp
.ne 2
.na
\fB\fB/delivery\fR\fR
.ad
.RS 15n
Inform the sender that the message was successfully delivered to the
\fIrecipient\fR's mailbox.
.RE

.sp
.ne 2
.na
\fB\fB/nodelivery\fR\fR
.ad
.RS 15n
Do not inform the sender of successful deliveries.
.RE

.sp
.ne 2
.na
\fB\fB/ignore\fR\fR
.ad
.RS 15n
Do not inform the sender of failed deliveries.
.RE

.sp
.ne 2
.na
\fB\fB/return\fR\fR
.ad
.RS 15n
Inform the sender if mail delivery fails. Return the failed message to the
sender.
.RE

.sp
.ne 2
.na
\fB\fB/report\fR\fR
.ad
.RS 15n
Same as \fB/return\fR except that the original message is not returned.
.RE

.sp
.LP
The default is \fB/nodelivery/return\fR. If contradictory options are used, the
first is recognized and later, conflicting, terms are ignored.
.SH OPERANDS
.sp
.LP
The following operand is supported for sending mail:
.sp
.ne 2
.na
\fB\fIrecipient\fR\fR
.ad
.RS 13n
A domain style address ("\fIuser\fR@\fImachine\fR") or user login name
recognized by \fBlogin\fR(1).
.RE

.SH USAGE
.sp
.LP
See \fBlargefile\fR(5) for the description of the behavior of \fBmail\fR and
\fBrmail\fR when encountering files greater than or equal to 2 Gbyte ( 2^31
bytes).
.SH ENVIRONMENT VARIABLES
.sp
.LP
See \fBenviron\fR(5) for descriptions of the following environment variables
that affect the execution of \fBmail\fR: \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and
\fBNLSPATH\fR.
.sp
.ne 2
.na
\fB\fBTZ\fR\fR
.ad
.RS 6n
Determine the timezone used with date and time strings.
.RE

.SH EXIT STATUS
.sp
.LP
The following exit values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion when the user had mail.
.RE

.sp
.ne 2
.na
\fB\fB1\fR\fR
.ad
.RS 6n
The user had no mail or an initialization error occurred.
.RE

.sp
.ne 2
.na
\fB\fB>1\fR\fR
.ad
.RS 6n
An error occurred after initialization.
.RE

.SH FILES
.sp
.ne 2
.na
\fB\fBdead.letter\fR\fR
.ad
.RS 20n
unmailable text
.RE

.sp
.ne 2
.na
\fB\fB/etc/passwd\fR\fR
.ad
.RS 20n
to identify sender and locate \fIrecipient\fRs
.RE

.sp
.ne 2
.na
\fB\fB$HOME/mbox\fR\fR
.ad
.RS 20n
saved mail
.RE

.sp
.ne 2
.na
\fB\fB$MAIL\fR\fR
.ad
.RS 20n
variable containing path name of \fImailfile\fR
.RE

.sp
.ne 2
.na
\fB\fB/tmp/MLDBG\fR*\fR
.ad
.RS 20n
debug trace file
.RE

.sp
.ne 2
.na
\fB\fB/var/mail/*.lock\fR\fR
.ad
.RS 20n
lock for mail directory
.RE

.sp
.ne 2
.na
\fB\fB/var/mail/:saved\fR\fR
.ad
.RS 20n
directory for holding temp files to prevent loss of data in the event of a
system crash
.RE

.sp
.ne 2
.na
\fB\fB/var/mail/\fIuser\fR\fR\fR
.ad
.RS 20n
incoming mail for \fIuser\fR; that is, the \fImailfile\fR
.RE

.sp
.ne 2
.na
\fB\fBvar/tmp/ma\fR*\fR
.ad
.RS 20n
temporary file
.RE

.SH SEE ALSO
.sp
.LP
\fBchmod\fR(1), \fBcsh\fR(1), \fBlogin\fR(1), \fBmailx\fR(1), \fBuucp\fR(1C),
\fBuuencode\fR(1C), \fBvacation\fR(1), \fBwrite\fR(1), \fBattributes\fR(5),
\fBenviron\fR(5), \fBlargefile\fR(5)
.sp
.LP
\fISolaris Advanced User\&'s Guide\fR
.SH NOTES
.sp
.LP
The interpretation and resulting action taken because of the header lines
described in the Delivery Notifications section only occur if this version of
\fBmail\fR is installed on the system where the delivery (or failure) happens.
Earlier versions of \fBmail\fR might not support any types of delivery
notification.
.sp
.LP
Conditions sometimes result in a failure to remove a lock file.
.sp
.LP
After an interrupt, the next message might not be printed. Printing can be
forced by typing a \fBp\fR.