`join`

Relational database operator (POSIX)

Syntax:

join [-a file_number] [-e string] [-jn field] 
     [-o list] [-t char] [-v file_number] [-1 n] [-2 n]
     file1 file2

Options:

Options -a, -j, and -v use the file_number argument. Specify 1 to refer to file1 or 2 to refer to file2.

-1 n

(the number one) Join on the nth field of file1. Fields are numbered, starting with 1.

-2 n

Join on the nth field of file2. Fields are numbered, starting with 1.

-a file_number

In addition to the default output, produce a line for every unpairable line in file file_number. If both -a 1 and -a 2 are specified, both sets of information are output, and information for -a 2 is always printed first.

-e string

Replace empty output fields by the string string.

-jn field

(Obsolescent) Join on the specified field of file n. If n is neither 1 nor 2 (e.g. -j0 3), use the specified field in both files. Fields are numbered starting with 1.

It is preferable to use options -1 and -2 in place of option -jn.

-o list

Produce output in which each line comprises the fields specified in list. Each entry in list has the form:

file_number.field

where field is a field number. Each entry can be separated by a space or a comma.

Output is written only for lines with matching join fields. The join field isn't written unless it's included in list.

-t char

Use the character char as a separator, for both input and output. Every appearance of char in a line is significant. When this option is specified, the collating sequence should be the same as that produced by sort, without the -b option.

-v file_number

Instead of the default output, produce a line only for every unpairable line in file_number.

file1 file2

The names of the text files. If either file1 or file2 is -, the standard input is used.

Description:

The join utility forms a "join" of the two relations specified by the lines of file1 and file2. The join is written to the standard output.

The files file1 and file2 are compared on the basis of a "join field" found in both files. For every pair of lines in file1 and file2 that have identical join fields, join prints one output line. The output line normally consists of the join field, followed by the rest of the line from file1 and then the rest of the line from file2. By default, the join field is the first field in each line.

Both file1 and file2 should be sorted in an increasing collating sequence on their join fields (i.e. the same sequence performed by sort -b). Otherwise, some field matches may not be reported. Note, however, that when option -t is specified, the collating sequence should be the same as that produced by sort, without the -b option.

The default input field separators are blanks. In this case, multiple separators count as one field separator; leading separators are ignored. The default output field separator is a space.

Examples:

Join the password file and group file, matching on the numeric group ID and outputting the login name, group name, and login directory. It's assumed that the files have been sorted in collating sequence on the groupid fields.

    join -1 4 -2 3 -o 1.1 2.1 1.6 -t:  /etc/passwd /etc/group

Exit status:

0: All input files were output successfully.
>0: An error occurred.