unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



patch(1)							     patch(1)



NAME

  patch	- Applies changes to files

SYNOPSIS

  patch	[-bflsvNRS] [-c	 | -e  | -n] [-B prefix] [-d directory]	[-D define]
  [-F] [number]	[-i patchfile] [-o outfile] [-p	number]	[-r rejectfile]
  [original_file] [patchfile] [+] [flags] [original_file]

  The patch command takes a patch file that contains any of the	three forms
  of difference	listing	produced by the	diff program (normal, context, or
  ed-style) and	applies	those differences to an	original file, producing a
  patched version.

STANDARDS

  Interfaces documented	on this	reference page conform to industry standards
  as follows:

  patch:  XCU5.0

  Refer	to the standards(5) reference page for more information	about indus-
  try standards	and associated tags.

OPTIONS

  -b  Saves 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
      .orig appended to	it.  If	the file already exists, it is overwritten.
      If multiple patches are applied to the same file,	the .orig file is
      written only for the first patch.	 If -o outfile is also specified,
      patchfile.orig will not be created, but if outfile already exists,
      outfile.orig is created.

  -B prefix
      [Tru64 UNIX]  Specifies a	prefix to the backup file name.

  -c  Interprets the patch file	as a context diff (the output of diff when -c
      or -C is specified).

  -d directory
      Changes the current directory to directory before	processing.

  -D define
      Uses the C preprocessor #ifdef define ...	 #endif	construct to mark
      changes.	The define argument is used as the differentiating symbol.

  -e  Interprets the patch file	as an ed script, rather	than as	a diff
      script.

  -f  [Tru64 UNIX]  Suppresses queries to the user.  To	suppress commentary,
      use the -s option.

  -F[number]
      [Tru64 UNIX]  Sets the maximum fuzz factor.  This	option applies to
      context diffs only, and causes patch to ignore up	to the specified
      number of	lines when determining where to	install	a hunk.	 If the	-F
      option is	not specified, the default fuzz	factor is 2.  If the -F
      option is	specified without a number argument, the fuzz factor is	taken
      to be 0 (zero).  The factor may not be set to more than the number of
      lines of context in the context diff (ordinarily 3).

      [Tru64 UNIX]  Note that a	larger fuzz factor increases the odds of a
      faulty patch.

  -i patchfile
      Reads the	patch information from the file	named by the specified patch-
      file, rather than	from standard input.

  -l  Causes any sequence of spaces and	tabs (whitespace) in the diff script
      to match any sequence of spaces in the input file.  Other	characters
      will be matched exactly.

  -n  Interprets the script as a normal	diff.

  -N  Ignores patches where the	differences have already been applied to the
      file; by default,	already-applied	patches	are rejected. (See the -R
      option.)

  -o outfile
      Instead of modifying the files (specified	by the patchfile argument or
      the diff listings) directly, write a copy	of the file referenced by
      each patch, with the appropriate differences applied, to outfile.	 Mul-
      tiple patches for	a single file are applied to the intermediate ver-
      sions of the file	created	by any previous	patches, and result in multi-
      ple, concatenated	versions of the	file written to	outfile.

  -p number
      Sets the path name strip count, which controls how path names found in
      the patch	file are treated.  This	option is useful if you	keep your
      files in a different directory than that specified by the	patch.	The
      strip count specifies how	many slashes are to be stripped	from the
      front of the path	name. Any intervening directory	names are also
      stripped.

      For example, if the file name in the patch file was
      /u/howard/src/blurfl/blurfl.c, entering -p0 leaves the entire path name
      unmodified.  Entering -p1	results	in u/howard/src/blurfl/blurfl.c
      without the leading slash.  Entering -p4 results in blurfl/blurfl.c.
      Omitting -p from the patch command line, results in blurfl.c.

      The patch	command	looks for the resulting	path name in the current
      directory, or in the directory specified by the -d option.

  -r rejectfile
      Specifies	the reject file	name.  By default, the reject file name	has
      the same name as the output file,	with the suffix	.rej appended to it.

  -R  Reverses the sense of the	patch script; that is, patch assumes that the
      diff script was created from the new version to the old version.	The
      patch command tries to reverse each portion of the script	before apply-
      ing it.  Rejected	differences are	saved in swapped format.  The -R
      option cannot be used with ed scripts because there is too little
      information to reconstruct the reverse operation.

      If this option is	not specified, and until a portion of the patch	file
      is successfully applied, patch tries to apply each portion in its
      reversed sense as	well as	in its normal sense.  If the attempt is
      successful, you are prompted to determine	if -R should be	set.

      Note that	this method cannot detect a reversed patch if it is a normal
      diff and if the first command is an append (that is, it should have
      been a delete), since appends always succeed because a NULL context
      matches anywhere.	 Luckily, most patches add or change lines rather
      than delete them,	so most	reversed normal	diffs begin with a delete,
      which will fail, triggering the heuristic.)

  -s  [Tru64 UNIX]  Patches silently unless an error occurs.

  -S  [Tru64 UNIX]  Ignores a patch from the patch file, but continues look-
      ing for the next patch in	the file.  Thus,
	   patch -S + -S + <&lt;patchfile

      ignores the first	and second patches in patchfile	(see the description
      of the + offset that follows).

  -v  [Tru64 UNIX]  Prints out the revision header and patch level.

  -xnumber
      [Tru64 UNIX]  Sets internal debugging flags.  (This option is of
      interest only to patch patchers.)

  + flags [original_file]
      [Tru64 UNIX]  Specifies flags (and possibly another original file	name)
      for the second and subsequent patches.  The argument list	for each
      patch must be preceded with a +.	(Note, however,	that the argument
      list for a second	or subsequent patch may	not specify a new patch
      file.)

