constant database multitool
ezcdb(1)                             ezcdb                            ezcdb(1)



NAME
       ezcdb - constant database (cdb) multitool

SYNOPSIS
       ezcdb [-hV] command opts args

       ezcdb cross [-h] [-p perms ] [-t tmpfile ] result.cdb A.cdb B.cdb
       ezcdb dump [-h] [-d del | -g | -x] [ cdb ]
       ezcdb dupes [-h] [-d del | -g | -x] [-q] [ cdb ]
       ezcdb get [-h] [-a | -j num ] [-n] key [ cdb ]
       ezcdb grep [-h] [-d del | -g | -x] [-i] [-k] [-!]  regex [ cdb ]
       ezcdb keys [-h] [-g | -x] [-X] [ cdb ]
       ezcdb make [-h] [-d del | -g | -x] [-p perms ] [-t tmpfile ] cdb
       ezcdb match [-h] [-d del | -g | -x] [-i] [-k] [-!]  pattern [ cdb ]
       ezcdb merge [-h] [-p perms ] [-t tmpfile ] [-a] result.cdb A.cdb B.cdb
       ezcdb purge [-h] [-p perms ] [-t tmpfile ] result.cdb A.cdb B.cdb
       ezcdb stats [-h] [-v] [ cdb ]

DESCRIPTION
       ezcdb  is  used  to  generate,  query, analyze, and operate on constant
       database files in cdb(5) format.  The  following  operations  are  sup-
       ported:

   cross
       ezcdb cross performs a set intersect operation with A.cdb and B.cdb and
       compiles the result in result.cdb.  The cross operation selects records
       in  A  with matching keys in B.  The record sequence in result.cdb pre-
       serves the original sequence among records in A.  Any/all of the  named
       argument files may ``overlap''.  Options:

       -p perms
              Permissions.   Set  the file creation permissions for result.cdb
              as explicitly given in the octal argument perms.  Otherwise, the
              result.cdb  file  permissions will be set to mode 0666 and modi-
              fied by the process umask.

       -t tmpfile
              Tempfile.  Use the path specified by the  argument  tmpfile  for
              the temporary file used during the creation of result.cdb.  Nor-
              mally the temporary file name is constructed from the result.cdb
              argument as result.cdb.{new}.

   dump
       ezcdb  dump lists to stdout all records found in the given cdb file (or
       seekable input on stdin).  Output format is under  control  of  options
       and described in the FORMATS section.  Options:

       -d del Delimiter.   Output  records  in  ``getline''  format, using the
              first character in the argument del as separator between the key
              and value parts of the record.  Implies -g.

       -g     Getline.  Output records in ``getline'' format.

       -x     Exchange.  Output records in ``exchange'' format.

   dupes
       ezcdb  dupes  lists  to stdout all records with duplicate keys found in
       the given cdb file (or seekable input on  stdin),  and  prints  summary
       report  to  stderr.   Because the dupes command sequentially scans each
       record and hash value in the file, it may also be used to validate  the
       integrity  of  the database.  Output format is under control of options
       and described in the FORMATS section.  Options:

       -d del Delimiter.  Output records  in  ``getline''  format,  using  the
              first character in the argument del as separator between the key
              and value parts of the record.  Implies -g.

       -g     Getline.  Output records in ``getline'' format.

       -x     Exchange.  Output records in ``exchange'' format.

       -q     Quick/quiet.   Suppress  any  output  and   summary   reporting.
              Short-circuit  scan  and return exit status 1 on first duplicate
              key found in cdb.  Otherwise, return exit status 0 for no dupli-
              cates found.

   get
       ezcdb  get  looks  up  key  in cdb (or seekable input on stdin) and, if
       found, writes the associated record value to  stdout.   Exits  zero  if
       lookup is successful.  Exits non-zero (1) if key not found.  Options:

       -a     All.   Write  all record values with matching key.  A newline is
              appended to each record value output.  Normally, only the  first
              record matching key is output.

       -j num Jump.   Skip  the  first  num matches for key before writing the
              num+1 matching record value, if any.

       -n     Newline suppressed.  Write only the record value without append-
              ing  a  newline.  Normally, a newline is appended to each record
              in the output.

   grep
       ezcdb grep lists to stdout all records found in the given cdb file  (or
       seekable  input  on  stdin)  matching the re_format(7) extended regular
       expression given in regex.  Note that the regex argument may need to be
       quoted  to  inhibit  unwanted expansion by the shell.  Output format is
       under control of options and described in the FORMATS  section.   Exits
       zero  if  one  or  more  matches found.  Exits non-zero (1) if no match
       found.  Options:

       -d del Delimiter.  Output records  in  ``getline''  format,  using  the
              first character in the argument del as separator between the key
              and value parts of the record.  Implies -g.

       -g     Getline.  Output records in ``getline'' format.

       -x     Exchange.  Output records in ``exchange'' format.

       -i     Case insensitive.  Perform case insensitive matching.   Normally
              the  regular  expression  is  matched explicitly with respect to
              case.

       -k     Key match.  Perform  the  regular  expression  matching  against
              record keys.  Normally the regular expression is matched against
              record values.

       -!     Invert (logical not).  Select and output the records that do not
              match  the  given  regular  expression.   Normally  the matching
              records are output.

   keys
       ezcdb keys lists to stdout all keys found in the  given  cdb  file  (or
       seekable  input  on  stdin).  Output format is under control of options
       and modified slightly from the descriptions in the FORMATS section.  By
       default, keys are listed in a modified default format:

           +klen:key\n

       An empty line terminates the default output sequence.  Options:

       -g     Getline.  Output keys listed in a modified ``getline'' format:
                   key\n

       -x     Exchange.  Output keys listed in a modified ``exchange'' format:
                   klen:key\n

       -X     Hash (hexadecimal).  Following each key, display the hash  value
              computed for the key in hexadecimal format.

   make
       ezcdb  make  generates  the  cdb  file cdb from formatted input read on
       stdin.  Input format is under control of options and described  in  the
       FORMATS section.  Options:

       -d del Delimiter.  Input records in ``getline'' format, using the first
              character in the argument del as separator between the  key  and
              value parts of the record.  Implies -g.

       -g     Getline.  Input records in ``getline'' format.

       -x     Exchange.  Input records in ``exchange'' format.

       -p perms
              Permissions.   Set  the  file  creation  permissions  for cdb as
              explicitly given in the octal argument  perms.   Otherwise,  the
              cdb  file  permissions  will be set to mode 0666 and modified by
              the process umask.

       -t tmpfile
              Tempfile.  Use the path specified by the  argument  tmpfile  for
              the  temporary  file  used during the creation of cdb.  Normally
              the temporary file name is constructed from the cdb argument  as
              cdb.{new}.

   match
       ezcdb match lists to stdout all records found in the given cdb file (or
       seekable input on stdin) matching the simple wildcard expression  given
       in  pattern.   A pattern is a character string composed in any combina-
       tion of:

              o   any character (excepting `?' and `*'), matched explicitly

              o   the `?' (question-mark) character, matching any single char-
                  acter

              o   the  `*' (asterisk) character, matching any sequence of zero
                  or more characters

       Note that the pattern expression argument is a simplified subset of the
       sh(1)  globbing  rules provided by fnmatch(3), and does not provide for
       range expressions or escaping of metacharacters.  (The ezcdb grep  com-
       mand  may  be used whenever more sophisticated pattern matching expres-
       sions are required.)

       Note also that the pattern argument may need to be  quoted  to  inhibit
       unwanted  expansion  by  the  shell.  Output format is under control of
       options and described in the FORMATS section.  Exits  zero  if  one  or
       more matches found.  Exits non-zero (1) if no match found.  Options:

       -d del Delimiter.   Output  records  in  ``getline''  format, using the
              first character in the argument del as separator between the key
              and value parts of the record.  Implies -g.

       -g     Getline.  Output records in ``getline'' format.

       -x     Exchange.  Output records in ``exchange'' format.

       -i     Case  insensitive.  Perform case insensitive matching.  Normally
              the wildcard expression is matched explicitly  with  respect  to
              case.

       -k     Key  match.   Perform the wildcard matching against record keys.
              Normally the wildcard expression is matched against record  val-
              ues.

       -!     Invert (logical not).  Select and output the records that do not
              match the given  wildcard  expression.   Normally  the  matching
              records are output.

   merge
       ezcdb  merge  performs  a  set union operation with A.cdb and B.cdb and
       compiles the result in result.cdb.  The merge  operation  combines  all
       records in A and B, excluding by default any records in A with matching
       keys in B.  Note that the -a option may be used  for  a  ``union  all''
       operation.  The record sequence in result.cdb includes A records before
       B records, and original sequence is preserved among records in A and B.
       Any/all of the named argument files may ``overlap''.  Options:

       -p perms
              Permissions.   Set  the file creation permissions for result.cdb
              as explicitly given in the octal argument perms.  Otherwise, the
              result.cdb  file  permissions will be set to mode 0666 and modi-
              fied by the process umask.

       -t tmpfile
              Tempfile.  Use the path specified by the  argument  tmpfile  for
              the temporary file used during the creation of result.cdb.  Nor-
              mally the temporary file name is constructed from the result.cdb
              argument as result.cdb.{new}.

       -a     All.  Merge all records from A and B, not excluding any matching
              keys.  Normally any records in A with matching  keys  in  B  are
              excluded.

   purge
       ezcdb  purge  performs  a  set minus (exclude) operation with A.cdb and
       B.cdb and compiles the  result  in  result.cdb.   The  purge  operation
       selects  only  records  in  A  without  matching keys in B.  The record
       sequence in result.cdb preserves the original sequence among records in
       A.  Any/all of the named argument files may ``overlap''.  Options:

       -p perms
              Permissions.   Set  the file creation permissions for result.cdb
              as explicitly given in the octal argument perms.  Otherwise, the
              result.cdb  file  permissions will be set to mode 0666 and modi-
              fied by the process umask.

       -t tmpfile
              Tempfile.  Use the path specified by the  argument  tmpfile  for
              the temporary file used during the creation of result.cdb.  Nor-
              mally the temporary file name is constructed from the result.cdb
              argument as result.cdb.{new}.

   stats
       ezcdb  stats scans the cdb file (or seekable input on stdin) and prints
       some summary statistics to stdout.  Options:

       -v     Verbose.  Some additional information is included  in  the  sum-
              mary.

FORMATS
       The  ezcdb  utility accepts the following formats for record input/out-
       put:

   default
       The default record format follows the  original  cdbmake  specification
       and is described as:

           +klen,dlen:key->data\n

       Where:  klen and dlen are the key length and data length, respectively,
       in decimal ascii notation; key and data  are  any  arbitrary  character
       sequences  for  the record key and data; each record begins with a lit-
       eral `+' character; each record ends with a newline; and the `,',  `:',
       and  `->'  separators are literal characters.  A sequence of records is
       terminated by a final empty line.

   getline [-g]
       The ``getline'' record format is selected with the  -g  option  and  is
       described as:

           key\tdata\n

       Where:  key  and  data are any arbitrary character sequences (excepting
       nul and newline) for the record key and data; separated by default with
       a  single  tab character; and each record is terminated with a newline.
       The separator must itself not appear within any  key,  but  may  appear
       within  data.   An alternative separator character between key and data
       may be specified by the first character in the del argument to  the  -d
       option.   Lines beginning with a `#' character are ignored.  A sequence
       of records is terminated by eof.  Note that this  format  will  not  be
       usable  in cases wh