Top (GNU poke Manual)

1 Introduction
- 1.1 Motivation
  - 1.1.1 Decode-Compute-Encode
  - 1.1.2 Describe-Compute
- 1.2 Nomenclature
- 1.3 Invoking poke
- 1.4 Commanding poke
2 Setting Up
- 2.1 Setting up Hyperlinks
- 2.2 Simple Init File
3 Basic Editing
- 3.1 Binary Files
- 3.2 Files as IO Spaces
- 3.3 Dumping File Contents
- 3.4 Poking Bytes
- 3.5 Values and Variables
- 3.6 From Bytes to Integers
- 3.7 Big and Little Endians
- 3.8 Negative Integers
  - 3.8.1 Negative Encodings
  - 3.8.2 Signed Integers
  - 3.8.3 Mixing Signed and Unsigned Integers
- 3.9 Weird Integers
  - 3.9.1 Incomplete Bytes
  - 3.9.2 Quantum Bytenics
  - 3.9.3 Signed Weird Numbers
- 3.10 Unaligned Integers
- 3.11 Integers of Different Sizes
- 3.12 Offsets and Sizes
- 3.13 Buffers as IO Spaces
- 3.14 Copying Bytes
- 3.15 Saving Buffers in Files
- 3.16 Character Sets
- 3.17 From Bytes to Characters
  - 3.17.1 Character Literals
  - 3.17.2 Classifying Characters
  - 3.17.3 Non-printable Characters
- 3.18 ASCII Strings
  - 3.18.1 String Values
  - 3.18.2 Poking Strings
  - 3.18.3 From Characters to Strings
- 3.19 From Strings to Characters
- 3.20 Strings are not Arrays
4 Structuring Data
- 4.1 The SBM Format
- 4.2 Poking a SBM Image
- 4.3 Modifying SBM Images
- 4.4 Defining Types
  - 4.4.1 Naming your Own Abstractions
  - 4.4.2 Abstracting the Structure of Entities
- 4.5 Pickles
- 4.6 Poking Structs
- 4.7 How Structs are Built
- 4.8 Variables in Structs
- 4.9 Functions in Structs
- 4.10 Struct Methods
- 4.11 Padding and Alignment
- 4.12 Dealing with Alternatives
  - 4.12.1 BSON
  - 4.12.2 Unions are Tagged
- 4.13 Structured Integers
- 4.14 Working with Incorrect Data
5 Maps and Map-files
- 5.1 Editing using Variables
- 5.2 poke Maps
- 5.3 Loading Maps
- 5.4 Multiple Maps
- 5.5 Auto-map
- 5.6 Constructing Maps
- 5.7 Predefined Maps
6 Writing Pickles
- 6.1 Pretty-printers
  - 6.1.1 Convention for pretty-printed Output
  - 6.1.2 Pretty Printing Optional Fields
- 6.2 Setters and Getters
7 Writing Binary Utilities
- 7.1 Poke Scripts
- 7.2 Command-Line Arguments
- 7.3 Exiting from Scripts
- 7.4 Loading pickles as Modules
- 7.5 elfextractor
- 7.6 Filters
8 Configuration
- 8.1 .pokerc
- 8.2 Load Path
- 8.3 Styling
9 IOS
- 9.1 ios_dump_bytes
- 9.2 ios_copy_bytes
- 9.3 ios_save_bytes
10 Time
- 10.1 POSIX Time
11 Colors
- 11.1 The Color Registry
- 11.2 RGB24 Encoding
12 Audio
- 12.1 MP3
  - 12.1.1 ID3V1 Tags
    - 12.1.1.1 Song Genres
    - 12.1.1.2 The ID3V1_Tag Type
13 Object Formats
- 13.1 ELF
- 13.2 Dwarf
14 Programs
- 14.1 argp
15 poked
16 Programming Emacs Modes
- 16.1 poke-mode
- 16.2 poke-map-mode
- 16.3 poke-ras-mode
17 Vim Syntax Highlighting
- 17.1 poke.vim
18 Dot-Commands
- 18.1 .load
- 18.2 .source
- 18.3 .file
- 18.4 .mem
- 18.5 .nbd
- 18.6 .proc
- 18.7 .sub
- 18.8 .ios
- 18.9 .close
- 18.10 .doc
- 18.11 .editor
- 18.12 .info
- 18.13 .set
- 18.14 .vm
- 18.15 .exit
- 18.16 .quit
19 Commands
- 19.1 dump
  - 19.1.1 Information dump shows
  - 19.1.2 Presentation options for dump
