10564b1175
groff 1.23.0 added .MR to its -man macro package. The NEWS file states
that the inclusion of the macro "was prompted by its introduction to
Plan 9 from User Space's troff in August 2020." From d32deab it seems
that the name for Plan 9 from User Space's implementation was suggested
by groff maintainer G. Brandon Robinson.
Not sure if the intention was to make these definitions compatible, but
it would be nice if they were.
Currently, Plan 9 from User Space's .MR expects its second argument to
be parenthesized. groff's .MR does not. This results in extra
parentheses appearing in manual references when viewing Plan 9 from User
Space's manual pages on a system using groff.
148 lines
2.5 KiB
Groff
148 lines
2.5 KiB
Groff
.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 /etc/passwd | join -t: -1 1 -a 1 -e "" - bdays
|
|
Add birthdays to the
|
|
.B /etc/passwd
|
|
file, leaving unknown
|
|
birthdays empty.
|
|
The layout of
|
|
.B /adm/users
|
|
is given in
|
|
.MR passwd 5 ;
|
|
.B bdays
|
|
contains sorted lines like
|
|
.LR "ken:Feb\ 4,\ 1953" .
|
|
.TP
|
|
.L
|
|
tr : ' ' </etc/passwd | 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 \*9/src/cmd/join.c
|
|
.SH "SEE ALSO"
|
|
.IR sort (1),
|
|
.IR comm (1),
|
|
.MR 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.
|
|
.PP
|
|
One of the files must be randomly accessible.
|