oasis-root

patch.1p (19652B)

'\" et
.TH PATCH "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\"
.SH PROLOG
This manual page is part of the POSIX Programmer's Manual.
The Linux implementation of this interface may differ (consult
the corresponding Linux manual page for details of Linux behavior),
or the interface may not be implemented on Linux.
.\"
.SH NAME
patch
\(em apply changes to files
.SH SYNOPSIS
.LP
.nf
patch \fB[\fR-blNR\fB] [\fR-c|-e|-n|-u\fB] [\fR-d \fIdir\fB] [\fR-D \fIdefine\fB] [\fR-i \fIpatchfile\fB]
    [\fR-o \fIoutfile\fB] [\fR-p \fInum\fB] [\fR-r \fIrejectfile\fB] [\fIfile\fB]\fR
.fi
.SH DESCRIPTION
The
.IR patch
utility shall read a source (patch) file containing any of four
forms of difference (diff) listings produced by the
.IR diff
utility (normal, copied context, unified context, or in the style of
.IR ed )
and apply those differences to a file. By default,
.IR patch
shall read from the standard input.
.P
The
.IR patch
utility shall attempt to determine the type of the
.IR diff
listing, unless overruled by a
.BR \-c ,
.BR \-e ,
.BR \-n ,
or
.BR \-u
option.
.P
If the patch file contains more than one patch,
.IR patch
shall attempt to apply each of them as if they came from separate patch
files. (In this case, the application shall ensure that the name of the
patch file is determinable for each
.IR diff
listing.)
.SH OPTIONS
The
.IR patch
utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 12.2" ", " "Utility Syntax Guidelines".
.P
The following options shall be supported:
.IP "\fB\-b\fP" 10
Save a copy of the original contents of each modified file, before the
differences are applied, in a file of the same name with the suffix
.BR .orig
appended to it. If the file already exists, it shall be overwritten;
if multiple patches are applied to the same file, the
.BR .orig
file shall be written only for the first patch. When the
.BR \-o
.IR outfile
option is also specified,
.IR file \c
.BR .orig
shall not be created but, if
.IR outfile
already exists,
.IR outfile \c
.BR .orig
shall be created.
.IP "\fB\-c\fP" 10
Interpret the patch file as a copied context difference (the output
of the utility
.IR diff
when the
.BR \-c
or
.BR \-C
options are specified).
.IP "\fB\-d\ \fIdir\fR" 10
Change the current directory to
.IR dir
before processing as described in the EXTENDED DESCRIPTION section.
.IP "\fB\-D\ \fIdefine\fR" 10
Mark changes with one of the following C preprocessor constructs:
.RS 10 
.sp
.RS 4
.nf
#ifdef define
\&...
#endif
.P
#ifndef define
\&...
#endif
.fi
.P
.RE
.P
optionally combined with the C preprocessor construct
.BR #else .
If the patched file is processed with the C preprocessor, where the
macro
.IR define
is defined, the output shall contain the changes from the patch file;
otherwise, the output shall not contain the patches specified in the
patch file.
.RE
.IP "\fB\-e\fP" 10
Interpret the patch file as an
.IR ed
script, rather than a
.IR diff
script.
.IP "\fB\-i\ \fIpatchfile\fR" 10
Read the patch information from the file named by the pathname
.IR patchfile ,
rather than the standard input.
.IP "\fB\-l\fP" 10
(The letter ell.) Cause any sequence of
<blank>
characters in the difference script to match any sequence of
<blank>
characters in the input file. Other characters shall be matched exactly.
.IP "\fB\-n\fP" 10
Interpret the script as a normal difference.
.IP "\fB\-N\fP" 10
Ignore patches where the differences have already been applied to the
file; by default, already-applied patches shall be rejected.
.IP "\fB\-o\ \fIoutfile\fR" 10
Instead of modifying the files (specified by the
.IR file
operand or the difference listings) directly, write a copy of the file
referenced by each patch, with the appropriate differences applied, to
.IR outfile .
Multiple patches for a single file shall be applied to the intermediate
versions of the file created by any previous patches, and shall result
in multiple, concatenated versions of the file being written to
.IR outfile .
.IP "\fB\-p\ \fInum\fR" 10
For all pathnames in the patch file that indicate the names of files to
be patched, delete
.IR num
pathname components from the beginning of each pathname. If the
pathname in the patch file is absolute, any leading
<slash>
characters shall be considered the first component (that is,
.BR "\-p\ 1"
shall remove the leading
<slash>
characters). Specifying
.BR "\-p\ 0"
shall cause the full pathname to be used. If
.BR \-p
is not specified, only the basename (the final pathname component)
shall be used.
.IP "\fB\-R\fP" 10
Reverse the sense of the patch script; that is, assume that the
difference script was created from the new version to the old version.
The
.BR \-R
option cannot be used with
.IR ed
scripts. The
.IR patch
utility shall attempt to reverse each portion of the script before
applying it. Rejected differences shall be saved in swapped format. If
this option is not specified, and until a portion of the patch file is
successfully applied,
.IR patch
attempts to apply each portion in its reversed sense as well as in its
normal sense. If the attempt is successful, the user shall be prompted
to determine whether the
.BR \-R
option should be set.
.IP "\fB\-r\ \fIrejectfile\fR" 10
Override the default reject filename. In the default case, the reject
file shall have the same name as the output file, with the suffix
.BR .rej
appended to it; see
.IR "Patch Application".
.IP "\fB\-u\fR" 10
Interpret the patch file as a unified context difference (the output
of the
.IR diff
utility when the
.BR \-u
or
.BR \-U
options are specified).
.SH OPERANDS
The following operand shall be supported:
.IP "\fIfile\fR" 10
A pathname of a file to patch.
.SH STDIN
See the INPUT FILES section.
.SH "INPUT FILES"
Input files shall be text files.
.SH "ENVIRONMENT VARIABLES"
The following environment variables shall affect the execution of
.IR patch :
.IP "\fILANG\fP" 10
Provide a default value for the internationalization variables that are
unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
.IR "Section 8.2" ", " "Internationalization Variables"
the precedence of internationalization variables used to determine the
values of locale categories.)
.IP "\fILC_ALL\fP" 10
If set to a non-empty string value, override the values of all the
other internationalization variables.
.IP "\fILC_COLLATE\fP" 10
.br
Determine the locale for the behavior of ranges, equivalence classes,
and multi-character collating elements used in the extended regular
expression defined for the
.BR yesexpr
locale keyword in the
.IR LC_MESSAGES
category.
.IP "\fILC_CTYPE\fP" 10
Determine the locale for the interpretation of sequences of bytes of text
data as characters (for example, single-byte as opposed to multi-byte
characters in arguments and input files), and the behavior of character
classes used in the extended regular expression defined for the
.BR yesexpr
locale keyword in the
.IR LC_MESSAGES
category.
.IP "\fILC_MESSAGES\fP" 10
.br
Determine the locale used to process affirmative responses, and the
locale used to affect the format and contents of diagnostic messages
and prompts written to standard error.
.IP "\fINLSPATH\fP" 10
Determine the location of message catalogs for the processing of
.IR LC_MESSAGES .
.IP "\fILC_TIME\fP" 10
Determine the locale for recognizing the format of file timestamps
written by the
.IR diff
utility in a context-difference input file.
.SH "ASYNCHRONOUS EVENTS"
Default.
.SH STDOUT
Not used.
.SH STDERR
The standard error shall be used for diagnostic and informational
messages.
.SH "OUTPUT FILES"
The output of the
.IR patch
utility, the save files (\c
.BR .orig
suffixes), and the reject files (\c
.BR .rej
suffixes) shall be text files.
.SH "EXTENDED DESCRIPTION"
A patch file may contain patching instructions for more than one file;
filenames shall be determined as specified in
.IR "Filename Determination".
When the
.BR \-b
option is specified, for each patched file, the original shall be saved
in a file of the same name with the suffix
.BR .orig
appended to it.
.P
For each patched file, a reject file may also be created as noted in
.IR "Patch Application".
In the absence of a
.BR \-r
option, the name of this file shall be formed by appending the suffix
.BR .rej
to the original filename.
.SS "Patch File Format"
.P
The patch file shall contain zero or more lines of header information
followed by one or more patches. Each patch shall contain zero or more
lines of filename identification in the format produced by the
.BR \-c ,
.BR \-C ,
.BR \-u ,
or
.BR \-U
options of the
.IR diff
utility, and one or more sets of
.IR diff
output, which are customarily called \fIhunks\fP.
.P
The
.IR patch
utility shall recognize the following expression in the header
information:
.IP "\fBIndex:\ \fIpathname\fR" 6
.br
The file to be patched is named
.IR pathname .
.P
If all lines (including headers) within a patch begin with the same
leading sequence of
<blank>
characters, the
.IR patch
utility shall remove this sequence before proceeding. Within each
patch, if the type of difference is common context, the
.IR patch
utility shall recognize the following expressions:
.IP "***\ \fIfilename\ timestamp\fR" 6
.br
The patches arose from
.IR filename .
.IP "\-\|\-\|\-\ \fIfilename\ timestamp\fR" 6
.br
The patches should be applied to
.IR filename .
.P
If the type of difference is unified context, the
.IR patch
utility shall recognize the following expressions:
.IP "\-\|\-\|\-\ \fIfilename\ timestamp\fR" 6
.br
The patches arose from
.IR filename .
.IP "+\|+\|+\ \fIfilename\ timestamp\fR" 6
.br
The patches should be applied to
.IR filename .
.P
Each hunk within a patch shall be the
.IR diff
output to change a line range within the original file. The line
numbers for successive hunks within a patch shall occur in ascending
order.
.SS "Filename Determination"
.P
If no
.IR file
operand is specified,
.IR patch
shall perform the following steps to determine the filename to use:
.IP " 1." 4
If the type of
.IR diff
is context, the
.IR patch
utility shall delete pathname components (as specified by the
.BR \-p
option) from the filename on the line beginning with
.BR \(dq***\(dq 
(if copied context) or
.BR \(dq---\(dq 
(if unified context), then test for the existence of this file relative
to the current directory (or the directory specified with the
.BR \-d
option). If the file exists, the
.IR patch
utility shall use this filename.
.IP " 2." 4
If the type of
.IR diff
is context, the
.IR patch
utility shall delete the pathname components (as specified by the
.BR \-p
option) from the filename on the line beginning with
.BR \(dq---\(dq 
(if copied context) or
.BR \(dq+\|+\|+\(dq 
(if unified context), then test for the existence of this file relative
to the current directory (or the directory specified with the
.BR \-d
option). If the file exists, the
.IR patch
utility shall use this filename.
.IP " 3." 4
If the header information contains a line beginning with the string
.BR Index: ,
the
.IR patch
utility shall delete pathname components (as specified by the
.BR \-p
option) from this line, then test for the existence of this file
relative to the current directory (or the directory specified with the
.BR \-d
option). If the file exists, the
.IR patch
utility shall use this filename.
.IP " 4." 4
If an
.BR SCCS
directory exists in the current directory,
.IR patch
shall attempt to perform a
.IR get
.BR \-e
.BR SCCS/s. \c
.IR filename
command to retrieve an editable version of the file. If the file
exists, the
.IR patch
utility shall use this filename.
.IP " 5." 4
The
.IR patch
utility shall write a prompt to standard output and request a filename
interactively from the controlling terminal (for example,
.BR /dev/tty ).
.SS "Patch Application"
.P
If the
.BR \-c ,
.BR \-e ,
.BR \-n ,
or
.BR \-u
option is present, the
.IR patch
utility shall interpret information within each hunk as a copied context
difference, an
.IR ed
difference, a normal difference, or a unified context difference,
respectively. In the absence of any of these options, the
.IR patch
utility shall determine the type of difference based on the format of
information within the hunk.
.P
For each hunk, the
.IR patch
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,
.IR patch
shall scan both forwards and backwards at least 1\|000 bytes for a set
of lines that match the hunk context.
.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
If no location can be found, the
.IR patch
utility shall append the hunk to the reject file. A rejected hunk that
is a copied context difference, an
.IR ed
difference, or a normal difference shall be written in
copied-context-difference format regardless of the format of the patch
file. It is implementation-defined whether a rejected hunk that is
a unified context difference is written in copied-context-difference
format or in unified-context-difference format.
If the input was a normal or
.IR ed -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
If the type of patch is an
.IR ed
diff, the implementation may accomplish the patching by invoking the
.IR ed
utility.
.SH "EXIT STATUS"
The following exit values shall be returned:
.IP "\00" 6
Successful completion.
.IP "\01" 6
One or more lines were written to a reject file.
.IP >1 6
An error occurred.
.SH "CONSEQUENCES OF ERRORS"
Patches that cannot be correctly placed in the file shall be written to
a reject file.
.LP
.IR "The following sections are informative."
.SH "APPLICATION USAGE"
The
.BR \-R
option does not work with
.IR ed
scripts because there is too little information to reconstruct the
reverse operation.
.P
The
.BR \-p
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:
.sp
.RS 4
.nf
/curds/whey/src/blurfl/blurfl.c
.fi
.P
.RE
.P
Setting
.BR "\-p\ 0"
gives the entire pathname unmodified;
.BR "\-p\ 1"
gives:
.sp
.RS 4
.nf
curds/whey/src/blurfl/blurfl.c
.fi
.P
.RE
.P
without the leading
<slash>,
.BR "\-p\ 4"
gives:
.sp
.RS 4
.nf
blurfl/blurfl.c
.fi
.P
.RE
.P
and not specifying
.BR \-p
at all gives:
.sp
.RS 4
.nf
blurfl.c .
.fi
.P
.RE
.SH EXAMPLES
None.
.SH RATIONALE
Some of the functionality in historical
.IR patch
implementations was not specified. The following documents those
features present in historical implementations that have not been
specified.
.P
A deleted piece of functionality was the
.BR '\(pl' 
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
In historical implementations, if the string
.BR \(dqPrereq:\(dq 
appeared in the header, the
.IR patch
utility would search for the corresponding version information (the
string specified in the header, delimited by
<blank>
characters 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:
.sp
.RS 4
.nf
Prereq: 1.2
.fi
.P
.RE
.P
were in the header, the presence of a delimited 1.2 anywhere in the
file would satisfy the prerequisite.
.P
The following options were dropped from historical implementations of
.IR patch
as insufficiently useful to standardize:
.IP "\fB\-b\fP" 10
The
.BR \-b
option historically provided a method for changing the name extension
of the backup file from the default
.BR .orig .
This option has been modified and retained in this volume of POSIX.1\(hy2017.
.IP "\fB\-F\fP" 10
The
.BR \-F
option specified the number of lines of a context diff to ignore when
searching for a place to install a patch.
.IP "\fB\-f\fP" 10
The
.BR \-f
option historically caused
.IR patch
not to request additional information from the user.
.IP "\fB\-r\fP" 10
The
.BR \-r
option historically provided a method of overriding the extension of
the reject file from the default
.BR .rej .
.IP "\fB\-s\fP" 10
The
.BR \-s
option historically caused
.IR patch
to work silently unless an error occurred.
.IP "\fB\-x\fP" 10
The
.BR \-x
option historically set internal debugging flags.
.P
In some file system implementations, the saving of a
.BR .orig
file may produce unwanted results. In the case of 12, 13, or
14-character filenames (on file systems supporting 14-character
maximum filenames), the
.BR .orig
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>
(\c
.BR '\(ti' )
suffix be used instead of
.BR .orig
and some other character instead of the
.BR .rej
suffix. This was rejected because it is not obvious to the user which
file is which. The suffixes
.BR .orig
and
.BR .rej
are clearer and more understandable.
.P
The
.BR \-b
option has the opposite sense in some historical implementations\(emdo
not save the
.BR .orig
file. The default case here is not to save the files, making
.IR patch
behave more consistently with the other standard utilities.
.P
The
.BR \-w
option in early proposals was changed to
.BR \-l
to match historical practice.
.P
The
.BR \-N
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
.IR diff
into the
.IR patch
utility, and the user only wants to patch a file to a newer version
non-interactively, the
.BR \-N
option is required.
.P
Changes to the
.BR \-l
option description were proposed to allow matching across
<newline>
characters in addition to just
<blank>
characters. 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
.BR \-L .
.P
The
.BR \-u
option of GNU
.IR patch
has been added, along with support for unified context formats.
.SH "FUTURE DIRECTIONS"
None.
.SH "SEE ALSO"
.IR "\fIdiff\fR\^",
.IR "\fIed\fR\^"
.P
The Base Definitions volume of POSIX.1\(hy2017,
.IR "Chapter 8" ", " "Environment Variables",
.IR "Section 12.2" ", " "Utility Syntax Guidelines"
.\"
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1-2017, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 7, 2018 Edition,
Copyright (C) 2018 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group.
In the event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online at
http://www.opengroup.org/unix/online.html .
.PP
Any typographical or formatting errors that appear
in this page are most likely
to have been introduced during the conversion of the source files to
man page format. To report such errors, see
https://www.kernel.org/doc/man-pages/reporting_bugs.html .