docs: Added All OpenBSD Manuals

1 files changed, 634 insertions, 0 deletions

diff --git a/static/openbsd/man8/chat.8 b/static/openbsd/man8/chat.8
new file mode 100644
index 00000000..76e722b4
--- /dev/null
+++ b/static/openbsd/man8/chat.8
@@ -0,0 +1,634 @@
+.\"	$OpenBSD: chat.8,v 1.21 2023/08/07 06:21:53 guenther Exp $
+.\" Id: chat.8,v 1.7 1998/02/04 01:35:49 paulus Exp $
+.\" manual page [] for chat 1.8
+.Dd $Mdocdate: August 7 2023 $
+.Dt CHAT 8
+.Os
+.Sh NAME
+.Nm chat
+.Nd automated conversational script with a modem
+.Sh SYNOPSIS
+.Nm chat
+.Op Fl eSsVv
+.Bk -words
+.Op Fl f Ar chat_file
+.Op Fl r Ar report_file
+.Op Fl T Ar phone_number
+.Op Fl t Ar timeout
+.Op Fl U Ar phone_number_2
+.Ar script
+.Ek
+.Sh DESCRIPTION
+The
+.Nm
+program defines a conversational exchange between the computer and the modem.
+Its primary purpose is to establish a connection between the
+Point-to-Point Protocol Daemon
+.Pf ( Xr pppd 8 )
+and the remote's pppd process.
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Fl e
+Start with the echo option turned on.
+Echoing may also be turned on or off at specific points in the chat script
+by using the
+.Ic ECHO
+keyword.
+When echoing is enabled, all output from the modem is echoed to
+.Ar stderr .
+.It Fl f Ar chat_file
+Read the chat script from the
+.Ar chat_file .
+The use of this option is mutually exclusive with the chat
+.Ar script
+parameter.
+The user must have read access to the file.
+Multiple lines are permitted in the file.
+Space or horizontal tab characters should be used to separate the strings.
+.It Fl r Ar report_file
+Set the file for output of the report strings.
+If you use the keyword
+.Ic REPORT ,
+the resulting strings are written to this file.
+If this option is not used and you still use
+.Ic REPORT
+keywords, the
+.Ar stderr
+file is used for the report strings.
+.It Fl S
+Do not use
+.Xr syslog 3 .
+By default, error messages are logged through
+.Xr syslog 3
+with facility
+.Dq local2
+and level
+.Dq warning .
+The use of
+.Fl S
+will prevent both log messages from
+.Fl v
+and error messages from being logged via
+.Xr syslog 3 .
+.It Fl s
+Use
+.Ar stderr .
+All log messages from
+.Fl v
+and all error messages will be sent to
+.Ar stderr .
+.It Fl T Ar phone_number
+Pass in an arbitrary string, usually a phone number, that will be
+substituted for the \eT substitution metacharacter in a send string.
+.It Fl t Ar timeout
+Set the timeout for the expected string to be received.
+If the string is not received within the time limit then the reply string
+is not sent.
+An alternate reply may be sent or the script will fail if there
+is no alternate reply string.
+A failed script will cause the
+.Nm
+program to terminate with a non-zero error code.
+.It Fl U Ar phone_number_2
+Pass in a second string, usually a phone number, that will be
+substituted for the \eU substitution metacharacter in a send string.
+This is useful when dialing an ISDN terminal adapter that requires two numbers.
+.It Fl V
+Request that the chat script be executed in a
+.Ar stderr
+verbose mode.
+The
+.Nm
+program will then log all text received from the modem and the output strings
+sent to the modem to the
+.Ar stderr
+device.
+This device is usually the local console at the station running the
+.Nm
+or
+.Xr pppd 8
+program.
+.It Fl v
+Request that the chat script be executed in a verbose mode.
+The
+.Nm
+program will then log the execution state of the chat script as well as all
+text received from the modem and the output strings sent to the modem.
+The default is to log through
+.Xr syslog 3
+with level
+.Dq info ,
+though this may be altered with the
+.Fl S
+and
+.Fl s
+flags.
+.It Ar script
+If the script is not specified in a file with the
+.Fl f
+option, then the script is included as parameters to the
+.Nm
+program.
+.El
+.Sh CHAT SCRIPT
+The chat script defines the communications.
+.Pp
+A script consists of one or more
+.Dq expect-send
+pairs of strings,
+separated by spaces, with an optional
+.Dq subexpect-subsend
+string pair, separated by a dash as in the following example:
+.Pp
+.Dl ogin:-BREAK-ogin: ppp ssword: hello2u2
+.Pp
+This line indicates that the
+.Nm
+program should expect the string
+.Dq ogin: .
+If it fails to receive a login prompt within the time interval allotted,
+it is to send a break sequence to the remote and then expect the
+string
+.Dq ogin: .
+If the first
+.Dq ogin:
+is received then the break sequence is not generated.
+.Pp
+Once it receives the login prompt, the
+.Nm
+program will send the string ppp and then expect the prompt
+.Dq ssword: .
+When it receives the prompt for the password, it will send the password
+hello2u2.
+.Pp
+A carriage return is normally sent following the reply string.
+It is not expected in the
+.Dq expect
+string unless it is specifically requested by using the \er character sequence.
+.Pp
+The expect sequence should contain only what is needed to identify the string.
+Since it is normally stored on a disk file, it should not contain
+variable information.
+It is generally not acceptable to look for time strings, network
+identification strings, or other variable pieces of data as an expect string.
+.Pp
+To help correct for characters which may be corrupted during the initial
+sequence, look for the string
+.Dq ogin:
+rather than
+.Dq login: .
+It is possible that the leading
+.Dq l
+character may be received in error and you may never find the string
+even though it was sent by the system.
+For this reason, scripts look for
+.Dq ogin:
+rather than
+.Dq login:
+and
+.Dq ssword:
+rather than
+.Dq password: .
+.Pp
+A very simple script might look like this:
+.Pp
+.Dl ogin: ppp ssword: hello2u2
+.Pp
+In other words, expect ....ogin:, send ppp, expect ...ssword:, send hello2u2.
+.Pp
+In actual practice, simple scripts are rare.
+At the very least, you should include sub-expect sequences should the
+original string not be received.
+For example, consider the following script:
+.Pp
+.Dl ogin:--ogin: ppp ssword: hello2u2
+.Pp
+This would be a better script than the simple one used earlier.
+This would look for the same login: prompt.
+If one is not received, a single return sequence is sent and then it will
+look for login: again.
+Should line noise obscure the first login prompt then sending the empty line
+will usually generate a login prompt again.
+.Sh COMMENTS
+Comments can be embedded in the chat script.
+A comment is a line which starts with the
+.Sq #
+(hash) character in column 1.
+Such comment lines are just ignored by the
+.Nm
+program.
+If a
+.Sq #
+character is to be expected as the first character of the expect sequence,
+you should quote the expect string.
+If you want to wait for a prompt that starts with a
+.Sq #
+(hash) character, you would have to write something like this:
+.Bd -literal -offset indent
+# Now wait for the prompt and send logout string
+\'# ' logout
+.Ed
+.Sh ABORT STRINGS
+Many modems will report the status of the call as a string.
+These strings may be
+.Em CONNECT
+or
+.Em NO CARRIER
+or
+.Em BUSY .
+It is often desirable to terminate the script should the modem fail to
+connect to the remote.
+The difficulty is that a script would not know exactly which modem string
+it may receive.
+On one attempt it may receive
+.Em BUSY ,
+while the next time it may receive
+.Em NO CARRIER .
+.Pp
+These
+.Dq abort
+strings may be specified in the script using the
+.Ic ABORT
+sequence.
+It is written in the script as in the following example:
+.Pp
+.Dl "ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT"
+.Pp
+This sequence will expect nothing; and then send the string ATZ.
+The expected response to this is the string
+.Em OK .
+When it receives
+.Em OK ,
+it sends the string ATDT5551212 to dial the telephone.
+The expected string is
+.Em CONNECT .
+If the string
+.Em CONNECT
+is received, the remainder of the script is executed.
+However, should the modem find a busy telephone, it will send the string
+.Em BUSY .
+This will cause the string to match the abort character sequence.
+The script will then fail because it found a match to the abort string.
+If it received the string
+.Em NO CARRIER ,
+it will abort for the same reason.
+Either string may be received.
+Either string will terminate the chat script.
+.Sh CLR_ABORT STRINGS
+This sequence allows for clearing previously set
+.Ic ABORT
+strings.
+.Ic ABORT
+strings are kept in an array of a pre-determined size (at compilation time);
+.Ic CLR_ABORT
+will reclaim the space for cleared entries so that new strings can use
+that space.
+.Sh SAY STRINGS
+The
+.Ic SAY
+directive allows the script to send strings to the user
+at the terminal via standard error.
+If
+.Nm
+is being run by
+.Xr pppd 8 ,
+and pppd is running as a daemon (detached from its controlling terminal),
+standard error will normally be redirected to the file
+.Pa /etc/ppp/connect-errors .
+.Pp
+.Ic SAY
+strings must be enclosed in single or double quotes.
+If carriage return and line feed are needed in the string to be output,
+you must explicitly add them to your string.
+.Pp
+The
+.Ic SAY
+strings could be used to give progress messages in sections of
+the script where you want to have 'ECHO OFF' but still let the user
+know what is happening.
+An example is:
+.Bd -literal -offset indent
+ABORT BUSY
+ECHO OFF
+SAY "Dialling your ISP...\en"
+\'' ATDT5551212
+TIMEOUT 120
+SAY "Waiting up to 2 minutes for connection ... "
+CONNECT ''
+SAY "\enConnected, now logging in ...\en"
+ogin: account
+ssword: pass
+$ \c
+SAY "Logged in OK ...\en"
+etc ...
+.Ed
+.Pp
+This sequence will only present the
+.Ic SAY
+strings to the user and all the details of the script will remain hidden.
+For example, if the above script works, the user will see:
+.Bd -literal -offset indent
+Dialling your ISP...
+Waiting up to 2 minutes for connection ...
+Connected, now logging in ...
+Logged in OK ...
+.Ed
+.Sh REPORT STRINGS
+A report string is similar to the
+.Ic ABORT
+string.
+The difference is that the strings, and all characters to the next control
+character such as a carriage return, are written to the report file.
+.Pp
+The report strings may be used to isolate the transmission rate of the
+modem's connect string and return the value to the
+.Nm
+user.
+The analysis of the report string logic occurs in conjunction with the
+other string processing such as looking for the expect string.
+The use of the same string for a report and abort sequence is probably not
+very useful; however, it is possible.
+.Pp
+The report strings do not change the completion code of the program.
+.Pp
+These
+.Dq report
+strings may be specified in the script using the
+.Ic REPORT
+sequence.
+It is written in the script as in the following example:
+.Pp
+.Dl "REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account"
+.Pp
+This sequence will expect nothing; and then send the string
+ATDT5551212 to dial the telephone.
+The expected string is
+.Em CONNECT .
+If the string
+.Em CONNECT
+is received, the remainder of the script is executed.
+In addition the program will write to the expect-file the string
+.Dq CONNECT
+plus any characters which follow it such as the connection rate.
+.Sh CLR_REPORT STRINGS
+This sequence allows for clearing previously set
+.Ic REPORT
+strings.
+.Ic REPORT
+strings are kept in an array of a pre-determined size (at compilation time);
+.Ic CLR_REPORT
+will reclaim the space for cleared entries so that new strings can use
+that space.
+.Sh ECHO
+The echo options controls whether the output from the modem is echoed to
+.Ar stderr .
+This option may be set with the
+.Fl e
+option, but it can also be controlled by the
+.Ic ECHO
+keyword.
+The
+.Dq expect-send
+pair
+.Ic ECHO ON
+enables echoing, and
+.Ic ECHO OFF
+disables it.
+With this keyword you can select which parts of the conversation should be
+visible.
+For instance, with the following script:
+.Bd -literal -offset indent
+ABORT   'BUSY'
+ABORT   'NO CARRIER'
+\&''      ATZ
+OK\er\en  ATD1234567
+\er\en    \ec
+ECHO    ON
+CONNECT \ec
+ogin:   account
+.Ed
+.Pp
+all output resulting from modem configuration and dialing is not visible,
+but starting with the
+.Em CONNECT
+(or
+.Em BUSY )
+message, everything will be echoed.
+.Sh HANGUP
+The
+.Ic HANGUP
+options control whether a modem hangup should be considered as an error or not.
+This option is useful in scripts for dialing systems which will hang up and
+call your system back.
+The
+.Ic HANGUP
+options can be
+.Ic ON
+or
+.Ic OFF .
+.Pp
+When
+.Ic HANGUP
+is set
+.Ic OFF
+and the modem hangs up (e.g., after the first stage of logging in to a
+callback system),
+.Nm
+will continue running the script
+(e.g., waiting for the incoming call and second-stage login prompt).
+As soon as the incoming call is connected, you should use the
+.Ic HANGUP ON
+directive to reinstall normal hangup signal behavior.
+Here is an example script:
+.Bd -literal -offset indent
+ABORT   'BUSY'
+\&''      ATZ
+OK\er\en  ATD1234567
+\er\en    \ec
+CONNECT \ec
+\'Callback login:' call_back_ID
+HANGUP OFF
+ABORT "Bad Login"
+\'Callback Password:' Call_back_password
+TIMEOUT 120
+CONNECT \ec
+HANGUP ON
+ABORT "NO CARRIER"
+ogin:--BREAK--ogin: real_account
+etc ...
+.Ed
+.Sh TIMEOUT
+The initial timeout value is 45 seconds.
+This may be changed using the
+.Fl t
+parameter.
+.Pp
+The following example illustrates how to change the timeout value for
+the next expect string:
+.Pp
+.Dl "ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 assword: hello2u2"
+.Pp
+This will change the timeout to 10 seconds when it expects the login: prompt.
+The timeout is then changed to 5 seconds when it looks for the password prompt.
+.Pp
+The timeout, once changed, remains in effect until it is changed again.
+.Sh SENDING EOT
+The special reply string of
+.Ic EOT
+indicates that the
+.Nm
+program should send an EOT character to the remote.
+This is normally the End-of-file character sequence.
+A return character is not sent following the EOT.
+The EOT sequence may be embedded into the send string using the sequence
+.Em ^D .
+.Sh GENERATING BREAK
+The special reply string of
+.Ic BREAK
+will cause a break condition to be sent.
+The break is a special signal on the transmitter.
+The normal processing on the receiver is to change the transmission rate.
+It may be used to cycle through the available transmission rates on
+the remote until you are able to receive a valid login prompt.
+The break sequence may be embedded into the send string using the
+.Em \eK
+sequence.
+.Sh ESCAPE SEQUENCES
+The expect and reply strings may contain escape sequences.
+All of the sequences are legal in the reply string.
+Many are legal in the expect string.
+Those which are not valid in the expect sequence are so indicated.
+.Bl -tag -width Ds
+.It ''
+Expects or sends a null string.
+If you send a null string then it will still send the return character.
+This sequence may be a pair of either apostrophe or quote characters.
+.It \eb
+Represents a backspace character.
+.It \ec
+Suppresses the newline at the end of the reply string.
+This is the only method to send a string without a trailing return character.
+It must be at the end of the send string.
+For example, the sequence
+.Qq hello\ec
+will simply send the characters h, e, l, l, o.
+(Not valid in expect.)
+.It \ed
+Delay for one second.
+The program uses
+.Xr sleep 3
+to sleep for one second.
+(Not valid in expect.)
+.It \eK
+Insert a
+.Ic BREAK .
+(Not valid in expect.)
+.It \en
+Send a newline or linefeed character.
+.It \eN
+Send a NUL character.
+The same sequence may be represented by \e0.
+(Not valid in expect.)
+.It \ep
+Pause for a fraction of a second.
+The delay is 1/10th of a second.
+(Not valid in expect.)
+.It \eq
+Suppress writing the string to the
+.Xr syslog 3
+file.
+The string
+.Dq hidden
+is written to the log in its place.
+(Not valid in expect.)
+.It \er
+Send or expect a carriage return.
+.It \es
+Represents a space character in the string.
+This may be used when it is not desirable to quote the strings which
+contain spaces.
+The sequence 'HI TIM' and HI\esTIM are the same.
+.It \et
+Send or expect a tab character.
+.It \e\e
+Send or expect a backslash character.
+.It \eddd
+Collapse the octal digits (ddd) into a single ASCII character and send that
+character.
+(Some characters are not valid in expect.)
+.It ^C
+Substitute the sequence with the control character represented by C.
+For example, the character DC1 (17) is shown as ^Q.
+(Some characters are not valid in expect.)
+.El
+.Sh TERMINATION CODES
+The
+.Nm
+program will terminate with the following completion codes:
+.Bl -tag -width Ds
+.It 0
+The normal termination of the program.
+This indicates that the script was executed without error to the normal
+conclusion.
+.It 1
+One or more of the parameters are invalid or an expect string was too
+large for the internal buffers.
+This indicates that the program was not properly executed.
+.It 2
+An error occurred during the execution of the program.
+This may be due to a read or write operation failing for some reason or
+.Nm
+receiving a signal such as
+.Dv SIGINT .
+.It 3
+A timeout event occurred when there was an
+.Dq expect
+string without having a
+.Dq \-subsend
+string.
+This may mean that you did not program the script correctly for the condition
+or that some unexpected event has occurred and the expected string could not
+be found.
+.It 4
+The first string marked as an
+.Ic ABORT
+condition occurred.
+.It 5
+The second string marked as an
+.Ic ABORT
+condition occurred.
+.It 6
+The third string marked as an
+.Ic ABORT
+condition occurred.
+.It 7
+The fourth string marked as an
+.Ic ABORT
+condition occurred.
+.It ...
+The other termination codes are also strings marked as an
+.Ic ABORT
+condition.
+.El
+.Pp
+Using the termination code, it is possible to determine which event
+terminated the script.
+It is possible to decide if the string
+.Dq BUSY
+was received from the modem as opposed to
+.Dq NO DIAL TONE .
+While the first event may be retried, the second will probably have little
+chance of succeeding during a retry.
+.\" .Sh SEE ALSO
+.\" Additional information about chat scripts may be found with UUCP
+.\" documentation.
+.\" The chat script was taken from the ideas proposed
+.\" by the scripts used by the uucico program.
+.\" .Pp
+.\" .Xr uucp 1
+.Sh COPYRIGHT
+The
+.Nm
+program is in the public domain.
+This is not the GNU public license.
+If it breaks then you get to keep both pieces.