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