Import of patch-2.4.tar.gzv2.4

1 files changed, 352 insertions, 155 deletions

diff --git a/patch.man b/patch.man
index a145cf9..13fa1b9 100644
--- a/patch.man
+++ b/patch.man
@@ -2,7 +2,7 @@
 .de Id
 .ds Dt \\$4
 ..
-.Id $Id: patch.man,v 1.16 1997/05/30 08:03:48 eggert Exp $
+.Id $Id: patch.man,v 1.20 1997/06/17 22:32:49 eggert Exp $
 .ds = \-\^\-
 .de Sp
 .if t .sp .3
@@ -20,7 +20,7 @@ patch \- apply a diff file to an original
 .Sp
 but usually just
 .Sp
-.BI "patch \-p" "number"
+.BI "patch \-p" "num"
 .BI < patchfile
 .SH DESCRIPTION
 .B patch
@@ -115,9 +115,6 @@ As each hunk is completed, you are told if the hunk
 failed, and if so which line (in the new file)
 .B patch
 thought the hunk should go on.
-If the
-.B \*=verbose
-option is given, you are also told about hunks that succeeded.
 If the hunk is installed at a different line
 from the line number specified in the diff you
 are told the offset.
@@ -127,38 +124,76 @@ indicate that a hunk was installed in the
 wrong place.
 You are also told if a fuzz factor was used to make the match, in which
 case you should also be slightly suspicious.
+If the
+.B \*=verbose
+option is given, you are also told about hunks that match exactly.
 .PP
 If no original file
 .I origfile
 is specified on the command line,
 .B patch
 tries to figure out from the leading garbage what the name of the file
-to edit is.
+to edit is, using the following rules.
+.TP 3
+.B " \(bu"
 If the header is that of a context diff,
 .B patch
-takes the old and new file names in the header,
-and if there is an
-.B Index:\&
-line in the leading garbage,
-.B patch
-obtains the name in that line; any
+takes the old and new file names in the header.
+Any
 .B /dev/null
 names are ignored.
-These names are considered to be in the order (old, new, index),
+.TP
+.B " \(bu"
+If there is an
+.B Index:\&
+line in the leading garbage
+and if either the old and new names are both absent or the
+.B POSIXLY_CORRECT
+environment variable is set,
+.B patch
+takes the name in the
+.B Index:\&
+line.
+.TP
+.B " \(bu"
+For the purpose of the following rules,
+the names are considered to be in the order (old, new, index),
 regardless of the order that they appear in the header.
+.TP
+.B " \(bu"
 If some of the named files exist,
 .B patch
 uses the first name if the
 .B POSIXLY_CORRECT
 environment variable is set, and the best name otherwise.
-If no named files exist, some names are given,
+.TP
+.B " \(bu"
+If
+.B patch
+is not ignoring \s-1RCS\s0 and \s-1SCCS\s0 (see the
+.BI "\-g " num
+or
+.BI \*=get= num
+option), and no named files exist
+but an \s-1RCS\s0 or \s-1SCCS\s0 master is found,
+.B patch
+uses the first named file with an \s-1RCS\s0 or \s-1SCCS\s0 master.
+.TP
+.B " \(bu"
+If no named files exist, no \s-1RCS\s0 or \s-1SCCS\s0 master was found,
+some names are given,
 .B POSIXLY_CORRECT
 is not set, and the patch appears to create a file,
 .B patch
 uses the best name requiring the creation of the fewest directories.
+.TP
+.B " \(bu"
 If no file name results from the above heuristics, you are asked
 for the name of the file to patch.
-To determine the best of a nonempty list of file names,
+.LP
+To determine the
+.I best
+of a nonempty list of file names,
 .B patch
 first takes all the names with the fewest path name components;
 of those, it then takes all the names with the shortest basename;
@@ -175,22 +210,6 @@ If not,
 .B patch
 asks for confirmation before proceeding.
 .PP
