BVI(1)

📦
version 1.5.0 · 5 versions
, in alpine 3.24, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu resolute, ubuntu stonking

💖 BVI — the manual, but make it make sense 💖

okay so bestie. sit down. we're talking about bvi and bview, and ngl this page is a whole vibe. it's BVI(1), User Commands, and it's giving "hex editor that actually loves you". let's get into it 🫶

✨ NAME ✨

bvi, bview — visual editor for binary files. that's it, that's the whole pitch, slay 💅

🌸 VERSION 🌸

bvi-1.5.0 — periodt, that's the version, don't @ me ✨

🦋 SYNOPSIS 🦋

bvi   [-R] [-c cmd] [-f script] [-s skip] [-e end] [-n length] file...
bview [-R] [-c cmd] [-f script] [-s skip] [-e end] [-n length] file...

literally the same flags for both, they're twins, iconic 👑

🎀 OPTIONS 🎀

okay so here's where it gets good. every single one of these matters, so pay attention bestie:

  • file... — a list of filenames. the first one becomes the current file and gets read into the buffer, and the cursor parks itself on the first line of the buffer. wanna hop to the other files? use the :next command, easy 💖
  • -R — "Readonly". the readonly flag gets set for all the files, so you can't accidentally overwrite stuff with a write command. protective king behavior 🛡️
  • -s skip — makes bvi load a file not from the start but from offset skip. so it skips skip offset bytes from the beginning of the input. by default, offset is read as a decimal number. with a leading 0x or 0X it's hexadecimal, otherwise with a leading 0 it's octal. and if you append b, k, or m to offset, it gets interpreted as a multiple of 512, 1024, or 1048576 respectively. math girlies rise up 🧚
  • -e end — makes bvi load a file not till end but till address end. yeah. exactly what it says 🌸
  • -n length — makes bvi not load the complete file but only length bytes. lil snack instead of the whole meal 🍓
  • -c cmd — cmd gets executed after the first file has been read. if cmd contains spaces it must be wrapped in double quotes (this depends on the shell you're using, iykyk). so like, quote it. please. 🙈
  • -f script — this one is a whole moment. it gives you a way to collect a series of ex (colon) commands into a script file, then use that file to edit other files. and since there is no binary stream editor "bsed", you can use this option to make several global changes in a binary file. no bsed? no problem, we improvise 💅

💜 DESCRIPTION 💜

Bvi stands for "Binary VIsual editor". yes. it's a screen oriented editor for binary files, and its command set is based on that of the vi(1) text editor. but here's the plot twist — since bvi is a binary editor, it does not have the concept of "lines". all end-of-lines (EOLs) are simply bytes. therefore bvi's commands are different from vi's commands for all the line-oriented commands (see below). no lines, no drama, just bytes 💀

🔥 COMPARISON 🔥

the main differences between Vi and Bvi are, bestie:

the screen is divided into three sections (or panes): the byte offset (extreme left), the hex pane (middle), and an ascii pane (right) which shows as printable characters those bytes that are in the hex pane. on an 80 column terminal there will be sixteen hex values and their ASCII values on each screen line. and note that (as one would expect) the first byte has the offset '0' (zero). zero. not one. we start at zero here 🫶

you can toggle between the hex and ascii windows with the tab key (TAB). and toggling between these two windows does not change the current position (offset) within the file. your place is safe, periodt ✨

No "lines" concept: files are treated as one long stream of bytes. the characters "newline" and "carriage return" are not special, id est they never mark the end of lines. therefore the lines on the screen do not represent lines in the usual way. data is broken across screen lines arbitrarily. as a consequence there are no commands in bvi from ex or vi that are based on line numbers, eg dd, yy, C, S, o, O. this also changes the meaning of "range" before the :write command to a byte offset, ie the command :100,200w foo writes all bytes (not lines) from offset 100 to offset 200 to the file foo. read that again. bytes. not lines. 😭

No "text objects": there are also no text-specific arrangements like words, paragraphs, sentences, sections and so on. gone. not here. we don't do that 🌈

Extended "ruler": the bottom line of the screen shows the current address (byte offset) and the current character in these notations:

octal, hexadecimal, decimal and ascii.

Search patterns: all search commands understand these special characters:

.    any character
[]   set of characters
*    zero or more occurrences of previous char or set

but as there is no concept of lines you cannot use the standard symbols ("anchors") for "begin-of-line" (^) and "end-of-line" ($). searching for the start/end of lines must be done explicitly by adding these special characters to your search pattern using these meta sequences:

\n   newline
\r   return
\t   tab
\0   binary zero

Additional search commands: similar to the text search commands there are additional hex-search functions \ and # which allow one to search for any byte value. example: "\62 76 69" will search for the string "bvi". spaces between hex value are optional, so searching for "6775636B6573" will find "guckes". obsessed with this ngl 🔍

changing the length of data (insertion, deletion) moves the data to other addresses. this is bad for many cases (eg. databases, program files) and is thus disabled by default. you can enable this commands by typing:
:set memmove

okay so now the BVI Modes, and there's three of them, main character energy for real:

👑 Command Mode (Normal Mode) 👑

input is treated as command. note that command mode is the default mode after startup and after escaping from input mode. use ESC (escape) to cancel a partial (uncompleted) command. unfinished business? cancel it, queen 💅

🌸 Input Mode 🌸

input is treated as replacement of current characters or (after the end of the file) is appended to the current file. this mode is entered from command mode by typing one of i, I, A, r, or R. you can enter the characters from the keyboard (in the ASCII window) or hexadecimal values (in the HEX window). type TAB to switch between these two windows. type ESC to finish the current input and return to command mode. type CTRL-C to cancel current command abnormally. know your exits bestie 🚪

🦋 Command line mode (Last Line Mode or : mode) 🦋

similar to vi, this mode is entered by typing one of the characters : / ? \ # ! — the command is terminated and executed by typing a carriage return; to cancel a partially typed command, type ESC to cancel the current command and return to command mode. so many ways in, one clean way out ✨

🌿 ENVIRONMENT 🌿

the editor recognizes the environment variable BVIINIT as a command (or list of commands) to run when it starts up. if this variable is undefined, the editor checks for startup commands in the file ~/.bvirc, which you must own. however, if there is a .bvirc owned by you in the current directory, the editor takes its startup commands from this file — overriding both the file in your home directory and the environment variable. current directory wins, home dir and env var cry about it, that's just the rules 🏆

💫 TERMINOLOGY 💫

character names are abbreviated as follows:

  • CR — 010 — carriage return
  • ^A — 001 — control-a
  • ^H — 008 — control-h
  • ^I — 009 — control-i — aka TAB
  • ^U — 021 — control-u
  • ^Z — 026 — control-z
  • ESC — 027 — escape — aka ESC
  • DEL — 127 — delete
  • LEFT — --- — left arrow
  • RIGHT — --- — right arrow
  • DOWN — --- — down arrow
  • UP — --- — up arrow

and that's where part 1 leaves us, bestie — more is coming, don't go anywhere 💖

💅 COMMAND SUMMARY 💅

okay bestie, before we dive in — peek at TERMINOLOGY for the rundown on all the key-name abbreviations used in the command descriptions below. iykyk 🫶

🌸 Abstract 🌸

Arrow keys move the cursor on the screen within the current window. that's it. that's the whole vibe.

⭐ Sample commands ⭐

:version    show version info
<- v ^ ->   arrow keys move the cursor
h j k l     same as arrow keys
u           undo previous change
ZZ          exit bvi, saving changes
:q!         quit, discarding changes
/text       search for text
^U ^D       scroll up or down

🔢 Counts before bvi commands 🔢

Numbers may be typed as a prefix to some commands. They are interpreted in one of these ways, and which way depends on the command:

screen column       ⎪
byte of file        G
scroll amount       ^D  ^U
repeat effect       most of the rest

🛑 Interrupting, canceling 🛑

  • ESC — end insert or incomplete command
  • DEL — (delete or rubout) interrupts

📁 File manipulation 📁

  • ZZ — if file modified, write and exit; otherwise, exit
  • :w — write changed buffer to file
  • :w! — write changed buffer to file, overriding read-only (this is a "forced" write, no cap 💅)
  • :q — quit when no changes have been made
  • :q! — quit and discard all changes
  • :e file — edit file
  • :e! — re-read current file, discard all changes
  • :e # — edit the alternate file
  • :e! # — edit the alternate file, discard changes
  • :w file — write current buffer to file
  • :w! file — write current buffer to file overriding read-only (this "overwrites" the file)
  • :sh — run the command as set with option "shell", then return
  • :!cmd — run the command cmd from "shell", then return
  • :n — edit next file in the argument list
  • :f — show current filename, modified flag, current byte offset, and percentage of current position within buffer
  • ^G — same as :f

✏️ Additional edit commands ✏️

You can insert/append/change bytes in ASCII/binary/decimal/hexadecimal or octal representation. You can enter several (screen) lines of input. A line with only a period (.) in it will terminate the command.

🚨 You must not type in values greater than a byte value. That causes an abandonment of the command. bye bye input, we hardly knew ye 😭

Pressing the CR key does not insert a newline-character into the file. If you use ASCII mode you can use the special characters \n, \r, \t and \0.

:i aCR      insert bytes (ASCII) at cursor position
:a bCR      append bytes (Binary) at end of file
:c hCR      change bytes (hexadecimal) at cursor position

🧮 Bit-level operations 🧮

  • :and n — bitwise 'and' operation with value n
  • :or n — bitwise 'or' operation with value n
  • :xor n — bitwise 'xor' operation with value n
  • :neg — two's complement
  • :not — logical negation
  • :sl i — shift each byte i bits to the left
  • :sr i — shift each byte i bits to the right
  • :rl i — rotate each byte i bits to the left
  • :rr i — rotate each byte i bits to the right

📍 Command mode addresses 📍

:w foo         write current buffer to a file
               named "foo"
:5,10w foo     copy byte 5 through 100 into as
               file named foo
:.,.+20w foo   copy the current byte and the next
               20 bytes to foo
:^,'aw foo     write all bytes from the beginning
               through marker 'a'
:/pat/,$ foo   search pattern pat and and copy
               through end of file

🧭 Positioning within file 🧭

  • ^B — backward screen
  • ^F — forward screen
  • ^D — scroll down half screen
  • ^U — scroll up half screen
  • nG — go to the specified character (end default), where n is a decimal address
  • /pat — next line matching pat
  • ?pat — previous line matching pat
  • \hex — jump to next occurrence of hex string hex
  • #hex — jump to previous occurrence of hex string hex
  • n — repeat last search command
  • N — repeat last search command, but in opposite direction

🖥️ Adjusting the screen 🖥️

  • ^L — clear and redraw screen
  • zCR — redraw screen with current line at top of screen
  • z- — redraw screen with current line at bottom of screen
  • z. — redraw screen with current line at center of screen
  • /pat/z- — search for pattern pat and then move currents line to bottom
  • ^E — scroll screen down 1 line
  • ^Y — scroll screen up 1 line

🎀 Marking and returning 🎀

  • mx — mark current position with lower-case letter x. Note: this command works for all lower-case letters
  • 'x — move cursor to mark x in ASCII section
  • `x — move cursor to mark x in HEX section
  • '' — move cursor to previous context in ASCII section
  • `` — move cursor to previous context in HEX section

⬆️⬇️ Line positioning ⬆️⬇️

  • H — jump to first line on screen ("top")
  • L — jump to last line on screen ("low")
  • M — jump to middle line on screen ("middle")
  • - — jump onto previous line on screen
  • + — jump onto next line on screen
  • CR — same as +
  • DOWN or j — next line, same column
  • UP or k — previous line, same column

🔤 Character positioning 🔤

  • ^ — first byte in HEX window
  • $ — end of screen line
  • l or RIGHT — jump onto next byte (within current screen line)
  • h or LEFT — jump onto previous byte (within current screen line)
  • ^H — same as LEFT
  • space — same as RIGHT
  • fx — find next occurrence of character x
  • Fx — find previous occurrence of character x
  • n⎪ — jump onto nth byte/character within current line

🧵 Strings 🧵

(works similar to the strings(1) command)

Note: "Words" are defined as strings of "nonprinting characters". slay 🌈
  • e — jump to next end of word
  • w — jump to next begin of word
  • b — jump to previous begin of word
  • W — forward to next string delimited with a \0 or \n
  • B — back to previous string delimited with a nonprinting char

🙈 Corrections during insert 🙈

  • ^H — erase last character (backspace)
  • erase — your erase character, same as ^H (backspace)
  • ESC — ends insertion, back to command mode

🦋 Append and replace 🦋

  • A — append at end of file
  • rx — replace current byte with char 'x'
  • R — enter replace mode; for all subsequent input, the current byte is overwritten with the next input character; leave replace mode with ESC.

🎲 Miscellaneous Operations 🎲

  • TAB — toggle between ASCII and HEX section

🍓 Yank and Put 🍓

  • 3ySPACE — yank 3 characters
  • p — insert contents of yank buffer
  • o — replace text with content of yank buffer
  • P — put back at end of file

↩️ Undo, Redo ↩️

  • u — undo last change
Note: Only the last change can be undone. Therefore this commands toggles between the last and second-t-last state of the buffer. so it's a lil toggle situation, not a full time machine 😭

⚙️ Setting Options ⚙️

With the :set command you can set options in bvi 💖

  • autowrite (default: noaw) — Save current file, if modified, if you give a :n, :r or ! command
  • columns (default: cm=16) — on an 80 character wide terminal
  • ignorecase (default: noic) — Ignores letter case in searching
  • magic (default: nomagic) — Makes . [ * special in patterns
  • memmove (default: nomm) — enables insert and delete commands
  • offset (default: of=0) — adds an offset to the displayed addresses
  • readonly (default: noro) — If set, write fails unless you use ! after command
  • reverse (default: nore) — display otherwise-printable characters with their high bit set as reverse video
  • scroll (default: sc=1/2 window) — Number of lines scrolled by ^U and ^D
  • showmode (default: mo) — Displays statusline on bottom of the screen
  • terse (default: noterse) — Let you obtain shorter error messages
  • window (default: window=screensize) — Lines in window, can be reduced at slow terminals
  • wordlength (default: wl=4) — Length of an ASCII-string found by w, W, b or B
  • wrapscan (default: ws) — Searches wrap around past the end of the file
  • unixstyle (default: nous) — The representation of ascii characters below 32 is displayed in the statusline as shown in ascii(7) if unset rather in DOS-style (^A)

👑 AUTHOR 👑

bvi was developed by Gerhard Buergmann, Vienna, Austria — gerhard@puon.at

the literal icon who made all this happen 💜

🌐 WWW 🌐

📂 FILES 📂

 $HOME/.bvirc          editor startup file
 ./.bvirc              editor startup file

🔗 SEE ALSO 🔗

bmore(1), vi(1), strings(1), ascii(5)

okay bestie that's the whole page 💖 this lil masterpiece is BVI Version 1.5.0 from the 3rd Berkeley Distribution, and it's filed under BVI(1) 🎀 go forth and edit those bytes, you absolute main character 🫶✨

📦 where this page comes from