1 files changed, 148 insertions, 0 deletions
diff --git a/man/man1/join.1 b/man/man1/join.1
new file mode 100644
index 00000000..379eec7f
--- /dev/null
+++ b/man/man1/join.1
@@ -0,0 +1,148 @@
+.TH JOIN 1
+.CT 1 files
+.SH NAME
+join \- relational database operator
+.SH SYNOPSIS
+.B join
+[
+.I options
+]
+.I file1 file2
+.SH DESCRIPTION
+.I Join
+forms, on the standard output,
+a join
+of the two relations specified by the lines of
+.I file1
+and
+.IR file2 .
+If one of the file names is
+.LR - ,
+the standard input is used.
+.PP
+.I File1
+and
+.I file2
+must be sorted in increasing
+.SM ASCII 
+collating
+sequence on the fields
+on which they are to be joined,
+normally the first in each line.
+.PP
+There is one line in the output
+for each pair of lines in
+.I file1
+and
+.I file2
+that have identical join fields.
+The output line normally consists of the common field,
+then the rest of the line from
+.IR file1 ,
+then the rest of the line from
+.IR file2 .
+.PP
+Input fields are normally separated spaces or tabs;
+output fields by space.
+In this case, multiple separators count as one, and
+leading separators are discarded.
+.PP
+The following options are recognized, with POSIX syntax.
+.TP
+.BI -a " n
+In addition to the normal output,
+produce a line for each unpairable line in file
+.IR n ,
+where
+.I n
+is 1 or 2.
+.TP
+.BI -v " n
+Like
+.BR -a ,
+omitting output for paired lines.
+.TP
+.BI -e " s
+Replace empty output fields by string
+.IR s .
+.TP
+.BI -1 " m
+.br
+.ns
+.TP
+.BI -2 " m
+Join on the
+.IR m th
+field of
+.I file1
+or
+.IR file2 .
+.TP
+.BI -j "n m"
+Archaic equivalent for
+.BI - n " m"\f1.
+.TP
+.BI -o fields
+Each output line comprises the designated fields.
+The comma-separated field designators are either
+.BR 0 ,
+meaning the join field, or have the form
+.IR n . m ,
+where
+.I n
+is a file number and
+.I m
+is a field number.
+Archaic usage allows separate arguments for field designators.
+.PP
+.TP
+.BI -t c
+Use character
+.I c
+as the only separator (tab character) on input and output.
+Every appearance of
+.I c
+in a line is significant.
+.SH EXAMPLES
+.TP
+.L
+sort -t: +1 /adm/users | join -t: -1 2 -a 1 -e "" - bdays
+Add birthdays to the
+.B /adm/users
+file, leaving unknown
+birthdays empty.
+The layout of 
+.B /adm/users
+is given in
+.IR users (6);
+.B bdays
+contains sorted lines like
+.LR "ken:Feb\ 4,\ 1953" .
+.TP
+.L
+tr : ' ' </adm/users | sort -k 3 3 >temp
+.br
+.ns
+.TP
+.L
+join -1 3 -2 3 -o 1.1,2.1 temp temp | awk '$1 < $2'
+Print all pairs of users with identical userids.
+.SH SOURCE
+.B /sys/src/cmd/join.c
+.SH "SEE ALSO"
+.IR sort (1), 
+.IR comm (1), 
+.IR awk (1)
+.SH BUGS
+With default field separation,
+the collating sequence is that of
+.BI "sort -b"
+.BI -k y , y\f1;
+with
+.BR -t ,
+the sequence is that of
+.BI "sort -t" x
+.BI -k y , y\f1.
+.br
+One of the files must be randomly accessible.
+