Edit Anything

Professional text and hex editing
with Binary Templates technology.







010 Editor - Text/Hex Editor Homepage

The following is a list of functions for communicating with the 010 Editor program when writing a Template or Script.


void AddBookmark(
    int64 pos,
    string name,
    string typename,
    int arraySize=-1,
    int forecolor=cNone,
    int backcolor=0xffffc4,
    int moveWithCursor=false )

Creates a bookmark in the file on which the current Script or Template is being executed (not the actual Script or Template). See Using Bookmarks for information on bookmarks and see Running Templates and Scripts for information on controlling on which file a Script or Template is run.

pos indicates the file address where the bookmark will be generated and name gives the name of the bookmark (this name can be empty). typename is a string giving the type of the bookmark to generate and this must be one of the built-in types or a user-defined type. If the type is user-defined and the AddBookmark function is run from a Template, that type must be defined in the current Template. If the type is user-defined and the AddBookmark function is run from a Script, that type must be defined in a Template that has already been run on the file (not in the current Script). Specify an array of variables using the arraySize argument or set arraySize to -1 to just generate a single variable. The text color of the bookmark can be indicated using the forecolor argument and the background color can be specified with the backcolor argument. If the moveWithCursor argument is true, the bookmark will reposition itself to the cursor as the cursor moves around the file.

For example, after loading a ZIP file in 010 Editor (which will cause the 'ZIPTemplate.bt' Template to be run on the file), create a new Script and run the following command on the file:

    AddBookmark( GetCursorPos(), "endmarker", 
        "ZIPENDLOCATOR", -1, cRed );

Here the type "ZIPENDLOCATOR" type is defined in the 'ZIPTemplate.bt' file, not in the Script. The functions GetNumBookmarks, GetBookmarkPos and GetBookmarkName can be used to query existing bookmarks and the RemoveBookmark function can be used to erase bookmarks.

Requires 010 Editor v3.1 or higher.

void Assert( int value, const char msg[] = "" )
Stops execution of the script or template if the value is equal to zero. If execution is stopped, the text message msg will be displayed in the Output tab of the Output Window (note that this is an optional argument). Because conditional statements evaluate to 1 or 0 in C/C++, comparisons can be used in asserts. For example:

    Assert( numRecords > 10, 
      "numRecords should be more than 10." );
Requires 010 Editor v3.1 or higher.

void ClearClipboard()
Removes any data that is on the currently active clipboard. See the SetClipboardIndex function to control which clipboard is active.

Requires 010 Editor v3.1 or higher.

void CopyBytesToClipboard( uchar buffer[], int size, int charset=CHARSET_ANSI, int bigendian=false )
Copies size bytes from the array buffer and places them on the currently active clipboard. If the data being copied represents a string, use the charset parameter to indicate which character set the string uses (see the ConvertString function for a list of character sets). If copying Unicode data the bigendian parameter indicates if the data is in big or little endian format, otherwise this parameter is ignored. See the SetClipboardIndex function to control which clipboard is currently active.

Requires 010 Editor v5.0 or higher.

void CopyStringToClipboard( const char str[], int charset=CHARSET_ANSI )
Sets the currently active clipboard to contain the string passed in the str argument. The charset parameter tells the clipboard what character encoding is used for the string (e.g. ANSI, UTF-8, etc.) and the list of possible character sets is available in the ConvertString function. If copying hex bytes to the clipboard see the CopyBytesToClipboard function and the active clipboard can be set using the SetClipboardIndex function.

Requires 010 Editor v3.1 or higher.

void CopyToClipboard()
Copies the currently selected bytes to the active clipboard. See SetSelection to change the selection or SetClipboardIndex to set the active clipboard.


void CutToClipboard()
Copies the currently selected bytes to the active clipboard and deletes them from the file. See SetSelection to change the selection or SetClipboardIndex to set the active clipboard.


int DeleteFile( char filename[] )
Deletes the file given by filename from disk. Note that the file should not be open in the editor or the delete will fail. Returns a value less than zero on failure.


void DisableUndo()
Turns off undo support for a file. This function will speed up a script when writing a large number of changes to a file. Undo is automatically turned on after the script is finished. Note that undo is automatically disabled for files created with FileNew. See EnableUndo below.


void DisplayFormatBinary()
void DisplayFormatDecimal()
void DisplayFormatHex()
void DisplayFormatOctal()
Sets the display format of variables in the Inspector to binary, decimal, hexadecimal, or octal. Any variables declared after this function is called will be displayed in the selected format. Note that the format can also be set for one variable using the syntax <format=hex|decimal|octal|binary> after a declaration or typedef (see Declaring Template Variables for more information).


void EnableUndo()
Turns back on Undo support for a file after calling DisableUndo. Undo is automatically turned on after the script is finished.


int Exec( const char program[], const char arguments[], int wait=false )
int Exec( const char program[], const char arguments[], int wait, int &errorCode )
Executes an external application using the given program and arguments. Returns 0 if successful or a negative number if an error occurred. If the wait argument is true, this function waits for the external application to finish processing before it returns. If wait is true and the errorCode parameter is given, the error code from the executed program will be stored in the errorCode variable. Note that starting in 010 Editor version 3.1, this function can no longer be called in a Template because of security issues.

Requires 010 Editor v3.1 or higher for the wait parameter.
Requires 010 Editor v6.0 or higher for the errorCode parameter.

