usr.bin/join/join.1

   1 .\" Copyright (c) 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" the Institute of Electrical and Electronics Engineers, Inc.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\" 3. All advertising materials mentioning features or use of this software
  16 .\"    must display the following acknowledgement:
  17 .\"     This product includes software developed by the University of
  18 .\"     California, Berkeley and its contributors.
  19 .\" 4. Neither the name of the University nor the names of its contributors
  20 .\"    may be used to endorse or promote products derived from this software
  21 .\"    without specific prior written permission.
  22 .\"
  23 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  33 .\" SUCH DAMAGE.
  34 .\"
  35 .\"     @(#)join.1      8.3 (Berkeley) 4/28/95
  36 .\" $FreeBSD: src/usr.bin/join/join.1,v 1.3.2.5 2003/02/24 23:04:39 trhodes Exp $
  37 .\"
  38 .Dd April 18, 2002
  39 .Dt JOIN 1
  40 .Os
  41 .Sh NAME
  42 .Nm join
  43 .Nd relational database operator
  44 .Sh SYNOPSIS
  45 .Nm
  46 .Oo
  47 .Fl a Ar file_number | Fl v Ar file_number
  48 .Oc
  49 .Op Fl e Ar string
  50 .Op Fl o Ar list
  51 .Bk -words
  52 .Ek
  53 .Op Fl t Ar char
  54 .Op Fl \&1 Ar field
  55 .Op Fl \&2 Ar field
  56 .Ar file1
  57 .Ar file2
  58 .Sh DESCRIPTION
  59 The
  60 .Nm
  61 utility performs an
  62 .Dq equality join
  63 on the specified files
  64 and writes the result to the standard output.
  65 The
  66 .Dq join field
  67 is the field in each file by which the files are compared.
  68 The first field in each line is used by default.
  69 There is one line in the output for each pair of lines in
  70 .Ar file1
  71 and
  72 .Ar file2
  73 which have identical join fields.
  74 Each output line consists of the join field, the remaining fields from
  75 .Ar file1
  76 and then the remaining fields from
  77 .Ar file2 .
  78 .Pp
  79 The default field separators are tab and space characters.
  80 In this case, multiple tabs and spaces count as a single field separator,
  81 and leading tabs and spaces are ignored.
  82 The default output field separator is a single space character.
  83 .Pp
  84 Many of the options use file and field numbers.
  85 Both file numbers and field numbers are 1 based, i.e. the first file on
  86 the command line is file number 1 and the first field is field number 1.
  87 The following options are available:
  88 .Bl -tag -width indent
  89 .It Fl a Ar file_number
  90 In addition to the default output, produce a line for each unpairable
  91 line in file
  92 .Ar file_number .
  93 .It Fl e Ar string
  94 Replace empty output fields with
  95 .Ar string .
  96 .It Fl o Ar list
  97 The
  98 .Fl o
  99 option specifies the fields that will be output from each file for
 100 each line with matching join fields.
 101 Each element of
 102 .Ar list
 103 has the either the form
 104 .Ql file_number.field ,
 105 where
 106 .Ar file_number
 107 is a file number and
 108 .Ar field
 109 is a field number, or the form
 110 .Ql 0
 111 .Pq zero ,
 112 representing the join field.
 113 The elements of list must be either comma
 114 .Pq Ql \&,
 115 or whitespace separated.
 116 (The latter requires quoting to protect it from the shell, or, a simpler
 117 approach is to use multiple
 118 .Fl o
 119 options.)
 120 .It Fl t Ar char
 121 Use character
 122 .Ar char
 123 as a field delimiter for both input and output.
 124 Every occurrence of
 125 .Ar char
 126 in a line is significant.
 127 .It Fl v Ar file_number
 128 Do not display the default output, but display a line for each unpairable
 129 line in file
 130 .Ar file_number .
 131 The options
 132 .Fl v Ar 1
 133 and
 134 .Fl v Ar 2
 135 may be specified at the same time.
 136 .It Fl 1 Ar field
 137 Join on the
 138 .Ar field Ns 'th
 139 field of file 1.
 140 .It Fl 2 Ar field
 141 Join on the
 142 .Ar field Ns 'th
 143 field of file 2.
 144 .El
 145 .Pp
 146 When the default field delimiter characters are used, the files to be joined
 147 should be ordered in the collating sequence of
 148 .Xr sort 1 ,
 149 using the
 150 .Fl b
 151 option, on the fields on which they are to be joined, otherwise
 152 .Nm
 153 may not report all field matches.
 154 When the field delimiter characters are specified by the
 155 .Fl t
 156 option, the collating sequence should be the same as
 157 .Xr sort 1
 158 without the
 159 .Fl b
 160 option.
 161 .Pp
 162 If one of the arguments
 163 .Ar file1
 164 or
 165 .Ar file2
 166 is
 167 .Dq - ,
 168 the standard input is used.
 169 .Sh DIAGNOSTICS
 170 .Ex -std
 171 .Sh COMPATIBILITY
 172 For compatibility with historic versions of
 173 .Nm ,
 174 the following options are available:
 175 .Bl -tag -width indent
 176 .It Fl a
 177 In addition to the default output, produce a line for each unpairable line
 178 in both file 1 and file 2.
 179 .It Fl j1 Ar field
 180 Join on the
 181 .Ar field Ns 'th
 182 field of file 1.
 183 .It Fl j2 Ar field
 184 Join on the
 185 .Ar field Ns 'th
 186 field of file 2.
 187 .It Fl j Ar field
 188 Join on the
 189 .Ar field Ns 'th
 190 field of both file 1 and file 2.
 191 .It Fl o Ar list ...
 192 Historical implementations of
 193 .Nm
 194 permitted multiple arguments to the
 195 .Fl o
 196 option.
 197 These arguments were of the form
 198 .Ql file_number.field_number
 199 as described
 200 for the current
 201 .Fl o
 202 option.
 203 This has obvious difficulties in the presence of files named
 204 .Ql 1.2 .
 205 .El
 206 .Pp
 207 These options are available only so historic shellscripts don't require
 208 modification and should not be used.
 209 .Sh STANDARDS
 210 The
 211 .Nm
 212 command conforms to
 213 .St -p1003.1-2001 .
 214 .Sh SEE ALSO
 215 .Xr awk 1 ,
 216 .Xr comm 1 ,
 217 .Xr paste 1 ,
 218 .Xr sort 1 ,
 219 .Xr uniq 1