- 19.2 copy
- 19.3 save
- 19.4 sdiff
- 19.5 extract
- 19.6 scrabble
20 The Poke Language
- 20.1 Integers
  - 20.1.1 Integer Literals
    - 20.1.1.1 The digits separator _
    - 20.1.1.2 Types of integer literals
  - 20.1.2 Characters
  - 20.1.3 Booleans
  - 20.1.4 Integer Types
  - 20.1.5 Casting Integers
  - 20.1.6 Relational Operators
  - 20.1.7 Arithmetic Operators
  - 20.1.8 Bitwise Operators
  - 20.1.9 Boolean Operators
  - 20.1.10 Integer Attributes
- 20.2 Offsets
  - 20.2.1 Offset Literals
  - 20.2.2 Offset Units
  - 20.2.3 Offset Types
  - 20.2.4 Casting Offsets
  - 20.2.5 Offset Operations
  - 20.2.6 Offset Attributes
- 20.3 Strings
  - 20.3.1 String Literals
  - 20.3.2 String Types
  - 20.3.3 String Indexing
  - 20.3.4 String Concatenation
  - 20.3.5 String Attributes
  - 20.3.6 String Formatting
- 20.4 Arrays
  - 20.4.1 Array Literals
  - 20.4.2 Array Types
    - 20.4.2.1 Writing unbounded array literals
    - 20.4.2.2 Array boundaries and closures
  - 20.4.3 Casting Arrays
  - 20.4.4 Array Constructors
  - 20.4.5 Array Comparison
  - 20.4.6 Array Indexing
    - 20.4.6.1 Indexing an array by number of element
    - 20.4.6.2 Indexing an array by offset of element
  - 20.4.7 Array Trimming
  - 20.4.8 Array Elements
  - 20.4.9 Array Concatenation
  - 20.4.10 Array Attributes
  - 20.4.11 Arrays as Stacks
- 20.5 Structs
  - 20.5.1 Struct Types
  - 20.5.2 Struct Constructors
  - 20.5.3 Struct Comparison
  - 20.5.4 Field Endianness
  - 20.5.5 Accessing Fields
  - 20.5.6 Field Constraints
  - 20.5.7 Field Initializers
  - 20.5.8 Field Labels
  - 20.5.9 Pinned Structs
  - 20.5.10 The OFFSET variable
  - 20.5.11 Integral Structs
  - 20.5.12 Unions
  - 20.5.13 Union Constructors
  - 20.5.14 Integral Unions
  - 20.5.15 Optional Fields
  - 20.5.16 Casting Structs
  - 20.5.17 Declarations in Structs
  - 20.5.18 Methods
  - 20.5.19 Computed Fields
  - 20.5.20 Struct Attributes
- 20.6 Types
  - 20.6.1 type
  - 20.6.2 The any Type
  - 20.6.3 The isa Operator
  - 20.6.4 typeof
- 20.7 Assignments
  - 20.7.1 Simple Assignments
  - 20.7.2 Bit Assignments
- 20.8 Compound Statements
- 20.9 Conditionals
  - 20.9.1 if-else
  - 20.9.2 Conditional Expressions
- 20.10 Loops
  - 20.10.1 while
  - 20.10.2 for
  - 20.10.3 for-in
- 20.11 Expression Statements
- 20.12 Functions
  - 20.12.1 Function Declarations
  - 20.12.2 Optional Arguments
  - 20.12.3 Variadic Functions
  - 20.12.4 Calling Functions
  - 20.12.5 Function Types
  - 20.12.6 Lambdas
  - 20.12.7 Function Comparison
  - 20.12.8 Function Attributes
- 20.13 Assembler
- 20.14 Endianness
  - 20.14.1 .set endian
  - 20.14.2 Endian in Fields
  - 20.14.3 Endian built-ins
- 20.15 Mapping
  - 20.15.1 IO Spaces
  - 20.15.2 The Map Operator
  - 20.15.3 Mapping Simple Types
  - 20.15.4 Mapping Structs
  - 20.15.5 Mapping Arrays
  - 20.15.6 Mapping Functions
  - 20.15.7 Non-strict Mapping
  - 20.15.8 Auto-Remapping
  - 20.15.9 Unmapping
- 20.16 Exception Handling
  - 20.16.1 Exceptions
  - 20.16.2 try-catch
  - 20.16.3 try-until
  - 20.16.4 raise
  - 20.16.5 exception-predicate
  - 20.16.6 assert
- 20.17 Terminal
  - 20.17.1 Terminal Colors
  - 20.17.2 Terminal Styling
  - 20.17.3 Terminal Hyperlinks
- 20.18 Printing
  - 20.18.1 print
  - 20.18.2 printf
- 20.19 Comments
  - 20.19.1 Multi-line comments
  - 20.19.2 Single line comments
  - 20.19.3 Vertical separator
- 20.20 Modules
- 20.21 System
  - 20.21.1 getenv
  - 20.21.2 rand