-If an
-\s-1RCS\s0 file is handy,
-and the original file cannot be found
-or is read-only and matches the default version,
-and if version control
-(see the
-.B \-V
-or
-.B \*=version\-control
-option)
-is set to
-.BR existing ,
-.B patch
-attempts to get and lock the file.
-\s-1SCCS\s0 is treated in a similar way.
-.PP
 The upshot of all this is that you should be able to say, while in a news
 interface, something like the following:
 .Sp
@@ -213,20 +232,38 @@ mentioned previously.
 .TP 3
 \fB\-b\fP  or  \fB\*=backup\fP
 Make backup files.
+That is, when patching a file,
+rename or copy the original instead of removing it.
+When backing up a file that does not exist,
+an empty, unreadable backup file is created
+as a placeholder to represent the nonexistent file.
+.Sp
 This option is equivalent to
 .BR \*=version\-control=simple ;
 see the
 .B \-V
 or
 .B \*=version\-control
-option for details.
-In older versions of
-.BR patch ,
-this option had an argument specifying the simple backup suffix;
-this argument has been moved to the
-.B \-z
 option.
 .TP
+.B \*=backup\-if\-mismatch
+Back up a file if the patch does not match the file exactly
+and if backups are not otherwise requested.
+The backup file name is calculated as usual,
+except that if the version control method is
+.BR none ,
+a simple backup name is used.
+This is the default unless the
+.B POSIXLY_CORRECT
+environment variable is set.
+.TP
+.B \*=no\-backup\-if\-mismatch
+Do not back up a file if the patch does not match the file exactly
+and if backups are not otherwise requested.
+This is the default if the
+.B POSIXLY_CORRECT
+environment variable is set.
+.TP
 \fB\-B\fP \fIpref\fP  or  \fB\*=prefix=\fP\fIpref\fP
 Prefix simple backup file names with
 .IR pref .
@@ -249,20 +286,17 @@ the patch should be generated by
 \fB\-c\fP  or  \fB\*=context\fP
 Interpret the patch file as a ordinary context diff.
 .TP
-\fB\*=verbose\fP
-Output extra information about the work being done.
-.TP
 \fB\-d\fP \fIdir\fP  or  \fB\*=directory=\fP\fIdir\fP
 Change to the directory
 .I dir
 immediately, before doing
 anything else.
 .TP
-\fB\-D\fP \fIsym\fP  or  \fB\*=ifdef=\fP\fIsym\fP
+\fB\-D\fP \fIdefine\fP  or  \fB\*=ifdef=\fP\fIdefine\fP
 Use the
 .BR #ifdef " .\|.\|. " #endif
 construct to mark changes, with
-.I sym
+.I define
 as the differentiating symbol.
 .TP
 .B "\*=dry\-run"
@@ -277,7 +311,7 @@ script.
 Remove output files that are empty after the patches have been applied.
 Normally this option is unnecessary, since
 .B patch
-can examine the timestamps on the header to determine whether a file
+can examine the time stamps on the header to determine whether a file
 should exist after patching.
 However, if the input is not a context diff or if the
 .B POSIXLY_CORRECT
@@ -300,7 +334,7 @@ This option does not suppress commentary; use
 .B \-s
 for that.
 .TP
-\fB\-F\fP \fInumber\fP  or  \fB\*=fuzz=\fP\fInumber\fP
+\fB\-F\fP \fInum\fP  or  \fB\*=fuzz=\fP\fInum\fP
 Set the maximum fuzz factor.
 This option only applies to diffs that have context, and causes
 .B patch
@@ -309,19 +343,25 @@ Note that a larger fuzz factor increases the odds of a faulty patch.
 The default fuzz factor is 2, and it may not be set to more than
 the number of lines of context in the context diff, ordinarily 3.
 .TP
