| .Dd 2015-10-08 |
| .Dt JOIN 1 |
| .Os sbase |
| .Sh NAME |
| .Nm join |
| .Nd relational database operator |
| .Sh SYNOPSIS |
| .Nm |
| .Op Fl 1 Ar field |
| .Op Fl 2 Ar field |
| .Op Fl o Ar list |
| .Op Fl e Ar string |
| .Op Fl a Ar fileno | Fl v Ar fileno |
| .Op Fl t Ar delim |
| .Ar file1 file2 |
| .Sh DESCRIPTION |
| .Nm |
| lines from |
| .Ar file1 |
| and |
| .Ar file2 |
| on a matching field. If one of the input files is '-', standard input |
| is read for that file. |
| .Pp |
| Files are read sequentially and are assumed to be sorted on the join |
| field. |
| .Nm |
| does not check the order of input, and joining two unsorted files will |
| produce unexpected output. |
| .Pp |
| By default, input lines are matched on the first blank-separated |
| field; output lines are space-separated and consist of the join field |
| followed by the remaining fields from |
| .Ar file1 Ns , |
| then the remaining fields from |
| .Ar file2 Ns . |
| .Sh OPTIONS |
| .Bl -tag -width Ds |
| .It Fl 1 Ar field |
| Join on the |
| .Ar field Ns th |
| field of file 1. |
| .It Fl 2 Ar field |
| Join on the |
| .Ar field Ns th |
| field of file 2. |
| .It Fl a Ar fileno |
| Print unpairable lines from file |
| .Ar fileno |
| in addition to normal output. |
| .It Fl e Ar string |
| When used with |
| .Fl o Ns , |
| replace empty fields in the output list with |
| .Ar string Ns . |
| .It Fl o Ar list |
| Format output according to the string |
| .Ar list Ns . |
| Each element of |
| .Ar list |
| may be either |
| .Ar fileno.field |
| or 0 (representing the join field). |
| Elements in |
| .Ar list |
| may be separated by blanks or commas. For example, |
| .Bd -literal -offset indent |
| join -o "0 2.1 1.3" |
| .Ed |
| .Pp |
| would print the join field, the first field of |
| .Ar file2 Ns , |
| then the third field of |
| .Ar file1 Ns . |
| .Pp |
| Only paired lines are formatted with the |
| .Fl o |
| option. Unpairable lines (selected with |
| .Fl a |
| or |
| .Fl v Ns ) |
| are printed raw. |
| .It Fl t Ar delim |
| Use the arbitrary string |
| .Ar delim |
| as field delimiter for both input and output. |
| .It Fl v Ar fileno |
| Print unpairable lines from file |
| .Ar fileno |
| instead of normal output. |
| .El |
| .Sh STANDARDS |
| The |
| .Nm |
| utility is compliant with the |
| .St -p1003.1-2013 |
| specification with the following exeption: |
| .Bl -bullet -offset indent |
| .It |
| Unpairable lines ignore formatting specified with |
| .Fl o Ns . |
| .El |
| .Pp |
| The possibility of specifying multibyte delimiters of arbitrary |
| length is an extension to the specification. |