patch.html

IEEE 1003.1-2003, Single Unix Specification v3

<dt>---&nbsp;<i>filename&nbsp;timestamp</i></dt>

<dd><br>
The patches should be applied to <i>filename</i>.</dd>
</dl>

<p>Each hunk within a patch shall be the <a href="../utilities/diff.html"><i>diff</i></a> output to change a line range within the
original file. The line numbers for successive hunks within a patch shall occur in ascending order.</p>

<h5><a name="tag_04_98_13_02"></a>Filename Determination</h5>

<p>If no <i>file</i> operand is specified, <i>patch</i> shall perform the following steps to determine the filename to use:</p>

<ol>
<li>
<p>If the type of <a href="../utilities/diff.html"><i>diff</i></a> is context, the <i>patch</i> utility shall delete pathname
components (as specified by the <b>-p</b> option) from the filename on the line beginning with <tt>"***"</tt> , then test for the
existence of this file relative to the current directory (or the directory specified with the <b>-d</b> option). If the file
exists, the <i>patch</i> utility shall use this filename.</p>
</li>

<li>
<p>If the type of <a href="../utilities/diff.html"><i>diff</i></a> is context, the <i>patch</i> utility shall delete the pathname
components (as specified by the <b>-p</b> option) from the filename on the line beginning with <tt>"---"</tt> , then test for the
existence of this file relative to the current directory (or the directory specified with the <b>-d</b> option). If the file
exists, the <i>patch</i> utility shall use this filename.</p>
</li>

<li>
<p>If the header information contains a line beginning with the string <b>Index:</b>, the <i>patch</i> utility shall delete
pathname components (as specified by the <b>-p</b> option) from this line, then test for the existence of this file relative to the
current directory (or the directory specified with the <b>-d</b> option). If the file exists, the <i>patch</i> utility shall use
this filename.</p>
</li>

<li>
<p><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt="[Option Start]" border="0">
If an <b>SCCS</b> directory exists in the current directory, <i>patch</i> shall attempt to perform a <a href=
"../utilities/get.html"><i>get</i></a> <b>-e</b> <b>SCCS/s.</b> <i>filename</i> command to retrieve an editable version of the
file. If the file exists, the <i>patch</i> utility shall use this filename. <img src="../images/opt-end.gif" alt="[Option End]"
border="0"></p>
</li>

<li>
<p>The <i>patch</i> utility shall write a prompt to standard output and request a filename interactively from the controlling
terminal (for example, <b>/dev/tty</b>).</p>
</li>
</ol>

<h5><a name="tag_04_98_13_03"></a>Patch Application</h5>

<p>If the <b>-c</b>, <b>-e</b>, or <b>-n</b> option is present, the <i>patch</i> utility shall interpret information within each
hunk as a context difference, an <a href="../utilities/ed.html"><i>ed</i></a> difference, or a normal difference, respectively. In
the absence of any of these options, the <i>patch</i> utility shall determine the type of difference based on the format of
information within the hunk.</p>

<p>For each hunk, the <i>patch</i> utility shall begin to search for the place to apply the patch at the line number at the
beginning of the hunk, plus or minus any offset used in applying the previous hunk. If lines matching the hunk context are not
found, <i>patch</i> shall scan both forwards and backwards at least 1000 bytes for a set of lines that match the hunk context.</p>

<p>If no such place is found and it is a context difference, then another scan shall take place, ignoring the first and last line
of context. If that fails, the first two and last two lines of context shall be ignored and another scan shall be made.
Implementations may search more extensively for installation locations.</p>

<p>If no location can be found, the <i>patch</i> utility shall append the hunk to the reject file. The rejected hunk shall be
written in context-difference format regardless of the format of the patch file. If the input was a normal or <a href=
"../utilities/ed.html"><i>ed</i></a>-style difference, the reject file may contain differences with zero lines of context. The line
numbers on the hunks in the reject file may be different from the line numbers in the patch file since they shall reflect the
approximate locations for the failed hunks in the new file rather than the old one.</p>

<p>If the type of patch is an <a href="../utilities/ed.html"><i>ed</i></a> diff, the implementation may accomplish the patching by
invoking the <a href="../utilities/ed.html"><i>ed</i></a> utility.</p>
</blockquote>

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

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

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

<dd>Successful completion.</dd>

<dt>&nbsp;1</dt>

<dd>One or more lines were written to a reject file.</dd>

<dt>&gt;1</dt>

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

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

<blockquote>
<p>Patches that cannot be correctly placed in the file shall be written to a reject file.</p>
</blockquote>

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

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

<blockquote>
<p>The <b>-R</b> option does not work with <a href="../utilities/ed.html"><i>ed</i></a> scripts because there is too little
information to reconstruct the reverse operation.</p>

<p>The <b>-p</b> option makes it possible to customize a patch file to local user directory structures without manually editing the
patch file. For example, if the filename in the patch file was:</p>