void Exit( int errorcode )
Ends execution of the current script or template and displays the errorcode in the Output tab of the Output panel. Note that usually the keyword return can be used to accomplish the same task unless execution is inside of a custom function.

This function is special in that it can be used to return an ERRORLEVEL code to a batch file (see Command Line Parameters for more information). The last errorcode that was passed to an Exit function, either from a script or a template, will be returned as the global ERRORLEVEL when 010 Editor exits.


void ExpandAll()
Recursively opens all tree nodes in the Template Results panel. Variables that have the attribute '<open=suppress>' set will not be opened. See Template Results for more information.

Requires 010 Editor v3.2 or higher.

void ExportCSV( const char filename[] )
Writes the contents of the Template Results panel to a file in a comma-delimited format which can be opened in other programs such as Excel. The file is saved to the given filename and the ExpandAll function can be called first to ensure all variables are included in the export. Alternately, the FPrintf function can be used to output individual variables.

Requires 010 Editor v3.2 or higher.

void ExportXML( const char filename[] )
Similar to ExportCSV except the contents of the Template Results panel are written to a file in XML format. The file to write is given by the filename paramater. Call the ExpandAll function first to ensure all variables are included in the XML file.

Requires 010 Editor v6.0 or higher.

void FileClose()
Closes the current file. No file will be active after this function is called and use the FileSelect function to activate another file. This function can also be used to close an open process or drive. Note that the user will not be asked to save changes if the file is modified.


int FileCount()
Returns the number of existing file handles. See FileSelect to set the current file.


int FileExists( const char filename[] )
Returns true if the given file name exists on disk, or false if it does not.


int FileNew( char interface[]="", int makeActive=true )
Creates a new file in the editor and returns the index of the created file (see GetFileNum). If the interface parameter is not empty, the created file will be assigned that File Interface the same as using the SetFileInterface function (for example, "Hex", "Text", or "Unicode"). If no interface is given, the default File Interface is used from the Editor Options dialog.

If this function is run from a script and the makeActive parameter is true, the created file becomes the current file. If this function is run from a template or the makeActive parameter is false, the current file does not change (use the FPrintf function to write data to the returned file handle). Note that when new files are created, the undo buffer is turned off by default, but will be turned on as soon as the script finishes.

Requires 010 Editor v4.0 or higher for the interface parameter.
Requires 010 Editor v5.0 or higher for the makeActive parameter.

int FileOpen( const char filename[], int runTemplate=false, char interface[]="", int openDuplicate=false )
Opens the file specified by the UTF-8 encoded string filename into the editor. If runTemplate is true and a Template is associated with that file (see Template Options), the Template will be run on the file. The opened file will be assigned the File Interface interface (for example, "Hex", "Text", or "Unicode") and if interface is an empty string, FileOpen will automatically choose an interface. If openDuplicate is true and the file to be opened is already open in the editor, a duplicate copy of the file will be created but if openDuplicate is false, no action will be taken. This function returns the file index of the opened file if the file could be loaded (see GetFileNum), the file index of the already opened file if openDuplicate is false and the file is already open, or a negative number if the file could not be opened (no error message is displayed if the file could not be found). FileOpen is usually called in a Script but can be called in a Template if that Template is given special permission to read other files (see Permissions).

Requires 010 Editor v3.1 or higher for the runTemplate parameter.
Requires 010 Editor v4.0 or higher for the interface or openDuplicate parameters.

int FileSave()
int FileSave( const char filename[] )
int FileSave( const wchar_t filename[] )
Saves the current file to the given file name. The file name can be either a UTF-8 string or a wide string. If FileSave is called with no parameters, the file is saved to the current file name. See GetFileName or GetFileNameW to retrieve the name of the current file. Returns a value less than zero on error. Note that when using backslashes in Windows path names, two backslashes must be used in string constants. For example:

     FileSave( "C:\\temp\\data.log" );

int FileSaveRange( const char filename[], int64 start, int64 size )
int FileSaveRange( const wchar_t filename[], int64 start, int64 size )
Similar to the FileSave function except that only part of the file is written to disk. size bytes starting from the address start are written to the given filename and filename can be given in UTF-8 or Unicode format. Note that filename must specify a different file than the current file name. Returns a negative value on error.

Requires 010 Editor v5.0 or higher.

void FileSelect( int index )
Only one file can be active at a time and all of the Read/Write operations occur on that file. Use FileSelect to select a different file to be the current file. The files are numbered from 0 up to FileCount()-1. See GetFileNum to get the index of the current file.


int FindOpenFile( const char path[] )
int FindOpenFileW( const wchar_t path[] )
Searches through the list of all open files to see if the file indicated by path is currently open. If the file is open, the index of the file is returned which can be used with the FileSelect function. If the file cannot be found, -1 is returned. The FindOpenFileW operates similarly to the FindOpenFile function but takes as input a Unicode file name.

Requires 010 Editor v4.0 or higher.

char[] GetArg( int index )
wchar_t[] GetArgW( int index )
Returns an argument passed to a script or a template from the command line. The GetArg function returns an ASCII string and the GetArgW function returns a wide string. The index parameter must be a number between 0 and GetNumArgs()-1. If index is an invalid number an empty string is returned. See the GetNumArgs function or the -script or -template parameter for more information on passing command line arguments.

Requires 010 Editor v3.2 or higher.

int GetBackColor()
Returns the currently active background color for template variables. See SetBackColor for more information.

Requires 010 Editor v6.0 or higher.

