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