- 20.22 VM
  - 20.22.1 vm_obase
  - 20.22.2 vm_set_obase
  - 20.22.3 vm_opprint
  - 20.22.4 vm_set_opprint
  - 20.22.5 vm_oacutoff
  - 20.22.6 vm_set_oacutoff
  - 20.22.7 vm_odepth
  - 20.22.8 vm_set_odepth
  - 20.22.9 vm_oindent
  - 20.22.10 vm_set_oindent
  - 20.22.11 vm_omaps
  - 20.22.12 vm_set_omaps
  - 20.22.13 vm_omode
  - 20.22.14 vm_set_omode
  - 20.22.15 vm_autoremap
  - 20.22.16 vm_set_autoremap
- 20.23 Debugging
  - 20.23.1 __LINE__ and __FILE__
  - 20.23.2 strace
21 The Standard Library
- 21.1 Standard Integral Types
- 21.2 Standard Offset Types
- 21.3 Standard Units
- 21.4 Conversion Functions
- 21.5 Array Functions
  - 21.5.1 reverse
- 21.6 String Functions
- 21.7 Character Functions
- 21.8 Values Functions
  - 21.8.1 eoffset
- 21.9 IO Space Functions
  - 21.9.1 with_cur_ios
  - 21.9.2 with_temp_ios
- 21.10 Sorting Functions
  - 21.10.1 qsort
- 21.11 CRC Functions
- 21.12 Dates and Times
- 21.13 Offset Functions
  - 21.13.1 alignto
- 21.14 Other Standard Library Functions
  - 21.14.1 GNU poke Version String Parsing Utilities
22 The Poke Virtual Machine
- 22.1 PVM Instructions
Appendix A Table of ASCII Codes
Appendix B GNU Free Documentation License
Appendix C Indices
- C.1 Concept Index
- C.2 PVM Instruction Index

GNU poke Manual

GNU poke is an interactive, extensible editor for binary data. Not limited to editing basic entities such as bits and bytes, it provides a full-fledged procedural, interactive programming language designed to describe data structures and to operate on them.

This manual describes the poke binary data editor as well as the Poke language.

Getting Started
• Introduction		Introducing GNU poke.
• Setting Up		Preparing to use GNU poke.
Using poke
• Basic Editing		Poking bits, bytes and simple data.
• Structuring Data		Poking your own abstractions.
• Maps and Map-files		Working with views of data.
• Writing Pickles		Sharing your abstractions the sane way.
• Writing Binary Utilities		Standalone Poke programs.
• Configuration		Tailoring the tool to your needs.
Pickles
• IOS		Functions to work with IO spaces.
• Time		Handling time.
• Colors		Editing colors.
• Audio		Poking audio files.
• Object Formats		Editing executables and libraries.
• Programs		Facilities to write binary utilities.
poked
• poked		The poke daemon.
poke and Emacs
• Programming Emacs Modes		Modes to write Poke and RAS programs.
poke and Vim
• Vim Syntax Highlighting		Poke Syntax Highlighting in Vim.
Reference Material
• Dot-Commands		Commanding the tool.
• Commands		Commands for editing data.
• The Poke Language		Poke reference manual.
• The Standard Library		Standard goodies for Poke programs.
Internals
• The Poke Virtual Machine		The PVM and its mysteries.
Appendices
• Table of ASCII Codes		The ASCII character set.
• GNU Free Documentation License		Distribution terms for this document.
• Indices		List of indices in this document.

