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

24.2.1 Shell Variables
----------------------

A number of 'gdbmtool' parameters is kept in its internal variables.  To
examine or modify variables, use the 'set' command (*note set::).

 -- gdbmtool variable: bool confirm
     Whether to ask for confirmation before certain destructive
     operations, such as truncating the existing database.

     Default is 'true'.

 -- gdbmtool variable: string delim1
     A string used to delimit fields of a structured datum on output
     (*note definitions::).

     Default is ',' (a comma).  This variable cannot be unset.

 -- gdbmtool variable: string delim2
     A string used to delimit array items when printing a structured
     datum (*note definitions::).

     Default is ',' (a comma).  This variable cannot be unset.

 -- gdbmtool variable: string errorexit
 -- gdbmtool variable: bool errorexit
     Comma-delimited list of 'GDBM' error codes which cause program
     termination.  Error codes are specified via their canonical names
     (*note Error codes::).  The 'GDBM_' prefix can be omitted.  Code
     name comparison is case-insensitive.  Each error code can
     optionally be prefixed with minus sign, to indicate that it should
     be removed from the resulting list, or with plus sign (which is
     allowed for symmetry).  A special code 'all' stands for all
     available error codes.

     In boolean context, the 'true' value is equivalent to 'all', and
     'false' (i.e.  variable unset) is equivalent to '-all'.

     This variable cannot be set from interactive sessions.

 -- gdbmtool variable: string errormask
 -- gdbmtool variable: bool errormask
     Comma-delimited list of 'GDBM' error codes which are masked, i.e.
     which won't trigger a diagnostic message if they occur.  The syntax
     is the same as described for 'errorexit'.

 -- gdbmtool variable: string pager
     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 then the number of lines on your screen.

     The default value is inherited from the environment variable
     'PAGER'.  Unsetting this variable disables paging.

 -- gdbmtool variable: string ps1
     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:

     Sequence                      Expansion
     -------------------------------------------------------------------
     %f                            name of the current database file
     %p                            program invocation name
     %P                            package name ('GDBM')
     %v                            program version
     %_                            single space character
     %%                            %

     The default value is '%p>%_', i.e.  the program name, followed by a
     "greater than" sign, followed by a single space.

 -- gdbmtool variable: string ps2
     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 '%_>%_'.

 -- gdbmtool variable: bool timing
     When each command terminates, print an additional line listing
     times spent in that command.  The line is formatted as follows:

          [reorganize r=0.070481 u=0.000200 s=0.000033]

     Here, 'reorganize' is the name of the command that finished, the
     number after 'r=' is real time spent executing the command, the
     number after 'u=' is the user CPU time used and the number after
     's=' is the system CPU time used.

 -- gdbmtool variable: bool trace
     Enable command tracing.  This is similar to the shell '-t' option:
     before executing each command, 'gdbmtool' will print on standard
     error a line starting with a plus sign and followed by the command
     name and its arguments.

 -- gdbmtool variable: bool quiet
     Whether to display a welcome banner at startup.  To affect
     'gdbmtool', this variable should be set in a startup script file
     (*note startup files::).  *Note -q option::.

   The following variables control how the database is opened:

 -- gdbmtool variable: numeric blocksize
     Sets the block size.  *Note block_size: Open.  Unset by default.

 -- gdbmtool variable: numeric cachesize
     Sets the cache size.  *Note GDBM_SETCACHESIZE: Options.

     This variable affects the currently opened database immediately.
     It is also used by 'open' command.

     To enable automatic cache size selection, unset this variable.
     This is the default.

 -- gdbmtool variable: string filename
     Name of the database file.  If the 'open' command is called without
     argument (e.g.  called implicitly), this variable names the
     database file to open.  If 'open' is called with file name
     argument, upon successful opening of the database the 'filename'
     variable is initialized with its file name.

     This variable cannot be unset.

 -- gdbmtool variable: number fd
     File descriptor of the database file to open.  If this variable is
     set, its value must be an open file descriptor referring to a
     'GDBM' database file.  The 'open' command will use 'gdbm_fd_open'
     function to use this file (*note gdbm_fd_open::).  When this
     database is closed, the descriptor will be closed as well and the
     'fd' variable will be unset.

     See also the '-d' ('--db-descriptor') command line option in *note
     invocation::.

 -- gdbmtool variable: string format
     Defines the format in which new databases will be created.  Allowed
     values are:

     'standard'
          Databases will be created in standard format.  This is the
          format used by all 'GDBM' versions prior to 1.21.  This value
          is the default.

     'numsync'
          Extended format, best for crash-tolerant applications.  *Note
          Numsync::, for a discussion of this format.

 -- gdbmtool variable: string open
     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.

          Technically, this sets the 'GDBM_NEWDB' flag in call to
          'gdbm_open'.  *Note GDBM_NEWDB: Open.
     wrcreat
     rw
          Open the database in read-write mode.  Create it if it does
          not exist.  This is the default.

          Technically speaking, it sets the 'GDBM_WRCREAT' flag in call
          to 'gdbm_open'.  *Note GDBM_WRCREAT: Open.
     reader
     readonly
          Open the database in read-only mode.  Signal an error if it
          does not exist.

          This sets the 'GDBM_READER' flag (*note GDBM_READER: Open.).

     Attempting to set any other value or to unset this variable results
     in error.

 -- gdbmtool variable: number filemode
     File mode (in octal) for creating new database files and database
     dumps.

 -- gdbmtool variable: bool lock
     Lock the database.  This is the default.

     Setting this variable to false or unsetting it results in passing
     'GDBM_NOLOCK' flag to 'gdbm_open' (*note GDBM_NOLOCK: Open.).

 -- gdbmtool variable: bool mmap
     Use memory mapping.  This is the default.

     Setting this variable to false or unsetting it results in passing
     'GDBM_NOMMAP' flag to 'gdbm_open' (*note GDBM_NOMMAP: Open.).

 -- gdbmtool variable: bool sync
     Flush all database writes on disk immediately.  Default is false.
     *Note GDBM_SYNC: Open.

 -- gdbmtool variable: bool coalesce
     Enables the _coalesce_ mode, i.e.  merging of the freed blocks of
     'GDBM' files with entries in available block lists.  This provides
     for effective memory management at the cost of slight increase in
     execution time when calling 'gdbm_delete'.  *Note
     GDBM_SETCOALESCEBLKS: Options.

     This variable affects the currently opened database immediately and
     will be used by 'open' command, when it is invoked.

 -- gdbmtool variable: bool centfree
     Set to 'true', enables the use of central free block pool in newly
     opened databases.  *Note GDBM_SETCENTFREE: Options.

     This variable affects the currently opened database immediately and
     will be used by 'open' command, when it is invoked.

   The following commands are used to list or modify the variables:

 -- command verb: set [ASSIGNMENTS]
     When used without arguments, lists all variables and their values.
     Unset variables are shown after a comment sign ('#').  For string
     and numeric variables, values are shown after an equals sign.  For
     boolean variables, only the variable name is displayed if the
     variable is 'true'.  If it is 'false', its name is prefixed with
     'no'.

     For example:

          # blocksize is unset
          # cachesize is unset
          nocentfree
          nocoalesce
          confirm
          delim1=","
          delim2=","
          # fd is unset
          filemode=644
          filename="junk.gdbm"
          format="standard"
          lock
          mmap
          open="wrcreat"
          pager="less"
          ps1="%p>%_"
          ps2="%_>%_"
          # quiet is unset
          nosync

     If used with arguments, the 'set' command alters the specified
     variables.  In this case, arguments are variable assignments in the
     form 'NAME=VALUE'.  For boolean variables, the VALUE is interpreted
     as follows: if it is numeric, '0' stands for 'false', any non-zero
     value stands for 'true'.  Otherwise, the values 'on', 'true', and
     'yes' denote 'true', and 'off', 'false', 'no' stand for 'false'.
     Alternatively, only the name of a boolean variable can be supplied
     to set it to 'true', and its name prefixed with 'no' can be used to
     set it to false.  For example, the following command sets the
     'delim2' variable to ';' and the 'confirm' variable to 'false':

          set delim2=";" noconfirm

 -- command verb: unset VARIABLES
     Unsets the listed variables.  The effect of unsetting depends on
     the variable.  Unless explicitly described in the discussion of the
     variables above, unsetting a boolean variable is equivalent to
     setting it to 'false'.  Unsetting a string variable is equivalent
     to assigning it an empty string.