Man Linux: Main Page and Category List

NAME

       join-dctrl - perform relational join on data in dctrl format

SYNOPSIS

       join-dctrl [ options ] filename filename

       join-dctrl --version

       join-dctrl --help

DESCRIPTION

       join-dctrl  performs a relational join operation on data given to it in
       Debian control file format.

       A join field must be specified using either the switches -1 and  -2  or
       the  switch -j.  Conceptually, the program creates all ordered pairs of
       records that can be formed by having a record from the  first  file  as
       the  first  member of the pair and having a record from the second file
       as the second member of the pair; and then it deletes  all  such  pairs
       where  the  join  fields are not equal.  Effectively, each of the input
       files is treated as a relational database table.

       Every input file must be in ascending order on  its  join  field;  this
       allows the program to work fast.  The sort-dctrl(1) program can be used
       to make it so.

OPTIONS

       -1 FIELD, --1st-join-field=FIELD
              Specify the join field of the first input file.

       -2 FIELD, --2nd-join-field=FIELD
              Specify the join field of the second input file.

       -j FIELD, --join-field=FIELD
              Specify a common join field for all files.

       -a FIELDNO,--unpairable-from=FIELDNO
              Specify that unmatched paragraphs from the first (if 1 is given)
              or the second (if 2 is given) file are printed.

       -o FIELDSPEC, --output-fields=FIELDSPEC
              Specify  which  fields  are  included in the output.  Fields are
              separated by commas (more than one -o option can be used,  too).
              Each  field  is  specified  in  the format fileno.field in which
              fileno is the ordinal number of the input file  from  which  the
              field  is drawn (either 1 or 2), and field gives the name of the
              field to use.  As a special case, simple 0 can be  used  instead
              of fileno.field to refer to the common value of the join fields.

              The name of the field (not including the file number) is used in
              the  output as the name of the field.  However, a different name
              for output purposes can be  specified  by  suffixing  the  field
              specification by a colon and the preferred visible name.

              For  example,  the  option  -o 0,1.Version:Old-Version,2.Version
              specifies that the first field in any output  record  should  be
              the  join  field, the second field should be Old-Version drawing
              its data from the Version field of the first input file, and the
              third  field  should  be Version drawing its data from the field
              with the same name in the second input file, and these  are  the
              only fields in an output record.

              If  no  -o  option is given, all fields of all the records being
              joined are included in the output.

       -l LEVEL, --errorlevel=LEVEL
              Set  debugging  level  to  LEVEL.   LEVEL  is  one  of  "fatal",
              "important",  "informational"  and "debug", but the last may not
              be available, depending  on  the  compile-time  options.   These
              categories  are  given  here  in  order;  every  message that is
              emitted when "fatal" is  in  effect,  will  be  emitted  in  the
              "important" error level, and so on.  The default is "important".

       -V, --version
              Print out version information.

       -C, --copying
              Print out the copyright license.  This produces much output;  be
              sure  to  redirect  or pipe it somewhere (such as your favourite
              pager).

       -h, --help
              Print out a help summary.

OPERANDS

       join-dctrl will treat  each  file  named  on  the  command  line  as  a
       relational  database  table.   A file called - represents the program’s
       standard input stream.  Currently, exactly two files must be named.

STDIN

       The standard input stream may be used as input as  specified  above  in
       the OPERANDS section.

INPUT FILES

       All input to join-dctrl is in the format of a Debian control file.

       A  Debian  control  (dctrl)  file is a single table of a semistructured
       database stored  in  a  machine-parseable  text  file.   Such  a  table
       consists of a set of records; each record is a mapping from field names
       to field content.  Textually, records are  separated  by  empty  lines,
       while  each  field  is  encoded  as one or more nonempty lines inside a
       record.  A field starts with its name, followed by a colon, followed by
       the  field  content.   The  colon  must reside on the first line of the
       field, and the first line must start with  no  whitespace.   Subsequent
       lines,  in  contrast,  always start with linear whitespace (one or more
       space or tab characters).

       Each input file must be in the ascending order of its join field.

ENVIRONMENT VARIABLES

       The  standard  locale  environment,  specifically  its  character   set
       setting,  affects  the  interpretation of input and output as character
       streams.

ASYNCHRONOUS EVENTS

       Standard Unix signals have their usual meaning.

STDOUT

       All output is sent to the standard output stream.  The output is in the
       format  of  a  Debian  control file, described above in the INPUT FILES
       section.  The output will be in the ascending order of the join  field,
       if that field is included in the output.

OUTPUT FILES

       There are no output files.

EXIT STATUS

       This utility exits with 0 when successful.  It uses a nonzero exit code
       inconsistently when an error is noticed (this is a bug).

CONSEQUENCES OF ERRORS

       In case of errors in  the  input,  the  output  will  be  partially  or
       completely  garbage.  In case of errors in invocation, the program will
       refuse to function.

EXAMPLES

       Suppose that a file containing data about binary packages for the AMD64
       architecture  contained in the Debian etch (4.0) release, section main,
       is in the current directory and named Packages.  Suppose  that  we  are
       currently  on  a  Debian  system.   Suppose  further  that  the current
       directory does not contain files named stat  and  pkg.   The  following
       commands  gives,  for each package currently installed and available in
       Debian etch (4.0), its currently installed version (as Old-Version) and
       the version in etch (as New-Version):
       $ sort-dctrl -kPackage /var/lib/dpkg/status > stat
       $ sort-dctrl -kPackage Packages > pkg
       $ join-dctrl -j Package \
         -o 0,1.Version:Old-Version,2.Version:New-Version \
         stat pkg

SEE ALSO

       grep-dctrl(1), sort-dctrl(1), tbl-dctrl(1)

AUTHOR

       The  join-dctrl  program  and  this  manual page were written by Antti-
       Juhani Kaijanaho.

                                                                 join-dctrl(1)