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