ACHTUNG: AS OF 20110523, THIS PAGE IS NOW MAINTAINED IN THE NEW WIKI: http://whiki.wanderinghorse.net/wikis/whio/?page=whio_udb_tool

whio-udb-tool

whio-udb-tool for testing and in general tinkering with whio_udb files. It has a number of commands for inserting, searching, and removing records, as well as more esoteric things like adding empty records, viewing the free-list chain, and such. i.e. it's a tool with which i can test the db API while developing.

It is currently ONLY useful for databases storing string data, and may produce garbage on stdout or stderr if used with a binary-data db.

Its usage is much different from the whio_epfs tools, and more like that of the Sun Cluster family of tools. In the abstract it is used like this:

whio-udb-tool [-m] db_file COMMAND [command args]

It supports commands to do the following:

• create [-f] hashSize N keyLen N dataLen N [funcSet "name"]
  Create or "format" a udb file. The arguments are as documented for whio_udb_dev_format(). Use -f to force overwriting of an existing file.
• insert
  Insert new records from standard input, one record per line, first token is the key and the rest is the value.
• ls: list all records.
• replace
  Like insert, but replaces any existing entry instead of failing.
• rm KEY1..N
  remove records by key. Use RM to not fail if the record is not found.
• search KEY1..N
  search by key name. This is an O(1) operation.
• glob PATTERN1..N
  Search by key by wildcard pattern. e.g. "*.txt". This is a relatively slow operation.
• like PATTERN1..N
  Search by SQL-formatted wildcard. e.g. "%.txt". This is a relatively slow operation.
• magic
  Show some internal details about the library and the db.
• freelist (alias: fl)
  List the free-list chain.
• add [N=1]
  Add empty/unused records to the db, to reserve storage capacity for future inserts.

Run it without any arguments for the usage/help text.

There are lots of potential combinations which are not implemented, e.g. "rm 'a*'", but some of them won't work at the moment due to constness issues, and may never work due to locking-related issues.

Example:

~> whio-udb-tool u.db create hashSize 919 keyLen 32 dataLen 1 funcSet strings
formatted file [u.db] as a whio_udb.

~> whio-udb-tool u.db magic
uDB magic bytes, sizes, and such:
	sizeof(whio_udb) = 132
	sizeof(whio_udb_opt) = 12
	sizeof(whio_udb_record) = 40
	sizeof(whio_udb_result) = 16
	whio_udb_sizeof_record_header = 36
	whio_udb_sizeof_magic = 55
	whio_udb_sizeof_dbopt = 16
	WHIO_UDB_MAGIC_STRING=[whio_udb:format version=20100313:WHIO_SIZE_T_BITS=0x20]
	strlen WHIO_UDB_MAGIC_STRING=[54]
	db hashtable size: 919
	db max key length: 32
	db max data length: 1
	db highest record ID: 0
	db->osz[whio_udb_osz_sizeof_page_line]=118
	db->osz[whio_udb_osz_sizeof_ht]=5514

~> ls -1 | ./whio-udb-tool u.db insert
...
Inserted: [libwhio_udb.a]=[]
Inserted: [libwhio_udb.so]=[]
Inserted: [Makefile]=[]
...
Inserted: [whio-udb-tool.o]=[]

~> whio-udb-tool u.db ls
List of all record entries:
...
	#12	[libwhio_udb.a]
	#13	[libwhio_udb.so]
...
	#32	[whio-udb-tool.o]
Visited 32 record(s).

~> whio-udb-tool u.db fl
Free-record list:
	Free-list is empty.

~> whio-udb-tool u.db add 3
Added 3 of 3 empty/unused record(s).
~> whio-udb-tool u.db fl
Free-record list:
	0<-35->34
	35<-34->33
	34<-33->0
End of free-list.

~> whio-udb-tool u.db ls
...
	#32	[whio-udb-tool.o]
	#33	-->UNUSED<--  prev=34 next=0
	#34	-->UNUSED<--  prev=35 next=33
	#35	-->UNUSED<--  prev=0 next=34
Visited 35 record(s).

~> whio-udb-tool u.db rm whio-udb-tool.o
	Removing [whio-udb-tool.o]	REMOVED

~> whio-udb-tool u.db ls
...
	#30	[whio-udb-tool]
	#31	-->UNUSED<--  prev=0 next=32
	#32	-->UNUSED<--  prev=31 next=35
...

~> whio-udb-tool u.db like 'wh%' 
Attempting to match patterns:	[wh%]
	RecordID	Key
	#25	[whglob.c]
	#26	[whglob.o]
	#27	[whio_udb.c]
	#28	[whio_udb.h]
	#29	[whio_udb.o]
	#30	[whio-udb-tool]

Matched 6 record(s) with 1 pattern(s).