1.\" Copyright (c) 1990 The Regents of the University of California. 2.\" All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)join.1 6.5 (Berkeley) 03/14/91 7.\" 8.Vx 9.Vx 10.Dd 11.Dt JOIN 1 12.Os 13.Sh NAME 14.Nm join 15.Nd relational database operator 16.Sh SYNOPSIS 17.Nm join 18.Op Fl a Ar file_number 19.Op Fl e Ar string 20.Op Fl j Ar file_number field 21.if n .br 22.Op Fl o Ar list 23.Op Fl t Ar char 24.Op Fl v Ar file_number 25.Ob 26.Fl \&1 27.Ar field 28.Oe 29.Ob 30.Fl \&2 31.Ar field 32.Oe 33.Ar file1 34.if n .br 35.Ar file2 36.Sh DESCRIPTION 37The join utility performs an ``equality join'' on the files 38.Ar file1 39and 40.Ar file2 . 41The joined files are written to the standard 42output. 43.Pp 44The ``join field'' is a field in each file on which the 45files are compared. 46There is one line in the output for 47each pair of lines in 48.Ar file1 49and 50.Ar file2 51which have identical 52join fields. 53The output line by default consists of the 54join field, then the remaining fields from 55.Ar file1 , 56then the 57remaining fields from 58.Ar file2 . 59This format can be changed by 60using the 61.Fl o 62option (see below). 63.Pp 64The files file1 and file2 should be ordered in the collating 65sequence of 66.Li sort -b 67on the fields on which they are to be 68joined, by default the first in each line; Otherwise, all 69join field matches need not be reported. 70.Pp 71The default input field separators are <blank>s. 72In this 73case, multiple separators count as one field separator, and 74leading separators are ignored. 75The default output field 76separator is a <space>. 77.Pp 78The following options are available: 79.Tw Fl 80.Tc Fl a 81.Ws 82.Ar file_number 83.Cx 84In addition to the default output, produce a line 85for each unpairable line in file 86.Ar file_number , 87where 88.Ar file_number 89is 1 or 2. 90.Tc Fl e 91.Ws 92.Ar string 93.Cx 94Replace empty output fields by the string 95.Ar string . 96.Tc Fl j 97.Ws 98.Ar file_number field 99.Cx 100Join on the 101.Sf Ar field 'th 102field of file 103.Ar file_number . 104If 105.Ar file_number 106is missing, (i.e., the 107first digit of the option argument is neither 1 nor 1082), use the 109.Sf Ar field 'th 110field in each file. 111Fields are 112decimal integers starting with 1. 113.Tc Fl o 114.Ws 115.Ar list 116.Cx 117Each output line comprises the fields specified in 118.Ar list , 119each element of which has the form 120.Ql file_number.field , 121where 122.Ar file_number 123is a file 124number and field is a decimal integer field number. 125The elements of list are either comma or <space> separated. 126The list is written only for lines with matching join fields, 127and is not output unless specifically requested. 128.Tc Fl t 129.Ws 130.Ar char 131.Cx 132Use character 133.Ar char 134as a separator, for both input 135and output. 136Every appearance of char in a line is 137significant. 138When this option is specified, the 139collating sequence should be the same as sort 140without the 141.Fl b 142option. 143.Tc Fl v 144.Ws 145.Ar file_number 146.Cx 147Instead of the default output, produce a line only 148for each unpairable line in 149.Ar file_number , 150where 151.Ar file_number 152is 1 or 2. 153.Tc Fl 1 154.Ws 155.Ar field 156.Cx 157Join on the 158.Sf Ar field 'th 159field of file 1. 160Fields are 161decimal integers starting with 1. 162.Tc Fl 2 163.Ws 164.Ar field 165.Cx 166Join on the 167.Sf Ar field 'th 168field of file 2. 169Fields are 170decimal integers starting with 1. 171.Tp 172.Pp 173If both 174.Ql \-a 1 175and 176.Ql \-a 2 177are specified, both sets of information 178are output, 179.Ql \-a 2 180always first, regardless of the specified 181order. 182.Pp 183The following arguments are required: 184.Dw Fl 185.Di L 186.Dp Ar file1 187.Dp Ar file2 188A pathname of a file to be joined. 189If either of 190the 191.Ar file1 192or 193.Ar file2 194arguments is 195.Sq Fl 196the standard 197input is used in its place. 198.Dp 199.Pp 200The 201.Nm join 202utility exits 0 on success, and >0 if an error occurs. 203.Sh STANDARDS 204The 205.Nm join 206function is expected to be POSIX 1003.2 compatible. 207.Sh SEE ALSO 208.Xr awk 1 209.Xr comm 1 , 210.Xr look 1 211.Xr sort 1 , 212.Xr uniq 1 , 213.Sh BUGS 214The conventions of 215.Nm join , 216.Xr comm 1 , 217.Xr sort 1 , 218.Xr uniq 1 , 219.Xr look 1 220and 221.Xr awk 1 222are wildly incongruous. 223