-\fB\-g\fP  or  \fB\*=get\fP
-If a file does not exist or is read-only and matches the default version,
-get it from \s-1RCS\s0 if it is under \s-2RCS\s0 control;
-similarly for \s-1SCCS\s0.
-If the
-.B PATCH_GET
-environment variable is set, this is the default.
-.TP
-\fB\-G\fP  or  \fB\*=no\-get\fP
-Do not get files from \s-1RCS\s0 or \s-2SCCS\s0.
-This is the default unless the
+\fB\-g\fP \fInum\fP  or  \fB\*=get=\fP\fInum\fP
+This option controls
+.BR patch 's
+actions when a file is under \s-1RCS\s0 or \s-1SCCS\s0 control,
+and does not exist or is read-only and matches the default version.
+If
+.I num
+is positive,
+.B patch
+gets (or checks out) the file from the revision control system; if zero,
+.B patch
+ignores \s-1RCS\s0 and \s-1SCCS\s0 and does not get the file; and if negative,
+.B patch
+asks the user whether to get the file.
+The default value of this option is given by the value of the
 .B PATCH_GET
-environment variable is set.
+environment variable if it is set; if not, the default value is zero if 
+.B POSIXLY_CORRECT
+is set, negative otherwise.
 .TP
 .B "\*=help"
 Print a summary of options and exit.
@@ -351,14 +391,14 @@ Ignore patches that seem to be reversed or already applied.
 See also
 .BR \-R .
 .TP
-\fB\-o\fP \fIfile\fP  or  \fB\*=output=\fP\fIfile\fP
+\fB\-o\fP \fIoutfile\fP  or  \fB\*=output=\fP\fIoutfile\fP
 Send output to
-.I file
+.I outfile
 instead of patching files in place.
 .TP
-\fB\-p\fP\fInumber\fP  or  \fB\*=strip\fP\fB=\fP\fInumber\fP
+\fB\-p\fP\fInum\fP  or  \fB\*=strip\fP\fB=\fP\fInum\fP
 Strip the smallest prefix containing
-.I number
+.I num
 leading slashes from each file name found in the patch file.
 A sequence of one or more adjacent slashes is counted as a single slash.
 This controls how file names found in the patch file are treated, in case
@@ -389,19 +429,10 @@ Whatever you end up with is looked for either in the current directory,
 or the directory specified by the
 .B \-d
 option.
-With \s-1GNU\s0
-.BR patch ,
-the two-argument
-.BI "\-p " N
-form of this option is equivalent to one-argument
-.BI \-p N
-form, but this is not true of traditional
-.BR patch ,
-so the one-argument form is recommended for portability.
 .TP
-\fB\-r\fP \fIfile\fP  or  \fB\*=reject\-file=\fP\fIfile\fP
+\fB\-r\fP \fIrejectfile\fP  or  \fB\*=reject\-file=\fP\fIrejectfile\fP
 Put rejects into
-.I file
+.I rejectfile
 instead of the default
 .B \&.rej
 file.
@@ -449,6 +480,19 @@ line
 in the patch; and assume that patches are reversed if they look like
 they are.
 .TP
+\fB\-T\fP  or  \fB\*=set\-time\fP
+Set the modification and access times of patched files from time stamps
+given in context diff headers, assuming that the context diff headers
+use local time.  This option is not recommended, because patches using
+local time cannot easily be used by people in other time zones, and
+because local time stamps are ambiguous when local clocks move backwards
+during daylight-saving time adjustments.  Instead of using this option,
+generate patches with \s-1UTC\s0 and use the
+.B \-Z
+or
+.B \*=set\-utc
+option instead.
+.TP
 \fB\-u\fP  or  \fB\*=unified\fP
 Interpret the patch file as a unified context diff.
 .TP
@@ -460,8 +504,8 @@ revision header and patch level, and exit.
 \fB\-V\fP \fImethod\fP  or  \fB\*=version\-control=\fP\fImethod\fP
 Use
 .I method
-when creating
-backup file names.  The type of backups made can also be given in the
+to determine
+backup file names.  The method can also be given by the
 .B PATCH_VERSION_CONTROL
 (or, if that's not set, the
 .BR VERSION_CONTROL )
@@ -484,7 +528,8 @@ Make numbered backups of files that already have them,
 otherwise simple backups.
 .TP
 \fBnone\fP
-Do not make backups.
+Do not make backups, unless backup-if-mismatch is in effect
+and patches do not match files.
 This is the default.
 .TP
 \fBnumbered\fP  or  \fBt\fP
