join-dctrl(1) General Commands Manual join-dctrl(1)
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 al-
lows 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 fileno, --unpairable-from=fileno
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 sep-
arated 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 spec-
ification 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 log level to level. level is one of fatal, important, infor-
mational 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 de-
fault 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 rela-
tional database table. A file called - represents the program's stan-
dard 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 semistructured single-table database
stored in a machine-parseable text file. Such a database consists of a
set of records; each record is a mapping from field names to field con-
tent. 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 con-
tent. The colon must reside on the first line of the field, and the
first line must start with no whitespace. Subsequent lines, in con-
trast, 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 sec-
tion. 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 com-
pletely 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 squeeze (6.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 di-
rectory does not contain files named stat and pkg. The following com-
mands gives, for each package currently installed and available in De-
bian squeeze (6.0), its currently installed version (as Old-Version) and
the version in squeeze (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
AUTHOR
The join-dctrl program and this manual page were written by Antti-Juhani
Kaijanaho.
SEE ALSO
grep-dctrl(1), sort-dctrl(1), tbl-dctrl(1)
join-dctrl(1)
Generated by dwww version 1.16 on Sat Oct 3 06:00:41 CEST 2026.