int GetBookmarkArraySize( int index )
If the bookmark specified by index is an array this function returns the number of elements in the array, otherwise this function returns -1. index should be greater or equal to zero and less than the value returned by GetNumBookmarks. See AddBookmark for more information.

Requires 010 Editor v5.0 or higher.

int GetBookmarkBackColor( int index )
This function returns an integer representing the background color of the bookmark specified by index. index should be zero or greater and less than the number of bookmarks (see GetNumBookmarks). More information about creating bookmarks can be found in the AddBookmark help topic.

Requires 010 Editor v5.0 or higher.

int GetBookmarkForeColor( int index )
Returns an integer representing the foreground (text) color of the bookmark indicated by the index parameter. A return value of cNone means that the foreground color is not changed. index should be greater or equal to zero and less that the total number of bookmarks. See GetNumBookmarks to retrieve the number of bookmarks and AddBookmark for more information on adding bookmarks.

Requires 010 Editor v5.0 or higher.

int GetBookmarkMoveWithCursor( int index )
This function returns true if the bookmark specified by index is set to move around the file as the cursor moves (a floating bookmark). False is returned if this is not a floating bookmark. Bookmarks can be created to move with the cursor using the AddBookmark function. Note that index should be greater or equal to zero and less that the value returned by GetNumBookmarks.

Requires 010 Editor v5.0 or higher.

string GetBookmarkName( int index )
Returns a string which contains the name of a bookmark. index controls which bookmark name is returned and the value of index should be greater or equal to zero, and less than the number of bookmarks (see GetNumBookmarks). See AddBookmark for information on creating bookmarks.

Requires 010 Editor v3.1 or higher.

int64 GetBookmarkPos( int index )
Returns the starting address of a bookmark and the bookmark returned is specified using the index argument. index should be greater or equal to zero, and less than the number of bookmarks (see GetNumBookmarks). See AddBookmark for information on creating bookmarks.

Requires 010 Editor v3.1 or higher.

string GetBookmarkType( int index )
This function returns a string representing the type of data stored by the given bookmark (for example, "char" or "int"). The index parameter must be greater or equal to zero and less than the value returned by GetNumBookmarks. See the AddBookmark function for information about creating bookmarks.

Requires 010 Editor v5.0 or higher.

int GetBytesPerLine()
Returns the number of bytes displayed per line in the current Hex Editor Window. This value is by default 16, but may change depending upon the current settings in the View Menu.


int GetClipboardBytes( uchar buffer[], int maxBytes )
Reads data from the currently active clipboard into the given buffer. At most maxBytes bytes will be read from the clipboard and the buffer array must be large enough to hold maxBytes bytes. The return value is the number of bytes written into the buffer, or 0 if no bytes could be read. Also see the GetClipboardString for reading strings from the clipboard and the active clipboard can be set using the SetClipboardIndex function.

Requires 010 Editor v5.0 or higher.

int GetClipboardIndex()
Returns the index of the currently active clipboard. A return value of 0 means the standard system clipboard is chosen and a value of 1 to 9 inclusive means a custom clipboard is chosen. All clipboard operations including CopyToClipboard, CutToClipboard, PasteFromClipboard, CopyBytesToClipboard, CopyStringToClipboard, GetClipboardBytes, GetClipboardString, and ClearClipboard operate on the currently selected clipboard. Use the SetClipboardIndex function to select a different clipboard and see Using the Clipboard for more information on using multiple clipboards. The currently active clipboard is indicated in the Status Bar.

Requires 010 Editor v5.0 or higher.

string GetClipboardString()
If the active clipboard currently contains a string, this string will be returned by the GetClipboardString function. If the data on the clipboard cannot be converted to a string, an empty string will be returned. If the clipboard contains hex data that may include null characters, use the GetClipboardBytes function instead. The active clipboard can be set using the SetClipboardIndex function.

Requires 010 Editor v3.1 or higher.

string GetCurrentTime( char format[] = "hh:mm:ss" )
Returns a string representing the current time in the format "hh:mm:ss" by default (note this is using the 24-hour clock). For information on different formats that can be used see the GetCurrentDateTime function and to use the current application time format see the GetDefaultTimeFormat function.

Requires 010 Editor v3.1 or higher.
Requires 010 Editor v4.0 or higher for the format parameter.

string GetCurrentDate( char format[] = "MM/dd/yyyy" )
Returns a string representing the current date in the format "MM/dd/yyyy" by default. For information on different formats that can be used see the GetCurrentDateTime function and to use the current application date format see GetDefaultDateFormat.

Requires 010 Editor v3.1 or higher.
Requires 010 Editor v4.0 or higher for the format parameter.

string GetCurrentDateTime( char format[] = "MM/dd/yyyy hh:mm:ss" )
Returns a string representing the current date and time in the format "MM/dd/yyyy hh:mm:ss" by default (note this is using the 24-hour clock). When specifying a custom format, the following characters can be used:

  • h - hour without leading zero
  • hh - hour with leading zero
  • m - minute without leading zero
  • mm - minute with leading zero
  • s - second without leading zero
  • ss - second with leading zero
  • z - millisecond without leading zero
  • zzz - millisecond with leading zero
  • AP - either AM or PM
  • ap - either am or pm
  • d - day without leading zero
  • dd - day with leading zero
  • ddd - short day (e.g. 'Mon')
  • dddd - long day (e.g. 'Monday')
  • M - month without leading zero
  • MM - month with leading zero
  • MMM - short month (e.g. 'Jan')
  • MMMM - long month (e.g. 'January')
  • yy - 2-digit year
  • yyyy - 4-digit year

