Return to xchat.man CVS log

Up to [MW Coherent from dump] / coherent / g / usr / lib / uucp / tay104 / contrib

Annotation of coherent/g/usr/lib/uucp/tay104/contrib/xchat.man, revision 1.1

1.1     ! root        1: .TH xchat 8
        !             2: .SH NAME
        !             3: xchat - Extended chat processor
        !             4: .SH SYNOPSIS
        !             5: .BI "xchat " "scriptfile"
        !             6: .RI " [ " parameter... " ] "
        !             7: .PP
        !             8: where
        !             9: .I scriptfile
        !            10: is the name of a file containing an 
        !            11: .I xchat
        !            12: script. If 
        !            13: .I scriptfile
        !            14: begins with ``/'', then it is assumed to be a full path name for the
        !            15: script file. If not, a configuration-dependent default directory path
        !            16: (usually
        !            17: .B "/usr/local/conf/uucp/"
        !            18: ) is prepended to the script file name. Normally, the default path
        !            19: is the same as that for the Taylor UUCP configuration files.
        !            20: .SH DESCRIPTION
        !            21: .I Xchat
        !            22: is a general-purpose dialing and login program designed for use 
        !            23: with Taylor UUCP as a ``chat-program'', taking the place (or 
        !            24: augmenting) the built-in chat scripting facility. It provides the 
        !            25: ability to closely control timeouts, multiple simultaneous ``expect'' 
        !            26: strings with separate actions, extended terminal control, modem 
        !            27: command character pacing, and more.
        !            28: .PP
        !            29: When used in conjunction with Taylor UUCP's
        !            30: configuration features, 
        !            31: .I xchat
        !            32: can provide you the ability to manage the most intricate login, 
        !            33: dial and hangup needs. The scripts are written in a shell-like (well, 
        !            34: sort-of) style with labels, commands, and parameters, easing the task 
        !            35: of writing procedures for complex terminal communications situations.
        !            36: .PP
        !            37: Because 
        !            38: .I xchat
        !            39: assumes that it is connected to the terminal device via stdin/stdout, 
        !            40: you can easily debug scripts by invoking it from the shell and 
        !            41: responding to the script from the keyboard. A debug logging facility 
        !            42: is included, with the debug output going to a separate user-specified 
        !            43: file. This makes it easy to debug connection problems without wading 
        !            44: through large 
        !            45: .I uucico
        !            46: log and debug files.
        !            47: .PP
        !            48: Formally, a script describes a state machine; 
        !            49: .I xchat
        !            50: interprets the script and does what the state machine
        !            51: tells it to. This section will be much easier to understand 
        !            52: if you obtain listings of the script files supplied with
        !            53: .I xchat.
        !            54: .SH "SCRIPT FILE FORMAT"
        !            55: Script files are ordinary text files containing comments, labels,
        !            56: and statements. Blank lines are ignored. 
        !            57: Comments are denoted by leading ``#''
        !            58: characters. Some statements (those which do not end with an
        !            59: ``extended string'' argument; see below) can also have trailing
        !            60: comments.
        !            61: .PP
        !            62: .I Labels 
        !            63: begin in column one and are ended by colons (:). A label
        !            64: specifies a state name. All lines between a pair of labels are
        !            65: the statements for a single state.
        !            66: .PP
        !            67: Processing always begins at the head of the script (no leading
        !            68: state name is necessary).
        !            69: .PP
        !            70: .I Statements 
        !            71: are divided into two categories, ``action'' and ``expect''.
        !            72: When a state is entered, all of its actions are performed in the
        !            73: order in which they appear in the file.
        !            74: .PP
        !            75: A 
        !            76: .I transition 
        !            77: to another state may occur for any of three reasons:
        !            78: .IP (1) 5
        !            79: One of the actions may cause a transition to
        !            80: another state, in which case the rest of the
        !            81: current state's actions are skipped.
        !            82: Processing resumes with the first action
        !            83: statement of the new state.
        !            84: .IP (2) 5
        !            85: If none of the actions cause a state
        !            86: transition, and there are no expects in the
        !            87: state, processing ``falls through'' to the next
        !            88: state in the file.
        !            89: .IP (3) 5
        !            90: If none of the actions cause a state
        !            91: transition, but there are expects in the
        !            92: state, the state machine pauses until one of
        !            93: the expects is ``satisfied''. It then transitions 
        !            94: to the state named in the expect
        !            95: statement.
        !            96: .PP
        !            97: Finally, there are two action statements which, when executed,
        !            98: cause the script to exit.
        !            99: .SH "SCRIPT FILE STATEMENTS"
        !           100: This section describes all of the statements that may appear in script
        !           101: files, except for a few special action statements. Those are described
        !           102: in a later section, ``Overriding Defaults''.
        !           103: .PP
        !           104: Some statements accept one or two arguments, referred to in the
        !           105: following descriptions as 
        !           106: .IR int ", " ns ", " str ", or "
        !           107: .IR xstr ", to"
        !           108: indicate whether the argument is an integer, a new state name, a
        !           109: string, or an ``extended string'' (described in a later section).
        !           110: .PP
        !           111: For all statements that accept two arguments, the first is the
        !           112: name of a new state, and the second specifies a condition or
        !           113: reason for changing to the new state.
        !           114: .SS "Termination And Informational Statements"
        !           115: These statements are used to place entries into the Taylor UUCP
        !           116: .I Log
        !           117: file, and to cause 
        !           118: .I xchat
        !           119: to exit with successful or failure status. It is also possible to open a 
        !           120: separate
        !           121: .I debug
        !           122: log file and control the level of tracing and error reporting that will go
        !           123: into that log file. This is very useful in debugging 
        !           124: .I xchat
        !           125: scripts.
        !           126: .br
        !           127: .ta 1.0i 1.5i 2.0i
        !           128: .TP 2.0i
        !           129: .B failed
        !           130: Exit script with ``failed'' status. This causes 
        !           131: .I xchat 
        !           132: to exit with status 0.
        !           133: .TP 2.0i
        !           134: .B success
        !           135: Exit script with ``success'' status. This causes
        !           136: .I xchat
        !           137: to exit with status 1.
        !           138: .TP 2.0i
        !           139: .BI "log       " xstr     
        !           140: Send informational message
        !           141: .I xstr 
        !           142: to standard error. When used with Taylor UUCP, this is the 
        !           143: .I Log
        !           144: file for the 
        !           145: .I uucico
        !           146: program.
        !           147: .TP 2.0i
        !           148: .BI "logerr    " xstr     
        !           149: Send message
        !           150: .I xstr 
        !           151: to standard error, with ``ERROR:'' indicator. When used 
        !           152: with Taylor UUCP, this is the 
        !           153: .I Log
        !           154: file for the 
        !           155: .I uucico
        !           156: program.
        !           157: .TP 2.0i
        !           158: .BI "dbgfile   " xstr
        !           159: Open script debugging file 
        !           160: .I xstr.
        !           161: If
        !           162: .I xstr
        !           163: begins with ``/'', it is assumed to be an absolute path name for the
        !           164: debugging file. If not, then a configuration-dependent default directory 
        !           165: path (usually
        !           166: .B "/usr/spool/uucp"
        !           167: ) is prepended to
        !           168: .I xstr.
        !           169: Normally the default path is that of the directory where Taylor UUCP 
        !           170: puts its log files.
        !           171: The debugging file is used to capture a detailed log of the data sent
        !           172: and received, errors encountered, and a trace of script execution.
        !           173: The various types of logging are controlled by the
        !           174: .I "debug mask,"
        !           175: described next. 
        !           176: .B Note:
        !           177: A new log file is created each time 
        !           178: .I xchat
        !           179: runs. Use the 
        !           180: .B log
        !           181: and
        !           182: .B loge
        !           183: commands to log 
        !           184: continuous information onto standard out, which is connected
        !           185: to the Taylor UUCP
        !           186: .I Log
        !           187: file when 
        !           188: .I xchat
        !           189: is run by the Taylor
        !           190: .I uucico.
        !           191: .TP 2.0i
        !           192: .BI "dbgset    " int
        !           193: Set the bits specified in 
        !           194: .I int
        !           195: in the debugging mask. The value in
        !           196: .I int
        !           197: is ``or''ed into the mask. Set bit 0 (value \= 1) for error messages,
        !           198: bit 1 (value \= 2) for dial, login and init errors, bit 2 (value \= 4)
        !           199: for dial, login and init trace with character I/O, and bit 3 (value \= 8)
        !           200: for script processing internals. Normally, you will just turn it all on
        !           201: with a value of 15.
        !           202: .TP 2.0i
        !           203: .BI "dbgclr    " int
        !           204: Clear the bits specified in
        !           205: .I int
        !           206: from the debugging mask.
        !           207: .TP 2.0i
        !           208: .BI "debug     " xstr
        !           209: Write 
        !           210: .I
        !           211: xstr
        !           212: into the debug log. The entry will be enclosed in angle brackets.
        !           213: .TP 2.0i
        !           214: .BI "debuge    " xstr
        !           215: Write
        !           216: .I xstr
        !           217: into the debug log with ``ERROR: '' prepended. The entry will be enclosed
        !           218: in angle brackets. 
        !           219: .SS "Sending Data"
        !           220: These statements are used to transmit data to standard out (the tty or TCP
        !           221: port when used with Taylor UUCP).
        !           222: .I
        !           223: No implied carriage returns are sent.
        !           224: You must include a \\r if you want a carriage return in the string
        !           225: sent by the 
        !           226: .B send
        !           227: command. If you want a return sent after 
        !           228: .B dial
        !           229: or
        !           230: .B sendstr,
        !           231: you must send it with a separate
        !           232: .B send
        !           233: command.
        !           234: .TP 2.0i
        !           235: .B dial
        !           236: Send the string previously set by the 
        !           237: .B telno
        !           238: command to the serial port.
        !           239: .B W
        !           240: and
        !           241: .B P
        !           242: characters in the phone number are
        !           243: converted as described under 
        !           244: .B 
        !           245: Dial Strings,
        !           246: below. This statement also sets a default
        !           247: timeout value, as described under the 
        !           248: .B timeout
        !           249: statement.
        !           250: .TP 2.0i
        !           251: .BI "send      " xstr
        !           252: Send the string 
        !           253: .I xstr 
        !           254: to the serial port.
        !           255: .TP 2.0i
        !           256: .BI "sendstr   " int
        !           257: The argument of this statement is a digit from 0
        !           258: through 7. Send the corresponding string
        !           259: parameter as passed to 
        !           260: .I xchat
        !           261: following the script file name. The parameter is interpreted 
        !           262: as an extended string.
        !           263: .SS "Special Terminal Control Statements"
        !           264: These statements are used to cause the terminal port to perform some special action, or to change the mode of the port.
        !           265: .I 
        !           266: The modes of the port are restored to their original settings
        !           267: .I
        !           268: by xchat before it exits.
        !           269: .TP 2.0i
        !           270: .B flush
        !           271: Flush the terminal port's input buffer.
        !           272: .TP 2.0i
        !           273: .B break
        !           274: Send a break signal.
        !           275: .TP 2.0i
        !           276: .B hangup
        !           277: Momentarily drop Data Terminal Ready (DTR) on the
        !           278: serial port, causing the modem to hang up. (Not
        !           279: usually needed, since 
        !           280: .I uucico
        !           281: does this at the end of each call.)
        !           282: .TP 2.0i
        !           283: .B 7bit
        !           284: Change the port to strip incoming characters to 7 bits. 
        !           285: .I
        !           286: This is the default mode.
        !           287: This mode 
        !           288: is implied when the port has parity enabled, since parity characters
        !           289: are 7-bits wide.
        !           290: .TP 2.0i
        !           291: .B 8bit
        !           292: Change the port to allow incoming 8-bit characters to be passed 
        !           293: to the script processor. This mode has no effect if parity is 
        !           294: enabled, since parity characters are 7-bits wide.
        !           295: .TP 2.0i
        !           296: .B nopar
        !           297: Change the port to 8-bits, no parity. 
        !           298: .I
        !           299: This is the default mode.
        !           300: .TP 2.0i
        !           301: .B evenpar
        !           302: Change the port to 7-bits, even parity. 
        !           303: .I 
        !           304: Incoming characters with parity errors are discarded.
        !           305: .TP 2.0i
        !           306: .B oddpar
        !           307: Change the port to 7-bits, odd parity.
        !           308: .I 
        !           309: Incoming characters with parity errors are discarded.
        !           310: .SS "Counting, Branching, Timing and Testing Statements"
        !           311: These statements are used to control the flow of the 
        !           312: .I xchat
        !           313: script itself, including branching, delays, and counter manipulation.
        !           314: .TP 2.0i
        !           315: .BI "sleep     " int 
        !           316: Delay for 
        !           317: .I int
        !           318: milliseconds.
        !           319: .TP 2.0i
        !           320: .B zero
        !           321: Clear the counter.
        !           322: .TP 2.0i
        !           323: .B count
        !           324: Add one to the counter.
        !           325: .TP 2.0i
        !           326: .BI "ifgtr     " "ns   int"
        !           327: Go to state 
        !           328: .I ns
        !           329: if counter greater than 
        !           330: .I int.
        !           331: .TP 2.0i
        !           332: .BI "goto      " ns
        !           333: Go to state 
        !           334: .I ns 
        !           335: unconditionally.
        !           336: .TP 2.0i
        !           337: .BI "ifstr     " "ns   int"
        !           338: Go to state 
        !           339: .I ns
        !           340: if string parameter 
        !           341: .I int
        !           342: is nonempty.
        !           343: .TP 2.0i
        !           344: .BI "ifnstr    " "ns   int"
        !           345: Go to state
        !           346: .I ns
        !           347: if string parameter 
        !           348: .I int
        !           349: is empty.
        !           350: .TP 2.0i
        !           351: .BI "ifblind   " ns
        !           352: Change to state
        !           353: .I ns
        !           354: if the port is ``blind'' without carrier (CD) asserted.
        !           355: .I 
        !           356: This is not yet implemented, the test always fails.
        !           357: .TP 2.0i
        !           358: .BI "ifblgtr   " "ns   int"
        !           359: Change to state
        !           360: .I ns
        !           361: if the port is ``blind'' without carrier (CD) asserted, and counter
        !           362: is greater then
        !           363: .I int.
        !           364: .I 
        !           365: This is not yet implemented, the test always fails.
        !           366: .SS "Expect Statements"
        !           367: Expect statements are usually the last statements that appear in a
        !           368: given state, though in fact they can appear anywhere within the
        !           369: state. Even if they appear at the beginning, the script processor
        !           370: always does all of the action statements first. As a practical
        !           371: matter, the order of these statements is not significant; they are
        !           372: all interpreted ``in parallel''.
        !           373: .TP 2.0i
        !           374: .BI "expect    " "ns   xstr"
        !           375: Change to state 
        !           376: .I ns 
        !           377: if the string specified by
        !           378: .I xstr 
        !           379: is received from standard input (usually the serial port). 
        !           380: Case is significant, but high-order bits are not
        !           381: checked.
        !           382: .TP 2.0i
        !           383: .BI "ifcarr    " ns
        !           384: Change to state
        !           385: .I ns 
        !           386: if Carrier Detect (CD) is true.
        !           387: .I
        !           388: Not currently implemented. Always changes state.
        !           389: .TP 2.0i
        !           390: .BI "ifhang    " ns
        !           391: Change to state
        !           392: .I ns
        !           393: if a data set hangup occurs (SIGHUP signal received).
        !           394: .TP 2.0i
        !           395: .BI "timeout   " "ns   int"
        !           396: Change to state 
        !           397: .I ns 
        !           398: if the time (in milliseconds)
        !           399: given by 
        !           400: .I int
        !           401: has elapsed without satisfying any
        !           402: expects. If the time specified is 0, a default
        !           403: timeout value (calculated from the length and
        !           404: other characteristics of the most recent dial
        !           405: string) is used.
        !           406: .SH "SCRIPT PROCESSING DETAILS"
        !           407: .SS "Extended Strings"
        !           408: In the statements that accept string arguments, the strings are
        !           409: interpreted as 
        !           410: .I 
        !           411: extended strings. 
        !           412: Extended strings begin with
        !           413: the first nonblank character and continue, including all imbedded
        !           414: and trailing blanks and other whitespace, until (but not
        !           415: including) the end of the line in the script file. (There is no
        !           416: provision for line continuation.)  No trailing spaces should be
        !           417: present between the last ``desired'' character of the string and the
        !           418: end of the line, as they will be included in the stored string and
        !           419: sent or expected, just as they appear in the script file. And,
        !           420: obviously, no trailing comments are permitted!  They will just be
        !           421: stored as part of the string.
        !           422: .PP
        !           423: Within an extended string, the following ``escape sequences'' will
        !           424: be converted as indicated before being sent or expected:
        !           425: .br
        !           426: .nf
        !           427: .in +0.5i
        !           428: \fB\\d\fR      EOT character (control-D)
        !           429: \fB\\N\fR      null character
        !           430: \fB\\n\fR      line feed
        !           431: \fB\\r\fR      carriage return
        !           432: \fB\\s\fR      space
        !           433: \fB\\t\fR      tab
        !           434: \fB\\\-\fR     hyphen
        !           435: \fB\\\\\fR     backslash
        !           436: \fB\\ooo\fR    character with value ooo (in octal)
        !           437: .in -0.5i
        !           438: .fi
        !           439: .PP
        !           440: Since extended strings in scripts can include embedded spaces,
        !           441: tabs, etc., these escape sequences are only required in strings
        !           442: appearing in systems entries, though they may be used in script
        !           443: files to improve readability.
        !           444: .PP
        !           445: The octal-character specification (\\ooo) may have from one to
        !           446: three octal digits; it is terminated either after the third digit
        !           447: or when a non-octal character is encountered. But if you want to
        !           448: specify one of these followed by something that happens to be a
        !           449: valid octal character (for example, a control-A followed by a 7)
        !           450: make sure to include all three digits after the \\ . So \\0017
        !           451: would become a control-A followed by the Ascii character ``7'', but
        !           452: \\17 or \\017 would become a control-Y (decimal value 25). \\1S
        !           453: would convert to a control-A followed by an ``S''.
        !           454: .PP
        !           455: Extended strings are stored without a trailing carriage return
        !           456: unless one is explicitly present in the string (via \\r).
        !           457: .SS "String Parameters"
        !           458: The 
        !           459: .B sendstr 
        !           460: statement sends (after conversion from extended string
        !           461: format) one of the parameters given on the 
        !           462: .I xchat
        !           463: command line following the script file name. 
        !           464: The parameter is selected by the integer
        !           465: argument of the statement.
        !           466: .PP
        !           467: This allows ``generic'' script files to serve
        !           468: for many different systems; the string parameters 
        !           469: provide the phone number, username, password, etc. Character
        !           470: substitutions described under ``extended strings'' above are
        !           471: performed on these strings.
        !           472: .PP
        !           473: The ifstr and ifnstr statements allow further generality in script
        !           474: files, by testing whether a particular parameter is present in the
        !           475: systems entry. For example, a single script can be
        !           476: used both for those systems that require a password and
        !           477: those that do not. The password is specified as the last argument
        !           478: in the 
        !           479: .xchat
        !           480: command; the script can test for this
        !           481: parameter's existence and skip the password sequence if
        !           482: the parameter is empty.
        !           483: .SS "``Wait'' And ``Pause'' Characters In Dial Strings"
        !           484: An additional conversion is performed on dial strings. Dial strings
        !           485: are interpreted as extended strings. Then the characters
        !           486: .B W 
        !           487: and
        !           488: .B P
        !           489: within a dial string are interpreted as ``wait for dial
        !           490: tone'' and ``pause'', and may be converted to other characters. By
        !           491: default, 
        !           492: .B W
        !           493: is left alone, and
        !           494: .B P
        !           495: is converted to a comma (,);
        !           496: these are appropriate for Hayes-type modems. The script may
        !           497: specify other substitutions (see below).
        !           498: .PP
        !           499: .B NOTE: 
        !           500: The Taylor UUCP documentation states that the ``wait'' and ``pause''
        !           501: characters are ``='' and ``-'', respectively. These are actual characters
        !           502: understood by some modems. When using
        !           503: .I xchat
        !           504: you should put
        !           505: .B W
        !           506: and
        !           507: .B P
        !           508: in the dial strings you specify in the Taylor configuration files. 
        !           509: This way, the 
        !           510: .I xchat
        !           511: processor can make the substitution appropriate for the particular 
        !           512: modem in use. Make a separate 
        !           513: .I xchat
        !           514: script for each modem type, e.g.,
        !           515: .I "dial.hayes"
        !           516: and specify the translation there. This way, the phone number strings
        !           517: in the Taylor configuration files can be used with a variety of modems.
        !           518: .SS "Default Timeouts For Dial Strings"
        !           519: When a 
        !           520: .B dial 
        !           521: statement is executed, a default timeout value is set.
        !           522: This is the timeout value used by a subsequent timeout statement
        !           523: if the statement specifies a timeout value of 0.
        !           524: .PP
        !           525: The default timeout is given by:
        !           526: .br
        !           527: .nf
        !           528: .in +2
        !           529: \fIctime\fR + (\fIndigits\fR * \fIdgttime\fR) + (\fInwchar\fR * \fIwtime\fR) + (\fInpchar\fR * \fI ptime\fR) 
        !           530: .in -2
        !           531: .fi
        !           532: .PP
        !           533: where 
        !           534: .I 
        !           535: ndigits, nwchar, 
        !           536: and 
        !           537: .I npchar
        !           538: are the number of digits, wait characters, and pause characters in
        !           539: the dial string, and 
        !           540: .I ctime, dgttime, wtime, 
        !           541: and 
        !           542: .I ptime 
        !           543: are 45 seconds, 0.1 seconds, 10 seconds, and 2 seconds, 
        !           544: respectively.
        !           545: All of these times may be changed as specified below under
        !           546: ``Overriding Defaults.''
        !           547: .SS "Trailing Carriage Returns Not Assumed"
        !           548: In the 
        !           549: .B dial
        !           550: and
        !           551: .B sendstr 
        !           552: statements, the dial string or
        !           553: parameter is sent with no trailing carriage return;
        !           554: if a carriage return must be sent after one of these, a separate
        !           555: send statement must provide it.
        !           556: .SH "OVERRIDING DEFAULTS"
        !           557: The script processor sets several default values. The following
        !           558: statements, which override these defaults, may be useful in
        !           559: certain circumstances.
        !           560: .TP 2.0i
        !           561: .BI "chrdly    " int
        !           562: Since many modems cannot accept dialing commands
        !           563: at full ``computer speed'', the script processor
        !           564: sends all strings with a brief inter-character
        !           565: delay. This statement specifies the delay time,
        !           566: in milliseconds. The default is 100 (0.1 second).
        !           567: .TP 2.0i
        !           568: .BI "pchar     " str
        !           569: Specifies the character to which 
        !           570: .BR P s 
        !           571: in the
        !           572: dial string should be converted. Default is
        !           573: ``,'', for use with Hayes-type modems.
        !           574: .TP 2.0i
        !           575: .BI "ptime     " int
        !           576: Specifies the time, in milliseconds, to allow in
        !           577: the default timeout for each pause character in
        !           578: the dial string. Default is 2000 (2 seconds).
        !           579: .TP 2.0i
        !           580: .BI "wchar     " str
        !           581: Specifies the character to which 
        !           582: .BR W s 
        !           583: in the
        !           584: dial string should be converted. Default is
        !           585: ``W'', for Hayes modems.
        !           586: .TP 2.0i
        !           587: .BI "wtime     " int
        !           588: Specifies the time, in milliseconds, to allow in
        !           589: the default timeout for each wait-for-dialtone
        !           590: character in the dial string. Default is 10000
        !           591: (10 seconds).
        !           592: .TP 2.0i
        !           593: .BI "dgttime   " int
        !           594: Specifies the time, in milliseconds, to allow in
        !           595: the default timeout for each digit character in
        !           596: the dial string. Default is 100 (0.1 second).
        !           597: .TP 2.0i
        !           598: .BI "ctime     " int
        !           599: Specifies the time, in milliseconds, to allow in
        !           600: the default timeout for carrier to appear after
        !           601: the dial string is sent. Default is 45000 (45
        !           602: seconds).
        !           603: .SH "SEE ALSO"
        !           604: uucico(8) for Taylor UUCP, and documentation for Taylor UUCP.
        !           605: .SH AUTHOR
        !           606: Robert B. Denny ([email protected])
        !           607: .SH HISTORY
        !           608: This program is an adaptation of the dial/login script processing 
        !           609: code that is a part of DECUS UUCP for VAX/VMS, written by Jamie 
        !           610: Hanrahan, et. al.
        !           611: .SH BUGS
        !           612: This version (1.1) does not support BSD terminal facilities. Anyone 
        !           613: volunteer to add this?
        !           614: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.