.TH join "" "" Command
.PC "Join two data bases"
\fBjoin [\-a [\fIn\fB] ] [\-e \fIstring \fB] [\-j[\fIn\fB] \fIkeyf\fB]\fR \fB[\-o \fIn.m ...\fB] [\-t\fIc\fB] \fIfile1 file2\fR
.PP
.HS
.SH Options:
.IC \fB\-a[\fIn\fB]\fR
Print unpaired records from file \fIn\fR
.IC "\fB\-e\fI s\fR"
Replace empty fields on output with string \fIs\fR
.IC "\fB\-j[\fIn\fB]\fI key\fR"
Use \fIkey\fR of file \fIn\fR for comparison
.IC "\fB\-o [\fIn.\fB]\fIm ..\fR"
Subsequent arguments list fields to output;
each has file \fIn\fR and field number \fIm\fR
.IC \fB\-t\fIc\fR
Field separator is character \fIc\fR
.Pp
If either \fIfile1\fR or \fIfile2\fR is `-', stdin is used.
The optional file \fIn\fR may be either 1 or 2;
if omitted, both 1 and 2 are assumed.
.HE
.B join
processes the text files
.I file1
and
.IR file2 ,
each of which contains a relational data base.
If either file name is `\-', the standard input is used for that file.
.PP
For the purposes of
.BR join ,
a data base file contains a set of records, one per input line.
Each record contains a number of
.I fields.
One field is differentiated as
.I key
field for each file.
Each file must be sorted by key field, for example with
.BR sort .
.PP
By default, the key field is the first field in each record.
The
.B \-j
option changes the key field number to
.I keyf
for the desired file.
In this and other options below, the optional file number
.I n
must be
.B 1
to indicate
.I file1
or
.B 2
to indicate
.IR file2 .
If no
.I n
is given, both
.I file1
and
.I file2
are assumed.
.PP
Normally,
fields are separated by any amount of white space (blanks or tabs).
Leading blanks or tabs are not considered part of the fields.
With the
.B \-t
option,
the separator character is
.IR c .
With this option zero-length fields are possible;
every occurrence of the separator
ends the previous field and starts a new one.
.PP
Output consists only of records for which the key field
occurs in both files.
As a consequence of the sorted order of the input,
the output is also sorted by the key field.
Each output record has first the key field,
then each field from the
.I file1
record but the key field,
and then each field from the
.I file2
record but the key field.
Fields are separated in the output
with the specified field character,
or with a space character if no
.B \-t
option was given.
Output records are always terminated with a newline.
Under the
.B \-e
option,
.I string
is printed for each empty field.
.PP
The
.B \-a
option enables printing of records found in only file
.IR n .
If
.I n
is missing, unpaired records are printed from both input files.
To output only certain fields, the
.B \-o
option precedes a list of desired fields to print.
Each element is of the form
.I n.m
where
.I n
is the file number and
.I m
is the field number.
.PP
For example,
.DM
	join \-t: \-j1 3 \-o 1.3 2.4 1.4 1.1 2.2 filea fileb
.DE
.PP
joins
.B filea
and
.B fileb
which have fields separated by the colon (`:') character.
The join field number is 3 for
.B filea
and 1 (by default) for
.B fileb.
The selected five fields are produced in the output.
.SH "See Also"
.Xr "awk," awk
.Xr "comm," comm
.Xr "commands," commands
.Xr "sort," sort
.Xr "uniq" uniq
