\input texinfo @c -*-texinfo-*- @c %**start of header @setfilename tap.info @setcontentsaftertitlepage @settitle Tap @c %**end of header @c information for a proper install @dircategory Communication Programs @direntry * Tap: (tap). A program to communicate with a serial line tap. @end direntry @c include commands and keystrokes with the regular index @syncodeindex fn cp @syncodeindex ky cp @ifinfo This file documents Tap, a program to read data from (and write data to) a serial port. Amongst other things, it may be used to facilitate the reverse engineering of serial communication protocols. Copyright @copyright{} 1999 Jonathan E duSaint @email{jon@@mbayweb.com}. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. @ignore Permission is granted to process this file through TeX and print the results, provided the printed document carries a copying permission notice identical to this one except for the removal of this paragraph (this paragraph not being relevant to the printed manual). @end ignore Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled ``Copying'' and ``GNU General Public License'' are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation. @end ifinfo @titlepage @title Tap 1.0 @subtitle A program to communicate with a serial line tap. @author Jonathan E duSaint @page @vskip 0pt plus 1filll Copyright @copyright{} 1999 Jonathan E duSaint @email{jon@@mbayweb.com} Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided also that the sections entitled ``Copying'' and ``GNU General Public License'' are included exactly as in the original, and provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation. @end titlepage @ifnottex @node Top, Introduction, , (dir) @comment node-name, next, previous, up @top Tap Tap is a program designed to read data from and write data to the serial port. As such it has a wide variety of applications. For example, it can be used to prototype serial hardware, or to read data from a serial line tap, which can facilitate the reverse engineering of serial line communication protocols. This documentation corresponds with version 1.0 of Tap. @end ifnottex @menu * Introduction:: An introduction to @code{Tap} and the manual. * The Command Line:: The ins and outs of the interface. * Command Overview:: A look at the commands. * Input and Output:: Communicating with the serial line. * The Set Command:: Setting the environment. * Index:: The command, concept, and keystroke index. @detailmenu --- The Detailed Node Listing --- * Conventions:: Document conventions. * Invocation:: How to start @code{Tap} and the command line options. * Overview:: A brief tour through @code{Tap}. * History:: How to use the history functionality. * Editing:: Command line editing. * C-B: Moving Left. Moving the cursor to the left. * Left Arrow: Moving Left. Moving the cursor to the left. * C-F: Moving Right. Moving the cursor to the right. * Right Arrow: Moving Right. Moving the cursor to the right. * C-A:: Moving the cursor to the start of the line. * C-E:: Moving the cursor to the end of the line. * C-D:: Deleting the character under the point. * C-H:: Deleting the character to the left of the point. * C-U:: Entering a numerical argument. * C-space: Killing and Yanking Text. Setting the mark position. * C-K: Killing and Yanking Text. Killing from the point to the end of the line. * C-W: Killing and Yanking Text. Killing in between the mark and the point. * C-Y: Killing and Yanking Text. Yanking text from the kill ring. * C-T:: Transposing characters. * C-L:: Clearing the screen. * tab:: Command line completion. * alias:: Assign a different name to a command. * capture:: Capture incoming data to a file or a register. * clear:: Clear the input window. * close:: Close an open serial port. * help:: Get help on a command. * open:: Open a serial port. * out:: Write format controlled data to the serial port. * print:: Print the contents of a file or a register. * quit:: Quit the program. * set:: Change the behavior of the program. * unalias:: Remove an alias. * Help:: The --help command line option. * version:: The --version command line option. * port:: The --port command line option. * save-history:: The --save-history command line option. @end detailmenu @end menu @node Introduction, The Command Line, Top, Top @comment node-name, next, previous, up @chapter Introduction This chapter serves as an introduction to the manual as well as to @code{Tap}, and documents the command line options. @menu * Conventions:: Document conventions. * Invocation:: How to start @code{Tap} and the command line options. * Overview:: A brief tour through @code{Tap}. @end menu @node Conventions, Invocation, Introduction, Introduction @comment node-name, next, previous, up @section Conventions @cindex Document, How to Read @cindex Explanation of the C-? Syntax @cindex C-? Syntax, Explanation of The syntax @dfn{C-whatever} means to press the @kbd{Control} key and to simultaneously press the @kbd{whatever} key. For example, @kbd{C-P} means to hold down the @kbd{Control} key, and then hit the @kbd{P} key. When the command definitions are presented, the command usage is put first. Then follows a description of the function. If there is more than one way to use a function, then each invocation is shown with an explanation after it. @node Invocation, Overview, Conventions, Top @comment node-name, next, previous, up @section Invocation @cindex Options @cindex Command Line Options @cindex Startup Options @cindex Invocation To start @code{Tap}, merely type @kbd{tap} at the shell prompt. If it is properly installed, you should be presented with the interface. If it isn't, then read the file @file{INSTALL} for information on how to do so. @code{Tap} can be invoked with several different command line options. @menu * Help:: The --help command line option. * version:: The --version command line option. * port:: The --port command line option. * save-history:: The --save-history command line option. @end menu @node Help, version, Invocation, Invocation @comment node-name, next, previous, up @subsection @code{--help} @findex --help @findex -h @cindex @code{help}, Command Line Option @code{--help}, @code{-h} Invoking @code{Tap} with this option will cause @code{Tap} to print a short help message to @var{stdout} and then exit. @node version, port, Help, Invocation @comment node-name, next, previous, up @subsection @code{--version} @findex --version @findex -v @cindex @code{version}, Command Line Option @code{--version}, @code{-v} Invoking @code{Tap} with this option will cause @code{Tap} to print version and copyright information to @var{stdout} and then exit. @node port, save-history, version, Invocation @comment node-name, next, previous, up @subsection @code{--port} @cindex Default Port @cindex Port, Opening on Invocation @findex --port @findex -p @cindex @code{port}, Command Line Option @code{--port} @file{serial port}, @code{-p} @file{serial port} With this option, @code{Tap} will open @file{serial port} at startup. If the serial port can't be opened, @code{Tap} will print an error message at startup. @node save-history, , port, Invocation @comment node-name, next, previous, up @subsection @code{--save-history} @findex --save-history @findex -s @cindex @code{save-history}, Command Line Option @cindex Saving History @cindex History, Saving @cindex History File @cindex Default History File @code{--save-history} @file{history filename}, @code{-s} @file{history filename} This option will cause @code{Tap} to read history information at startup from the file specified and to write history information at shutdown to the file. If the file specified doesn't exist, it will be created, and if no file is specified, the default will be used, which is usually @file{~/.tap_history}. @node Overview, , Invocation, Introduction @comment node-name, next, previous, up @section Overview @findex help, Command This overview assumes that @code{tap} is already properly installed on your system. If it isn't, read the file @file{INSTALL} for instructions. To start, invoke @code{tap} from the command line by typing @kbd{tap}. Once it is started, you will notice that the screen is divided into two parts, both with headers. The top part is called the @dfn{input window} and the bottom part is called the @dfn{output window}. At the bottom of the screen is the status bar. It should state that no serial port is open on one side, and suggest typing @code{help} for help. As a first experiment, try typing @code{help}. You will be presented with a brief summary of all of the commands available. To get more specific help information, type @code{help command-name} @node The Command Line, Command Overview, Introduction, Top @comment node-name, next, previous, up @chapter The Command Line @cindex Command Line Interface If you are familiar with @code{Bash} or @code{Emacs}, then you should already have a good grasp of most of the functionality of the command line interface. While @code{Tap} doesn't actually use the @code{GNU Readline} or the @code{GNU History} libraries, the interface was designed to be very similar. All commands are saved in a history list, although if a command is repeated one or more times, only one copy is saved. Also, while entering text on the command line, a variety of keystrokes are available for command line editing. @menu * History:: How to use the history functionality. * Editing:: Command line editing. @end menu @node History, Editing, The Command Line, The Command Line @comment node-name, next, previous, up @section History @cindex History Functionality @cindex History List @cindex History File @kindex C-P @kindex C-N @kindex Up Arrow @kindex Arrow, Up @kindex Down Arrow @kindex Arrow, Down Every time a command is entered, it is automatically inserted into the internal history list. However, if the command is identical to the previous command, a list entry is not made. To access previous entries, press either @kbd{Up Arrow}, or @kbd{C-P}. To access more recent entries, press either @kbd{Down Arrow}, or @kbd{C-N}. If a previous entry is edited and @kbd{Enter} is not pressed, the edited copy will be saved in the place of the original. However, once @kbd{Enter} is pressed, the original copy will once again be available. When @code{Tap} is invoked with the @code{--save-history} (@pxref{save-history}) option, all history entries are read at startup from the file specified, or, if one isn't specified, from the default file. At shutdown, the current history list is appended onto the file. If a file is specified that doesn't exist, then one will be created at shutdown. @node Editing, , History, The Command Line @comment node-name, next, previous, up @section Editing @cindex Command Line Editing @cindex Editing, Command Line @code{Tap} contains features for editing the current command line. The keystrokes are the same as used in @code{Emacs} and in the @code{Bash} shell's @code{Emacs} mode. @menu --- list of keystrokes --- * C-B: Moving Left. Moving the cursor to the left. * Left Arrow: Moving Left. Moving the cursor to the left. * C-F: Moving Right. Moving the cursor to the right. * Right Arrow: Moving Right. Moving the cursor to the right. * C-A:: Moving the cursor to the start of the line. * C-E:: Moving the cursor to the end of the line. * C-D:: Deleting the character under the point. * C-H:: Deleting the character to the left of the point. * C-U:: Entering a numerical argument. * C-space: Killing and Yanking Text. Setting the mark position. * C-K: Killing and Yanking Text. Killing from the point to the end of the line. * C-W: Killing and Yanking Text. Killing in between the mark and the point. * C-Y: Killing and Yanking Text. Yanking text from the kill ring. * C-T:: Transposing characters. * C-L:: Clearing the screen. * tab:: Command line completion. @end menu @node Moving Left, Moving Right, Editing, Editing @comment node-name, next, previous, up @subsection Moving Left @kindex C-B @kindex Left Arrow @kindex Arrow, Left @cindex Point Movement @cindex Cursor Movement @kbd{C-B}, @kbd{Left Arrow} Both of these keystrokes will move the point one character to the left, if possible. @node Moving Right, C-A, Moving Left, Editing @comment node-name, next, previous, up @subsection Moving Right @kindex C-F @kindex Right Arrow @kindex Arrow, Right @cindex Point Movement @cindex Cursor Movement @kbd{C-F}, @kbd{Right Arrow} Both of these keystrokes will move the point one character to the right, if possible. @node C-A, C-E, Moving Right, Editing @comment node-name, next, previous, up @subsection @kbd{C-A} @kindex C-A @cindex Cursor Movement @cindex Point Movement @cindex Start of Line, Moving the Point to @kbd{C-A} This keystroke will move the point to the start of the line. @node C-E, C-D, C-A, Editing @comment node-name, next, previous, up @subsection @kbd{C-E} @kindex C-E @cindex Cursor Movement @cindex Point Movement @cindex End of Line, Moving the Point to @kbd{C-E} This keystroke will move the point to the end of the line. @node C-D, C-H, C-E, Editing @comment node-name, next, previous, up @subsection @kbd{C-D} @kindex C-D @kindex Delete @cindex Deleting Characters @kbd{C-D}, @kbd{Delete} Both of these keystrokes will delete the character under the point. @node C-H, C-U, C-D, Editing @comment node-name, next, previous, up @subsection @kbd{C-H} @kindex C-H @kindex Backspace @cindex Deleting Characters @kbd{C-H}, @kbd{Backspace} Both of these keystrokes will delete the character to the left of the point. @node C-U, Killing and Yanking Text, C-H, Editing @comment node-name, next, previous, up @subsection @kbd{C-U} @kindex C-U @cindex Entering Numerical Arguments @cindex Numerical Arguments, Entering @cindex Arguments, Numerical @cindex Numerical Arguments @kbd{C-U} This command prompts for a number. After the number is entered, press @kbd{Enter}, and then the desired key. If the key entered was @kbd{C-Y} (@pxref{Killing and Yanking Text}), then text from the kill ring will be entered. If @kbd{Enter} was pressed, then it will be just as if @kbd{Enter} had been pressed without the argument (i.e. the command line will be processed). Any other key will be repeated as many times as was indicated by the number. For example, type @example @kbd{C-U} @kbd{2} @kbd{0} @kbd{Enter} @kbd{a} @end example @noindent to insert 20 copies of the letter `a', or type @example @kbd{C-U} @kbd{5} @kbd{Enter} @kbd{C-D} @end example @noindent to delete the character under the point and four to the right of it. @node Killing and Yanking Text, C-T, C-U, Editing @comment node-name, next, previous, up @subsection Killing and Yanking Text @kindex C-space @kindex C-W @kindex C-K @kindex C-Y @cindex Killing Text @cindex Yanking Text @cindex Kill Ring @cindex Copying Text @cindex Cutting Text @cindex Pasting Text @cindex Setting the Mark @cindex Mark, Setting @kbd{C-space} Set the mark. @kbd{C-W} Kill the text from the mark to the point. @kbd{C-K} Kill the text from the mark to the end of the line. @kbd{C-Y} Yank from the kill ring and insert it at the point. Tap utilizes a kill ring for storage of text which has been killed using the above commands. The single character delete commands will not store anything to the ring. The @kbd{C-Y} command will only yank the most recent entry. In order to yank older entries than that, it must be used in combination with the @kbd{C-U} command (@pxref{C-U}). For example, type @example @kbd{C-U} @kbd{3} @kbd{Enter} @kbd{C-Y} @end example @noindent to insert the text from the third to last kill. @node C-T, C-L, Killing and Yanking Text, Editing @comment node-name, next, previous, up @subsection @kbd{C-T} @kindex C-T @cindex Transposing Characters @cindex Characters, Transposing @kbd{C-T} This keystroke transposes the character under the point with the character to its left. @node C-L, tab, C-T, Editing @comment node-name, next, previous, up @subsection @kbd{C-L} @kindex C-T @cindex Clearing the Screen @kbd{C-L} This keystroke clears the screen and redraws the current line. @xref{clear}. @node tab, , C-L, Editing @comment node-name, next, previous, up @subsection @kbd{tab} @kindex tab @cindex Command Line Completion @cindex Completion, Command @cindex Command Completion @kbd{tab} Pressing the tab key will complete the token under the point, if at all possible. If the point is over the first token, then a command completion will be attempted. If it is over any other token, a completion will be attempted, based on the arguments that the command takes. If only a partial completion is possible, the token is completed as far as it can be, and all of the matching completions are printed out. If no completion is possible, the program just beeps. @node Command Overview, Input and Output, The Command Line, Top @comment node-name, next, previous, up @chapter Command Overview @cindex Commands @cindex Command Overview These are descriptions of all of the commands. Some commands are documented elsewhere, so for them, there will be only a short description. @menu * alias:: Assign a different name to a command. * capture:: Capture incoming data to a file or a register. * clear:: Clear the input window. * close:: Close an open serial port. * help:: Get help on a command. * open:: Open a serial port. * out:: Write format controlled data to the serial port. * print:: Print the contents of a file or a register. * quit:: Quit the program. * set:: Change the behavior of the program. * unalias:: Remove an alias. @end menu @node alias, capture, Command Overview, Command Overview @comment node-name, next, previous, up @section @code{alias} @findex alias, Command @cindex Aliasing Command Names @cindex Renaming Commands @code{alias} Invoking @code{alias} with no arguments will print out all of the aliases which have been assigned. @code{alias} @var{alias} The @code{alias} command with one argument will print out the alias and the command to which it is aliased. @code{alias} @var{alias} @var{command} With two options, @code{alias} will assign @var{alias} to @var{command} so that when @var{alias} is entered, the program will act as if @var{command} itself had been entered. This command can be very useful to decrease the amount of typing necessary. If, for example, the @code{out} (@pxref{out}) command were to be aliased to @code{o}, then rather than typing @example out foo bar\n @end example @noindent it would be possible to merely type @example o foo bar\n @end example @noindent which doesn't save that much typing, but does illustrate the point. However, @code{alias} is limited to aliasing commands only, so it is not possible to type something like @example alias bin 'set if bin' @end example Also see @ref{unalias}. @node capture, clear, alias, Command Overview @comment node-name, next, previous, up @section @code{capture} @code{capture} @option{file} @file{filename} When invoked in this manner, @code{capture} starts capturing data recieved from the serial port to @file{filename}. Only one file may be open at a time. @code{capture} @option{file} @option{off} This causes @code{Tap} to stop capturing data and to close the file. @code{capture} @option{register} @option{1--64} @code{capture}, when invoked like this, will cause @code{Tap} to start capturing data to a register. Data is captured until it is turned off, as described below, or the register is full. The size of the registers may be changed by using the command @code{set}. @code{capture} @option{register} @option{off} This stops the capturing to the register. @xref{set}, and @ref{The Set Command}. @node clear, close, capture, Command Overview @comment node-name, next, previous, up @section @code{clear} @code{clear} Invoking clear will clear the input window. @xref{C-L}. @node close, help, clear, Command Overview @comment node-name, next, previous, up @section @code{close} @code{close} This command closes the currently open serial port. @node help, open, close, Command Overview @comment node-name, next, previous, up @section @code{help} @code{help} When invoked without a command name, @code{help} prints a short description of every command. @code{help} @option{command name} This provides help on individual commands. @node open, out, help, Command Overview @comment node-name, next, previous, up @section @code{open} @code{open} @option{serial port} @code{open} opens a serial port and prepares it for communication. The properties of the serial port may be changed with the command @code{set}. @xref{set}. @node out, print, open, Command Overview @comment node-name, next, previous, up @section @code{out} @code{out} @option{data} The @code{out} command writes data to the serial port. @xref{Input and Output}. @node print, quit, out, Command Overview @comment node-name, next, previous, up @section @code{print} @code{print} @option{file} If a file is currently being captured to, this will print the contents of that file. If no file is open, then an error will be thrown. @code{print} @option{file} @file{filename} This prints the contents of the file specified in @file{filename}. @code{print} @option{file} @file{filename} @option{bytes} This does the same as above, but only prints the first @option{bytes} number of bytes. @code{print} @option{register} If a register is currently being captured to, this will print its contents. If one isn't being used, then an error will be thrown. @code{print} @option{register} @option{register number} This will print the contents of the register specified. @code{print} @option{register} @option{register number} @option{bytes} This will print the first @option{bytes} number of bytes of the specified register. @node quit, set, print, Command Overview @comment node-name, next, previous, up @section @code{quit} @code{quit} This command quits the program, closing any open files and the serial port, if one is open. @node set, unalias, quit, Command Overview @comment node-name, next, previous, up @section @code{set} @code{set} @option{options} The @code{set} command adjusts various run time parameters of @code{Tap}. @xref{The Set Command}, for a full explanation. @node unalias, , set, Command Overview @comment node-name, next, previous, up @section @code{unalias} @code{unalias} @option{alias} The @code{unalias} command removes the alias @option{alias} from the alias list. @node Input and Output, The Set Command, Command Overview, Top @comment node-name, next, previous, up @chapter Input and Output @node The Set Command, Index, Input and Output, Top @comment node-name, next, previous, up @chapter The Set Command Often, while working with @code{Tap}, you will find that you might want to change some of the operational parameters. @node Index, , The Set Command, Top @comment node-name, next, previous, up @unnumbered Command, Concept, and Keystroke Index @printindex cp @contents @bye