1 files changed, 509 insertions, 0 deletions
diff --git a/man1p/patch.1p b/man1p/patch.1p
new file mode 100644
index 000000000..7bd5bc260
--- /dev/null
+++ b/man1p/patch.1p
@@ -0,0 +1,509 @@
+.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
+.TH "PATCH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\" patch 
+.SH NAME
+patch \- apply changes to files
+.SH SYNOPSIS
+.LP
+\fBpatch\fP \fB[\fP\fB-blNR\fP\fB][\fP \fB-c| -e| -n\fP\fB][\fP\fB-d\fP
+\fIdir\fP\fB][\fP\fB-D\fP \fIdefine\fP\fB][\fP\fB-i\fP \fIpatchfile\fP\fB]
+.br
+\fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-o\fP \fIoutfile\fP\fB][\fP\fB-p\fP
+\fInum\fP\fB][\fP\fB-r\fP \fIrejectfile\fP\fB][\fP\fIfile\fP\fB]\fP\fB\fP
+.SH DESCRIPTION
+.LP
+The \fIpatch\fP utility shall read a source (patch) file containing
+any of the three forms of difference (diff) listings
+produced by the \fIdiff\fP utility (normal, context, or in the style
+of \fIed\fP) and apply those differences to a file. By default, \fIpatch\fP
+shall read from the standard
+input.
+.LP
+The \fIpatch\fP utility shall attempt to determine the type of the
+\fIdiff\fP listing,
+unless overruled by a \fB-c\fP, \fB-e\fP, or \fB-n\fP option.
+.LP
+If the patch file contains more than one patch, \fIpatch\fP 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 \fIdiff\fP listing.)
+.SH OPTIONS
+.LP
+The \fIpatch\fP utility shall conform to the Base Definitions volume
+of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
+.LP
+The following options shall be supported:
+.TP 7
+\fB-b\fP
+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 \fB.orig\fP appended to it. If the file already exists,
+it shall be overwritten; if multiple patches are applied to the
+same file, the \fB.orig\fP file shall be written only for the first
+patch. When the \fB-o\fP \fIoutfile\fP option is also
+specified, \fIfile\fP \fB.orig\fP shall not be created but, if \fIoutfile\fP
+already exists, \fIoutfile\fP \fB.orig\fP shall
+be created.
+.TP 7
+\fB-c\fP
+Interpret the patch file as a context difference (the output of the
+utility \fIdiff\fP
+when the \fB-c\fP or \fB-C\fP options are specified).
+.TP 7
+\fB-d\ \fP \fIdir\fP
+Change the current directory to \fIdir\fP before processing as described
+in the EXTENDED DESCRIPTION section.
+.TP 7
+\fB-D\ \fP \fIdefine\fP
+Mark changes with one of the following C preprocessor constructs:
+.sp
+.RS
+.nf
+
+\fB#ifdef define
+\&...
+#endif
+.sp
+
+#ifndef define
+\&...
+#endif
+\fP
+.fi
+.RE
+.LP
+optionally combined with the C preprocessor construct \fB#else\fP.
+If the patched file is processed with the C preprocessor,
+where the macro \fIdefine\fP 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.
+.TP 7
+\fB-e\fP
+Interpret the patch file as an \fIed\fP script, rather than a \fIdiff\fP
+script.
+.TP 7
+\fB-i\ \fP \fIpatchfile\fP
+Read the patch information from the file named by the pathname \fIpatchfile\fP,
+rather than the standard input.
+.TP 7
+\fB-l\fP
+(The letter ell.) Cause any sequence of <blank>s in the difference
+script to match any sequence of <blank>s in the
+input file. Other characters shall be matched exactly.
+.TP 7
+\fB-n\fP
+Interpret the script as a normal difference.
+.TP 7
+\fB-N\fP
+Ignore patches where the differences have already been applied to
+the file; by default, already-applied patches shall be
+rejected.
+.TP 7
+\fB-o\ \fP \fIoutfile\fP
+Instead of modifying the files (specified by the \fIfile\fP operand
+or the difference listings) directly, write a copy of the
+file referenced by each patch, with the appropriate differences applied,
+to \fIoutfile\fP. 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 \fIoutfile\fP.
+.TP 7
+\fB-p\ \fP \fInum\fP
+For all pathnames in the patch file that indicate the names of files
+to be patched, delete \fInum\fP pathname components from
+the beginning of each pathname. If the pathname in the patch file
+is absolute, any leading slashes shall be considered the first
+component (that is, \fB-p\ 1\fP shall remove the leading slashes).
+Specifying \fB-p\ 0\fP shall cause the full pathname
+to be used. If \fB-p\fP is not specified, only the basename (the final
+pathname component) shall be used.
+.TP 7
+\fB-R\fP
+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 \fB-R\fP option cannot be used with \fIed\fP scripts.
+The \fIpatch\fP 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, \fIpatch\fP 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 \fB-R\fP option should be set.
+.TP 7
+\fB-r\ \fP \fIrejectfile\fP
+Override the default reject filename. In the default case, the reject
+file shall have the same name as the output file, with
+the suffix \fB.rej\fP appended to it; see Patch Application .
+.sp
+.SH OPERANDS
+.LP
+The following operand shall be supported:
+.TP 7
+\fIfile\fP
+A pathname of a file to patch.
+.sp
+.SH STDIN
+.LP
+See the INPUT FILES section.
+.SH INPUT FILES
+.LP
+Input files shall be text files.
+.SH ENVIRONMENT VARIABLES
+.LP
+The following environment variables shall affect the execution of
+\fIpatch\fP:
+.TP 7
+\fILANG\fP
+Provide a default value for the internationalization variables that
+are unset or null. (See the Base Definitions volume of
+IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
+for
+the precedence of internationalization variables used to determine
+the values of locale categories.)
+.TP 7
+\fILC_ALL\fP
+If set to a non-empty string value, override the values of all the
+other internationalization variables.
+.TP 7
+\fILC_CTYPE\fP
+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).
+.TP 7
+\fILC_MESSAGES\fP
+Determine the locale that should be used to affect the format and
+contents of diagnostic messages written to standard error and
+informative messages written to standard output.
+.TP 7
+\fINLSPATH\fP
+Determine the location of message catalogs for the processing of \fILC_MESSAGES
+\&.\fP 
+.TP 7
+\fILC_TIME\fP
+Determine the locale for recognizing the format of file timestamps
+written by the \fIdiff\fP utility in a context-difference input file.
+.sp
+.SH ASYNCHRONOUS EVENTS
+.LP
+Default.
+.SH STDOUT
+.LP
+Not used.
+.SH STDERR
+.LP
+The standard error shall be used for diagnostic and informational
+messages.
+.SH OUTPUT FILES
+.LP
+The output of the \fIpatch\fP utility, the save files ( \fB.orig\fP
+suffixes), and the reject files ( \fB.rej\fP suffixes)
+shall be text files.
+.SH EXTENDED DESCRIPTION
+.LP
+A patch file may contain patching instructions for more than one file;
+filenames shall be determined as specified in Filename Determination
+\&. When the \fB-b\fP option is specified, for each patched file, the
+original shall
+be saved in a file of the same name with the suffix \fB.orig\fP appended
+to it.
+.LP
+For each patched file, a reject file may also be created as noted
+in Patch Application . In the
+absence of a \fB-r\fP option, the name of this file shall be formed
+by appending the suffix \fB.rej\fP to the original
+filename.
+.SS Patch File Format
+.LP
+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 \fIdiff\fP \fB-c\fP,
+and one or more sets of \fIdiff\fP output, which are customarily called
+\fIhunks\fP.
+.LP
+The \fIpatch\fP utility shall recognize the following expression in
+the header information:
+.TP 7
+\fBIndex:\ \fP \fIpathname\fP
+.sp
+The file to be patched is named \fIpathname\fP.
+.sp
+.LP
+If all lines (including headers) within a patch begin with the same
+leading sequence of <blank>s, the \fIpatch\fP utility
+shall remove this sequence before proceeding. Within each patch, if
+the type of difference is context, the \fIpatch\fP utility
+shall recognize the following expressions:
+.TP 7
+***\ \fIfilename\ timestamp\fP
+.sp
+The patches arose from \fIfilename\fP.
+.TP 7
+---\ \fIfilename\ timestamp\fP
+.sp
+The patches should be applied to \fIfilename\fP.
+.sp
+.LP
+Each hunk within a patch shall be the \fIdiff\fP 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
+.LP
+If no \fIfile\fP operand is specified, \fIpatch\fP shall perform the
+following steps to determine the filename to use:
+.IP " 1." 4
+If the type of \fIdiff\fP is context, the \fIpatch\fP utility shall
+delete pathname
+components (as specified by the \fB-p\fP option) from the filename
+on the line beginning with \fB"***"\fP , then test for the
+existence of this file relative to the current directory (or the directory
+specified with the \fB-d\fP option). If the file
+exists, the \fIpatch\fP utility shall use this filename.
+.LP
+.IP " 2." 4
+If the type of \fIdiff\fP is context, the \fIpatch\fP utility shall
+delete the pathname
+components (as specified by the \fB-p\fP option) from the filename
+on the line beginning with \fB"---"\fP , then test for the
+existence of this file relative to the current directory (or the directory
+specified with the \fB-d\fP option). If the file
+exists, the \fIpatch\fP utility shall use this filename.
+.LP
+.IP " 3." 4
+If the header information contains a line beginning with the string
+\fBIndex:\fP, the \fIpatch\fP utility shall delete
+pathname components (as specified by the \fB-p\fP option) from this
+line, then test for the existence of this file relative to the
+current directory (or the directory specified with the \fB-d\fP option).
+If the file exists, the \fIpatch\fP utility shall use
+this filename.
+.LP
+.IP " 4." 4
+If an \fBSCCS\fP directory exists in the current directory, \fIpatch\fP
+shall attempt to perform a \fIget\fP \fB-e\fP \fBSCCS/s.\fP \fIfilename\fP
+command to retrieve an editable version of the
+file. If the file exists, the \fIpatch\fP utility shall use this filename.
+.LP
+.IP " 5." 4
+The \fIpatch\fP utility shall write a prompt to standard output and
+request a filename interactively from the controlling
+terminal (for example, \fB/dev/tty\fP).
+.LP
+.SS Patch Application
+.LP
+If the \fB-c\fP, \fB-e\fP, or \fB-n\fP option is present, the \fIpatch\fP
+utility shall interpret information within each
+hunk as a context difference, an \fIed\fP difference, or a normal
+difference, respectively. In
+the absence of any of these options, the \fIpatch\fP utility shall
+determine the type of difference based on the format of
+information within the hunk.
+.LP
+For each hunk, the \fIpatch\fP 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, \fIpatch\fP shall scan both forwards and backwards at least
+1000 bytes for a set of lines that match the hunk context.
+.LP
+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.
+.LP
+If no location can be found, the \fIpatch\fP 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 \fIed\fP-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.
+.LP
+If the type of patch is an \fIed\fP diff, the implementation may accomplish
+the patching by
+invoking the \fIed\fP utility.
+.SH EXIT STATUS
+.LP
+The following exit values shall be returned:
+.TP 7
+\ 0
+Successful completion.
+.TP 7
+\ 1
+One or more lines were written to a reject file.
+.TP 7
+>1
+An error occurred.
+.sp
+.SH CONSEQUENCES OF ERRORS
+.LP
+Patches that cannot be correctly placed in the file shall be written
+to a reject file.
+.LP
+\fIThe following sections are informative.\fP
+.SH APPLICATION USAGE
+.LP
+The \fB-R\fP option does not work with \fIed\fP scripts because there
+is too little
+information to reconstruct the reverse operation.
+.LP
+The \fB-p\fP 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
+.nf
+
+\fB/curds/whey/src/blurfl/blurfl.c
+\fP
+.fi
+.RE
+.LP
+Setting \fB-p\ 0\fP gives the entire pathname unmodified; \fB-p\ 1\fP
+gives:
+.sp
+.RS
+.nf
+
+\fBcurds/whey/src/blurfl/blurfl.c
+\fP
+.fi
+.RE
+.LP
+without the leading slash, \fB-p\ 4\fP gives:
+.sp
+.RS
+.nf
+
+\fBblurfl/blurfl.c
+\fP
+.fi
+.RE
+.LP
+and not specifying \fB-p\fP at all gives:
+.sp
+.RS
+.nf
+
+\fBblurfl.c .
+\fP
+.fi
+.RE
+.SH EXAMPLES
+.LP
+None.
+.SH RATIONALE
+.LP
+Some of the functionality in historical \fIpatch\fP implementations
+was not specified. The following documents those features
+present in historical implementations that have not been specified.
+.LP
+A deleted piece of functionality was the \fB'+'\fP 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.
+.LP
+In historical implementations, if the string \fB"Prereq:"\fP appeared
+in the header, the \fIpatch\fP utility would search
+for the corresponding version information (the string specified in
+the header, delimited by <blank>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:
+.sp
+.RS
+.nf
+
+\fBPrereq: 1.2
+\fP
+.fi
+.RE
+.LP
+were in the header, the presence of a delimited 1.2 anywhere in the
+file would satisfy the prerequisite.
+.LP
+The following options were dropped from historical implementations
+of \fIpatch\fP as insufficiently useful to standardize:
+.TP 7
+\fB-b\fP
+The \fB-b\fP option historically provided a method for changing the
+name extension of the backup file from the default
+\fB\&.orig\fP. This option has been modified and retained in this volume
+of IEEE\ Std\ 1003.1-2001.
+.TP 7
+\fB-F\fP
+The \fB-F\fP option specified the number of lines of a context diff
+to ignore when searching for a place to install a
+patch.
+.TP 7
+\fB-f\fP
+The \fB-f\fP option historically caused \fIpatch\fP not to request
+additional information from the user.
+.TP 7
+\fB-r\fP
+The \fB-r\fP option historically provided a method of overriding the
+extension of the reject file from the default
+\fB\&.rej\fP.
+.TP 7
+\fB-s\fP
+The \fB-s\fP option historically caused \fIpatch\fP to work silently
+unless an error occurred.
+.TP 7
+\fB-x\fP
+The \fB-x\fP option historically set internal debugging flags.
+.sp
+.LP
+In some file system implementations, the saving of a \fB.orig\fP file
+may produce unwanted results. In the case of 12, 13, or
+14-character filenames (on file systems supporting 14-character maximum
+filenames), the \fB.orig\fP 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 (
+\fB'~'\fP ) suffix be used instead of \fB.orig\fP and some other character
+instead of the \fB.rej\fP suffix. This was
+rejected because it is not obvious to the user which file is which.
+The suffixes \fB.orig\fP and \fB.rej\fP are clearer and more
+understandable.
+.LP
+The \fB-b\fP option has the opposite sense in some historical implementations-do
+not save the \fB.orig\fP file. The default
+case here is not to save the files, making \fIpatch\fP behave more
+consistently with the other standard utilities.
+.LP
+The \fB-w\fP option in early proposals was changed to \fB-l\fP to
+match historical practice.
+.LP
+The \fB-N\fP 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 \fIdiff\fP into the
+\fIpatch\fP utility, and
+the user only wants to patch a file to a newer version non-interactively,
+the \fB-N\fP option is required.
+.LP
+Changes to the \fB-l\fP option description were proposed to allow
+matching across <newline>s in addition to just
+<blank>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 \fB-L\fP.
+.SH FUTURE DIRECTIONS
+.LP
+None.
+.SH SEE ALSO
+.LP
+\fIed\fP , \fIdiff\fP
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 6, Copyright (C) 2001-2003 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 .