NAME
join - Joins the lines of two files
SYNOPSIS
Current syntax
join [-anumber] [-e string] [-o number.field ...] [-
tcharacter] [-v file_number] [-1 field] [-2 field]
file1 file2
Obsolescent syntax
join [-anumber] [-e string] [-j][number field] [-o
number.field ...] [-tcharacter]
file1 file2
The join command reads file1 and file2 and joins lines in
the files that contain common fields, or otherwise according
to the flags, and writes the results to standard output.
FLAGS
-1 field
Joins on the fieldth field of file1. Fields are decimal
integers starting with 1.
-2 field
Joins on the fieldth field of file2. Fields are decimal
integers starting with 1.
-anumber
Produces an output line for each line found in file1 if
number is 1, or file2 if number is 2. Without -a, join
produces output only for lines containing a common
field. If the number argument is omitted, join simply
merges the contents of the two files. An output line is
thus produced for each line in both files.
-e string
Replaces empty output fields with string.
-j[number] field
Joins the two files on field of file number, where
number is 1 for file1 or 2 for file2. If you do not
specify number, join uses field in each file. Without
-j, join uses the first field in each file. (Obsoles-
cent)
-o file.field ...
Produces output lines consisting of the fields specified
in one or more number.field arguments, where number is 1
for file1 or 2 for file2, and field is a field number.
-tcharacter
Uses character (a single character) as the field separa-
tor character in the input and the output. Every
appearance of character in a line is significant. The
default separator is a space. If you do not specify -t,
join also recognizes the tab and newline characters as
separators.
-v file_number
Produces an output line for each unpairable line in
file_number (where file_number is 1 or 2), instead of
the default output. If both -v 1 and -v 2 are speci-
fied, produces output lines for all unpairable lines.
With default field separation, the collating sequence is
that of sort -b. If you specify -t, the sequence is
that of a plain sort. To specify a tab character,
enclose it in ' ' (single quotes).
DESCRIPTION
The join field is the field in the input files that join
looks at to determine what will be included in the output.
One line appears in the output for each identical join field
appearing in both file1 and file2. The output line consists
of the join field, the rest of the line from file1, then the
rest of the line from file2.
You can specify standard input in place of file1 or file2 by
substituting a - (dash) for the name.
Both input files must be sorted according to the collating
sequence specified by the LC_COLLATE environment variable,
if set, for the fields on which they are to be joined (usu-
ally the first field in each line).
Fields are normally separated by a space, a tab character,
or a newline character. In this case, join treats consecu-
tive separators as one, and discards leading separators.
Use the -t flag to specify another field separator.
EXAMPLES
Note that the vertical alignment shown in these examples may
not be consistent with your output.
1. To perform a simple join operation on two files,
phonedir and names, whose first fields are the same,
enter:
join phonedir names
If phonedir contains the following telephone directory:
Binst 555-6235
Dickerson 555-1842
Eisner 555-1234
Green 555-2240
Hrarii 555-0256
Janatha 555-7358
Lewis 555-3237
Takata 555-5341
Wozni 555-1234
and names is this listing of names and department
numbers:
Eisner Dept. 389
Frost Dept. 217
Green Dept. 311
Takata Dept. 454
Wozni Dept. 520
then join phonedir names displays:
Eisner 555-1234 Dept. 389
Green 555-2240 Dept. 311
Takata 555-5341 Dept. 454
Wozni 555-1234 Dept. 520
Each line consists of the join field (the last name),
followed by the rest of the line found in phonedir and
the rest of the line in names.
2. To display unmatched lines as well as matched line,
enter:
join -a2 phonedir names
If phonedir contains:
Binst 555-6235
Dickerson 555-1842
Eisner 555-1234
Green 555-2240
Hrarii 555-0256
Janatha 555-7358
Lewis 555-3237
Takata 555-5341
Wozni 555-1234
and names contains:
Eisner Dept. 389
Frost Dept. 217
Green Dept. 311
Takata Dept. 454
Wozni Dept. 520
then join -a2 phonedir names displays:
Eisner 555-1234 Dept. 389
Frost Dept. 217
Green 555-2240 Dept. 311
Takata 555-5341 Dept. 454
Wozni 555-1234 Dept. 520
This performs the same join operation as in the first
example, and also lists the lines of names that have no
match in phonedir. It includes Frost's name and
department number in the listing, although there is no
entry for Frost in phonedir.
3. To display selected fields, enter:
join -o 2.3 2.1 1.2 phonedir names
This displays the following fields:
Field 3 of names (Department Number)
Field 1 of names (Last Name)
Field 2 of phonedir (Telephone Number)
If phonedir contains:
Binst 555-6235
Dickerson 555-1842
Eisner 555-1234
Green 555-2240
Hrarii 555-0256
Janatha 555-7358
Lewis 555-3237
Takata 555-5341
Wozni 555-1234
and names contains:
Eisner Dept. 389
Frost Dept. 217
Green Dept. 311
Takata Dept. 454
Wozni Dept. 520
then join -o 2.3 2.1 1.2 phonedir names displays:
389 Eisner 555-1234
311 Green 555-2240
454 Takata 555-5341
520 Wozni 555-1234
4. To perform the join operation on a field other than the
first, enter:
sort -b +1 -2 phonedir | join -1 2 - numbers
This combines the lines in phonedir and names, compar-
ing the second field of phonedir to the first field of
numbers.
First, this sorts phonedir by the second field because
both files must be sorted by their join fields. The
output of sort is then piped to join. The - (dash) by
itself causes the join command to use this output as
its first file. -1 2 defines the second field of the
sorted phonedir as the join field. This is compared to
the first field of numbers because its join field is
not specified with a -2 flag.
If phonedir contains:
Binst 555-6235
Dickerson 555-1842
Eisner 555-1234
Green 555-2240
Hrarii 555-0256
Janatha 555-7358
Lewis 555-3237
Takata 555-5341
Wozni 555-1234
and numbers contains:
555-0256
555-1234
555-5555
555-7358
then sort ... | join ... displays:
555-0256 Hrarii
555-1234 Eisner
555-1234 Wozni
555-7358 Janatha
Each number in numbers is listed with the name listed
in phonedir for that number. Note that join lists all
the matches for a given field. In this case, join
lists both Eisner and Wozni as having the telephone
number 555-1234. The number 555-5555 is not listed
because it does not appear in phonedir.
RELATED INFORMATION
Commands: awk(1), comm(1), cut(1), paste(1), sort(1),
uniq(1).
"Using Internationalization Features" in the OSF/1 User's
Guide.
Acknowledgement and Disclaimer