File: gdbm.info,  Node: commands,  Next: definitions,  Prev: variables,  Up: shell

24.2.2 Gdbmtool Commands
------------------------

 -- command verb: avail
     Print the "avail list".

 -- command verb: bucket NUM
     Print the bucket number NUM and set it as the current one.

 -- command verb: cache
     Print the bucket cache.

 -- command verb: close
     Close the currently open database.

 -- command verb: count
     Print the number of entries in the database.

 -- command verb: current
     Print the current bucket.

 -- command verb: debug [[+-]TOKEN...]
     If 'GDBM' is configured with additional debugging, this statement
     queries or sets 'GDBM' internal debugging level.  This is intended
     for debugging and testing purposes and requires good knowledge of
     'GDBM' internals.  The use of this command is not recommended.

 -- command verb: delete KEY
     Delete record with the given KEY

 -- command verb: dir
     Print hash directory.

 -- command verb: downgrade
     Downgrade the database from extended to the standard database
     format.  *Note Numsync::.

 -- command verb: export FILE-NAME [truncate] [binary|ascii]
     Export the database to the flat file FILE-NAME.  *Note Flat
     files::, for a description of the flat file format and its
     purposes.  This command will not overwrite an existing file, unless
     the 'truncate' parameter is also given.  Another optional argument
     determines the type of the dump (*note Flat files::).  By default,
     ASCII dump is created.

     The global variable 'filemode' specifies the permissions to use for
     the created output file.

 -- command verb: fetch KEY
     Fetch and display the record with the given KEY.

 -- command verb: first
     Fetch and display the first record in the database.  Subsequent
     records can be fetched using the 'next' command (see below).  *Note
     Sequential::, for more information on sequential access.

 -- command verb: hash KEY
     Compute and display the hash value for the given KEY.

 -- command verb: header
     Print file header.

 -- command verb: help
 -- command verb: ?
     Print a concise command summary, showing each command verb with its
     parameters and a short description of what it does.  Optional
     arguments are enclosed in square brackets.

 -- command verb: import FILE-NAME [replace] [nometa]
     Import data from a flat dump file FILE-NAME (*note Flat files::).
     If the word 'replace' is given as an argument, any records with the
     same keys as the already existing ones will replace them.  The word
     'nometa' turns off restoring meta-information from the dump file.

 -- command verb: history
 -- command verb: history COUNT
 -- command verb: history N COUNT
     Shows the command history list with line numbers.  When used
     without arguments, shows entire history.  When used with one
     argument, displays COUNT last commands from the history.  With two
     arguments, displays COUNT commands starting from Nth command.
     Command numbering starts with 1.

     This command is available only if 'GDBM' was compiled with GNU
     Readline.  The history is saved in file '.gdbmtool_history' in the
     user's home directory.  If this file exists upon startup, it is
     read to populate the history.  Thus, command history is preserved
     between 'gdbmtool' invocations.

 -- command verb: list
     List the contents of the database.

 -- command verb: 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.

     Issuing several 'next' commands in row is rather common.  A
     shortcut is provided to facilitate such use: if the last entered
     command was 'next', hitting the 'Enter' key repeats it without
     arguments.

     See also 'first', above.

     *Note Sequential::, for more information on sequential access.

 -- command verb: open FILENAME
 -- command verb: open
     Open the database file FILENAME.  If used without arguments, the
     database name is taken from the variable 'filename'.

     If successful, any previously open database is closed and the
     'filename' variable is updated.  Otherwise, if the operation fails,
     the currently opened database remains unchanged.

     This command takes additional information from the following
     variables:

     'filename'
          Name of the database to open, if no argument is given.

     'fd'
          File descriptor to use.  If set, this must be an open file
          descriptor referring to a valid database file.  The database
          will be opened using 'gdbm_fd_open' (*note gdbm_fd_open::).
          The file descriptor will be closed and the variable unset upon
          closing the database.

     'filemode'
          Specifies the permissions to use in case a new file is
          created.

     'open'
          The database access mode.  *Note The OPEN variable: openvar,
          for a list of its values.

     'lock'
          Whether or not to lock the database.  Default is 'on'.

     'mmap'
          Use the memory mapping.  Default is 'on'.

     'sync'
          Synchronize after each write.  Default is 'off'.

     *Note open parameters::, for a detailed description of these
     variables.

 -- command verb: perror [CODE]
     Describe the given 'GDBM' error code.

     The description occupies one or two lines.  The second line is
     present if the system error number should be checked when handling
     this code.  In this case, the second line states 'Examine errno'.

     If CODE is omitted, the latest error that occurred in the current
     database is described.  Second line of the output (if present),
     contains description of the latest system error.

     Example:

          gdbmtool> perror 3
          GDBM error code 3: "File open error"
          Examine errno.

 -- command verb: quit
     Close the database and quit the utility.

 -- command verb: recover [OPTIONS]
     Recover the database from structural inconsistencies.  *Note
     Database consistency::.

     The following OPTIONS are understood:

     'backup'
          Create a backup copy of the original database.

     'max-failed-buckets=N'
          Abort recovery process if N buckets could not be recovered.

     'max-failed-keys=N'
          Abort recovery process if N keys could not be recovered.

     'max-failures=N'
          Abort recovery process after N failures.  A "failure" in this
          context is either a key or a bucket that failed to be
          recovered.

     'summary'
          Print the recovery statistics at the end of the run.  The
          statistics includes number of successfully recovered, failed
          and duplicate keys and the number of recovered and failed
          buckets.

     'verbose'
          Verbosely list each error encountered.

 -- command verb: reorganize
     Reorganize the database (*note Reorganization::).

 -- command verb: shell COMMAND
 -- command verb: ! COMMAND
     Execute COMMAND via current shell.  If COMMAND is empty, shell is
     started without additional arguments.  Otherwise, it is run as
     '$SHELL -c COMMAND'.

     For convenience, COMMAND is not parsed as 'gdbmtool' command line.
     It is passed to the shell verbatim.  It can include newline
     characters if these are preceded by a backslash or appear within
     singly or doubly quoted strings.

     When using '!' form, be sure to separate it from COMMAND by
     whitespace, otherwise it will be treated as readline "event
     specifier".

 -- command verb: snapshot FILENAME FILENAME
     Analyze two snapshot files and select the most recent of them.  In
     case of error, display a detailed diagnostics and meta-information
     of both snapshots.

     *Note Manual crash recovery::, for a detailed discussion.

 -- command verb: source FILENAME
     Read 'gdbmtool' commands from the file FILENAME.

 -- command verb: status
     Print current program status.  The following example shows the
     information displayed:

          Database file: junk.gdbm
          Database is open
          define key string
          define content string

     The two 'define' strings show the defined formats for key and
     content data.  *Note definitions::, for a detailed discussion of
     their meaning.

 -- command verb: store KEY DATA
     Store the DATA with KEY in the database.  If KEY already exists,
     its data will be replaced.

 -- command verb: sync
     Synchronize the database with the disk storage (*note Sync::).

 -- command verb: upgrade
     Upgrade the database from standard to extended database format.
     *Note Numsync::.

 -- command verb: version
     Print the version of 'gdbm'.