join(1) 						      General Commands Manual							   join(1)

Name
       join - join files

Syntax
       join [ -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 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
       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 definition supercedes the defini-
		      tion 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, 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 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

See Also
       awk(1), comm(1), sort(1), sort5(1), environ(5int)

																	   join(1)