man1p/patch.1p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "PATCH" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" patch
   4 .SH NAME
   5 patch \- apply changes to files
   6 .SH SYNOPSIS
   7 .LP
   8 \fBpatch\fP \fB[\fP\fB-blNR\fP\fB][\fP \fB-c| -e| -n\fP\fB][\fP\fB-d\fP
   9 \fIdir\fP\fB][\fP\fB-D\fP \fIdefine\fP\fB][\fP\fB-i\fP \fIpatchfile\fP\fB]
  10 .br
  11 \fP \fB\ \ \ \ \ \ \fP \fB[\fP\fB-o\fP \fIoutfile\fP\fB][\fP\fB-p\fP
  12 \fInum\fP\fB][\fP\fB-r\fP \fIrejectfile\fP\fB][\fP\fIfile\fP\fB]\fP\fB\fP
  13 .SH DESCRIPTION
  14 .LP
  15 The \fIpatch\fP utility shall read a source (patch) file containing
  16 any of the three forms of difference (diff) listings
  17 produced by the \fIdiff\fP utility (normal, context, or in the style
  18 of \fIed\fP) and apply those differences to a file. By default, \fIpatch\fP
  19 shall read from the standard
  20 input.
  21 .LP
  22 The \fIpatch\fP utility shall attempt to determine the type of the
  23 \fIdiff\fP listing,
  24 unless overruled by a \fB-c\fP, \fB-e\fP, or \fB-n\fP option.
  25 .LP
  26 If the patch file contains more than one patch, \fIpatch\fP shall
  27 attempt to apply each of them as if they came from separate
  28 patch files. (In this case, the application shall ensure that the
  29 name of the patch file is determinable for each \fIdiff\fP listing.)
  30 .SH OPTIONS
  31 .LP
  32 The \fIpatch\fP utility shall conform to the Base Definitions volume
  33 of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility Syntax Guidelines.
  34 .LP
  35 The following options shall be supported:
  36 .TP 7
  37 \fB-b\fP
  38 Save a copy of the original contents of each modified file, before
  39 the differences are applied, in a file of the same name with
  40 the suffix \fB.orig\fP appended to it. If the file already exists,
  41 it shall be overwritten; if multiple patches are applied to the
  42 same file, the \fB.orig\fP file shall be written only for the first
  43 patch. When the \fB-o\fP \fIoutfile\fP option is also
  44 specified, \fIfile\fP \fB.orig\fP shall not be created but, if \fIoutfile\fP
  45 already exists, \fIoutfile\fP \fB.orig\fP shall
  46 be created.
  47 .TP 7
  48 \fB-c\fP
  49 Interpret the patch file as a context difference (the output of the
  50 utility \fIdiff\fP
  51 when the \fB-c\fP or \fB-C\fP options are specified).
  52 .TP 7
  53 \fB-d\ \fP \fIdir\fP
  54 Change the current directory to \fIdir\fP before processing as described
  55 in the EXTENDED DESCRIPTION section.
  56 .TP 7
  57 \fB-D\ \fP \fIdefine\fP
  58 Mark changes with one of the following C preprocessor constructs:
  59 .sp
  60 .RS
  61 .nf
  62
  63 \fB#ifdef define
  64 \&...
  65 #endif
  66 .sp
  67
  68 #ifndef define
  69 \&...
  70 #endif
  71 \fP
  72 .fi
  73 .RE
  74 .LP
  75 optionally combined with the C preprocessor construct \fB#else\fP.
  76 If the patched file is processed with the C preprocessor,
  77 where the macro \fIdefine\fP is defined, the output shall contain
  78 the changes from the patch file; otherwise, the output shall not
  79 contain the patches specified in the patch file.
  80 .TP 7
  81 \fB-e\fP
  82 Interpret the patch file as an \fIed\fP script, rather than a \fIdiff\fP
  83 script.
  84 .TP 7
  85 \fB-i\ \fP \fIpatchfile\fP
  86 Read the patch information from the file named by the pathname \fIpatchfile\fP,
  87 rather than the standard input.
  88 .TP 7
  89 \fB-l\fP
  90 (The letter ell.) Cause any sequence of <blank>s in the difference
  91 script to match any sequence of <blank>s in the
  92 input file. Other characters shall be matched exactly.
  93 .TP 7
  94 \fB-n\fP
  95 Interpret the script as a normal difference.
  96 .TP 7
  97 \fB-N\fP
  98 Ignore patches where the differences have already been applied to
  99 the file; by default, already-applied patches shall be
 100 rejected.
 101 .TP 7
 102 \fB-o\ \fP \fIoutfile\fP
 103 Instead of modifying the files (specified by the \fIfile\fP operand
 104 or the difference listings) directly, write a copy of the
 105 file referenced by each patch, with the appropriate differences applied,
 106 to \fIoutfile\fP. Multiple patches for a single file
 107 shall be applied to the intermediate versions of the file created
 108 by any previous patches, and shall result in multiple,
 109 concatenated versions of the file being written to \fIoutfile\fP.
 110 .TP 7
 111 \fB-p\ \fP \fInum\fP
 112 For all pathnames in the patch file that indicate the names of files
 113 to be patched, delete \fInum\fP pathname components from
 114 the beginning of each pathname. If the pathname in the patch file
 115 is absolute, any leading slashes shall be considered the first
 116 component (that is, \fB-p\ 1\fP shall remove the leading slashes).
 117 Specifying \fB-p\ 0\fP shall cause the full pathname
 118 to be used. If \fB-p\fP is not specified, only the basename (the final
 119 pathname component) shall be used.
 120 .TP 7
 121 \fB-R\fP
 122 Reverse the sense of the patch script; that is, assume that the difference
 123 script was created from the new version to the old
 124 version. The \fB-R\fP option cannot be used with \fIed\fP scripts.
 125 The \fIpatch\fP utility
 126 shall attempt to reverse each portion of the script before applying
 127 it. Rejected differences shall be saved in swapped format. If
 128 this option is not specified, and until a portion of the patch file
 129 is successfully applied, \fIpatch\fP attempts to apply each
 130 portion in its reversed sense as well as in its normal sense. If the
 131 attempt is successful, the user shall be prompted to determine
 132 whether the \fB-R\fP option should be set.
 133 .TP 7
 134 \fB-r\ \fP \fIrejectfile\fP
 135 Override the default reject filename. In the default case, the reject
 136 file shall have the same name as the output file, with
 137 the suffix \fB.rej\fP appended to it; see Patch Application .
 138 .sp
 139 .SH OPERANDS
 140 .LP
 141 The following operand shall be supported:
 142 .TP 7
 143 \fIfile\fP
 144 A pathname of a file to patch.
 145 .sp
 146 .SH STDIN
 147 .LP
 148 See the INPUT FILES section.
 149 .SH INPUT FILES
 150 .LP
 151 Input files shall be text files.
 152 .SH ENVIRONMENT VARIABLES
 153 .LP
 154 The following environment variables shall affect the execution of
 155 \fIpatch\fP:
 156 .TP 7
 157 \fILANG\fP
 158 Provide a default value for the internationalization variables that
 159 are unset or null. (See the Base Definitions volume of
 160 IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables
 161 for
 162 the precedence of internationalization variables used to determine
 163 the values of locale categories.)
 164 .TP 7
 165 \fILC_ALL\fP
 166 If set to a non-empty string value, override the values of all the
 167 other internationalization variables.
 168 .TP 7
 169 \fILC_CTYPE\fP
 170 Determine the locale for the interpretation of sequences of bytes
 171 of text data as characters (for example, single-byte as
 172 opposed to multi-byte characters in arguments and input files).
 173 .TP 7
 174 \fILC_MESSAGES\fP
 175 Determine the locale that should be used to affect the format and
 176 contents of diagnostic messages written to standard error and
 177 informative messages written to standard output.
 178 .TP 7
 179 \fINLSPATH\fP
 180 Determine the location of message catalogs for the processing of \fILC_MESSAGES
 181 \&.\fP
 182 .TP 7
 183 \fILC_TIME\fP
 184 Determine the locale for recognizing the format of file timestamps
 185 written by the \fIdiff\fP utility in a context-difference input file.
 186 .sp
 187 .SH ASYNCHRONOUS EVENTS
 188 .LP
 189 Default.
 190 .SH STDOUT
 191 .LP
 192 Not used.
 193 .SH STDERR
 194 .LP
 195 The standard error shall be used for diagnostic and informational
 196 messages.
 197 .SH OUTPUT FILES
 198 .LP
 199 The output of the \fIpatch\fP utility, the save files ( \fB.orig\fP
 200 suffixes), and the reject files ( \fB.rej\fP suffixes)
 201 shall be text files.
 202 .SH EXTENDED DESCRIPTION
 203 .LP
 204 A patch file may contain patching instructions for more than one file;
 205 filenames shall be determined as specified in Filename Determination
 206 \&. When the \fB-b\fP option is specified, for each patched file, the
 207 original shall
 208 be saved in a file of the same name with the suffix \fB.orig\fP appended
 209 to it.
 210 .LP
 211 For each patched file, a reject file may also be created as noted
 212 in Patch Application . In the
 213 absence of a \fB-r\fP option, the name of this file shall be formed
 214 by appending the suffix \fB.rej\fP to the original
 215 filename.
 216 .SS Patch File Format
 217 .LP
 218 The patch file shall contain zero or more lines of header information
 219 followed by one or more patches. Each patch shall contain
 220 zero or more lines of filename identification in the format produced
 221 by \fIdiff\fP \fB-c\fP,
 222 and one or more sets of \fIdiff\fP output, which are customarily called
 223 \fIhunks\fP.
 224 .LP
 225 The \fIpatch\fP utility shall recognize the following expression in
 226 the header information:
 227 .TP 7
 228 \fBIndex:\ \fP \fIpathname\fP
 229 .sp
 230 The file to be patched is named \fIpathname\fP.
 231 .sp
 232 .LP
 233 If all lines (including headers) within a patch begin with the same
 234 leading sequence of <blank>s, the \fIpatch\fP utility
 235 shall remove this sequence before proceeding. Within each patch, if
 236 the type of difference is context, the \fIpatch\fP utility
 237 shall recognize the following expressions:
 238 .TP 7
 239 ***\ \fIfilename\ timestamp\fP
 240 .sp
 241 The patches arose from \fIfilename\fP.
 242 .TP 7
 243 ---\ \fIfilename\ timestamp\fP
 244 .sp
 245 The patches should be applied to \fIfilename\fP.
 246 .sp
 247 .LP
 248 Each hunk within a patch shall be the \fIdiff\fP output to change
 249 a line range within the
 250 original file. The line numbers for successive hunks within a patch
 251 shall occur in ascending order.
 252 .SS Filename Determination
 253 .LP
 254 If no \fIfile\fP operand is specified, \fIpatch\fP shall perform the
 255 following steps to determine the filename to use:
 256 .IP " 1." 4
 257 If the type of \fIdiff\fP is context, the \fIpatch\fP utility shall
 258 delete pathname
 259 components (as specified by the \fB-p\fP option) from the filename
 260 on the line beginning with \fB"***"\fP , then test for the
 261 existence of this file relative to the current directory (or the directory
 262 specified with the \fB-d\fP option). If the file
 263 exists, the \fIpatch\fP utility shall use this filename.
 264 .LP
 265 .IP " 2." 4
 266 If the type of \fIdiff\fP is context, the \fIpatch\fP utility shall
 267 delete the pathname
 268 components (as specified by the \fB-p\fP option) from the filename
 269 on the line beginning with \fB"---"\fP , then test for the
 270 existence of this file relative to the current directory (or the directory
 271 specified with the \fB-d\fP option). If the file
 272 exists, the \fIpatch\fP utility shall use this filename.
 273 .LP
 274 .IP " 3." 4
 275 If the header information contains a line beginning with the string
 276 \fBIndex:\fP, the \fIpatch\fP utility shall delete
 277 pathname components (as specified by the \fB-p\fP option) from this
 278 line, then test for the existence of this file relative to the
 279 current directory (or the directory specified with the \fB-d\fP option).
 280 If the file exists, the \fIpatch\fP utility shall use
 281 this filename.
 282 .LP
 283 .IP " 4." 4
 284 If an \fBSCCS\fP directory exists in the current directory, \fIpatch\fP
 285 shall attempt to perform a \fIget\fP \fB-e\fP \fBSCCS/s.\fP \fIfilename\fP
 286 command to retrieve an editable version of the
 287 file. If the file exists, the \fIpatch\fP utility shall use this filename.
 288 .LP
 289 .IP " 5." 4
 290 The \fIpatch\fP utility shall write a prompt to standard output and
 291 request a filename interactively from the controlling
 292 terminal (for example, \fB/dev/tty\fP).
 293 .LP
 294 .SS Patch Application
 295 .LP
 296 If the \fB-c\fP, \fB-e\fP, or \fB-n\fP option is present, the \fIpatch\fP
 297 utility shall interpret information within each
 298 hunk as a context difference, an \fIed\fP difference, or a normal
 299 difference, respectively. In
 300 the absence of any of these options, the \fIpatch\fP utility shall
 301 determine the type of difference based on the format of
 302 information within the hunk.
 303 .LP
 304 For each hunk, the \fIpatch\fP utility shall begin to search for the
 305 place to apply the patch at the line number at the
 306 beginning of the hunk, plus or minus any offset used in applying the
 307 previous hunk. If lines matching the hunk context are not
 308 found, \fIpatch\fP shall scan both forwards and backwards at least
 309 1000 bytes for a set of lines that match the hunk context.
 310 .LP
 311 If no such place is found and it is a context difference, then another
 312 scan shall take place, ignoring the first and last line
 313 of context. If that fails, the first two and last two lines of context
 314 shall be ignored and another scan shall be made.
 315 Implementations may search more extensively for installation locations.
 316 .LP
 317 If no location can be found, the \fIpatch\fP utility shall append
 318 the hunk to the reject file. The rejected hunk shall be
 319 written in context-difference format regardless of the format of the
 320 patch file. If the input was a normal or \fIed\fP-style difference,
 321 the reject file may contain differences with zero lines of context.
 322 The line
 323 numbers on the hunks in the reject file may be different from the
 324 line numbers in the patch file since they shall reflect the
 325 approximate locations for the failed hunks in the new file rather
 326 than the old one.
 327 .LP
 328 If the type of patch is an \fIed\fP diff, the implementation may accomplish
 329 the patching by
 330 invoking the \fIed\fP utility.
 331 .SH EXIT STATUS
 332 .LP
 333 The following exit values shall be returned:
 334 .TP 7
 335 \ 0
 336 Successful completion.
 337 .TP 7
 338 \ 1
 339 One or more lines were written to a reject file.
 340 .TP 7
 341 >1
 342 An error occurred.
 343 .sp
 344 .SH CONSEQUENCES OF ERRORS
 345 .LP
 346 Patches that cannot be correctly placed in the file shall be written
 347 to a reject file.
 348 .LP
 349 \fIThe following sections are informative.\fP
 350 .SH APPLICATION USAGE
 351 .LP
 352 The \fB-R\fP option does not work with \fIed\fP scripts because there
 353 is too little
 354 information to reconstruct the reverse operation.
 355 .LP
 356 The \fB-p\fP option makes it possible to customize a patch file to
 357 local user directory structures without manually editing the
 358 patch file. For example, if the filename in the patch file was:
 359 .sp
 360 .RS
 361 .nf
 362
 363 \fB/curds/whey/src/blurfl/blurfl.c
 364 \fP
 365 .fi
 366 .RE
 367 .LP
 368 Setting \fB-p\ 0\fP gives the entire pathname unmodified; \fB-p\ 1\fP
 369 gives:
 370 .sp
 371 .RS
 372 .nf
 373
 374 \fBcurds/whey/src/blurfl/blurfl.c
 375 \fP
 376 .fi
 377 .RE
 378 .LP
 379 without the leading slash, \fB-p\ 4\fP gives:
 380 .sp
 381 .RS
 382 .nf
 383
 384 \fBblurfl/blurfl.c
 385 \fP
 386 .fi
 387 .RE
 388 .LP
 389 and not specifying \fB-p\fP at all gives:
 390 .sp
 391 .RS
 392 .nf
 393
 394 \fBblurfl.c .
 395 \fP
 396 .fi
 397 .RE
 398 .SH EXAMPLES
 399 .LP
 400 None.
 401 .SH RATIONALE
 402 .LP
 403 Some of the functionality in historical \fIpatch\fP implementations
 404 was not specified. The following documents those features
 405 present in historical implementations that have not been specified.
 406 .LP
 407 A deleted piece of functionality was the \fB'+'\fP pseudo-option allowing
 408 an additional set of options and a patch file
 409 operand to be given. This was seen as being insufficiently useful
 410 to standardize.
 411 .LP
 412 In historical implementations, if the string \fB"Prereq:"\fP appeared
 413 in the header, the \fIpatch\fP utility would search
 414 for the corresponding version information (the string specified in
 415 the header, delimited by <blank>s or the beginning or end
 416 of a line or the file) anywhere in the original file. This was deleted
 417 as too simplistic and insufficiently trustworthy a mechanism
 418 to standardize. For example, if:
 419 .sp
 420 .RS
 421 .nf
 422
 423 \fBPrereq: 1.2
 424 \fP
 425 .fi
 426 .RE
 427 .LP
 428 were in the header, the presence of a delimited 1.2 anywhere in the
 429 file would satisfy the prerequisite.
 430 .LP
 431 The following options were dropped from historical implementations
 432 of \fIpatch\fP as insufficiently useful to standardize:
 433 .TP 7
 434 \fB-b\fP
 435 The \fB-b\fP option historically provided a method for changing the
 436 name extension of the backup file from the default
 437 \fB\&.orig\fP. This option has been modified and retained in this volume
 438 of IEEE\ Std\ 1003.1-2001.
 439 .TP 7
 440 \fB-F\fP
 441 The \fB-F\fP option specified the number of lines of a context diff
 442 to ignore when searching for a place to install a
 443 patch.
 444 .TP 7
 445 \fB-f\fP
 446 The \fB-f\fP option historically caused \fIpatch\fP not to request
 447 additional information from the user.
 448 .TP 7
 449 \fB-r\fP
 450 The \fB-r\fP option historically provided a method of overriding the
 451 extension of the reject file from the default
 452 \fB\&.rej\fP.
 453 .TP 7
 454 \fB-s\fP
 455 The \fB-s\fP option historically caused \fIpatch\fP to work silently
 456 unless an error occurred.
 457 .TP 7
 458 \fB-x\fP
 459 The \fB-x\fP option historically set internal debugging flags.
 460 .sp
 461 .LP
 462 In some file system implementations, the saving of a \fB.orig\fP file
 463 may produce unwanted results. In the case of 12, 13, or
 464 14-character filenames (on file systems supporting 14-character maximum
 465 filenames), the \fB.orig\fP file overwrites the new file.
 466 The reject file may also exceed this filename limit. It was suggested,
 467 due to some historical practice, that a tilde (
 468 \fB'~'\fP ) suffix be used instead of \fB.orig\fP and some other character
 469 instead of the \fB.rej\fP suffix. This was
 470 rejected because it is not obvious to the user which file is which.
 471 The suffixes \fB.orig\fP and \fB.rej\fP are clearer and more
 472 understandable.
 473 .LP
 474 The \fB-b\fP option has the opposite sense in some historical implementations-do
 475 not save the \fB.orig\fP file. The default
 476 case here is not to save the files, making \fIpatch\fP behave more
 477 consistently with the other standard utilities.
 478 .LP
 479 The \fB-w\fP option in early proposals was changed to \fB-l\fP to
 480 match historical practice.
 481 .LP
 482 The \fB-N\fP option was included because without it, a non-interactive
 483 application cannot reject previously applied patches.
 484 For example, if a user is piping the output of \fIdiff\fP into the
 485 \fIpatch\fP utility, and
 486 the user only wants to patch a file to a newer version non-interactively,
 487 the \fB-N\fP option is required.
 488 .LP
 489 Changes to the \fB-l\fP option description were proposed to allow
 490 matching across <newline>s in addition to just
 491 <blank>s. Since this is not historical practice, and since some ambiguities
 492 could result, it is suggested that future
 493 developments in this area utilize another option letter, such as \fB-L\fP.
 494 .SH FUTURE DIRECTIONS
 495 .LP
 496 None.
 497 .SH SEE ALSO
 498 .LP
 499 \fIed\fP , \fIdiff\fP
 500 .SH COPYRIGHT
 501 Portions of this text are reprinted and reproduced in electronic form
 502 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 503 -- Portable Operating System Interface (POSIX), The Open Group Base
 504 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 505 Electrical and Electronics Engineers, Inc and The Open Group. In the
 506 event of any discrepancy between this version and the original IEEE and
 507 The Open Group Standard, the original IEEE and The Open Group Standard
 508 is the referee document. The original Standard can be obtained online at
 509 http://www.opengroup.org/unix/online.html .