OPERANDS

  originalfile
      The file to be patched.

DESCRIPTION

  By default, the patched version is put in place of the original.  The	ori-
  ginal	file can be backed up to the same name with the	extension .orig	by
  using	the -b option.	You may	also specify where you want the	output to go
  with the -o option.  If the -i patchfile option is not specified, or if
  patchfile is a - (dash), the patch is	read from standard input.

  The patch command attempts to	determine the type of the diff listing,
  unless it is overruled by a -c, -e, or -n option, which specify context,
  ed, and normal diffs,	respectively.  Context diffs and normal	diffs are
  applied by the patch program itself, while ed	diffs are fed to the ed	edi-
  tor by means of a pipe.

  The patch file must contain zero or more lines of header information fol-
  lowed	by one or more patches.	 Each patch must contain zero or more lines
  of file name identification in the format produced by	diff -c, and one or
  more sets of diff output, which are customarily called "hunks".

  The patch command tries to skip any leading text, apply the diff, and	then
  skip any trailing text.  Thus, you could feed	an article or message con-
  taining a diff listing to patch, and it would	work.  If the entire diff is
  indented by a	consistent amount, patch takes this into account.

  If no	original file is specified on the command line,	patch tries to figure
  out the name of the file to edit from	the leading text.  In the header of a
  context diff,	the file name is found from lines beginning with *** (the
  name of the file from	which the patches arose) or ---	(the name of the file
  to which the patches should be applied), with	the shortest name of an
  existing file	being selected.	 If there is an	Index: line in the leading
  text,	patch tries to use the file name from that line.  The context diff
  header takes precedence over an Index: line. If no file name can be deter-
  mined	from the leading text, patch asks you for the name of the file to
  patch.


  If the original file cannot be found,	but a suitable SCCS or RCS file	is
  available, patch attempts to get or check out	the file.

  Additionally,	if the leading text contains a Prereq: line, patch takes the
  first	word from the prerequisites line (normally a version number) and
  checks the input file	to see if that word can	be found.  If not, patch asks
  for confirmation before proceeding.

  If the patch file contains more than one patch, patch	tries to apply each
  of them as if	they came from separate	patch files.  In this case, the	name
  of the file to patch must be determined for each diff	listing, and the
  header text before each diff listing is examined for information such	as
  file names and revision level.  You can give options (and another original
  file name) for the second and	subsequent patches by separating the
  corresponding	argument lists with a +.

  For each hunk, patch takes the line number mentioned for the hunk, plus or
  minus	any offset used	in applying the	previous hunk.	If that	is not the
  correct place, patch scans both forwards and backwards for a set of lines
  matching the context given in	the hunk.  The patch command looks for a
  place	where all lines	of the context match.

  If no	such place is found, and patch is performing a context diff, and the
  maximum fuzz factor is set to	1 or more, patch performs another scan that
  ignores the first and	last line of context.  If that scan fails, and the
  maximum fuzz factor is set to	2 or more, patch ignores the first two and
  last two lines of context, and makes another scan.  (The default maximum
  fuzz factor is 2.)

  If patch cannot find a place to install that hunk of the patch, it places
  the hunk in a	reject file (normally, with the	same name as the output	file
  and the suffix .rej).	 The rejected hunk is written in context diff form,
  regardless of	the format of the patch	file.  If the input was	a normal or
  ed-style diff, the reject file may contain diffs with	zero lines of con-
  text.	 The line numbers on the hunks in the reject file may be different
  from the line	numbers	in the patch file; the reject file line	numbers
  reflect the approximate locations for	the failed hunks in the	new file
  rather than the old one.

  As each hunk is completed, patch tells you whether the hunk succeeded	or
  failed, and on which line in the new file patch assumed the hunk should go.
  If this is different from the	line number specified in the diff, patch
  tells	you the	offset.	 A single large	offset may be an indication that a
  hunk was installed in	the wrong place.  The patch command also tells you if
  a fuzz factor	was used to make the match, in which case you should be
  slightly suspicious.

