# The &okteta; Handbook

## Introduction

&okteta; is a simple editor for the raw data of files.

The data is displayed in two variants: as the numeric values of the bytes and as the character assigned to the values. Values and characters can be shown either in two columns (the traditional display in hex editors) or in rows with the value on top of the character. Editing can be done both for the values and for the characters.

Besides the usual editing capabilities &okteta; also brings a small set of tools, like a table listing decodings into common simple data types, a table listing all possible bytes with its' character and value equivalents, an info view with a statistic, a checksum calculator, a filter tool and a string extraction tool.

All modifications to the data loaded can be endlessly undone or redone.

## Basics

### Starting &okteta;

Type ``okteta`` at a command prompt or select Hex Editor from the Applications Utilities group in the application launcher.

The standard &Qt; and &kde; command line options are available, and can be listed by entering ``okteta` `--help``.

Command line options specific to &okteta; are:

``<&URL;(s)>`` - open file(s) from the specified &URL;(s)

### Usage

The main &okteta; window has the following components: a menu bar, a toolbar, a status bar, one or several sidebars with tools, and the main view with the tabbed data views.

When a file is opened or a new byte array is created, the bytes contained are listed consecutively in lines with a given number of bytes per line. They are displayed in two variants: as the numeric values of the bytes and as the characters assigned to the values. Values and characters can be shown either separated in two columns or next to each other with the value on top of the character. On the left side the offsets of the first byte in each line are shown.

The handling is similar to that of most text editors: the data can be edited, cut, copied, pasted, dragged and dropped much as text in these can. A cursor marks the current position. Pressing the Insert key toggles between the overwrite and insert modes. The overwrite mode is stricter than in text editors, as it doesn't allow any operation which changes the size of the byte array.

Other than in text editors the content is displayed in two variants. Only one of these is active with regard to new input. There are two linked cursors shown for the value and the character display, the cursor of the active one is blinking. With the characters active, characters can be entered as known from text editors. With the values active, typing a digit will open a minimal editor to enter the rest of the value.

The search dialog allows the user to search for a specific string of bytes, definable as values (hexadecimal, decimal, octal, binary) or text (current 8-bit encoding or UTF-8).

Multiple byte arrays can be open at the same time, but only one can be active. Use the Windows menu to select which byte array will be active.

## Tools

### Overview

&okteta; brings some tools, some to analyze and manipulate the byte arrays and some with more general purpose. These tools can be activated or deactivated from the Tools entry in the menu bar. Each tool has a small view, which docks either in one of the sidebars or freely floats as a window. You can dock, undock, rearrange and also stack the tool views with the mouse, by pressing the &LMB; on the title bar of a tool view, moving it as you like and releasing the &LMB; to complete the action, otherwise cancel it by pressing the &Esc; key.

#### Analyzers and Manipulators

Byte Table

- The table lists all possible byte values, both as character and numerical value.

  The selected value can be inserted at the cursor position for a defined number of bytes. This can be achieved by using the Insert button or double-clicking the line in the table.

Binary Filter

- The filter performs binary operations on the selected bytes. After choosing the operation (AND, OR, ROTATE..) the parameters, if any, can be set in the box below. The filter is executed on the use of the Filter button.

Strings

- This tool locates the strings in the selected bytes. After choosing the minimum string length, the strings are grepped for on the use of the Extract button. The list of the strings displayed can be narrowed by entering a filter term.

Statistics

- This tool builds a statistic for the selected bytes. The statistic gives the frequency of the occurrence of each byte value in the selection. It can be calculated by using the Build button.

Checksum

- This tool calculates various checksums or hashsums for the selected bytes. After choosing the algorithm and setting the parameter, if any, the sum is computed on the use of the Calculate button.

Decoding Table

- The table displays the values of the byte or the bytes starting at the cursor for some common simple data types like Integer or Float, but also UTF-8. Double-clicking on a line in the table opens an editor, so the value can be edited and changed.

Structures

- This tool enables investigating and editing of byte arrays based on user-creatable structure definitions. Detailed instructions are in an own section.

#### General tools

Filesystem

- This tool offers an embedded file browser which can be used to select files to open.

Documents

- This tool shows all currently created or loaded files. Symbols mark the file with the currently active view and also show which files have unsaved changes or which storage copy has been modified by another program.

Bookmarks