The function GetDefaultDateTimeFormat can also be used to get the current application date/time format. Functions such as StringToTimeT or StringToOleTime can be used to convert the resulting string to a date format.

Requires 010 Editor v3.1 or higher.
Requires 010 Editor v4.0 or higher for the format parameter.

int64 GetCursorPos()
Returns the address of the cursor in the file.


string GetDefaultDateFormat()
Returns the default date format for the application as set in the Inspector Options dialog. This date format is used in the Inspector and the Template Results.

Requires 010 Editor v8.0 or higher.

string GetDefaultDateTimeFormat()
Returns a string containing the default date format followed a single space followed by the default time format. Both date and time formats can be set using the Inspector Options dialog.

Requires 010 Editor v8.0 or higher.

string GetDefaultTimeFormat()
Returns the default time format set in the Inspector Options dialog. This time format is used in the Inspector and the Template Results.

Requires 010 Editor v8.0 or higher.

char[] GetEnv( const char str[] )
Attempts to locate the system environment variable indicated by str. If the environment variable is found, the value of the environment variable is returned as a UTF-8 string and if it could not be found an empty string is returned.

Requires 010 Editor v4.0 or higher.

int GetFileAttributesUnix()
Returns the file attributes of a file on a Unix or Macintosh operating system as a bit flag. The resulting value has nine different flags: read, write and execute for each of the areas user, group, and other. The following constants can be used for testing the bits:

  • FILEATTR_READ_USER
  • FILEATTR_WRITE_USER
  • FILEATTR_EXE_USER
  • FILEATTR_READ_GROUP
  • FILEATTR_WRITE_GROUP
  • FILEATTR_EXE_GROUP
  • FILEATTR_READ_OTHER
  • FILEATTR_WRITE_OTHER
  • FILEATTR_EXE_OTHER

If the file is not a valid file or the file is not in a Unix or Macintosh operating system, the constant FILEATTR_INVALID is returned. For example:

     int flags = GetFileAttributesUnix();
     if( (flags != FILEATTR_INVALID) && !(flags & FILEATTR_READ_USER) )
         Printf( "File is read only.\n" );

See the SetFileAttributesUnix function to modify the attributes.

Requires 010 Editor v4.0 or higher.

int GetFileAttributesWin()
Returns the file attributes of a file on a Windows operating system as a bit flag. The resulting constants can be used for testing the bits:

  • FILEATTR_ARCHIVE
  • FILEATTR_HIDDEN
  • FILEATTR_READONLY
  • FILEATTR_SYSTEM

If the file is not a valid file or the file is not in a Windows operating system, the constant FILEATTR_INVALID is returned. For example:

     int flags = GetFileAttributesWin();
     if( (flags != FILEATTR_INVALID) && (flags & FILEATTR_READONLY) )
         Printf( "File is read only.\n" );

See the SetFileAttributesWin function to modify the attributes.

Requires 010 Editor v4.0 or higher.

int GetFileCharSet()
Returns an integer representing the character set of the current file. The list of possible character sets is available in the ConvertString function.

Requires 010 Editor v4.0 or higher.

char[] GetFileInterface()
Returns a string representing the File Interface of the current file. The File Interface name is listed in the Edit As section above each editor (for example: "Hex", "Text", or "Unicode"). See the SetFileInterface function to change the interface of the current file.

Requires 010 Editor v4.0 or higher.

char[] GetFileName()
Returns a string representing the file name of the current file including the path. The string is returned in UTF-8 format.


wchar_t[] GetFileNameW()
Returns a wide string which contains the file name of the current file including the path.

Requires 010 Editor v3.2 or higher.

int GetFileNum()
Each open file is assigned a index from 0 up to FileCount()-1. This function returns the index of the current file. Use the FileSelect function to make another file the active file.


int GetForeColor()
Returns the currently active foreground (text) color for template variables. See SetForeColor for more information.

Requires 010 Editor v6.0 or higher.

int GetMouseWheelScrollSpeed()
Returns the number of lines that are scrolled every time a mouse scroll wheel is clicked ahead or back. The scroll speed can be controlled with the Editor Options dialog or with the SetMouseWheelScrollSpeed function.

Requires 010 Editor v6.0 or higher.

int GetNumArgs()
Returns the number of arguments that were passed to this script or template from the command line. The individual arguments can be accessed using the GetArg and GetArgW functions. For more information on how to pass arguments see the -script and -template command line parameters.

Requires 010 Editor v3.2 or higher.

int GetNumBookmarks()
Returns the number of bookmarks set for the file that the current Script or Template is being run on (see Running Templates and Scripts for more information on choosing which file to run a Template or Script on). See the AddBookmark function for information on creating bookmarks.

Requires 010 Editor v3.1 or higher.

int GetReadOnly()
Returns true if the file is marked as read-only, or false if the file can be modified.


char[] GetScriptName()
wchar_t[] GetScriptNameW()
These functions return the name of the script that is currently being executed. This name is calculated by taking the full file name of the script and removing the path information. For example, if the script being run was 'H:\Scripts\Test.1sc', these functions would return 'Test.1sc'. GetScriptName returns a UTF-8 string and GetScriptNameW returns a Unicode string.

Requires 010 Editor v4.0 or higher.

char[] GetScriptFileName()
wchar_t[] GetScriptFileNameW()
When a script is being executed, these functions return the full file name of the script being run. GetScriptFileName returns a UTF-8 string and GetScriptFileNameW returns a Unicode string.

