pkg://HexEd-1.10-src.tar.gz:424274/
HexEd-1.10/hexed.doc
downloads
HexEd V1.10
Copyright (C) 1995,96 Ullrich von Bassewitz
<uz@ibb.schwaben.com>
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 <Alt> 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+<windownumber>, where <windownumber> 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 and command line parameters that change the behaviour
under X are not evaluated (this is because my book on X
programming did not explain how to do it). This may change
in the future.
* 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.
* Spunk uses mod4 for left Alt key. If the alt keys do not work,
check this.
* Some Linux systems use mod5 for both, the left and right alt
keys. If this is the case, the german keyboard does not work
correctly (I do not know about other keyboards, any input on
that is appreciated). You must disable this feature to use
spunk programs, for example by doing a
xmodmap -e "remove mod5 = ALT_L"
* 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!
