join.1 (2202B)
1 .Dd 2015-10-08 2 .Dt JOIN 1 3 .Os sbase 4 .Sh NAME 5 .Nm join 6 .Nd relational database operator 7 .Sh SYNOPSIS 8 .Nm 9 .Op Fl 1 Ar field 10 .Op Fl 2 Ar field 11 .Op Fl o Ar list 12 .Op Fl e Ar string 13 .Op Fl a Ar fileno | Fl v Ar fileno 14 .Op Fl t Ar delim 15 .Ar file1 file2 16 .Sh DESCRIPTION 17 .Nm 18 lines from 19 .Ar file1 20 and 21 .Ar file2 22 on a matching field. If one of the input files is '-', standard input 23 is read for that file. 24 .Pp 25 Files are read sequentially and are assumed to be sorted on the join 26 field. 27 .Nm 28 does not check the order of input, and joining two unsorted files will 29 produce unexpected output. 30 .Pp 31 By default, input lines are matched on the first blank-separated 32 field; output lines are space-separated and consist of the join field 33 followed by the remaining fields from 34 .Ar file1 Ns , 35 then the remaining fields from 36 .Ar file2 Ns . 37 .Sh OPTIONS 38 .Bl -tag -width Ds 39 .It Fl 1 Ar field 40 Join on the 41 .Ar field Ns th 42 field of file 1. 43 .It Fl 2 Ar field 44 Join on the 45 .Ar field Ns th 46 field of file 2. 47 .It Fl a Ar fileno 48 Print unpairable lines from file 49 .Ar fileno 50 in addition to normal output. 51 .It Fl e Ar string 52 When used with 53 .Fl o Ns , 54 replace empty fields in the output list with 55 .Ar string Ns . 56 .It Fl o Ar list 57 Format output according to the string 58 .Ar list Ns . 59 Each element of 60 .Ar list 61 may be either 62 .Ar fileno.field 63 or 0 (representing the join field). 64 Elements in 65 .Ar list 66 may be separated by blanks or commas. For example, 67 .Bd -literal -offset indent 68 join -o "0 2.1 1.3" 69 .Ed 70 .Pp 71 would print the join field, the first field of 72 .Ar file2 Ns , 73 then the third field of 74 .Ar file1 Ns . 75 .Pp 76 Only paired lines are formatted with the 77 .Fl o 78 option. Unpairable lines (selected with 79 .Fl a 80 or 81 .Fl v Ns ) 82 are printed raw. 83 .It Fl t Ar delim 84 Use the arbitrary string 85 .Ar delim 86 as field delimiter for both input and output. 87 .It Fl v Ar fileno 88 Print unpairable lines from file 89 .Ar fileno 90 instead of normal output. 91 .El 92 .Sh STANDARDS 93 The 94 .Nm 95 utility is compliant with the 96 .St -p1003.1-2013 97 specification with the following exeption: 98 .Bl -bullet -offset indent 99 .It 100 Unpairable lines ignore formatting specified with 101 .Fl o Ns . 102 .El 103 .Pp 104 The possibility of specifying multibyte delimiters of arbitrary 105 length is an extension to the specification.