HexEd V1.20 Copyright (C) 1995-98 Ullrich von Bassewitz What it is ---------- HexEd is a hex editor. It features * a user friendly, menu driven interface * multiple windows * multiple operating system support (DOS, OS/2, Linux, FreeBSD) * national language support * freeware, even for commercial use * full source code Please see the section titled "Copying" below for copying conditions. Why another binary editor? -------------------------- HexEd is a test case. More than one year ago, I started to develop a portable text mode class library. Because I've been a happy Linux user for more than one and a half year now, I thought about supporting Linux. So, at the end of february '95, I started porting the library to Linux. When I thought about releasing the library for Linux, I realized, that - without a sample program - no one would be interested to have even a look at the library. So I decided to write a demo application that shows the features of my class library. This demo application is HexEd. Program operation ----------------- HexEd is a full menu driven program. If you start it by typing "hexed" from the command prompt, you will be able open or close files by menu. Many of the menu selections have hotkeys that work in (almost) every situation. If a menue entry has a hotkey, it is shown to the right of the menu entry. The most important hotkeys that are valid in a given context are also visible in the status line. Command line parameters ----------------------- You can use command line parameters when starting the program. Use filenames mixed up with one or more of the following options. An option has influence on any parameters that follow the option. -mh Default edit mode is hex -ma Default edit mode is ASCII -ms Default edit mode is show -mr Default edit mode is readonly Only the first 9 filenames on the command line are accepted, all others are silently ignored. The menu functions ------------------ HexEd/About HexEd... This shows a info box with the program version, the name of the program author and his email address. File/Open Open a new file for editing. This selection may be grayed if you have already 9 windows open. A file selector pops up if you select this entry. Enter the name of the file to edit or choose an existing file from the file list. There is an extra paragraph below describing the features of the file selector. File/Save Save any changes back to the original. If the file has a shadow file (see "Program options" below), the shadow file is copied back to the original. If the file has no shadow file, the buffer, that holds the current window data is written out. File/Save all Like "File/Save" but saves the data of all open windows. File/Search Same as pressing Alt+S when editing a window: Search for a string in the file. When entering the search string, you can use the following escape sequences: \\ Means one backslash. This is needed because '\' prefixes an escape sequence. \n A newline (ASCII 0x0d) \r A return (ASCII 0x0a) \t A tab (ASCII 0x09) \xAA The character with the hexadecimal code AA You are able to search for null bytes by entering "\x00" in the search string. As a result of the search, the cursor will be positioned to the location of the string or a window pops up, saying that the string has not been found. Searching starts at the character after the cursor and goes on until the string is found or end of file is reached (you can force HexEd to wrap the search at the end of file, see the section "Program options" below). File/Position Enter a new file position. If the input is preceeded by "0x" it is interpreted as hexadecimal. The accel key for this function is Alt+P. File/Quit End HexEd. This will close all open windows and exit the program. You can use the accel key Alt+X instead. Window/Tile This arranges all windows so that every window is fully visible. If you have many windows open, this results in very small windows. Window/Cascade Make a window cascade (try that with 9 windows open :-). Window/Close all Close all open windows. If a window has changes and you are using shadow files, you are asked, if you want to save or discard your changes. Window/Refresh display Rebuilds the desktop. This is nice if your screen becomes garbled. Window/Zoom Switches the size of the topmost window between full size and the last used small size. This is equivalent to pressing F5 when editing a file. Window/Resize Allows resizing the topmost window. Accel key for this function is Ctrl+F5. Window/Close Closes the current edit window. This selection is inactive if you have no edit windows open. If the file is modified, and you are using a shadow file (see "Program options" below), you will be asked to save or discard your changes. Window/Window list List all open windows with title and allow activating one of them. The accel key for this function is Alt+0. Options/Change Change program settings. See "Program options" below. Options/Save Save the program settings. The file selector ----------------- The file selector has some features that are not visible, so they are described here. * To activate one of the entry or list fields in the file selector, enter together with the highlighted character of the field label. * If you are in the file or directory list box, you may position the cursor by typing part of the file name. Assume there are (among others) the names coll.h str.h strbox.h strcoll.h strcvt.h visible in the file box. After typing 's', the highlighted bar will be positioned on the name "str.h". If you type 't', 'r', this will not change (remember: you typed "str" until now). If you add 'c', the bar will move to the name "strcoll.h" and after adding 'v' it will highlight "strcvt.h". This is a very fast way to choose among lots of similar files without having to enter the complete name. * The file selector will detect if you entered a directory name in the name edit field and change the directory if possible. Program options --------------- You can change some of the program settings by choosing "Options/ Change" from the main menu. The following is a brief description of the available settings: Auto save option on exit If you set this to "on", the current settings are automatically saved to the file "hexed.rc" when you leave HexEd. On the next startup, HexEd will read this file and use this settings. Create shadow file This should be set to "on". If HexEd opens a file in something other than read only mode, it will create a copy of the file if this option is set. All changes are done to the copy, not to the original, so you have the option not to save your changes on exit. If HexEd does not create a shadow file, every change is written to the original file. So, not creating a shadow file is faster and uses less hard disk space, but there is no way back when you don't like your changes. Show ASCII >= code 127 (dos/os2) This should be "off" for Linux. If you switch this to "on", characters with values above 126 are displayed as is (instead of using a dot). Search wraps If this switch is set to "on", the search wraps around the end of file, continuing at the beginning until the search string is found or the cursor position is reached again. If the switch is set to "off", the search stops when the search string is found or when end of file is reached. Default mode This is the mode that is assigned to a window if the file is writable (if it is not, the mode is always "Readonly"). This option is overridden by one of the -mx command line switches. Beware: you are not able to switch away from read only mode (this does not make any sense, because changes could not be written to the file anyway). Reload files on startup If this is set to "yes", any open windows and window positions will be remembered if you exit HexEd and will be restored if you start up HexEd again. If set to "no", HexEd will forget about open windows if you leave the program. Changing the active window -------------------------- The currently active window is denoted by a highlighted border. If you have more than one window open or if you activated the menu system and want to go back to editing, you may select your window from the window list (type Alt+0), or alternatively enter the window hotkey, which is Alt+, where is the number of the window as seen in the upper right corner of the window frame. National language support ------------------------- HexEd has built in national language support. Because my capabilities are rather poor, when it comes to languages, the only two languages supported by now are german and english. Under DOS and OS/2, HexEd will choose the language, the operating system supports by default. Under Linux, the default language is english. To change the language, simply define an environment variable named SPUNK_LANGUAGE with the language code. Available language codes are 1 German 2 English 3 French 4 Dutch 5 Spanish 6 Italian So, to set the language to german, enter set SPUNK_LANGUAGE=1 (DOS, OS/2) or export SPUNK_LANGUAGE=1 (Linux, FreeBSD [bash]) If a selected language is not supported, english will be used instead. To select date and number format for your country, define an environment variable named SPUNK_COUNTRY. Available country codes are 001 USA 031 Netherlands 039 Italy 041 Switzerland 044 United Kingdom 049 Germany So, to set the country to germany, enter set SPUNK_COUNTRY=049 (DOS, OS/2) or export SPUNK_COUNTRY=049 (Linux, FreeBSD [bash]) If the selected country is not supported, USA is used instead. Preferably, the environment variables will be set on startup (CONFIG.SYS/AUTOEXEC.BAT/.profile). Linux and FreeBSD users beware: If you select the german language, you have to be on the console or a terminal that supports the ISO-8859-1 character set. Things become unpredictable if this is not the case. Supporting more languages is possible without even changing the executable. All menus, messages and so on are contained in the corresponding resource file hexed.res. If you have the source code, compiling the class library will also create an application named ResEd. This is the resource editor that is used to create/change resource files like hexed.res. Resources --------- As mentioned before, HexEd needs his resource file hexed.res to run. Sometimes HexEd needs a little bit of help, to locate the resource file. If you have both files, the executable and the resource file in a directory that is contained in your PATH= (or DPATH= in OS/2) statement, all is ok. If this is not the case (or if you want to speed up processing), you can tell HexEd, where it will find the resource file. Set the environment variable HEXEDPATH to the full name of the directory that contains the resource file. Linux and FreeBSD specifics --------------------------- There is another section that handles running HexEd under X, this section is about running HexEd on textmode terminals. The class library used to create HexEd is running on IBM compatible systems. The target has been to bring the user friendlyness of DOS programs to every platform that is supported. Unfortunately, this has not been easy on the UNIX like operating systems. HexEd works best on the Linux console and under the X Window system. It automagically detects, if it is running on the console and uses colors and the line drawing characters of the built in ROM charset. But even on the console, some of the keys, that DOS programs use are missing. This are many of the "extended" keys together with the modifier keys Alt/Shift and Ctrl, for example Alt-F1 or Ctrl-Left. On a terminal, the situation is even worse. No color, no linedrawing characters, no function keys ... So the class library develops a replacement strategy: Any of the virtual keys (that are the keys that have a funtion implied, e.g. "page up") are mapped to a real key that is guarantied to exist (but it's not guarantied that anyone will remember that key :-). If the termcap entry says, that more keys are available, those extra keys are also mapped to the virtual keys. If you do not understand that fully, don't bother. It simply means that there are keys that are ugly to remember but are always available, in case your terminal does not support the more "dosish" keys. Here is a list of the key mappings (beware, HexEd does not use all of the following keys): Function Primary Secondary Last resort Esc Esc Esc-Esc Help F1 Esc-Ctrl+H PgDn PgDn Ctrl+C PgUp PgUp Ctrl+R Up Up Ctrl+E Ctrl+Up Ctrl+Up Ctrl+W Down Down Ctrl+Z Ctrl+Down Ctrl+Down Ctrl+Z Left Left Ctrl+S Ctrl+Left Ctrl+Left Ctrl+A Right Right Ctrl+D Ctrl+Right Ctrl+Right Ctrl+F Insert Ins Ctrl+V Delete Del Ctrl+G Home Home Ctrl+Q-S End End Ctrl+Q-D Zoom F5 Esc-Ctrl+Z Close Esc-Ctrl+C Open F3 Esc-Ctrl+O Accept F10 F2 Esc-Ctrl+A Resize Esc-Ctrl+R Quit Esc-X When running on the Linux console, HexEd switches the keyboard to meta-prefix-mode. This results in an escape prefix for every key that is pressed together with the Alt key. So, when running on the console, you can press Alt+X instead of Esc-X. Remembering the keys is usually no problem, because most choices can be selected via the menu, other choices are shown in the status line (which will automatically show the really available keys). Another thing when using terminals is the data transfer rate (baud rate). The window system implements many functions in software and does not use the operating system dependent layer for those functions. One example is scrolling. Scrolling does not occur in the terminal support layer but in the window layer of the software. This has the advantage that the lowest (operating system dependent) layer is small, but the amount of data that is transfered to the screen is larger, because terminal specific functions for scrolling are not used. In consequence, you will not be happy when using HexEd on slow terminals and there is nothing you can do about it. I think it's usable on a 14.4 kbit modem line, but your opinion may be different. One (last) Linux specific point is the character set used. The class library internally uses the IBM codepage 437. The keyboard and screen handlers translate from and to the internally used charset. This means that you cannot enable the "Show ASCII chars with code >= 127" option. The characters shown will not be the characters you expect. Running HexEd under X --------------------- The textmode version of HexEd will run in monochrome mode in a XTerm window. Enabling colors using the SPUNK_COLOR environment variable will not work correctly, because XTerm does not support enough colors. If you want to run HexEd under X, you should preferable use the X version (named xhexed) instead. This version is discussed below. The current X backend for spunk has some limitations: * X resources are not supported. However, the -geometry and -fn command line switches will work. * On a display with more than 4 color planes (> 16 colors), the X backend will emulate a text display with 16 colors. If there are less color planes (but more than one), spunk will emulate a display with three gray shades. If you use a monochrome server, the display is black and white. You may override this by using the SPUNK_COLOR environment variable, but trying to use 16 colors for HexEd on a display that has just 16 colors may not be very comfortable. * Spunk will use a font named "vga" that contains the characters of the IBM codepage 437 (line graphics). This font is usually available on linux systems since it comes with dosemu. If you don't have this font, you must tell spunk, which font to use by setting the SPUNK_XFONT environment variable to correct font name. You may only use fixed size fonts. Use of the vga font is strongly recommended. Try it and judge for yourself. If the name of the font starts with "VGA", it is assumed that the codepage 437 is available. This may be overridden by the SPUNK_CP437 environment variable. If the font name does not start with "VGA" but is an ISO-8859-1 font, remember to set LC_CTYPE or SPUNK_CTYPE correctly. * You may invert the gray and b/w displays by setting the environment variable SPUNK_XINVERTMONO to yes. * Window managers do grab a lot of keys for their own use. This is especially true with fvwm and the the cursor keys together with all(!) modifier keys. If your window manager does this, HexEd will never get the keys. You must use the replacement codes explained above or reconfigure your window manager to be something more modest about the key it grabs. * Even if xhexed is a true X application, it will not recognize any mouse input. Changing the way, HexEd works under Linux and FreeBSD ----------------------------------------------------- The console is the only output device that is treated in a special way by the class library. On any other terminal, HexEd makes some pessimistic assumptions about the capabilities of the terminal. For example, because termcap does not support colors, HexEd assumes a monochrome terminal if it does not detect the console. To change those assumptions, HexEd reads a few environment variables when it starts and changes it's behaviour accordingly. But beware: If you set the wrong options, program output may look very ugly. List of environment variables: SPUNK_LANGUAGE Set the language, see "National language support" above. SPUNK_COUNTRY Set the country (date/time format and monetary symbol), see "National language support" above. SPUNK_COLOR Possible values: "yes", "no", "0", "1". Force HexEd to use ANSI compatible colors strings. This works with many DOS or OS/2 terminal programs that do an ANSI or VT100 emulation. SPUNK_CP437 Possible values: "yes", "no", "0", "1". If this selection is true, HexEd will use characters from the IBM codepage 437 for display, including the line drawing characters. The default for this setting is "yes" at the console (after switching the console character translation to "PC") and "no" anywhere else. Again, many DOS and OS/2 terminal programs will support this. SPUNK_CTYPE The class library evaluates LC_CTYPE to adjust for the character set used. Currently it knows about "ISO-8859-1" and "ISO_8859-1". If you already have set your LC_CTYPE environment variable to something other than this value and don't want to change it, you may use SPUNK_CTYPE (which is evaluated first) to override the setting in LC_CTYPE. If you don't use the codepage 437 on output and you want to use ISO-8859-1 characters in the range 128-255, you have to use a correct LC_CTYPE or SPUNK_CTYPE setting or otherwise spunk will not use those characters. This is especially important if you live in germany (like me :-) and you want to have german umlauts displayed. Bugs & Limitations ------------------ There may be more bugs and limitations but the following are the ones, I have in mind now: * HexEd does not recognize if you open a file twice. * The "reload files on startup" does not work reliably if the files are deleted or renamed while HexEd is not active. Additional notes ---------------- There are some extra doc files describing how to recompile and install HexEd. Copying ------- The spunk library comes with its own copying conditions, the ones below are valid only for the hexed application sources and for the binaries. HexEd copying policy: You are allowed to do anything what you want with the binary and the source code with the following restrictions: * You are not allowed to distribute changed sources for HexEd. However, you _are_ allowed to distribute changed binaries and diffs to the sources. This is because I do not want to have many different versions of the source floating around on the net. * You are not allowed to redistribute this package in an incomplete form. * You are not allowed to take money for distributing this package without my prior, written permission. This includes putting the package on a cd-rom which is sold (even for a nominal fee) or on a bbs or ftp-server where access to this bbs or ftp server is not free for everyone without charge. * I'm not liable for any damages to revenue, loss of sales, damages to property or any other bad thing, as a result of using this package. I'm taking no money for this program and/or the source code, so you use it completely at your own risk! This code is probably full of nasty bugs, that cause head crashes on your hard disk, spill coffee on your keyboard and much, much more! You've been warned!