JOIN(1)

NAME
join - relational database operator

SYNOPSIS
join [ -an ] [ -e string ] [ -j [1|2] m ] [ -o list ] [ -tc ]
filename1 filename2

DESCRIPTION
join forms, on the standard output, a join of the two relations specified by the lines of filename1 and filename2. If filename1 is `-', the standard input is used.

filename1 and filename2 must be sorted in increasing ASCII collating sequence on the fields on which they are to be joined — normally the first in each line.

There is one line in the output for each pair of lines in filename1 and filename2 that have identical join fields. The output line normally consists of the common field, then the rest of the line from filename1, then the rest of the line from filename2.

The default input field separators are SPACE, TAB, and NEWLINE characters. If the default input field separators are used, multiple separators count as one field separator, and leading separators are ignored. The default output field separator is a blank.

OPTIONS

-an The parameter n can be one of the values:
    1   Produce a line for each unpairable line in filename1.
    2   Produce a line for each unpairable line in filename2.
    3   Produce a line for each unpairable line in both filename1 and filename2.

    The normal output is also produced.

-e string
    Replace empty output fields by string.

-j[1|2]m
    The j may be immediately followed by n, which is either a 1 or a 2. If n is missing, the join is on the m'th field of both files. If n is present, the join is on the m'th field of file n, and the first field of the other. Note: join counts fields from 1 instead of 0 as sort(1V) does.

-o list
    Each output line comprises the fields specified in list, each element of which has the form n.m, where n is a file number and m is a field number. The common field is not printed unless specifically requested. Note: join counts fields from 1 instead of 0 like sort does.

-tc Use character c as a separator (tab character). Every appearance of c in a line is significant. The character c is used as the field separator for both input and output.

EXAMPLE
The following command line will join the password file and the group file, matching on the numeric group ID, and outputting the login name, the group name and the login directory. It is assumed that the files have been sorted in ASCII collating sequence on the group ID fields.

    join -j1 4 -j2 3 -o 1.1 2.1 1.6 -t: /etc/passwd /etc/group

SEE ALSO
awk(1), comm(1), look(1), sort(1V), uniq(1)

BUGS
With default field separation, the collating sequence is that of sort -b; with -t, the sequence is that of a plain sort.

The conventions of join, sort, comm, uniq, look, and awk are wildly incongruous.

Filenames that are numeric may cause conflict when the -o option is used right before listing filenames.