GNU poke Manual

Table of Contents

Next: , Up: (dir)   [Contents][Index]

GNU poke Manual

This manual describes GNU poke (version 4.0, 19 February 2024).

Copyright © 2019, 2020, 2021, 2022, 2023, 2024 The poke authors.

You can redistribute it and/or modify this manual under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

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. 

Customizing poke
• pokerc  User’s initialization file.
• Load Path  Determining location of modules.
• Styling  Changing the appearance of poke’s output.
• Changing the Prompt  The prompt can be made more useful. 

Pickles
• IOS  Functions to work with IO spaces.
• Data Encodings  base 64 and friends.
• 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. 

pokefmt
• pokefmt  The poke template system. 

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. 

Data Encodings
• base64  Encoding and decoding data in base64. 

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.
• mmap command  Opening and selecting memory mapped devices.
• 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.

Next: , Up: (dir)   [Contents][Index]