1.\" -*- nroff -*- 2.\" manual page [] for chat 1.8 3.\" $FreeBSD: src/usr.bin/chat/chat.8,v 1.15.2.3 2003/02/24 22:37:41 trhodes Exp $ 4.Dd October 17, 2017 5.Dt CHAT 8 6.Os 7.Sh NAME 8.Nm chat 9.Nd Automated conversational script with a modem 10.Sh SYNOPSIS 11.Nm 12.Op Fl evVsS 13.Op Fl f Ar chat_file 14.Op Fl r Ar report_file 15.Op Fl t Ar timeout 16.Op Fl T Ar phone_number 17.Op Fl U Ar phone_number 18.Sh DESCRIPTION 19The 20.Nm 21program defines a conversational exchange between the computer and the modem. 22.Sh OPTIONS 23The following options are provided: 24.Bl -tag -width ".Fl U Ar phone_number" -offset indent 25.It Fl f Ar chat_file 26Read the chat script from 27.Ar chat_file . 28The use of this option is mutually exclusive with the chat script parameters. 29The user must have read access to the file. 30Multiple lines are permitted in the file. 31Space or horizontal tab characters should be used to separate the strings. 32.It Fl t Ar timeout 33Set the timeout for the expected string to be received. 34If the string 35is not received within the time limit then the reply string is not sent. 36An alternate reply may be sent or the script will fail if there 37is no alternate reply string. 38A failed script will cause the 39.Nm 40program to terminate with a non-zero error code. 41.It Fl r Ar report_file 42Set the file for output of the report strings. 43If you use the keyword 44.Dq REPORT , 45the resulting strings are written to this file. 46If this option is not used and you still use 47.Dq REPORT 48keywords, the stderr file is used for the report strings. 49.It Fl e 50Start with the echo option turned on. 51Echoing may also be turned on 52or off at specific points in the chat script by using the 53.Dq ECHO 54keyword. 55When echoing is enabled, all output from the modem is echoed to stderr. 56.It Fl v 57Request that the 58.Ar script 59be executed in a verbose mode. 60The 61.Nm 62program will then log the execution state of the chat 63script as well as all text received from the modem and the output 64strings sent to the modem. 65The default is to log through 66.Xr syslog 3 ; 67the logging method may be altered with the 68.Fl S 69and 70.Fl s 71flags. 72Logging is done to the 73.Dq local2 74facility at level 75.Dq info 76for verbose tracing and level 77.Dq err 78for some errors. 79.It Fl V 80Request that 81.Ar script 82be executed in a stderr verbose mode. 83The 84.Nm 85program will then log all text received from the 86modem and the output strings sent to the modem to the stderr device. 87This device is usually the local console at the station running the chat or 88the 89.Xr ppp 8 90program. 91.It Fl s 92Use stderr. 93All log messages from 94.Fl v 95and all error messages will be sent to stderr. 96.It Fl S 97Do not use 98.Xr syslog 3 . 99By default, error messages are sent to 100.Xr syslog 3 . 101The use of 102.Fl S 103will prevent both log messages from 104.Fl v 105and error messages from being sent to 106.Xr syslog 3 . 107.It Fl T Ar phone_number 108Pass in an arbitrary string, usually a phone number, that will be 109substituted for the \eT substitution metacharacter in a send string. 110.It Fl U Ar phone_number 111Pass in a second string, usually a phone number, that will be 112substituted for the \eU substitution metacharacter in a send string. 113This is useful when dialing an ISDN terminal adapter that requires two 114numbers. 115.It Ar script 116If the script is not specified in a file with the 117.Fl f 118option then the script is included as parameters to the 119.Nm 120program. 121.El 122.Sh CHAT SCRIPT 123The 124.Nm 125script defines the communications. 126.Pp 127A script consists of one or more 128.Dq expect-send 129pairs of strings, separated by spaces, with an optional 130.Dq subexpect-subsend 131string pair, separated by a dash as in the following example: 132.Pp 133.Dl ogin:-BREAK-ogin: ppp ssword: hello2u2 134.Pp 135This line indicates that the 136.Nm 137program should expect the string 138.Dq ogin: . 139If it fails to receive a login prompt within the time interval 140allotted, it is to send a break sequence to the remote and then expect the 141string 142.Dq ogin: . 143If the first 144.Dq ogin: 145is received then the break sequence is not generated. 146.Pp 147Once it received the login prompt the 148.Nm 149program will send the string ppp and then expect the prompt 150.Dq ssword: . 151When it receives the 152prompt for the password, it will send the password hello2u2. 153.Pp 154A carriage return is normally sent following the reply string. 155It is not expected in the 156.Dq expect 157string unless it is specifically requested by using the \er character sequence. 158.Pp 159The expect sequence should contain only what is needed to identify the string. 160Since it is normally stored on a disk file, it should not contain 161variable information. 162It is generally not acceptable to look for time 163strings, network identification strings, or other variable pieces of data as 164an expect string. 165.Pp 166To help correct for characters which may be corrupted during the initial 167sequence, look for the string 168.Dq ogin: 169rather than 170.Dq login: . 171It is possible that the leading 172.Dq l 173character may be received in error and you may never 174find the string even though it was sent by the system. 175For this reason, scripts look for 176.Dq ogin: 177rather than 178.Dq login: 179and 180.Dq ssword: 181rather than 182.Dq password: . 183.Pp 184A very simple script might look like this: 185.Pp 186.Dl ogin: ppp ssword: hello2u2 187.Pp 188In other words, expect ....ogin:, send ppp, expect ...ssword:, send hello2u2. 189.Pp 190In actual practice, simple scripts are rare. 191At the vary least, you 192should include sub-expect sequences should the original string not be 193received. 194For example, consider the following script: 195.Pp 196.Dl ogin:--ogin: ppp ssword: hello2u2 197.Pp 198This would be a better script than the simple one used earlier. 199This would look 200for the same login: prompt, however, if one was not received, a single 201return sequence is sent and then it will look for login: again. 202Should line 203noise obscure the first login prompt then sending the empty line will 204usually generate a login prompt again. 205.Sh COMMENTS 206Comments can be embedded in the chat script. 207A comment is a line which 208starts with the 209.Sy # 210(hash) character in column 1. 211Such comment lines are just ignored by the chat program. 212If a 213.Sq # 214character is to 215be expected as the first character of the expect sequence, you should 216quote the expect string. 217If you want to wait for a prompt that starts with a # (hash) 218character, you would have to write something like this: 219.Bd -literal -offset indent 220# Now wait for the prompt and send logout string 221.br 222\&'# ' logout 223.Ed 224.Sh ABORT STRINGS 225Many modems will report the status of the call as a string. 226These strings may be 227.Dq CONNECTED 228or 229.Dq NO CARRIER 230or 231.Dq BUSY . 232It is often desirable to terminate the script should the modem fail to 233connect to the remote. 234The difficulty is that a script would not know 235exactly which modem string it may receive. 236On one attempt, it may receive 237.Dq BUSY 238while the next time it may receive 239.Dq NO CARRIER . 240.Pp 241These 242.Dq abort 243strings may be specified in the script using the 244.Dq ABORT 245sequence. 246It is written in the script as in the following example: 247.Pp 248.Dl ABORT BUSY ABORT 'NO CARRIER' '' ATZ OK ATDT5551212 CONNECT 249.Pp 250This sequence will expect nothing; and then send the string ATZ. 251The expected response to this is the string 252.Dq OK . 253When it receives 254.Dq OK , 255the string ATDT5551212 to dial the telephone. 256The expected string is 257.Dq CONNECT . 258If the string 259.Dq CONNECT 260is received the remainder of the script is executed. 261However, should the modem find a busy telephone, it will send the string 262.Dq BUSY . 263This will cause the string to match the abort character sequence. 264The script will then fail because it found a match to the abort string. 265If it received the string 266.Dq NO CARRIER , 267it will abort for the same reason. 268Either string may be received. 269Either string will terminate the 270.Nm 271script. 272.Sh CLR_ABORT STRINGS 273This sequence allows for clearing previously set 274.Dq ABORT 275strings. 276.Dq ABORT 277strings are kept in an array of a pre-determined size (at compilation time); 278.Dq CLR_ABORT will reclaim the space for cleared 279entries so that new strings can use that space. 280.Sh SAY STRINGS 281The 282.Dq SAY 283directive allows the script to send strings to the user 284at the terminal via standard error. 285.Pp 286.Dq SAY 287strings must be enclosed in single or double quotes. 288If carriage return and line feed are needed in the string to be output, 289you must explicitly add them to your string. 290.Pp 291The 292.Dq SAY 293strings could be used to give progress messages in sections of 294the script where you want to have 295.Sq ECHO OFF 296but still let the user know what is happening. 297An example is: 298.Bd -literal -offset indent 299ABORT BUSY 300ECHO OFF 301SAY "Dialling your ISP...\\n" 302.br 303\&'' ATDT5551212 304TIMEOUT 120 305SAY "Waiting up to 2 min. for connection... " 306CONNECT '' 307SAY "Connected, now logging in...\\n" 308ogin: account 309ssword: pass 310$ \c 311SAY "Logged in OK ...\\n" 312\&... 313.Ed 314.Pp 315This sequence will only present the SAY strings to the user and all 316the details of the script will remain hidden. 317For example, if the above script works, the user will see: 318.Bd -literal -offset indent 319Dialling your ISP... 320Waiting up to 2 min. for connection... Connected, now logging in... 321Logged in OK ... 322.Ed 323.Sh REPORT STRINGS 324A 325.Dq report 326string is similar to the ABORT string. 327The difference 328is that the strings, and all characters to the next control character 329such as a carriage return, are written to the report file. 330.Pp 331The report strings may be used to isolate the transmission rate of the 332modem's connect string and return the value to the chat user. 333The analysis of the report string logic occurs in conjunction with the 334other string processing such as looking for the expect string. 335The use of the same string for a report and abort sequence is probably not 336very useful, however, it is possible. 337.Pp 338The report strings to no change the completion code of the program. 339.Pp 340These 341.Dq report 342strings may be specified in the script using the 343.Dq REPORT 344sequence. 345It is written in the script as in the following example: 346.Pp 347.Dl REPORT CONNECT ABORT BUSY '' ATDT5551212 CONNECT '' ogin: account 348.Pp 349This sequence will expect nothing; and then send the string 350ATDT5551212 to dial the telephone. 351The expected string is 352.Dq CONNECT . 353If the string 354.Dq CONNECT 355is received the remainder of the script is executed. 356In addition the program will write to the expect-file the string 357.Dq CONNECT 358plus any characters which follow it such as the connection rate. 359.Sh CLR_REPORT STRINGS 360This sequence allows for clearing previously set 361.Dq REPORT 362strings. 363.Dq REPORT 364strings are kept in an array of a pre-determined size (at compilation time); 365.Dq CLR_REPORT 366will reclaim the space for cleared 367entries so that new strings can use that space. 368.Sh ECHO 369The echo options controls whether the output from the modem is echoed 370to stderr. 371This option may be set with the 372.Fl e 373option, but it can also be controlled by the 374.Dq ECHO 375keyword. 376The 377.Dq expect-send 378pair 379.Dq ECHO ON 380enables echoing, and 381.Dq ECHO OFF 382disables it. 383With this keyword you can select which parts of the 384conversation should be visible. 385For instance, with the following script: 386.Bd -literal -offset indent 387ABORT 'BUSY' 388ABORT 'NO CARRIER' 389.br 390\&'' ATZ 391OK\\r\\n ATD1234567 392\\r\\n \\c 393ECHO ON 394CONNECT \\c 395ogin: account 396.Ed 397.Pp 398all output resulting from modem configuration and dialing is not visible, 399but starting with the 400.Dq CONNECT 401(or 402.Dq BUSY ) 403message, everything will be echoed. 404.Sh HANGUP 405The HANGUP options control whether a modem hangup should be considered 406as an error or not. This option is useful in scripts for dialling 407systems which will hang up and call your system back. The HANGUP 408options can be 409.Dq ON 410or 411.Dq OFF . 412.Pp 413When HANGUP is set OFF and the modem hangs up (e.g., after the first 414stage of logging in to a callback system), 415.Nm 416will continue 417running the script (e.g.\&, waiting for the incoming call and second 418stage login prompt). As soon as the incoming call is connected, you 419should use the 420.Dq HANGUP ON 421directive to reinstall normal hang up signal behavior. 422Here is a (simple) example script: 423.Bd -literal -offset indent 424ABORT 'BUSY' 425.br 426\&'' ATZ 427OK\\r\\n ATD1234567 428\\r\\n \\c 429CONNECT \\c 430.br 431\&'Callback login:' call_back_ID 432HANGUP OFF 433ABORT "Bad Login" 434.br 435\&'Callback Password:' Call_back_password 436TIMEOUT 120 437CONNECT \\c 438HANGUP ON 439ABORT "NO CARRIER" 440ogin:--BREAK--ogin: real_account 441\&... 442.Ed 443.Sh TIMEOUT 444The initial timeout value is 45 seconds. 445This may be changed using the 446.Fl t 447parameter. 448.Pp 449To change the timeout value for the next expect string, the following 450example may be used: 451.Pp 452.Dl ATZ OK ATDT5551212 CONNECT TIMEOUT 10 ogin:--ogin: TIMEOUT 5 assword: hello2u2 453.Pp 454This will change the timeout to 10 seconds when it expects the login: 455prompt. 456The timeout is then changed to 5 seconds when it looks for the 457password prompt. 458.Pp 459The timeout, once changed, remains in effect until it is changed again. 460.Sh SENDING EOT 461The special reply string of 462.Dq EOT 463indicates that the chat program should send an EOT character to the remote. 464This is normally the End-of-file character sequence. 465A return character is not sent following the EOT. 466.Pp 467The EOT sequence may be embedded into the send string using the 468sequence 469.Dq ^D . 470.Sh GENERATING BREAK 471The special reply string of 472.Dq BREAK 473will cause a break condition to be sent. 474The break is a special signal on the transmitter. 475The normal processing on the receiver is to change the transmission rate. 476It may be used to cycle through the available transmission rates on 477the remote until you are able to receive a valid login prompt. 478.Pp 479The break sequence may be embedded into the send string using the 480.Dq \eK 481sequence. 482.Sh ESCAPE SEQUENCES 483The expect and reply strings may contain escape sequences. 484All of the sequences are legal in the reply string. 485Many are legal in the expect. 486Those which are not valid in the expect sequence are so indicated. 487.Bl -tag -width ".Li \e\e000" 488.It Li '' 489Expects or sends a null string. 490If you send a null string then it will still send the return character. 491This sequence may either be a pair of apostrophe or quote characters. 492.It Li \eb 493represents a backspace character. 494.It Li \ec 495Suppresses the newline at the end of the reply string. 496This is the only method to send a string without a trailing return character. 497It must be at the end of the send string. 498For example, 499the sequence hello\ec will simply send the characters h, e, l, l, o. 500.Em ( not valid in expect . ) 501.It Li \ed 502Delay for one second. 503The program uses 504.Xr sleep 1 505which will delay to a maximum of one second. 506.Em ( not valid in expect . ) 507.It Li \eK 508Insert a BREAK 509.Em ( not valid in expect . ) 510.It Li \en 511Send a newline or linefeed character. 512.It Li \eN 513Send a null character. 514The same sequence may be represented by \e0. 515.Em ( not valid in expect . ) 516.It Li \ep 517Pause for a fraction of a second. 518The delay is 1/10th of a second. 519.Em ( not valid in expect . ) 520.It Li \eq 521Suppress writing the string to 522.Xr syslogd 8 . 523The string ?????? is 524written to the log in its place. 525.Em ( not valid in expect . ) 526.It Li \er 527Send or expect a carriage return. 528.It Li \es 529Represents a space character in the string. 530This may be used when it 531is not desirable to quote the strings which contains spaces. 532The sequence 533.Sq HI TIM 534and 535.Sq HI\esTIM 536are the same. 537.It Li \et 538Send or expect a tab character. 539.It Li \e\e 540Send or expect a backslash character. 541.It Li \e\eddd 542Collapse the octal digits (ddd) into a single ASCII character and send that 543character. 544.Em ( some characters are not valid in expect . ) 545.It Li ^C 546Substitute the sequence with the control character represented by C. 547For example, the character DC1 (17) is shown as ^Q. 548.Em ( some characters are not valid in expect . ) 549.El 550.Sh TERMINATION CODES 551The 552.Nm 553program will terminate with the following completion codes. 554.Bl -tag -width ".Li ..." 555.It Li 0 556The normal termination of the program. 557This indicates that the script 558was executed without error to the normal conclusion. 559.It Li 1 560One or more of the parameters are invalid or an expect string was too 561large for the internal buffers. 562This indicates that the program as not properly executed. 563.It Li 2 564An error occurred during the execution of the program. 565This may be due 566to a read or write operation failing for some reason or chat receiving 567a signal such as 568.Dv SIGINT . 569.It Li 3 570A timeout event occurred when there was an 571.Dq expect 572string without having a 573.Dq -subsend 574string. 575This may mean that you did not program the 576script correctly for the condition or that some unexpected event has 577occurred and the expected string could not be found. 578.It Li 4 579The first string marked as an 580.Dq ABORT 581condition occurred. 582.It Li 5 583The second string marked as an 584.Dq ABORT 585condition occurred. 586.It Li 6 587The third string marked as an 588.Dq ABORT 589condition occurred. 590.It Li 7 591The fourth string marked as an 592.Dq ABORT 593condition occurred. 594.It Li ... 595The other termination codes are also strings marked as an 596.Dq ABORT 597condition. 598.El 599.Pp 600Using the termination code, it is possible to determine which event 601terminated the script. 602It is possible to decide if the string 603.Dq BUSY 604was received from the modem as opposed to 605.Dq NO DIAL TONE . 606While the first event may be retried, the second will probably have little 607chance of succeeding during a retry. 608.Sh SEE ALSO 609.Xr uucp 1 Pq Pa net/freebsd-uucp , 610.Xr syslog 3 , 611.Xr syslogd 8 , 612.Xr uucico 8 Pq Pa net/freebsd-uucp 613.Pp 614Additional information about 615.Nm 616scripts may be found with UUCP documentation. 617The 618.Nm 619script was taken from the ideas proposed by the scripts used by the 620.Xr uucico 8 Pq Pa net/freebsd-uucp 621program. 622.Sh COPYRIGHT 623The 624.Nm 625program is in public domain. 626This is not the GNU public license. 627If it breaks then you get to keep both pieces. 628