<pre>
<tt>/curds/whey/src/blurfl/blurfl.c
</tt>
</pre>

<p>Setting <b>-p&nbsp;0</b> gives the entire pathname unmodified; <b>-p&nbsp;1</b> gives:</p>

<pre>
<tt>curds/whey/src/blurfl/blurfl.c
</tt>
</pre>

<p>without the leading slash, <b>-p&nbsp;4</b> gives:</p>

<pre>
<tt>blurfl/blurfl.c
</tt>
</pre>

<p>and not specifying <b>-p</b> at all gives:</p>

<pre>
<tt>blurfl.c .
</tt>
</pre>
</blockquote>

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

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

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

<blockquote>
<p>Some of the functionality in historical <i>patch</i> implementations was not specified. The following documents those features
present in historical implementations that have not been specified.</p>

<p>A deleted piece of functionality was the <tt>'+'</tt> pseudo-option allowing an additional set of options and a patch file
operand to be given. This was seen as being insufficiently useful to standardize.</p>

<p>In historical implementations, if the string <tt>"Prereq:"</tt> appeared in the header, the <i>patch</i> utility would search
for the corresponding version information (the string specified in the header, delimited by &lt;blank&gt;s or the beginning or end
of a line or the file) anywhere in the original file. This was deleted as too simplistic and insufficiently trustworthy a mechanism
to standardize. For example, if:</p>

<pre>
<tt>Prereq: 1.2
</tt>
</pre>

<p>were in the header, the presence of a delimited 1.2 anywhere in the file would satisfy the prerequisite.</p>

<p>The following options were dropped from historical implementations of <i>patch</i> as insufficiently useful to standardize:</p>

<dl compact>
<dt><b>-b</b></dt>

<dd>The <b>-b</b> option historically provided a method for changing the name extension of the backup file from the default
<b>.orig</b>. This option has been modified and retained in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001.</dd>

<dt><b>-F</b></dt>

<dd>The <b>-F</b> option specified the number of lines of a context diff to ignore when searching for a place to install a
patch.</dd>

<dt><b>-f</b></dt>

<dd>The <b>-f</b> option historically caused <i>patch</i> not to request additional information from the user.</dd>

<dt><b>-r</b></dt>

<dd>The <b>-r</b> option historically provided a method of overriding the extension of the reject file from the default
<b>.rej</b>.</dd>

<dt><b>-s</b></dt>

<dd>The <b>-s</b> option historically caused <i>patch</i> to work silently unless an error occurred.</dd>

<dt><b>-x</b></dt>

<dd>The <b>-x</b> option historically set internal debugging flags.</dd>
</dl>

<p>In some file system implementations, the saving of a <b>.orig</b> file may produce unwanted results. In the case of 12, 13, or
14-character filenames (on file systems supporting 14-character maximum filenames), the <b>.orig</b> file overwrites the new file.
The reject file may also exceed this filename limit. It was suggested, due to some historical practice, that a tilde (
<tt>'&#152;'</tt> ) suffix be used instead of <b>.orig</b> and some other character instead of the <b>.rej</b> suffix. This was
rejected because it is not obvious to the user which file is which. The suffixes <b>.orig</b> and <b>.rej</b> are clearer and more
understandable.</p>

<p>The <b>-b</b> option has the opposite sense in some historical implementations-do not save the <b>.orig</b> file. The default
case here is not to save the files, making <i>patch</i> behave more consistently with the other standard utilities.</p>

<p>The <b>-w</b> option in early proposals was changed to <b>-l</b> to match historical practice.</p>

<p>The <b>-N</b> option was included because without it, a non-interactive application cannot reject previously applied patches.
For example, if a user is piping the output of <a href="../utilities/diff.html"><i>diff</i></a> into the <i>patch</i> utility, and
the user only wants to patch a file to a newer version non-interactively, the <b>-N</b> option is required.</p>

<p>Changes to the <b>-l</b> option description were proposed to allow matching across &lt;newline&gt;s in addition to just
&lt;blank&gt;s. Since this is not historical practice, and since some ambiguities could result, it is suggested that future
developments in this area utilize another option letter, such as <b>-L</b>.</p>
</blockquote>

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

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

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

<blockquote>
<p><a href="ed.html"><i>ed</i></a> , <a href="diff.html"><i>diff</i></a></p>
</blockquote>

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

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

<h4><a name="tag_04_98_22"></a>Issue 5</h4>

<blockquote>
<p>The FUTURE DIRECTIONS section is added.</p>
</blockquote>

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

<blockquote>
<p>This utility is marked as part of the User Portability Utilities option.</p>

<p>The description of the <b>-D</b> option and the steps in <a href="#tag_04_98_13_02">Filename Determination</a> are changed to
match historical practice as defined in the IEEE&nbsp;P1003.2b draft standard.</p>

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

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XCU/TC1/D6/34 is applied, clarifying the way that the <i>patch</i> utility
performs <b>ifdef</b> selection for the <b>-D</b> option.</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>