Documented the '~$' (local process -> remote host) command.

[unix-history] / usr / src / usr.bin / tip / tip.1

diff --git a/usr/src/usr.bin/tip/tip.1 b/usr/src/usr.bin/tip/tip.1
index d7245f8..16771b4 100644 (file)
--- a/usr/src/usr.bin/tip/tip.1
+++ b/usr/src/usr.bin/tip/tip.1
@@ -2,209 +2,399 @@
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"
 .\" All rights reserved.  The Berkeley software License Agreement
 .\" specifies the terms and conditions for redistribution.
 .\"

-.\"    @(#)tip.1       4.1 (Berkeley) %G%
+.\"    @(#)tip.1       6.2 (Berkeley) %G%

 .\"
 .\"

-.TH CU 1C 4/1/81
+.TH TIP 1C ""

 .UC 4
 .SH NAME
 .UC 4
 .SH NAME

-cu \- call UNIX
+tip, cu \- connect to a remote system

 .SH SYNOPSIS
 .SH SYNOPSIS

-.B cu
-telno
+.B tip

 [
 [

-.B \-t
-]
+.B \-v
+] [
+.BI \- speed
+] system-name
+.br
+.B tip

 [
 [

-.BI \- n
+.B \-v
+] [
+.BI \- speed
+] phone-number
+.br
+.B cu
+phone-number

 [
 [

+.B \-t
+] [

 .B \-s
 .B \-s

-speed ]
-[
-.B \-a
-acu ]
-[
+.I speed
+] [
+.B \ -a
+.I acu
+] [

 .B \-l
 .B \-l

-line ]
-[
-.B \-b
+.I line
+] [
+.B \-#

 ]
 .SH DESCRIPTION
 ]
 .SH DESCRIPTION

-.I Cu
-calls up another UNIX system,
-a terminal,
-or possibly a non-UNIX system.
-It manages an interactive conversation with possible
-transfers of text files.
-.I Telno
-is the telephone number,
-with minus signs at appropriate places for delays.
-The
-.BR \-t ""
-flag is used to dial out to a terminal.
-.I Speed
-gives the transmission speed (110, 134, 150, 300, 1200);
-300 is the default value.
-.PP
-The
-.B \-a
+.I Tip

 and
 and

-.B \-l
-values may be used to
-specify pathnames
-for the ACU and communications line devices.
-They can be used to override the following
-built-in choices:
+.I cu
+establish a full-duplex connection to another machine,
+giving the appearance of being logged in directly on the
+remote cpu.  It goes without saying that you must have a login
+on the machine (or equivalent) to which you wish to connect.
+The preferred interface is
+.IR tip .
+The
+.I cu
+interface is included for those people attached to the
+``call UNIX'' command of version 7.  This manual page
+describes only 
+.IR tip .

 .PP
 .PP

-.BR \-a " /dev/cua0"
-.BR \-l " /dev/cul0"
+Typed characters are normally transmitted directly to the remote
+machine (which does the echoing as well).  A tilde (`~') appearing
+as the first character of a line is an escape signal; the following
+are recognized:
+.TP 10
+.B ~^D ~.
+Drop the connection and exit
+(you may still be logged in on the
+remote machine).
+.TP 10
+\fB~c \fP [\fIname\fP]
+Change directory to name (no argument
+implies change to your home directory).
+.TP 10
+.B ~!
+Escape to a shell (exiting the shell will
+return you to tip).
+.TP 10
+.B ~>
+Copy file from local to remote.
+.I Tip
+prompts for the name of a local file to transmit.
+.TP 10
+.B ~<
+Copy file from remote to local.
+.I Tip
+prompts first for the name of the file to be sent, then for
+a command to be executed on the remote machine.
+.TP 10
+\fB~p\fP \fIfrom\fP [ \fIto\fP ]
+Send a file to a remote UNIX host.  The put command causes the remote UNIX
+system to run the command string ``cat > 'to''', while
+.I tip
+sends it the ``from''
+file.  If the ``to'' file isn't specified the ``from'' file name is used.
+This command is actually a UNIX specific version of the ``~>'' command.
+.TP 10
+\fB~t\fP \fIfrom\fP [ \fIto\fP ]
+Take a file from a remote UNIX host. 
+As in the put command the ``to'' file
+defaults to the ``from'' file name if it isn't specified. 
+The remote host
+executes the command string ``cat 'from';echo ^A'' to send the file to
+.IR tip .
+.TP 10
+.B ~|
+Pipe the output from a remote command to a local UNIX process.
+The command string sent to the local UNIX system is processed by the shell.
+.TP 10
+.B ~$
+Pipe the output from a local UNIX process to the remote host.
+The command string sent to the local UNIX system is processed by the shell.
+.TP 10
+.B ~#
+Send a BREAK to the remote system. 
+For systems which don't support the
+necessary
+.I ioctl
+call the break is simulated by a sequence of line speed changes
+and DEL characters.
+.TP 10
+.B ~s
+Set a variable (see the discussion below).
+.TP 10
+.B ~^Z
+Stop
+.I tip
+(only available with job control).
+.TP 10
+.B ~?
+Get a summary of the tilde escapes
+.sp

 .PP
 .PP

-The
-.BI \- n
-option, where
-.I n
-is a single digit,
-changes the last character of the ACU and communications line to
-.IR n .
-It is an abbreviation for
-.BI "\-a /dev/cua" n " \-l /dev/cul" n .
+.I Tip
+uses the file /etc/remote to find how to reach a particular
+system and to find out how it should operate while talking
+to the system;
+refer to
+.IR remote (5)
+for a full description.
+Each system has a default baud rate with which to
+establish a connection.  If this value is not suitable, the baud rate
+to be used may be specified on the command line, e.g. ``tip -300 mds''.

 .PP
 .PP

-After making the connection,
-.I cu
-runs as two processes:
-the
-.I send
-process reads the standard input and
-passes most of it to the remote system;
-the
-.I receive
-process reads from the remote system and passes
-most data to the standard output.
-Lines beginning with `~' have special meanings.
+When
+.I tip
+establishes a connection it sends out a
+connection message to the remote system; the default value, if any,
+is defined in /etc/remote.

 .PP
 .PP

-The
-.I send
-process interprets the following:
-.TP 18
-~\|\fB.\|
-terminate the conversation.
-.br
-.ns
-.TP 18
-~EOT
-terminate the conversation
-.TP 18
-~<file
-send the contents of
-.I file
-to the remote system,
-as though typed at the terminal.
-.TP 18
-\~^Z
-suspend the cu process.
-Note that the control-Z must be followed by a newline.
-.TP 18
-\~#
-sends a break.
-.TP 18
-~!
-invoke an interactive shell on the local system.
-.TP 18
-~!cmd ...
-run the command on the local system
-(via
-.BR "sh \-c" ")."
-.TP 18
-~$cmd ...
-run the command locally and send its output
-to the remote system.
-.TP 18
-~%take from [to]
-copy file `from' (on the remote system)
-to file `to' on the local system.
-If `to' is omitted,
-the `from' name is used both places.
-.TP 18
-~%put from [to]
-copy file `from' (on local system)
-to file `to' on remote system.
-If `to' is omitted, the `from' name is used both places.
-.TP 18
-~:
-during an output diversion, this toggles whether the operation of
-.I cu
-will be silent, i.e., whether information received from the foreign
-system will be written to the standard output.
-This allows a ``progress report'' during long transfers.
-.TP 18
-~~\fB\|.\|.\|.\fR
-send
-the line `~\|.\|.\|.'.
+When
+.I tip
+prompts for an argument (e.g. during setup of
+a file transfer) the line typed may be edited with the standard
+erase and kill characters.  A null line in response to a prompt,
+or an interrupt, will abort the dialogue and return you to the
+remote machine.

 .PP
 .PP

-Both the
-.I send
-and
-.I receive
-processes handles output diversions of the following form:
+.I Tip
+guards against multiple users connecting to a remote system
+by opening modems and terminal lines with exclusive access,
+and by honoring the locking protocol used by
+.IR uucp (1C).

 .PP
 .PP

-\&~>[>][:]file
-.br
-zero or more lines to be written to file
-.br
-\&~>
+During file transfers 
+.I tip
+provides a running count of the number of lines transferred.
+When using the ~> and ~< commands, the ``eofread'' and ``eofwrite''
+variables are used to recognize end-of-file when reading, and
+specify end-of-file when writing (see below).  File transfers
+normally depend on tandem mode for flow control.  If the remote
+system does not support tandem mode, ``echocheck'' may be set
+to indicate
+.I tip
+should synchronize with the remote system on the echo of each
+transmitted character.

 .PP
 .PP

-In any case, output is diverted (or appended, if `>>' used) to the file.
-If `:' is used,
-the diversion is
-.I silent,
-i.e., it is written only to the file.
-If `:' is omitted,
-output is written both to the file and to the standard output.
-The trailing `~>' terminates the diversion.
+When
+.I tip
+must dial a phone number to connect to a system it will print
+various messages indicating its actions.
+.I Tip
+supports the DEC DN-11 and Racal-Vadic 831 auto-call-units;
+the DEC DF02 and DF03, Ventel 212+, Racal-Vadic 3451, and
+Bizcomp 1031 and 1032 integral call unit/modems.

 .PP
 .PP

-The use of
-.B  ~%put
-requires
-.I stty
-and
-.I cat
-on the remote side.
-It also requires that the
-current erase and kill characters on the remote
-system be identical to the current ones on the local system.
-Backslashes are inserted at appropriate places.
+.SM
+.B VARIABLES

 .PP
 .PP

-The use of
-.B  ~%take
-requires the existence of
-.I echo
+.I Tip
+maintains a set of
+.I variables
+which control its operation.
+Some of these variable are read-only to normal users (root is allowed
+to change anything of interest).  Variables may be displayed
+and set through the ``s'' escape.  The syntax for variables is patterned
+after
+.IR vi (1)

 and
 and

-.I tee
-on the remote system.
-Also,
-.B "stty tabs"
-mode is required on the remote system if
-tabs are to be copied without expansion.
+.IR Mail (1).
+Supplying ``all''
+as an argument to the set command displays all variables readable by
+the user.  Alternatively, the user may request display of a particular
+variable by attaching a `?' to the end.  For example ``escape?''
+displays the current escape character.

 .PP
 .PP

-Finally, the
-.BR \-b
-flag specifies that nulls are to be turned into breaks.
-This allows the break key (and also control-shift-@) to send a break.
-.SH FILES
-/dev/cua0
+Variables are numeric, string, character, or boolean values.  Boolean
+variables are set merely by specifying their name; they may be reset
+by prepending a `!' to the name.  Other variable types are set by
+concatenating an `=' and the value.  The entire assignment must not
+have any blanks in it.  A single set command may be used to interrogate
+as well as set a number of variables.
+Variables may be initialized at run time by placing set commands
+(without the ``~s'' prefix in a file
+.I .tiprc
+in one's home directory).  The
+.B \-v
+option causes
+.I tip
+to display the sets as they are made.
+Certain common variables have abbreviations. 
+The following is a list of common variables,
+their abbreviations, and their default values.
+.TP
+.B beautify

 .br
 .br

-/dev/cul0
+(bool) Discard unprintable characters when a session is being scripted;
+abbreviated 
+.IR be .
+.TP
+.B baudrate

 .br
 .br

-/dev/null
+(num) The baud rate at which the connection was established;
+abbreviated
+.IR ba .
+.TP
+.B dialtimeout

 .br
 .br

-/usr/spool/uucp/LCK..cu[al][0-7]
-.SH "SEE ALSO"
-rv(4), tty(4)
+(num) When dialing a phone number, the time (in seconds)
+to wait for a connection to be established; abbreviated
+.IR dial .
+.TP
+.B echocheck
+.br
+(bool) Synchronize with the remote host during file transfer by
+waiting for the echo of the last character transmitted; default is
+.IR off .
+.TP
+.B eofread
+.br
+(str) The set of characters which signify and end-of-tranmission
+during a ~< file transfer command; abbreviated
+.IR eofr .
+.TP
+.B eofwrite
+.br
+(str) The string sent to indicate end-of-transmission during
+a ~> file transfer command; abbreviated
+.IR eofw .
+.TP
+.B eol
+.br
+(str) The set of characters which indicate an end-of-line.
+.I Tip
+will recognize escape characters only after an end-of-line.
+.TP
+.B escape
+.br
+(char) The command prefix (escape) character; abbreviated
+.IR es ;
+default value is `~'.
+.TP
+.B exceptions
+.br
+(str) The set of characters which should not be discarded
+due to the beautification switch; abbreviated
+.IR ex ;
+default value is ``\et\en\ef\eb''.
+.TP
+.B force
+.br
+(char) The character used to force literal data transmission;
+abbreviated
+.IR fo ;
+default value is `^P'.
+.TP
+.B framesize
+.br
+(num) The amount of data (in bytes) to buffer between file system
+writes when receiving files; abbreviated
+.IR fr .
+.TP
+.B host
+.br
+(str) The name of the host to which you are connected; abbreviated
+.IR ho .
+.TP
+.B prompt
+.br
+(char) The character which indicates and end-of-line on the remote
+host; abbreviated
+.IR pr ;
+default value is `\en'.  This value is used to synchronize during
+data transfers.  The count of lines transferred during a file transfer
+command is based on recipt of this character.
+.TP
+.B raise
+.br
+(bool) Upper case mapping mode; abbreviated 
+.IR ra ;
+default value is 
+.IR off .
+When this mode is enabled, all lower case letters will be mapped to
+upper case by
+.I tip
+for transmission to the remote machine.
+.TP
+.B raisechar
+.br
+(char) The input character used to toggle upper case mapping mode;
+abbreviated
+.IR rc ;
+default value is `^A'.
+.TP
+.B record
+.br
+(str) The name of the file in which a session script is recorded;
+abbreviated
+.IR rec ;
+default value is ``tip.record''.
+.TP
+.B script
+.br
+(bool) Session scripting mode; abbreviated
+.IR sc ;
+default is 
+.IR off .
+When
+.I script
+is 
+.IR true ,
+.I tip
+will record everything transmitted by the remote machine in
+the script record file specified in
+.IR record .
+If the
+.I beautify
+switch is on, only printable ASCII characters will be included in
+the script file (those characters betwee 040 and 0177).  The
+variable
+.I exceptions
+is used to indicate characters which are an exception to the normal
+beautification rules.
+.TP
+.B tabexpand
+.br
+(bool) Expand tabs to spaces during file transfers; abbreviated
+.IR tab ;
+default value is
+.IR false .
+Each tab is expanded to 8 spaces.
+.TP
+.B verbose
+.br
+(bool) Verbose mode; abbreviated
+.IR verb ;
+default is 
+.IR true .
+When verbose mode is enabled, 
+.I tip
+prints messages while dialing, shows the current number
+of lines transferred during a file transfer operations,
+and more.
+.TP
+.B SHELL
+.br
+(str) The name of the shell to use for the ~! command; default
+value is ``/bin/sh'', or taken from the environment.
+.TP
+.B HOME
+.br
+(str) The home directory to use for the ~c command; default
+value is taken from the environment.
+.PP
+.SH FILES
+.ta \w'/usr/spool/uucp/LCK..*   'u
+.nf
+/etc/remote    global system descriptions
+/etc/phones    global phone number data base
+${REMOTE}      private system descriptions
+${PHONES}      private phone numbers
+~/.tiprc       initialization file.
+/usr/spool/uucp/LCK..* lock file to avoid conflicts with \fIuucp\fP
+.fi

 .SH DIAGNOSTICS
 .SH DIAGNOSTICS

-Exit code is
-zero for normal exit,
-nonzero (various values) otherwise.
+Diagnostics are, hopefully, self explanatory.
+.SH "SEE ALSO"
+remote(5),
+phones(5)

 .SH BUGS
 .SH BUGS

-Only
-.IR mail (1)
-uses syntax anything like the syntax of
-.I cu.
+The full set of variables is undocumented and should, probably, be
+paired down.