- This tool can be used to manage the bookmarks, alternatively to the Bookmarks menu.

  Bookmarks are currently only transient and not saved if you close a byte array or the whole program.

File Info

- This tool displays some information about the current file, including its type, the location of storage and the size.

### Structures Tool

#### General

The Structures tool enables analysing and editing of byte arrays based on user-creatable structure definitions, which can be built from arrays, unions, primitive types and enum values.

It has an own settings dialog, which can be reached by using the Settings button. There are various options that can be configured, like the style (decimal, hexadecimal or binary) in which the values are displayed. Moreover it is possible to choose which structure definitions get loaded and which structures are shown in the view.

Structures are defined in &okteta; Structure Definition files (based on &XML;, with the file extension `.osd`). Additionally a `.desktop` file contains metadata about that structure description file, such as author, homepage and license.

Currently there is no built-in support for creating, editing or installing structure definitions, so this must be done manually as described in the next sections.

#### Installing structure definitions

The Structures tool looks for structure descriptions in the subdirectory `share/apps/okteta/structures/` of the user's directory for program data (find that by executing ``kde4-config` `--localprefix``). You may need to create this directory if there are not any structure definitions installed yet.

In that subdirectory there is an own subdirectory for each structure definition, which contains both the `.desktop` file and the `.osd` file of that definition.

E.g. with the program data directory `.kde` and a structure definition named ExampleStructure there is the directory `.kde/share/apps/okteta/structures/ExampleStructure`, which contains a file `ExampleStructure.desktop` and a file `ExampleStructure.osd`.

If you have installed a new structure definition by creating such a subdirectory with the two files or edited them, you need to restart &okteta; and open the settings dialog of the Structure tool. There select the Structures Management tab and make sure the relevant structure definition is checked. Then use the button Apply Changes, switch to the Structures tab and make sure the desired element is listed on the right-hand side.

#### Sharing structure definitions

For common structures you may not need to create a definition yourself, but instead can reuse an already existing definition from places like kde-files.org.

You also may want to share a definition yourself. To do so, create a file archive (e.g. a zipped tar archive, `.tgz`) containing just the subdirectory with the `.osd` file and the `.desktop` file. From the example in the last section this would be the subdirectory `ExampleStructure`. If you adhere to this format future versions of the Structure tool will be able to provide automatical download and install of these definitions.

#### Creating your own structure definitions

##### A first structure definition

To start we create a definition for a very simple test structure containing only integral data types (one char and one 32-bit int). They would be expressed in C/C++ as:

              struct simple {
                char aChar;
                int anInt;
              };

The first step is writing the `.osd` file, which we will call `simplestruct.osd`:

              <?xml version="1.0" encoding="UTF-8"?>
              <data>
                <struct name="simple">
                  <primitive name="aChar" type="Char"/>
                  <primitive name="anInt" type="Int32"/>
                </struct>
              </data>

which is fairly similar to the C/C++ definition. The type attribute can be any of the following:

- Char
- Int8
- UInt8
- Int16
- UInt16
- Int32
- UInt32
- Int64
- UInt64
- Float
- Double
- Bool8
- Bool16
- Bool32
- Bool64

The next step is writing the `.desktop` file for the metadata, which is just a set of key-value pairs. It should be named `simplestruct.desktop`. In this example it looks as such:

              [Desktop Entry]
              Encoding=UTF-8
              Icon=arrow-up
              Type=Service
              ServiceTypes=KPluginInfo

              Name=Simple test structure
              Comment=A very simple test structure containing only two items

              X-KDE-PluginInfo-Author=Alex Richardson
              X-KDE-PluginInfo-Email=alex.richardson@gmx.de
              X-KDE-PluginInfo-Name=simplestruct
              X-KDE-PluginInfo-Version=1.0
              X-KDE-PluginInfo-Website=http://www.plugin.org/
              X-KDE-PluginInfo-Category=structure
              X-KDE-PluginInfo-License=LGPL
              X-KDE-PluginInfo-EnabledByDefault=false

These fields should all be pretty much self-explanatory, except for `X-KDE-PluginInfo-Name`. This one must have the name of the `.osd` file as its value (without the `.osd` suffix).

Now create a subdirectory `simplestruct` as described above, copy the two files to this directory, and restart &okteta;.

##### More complex structures

