.Dd 2015-10-08
.Dt JOIN 1
.Os sbase
.Sh NAME
.Nm join
.Nd relational database operator
.Sh SYNOPSIS
.Nm
.Op Fl 1 Ar field
.Op Fl 2 Ar field
.Op Fl o Ar list
.Op Fl e Ar string
.Op Fl a Ar fileno | Fl v Ar fileno
.Op Fl t Ar delim
.Ar file1 file2
.Sh DESCRIPTION
.Nm
lines from
.Ar file1
and
.Ar file2
on a matching field.
If one of the input files is '-', standard input is read for that file.
.Pp
Files are read sequentially and are assumed to be sorted on the join
field.
.Nm
does not check the order of input, and joining two unsorted files will
produce unexpected output.
.Pp
By default, input lines are matched on the first blank-separated
field; output lines are space-separated and consist of the join field
followed by the remaining fields from
.Ar file1 ,
then the remaining fields from
.Ar file2 .
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl 1 Ar field
Join on the
.Ar field Ns th
field of file 1.
.It Fl 2 Ar field
Join on the
.Ar field Ns th
field of file 2.
.It Fl a Ar fileno
Print unpairable lines from file
.Ar fileno
in addition to normal output.
.It Fl e Ar string
When used with
.Fl o ,
replace empty fields in the output list with
.Ar string .
.It Fl o Ar list
Format output according to the string
.Ar list .
Each element of
.Ar list
may be either
.Ar fileno.field
or 0 (representing the join field).
Elements in
.Ar list
may be separated by blanks or commas.
For example,
.Bd -literal -offset indent
join -o "0 2.1 1.3"
.Ed
.Pp
would print the join field, the first field of
.Ar file2 ,
then the third field of
.Ar file1 .
.Pp
Only paired lines are formatted with the
.Fl o
option.
Unpairable lines (selected with
.Fl a
or
.Fl v )
are printed raw.
.It Fl t Ar delim
Use the arbitrary string
.Ar delim
as field delimiter for both input and output.
.It Fl v Ar fileno
Print unpairable lines from file
.Ar fileno
instead of normal output.
.El
.Sh STANDARDS
The
.Nm
utility is compliant with the
.St -p1003.1-2013
specification with the following exeption:
.Bl -bullet -offset indent
.It
Unpairable lines ignore formatting specified with
.Fl o .
.El
.Pp
The possibility of specifying multibyte delimiters of arbitrary
length is an extension to the specification.