NOTES

  There	are several things you should bear in mind if you are going to be
  sending out patches:

    +  [Tru64 UNIX]  It	is recommended that you	keep a <&lt;patchlevel.h>&gt; file
       that is patched to increment the	patch level as the first diff in the
       patch file you send out.	 If you	put a Prereq: line in with the patch,
       users will not be able to apply patches out of order without some
       warning.

    +  [Tru64 UNIX]  Make sure you specify the file names correctly, either
       in a context diff header	or with	an Index: line.	 If you	are patching
       something in a subdirectory, be sure to tell the	patch user to specify
       a -p option as needed.

    +  [Tru64 UNIX]  You can create a file by sending out a diff that com-
       pares a null file to the	file you want to create.  This works only if
       the file	you want to create does	not already exist in the target
       directory.

    +  [Tru64 UNIX]  Take care not to send out reversed	patches, since this
       makes users wonder whether they already applied the patch.

    +  [Tru64 UNIX]  While you may be able to put many diff listings into one
       file, it	is advisable to	group related patches into separate files.

    +  [Tru64 UNIX]  The patch command cannot tell if the line numbers are
       off in an ed script, and	can only detect	bad line numbers in a normal
       diff when it finds a change or a	delete command.

       [Tru64 UNIX]  A context diff using a fuzz factor	of 3 may have the
       same problem.  Until a suitable interactive interface is	added, you
       should probably do a context diff in these cases	to see if the changes
       make sense.  Compiling without errors is	a pretty good indication that
       the patch worked, but this is not an infallible indicator.

    +  [Tru64 UNIX]  The results of the	patch command are guaranteed to	be
       correct only when the patch is applied to exactly the same version of
       the file	from which the patch was generated.

    +  [Tru64 UNIX]  If	the code has been duplicated (for example, with
       #ifdef OLDCODE ...  #else ...  #endif), patch is	incapable of patching
       both versions, and, if patch works at all, it will likely patch the
       wrong version and tell you that it succeeded.

    +  If you apply a patch you've already applied, patch assumes it is	a
       reversed	patch, and offers to undo it.

DIAGNOSTICS

  [Tru64 UNIX]	The message Hmm... indicates that there	is unprocessed text
  in the patch file and	that patch is attempting to determine whether there
  is a patch in	that text and, if so, what kind	of patch it is.

  [Tru64 UNIX]	The patch command exits	with a nonzero status if any reject
  files	were created.  When applying a set of patches in a loop, you should
  check	this exit status, so you don't apply a later patch to a	partially
  patched file.

EXIT STATUS

  The following	exit values are	returned:

  0   Successful completion.

  1   One or more lines	were written to	a reject file.

  >&gt;1  An error occurred.

ENVIRONMENT VARIABLES

  The following	environment variables affect the execution of patch:

  LANG
      Provides a default value for the internationalization variables that
      are unset	or null. If LANG is unset or null, the corresponding value
      from the default locale is used.	If any of the internationalization
      variables	contain	an invalid setting, the	utility	behaves	as if none of
      the variables had	been defined.

  LC_ALL
      If set to	a non-empty string value, overrides the	values of all the
      other internationalization variables.

  LC_CTYPE
      Determines 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).

  LC_MESSAGES
      Determines the locale for	the format and contents	of diagnostic mes-
      sages written to standard	error.

  LC_TIME
      Determines the locale for	recognizing the	format of time stamps written
      by the diff command.

  NLSPATH
      Determines the location of message catalogues for	the processing of
      LC_MESSAGES.

FILES

  /tmp/patch*

SEE ALSO

  Commands:  diff(1)

  Standards:  standards(5)