join.html

IEEE 1003.1-2003, Single Unix Specification v3

</tt>
</pre>

<p>where the concatenation of fields is described by the <b>-o</b> option, above.</p>

<p>For either format, each field (except the last) shall be written with its trailing separator character. If the separator is the
default ( &lt;blank&gt;s), a single &lt;space&gt; shall be written after each field (except the last).</p>
</blockquote>

<h4><a name="tag_04_71_11"></a>STDERR</h4>

<blockquote>
<p>The standard error shall be used only for diagnostic messages.</p>
</blockquote>

<h4><a name="tag_04_71_12"></a>OUTPUT FILES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_71_13"></a>EXTENDED DESCRIPTION</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_71_14"></a>EXIT STATUS</h4>

<blockquote>
<p>The following exit values shall be returned:</p>

<dl compact>
<dt>&nbsp;0</dt>

<dd>All input files were output successfully.</dd>

<dt>&gt;0</dt>

<dd>An error occurred.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_71_15"></a>CONSEQUENCES OF ERRORS</h4>

<blockquote>
<p>Default.</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_04_71_16"></a>APPLICATION USAGE</h4>

<blockquote>
<p>Pathnames consisting of numeric digits or of the form <i>string.string</i> should not be specified directly following the
<b>-o</b> list.</p>
</blockquote>

<h4><a name="tag_04_71_17"></a>EXAMPLES</h4>

<blockquote>
<p>The <b>-o</b> 0 field essentially selects the union of the join fields. For example, given file <b>phone</b>:</p>

<pre>
<tt>!Name           Phone Number
Don             [phone]
Hal             [phone]
Yasushi         [phone]
</tt>
</pre>

<p>and file <b>fax</b>:</p>

<pre>
<tt>!Name           Fax Number
Don             [phone]
Keith           [phone]
Yasushi         [phone]
</tt>
</pre>

<p>(where the large expanses of white space are meant to each represent a single &lt;tab&gt;), the command:</p>

<pre>
<tt>join -t "&lt;tab&gt;" -a 1 -a 2 -e '(unknown)' -o 0,1.2,2.2 phone fax
</tt>
</pre>

<p>would produce:</p>

<pre>
<tt>!Name           Phone Number            Fax Number
Don             [phone]         [phone]
Hal             [phone]         (unknown)
Keith           (unknown)               [phone]
Yasushi         [phone]         [phone]
</tt>
</pre>

<p>Multiple instances of the same key will produce combinatorial results. The following:</p>

<pre>
<tt>fa:
    a x
    a y
    a z
fb:
    a p
</tt>
</pre>

<p>will produce:</p>

<pre>
<tt>a x p
a y p
a z p
</tt>
</pre>

<p>And the following:</p>

<pre>
<tt>fa:
    a b c
    a d e
fb:
    a w x
    a y z
    a o p
</tt>
</pre>

<p>will produce:</p>

<pre>
<tt>a b c w x
a b c y z
a b c o p
a d e w x
a d e y z
a d e o p
</tt>
</pre>
</blockquote>

<h4><a name="tag_04_71_18"></a>RATIONALE</h4>

<blockquote>
<p>The <b>-e</b> option is only effective when used with <b>-o</b> because, unless specific fields are identified using <b>-o</b>,
<i>join</i> is not aware of what fields might be empty. The exception to this is the join field, but identifying an empty join
field with the <b>-e</b> string is not historical practice and some scripts might break if this were changed.</p>

<p>The 0 field in the <b>-o</b> list was adopted from the Tenth Edition version of <i>join</i> to satisfy international objections
that the <i>join</i> in the base documents does not support the &quot;full join&quot; or &quot;outer join&quot; described in relational database
literature. Although it has been possible to include a join field in the output (by default, or by field number using <b>-o</b>),
the join field could not be included for an unpaired line selected by <b>-a</b>. The <b>-o</b> 0 field essentially selects the
union of the join fields.</p>

<p>This sort of outer join was not possible with the <i>join</i> commands in the base documents. The <b>-o</b> 0 field was chosen
because it is an upwards-compatible change for applications. An alternative was considered: have the join field represent the union
of the fields in the files (where they are identical for matched lines, and one or both are null for unmatched lines). This was not
adopted because it would break some historical applications.</p>

<p>The ability to specify <i>file2</i> as <b>-</b> is not historical practice; it was added for completeness.</p>

<p>The <b>-v</b> option is not historical practice, but was considered necessary because it permitted the writing of <i>only</i>
those lines that do not match on the join field, as opposed to the <b>-a</b> option, which prints both lines that do and do not
match. This additional facility is parallel with the <b>-v</b> option of <a href="../utilities/grep.html"><i>grep</i></a>.</p>

<p>Some historical implementations have been encountered where a blank line in one of the input files was considered to be the end
of the file; the description in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 does not cite this as an allowable case.</p>
</blockquote>

<h4><a name="tag_04_71_19"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_04_71_20"></a>SEE ALSO</h4>

<blockquote>
<p><a href="awk.html"><i>awk</i></a> , <a href="comm.html"><i>comm</i></a> , <a href="sort.html"><i>sort</i></a> , <a href=
"uniq.html"><i>uniq</i></a></p>
</blockquote>

<h4><a name="tag_04_71_21"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 2.</p>
</blockquote>

<h4><a name="tag_04_71_22"></a>Issue 6</h4>

<blockquote>
<p>The obsolescent <b>-j</b> options and the multi-argument <b>-o</b> option are withdrawn in this issue.</p>

<p>The normative text is reworded to avoid use of the term &quot;must&quot; for application requirements.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>