Next we create a definition of a more complex structure which we will call "complex" and save in a file named `complex.osd`. This structure will contain two arrays (one with fixed length and one where the length is determined at runtime) as well as a nested structure and a union.

              <?xml version="1.0" encoding="UTF-8"?>
              <data>
                <struct name="complex">
                  <primitive name="size" type="UInt8" />
                  <union name="aUnion">
                    <array name="fourBytes" length="4">
                      <primitive type="Int8" />
                    </array>
                  </union>
                  <struct name="nested">
                    <array name="string" length="size"> <!-- references the field size above -->
                      <primitive type="Char" />
                    </array>
                  </struct>
                </struct>
              </data>

This would correspond to the following in pseudo C/C++

              struct complex {
                uint8_t size;
                union aUnion {
                  int8_t fourBytes[4];
                };
                struct nested {
                  char string[size] //not valid C++, references value of the uint8 size
                };
              };

You can obviously only have dynamic length arrays reference fields before the array.

Next we create the `complex.desktop` file just as in the example before (make sure you set `X-KDE-PluginInfo-Name` correctly) and also do the same to install both files.

##### Further information

A few example structure definitions can be found here. This include for example the file header for PNG files. An &XML; schema describing the structure of the `.osd` file can be found here. If more information is needed feel free to contact me at &Alex.Richardson.email;

## Menu Entries

Note that most menu commands also have a keyboard shortcut.

### File Menu

&Ctrl;N File New

- Create a new byte array...

  - Empty: ... as Empty one.

  - From Clipboard: ... by the current content of the clipboard.

  - Pattern...: ... with a given pattern.

  - Random Data...: ...with random data.

  - Sequence: ... with all the bytes from 0 to 255.

&Ctrl;O File Open...

- Open an existing file.

File Open Recent

- Choose from a list of the last opened files.

&Ctrl;S File Save

- Save byte array to the assigned file.

File Save As...

- Save byte array to another file with a new name.

File Export

- Export the selected bytes to a file...

  - Values: ... encoded as byte values.

  - Plain Text: ... encoded as characters.

  - Base64: ... encoded in the Base64 format.

  - C array: ... defined as an array in the programming language C.

  - View in Plain Text: ... as in the data view with offset, byte values and characters.

F5 File Reload

- Discards all changes and reloads the byte array from the file.

&Ctrl;P File Print...

- Print the current byte array.

File Permissions

- Set modification privileges:

  Set Read-only

- When set, changes may not be made to the loaded byte array.

&Ctrl;W File Close

- Close the current byte array.

File Close All

- Close all byte arrays.

File Close All Other

- Close all besides the current byte array.

&Ctrl;Q File Quit

- Close the &okteta; window.

### Edit Menu

Currently in &kde; 4.4 simple copy and cut send data to the clipboard with the mimetype "application/octetstream", &klipper; is not able to display this data. And almost all other applications cannot handle this, too, as this is simply raw data. So also see for the Copy as submenu.

&Ctrl;Z Edit Undo

- Undo the last action.

&Ctrl;&Shift;Z Edit Redo

- Redo the last undone action.

&Ctrl;X Edit Cut

- Delete the selected bytes and copy them to the clipboard.

&Ctrl;C Edit Copy

- Copy the selected bytes to the clipboard.

&Ctrl;V Edit Paste

- Insert the cut or copied bytes in the clipboard.

Edit Copy as

- Copy the selected bytes to the clipboard...

  - Values: ... encoded as byte values.

  - Plain Text: ... encoded as characters.

  - Base64: ... encoded in the Base64 format.

  - C array: ... defined as an array in the programming language C.

  - View in Plain Text: ... as in the data view with offset, byte values and characters.

Edit Insert

- Insert Pattern...

- Insert a specified string of bytes at the cursor.

  Options in the dialog box allow you to specify the number of insertion of the pattern and it's format (Hexadecimal, Decimal, Octal, Binary, Character(s) or UTF-8).

&Ctrl;A Edit Select All

- Select the entire byte array.

&Ctrl;&Shift;A Edit Deselect

- Deselect the current selection.

&Ctrl;E Edit Select Range...

- Opens an embedded dialog to enter the range to select.

Ins Edit Overwrite Mode

- Switch between Insert mode and Overwrite mode.

  Overwrite mode is implemented to be very strict, it is not possible to change the size of the data (no appending or removing of bytes).

&Ctrl;F Edit Find...