@@ -497,9 +542,7 @@ where
 is the version number.
 .TP
 \fBsimple\fP  or  \fBnever\fP
-Make simple backups.  That is, when patching a file
-.IR F ,
-rename or copy the original instead of removing it.
+Make simple backups.
 The
 .B \-B
 or
@@ -529,7 +572,10 @@ would make the name too long, then
 replaces the last character of the file name.
 .RE
 .TP
-\fB\-x\fP \fInumber\fP  or  \fB\*=debug=\fP\fInumber\fP
+\fB\*=verbose\fP
+Output extra information about the work being done.
+.TP
+\fB\-x\fP \fInum\fP  or  \fB\*=debug=\fP\fInum\fP
 Set internal debugging flags of interest only to
 .B patch
 patchers.
@@ -544,23 +590,72 @@ the backup file name for
 is
 .BR src/patch/.del/util.c .
 .TP
-\fB\-z\fP \fIsuff\fP  or  \fB\*=suffix=\fP\fIsuff\fP
+\fB\-z\fP \fIsuffix\fP  or  \fB\*=suffix=\fP\fIsuffix\fP
 Use
-.I suff
+.I suffix
 as the simple backup suffix.
 The backup extension may also be specified by the
 .B SIMPLE_BACKUP_SUFFIX
 environment variable, which is overridden by this option.
+.TP
+\fB\-Z\fP  or  \fB\*=set\-utc\fP
+Set the modification and access times of patched files from time stamps
+given in context diff headers, assuming that the context diff headers
+use Coordinated Universal Time (\s-1UTC\s0, often known as \s-1GMT\s0).
+Also see the
+.B \-T
+or
+.B \*=set\-time
+option.
+.Sp
+The
+.B \-Z
+or
+.B \*=set\-utc
+and
+.B \-T
+or
+.B \*=set\-time
+options normally refrain from setting a file's time if the file's original time
+does not match the time given in the patch header, or if its
+contents do not match the patch exactly.  However, if the
+.B \-f
+or
+.B \*=force
+option is given, the file time is set regardless.
+.Sp
+Due to the limitations of
+.B diff
+output format, these options cannot update the times of files whose
+contents have not changed.  Also, if you use these options, you should remove
+(e.g. with
+.BR "make\ clean" )
+all files that depend on the patched files, so that later invocations of
+.B make
+do not get confused by the patched files' times.
 .SH ENVIRONMENT
 .TP 3
+\fBPATCH_GET\fP
+This specifies whether
+.B patch
+gets missing or read-only files from \s-1RCS\s0 or \s-1SCCS\s0
+by default; see the
+.B \-g
+or
+.B \*=get
+option.
+.TP
 .B POSIXLY_CORRECT
 If set,
 .B patch
 conforms more strictly to the \s-1POSIX\s0 standard:
-it takes the first existing file when intuiting file names from diff headers,
+it takes the first existing file from the list (old, new, index)
+when intuiting file names from diff headers,
 it does not remove files that are empty after patching,
-and it requires that all options precede the
-files in the command line.
+it does not ask whether to get files from \s-1RCS\s0 or \s-1SCCS\s0,
+it requires that all options precede the
+files in the command line,
+and by default it does not make backup files.
 .TP
 .B SIMPLE_BACKUP_SUFFIX
 Extension to use for simple backup file names instead of
@@ -575,33 +670,19 @@ it is normally
 .B /tmp
 on Unix hosts.
 .TP
-\fBPATCH_VERSION_CONTROL\fP or \fBVERSION_CONTROL\fP
+\fBVERSION_CONTROL\fP or \fBPATCH_VERSION_CONTROL\fP
 Selects version control style; see the
 .B \-v
 or
 .B \*=version\-control
 option.
-.TP
-\fBPATCH_GET\fP
-If set,
-.B patch
-gets missing or read-only files from \s-1RCS\s0 or \s-1SCCS\s0
-by default; see the
-.B \-g
-or
-.B \*= get
-and the
-.B \-G
-or
-.B \*= no\-get
-options.
 .SH FILES
 .TP 3
 .IB $TMPDIR "/p\(**"
 temporary files
 .TP
 .B /dev/tty
