join(1)
Name
join − join files
Syntax
join [ −a n] [ −e string] [ −j n m] [ −o list] [ −t c] file1 file2
Description
The join command compares a field in file1 to a field in file2. If the two fields match, the join 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, join compares standard input to the contents of file2.
The join command compares and combines the input files one line at a time. Each line in the input file contains one field that join uses to determine if two lines should be joined. This field is called the join field. By default, the join 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 join 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 join command reads fields in this way until it encounters a new line character. 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 sort−b command on the fields that the two files are to be joined. By default, join uses the first field in each line and collates the same as sort −b.
To create output, the join 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 join command ignores lines that do not contain identical join fields. The command writes no output for these lines.
You can change how join 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 −o 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 specifiers:
file1.field2 field2.field4
International Environment
LC_COLLATEIf this environment variable is set and valid, join uses the international language database named in the definition to determine collation rules.
LC_CTYPEIf this environment variable is set and valid, join uses the international language database named in the definition to determine character classification rules.
LANGIf this environment variable is set and valid join 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 definition of LANG.
Options
−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, join writes unmatched lines only from file 1. If you specify 2, join writes unmatched lines only from file 2.
If you omit the −a option, join writes no output for unmatched lines.
−e sWrites the string you specify in s to the output if you specify a nonexistent field in the list for the −o option. For example, if lines in file 2 contain only three fields, and you specify 2.4 in list, join writes s in place of the nonexistent field.
−jn mDefines field m in file n to be the join field. The join command compares the field you specify in the −j option to the default join field in the other file. If you omit n, the join command uses the mth field in both files.
−1 mUse the m th field in the first file as the join field. This option is equivalent to using −j1 m.
−2 mUse the m field in the second file as the join field. This option is equivalent to using −j2 m.
−o listOutput 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.
−tcRecognize 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 −t option, the join command collates the same as sort with no options.
Examples
Suppose that by issuing the following cat 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 join 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
date
dec 18
feb 05 15