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 .\" $DragonFly: src/usr.bin/join/join.1,v 1.4 2006/02/17 19:39:07 swildner Exp $
  38 .\"
  39 .Dd April 18, 2002
  40 .Dt JOIN 1
  41 .Os
  42 .Sh NAME
  43 .Nm join
  44 .Nd relational database operator
  45 .Sh SYNOPSIS
  46 .Nm
  47 .Oo
  48 .Fl a Ar file_number | Fl v Ar file_number
  49 .Oc
  50 .Op Fl e Ar string
  51 .Op Fl j Ar fileno field
  52 .Op Fl o Ar list
  53 .Bk -words
  54 .Ek
  55 .Op Fl t Ar char
  56 .Op Fl \&1 Ar field
  57 .Op Fl \&2 Ar field
  58 .Ar file1
  59 .Ar file2
  60 .Sh DESCRIPTION
  61 The
  62 .Nm
  63 utility performs an
  64 .Dq equality join
  65 on the specified files
  66 and writes the result to the standard output.
  67 The
  68 .Dq join field
  69 is the field in each file by which the files are compared.
  70 The first field in each line is used by default.
  71 There is one line in the output for each pair of lines in
  72 .Ar file1
  73 and
  74 .Ar file2
  75 which have identical join fields.
  76 Each output line consists of the join field, the remaining fields from
  77 .Ar file1
  78 and then the remaining fields from
  79 .Ar file2 .
  80 .Pp
  81 The default field separators are tab and space characters.
  82 In this case, multiple tabs and spaces count as a single field separator,
  83 and leading tabs and spaces are ignored.
  84 The default output field separator is a single space character.
  85 .Pp
  86 Many of the options use file and field numbers.
  87 Both file numbers and field numbers are 1 based, i.e. the first file on
  88 the command line is file number 1 and the first field is field number 1.
  89 The following options are available:
  90 .Bl -tag -width indent
  91 .It Fl a Ar file_number
  92 In addition to the default output, produce a line for each unpairable
  93 line in file
  94 .Ar file_number .
  95 .It Fl e Ar string
  96 Replace empty output fields with
  97 .Ar string .
  98 .It Fl o Ar list
  99 The
 100 .Fl o
 101 option specifies the fields that will be output from each file for
 102 each line with matching join fields.
 103 Each element of
 104 .Ar list
 105 has the either the form
 106 .Ql file_number.field ,
 107 where
 108 .Ar file_number
 109 is a file number and
 110 .Ar field
 111 is a field number, or the form
 112 .Ql 0
 113 .Pq zero ,
 114 representing the join field.
 115 The elements of list must be either comma
 116 .Pq Ql \&,
 117 or whitespace separated.
 118 (The latter requires quoting to protect it from the shell, or, a simpler
 119 approach is to use multiple
 120 .Fl o
 121 options.)
 122 .It Fl t Ar char
 123 Use character
 124 .Ar char
 125 as a field delimiter for both input and output.
 126 Every occurrence of
 127 .Ar char
 128 in a line is significant.
 129 .It Fl v Ar file_number
 130 Do not display the default output, but display a line for each unpairable
 131 line in file
 132 .Ar file_number .
 133 The options
 134 .Fl v Ar 1
 135 and
 136 .Fl v Ar 2
 137 may be specified at the same time.
 138 .It Fl 1 Ar field
 139 Join on the
 140 .Ar field Ns 'th
 141 field of file 1.
 142 .It Fl 2 Ar field
 143 Join on the
 144 .Ar field Ns 'th
 145 field of file 2.
 146 .El
 147 .Pp
 148 When the default field delimiter characters are used, the files to be joined
 149 should be ordered in the collating sequence of
 150 .Xr sort 1 ,
 151 using the
 152 .Fl b
 153 option, on the fields on which they are to be joined, otherwise
 154 .Nm
 155 may not report all field matches.
 156 When the field delimiter characters are specified by the
 157 .Fl t
 158 option, the collating sequence should be the same as
 159 .Xr sort 1
 160 without the
 161 .Fl b
 162 option.
 163 .Pp
 164 If one of the arguments
 165 .Ar file1
 166 or
 167 .Ar file2
 168 is
 169 .Dq - ,
 170 the standard input is used.
 171 .Sh EXIT STATUS
 172 .Ex -std
 173 .Sh COMPATIBILITY
 174 For compatibility with historic versions of
 175 .Nm ,
 176 the following options are available:
 177 .Bl -tag -width indent
 178 .It Fl a
 179 In addition to the default output, produce a line for each unpairable line
 180 in both file 1 and file 2.
 181 .It Fl j1 Ar field
 182 Join on the
 183 .Ar field Ns 'th
 184 field of file 1.
 185 .It Fl j2 Ar field
 186 Join on the
 187 .Ar field Ns 'th
 188 field of file 2.
 189 .It Fl j Ar field
 190 Join on the
 191 .Ar field Ns 'th
 192 field of both file 1 and file 2.
 193 .It Fl o Ar list ...
 194 Historical implementations of
 195 .Nm
 196 permitted multiple arguments to the
 197 .Fl o
 198 option.
 199 These arguments were of the form
 200 .Ql file_number.field_number
 201 as described
 202 for the current
 203 .Fl o
 204 option.
 205 This has obvious difficulties in the presence of files named
 206 .Ql 1.2 .
 207 .El
 208 .Pp
 209 These options are available only so historic shellscripts don't require
 210 modification and should not be used.
 211 .Sh SEE ALSO
 212 .Xr awk 1 ,
 213 .Xr comm 1 ,
 214 .Xr paste 1 ,
 215 .Xr sort 1 ,
 216 .Xr uniq 1
 217 .Sh STANDARDS
 218 The
 219 .Nm
 220 command conforms to
 221 .St -p1003.1-2001 .