'\" t
.\" (the above line is to tell sun's man to run through tbl first)
.\"
.\"	To - send a one line message to another user
.\"
.\" Part of the CaSU package written by Luke Mewburn <lm@rmit.edu.au>
.\"
.\" To format this manual page, format it through a `tbl' compatible
.\" filter, then through an nroff or troff compatible formatter.
.\"
.\" This manual page is Copyright (C) 1993, 1994 by Luke Mewburn.
.\"
.TH TO 1 "April 21 1994"
.SH NAME
to \- send a one line message to another user.
.SH SYNOPSIS
.B to
.RB [ \-a\c
.IR "\ alias\ user" ]
.RB [ \-b ]
.RB [ \-e\c
.IR "\ user" ]
.RB [ \-h ]
.RB [ \-l ]
.RB [ \-r ]
.RB [ \-t\c
.IR "\ term" ]
.RB [ \-u\c
.IR "\ alias" ]
.RB [ \-n ]
.RB [ \-y ]
.RB [ \-P\c
.IR "\ pseudonym" ]
.RB [ \-G\c
.IR "\ gonereply" ]
.RB [ \-N\c
.IR "\ noreply" ]
.RB [ \-Y\c
.IR "\ yesreply" ]
.RB [ \-I\c
.IR "\ idlereply" ]
.RB [ \-X\c
.IR "\ excludereply" ]
[
.I user
[ 
.IR message
] ]
.SH DESCRIPTION
.I to
sends a short message to another user.
The default format for the message that the destination user receives is:
.IP
-=> From user ( userid@host ) on ttyxx at 12:00 :-
.br
.I message
.PP
The recipient of the message can, at this point, choose to reply
using the same method.
If the recipient has defined an
.B auto-reply
message, you will receive a message back of the form:
.IP
-=> Auto-reply from username :-
.br
.I message
.PP
All of the arguments to
.I to
after the username are treated as part of the message.
If a message isn't specified, then you are prompted to enter a
message interactively.
This is useful if you wish to enter a message that has characters
which would need to be escaped from the shell, and you're too
lazy to do that.
If no message is entered, then
.RI \` "I would like to talk to you" \'
is sent.
.PP
You can specify a user by a username, an alias, or with
.RB \` \&. \'
(a period.)
The use of a period indicates that you wish to send the message to
the last person that you sent a message to (if you've sent one.)
The message will be sent to the same tty as last time unless you
specify a new tty via the
.B \-t
option.
.PP
If an alias is defined for the user string you entered, it will be
used, otherwise 
.I to
will attempt to send the message to the user on the system with
that name.
.PP
If the recipient is logged on in more that one place, the message will
be sent to the terminal with the least idle time (unless a specific
terminal is requested via
.BR \-t .)
If you are sending a message to yourself, the current terminal will
only receive the message if you explicitly state it as the destination
terminal (This is useful if a friend is logged under your userid and
you wish to send them a message.)
.PP
You can exclude a user from transmitting a message to you by adding
them to your exclude list (by using the
.B \-e
command line option.)
.PP
Auto-reply messages are returned to you depending upon the conditions
in which the message was received.
They are:
.TP
.B gone
The auto-reply for when the recipient isn't logged on.
.TP
.B idle
The auto-reply for when you are idle more than 5 minutes (overrides the
.B yes
message.)
.TP
.B no
The auto-reply for when the message didn't get through.
.TP
.B yes
The auto-reply for when the message was successfully sent.
(Useful for when you are working or you're temporarily busy, and want
to let the message to still get through.)
.TP
.B exclude
The auto-reply message to people you've excluded.
.PP
By default,
.I to
uses your name from the
.B /etc/passwd
file.
This is overridden (in ascending order) by the environment variable
.BR NAME ,
the environment variable
.BR PSEUDONYM ,
and finally, the
.B \-p
command line option.
.PP
If you have your messages disabled, and you are sending a message to a user
other than yourself, you will receive a warning telling you that the the
recipient can't respond.
.SH OPTIONS
.I to
accepts the following options (in any combination):
.TP
.BI \-a " alias userid"
Define an alias,
.I alias
for the user
.IR "userid" .
.TP
.B \-b
Beep the recipient (with an ASCII BELL character.)
.TP
.BI \-e " userid"
Add
.I userid
to the list of people you've excluded from sending you messages.
.TP
.B \-h
Display a usage and help page.
.TP
.B \-l
List all the aliases that you have defined.
.TP
.B \-r
Display some status about
.IR to ,
including: mesg status, current name, current terminal, yes auto-reply,
no auto-reply, gone auto-reply, and last user.
.TP
.BI \-t " term"
Force the message to be sent to the terminal
.IR "term" .
It will only be sent if the recipient is currently using that terminal.
.TP
.BI \-u " alias"
Remove 
.I alias
from your alias list.
.TP
.BI "\-n, \-y"
Set the
.B mesg
status to off or on respectivly.
This performs the same purpose as
.IR "mesg" (1).
.TP
.BI \-P " pseudonym"
Sets your pseudonym.
.TP
.BI \-Y " yesmess"
Sets your auto-reply message for when a message gets through successfully.
.TP
.BI \-I " idlemess"
Sets your auto-reply message for when a message gets through
successfully and the recipient (you) has been idle for more than
five minutes.
.TP
.BI \-N " nomess"
Sets your auto-reply message for when a transmission is unsuccessful.
.TP
.BI \-G " gonemess"
Sets your auto-reply message for when you aren't logged on.
.TP
.BI \-X " excludemess"
Sets your auto-reply message to send to a person who you've excluded.
.TP
.B \-V
Display the usage and copyright information.
.SH ENVIRONMENT
.TP 12
.B PSEUDONYM
Name to display when sending messages and auto-replies.
.TP
.B NAME
Used if
.B PSEUDONYM
isn't defined.
.SH FILES
.PD 0
.TP 20
.B $\s-1HOME\s0/.torc
.TP 20
.B /etc/utmp
.TP 20
.B /etc/passwd
.PD
.PP
The
.B .torc
file is an ASCII file, which may be directly edited rather than using
the command line options (although the author doesn't recommend this
technique.)
Each line has the following format:
.br
\- A single character type specifier (case insensitive, but shown
with case here for mnemonic reference with the command line options.)
.br
\- A single space
.br
\- The arguments to the command.
.PP
The following characters are valid as type specifiers:
.TP 3
.B \&.
The last person to whom you sent a message.
.TP
.B :
The tty of the last person to whom you sent a message.
.TP
.B Y
The
.I yes
auto-reply.
.TP
.B N
The
.I no
auto-reply.
.TP
.B G
The
.I gone
auto-reply.
.TP
.B I
The
.I idle
auto-reply.
.TP
.B X
The
.I exclude
auto-reply.
.TP
.B P
The pseudonym which is printed in the auto-reply.
.TP
.B a
An alias. This takes the format of
.IR "alias userid" ,
with whitespace separating the two elements
.TP
.B e
An excluded user.
.PP
An unknown specifier or illegal line will be silently ignored by
.IR "to" .
.SH SEE ALSO
.IR "mesg" (1),
.IR "utmp" (5),
.IR "talk" (1),
.IR "write" (1).
.SH LIMITATIONS
The maximum length of a userid is 8 characters.
The maximum length of an alias is 16 characters.
The maximum length of an auto-reply, pseudonym, or message is 256 characters.
Any non-ASCII, or control characters in the message will be replaced with
a
.RB \` ? \'\&.
.PP
.I to
can only send an auto-reply message to another user if that user has
world read access (\fI\-rw\-r\-\-r\-\-\fP) to your
.I .torc
file, and at least search access (\fIdrwx\-\-x\-\-x\fP)
to your home directory.
.PP
The message that you send appears on the command line, and thus, can
be read (for a short time), by the use of commands such as
.IR "ps" (1).
If you want to send top secret or personal messages, you shouldn't
be using electronic media!
.SH HISTORY
.I to
was inspired by (and is upwardly compatible with) a program written
by Steve Riehm [Romulis].
Steve's version was based on one by Simon Burge [Snark].
.PP
For their inspiration, ideas and bug reports, thanks must go to:
.TS
center;
l l.
Andrew Vanderstock	<rxkajv@minyos.xx.rmit.oz.au>
Craig Humphrey	<Craig.Humphrey@comp.vuw.ac.nz>
John DuBois	<spcecdt@armory.com>
Keith	<basil@cs.odu.edu>
Ken Weaverling	<weave@pima.dtcc.edu>
Marc Boschma	<s861298@minyos.xx.rmit.oz.au>
Steve Riehm	<ln_smr@pki-nbg.philips.de>
Willem Kasdorp	<wkasdo@nikhefk.nikhef.nl>
.TE
.SH AUTHOR
Luke Mewburn, <lm@rmit.edu.au>.
.SH VERSION
This manual documents
.I to
version 3.3.3, 940421.