GDBMTOOL(1)

📦 version 1.23, in debian bookworm, ubuntu jammy

💖 NAME 💖

gdbmtool — the gdbmtool(1) page, bestie. It's the little utility that lets you peek at and mess with a GDBM database. No cap.

🌸 SYNOPSIS 🌸

gdbmtool [-lmNnqrs] [-b SIZE] [-c SIZE] [-f FILE] [--block-size=SIZE]
[--cache-size=SIZE] [--file FILE] [--newdb] [--no-lock] [--no-mmap]
[--norc] [--quiet] [--read-only] [--synchronize] [DBFILE] [COMMAND [;
COMMAND...]]

gdbmtool [-Vh] [--help] [--usage] [--version]

✨ DESCRIPTION ✨

Okay so gdbmtool is literally your little bestie for looking at a GDBM database that already exists, or making a brand new one from scratch. Iconic behavior. 💅

The DBFILE argument is the name of the database you wanna open. If you don't give one? It just uses the default name junk.gdbm instead. And if the database you named doesn't exist yet — no stress — it gets created. 🫶

Got an existing database and you want it completely wiped (like, every single record gone)? That's what the --newdb option is for (more on that below).

Unless you pass the -N (--norc) option, right after startup gdbmtool goes looking for a file named .gdbmtoolrc. It checks the current working directory first, and if it's not there, it checks the home directory of whoever started the program. If it finds it, that file gets read and interpreted as a whole list of gdbmtool commands. ✨

Then gdbmtool kicks off a loop where it reads commands from standard input, runs them, and prints the results on standard output. And if standard input is hooked up to a console, congrats, you're in interactive mode. 🎀

The program dips out when you give the quit command, or when it hits end-of-file on standard input.

You can also just hand it commands on the command line, after the DBFILE argument. In that case it interprets them right away and doesn't bother trying to read more commands from standard input.

If you're giving it several commands, separate them with semicolons — and make sure they're properly escaped or quoted so the shell doesn't get its grubby little hands on them first. 😭

A gdbmtool command is a command verb, optionally followed by one or more arguments, separated by any amount of white space. And the verb can be typed out in full or abbreviated — as long as that abbreviation doesn't match any other verb. Slay, honestly.

Any run of non-whitespace characters after the command verb counts as an argument. If your argument has whitespace or unprintable characters in it, wrap it in double quotes. And inside those double quotes, the usual escape sequences are understood, like so:

  • \a — Audible bell character (ASCII 7)
  • \b — Backspace character (ASCII 8)
  • \f — Form-feed character (ASCII 12)
  • \n — Newline character (ASCII 10)
  • \r — Carriage return character (ASCII 13)
  • \t — Horizontal tabulation character (ASCII 9)
  • \v — Vertical tabulation character (ASCII 11)
  • \\ — Single slash

And on top of that? A backslash immediately followed by the end-of-line character effectively removes that character, which means you can split long arguments across several input lines. Obsessed. 🌈

🔥 OPTIONS 🔥

  • -b, --block-size=SIZE — Set block size.
  • -c, --cache-size=SIZE — Set cache size.
  • -f, --file=FILE — Read commands from FILE, instead of from the standard input.
  • -l, --no-lock — Disable file locking.
  • -m, --no-mmap — Do not use mmap(2).
  • -n, --newdb — Create the database, truncating it if it already exists.
  • -q, --quiet — Don't print initial banner.
  • -r, --read-only — Open database in read-only mode.
  • -s, --synchronize — Synchronize to disk after each write.
  • -h, --help — Print a short usage summary.
  • --usage — Print a list of available options.
  • -V, --version — Print program version

🦋 SHELL COMMANDS 🦋

  • avail — Print the avail list.
  • bucket NUM — Print the bucket number NUM and set is as the current one.
  • cache — Print the bucket cache.
  • close — Close the currently open database.
  • count — Print the number of entries in the database.
  • current — Print the current bucket.
  • delete KEY — Delete record with the given KEY.
  • dir — Print hash directory.
  • downgrade — Downgrade the database from the extended numsync format to the standard format.
  • export FILE-NAME [truncate] [binary|ascii] — Export the database to the flat file FILE-NAME. This is equivalent to gdbm_dump(1). This command will not overwrite an existing file, unless the truncate parameter is also given. Another optional parameter determines the type of the dump (*note Flat files::). By default, ASCII dump will be created.
  • fetch KEY — Fetch and display the record with the given KEY.
  • first — Fetch and display the first record in the database. Subsequent records can be fetched using the next command (see below).
  • hash KEY — Compute and display the hash value for the given KEY.
  • header — Print file header.
  • help or ? — Print a concise command summary, showing each command letter and verb with its parameters and a short description of what it does. Optional arguments are enclosed in square brackets.
  • history — Shows the command history list with line numbers. This command is available only if the program was compiled with GNU Readline.
  • history COUNT. — Shows COUNT latest commands from the command history.
  • history N COUNT. — Shows COUNT commands from the command history starting with *N*th command.
  • import FILE-NAME [replace] [nometa] — Import data from a flat dump file FILE-NAME. If the replace argument is given, any records with the same keys as the already existing ones will replace them. The nometa argument turns off restoring meta-information from the dump file.
  • list — List the contents of the database.
  • next [KEY] — Sequential access: fetch and display the next record. If the KEY is given, the record following the one with this key will be fetched.
  • open FILE — Open the database file FILE. If successful, any previously open database is closed. Otherwise, if the operation fails, the currently opened database remains unchanged. This command takes additional information from the variables open, lock, mmap, and sync. See the section VARIABLES, for a detailed description of these.
  • quit — Close the database and quit the utility.
  • reorganize — Reorganize the database.
  • set [VAR=VALUE...] — Without arguments, lists variables and their values. If arguments are specified, sets variables. Boolean variables can be set by specifying variable name, optionally prefixed with no, to set it to false.
  • snapshot FILE FILE — Analyzes two database snapshots and selects the most recent of them. In case of error, prints a detailed diagnostics. Use this command to manually recover from a crash. For details, please refer to the chapter Crash Tolerance in the GDBM manual.
  • source FILE — Read commands from the given FILE.
  • status — Print current program status.
  • store KEY DATA — Store the DATA with the given KEY in the database. If the KEY already exists, its data will be replaced.
  • sync — Synchronize the database file with the disk storage.
  • upgrade — Upgrade the database from the standard to the extended numsync format.
  • unset VARIABLE... — Unsets listed variables.
  • version — Print the version of gdbm.