- Find a specified pattern in the document. Hexadecimal, decimal, octal, binary or text patterns can be searched for.

  Options in the dialog box allow you to specify the starting point, direction and range of the search.

F3 Edit Find Next

- Find the next instance of the Find pattern.

  If there isn't a pattern specified, the dialog box will be shown.

&Shift;F3 Edit Find Previous

- Find the previous instance of the Find pattern.

  If there isn't a pattern specified, the dialog box will be shown.

&Ctrl;R Edit Replace...

- Replace the find pattern with a different pattern.

&Ctrl;G Edit Goto Offset...

- Move the cursor to a specified offset.

### View Menu

&Ctrl;+ View Zoom In

- Increase the size of the font.

&Ctrl;- View Zoom Out

- Decrease the size of the font.

View Show Non-printing Chars

- Toggle display of non-printing chars on and off. If the display is turned off, at the corresponding places in the character column a substitute char is shown instead.

F11 View Show Line Offset

- Toggle display of the line offset on a pane to the left on and off.

View Show Values or Chars

- Select which of the byte interpretations are shown. Possible are:

  - Values

  - Chars

  - Values and Chars

View Value Coding

- Select the coding of the values from:

  - Hexadecimal

  - Decimal

  - Octal

  - Binary

View Char Coding

- Select the coding of the chars from the submenu.

View Dynamic Layout

- Set the rules for the layout of the data display. This defines how many bytes are displayed per line, depending on the width of the view. Possible rules are:

  - Off: The layout is fixed to the current number of bytes per line and not adapted on the change of the view size.

  - Wrap only complete byte groups: Puts as many bytes per line as possible, as long as groups of bytes are complete.

  - On: Same as previous, but allows also uncomplete groups of bytes.

View View Mode

- Select the layout for the view from:

  - Columns: The values and chars interpretations are shown in the classic layout with each listed in a separate column.

  - Rows: The char interpretation of a byte is directly shown under the value interpretation.

&Ctrl;&Shift;T View Split Horizontal

- Split the view area with the currently focussed view into two parts and add a copy of the current view to the new, lower area.

&Ctrl;&Shift;L View Split Vertically

- Split the view area with the currently focussed view into two parts and add a copy of the current view to the new, right area.

&Ctrl;&Shift;L View Close View Area

- Close the view area with the currently focussed view.

&Ctrl;&Shift;F11 View Full Screen Mode

- Toggle full screen mode on and off.

### Windows Menu

Provides a list of the current views. Select the active window.

### Bookmarks Menu

Multiple bookmarks can be set for a single byte array. Each byte array has its own set of bookmarks, and the appropriate set is displayed at the bottom of the Bookmarks menu. Choose a bookmark from the menu to move the cursor and the view to it.

Bookmarks are currently only transient and not saved if you close a byte array or the whole program.

&Ctrl;B Bookmarks Add Bookmark

- Bookmark a location within the byte array.

&Ctrl;&Shift;B Bookmarks Remove Bookmark

- Remove the current bookmark. This command is only available if the cursor is at a bookmarked location.

Bookmarks Remove All Bookmarks

- Clear the bookmark list.

&Alt;Up Bookmarks Goto Previous Bookmark

- Move the cursor to the previous bookmark.

&Alt;Down Bookmarks Go to Next Bookmark

- Move the cursor to the next bookmark.

### Tools Menu

Provides a list of installed tools. Toggle the display of each tools on or off. A detailed description of each tool you find in the Tools section.

### Settings Menu

Settings Show Toolbar

- Toggle display of the toolbar below the menu bar.

Settings Show Statusbar

- Toggle display of the status bar.

Settings Configure Shortcuts...

- Change program action shortcuts.

Settings Configure Toolbars...

- Control the content of the toolbar.

### Help Menu

&help.menu.documentation;

### Toolbar

The toolbar contains icons for the following commands:

(All behave identically to the menu command.)

- New

- Open

- Save

- Revert

- Print

- Undo

- Redo

- Cut

- Copy

- Paste

- Find

- Find Next

## Credits and License

&okteta;

Program Copyright 2006-2010 &Friedrich.Kossebau; &Friedrich.Kossebau.email;

Documentation Copyright 2008,2010 &Friedrich.Kossebau; &Friedrich.Kossebau.email;

&underFDL; &underGPL;

## Installation

### How to obtain &okteta;

&install.intro.documentation;

### Compilation and Installation

&install.compile.documentation;
&documentation.index;