Annotation of src/usr.bin/join/join.1, Revision 1.11
1.11 ! aaron 1: .\" $OpenBSD: join.1,v 1.10 2000/11/09 17:52:15 aaron 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.
17: .\" 3. All advertising materials mentioning features or use of this software
18: .\" must display the following acknowledgement:
19: .\" This product includes software developed by the University of
20: .\" California, Berkeley and its contributors.
21: .\" 4. Neither the name of the University nor the names of its contributors
22: .\" may be used to endorse or promote products derived from this software
23: .\" without specific prior written permission.
24: .\"
25: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
26: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
29: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35: .\" SUCH DAMAGE.
36: .\"
1.3 michaels 37: .\" @(#)join.1 8.3 (Berkeley) 4/28/95
1.1 deraadt 38: .\"
1.3 michaels 39: .Dd April 28, 1995
1.1 deraadt 40: .Dt JOIN 1
41: .Os
42: .Sh NAME
43: .Nm join
44: .Nd relational database operator
45: .Sh SYNOPSIS
46: .Nm join
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 file_number 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
1.6 aaron 61: The
62: .Nm
63: utility performs an
64: .Dq equality join
65: on the specified files
1.1 deraadt 66: and writes the result to the standard output.
1.6 aaron 67: The
68: .Dq join field
69: is the field in each file by which the files are compared.
1.1 deraadt 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.
1.4 millert 76: Each output line consists of the join field, the remaining fields from
1.1 deraadt 77: .Ar file1
1.4 millert 78: and then the remaining fields from
1.1 deraadt 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.
1.6 aaron 87: Both file numbers and field numbers are 1 based, i.e., the first file on
1.1 deraadt 88: the command line is file number 1 and the first field is field number 1.
1.8 aaron 89: .Pp
90: The options are as follows:
1.10 aaron 91: .Bl -tag -width Ds
1.1 deraadt 92: .It Fl a Ar file_number
93: In addition to the default output, produce a line for each unpairable
94: line in file
95: .Ar file_number .
1.3 michaels 96: (The argument to
97: .Fl a
98: must not be preceded by a space; see the
99: .Sx COMPATIBILITY
100: section.)
1.1 deraadt 101: .It Fl e Ar string
102: Replace empty output fields with
103: .Ar string .
104: .It Fl o Ar list
1.5 aaron 105: Specifies the fields that will be output from each file for
1.1 deraadt 106: each line with matching join fields.
107: Each element of
108: .Ar list
109: has the form
1.9 aaron 110: .Dq file_number.field ,
1.1 deraadt 111: where
112: .Ar file_number
113: is a file number and
114: .Ar field
115: is a field number.
1.6 aaron 116: The elements of list must be either comma
117: .Pq Ql \&,
118: or whitespace separated.
1.3 michaels 119: (The latter requires quoting to protect it from the shell, or, a simpler
1.1 deraadt 120: approach is to use multiple
121: .Fl o
122: options.)
123: .It Fl t Ar char
124: Use character
125: .Ar char
126: as a field delimiter for both input and output.
127: Every occurrence of
128: .Ar char
129: in a line is significant.
130: .It Fl v Ar file_number
131: Do not display the default output, but display a line for each unpairable
132: line in file
133: .Ar file_number .
134: The options
135: .Fl v Ar 1
136: and
137: .Fl v Ar 2
138: may be specified at the same time.
139: .It Fl 1 Ar field
140: Join on the
141: .Ar field Ns 'th
142: field of file 1.
143: .It Fl 2 Ar field
144: Join on the
145: .Ar field Ns 'th
146: field of file 2.
147: .El
148: .Pp
149: When the default field delimiter characters are used, the files to be joined
150: should be ordered in the collating sequence of
151: .Xr sort 1 ,
152: using the
153: .Fl b
154: option, on the fields on which they are to be joined, otherwise
1.6 aaron 155: .Nm
1.1 deraadt 156: may not report all field matches.
157: When the field delimiter characters are specified by the
158: .Fl t
159: option, the collating sequence should be the same as
160: .Xr sort
161: without the
162: .Fl b
163: option.
164: .Pp
165: If one of the arguments
166: .Ar file1
167: or
168: .Ar file2
1.6 aaron 169: is
1.9 aaron 170: .Dq - ,
1.6 aaron 171: the standard input is used.
1.9 aaron 172: .\" XXX - use .br as a work-around for an apparent bug in mdoc
173: .br
1.1 deraadt 174: .Pp
175: The
1.6 aaron 176: .Nm
1.5 aaron 177: utility exits 0 on success or >0 if an error occurred.
1.11 ! aaron 178: .Sh SEE ALSO
! 179: .Xr awk 1 ,
! 180: .Xr comm 1 ,
! 181: .Xr paste 1 ,
! 182: .Xr sort 1 ,
! 183: .Xr uniq 1
1.1 deraadt 184: .Sh COMPATIBILITY
185: For compatibility with historic versions of
186: .Nm join ,
187: the following options are available:
188: .Bl -tag -width Fl
189: .It Fl a
190: In addition to the default output, produce a line for each unpairable line
191: in both file 1 and file 2.
1.3 michaels 192: (To distinguish between this and
193: .Fl a Ar file_number ,
1.6 aaron 194: .Nm
1.7 aaron 195: currently requires that the latter not include any whitespace.)
1.1 deraadt 196: .It Fl j1 Ar field
197: Join on the
198: .Ar field Ns 'th
199: field of file 1.
200: .It Fl j2 Ar field
201: Join on the
202: .Ar field Ns 'th
203: field of file 2.
204: .It Fl j Ar field
205: Join on the
206: .Ar field Ns 'th
207: field of both file 1 and file 2.
208: .It Fl o Ar list ...
209: Historical implementations of
1.6 aaron 210: .Nm
1.1 deraadt 211: permitted multiple arguments to the
212: .Fl o
213: option.
1.6 aaron 214: These arguments were of the form
215: .Dq file_number.field_number
216: as described for the current
1.1 deraadt 217: .Fl o
218: option.
1.6 aaron 219: This has obvious difficulties in the presence of files named
220: .Dq 1.2 .
1.1 deraadt 221: .El
222: .Pp
1.5 aaron 223: These options are available only so historic shell scripts don't require
1.1 deraadt 224: modification and should not be used.
225: .Sh STANDARDS
226: The
1.6 aaron 227: .Nm
1.1 deraadt 228: command is expected to be
229: .St -p1003.2
230: compatible.
![[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