Source Code 1992 March

home *** CD-ROM | disk | FTP | other *** search

/ Source Code 1992 March / Source_Code_CD-ROM_Walnut_Creek_March_1992.iso / usenet / altsrcs / 3 / 3449 / beav1.doc

Wrap

Text File | 1991-06-07 | 31.3 KB | 1,209 lines

BEAV Binary Editor And Viewer Manual Copyright 1991 Version 1.20 March 13, 1991 By Peter Reilley 19 Heritage Cir. Hudson, N.H. 03051 pvr@wang.com BEAV source and executable can be freely distributed for non-commercial purposes. BEAV User Manual Table of Contents 1. Introduction 2. Overview 2.1 Terms and Definitions 2.2 The Screen Format 2.3 Display Modes 2.4 Commands 2.5 Buffers 2.6 Files 2.7 Key Binding 2.8 Configuration 3. Command Description 3.1 Help 3.2 Cursor Movement 3.3 Buffer Management 3.4 File Management 3.5 Window Management 3.6 Inserting and deleting 3.7 Search and Replace Commands 3.8 Exiting BEAV 3.9 Printing 3.10 Keyboard Macros 3.11 Key Binding 3.12 Special Functions 4. Alphabetical list of commands by name 5. Alphabetical list of commands by default key binding 6. Release notes - 2 - BEAV User Manual 1.0 Introduction BEAV is an editor that brings the features of a powerful full screen editor to the editing of binary files. It is the only editor that I know of that does that. When you need to edit a non-text file you generally have two choices; a text editor or a file zap type editor. Each choice has significant disadvantages. Text editors expect the file to be formatted in a certain way. At a minimum they expect that all lines be terminated by a carriage return or line feed and be limited in length. There is no line length limit with BEAV. Most text editors get confused by bytes that are outside of the normal range (20 to 7E HEX). In BEAV no special characters such as carriage return or line feed affect the display aside from producing their numeric value. BEAV can edit any file no matter the format. The other choice is to use a file zap type editor which can edit a binary file without difficulty. These editors are often very limited in their features and capabilities. Most file zap programs can edit a file only in HEX or ASCII. They generally operate on a sector basis and because of this they cannot insert or delete data in the middle of the file. All these limits are eliminated in BEAV. You can edit a file in HEX, ASCII, EBCDIC, OCTAL, DECIMAL, and BINARY. You can search or search and replace in any of these modes. Data can be displayed in BYTE, WORD, or DOUBLE WORD formats. While displaying WORDS or DOUBLE WORDS the data can be displayed in INTEL's or MOTOROLA's byte swap format. Data of any length can be inserted at any point in the file. The source of this data can be the keyboard, another buffer, or a file. Any data that is being displayed can be sent to a printer in the displayed format. Files that are bigger than memory can be handled. Some users may recognize the similarity to the EMACS text editor that was written by Richard Stallman at MIT. This is not a coincidence. I attempted to keep as much of the user interface and functionality as possible given the very different tasks of EMACS and BEAV. - 3 - BEAV User Manual 2. Overview 2.1 Terms and Definitions Throughout this manual certain terms will be used to describe the operation and structure of BEAV. The data that BEAV is editing is held in a buffer that is structured as a byte stream. There are many commands that affect the way that this byte stream is displayed on to the screen. Whatever display mode is chosen the data in the buffer is not effected, only the presentation. One such choice is to display the data as bytes, words, or double words. That is; 8 bit values, 16 bit values, or 32 bit values. Whatever choice is made the value of the selected size will be displayed. These values are referred to as units in this manual. Thus the 'delete-forw-unit' command deletes the unit under the cursor. If 32 bit units are being displayed then 4 bytes will be deleted. Many commands in BEAV start by pressing the 'ESCAPE' key. When this manual refers to a command that requires that the 'ESCAPE' key be pressed it will be abbreviated with 'Esc'. Another frequently used key stroke to start commands is 'CONTROL X'. This in done by pressing the 'CONTROL' key then pressing the 'X' key at the same time. In this manual this will be abbreviated by 'Ctl-X'. Many commands contain other control characters and these will be abbreviates similarly. Thus the 'insert-unit' command will be listed as 'Ctl-X I'. This will be entered by pressing the CONTROL key and while holding it hitting the 'X' key, release the CONTROL key then hit the 'I' key. 2.2 The Screen Format BEAV presents information to the user in a number of areas. The first is the window. There will be at least one window displayed on the screen at all times. The window consists of two areas. The first is the display area. This is where the data that is in the buffer is displayed. Most of the time the cursor will be in this area, as this is where most editing is done. Each line in the display area will start with a number that indicates the offset into the buffer for this line of data. At the bottom of the display area for each window is the status line. - 4 - BEAV User Manual The status line presents the user with a number of specific pieces of information. The first is the program name which is "BEAV". Next there are some flags indicating the status of this particular buffer. The first flag indicates if the buffer has been damaged by a memory allocation failure. If there is a '?' then the buffer is bad, otherwise there will be a space. Bad buffers are set to read only. The next flag indicates if the buffer has been changed and will need to be written out if the changes are to be saved. This flag is a '*' if the buffer has been changed, otherwise there will be a space. The next flag indicates insert/overstrike mode; 'I' for insert, 'O' for overstrike. This is only meaningful in ascii or ebcdic mode. Then the buffer name followed by the file name. A window can be in read only, read/write, or read/write with size lock. These will be displayed as [RO], [RW], or [WL] respectively. If auto-update is enabled then [AU] will be displayed. Next the cursor position in bytes and the character position within the unit. The next piece of information gives the format that the data is being displayed in; HEX, OCTAL, DECIMAL, BINARY, ASCII, EBCDIC. If a data mode is selected then the size in bytes (1, 2, 4) is displayed. If the data is being displayed in Intel mode then the swapped flag is displayed, 'S'. Lastly the byte shift is displayed; 0 only for 8 bit data, 0 or 1 for 16 bit data, or 0, 1, 2 or 3 for 32 bit data. There can be multiple windows on the screen at the same time but each window will have a status line at the bottom. The very bottom line on the screen is the prompt line. This is where you enter data that BEAV requests. If you want to edit a new file you would type 'Ctl-X Ctl-V', BEAV would respond with "Visit file:" on the prompt line. The cursor would be positioned after the prompt. You would then enter the name of the file that you wished to edit. - 5 - BEAV User Manual If you entered the command by mistake, you can abort the operation by typing a 'Ctl-G'. 'Control G' is a universal abort command and can be used anywhere. If you want to perform a search you will enter the search string on this line. When you have entered the information that BEAV has requested hit 'Return' and the cursor will return to it's original position in the window display area. The prompt line is also where error messages are displayed. - 6 - BEAV User Manual 2.3 Display Modes The data in the buffer can be displayed in a number of formats. First there is the display mode. This can be either; HEXADECIMAL, DECIMAL, OCTAL, BINARY, ASCII, or EBCDIC. If ASCII or EBCDIC mode is chosen then each byte in the buffer will be converted to it's ASCII or EBCDIC character and displayed. Bytes that are outside of the standard character set will be displayed as a dot. Each line will be 64 characters long. The byte value for "carriage return" and "line feed" will be displayed as a dot as any other non-printable characters. Within HEXADECIMAL, DECIMAL, OCTAL, or BINARY format the data can be displayed in 8, 16 or 32 bit values. If 16 or 32 bit values are displayed the user can choose to view these values in either the Intel format or the Motorola format. If Intel format is chosen then the first byte in each unit is the least significant byte when the value is calculated. Thus in hex 32 bit mode a byte string of "32 7A 9F 10" would be displayed as "109F7A32". If Motorola format is chosen this value would be displayed as "327A9F10". There is another display format choice that affects the 16 or 32 bit formats. This is called shift. The shift can be 0 or 1 for 16 bit modes, or 0, 1, 2, 3 for 32 bit modes. Shift moves the zero point reference for the buffer up by the selected value. The default is zero shift. If a buffer is displaying the following 32 bit hex data; "12345678 2F4792AF 673DFEA1 88551199" with the shift at 0. Changing shift to 1 will produce; "3456782F 4792AF67 3DFEA188 55119955" The data has been slid down toward the beginning of the buffer by one byte. This has not changed the data in the buffer at all, it has only affected the way that the data is presented on the screen. This is useful when looking at WORD or DOUBLE WORD data that is not aligned on two or four byte boundaries. When BEAV is first started or a new window is opened the default format is HEXADECIMAL BYTES. - 7 - BEAV User Manual 2.4 Commands Commands are the means that the user controls the operation of BEAV. A command can be given by using one of two methods. The first is to use the key binding. A command can have one or more associated key bindings. It can also have no key binding. There are a set of default key bindings that BEAV comes configured with. The current set of key bindings can be seen by using the 'help' command. The 'help' command is 'Esc ?' or Function Key 1 'F1' on the IBM PC. The help buffer can be scrolled by using the up and down arrow keys. A printed copy may be obtained by going to the bottom of the help buffer using the 'move-to-end' command ('Esc >' or the 'End' key). Then issue the 'print-mark-to-cursor' command ('Esc P' or 'Ctl-Print') and enter 'PRN' or a file name when prompted with "Print to:". This will output the entire help buffer to a printer connected to the parallel interface or the specified file. The second method of issuing a command is to use the 'extended-command' command (Esc X). You are prompted for a command name that you want to execute. This method is useful for executing commands that have no key binding. 2.5 Buffers Buffers are the in memory storage for all data editing and viewing. Each buffer has a name that appears in the mode line. Buffers generally have a file name that is associated with them. The file name also appears in the mode line. The buffer name and the file name are independent but the buffer name defaults to the file name. The buffer name is used to refer to a specific buffer. The 'change-buffer' ('Ctl-X B') command will prompt you for a buffer name. After you enter a buffer name that buffer will be displayed in the current window. If there is no such buffer, one will be created and displayed (it will be empty). When BEAV is run with a file name as a command line parameter, the file is read into a new buffer. The buffer name will be made the same as the file name. The file name is only used when the buffer is saved. If the file name is changed using the 'buffer-set-file-name' ('Ctl-X Ctl-F') command then when the buffer is saved it will be saved to the new file. - 8 - BEAV User Manual Buffers are dynamically allocated. They grow or shrink as the size of the data they contain changes. The buffer size can be frozen using the 'buffer-size-lock' ('Ctl-X Ctl-L') command. This prevents inserting or deleting data from the buffer but data can be modified. Buffers continue to exist even if they are not being displayed. Buffers are saved in a linked list that can be stepped through using the 'change-to-next-buffer' ('Esc +') or 'change-to-prev-buffer' ('Esc -') commands. If the 'change-to-next-buffer' command is given then the next buffer in the list is displayed in the current window. 2.6 Files Files are the means of storing data on disk. Files or segments of files can be loaded into BEAV for editing or viewing. The file on the disk has not been changed until BEAV does a save to that file. When a save to a file is performed the original file contents in saved in a ".bak" file. - 9 - BEAV User Manual 2.7 Key Binding All commands in BEAV have a command name and a default key binding. The bindings may be changed to suit personal preference by using the 'bind-to-key' ('Esc K') command. The current binding of a key sequence can be displayed by using the 'binding-for-key' ('Ctl-X ?') command. Key bindings can be loaded automatically from a file named "beavrc". This file must be in a directory specified by the PATH environment variable. When BEAV is started this file is read and the bindings are loaded. This file is a simple text file and can be edited to make changes. The beavrc file contains three columns. The first is the function name to be bound. The second is the key sequence that is bound to that function. The third is a number that defines the key code. Then the beavrc file is read in only the first and third columns are used. The simplest way to create a valid beavrc file is to first bind the key codes to the desired functions using the bind-to-key command. Next display the current bindings in a window using the help command (Esc ?). Now save that buffer to a file with the file-write command (Ctl-X Ctl-W). You will be prompted for a file name. This is a valid beavrc file. You may want to edit the beavrc file to remove the commented lines, those beginning with #, to make it load faster. On unix systems there can be multiple beavrc files, one for each terminal type. This is accomplished by appending the TERM variable to beavrc. Thus if you use both a vt100 and a wyse60 terminal, you could have a beavrc.wy60 and a beavrc.vt100 bindings file. When your TERM variable is TERM=wy60 then the beavrc.wy60 bindings file will be used. If there is no beavrc.wy60 file then the beavrc file will be used. 2.8 Configuration When the MSDOS version of BEAV run it detects whether the system is an IBM PC or a clone. If a PC is detected then a set of key bindings that use the 10 function keys and the relevant keypad keys are loaded. If the system is not recognized then only the standard bindings are loaded. - 10 - BEAV User Manual If a PC is detected the screen is managed by making BIOS level calls that enhance performance. Otherwise, the screen is controlled by making ANSI compatible calls to the operating system. This is much slower but is not sensitive to hardware configuration. This requires that non-standard MSDOS systems support ANSI display controls. The following ANSI escape sequences are used; Position cursor ESC [ <row> ; <column> H Erase to end of line ESC [ 0 K Erase to end of page ESC [ 0 J Normal video ESC [ 0 m Reverse video ESC [ 7 m On unix systems the termcap library is used. This requires that the TERM environment variable be set correctly. - 11 - BEAV User Manual 3. Command Description This section describes all BEAV commands as to their function and any side effects that they may have. The first line of each description of a command will begin with the default key binding then the command name and follows with the key binding for a PC for the MSDOS version. 3.1 Help This command returns information that will aid in the use of BEAV. Esc ? help F1 A new window is opened by splitting the current window then all current key bindings are displayed. This buffer is larger than can be shown at one time and must be scrolled up and down to see all entries. All commands that do not alter data can be used to move around and search the help buffer. To leave the help buffer use the 'window-delete' command ('Ctl-X 0'). Lines that begin with the comment character (#) are commands that have the default bindings. Lines without the comment character have been bound by the user or by processing a beavrc file. The comment character helps in creating a beavrc file by identifying only those bindings that have changed. - 12 - BEAV User Manual 3.2 Cursor Movement There are a number of commands that move the cursor around the current window. If the cursor bumps the top or the bottom of the window the position of the window will be adjusted so as to keep the cursor within the bounds. When the window is moved in response to cursor movements it is moved by about one third of the window size. This improves performance by reducing the number of window moves. Ctl-P move-back-line North (up arrow) Ctl-N move-forw-line South (down arrow) These commands move the cursor up one line or down one line. If the cursor is on the top line in the buffer and a 'move-back-line' command is given the cursor will jump to the beginning of the first unit in the buffer. If the cursor is on the last line of the buffer and a 'move-forw-line' is given the cursor will move to the last unit in the buffer. Ctl-F move-forw-char East (right arrow) Ctl-B Move-back-char West (left arrow) These commands move the cursor forward or backward in the current line. If the cursor is at the first character in the first unit of the line and the 'move-back-char' command is given then the cursor will wrap to the last character of the previous line. If the cursor is at the last character of the last unit in the current line then it will wrap to the first character of the next line. Esc F move-forw-unit Ctl-East Esc B move-back-unit Ctl-West These commands are similar to the above set but they move the cursor by units rather than characters. The command 'move-forw-unit' will position the cursor to the first character of the next unit. The command 'move-back-unit' will move the cursor to the first character of the previous unit. Ctl-V move-forw-page PageUp Esc V move-back-page PageDown These commands move the move the data in the window by the number of lines in the window less one. The cursor will stay in the same position relative to the window as the data is moved. - 13 - BEAV User Manual Esc < move-to-beginning Home Esc > move-to-end End Move the cursor to the beginning or the end of the buffer. Ctl-X G move-to-byte F9 Prompt for a byte offset, then go to that position in the current buffer. Ctl-X Ctl-N move-window-down Ctl-Z Ctl-X Ctl-P move-window-up Esc Z Move the buffer in the window up or down by one line. This does not effect the cursor until it hits the top or bottom of the window. Esc . mark-set F2 Set the mark position to the current cursor position. The mark position is remembered even for nonactive windows and buffers. Ctl-X Ctl-X swap-cursor-and-mark The position of the cursor and the position of the mark are swapped. Esc L window-link This command causes all windows that are displaying the contents of the current buffer to have the same cursor position. Thus if one window is scrolled then all other windows that display that buffer are scrolled so as to keep the cursor in the window. Ctl-X = show-position The current position of the cursor and the mark are displayed. The buffer size, file size and file name are also shown. - 14 - BEAV User Manual 3.3 Buffer Management Buffers store all data that is being edited. The only limit to the number of buffers is the size of available memory. If a file is loaded into a buffer and there is insufficient memory to hold the entire file, then it will be loaded until memory is exhausted. The buffer will then be set to read only mode. Ctl-X Ctl-B buffers-display Ctl-F1 A new window is opened and a list of all buffers in BEAV is displayed. The list contains the buffer name, the file name (if it exists), the buffer size, and a state flag. If the list is too large for the window, you can go to that window and scroll the list. Ctl-X B change-buffer Ctl-F2 This command prompts you for a buffer name. If you enter the name of an existing buffer, that buffer will be displayed in the current window. If the name does not match an existing buffer, a new buffer will be created and displayed. This buffer will be empty and will have no file name. Esc + change-to-next-buffer Ctl-F4 Esc - change-to-prev-buffer Ctl-F5 The next or the previous buffer in the buffer list is displayed in the current window. This does not effect buffers that are displayed in other windows. Esc G move-to-buffer-split Prompt for a buffer name. Then split the current window and display that buffer, creating it if necessary. Esc Ctl-N buffer-set-name Esc Ctl-N The current buffer name is changed to the name that you enter. This does not effect the file name. Ctl-X Ctl-F buffer-set-file-name Ctl-F7 The file name of the current buffer is changed to the name that you enter. This does not affect the buffer name. - 15 - BEAV User Manual Ctl-X K kill-buffer Ctl-F3 This command prompts you for a buffer name. This buffer is then deleted. If the buffer is currently being displayed you are prompted for conformation. If the buffer has been changed you are again prompted for conformation. Ctl-X Ctl-L buffer-size-lock The buffer size is prevented from being changed. Data can be edited but only by changing the existing data. If a buffer is copied into a size-locked buffer the operation well be successful but will overwrite existing data. This command toggles between locked and unlocked. Esc Y yank-buffer Ctl-F6 Data from one buffer is inserted into the current buffer at the cursor position. You are prompted for the name of the buffer to copy from. Esc O save-mark-to-cursor Prompt for a buffer name. Create a new buffer with that name and write the data from the mark to the cursor into that buffer. - 16 - BEAV User Manual 3.4 File Management These commands control BEAV's access to files. Files are loaded into buffers or are written from buffers. Commands that prompt for a file name also accept range parameters. Range parameters are always given in the numeric base of the current window. Thus if you are displaying data in decimal format then the range parameters must be entered in decimal. The size of a file read or write can be limited by specifying a range. The range parameter specifies the offset into the file, not the buffer. Range parameters can be specified in these forms; <file name> <start address> <file name> <start address> <end address> <file name> <start address> +<length> The first form causes the read or write to begin from the <start address> value until the end of the buffer on write or the end of the file on read. The second form reads or writes from <start address> until <end address> non-inclusive. The third form reads or writes from <start address> for <length> bytes. Thus, if the command 'file-read' is given and you enter at the prompt; main.obj 1000 +100. If the current display mode is hex, the file "main.obj" will be read from hex byte address 1000 to 10FF into the buffer. Ctl-X Ctl-R file-read Sh-F2 Prompt for a file name and read that file into the current buffer. This overwrites the current contents of the buffer. The buffer name is not changed but the buffer file name is set to the new file name. Ctl-X Ctl-S file-save Sh-F3 Write the current buffer out to the file if it has been changed. If the buffer has not been changed then do nothing. - 17 - BEAV User Manual Ctl-X V file-view Prompt for a file name and read file into a new buffer and display in current window. Set to read-only mode. Ctl-X Ctl-V file-visit Sh-F4 Prompt for a file name. If the buffer already exists then display it in the current window. Otherwise, read file into a new buffer and display in current window. If there is no such file then create it. Esc U file-visit-split Same as above but split current window and display new buffer. This displays the new buffer as well as the old buffer. Ctl-X Ctl-W file-write Sh-F5 Prompt for a file name, then write the current buffer to that file. Ctl-X Tab insert-file Sh-F8 Prompt for a file name and insert that file into the current buffer at the cursor position. Ctl-X Return save-all-buffers Sh-F6 Write all buffers that have been changed to their respective files. - 18 - BEAV User Manual 3.5 Window Management BEAV presents information to the user in one or more windows. Each window is a view into a buffer where the data is actually stored. The window controls how this data is formatted for display to the user. Data can be displayed as HEX bytes, OCTAL bytes, ASCII characters, plus many others. The display format is associated with the window. Thus if a new buffer is displayed in the current window that new data will be displayed in the current windows format. The only limit to the number of windows is the screen size. A window can be no smaller than two lines. This along with the mode line associated with each window limits to eight the number of windows on an IBM PC 25 line screen. Any window can view any buffer including having many windows on the same buffer. For example, two windows can display the same buffer but present the data in two different modes. One window could display HEX bytes and the other could display ASCII characters. Ctl-P change-window-back Ctl-PageUp Ctl-N change-window-forw Ctl-PageDown These commands move the cursor to the next or previous window on the screen, making it the current window. Ctl-X Z window-enlarge Ctl-X Ctl-Z window-shrink Enlarge or shrink the current window size by one line. Esc ! window-reposition Move window position so that the cursor is centered in the window. The cursor position in the buffer does not change. Ctl-X 2 window-split Split the current window into equal parts. Both haves have the same display mode and view the save buffer. Ctl-X 1 window-single Expand the current window to fill the entire display, all other windows are removed. Make the current window the only window displayed. This has no effect on the underlying buffers except that they may not be displayed any more. - 19 -