-console; used to get answers to questions asked of the user
+controlling terminal; used to get answers to questions asked of the user
 .SH "SEE ALSO"
 .BR diff (1),
 .BR ed (1)
@@ -622,9 +703,18 @@ The names
 and
 .I new
 should not contain any slashes.
-Here is an example:
+The
+.B diff
+command's headers should have dates
+and times in Universal Time using traditional Unix format,
+so that patch recipients can use the
+.B \-Z
+or
+.B \*=set\-utc
+option.
+Here is an example command, using Bourne shell syntax:
 .Sp
-	\fBdiff \-Naur version\-2.2 version\-2.3\fP
+	\fBLC_ALL=C TZ=UTC0 diff \-Naur gcc\-2.7 gcc\-2.8\fP
 .PP
 Tell your recipients how to apply the patch
 by telling them which directory to
@@ -646,19 +736,14 @@ If you put a
 line in with the patch, it won't let them apply
 patches out of order without some warning.
 .PP
-Make sure you've specified the file names right, either in a
-context diff header, or with an
-.B Index:\&
-line.
-.PP
-You can create a file by sending out a diff that compares an
-empty file (such as
-.BR /dev/null )
+You can create a file by sending out a diff that compares
+.B /dev/null
+or an empty file dated the Epoch (1970-01-01 00:00:00 \s-1UTC\s0)
 to the file you want to create.
 This only works if the file you want to create doesn't exist already in
 the target directory.
-Conversely, you can remove a file by sending out a diff that compares the
-file to be deleted with an empty file.
+Conversely, you can remove a file by sending out a context diff that compares
+the file to be deleted with an empty file dated the Epoch.
 The file will be removed unless the
 .B POSIXLY_CORRECT
 environment variable is set and the
@@ -669,6 +754,8 @@ option is not given.
 An easy way to generate patches that create and remove files
 is to use \s-1GNU\s0
 .BR diff 's
+.B \-N
+or
 .B \*=new\-file
 option.
 .PP
@@ -723,49 +810,14 @@ where there is a line
 in your makefile), since the recipient should be
 able to regenerate the derived files anyway.
 If you must send diffs of derived files,
-ensure that the diffs for each derived file
-follow the diffs for the files that it depends on,
-so that the dependencies will be preserved as
-.B patch
-updates the files one by one.
-Here is a sample shell script that output patches in an order that
-should preserve dependencies:
-.nf
-.Sp
-.ft B
-.in +3n
-#! /bin/sh
-.Sp
-.ne 2
-old=${1?}
-new=${2?}
-.Sp
-.ne 10
-fs=
-for f in `
-  diff \-Nqr $old $new |
-  sed \-e "s,.\(** $new/,," \-e 's, differ$,,'`
-do
-  if [ \-f $new/$f ]
-  then fs="$fs $f"
-  else diff \-au $old/$f /dev/null
-  fi
-done
-.Sp
-.ne 10
-case $fs in
-?\(**)
-  for f in `cd $new; ls \-rt $fs`
-  do
-    if [ \-f $old/$f ]
-    then diff \-au $old/$f $new/$f
-    else diff \-au /dev/null $new/$f
-    fi
-  done
-esac
-.in
-.ft
-.fi
+generate the diffs using \s-1UTC\s0,
+have the recipients apply the patch with the
+.B \-Z
+or
+.B \*=set\-utc
+option, and have them remove any unpatched files that depend on patched files
+(e.g. with
+.BR "make\ clean" ).
 .PP
 While you may be able to get away with putting 582 diff listings into
 one file, it may be wiser to group related patches into separate files in
@@ -817,6 +869,150 @@ guessing.
 However, the results are guaranteed to be correct only when the patch is
 applied to exactly the same version of the file that the patch was
 generated from.