Here are some other nodes which are really subnodes of the ones already listed, mentioned here so you can get to them in one step: Introduction
• Motivation		Why a binary editor?
• Nomenclature		poke, Poke and pickles.
• Invoking poke		command line options.
• Commanding poke		Interactive and non-interactive usage.
Setting Up
• Setting up Hyperlinks		GNU poke uses terminal hyperlinks.
• Simple Init File		A simple initial ~/.pokerc.
Basic Editing
• Binary Files		Text vs. binary.
• Files as IO Spaces		Poking files.
• Dumping File Contents		A first look at a file’s bytes.
• Poking Bytes		Reading, manipulating and writing bytes.
• Values and Variables		Values can be stored in variables.
• From Bytes to Integers		Building numbers with bytes.
• Big and Little Endians		Pick your egg.
• Negative Integers		Going behind zero.
• Weird Integers		Incomplete bytes in numbers.
• Unaligned Integers		IO spaces are bit-oriented.
• Integers of Different Sizes		Promotion of integers in expressions.
• Offsets and Sizes		United values.
• Buffers as IO Spaces		Poking memory buffers.
• Copying Bytes		Moving data between IO spaces.
• Saving Buffers in Files		From memory to files.
• Character Sets		ASCII, Unicode, …
• From Bytes to Characters		Working with ASCII codes
• ASCII Strings		NULL-terminated strings.
• From Strings to Characters		Indexing strings.
Structuring Data
• The SBM Format		The Stupid BitMap Format
• Poking a SBM Image		A need for abstraction.
• Modifying SBM Images		Modifying existing data.
• Defining Types		Abstracting data structures.
• Pickles		Pickling useful abstractions.
• Poking Structs		Abstracting heterogeneous data.
• How Structs are Built		How poke builds struct values.
• Variables in Structs
• Functions in Structs
• Struct Methods		Operations provided by built structs.
• Padding and Alignment		Reserved fields, payloads and more.
• Dealing with Alternatives		Conditional decoding.
• Structured Integers		Structs that are stored like integers.
• Working with Incorrect Data		Non-strict mapping to the rescue.
Maps and Map-files
• Editing using Variables		Data is usually edited mapping variables.
• poke Maps		Maps and map-files.
• Loading Maps		Using maps defined in files.
• Multiple Maps		Multiple perspectives of the same data.
• Auto-map		Loading maps automagically.
• Constructing Maps		Creating and managing maps on the fly.
• Predefined Maps		Collection of already-written maps.
Writing Pickles
• Pretty-printers		Conventions for pretty-printed output.
• Setters and Getters		Anatomy getters and setters.
Writing Binary Utilities
• Poke Scripts		Using poke as an interpreter.
• Command-Line Arguments		Handling command-line arguments.
• Exiting from Scripts		Exit with an error status.
• Loading pickles as Modules		Importing pickles in programs.
• elfextractor		An example Poke binary utility.
• Filters		Writing filters for binary data.
Configuration
• pokerc		User’s initialization file.
• Load Path		Determining location of modules.
• Styling		Changing the appearance of poke’s output.
Time
• POSIX Time		Encoding POSIX dates.
Colors
• The Color Registry		The `color` pickle.
• RGB24 Encoding		Encoding colors with three bytes.
Audio
• MP3		Editing MP3 files.
Programming Emacs Modes
• poke-mode		Major mode for writing Poke programs.
• poke-map-mode		Major mode for writing map-files.
• poke-ras-mode		Major mode for writing RAS programs.
Vim Syntax Highlighting
• `poke.vim`		Poke syntax highlighter
Dot-Commands
• load command		Loading pickles.
• source command		Executing commands in files.
• file command		Opening and selecting file IO spaces.
• mem command		Opening and selecting memory IO spaces.
• nbd command		Opening and selecting NBD IO spaces.
• proc command		Opening and selecting process IO spaces.
• ios command		Switching between IO spaces.
• close command		Closing IO spaces.
• doc command		Online manual.
• editor command		Using an external editor for input.
• info command		Getting information about open files, etc.
• set command		Querying and setting global options.
• vm command		Poke Virtual Machine services.
• exit command		Exiting poke :(
• quit command		Likewise.
Commands
• dump		Binary dumps.
• copy		Copying data around.
• save		Save data into a file.
• sdiff		Comparing mapped values byte by byte.
• extract		Extract contents of values to buffers.
• scrabble		Scrabble memory chunks based on patterns.
The Poke Language
• Integers		Whole numbers.
• Offsets		Memory sizes and offsets.
• Strings		NULL-terminated strings.
• Arrays		Homogeneous collections.
• Structs		Heterogeneous collections.
• Types		Declaring types.
• Assignments		Changing the value of variables.
• Compound Statements		Sequences of statements.
• Conditionals		Conditional statements and expressions.
• Loops		Statements to iterate on conditions.
• Expression Statements		Using expressions for their side-effects.
• Functions		Procedural abstraction.
• Assembler		Assembler instructions with Poke operands.
• Endianness		Byte ordering.
• Mapping		Accessing IO spaces.
• Exception Handling		Dealing with exceptional conditions.
• Terminal		Dealing with the terminal.
• Printing		Output in Poke programs.
• Comments		Documenting Poke programs.
• Modules		Loading pickles from Poke programs.
• System		Accessing the system from within Poke.
• VM		Tweaking the PVM in Poke programs.
• Debugging		Debugging Poke programs.
The Standard Library
• Standard Integral Types		int, long and the like.
• Standard Offset Types		off64 and the like.
• Standard Units		b, B, Kb and the like.
• Conversion Functions		catos, atoi, etc.
• Array Functions		Functions which deal with arrays.
• String Functions		Functions which deal with strings.
• Character Functions		Functions which deal with characters.
• Values Functions		Functions which deal with values in general.
• Sorting Functions		qsort.
• CRC Functions		Cyclic Redundancy Checksums.
• Dates and Times		Processing and displaying dates and times.
• Offset Functions		Useful functions that operate on offsets.
• Other Functions		Miscellany.
The Poke Virtual Machine
• PVM Instructions		Virtual Machine instructions.

GNU poke Manual

Table of Contents

GNU poke Manual