Requires 010 Editor v4.0 or higher.

int64 GetSelSize()
Returns the number of bytes that have been selected. Returns 0 if no selection is made.


int64 GetSelStart()
Returns the start address of the selection. Use GetSelSize to determine if a selection has been made.


string GetTempDirectory()
Returns a string representing the current temporary directory set using the Directory Options dialog. The temp directory will contain a slash as the last character (e.g. "C:\temp\").

Requires 010 Editor v3.1 or higher.

char[] GetTempFileName()
Returns the full path of a file that can be used as a temporary file. The file will be in the current temporary directory and will be guaranteed not to exist. The returned file name is in UTF-8 format.

Requires 010 Editor v4.0 or higher.

char[] GetTemplateName()
wchar_t[] GetTemplateNameW()
These functions operate by taking the full template file name as returned from the functions GetTemplateFileName or GetTemplateFileNameW, removing the path information and returning the result. For example, if the current Template being run was 'H:\Templates\Test.bt', these functions would return 'Test.bt'. GetTemplateName returns a UTF-8 string and GetTemplateNameW returns a Unicode string.

Requires 010 Editor v4.0 or higher.

char[] GetTemplateFileName()
wchar_t[] GetTemplateFileNameW()
When run in a Template, these functions return the full file name of the Template that is being run. When run in a Script, these functions return the full file name of the Template that has been associated with the target file, or an empty string if there is no associated Template. GetTemplateFileName returns a UTF-8 string and GetTemplateFileNameW returns a Unicode string.

Requires 010 Editor v4.0 or higher.

char[] GetWorkingDirectory()
wchar_t[] GetWorkingDirectoryW()
Returns the full path of the current working directory for the application. The last character of the directory will be a slash and the current working directory can be set using the SetWorkingDirectory and SetWorkingDirectoryW functions. GetWorkingDirectory returns UTF-8 string and GetWorkingDirectoryW returns a Unicode string.

Requires 010 Editor v4.0 or higher.

char[] InputDirectory( const char title[], const char defaultDir[]="" )
Allows the user to choose a directory using the standard system directory select dialog. The title string is displayed in the title bar of the dialog. The defaultDir paramater allows setting the initial directory when the dialog is first displayed and if this parameter is null, the last chosen directory will be used. The return value is the directory name in UTF-8 format including a trailing slash, or an empty string if the dialog was cancelled.

Requires 010 Editor v5.0 or higher.

double InputFloat(
    const char title[],
    const char caption[],
    const char defaultValue[] )

Opens up a dialog with a single edit box. The title displays in the title bar of the dialog and the caption displays above the edit box. The defaultValue specifies the starting value in the edit box. This function returns the floating-point value of the number entered in the edit box. If an invalid number is entered or Cancel is pressed, the constant BAD_VALUE is returned.


int InputNumber(
    const char title[],
    const char caption[],
    const char defaultValue[] )

Similar to InputFloat except an integer is returned instead of a float value. If an invalid number is entered or Cancel is pressed, the constant BAD_VALUE is returned.


char[] InputOpenFileName(
    char title[],
    char filter[]="All files (*)",
    char filename[]="" )

Shows a standard file open dialog box with the caption title. The filter controls which file masks are available in the File Type drop-down list. Specify filters as an array of strings separated by the '|' character (the file masks should be inside brackets). The filename gives the default file name of the file to open and may just contain a directory to start the dialog in that directory. Only a single file may be selected with the file dialog box. The returned value is the full chosen file name in UTF-8 format, or an empty string if cancel was pressed.


TOpenFileNames InputOpenFileNames(
    char title[],
    char filter[]="All files (*)",
    char filename[]="" )

Similar to InputOpenFileName except that multiple files may be selected. The results are returned in a structure TOpenFileNames that contains a count variable indicating the number of opened files (zero if cancel was pressed), and an array of file variables which each have a UTF-8 filename variable indicating the selected file. For example:

    int i;
    TOpenFileNames f = InputOpenFileNames( 
        "Open File Test", 
        "C Files (*.c *.cpp)|All Files (*)" );
    for( i = 0; i < f.count; i++ )
        Printf( "%s\n", f.file[i].filename );

will print out all file names selected.


int InputRadioButtonBox(
    const char title[],
    const char caption[],
    int defaultIndex,
    const char str1[], const char str2[], const char str3[]="",
    const char str4[]="", const char str5[]="", const char str6[]="",
    const char str7[]="", const char str8[]="", const char str9[]="",
    const char str10[]="", const char str11[]="", const char str12[]="",
    const char str13[]="", const char str14[]="", const char str15[]="" )

Displays a dialog box containing a number of radio buttons which allows a user to pick one choice from a list of options. The title string is displayed in the title bar and the caption string is displayed above the first radio button. The list of options to be displayed is controlled using the str1 .. str15 parameters. Which radio button is chosen by default is controlled with the defaultIndex parameter (use a value of -1 to not use a default and note that 0 represents the first item). The return value of this function is the index of the chosen radio button (0 is the first item, 1 the next, etc), or -1 is returned if the dialog was cancelled.

Requires 010 Editor v5.0 or higher.

char[] InputSaveFileName(
    char title[],
    char filter[]="All files (*)",
    char filename[]="",
    char extension[]="" )

Uses a standard file save dialog box to select a file name suitable to use when saving a file. The user will be asked to overwrite a file if it already exists on disk. The title, filter and filename arguments are similar to the InputOpenFileName function. If no extension is given for the file name, a period and the extension argument will automatically be appended to the file name. The return value is the full chosen file name in UTF-8 format, or an empty string if cancel was pressed.


char[] InputString(
    const char title[],
    const char caption[],
    const char defaultValue[] )

Similar to InputFloat except that the string value of the edit box is returned instead of a float value. If Cancel is pressed, an empty string is returned.


wstring InputWString(
    const char title[],
    const char caption[],
    const wstring defaultValue )

Displays a dialog for the user to enter a wide string (unicode string). See the InputFloat function for an explanation of the different arguments. If Cancel is pressed, an empty string is returned.

Requires 010 Editor v3.1 or higher.

int InsertFile( const char filename[], int64 position )
Inserts all of the bytes in the file given by filename into the current file starting at position. A negative number is returned if the file cannot be inserted.


int IsEditorFocused()
Returns true if a Editor Window is currently focused. This function is useful if you want to build a script that controls the cursor of the Editor Window and only want the cursor to move when the window is focused.


int IsModified()
Returns true if any changes have been made to the file, or false otherwise.


int IsNoUIMode()
Returns true if 010 Editor is currently in -noui mode, or false otherwise. See Command Line Parameters for more information on -noui mode.

Requires 010 Editor v3.2 or higher.

int MessageBox( int mask, const char title[], const char format[] [, argument, ... ] )
Displays a message box to the user with a number of buttons to press. The buttons displayed depend upon an OR mask of four values. The Ok, Cancel, Yes, or No buttons can be displayed by using the constants idOk, idCancel, idYes, or idNo respectively (note that not all possible combinations are supported). The title is display in the title bar of the message box. The message to display is obtained using a syntax similar to printf (see Printf below). The return value is one of the constants idOk, idCancel, idYes, or idNo depending upon which button was pressed. For example, to display a message box with Yes and No buttons use:

 if( MessageBox( idYes | idNo, 
    "Script", 
    "Save changes to '%s'?", 
    GetFileName() ) 
      == idYes )
  . . .

Note that extended characters can be displayed in the message box by passing strings in UTF-8 format.


void OutputPaneClear()
The Output Pane refers to the area where text from the Printf function is displayed (located in the Output tab of the Output Window). When this function is called, all previous output in the Output Pane is cleared.

Requires 010 Editor v3.1 or higher.

int OutputPaneSave( const char filename[] )
Saves all text in the Output tab of the Output Window to a file on disk. The filename argument gives the name of the target output file. This function returns 0 if the file was successfully written or a negative number if the file could not be written.

Requires 010 Editor v3.1 or higher.

void OutputPaneCopy()
Copies the text in the Output tab of the Output Window to the operating system clipboard.

Requires 010 Editor v3.1 or higher.

void PasteFromClipboard()
Inserts any bytes in the currently active clipboard into the file starting at the current cursor position. If a selection has been made, the selected bytes will be deleted before the bytes are inserted. See the SetClipboardIndex function to control which clipboard is active.


int Printf( const char format[] [, argument, ... ] )
Similar to the standard C printf function. Accepts a format specifier and a series of arguments. The results of the Printf are displayed in the Output tab of the Output Window and the following codes can be used to specify different data types:

  • %d, %i - signed integer
  • %u - unsigned integer
  • %x, %X - hex integer
  • %o - octal integer
  • %c - character
  • %s - string
  • %f, %e, %g - float
  • %lf - double
  • %Ld - signed int64
  • %Lu - unsigned int64
  • %Lx, %LX - hex int64

Width, precision, and justification characters are also supported (e.g. "%5.2lf", or "%-15s") and the newline character can be specified with '\n'. This function is different than the standard C printf function because type checking and casting are done on each of the arguments of the function. For example, in this function call the number '5' is automatically cast to a double:

     Printf( "Num = %d, Float = %lf, Str = '%s'\n", 15, 5, "Test" );

The above statement would display "Num = 15, Float = 5.000000, Str = 'Test'". Extended characters can be printed in the Output Window by passing a string in UTF-8 format. Wide strings can be printed with Printf using the regular '%s' specifier because they will automatically be cast to a UTF-8 string. Previous to version 4.0 of 010 Editor, the Printf function did some interpretation of basic HTML tags but this has been removed in version 4.0. Consult documentation on the standard C printf function for more information on different specifiers that can be used.

The Output Window is automatically shown when Printf is called in a Script but is not automatically shown when Printf is called in a Template. This functionality can be controlled via the Compiling Options dialog.


int64 ProcessGetHeapLocalAddress( int index )
Each memory heap in a process is assigned a position in the current file. This function returns the starting local file address for the heap given by index. index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap, -1 is returned. See Editing Processes for more information on processes and heaps.

Requires 010 Editor v3.2 or higher.

wchar_t[] ProcessGetHeapModule( int index )
Returns the name of the module to which the given memory heap belongs. The module name is returned as a wide string and index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap or if the given heap is not associated with a module, an empty string is returned. For more information on heaps and modules see Editing Processes.

Requires 010 Editor v3.2 or higher.

int ProcessGetHeapSize( int index )
Returns the size in number of bytes for the heap given by index. index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap, -1 is returned.

Requires 010 Editor v3.2 or higher.

int64 ProcessGetHeapStartAddress( int index )
Returns the starting address in memory for the heap given by index. index must be between 0 and ProcessGetNumHeaps()-1. If the current file is not a process or if index does not refer to a valid heap, -1 is returned.

Requires 010 Editor v3.2 or higher.

int ProcessGetNumHeaps()
Returns the number of memory heaps for the current process. If the current file is not a process, 0 is returned. See Editing Processes for more information on processes and heaps.

Requires 010 Editor v3.2 or higher.

int64 ProcessHeapToLocalAddress( int64 memoryAddress )
Each heap in a process has two addresses: a memory address where the data actually exists in computer memory and a local file address where the data is located for editing in 010 Editor. Given an address memoryAddress in system memory, this function returns the equivalent address in the local file. See Editing Processes for more information on processes and heaps.

Requires 010 Editor v3.2 or higher.

int64 ProcessLocalToHeapAddress( int64 localAddress )
Each heap in a process has two addresses: a memory address where the data actually exists in computer memory and a local file address where the data is located for editing in 010 Editor. Given an address localAddress in the local file, this function returns the equivalent address in system memory. See Editing Processes for more information on processes and heaps.

Requires 010 Editor v3.2 or higher.

void RemoveBookmark( int index )
Removes a bookmark from the current file. The index argument specifies which bookmark to remove and its value should be greater or equal to zero, and less than the number of bookmarks (see GetNumBookmarks). For information on creating bookmarks see AddBookmark.

Requires 010 Editor v3.1 or higher.

int RenameFile( const char originalname[], const char newname[] )
Renames a file on disk from originalname to newname. Note that the file should not be open in the editor when it is renamed. A negative number if returned if the rename fails.


void RequiresFile()
Scripts can either be run with a target file or without a target file (select "(none)" in the Run on File section when editing a Script to run it without a target file). If this function is called and the current script is being run without a target file, a runtime error will be displayed and the script will be stopped. This function should not be called in a Template because Templates must always have a target file.

Requires 010 Editor v4.0 or higher.

void RequiresVersion( int majorVer, int minorVer=0, int revision=0 )
Indicates what version of 010 Editor is required to execute the current script or template. The execution of the script or template will stop if the current version of 010 Editor is less than the version number given by the majorVer, minorVer, and reversion parameters. For example, with 010 Editor version '3.0.2', the '3' is the major version, '0' is the minor version, and '2' is the revision number. Use this function to ensure that other people that are running your scripts or templates are using the proper version of 010 Editor.


void RunTemplate( const char filename[]="", int clearOutput=false )
This function can be called in a Script to execute a Template on the current file. The filename argument indicates which Template file to run and the filename can either be a full file path, or can be just the name of the file and 010 Editor will attempt to locate the Template using the same rules as locating Include files. For example, 'RunTemplate( "ZIPTemplate.bt" );' will attempt to locate the "ZIPTemplate.bt" file and execute it on the current file. filename can also be an empty string in which case the Template which is associated with the current file will be run (usually this is the last Template that was run on the file). If the Template cannot be located or if there is an error executing the Template, program execution will be stopped. If clearOutput is true, the Output tab of the Output Window will be cleared before the Template is started.

Requires 010 Editor v3.1 or higher.
Requires 010 Editor v4.0 or higher for the clearOutput parameter
or passing an empty filename.

void SetBackColor( int color )
void SetColor( int forecolor, int backcolor )
void SetForeColor( int color )
These functions are used when writing a Template to apply color to different variables. All variables defined after calling one of these functions will be displayed in the given color. SetForeColor sets the foreground (text) color, and SetBackColor sets the background color. Use SetColor to set both the foreground and background color at the same time. A color is an integer made up of 3 hex bytes specifying the blue, green, and red components of the color. The following constants are defined and may be used when setting colors:

  • cBlack - 0x000000
  • cRed - 0x0000ff
  • cDkRed - 0x000080
  • cLtRed - 0x8080ff
  • cGreen - 0x00ff00
  • cDkGreen - 0x008000
  • cLtGreen - 0x80ff80
  • cBlue - 0xff0000
  • cDkBlue - 0x800000
  • cLtBlue - 0xff8080
  • cPurple - 0xff00ff
  • cDkPurple - 0x800080
  • cLtPurple - 0xffe0ff
  • cAqua - 0xffff00
  • cDkAqua - 0x808000
  • cLtAqua - 0xffffe0
  • cYellow - 0x00ffff
  • cDkYellow - 0x008080
  • cLtYellow - 0x80ffff
  • cDkGray - 0x404040
  • cGray - 0x808080,
  • cSilver - 0xc0c0c0,
  • cLtGray - 0xe0e0e0
  • cWhite - 0xffffff
  • cNone - 0xffffffff

The cNone constant indicates that no color should be applied. When a dark Theme is used for the editor, any background colors are automatically darkened and see the ThemeAutoScaleColors function for more information. See GetBackColor and GetForeColor to get the value of the currently active color.


void SetBytesPerLine( int bytesPerLine )
When displaying a file in the Hex Editor, calling this function allows overriding the number of bytes per line of the editor. Usually the number of bytes per line comes from the current File Interface and is set using the 'View > Line Width' menu. Setting a bytesPerLine value of 0 uses the default value from the File Interface. If a value is set with this function and then a new value is chosen with the 'View > Line Width' menu, the value set with this function will be discarded. Currently the maximum bytes per line accepted is 1024.

Requires 010 Editor v8.0 or higher.

int SetClipboardIndex( int index )
Sets which clipboard is the currently active clipboard. An index value of 0 indicates the normal system clipboard and a value of 1 through 9 indicates one of the custom clipboards. All clipboard functions including CopyToClipboard, PasteFromClipboard, etc. operate on the currently active clipboard. See the GetClipboardIndex function to retrieve which clipboard is active and see Using the Clipboard for more information on using multiple clipboards. Note that setting the clipboard index effects the whole application and the selected clipboard will remain active after the script has finished executing. See the Status Bar for a visual indication of which clipboard is active.

Requires 010 Editor v5.0 or higher.

void SetCursorPos( int64 pos )
Sets the cursor position in the current file to pos. A flashing caret will visually indicate the cursor position in the file.


int SetEnv( const char str[], const char value[] )
Attempts to set the system environment variable indicated by str to the given value (both str and value are UTF-8 strings). Note that the environment variable changes are only local to the 010 Editor process, so when 010 Editor is closed the changes will be lost. Returns 0 on success or a negative number on failure.

Requires 010 Editor v5.0 or higher.

int SetFileAttributesUnix( int attributes )
Sets the file attributes of the current Unix or Macintosh file to attributes. The attributes are a bit flag composed of the constants listed in the GetFileAttributesUnix function. This function returns true if the file is on a Unix or Macintosh operating system and the attributes were set properly, or false otherwise. For example:

     int flags = GetFileAttributesUnix();
     if( flags != FILEATTR_INVALID )
         SetFileAttributesUnix( flags & ~(FILEATTR_READ_USER) );
Requires 010 Editor v4.0 or higher.

int SetFileAttributesWin( int attributes )
Sets the file attributes of the current Windows file to the given attributes. The attributes are a bit flag made up of the constants in the GetFileAttributesWin function. This function returns true if the file is a valid Windows file and the attributes were set properly, or returns false otherwise. For example:

     int flags = GetFileAttributesWin();
     if( flags != FILEATTR_INVALID )
         SetFileAttributesWin( flags | FILEATTR_READONLY );
Requires 010 Editor v4.0 or higher.

int SetFileInterface( const char name[] )
Sets the File Interface of the current file to the interface with the given name. The current interface of the file can be returned using the GetFileInterface function. The list of valid File Interfaces is found in the Edit As section of the File Bar above each editor (for example: "Hex", "Text", or "Unicode"). This functions returns 0 if the change was successful or a negative number if the Interface could not be found.

Requires 010 Editor v4.0 or higher.

void SetMouseWheelScrollSpeed( int speed )
Sets the number of lines that are scrolled each time a scroll wheel on a mouse is clicked forward or backward. The scroll speed is also listed in the Editor Options dialog and the scroll speed can be investigated with the GetMouseWheelScrollSpeed function.

Requires 010 Editor v6.0 or higher.

int SetReadOnly( int readonly )
Sets the read-only status of the current file to true or false. A negative number is returned if the read-only status could not be changed.


void SetSelection( int64 start, int64 size )
Selects size bytes from the file starting at the address start. The selected bytes will appear blue in the main window.


int SetWorkingDirectory( const char dir[] )
int SetWorkingDirectoryW( const wchar_t dir[] )
Sets the current working directory of the application to the directory dir. The current working directory can be retrieved using the GetWorkingDirectory or GetWorkingDirectoryW functions. This functions returns 0 if the directory is valid and could be set, or a negative number if the directory is not valid.

Requires 010 Editor v4.0 or higher.

void Sleep( int milliseconds )
Halts program execution for the given number of milliseconds. For example, 'Sleep(2000);' would cause a pause of two seconds. Note that for sleeps of more than 1000 milliseconds the screen is automatically repainted before the sleep occurs.

Requires 010 Editor v3.1 or higher.

void StatusMessage( const char format[] [, argument, ... ] )
Similar to the Printf function except the resulting string is displayed in the Status Bar of the application as a normal status message. See also the Warning function.

Requires 010 Editor v4.0 or higher.

void ThemeAutoScaleColors( int autoScale, float scaleFactor=0.5f )
Background colors in a Template can be specified with either the bgcolor special attribute or with the SetBackColor function. When the editor is using a dark Theme the background colors are multiplied by a scale factor which effectively darkens the colors to fit in with the dark theme. To turn off this scaling call the ThemeAutoScaleColors function with autoScale set to false. To adjust the scale factor set autoScale to true and set the scale factor using scaleFactor. Scale factors between 0 and 1.0 are accepted and 0.5 is the default. To check if the current theme is dark see the ThemeIsDark function.

Requires 010 Editor v8.0 or higher.

int ThemeIsDark()
Returns true if the current Theme uses a dark color for the Editor background or returns false if the current Theme uses a light color for the Editor background. Note that colors applied using a Template automatically adjust their colors when being used on a dark theme and see the ThemeAutoScaleColors function to control this.

Requires 010 Editor v8.0 or higher.

void Terminate( int force=true )
Exits out of the script and then shuts down 010 Editor. If force is true, all open files will be closed and any unsaved modifications will be lost. If force is false and files are modified, the user will be asked if they want to save the files and optionally given a chance to cancel the shut down procedure.


void Warning( const char format[] [, argument, ... ] )
Similar to the Printf function except the resulting string is displayed in the Status Bar of the application and is highlighted orange. This is useful to display an error that occurs in a Template. See also the StatusMessage function.


















This is the manual for 010 Editor, a professional hex editor and disk editor. Use 010 Editor to edit the individual bytes of any binary file, hard drive, or process on your machine. 010 Editor contains a whole host of powerful analysis and editing tools, plus Binary Templates technology that allows any binary format to be understood.