join(1) General Commands Manual join(1)
join - join files
join [ -a n] [ -e string] [ -j n m] [ -o list] [ -t c] file1 file2
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 terminated 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 char-
acter. Any number of tabs or spaces can separate two fields, and any number of newline 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 demonstrates 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 con-
tain 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 example, 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
LC_COLLATE If this environment variable is set and valid, uses the international language database named in the definition to determine
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 definition supercedes the defini-
tion of LANG.
-a[n] Write lines that contain unmatched join fields to the output 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.
If you specify the option, the command collates the same as with no options.
Suppose that by issuing the following commands, you display the files shown in the example:
% cat file_1
% cat file_2
Both files are sorted in ascending order.
If you issue the command without options, the output appears as follows:
% 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 second 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
feb 05 15
awk(1), comm(1), sort(1), sort5(1), environ(5int)