join(1)join(1)Namejoin - join files
Syntaxjoin [ -a n] [ -e string] [ -j n m] [ -o list] [ -t c] file1 file2
Description
The command compares a field in file1 to a field in file2. If the two
fields match, the command combines the line in file1 that contains the
field with the line in file2 that contains the field. The command
writes its output to standard output. If you specify a hyphen (-) in
the file1 argument, compares standard input to the contents of file2.
The command compares and combines the input files one line at a time.
Each line in the input file contains one field that uses to determine
if two lines should be joined. This field is called the join field. By
default, the command uses the first field in each line as the join
field. The command compares the join field in the first line of file1
to the join field in the first line of file2. If the two fields match,
the command joins the lines. The command then compares the join fields
in the second line of both files, and so on.
In the input files, fields are separated by tab or space characters.
The command reads data from the first field until it encounters a tab
or space character, which terminates the first field. By default, the
command ignores tab and space characters, so the next character that is
not a tab or space begins the second field. The second field is termi‐
nated by the tab or space that follows it, and the third field begins
with the next character that is not a tab or space. The command reads
fields in this way until it encounters a new line character. Any num‐
ber of tabs or spaces can separate two fields, and any number of new‐
line characters can separate two lines.
Both file1 and file2 must be ordered in the collating sequence of the
command on the fields that the two files are to be joined. By default,
uses the first field in each line and collates the same as
To create output, the command writes the join field, followed by the
remaining fields in the line from file1, followed by the remaining
fields in the line from file2 to the output file. The following demon‐
strates how lines in the output appear by default:
join_field file1.field2 file1.field3 file1.field4 file2.field2 file2.field3
By default, the command ignores lines that do not contain identical
join fields. The command writes no output for these lines.
You can change how creates output using command options. For example,
you can cause the command to write output for lines that do not contain
identical join fields. You can also specify a list using the option.
In list, you supply a list of specifiers in the form file.field, where
file is either 1 or 2 and field is the number of the field. For exam‐
ple, 1.2 specifies the second field in the first file and 2.4 specifies
the fourth field in the second file. The following demonstrates how
lines in the output appear if you use these two specifiers:
file1.field2 field2.field4
International Environment
LC_COLLATE If this environment variable is set and valid, uses the
international language database named in the definition
to determine collation rules.
LC_CTYPE If this environment variable is set and valid, uses the
international language database named in the definition
to determine character classification rules.
LANG If this environment variable is set and valid uses the
international language database named in the definition
to determine collation and character classification
rules. If LC_COLLATE or LC_CTYPE is defined their defi‐
nition supercedes the definition of LANG.
Options
-a[n] Write lines that contain unmatched join fields to the out‐
put file. You can cause the command to write unmatched
lines from only one file using n. If you specify 1 in n,
writes unmatched lines only from file 1. If you specify 2,
writes unmatched lines only from file 2.
If you omit the option, writes no output for unmatched
lines.
-e s Writes the string you specify in s to the output if you
specify a nonexistent field in the list for the option.
For example, if lines in file 2 contain only three fields,
and you specify 2.4 in list, writes s in place of the
nonexistent field.
-jn m Defines field m in file n to be the join field. The command
compares the field you specify in the option to the default
join field in the other file. If you omit n, the command
uses the mth field in both files.
-1 m Use the m th field in the first file as the join field.
This option is equivalent to using m.
-2 m Use the m field in the second file as the join field. This
option is equivalent to using m.
-o list Output the joined data according to list. The specifiers
in list have the format file.field, where file is either 1
or 2 and field is the number of the field.
-tc Recognize the tab character c. The presence of c in a line
is significant, both for comparing join fields and creating
output.
Restrictions
If you specify the option, the command collates the same as with no
options.
Examples
Suppose that by issuing the following commands, you display the files
shown in the example:
% cat file_1
apr 15
aug 20
dec 18
feb 05
% cat file_2
apr 06
aug 14
date
feb 15
Both files are sorted in ascending order.
If you issue the command without options, the output appears as fol‐
lows:
% join file_1 file_2
apr 15 06
aug 20 14
feb 05 15
The third line in each input file is not joined in the output because
the join fields (date and dec) do not match.
To join the lines in these files and format the output so that the sec‐
ond field from each file appears first and the first (join) field
appears second, issue the following command:
% join-o 1.2 1.1 2.2 2.1 file_1 file_2
15 apr 06 apr
20 aug 14 aug
05 feb 15 feb
To write lines that are unmatched to the output, issue the following
command:
% join-a file_1 file_2
apr 15 06
aug 20 14
date
dec 18
feb 05 15
See Alsoawk(1), comm(1), sort(1), sort5(1), environ(5int)join(1)