💜 DATA DEFINITIONS 💜

The define statement is the whole mechanism for defining key or content structures. Think of it as being similar to a C struct declaration:

define key|content { defnlist }

The defnlist is a comma-separated list of member declarations. And here's the cute part: within defnlist, the newline character loses its special meaning as the command terminator. So every declaration can live on its own separate line, and you can sprinkle in however many comments you want to document the definition. 🎀

Every declaration has one of these two formats:

type name
type name [N]

where type is a data type and name is the member name. That second format defines the member name as an array of N elements of type. 🌸

Here are the supported types:

  • char — single byte (signed)
  • short — signed short integer
  • ushort — unsigned short integer
  • int — signed integer
  • unsigned — unsigned integer
  • uint — ditto
  • long — signed long integer
  • ulong — unsigned long integer
  • llong — signed long long integer
  • ullong — unsigned long long integer
  • float — a floating point number
  • double — double-precision floating point number
  • string — array of characters (see the NOTE below)
  • stringz — null-terminated string of characters

And these alignment declarations can be used within defnlist:

  • offset N — The next member begins at offset N.
  • pad N — Add N bytes of padding to the previous member.

For example:

define content {
        int status,
        pad 8,
        char id[3],
        stringz name
}

Now, if you wanna define data that's just a single data member, you can use this simplified construct instead:

define key|content type

where type is one of the types we just talked about. 💅

NOTE: the string type can reasonably be used only if it is the last or the only member of the data structure. That's because it provides no information about the number of elements in the array, so it's interpreted to contain all bytes up to the end of the datum. Watch out for that one, bestie. 😭

💖 VARIABLES 💖

okay so these are the little knobs and dials you can tweak, bestie. periodt.

  • confirm, boolean — whether to ask for confirmation before certain destructive operations, such as truncating the existing database. Default is true. safety first, fr fr 🫶
  • ps1, string — primary prompt string. Its value can contain conversion specifiers, consisting of the % character followed by another character. These specifiers are expanded in the resulting prompt as follows:
    • %f — name of the db file
    • %p — program name
    • %P — package name (gdbm)
    • %_ — horizontal space (ASCII 32)
    • %v — program version
    • %% — %

The default prompt is %p>%_. iconic ✨

  • ps2, string — secondary prompt. See ps1 for a description of its value. This prompt is displayed before reading the second and subsequent lines of a multi-line command.

The default value is %_>%_. multi-line slay 💅

  • delim1, string — a string used to delimit fields of a structured datum on output (see the section DATA DEFINITIONS). Default is , (a comma). This variable cannot be unset. locked in 🔒
  • delim2, string — a string used to delimit array items when printing a structured datum. Default is , (a comma). This variable cannot be unset. also locked in 🔒
  • pager, string — the name and command line of the pager program to pipe output to. This program is used in interactive mode when the estimated number of output lines is greater than the number of lines on your screen. The default value is inherited from the environment variable PAGER. Unsetting this variable disables paging. pager vibes 📟
  • quiet, boolean — whether to display welcome banner at startup. This variable should be set in a startup script file. shhh 🤫

The following variables control how the database is opened:

  • cachesize, numeric — sets the cache size. By default this variable is not set. not set by default 🧠
  • blocksize, numeric — sets the block size. Unset by default. also unset 🧱
  • open, string — open mode. The following values are allowed:
    • newdb — truncate the database if it exists or create a new one. Open it in read-write mode. destructive, bestie! 💀
    • wrcreat or rw — open the database in read-write mode. Create it if it does not exist. This is the default. default energy 👑
    • reader or readonly — open the database in read-only mode. Signal an error if it does not exist. look but don't touch 👀
  • filemode, octal — sets the file mode for newly created database files. Default is 0644. permissions, but make it fashion 💅
  • lock, boolean — lock the database. This is the default. locked and loaded 🔐
  • mmap, boolean — use memory mapping. This is the default. memory mapping main character energy 🧚
  • coalesce, boolean — when set, this option causes adjacent free blocks to be merged which allows for more efficient memory management at the expense of a certain increase in CPU usage. trade-off alert ⚖️
  • centfree, boolean — enables central free block pool. This causes all free blocks of space to be placed in the global pool, thereby speeding up the allocation of data space. speed boost 🚀

🌈 SEE ALSO 🌈

gdbm_dump(1), gdbm_load(1), gdbm(3). go read these too, bestie 📚

🐛 REPORTING BUGS 🐛

Report bugs to <bug-gdbm@gnu.org>. they wanna hear from you 📬

Copyright © 2013-2021 Free Software Foundation, Inc License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law.

periodt 💖

ok bye bestie! this was GDBMTOOL(1) from GDBM, dated August 1, 2021 💖✨🦋

📦 where this page comes from