+.SH "COMPATIBILITY ISSUES"
+The \s-1POSIX\s0 standard specifies behavior that differs from
+.BR patch 's
+traditional behavior.
+You should be aware of these differences if you must interoperate with
+.B patch
+versions 2.1 and earlier, which are not \s-1POSIX\s0-compliant.
+.TP 3
+.B " \(bu"
+In traditional
+.BR patch ,
+the
+.B \-p
+option's operand was optional, and a bare
+.B \-p
+was equivalent to
+.BR \-p0.
+The
+.B \-p
+option now requires an operand, and
+.B "\-p\ 0"
+is now equivalent to
+.BR \-p0 .
+For maximum compatibility, use options like
+.B \-p0
+and
+.BR \-p1 .
+.Sp
+Also,
+traditional
+.B patch
+simply counted slashes when stripping path prefixes;
+.B patch
+now counts pathname components.
+That is, a sequence of one or more adjacent slashes
+now counts as a single slash.
+For maximum portability, avoid sending patches containing
+.B //
+in file names.
+.TP
+.B " \(bu"
+In traditional
+.BR patch ,
+simple backups were enabled by default.
+This behavior is now enabled with the
+.B \-b
+or
+.B \*=backup
+option, or by setting the
+.B VERSION_CONTROL
+environment variable to
+.BR simple .
+.Sp
+Conversely, in \s-1POSIX\s0
+.BR patch ,
+backups are never made, even when there is a mismatch.
+In \s-1GNU\s0
+.BR patch ,
+this behavior is enabled with the
+.B \*=no\-backup\-if\-mismatch
+option or by setting the
+.B POSIXLY_CORRECT
+environment variable.
+.Sp
+The
+.BI \-b " suffix"
+option
+of traditional
+.B patch
+is equivalent to the
+.BI "\-b \-z" " suffix"
+options of \s-1GNU\s0
+.BR patch .
+.TP
+.B " \(bu"
+Traditional
+.B patch
+used a complicated (and incompletely documented) method
+to intuit the name of the file to be patched from the patch header.
+This method was not \s-1POSIX\s0-compliant, and had a few gotchas.
+Now
+.B patch
+uses a different, equally complicated (but better documented) method
+that is optionally \s-1POSIX\s0-compliant; we hope it has
+fewer gotchas.  The two methods are compatible if the
+file names in the context diff header and the
+.B Index:\&
+line are all identical after prefix-stripping.
+Your patch is normally compatible if each header's file names
+all contain the same number of slashes.
+.TP
+.B " \(bu"
+When traditional
+.B patch
+asked the user a question, it sent the question to standard error
+and looked for an answer from
+the first file in the following list that was a terminal:
+standard error, standard output,
+.BR /dev/tty ,
+and standard input.
+Now
+.B patch
+sends questions to standard output and gets answers from
+.BR /dev/tty .
+Defaults for some answers have been changed so that
+.B patch
+never goes into an infinite loop when using default answers.
+.TP
+.B " \(bu"
+Traditional
+.B patch
+exited with a status value that counted the number of bad hunks,
+or with status 1 if there was real trouble.
+Now
+.B patch
+exits with status 1 if some hunks failed,
+or with 2 if there was real trouble.
+.TP
+.B " \(bu"
+Limit yourself to the following options when sending instructions
+meant to be executed by anyone running \s-1GNU\s0
+.BR patch ,
+traditional
+.BR patch ,
+or a \s-1POSIX\s0-compliant
+.BR patch .
+Spaces are significant in the following list, and operands are required.
+.Sp
+.nf
+.in +3
+.ne 11
+.B \-c
+.BI \-d " dir"
+.BI \-D " define"
+.B \-e
+.B \-l
+.B \-n
+.B \-N
+.BI \-o " outfile"
+.BI \-p num
+.B \-R
+.BI \-r " rejectfile"
+.in
+.fi
 .SH BUGS
 .B patch
 could be smarter about partial matches, excessively deviant offsets and
@@ -860,7 +1056,8 @@ Larry Wall wrote the original version of
 .BR patch .
 Paul Eggert removed
 .BR patch 's
-arbitrary limits, added support for binary files,
+arbitrary limits; added support for binary files,
+setting file times, and deleting files;
 and made it conform better to \s-1POSIX\s0.
 Other contributors include Wayne Davison, who added unidiff support,
 and David MacKenzie, who added configuration and backup support.