1PATCH(1P)                  POSIX Programmer's Manual                 PATCH(1P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10
11

NAME

13       patch — apply changes to files
14

SYNOPSIS

16       patch [−blNR] [−c|−e|−n|−u] [−d dir] [−D define] [−i patchfile]
17           [−o outfile] [−p num] [−r rejectfile] [file]
18

DESCRIPTION

20       The patch utility shall read a source (patch) file  containing  any  of
21       four  forms  of difference (diff) listings produced by the diff utility
22       (normal, copied context, unified context, or in the style  of  ed)  and
23       apply  those  differences  to a file. By default, patch shall read from
24       the standard input.
25
26       The patch utility shall attempt to determine the type of the diff list‐
27       ing, unless overruled by a −c, −e, −n, or −u option.
28
29       If  the patch file contains more than one patch, patch shall attempt to
30       apply each of them as if they came from separate patch files. (In  this
31       case,  the  application shall ensure that the name of the patch file is
32       determinable for each diff listing.)
33

OPTIONS

35       The patch utility shall conform  to  the  Base  Definitions  volume  of
36       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.
37
38       The following options shall be supported:
39
40       −b        Save  a  copy of the original contents of each modified file,
41                 before the differences are applied, in a  file  of  the  same
42                 name  with  the  suffix  .orig  appended  to  it. If the file
43                 already exists, it shall be overwritten; if multiple  patches
44                 are applied to the same file, the .orig file shall be written
45                 only for the first patch. When the −o outfile option is  also
46                 specified,  file.orig  shall  not  be created but, if outfile
47                 already exists, outfile.orig shall be created.
48
49       −c        Interpret the patch file as a copied context difference  (the
50                 output  of  the  utility  diff  when the −c or −C options are
51                 specified).
52
53       −d dir    Change the current directory  to  dir  before  processing  as
54                 described in the EXTENDED DESCRIPTION section.
55
56       −D define Mark  changes  with  one of the following C preprocessor con‐
57                 structs:
58
59                     #ifdef define
60                     ...
61                     #endif
62
63                     #ifndef define
64                     ...
65                     #endif
66
67                 optionally combined with the C preprocessor construct  #else.
68                 If  the  patched  file  is processed with the C preprocessor,
69                 where the macro define is defined, the output  shall  contain
70                 the  changes from the patch file; otherwise, the output shall
71                 not contain the patches specified in the patch file.
72
73       −e        Interpret the patch file as an ed script, rather than a  diff
74                 script.
75
76       −i patchfile
77                 Read  the  patch information from the file named by the path‐
78                 name patchfile, rather than the standard input.
79
80       −l        (The letter ell.) Cause any sequence of <blank> characters in
81                 the  difference script to match any sequence of <blank> char‐
82                 acters in the input file. Other characters shall  be  matched
83                 exactly.
84
85       −n        Interpret the script as a normal difference.
86
87       −N        Ignore  patches  where  the  differences  have  already  been
88                 applied to the  file;  by  default,  already-applied  patches
89                 shall be rejected.
90
91       −o outfile
92                 Instead of modifying the files (specified by the file operand
93                 or the difference listings) directly, write  a  copy  of  the
94                 file  referenced  by each patch, with the appropriate differ‐
95                 ences applied, to outfile.  Multiple  patches  for  a  single
96                 file  shall  be  applied  to the intermediate versions of the
97                 file created by any previous patches,  and  shall  result  in
98                 multiple,  concatenated versions of the file being written to
99                 outfile.
100
101       −p num    For all pathnames in the patch file that indicate  the  names
102                 of  files  to be patched, delete num pathname components from
103                 the beginning of each pathname. If the pathname in the  patch
104                 file  is  absolute,  any  leading <slash> characters shall be
105                 considered the first component (that is,  −p 1  shall  remove
106                 the  leading <slash> characters). Specifying −p 0 shall cause
107                 the full pathname to be used. If −p is  not  specified,  only
108                 the basename (the final pathname component) shall be used.
109
110       −R        Reverse  the  sense of the patch script; that is, assume that
111                 the difference script was created from the new version to the
112                 old  version.   The −R option cannot be used with ed scripts.
113                 The patch utility shall attempt to reverse  each  portion  of
114                 the  script before applying it. Rejected differences shall be
115                 saved in swapped format. If this option is not specified, and
116                 until  a  portion  of the patch file is successfully applied,
117                 patch attempts to apply each portion in its reversed sense as
118                 well  as  in  its normal sense. If the attempt is successful,
119                 the user shall be prompted to determine whether the −R option
120                 should be set.
121
122       −r rejectfile
123                 Override  the  default  reject filename. In the default case,
124                 the reject file shall have the same name as the output  file,
125                 with the suffix .rej appended to it; see Patch Application.
126
127       −u        Interpret the patch file as a unified context difference (the
128                 output of the diff utility when the  −u  or  −U  options  are
129                 specified).
130

OPERANDS

132       The following operand shall be supported:
133
134       file      A pathname of a file to patch.
135

STDIN

137       See the INPUT FILES section.
138

INPUT FILES

140       Input files shall be text files.
141

ENVIRONMENT VARIABLES

143       The  following  environment  variables  shall  affect  the execution of
144       patch:
145
146       LANG      Provide a default value for  the  internationalization  vari‐
147                 ables  that are unset or null. (See the Base Definitions vol‐
148                 ume of POSIX.1‐2008, Section 8.2, Internationalization  Vari‐
149                 ables  the  precedence of internationalization variables used
150                 to determine the values of locale categories.)
151
152       LC_ALL    If set to a non-empty string value, override  the  values  of
153                 all the other internationalization variables.
154
155       LC_COLLATE
156                 Determine  the locale for the behavior of ranges, equivalence
157                 classes, and multi-character collating elements used  in  the
158                 extended  regular  expression  defined for the yesexpr locale
159                 keyword in the LC_MESSAGES category.
160
161       LC_CTYPE  Determine the locale for the interpretation of  sequences  of
162                 bytes of text data as characters (for example, single-byte as
163                 opposed to  multi-byte  characters  in  arguments  and  input
164                 files),  and  the  behavior  of character classes used in the
165                 extended regular expression defined for  the  yesexpr  locale
166                 keyword in the LC_MESSAGES category.
167
168       LC_MESSAGES
169                 Determine  the  locale used to process affirmative responses,
170                 and the locale used to affect  the  format  and  contents  of
171                 diagnostic messages and prompts written to standard error.
172
173       NLSPATH   Determine the location of message catalogs for the processing
174                 of LC_MESSAGES.
175
176       LC_TIME   Determine the locale for recognizing the format of file time‐
177                 stamps  written  by  the diff utility in a context-difference
178                 input file.
179

ASYNCHRONOUS EVENTS

181       Default.
182

STDOUT

184       Not used.
185

STDERR

187       The standard error shall be used for diagnostic and informational  mes‐
188       sages.
189

OUTPUT FILES

191       The  output  of the patch utility, the save files (.orig suffixes), and
192       the reject files (.rej suffixes) shall be text files.
193

EXTENDED DESCRIPTION

195       A patch file may contain patching instructions for more than one  file;
196       filenames  shall  be determined as specified in Filename Determination.
197       When the −b option is specified, for each patched  file,  the  original
198       shall  be  saved  in  a  file  of  the  same name with the suffix .orig
199       appended to it.
200
201       For each patched file, a reject file may also be created  as  noted  in
202       Patch  Application.   In  the  absence of a −r option, the name of this
203       file shall be formed by appending the suffix .rej to the original file‐
204       name.
205
206   Patch File Format
207       The  patch  file shall contain zero or more lines of header information
208       followed by one or more patches. Each patch shall contain zero or  more
209       lines  of filename identification in the format produced by the −c, −C,
210       −u, or −U options of the diff utility, and one or  more  sets  of  diff
211       output, which are customarily called hunks.
212
213       The  patch  utility  shall  recognize  the  following expression in the
214       header information:
215
216       Index: pathname
217             The file to be patched is named pathname.
218
219       If all lines (including headers) within a patch  begin  with  the  same
220       leading  sequence of <blank> characters, the patch utility shall remove
221       this sequence before proceeding. Within each patch, if the type of dif‐
222       ference  is  common context, the patch utility shall recognize the fol‐
223       lowing expressions:
224
225       *** filename timestamp
226             The patches arose from filename.
227
228       −−− filename timestamp
229             The patches should be applied to filename.
230
231       If the type of difference is unified context, the patch  utility  shall
232       recognize the following expressions:
233
234       −−− filename timestamp
235             The patches arose from filename.
236
237       +++ filename timestamp
238             The patches should be applied to filename.
239
240       Each  hunk  within  a  patch  shall be the diff output to change a line
241       range within the original file. The line numbers for  successive  hunks
242       within a patch shall occur in ascending order.
243
244   Filename Determination
245       If  no  file  operand  is  specified, patch shall perform the following
246       steps to determine the filename to use:
247
248        1. If the type of diff is context,  the  patch  utility  shall  delete
249           pathname  components (as specified by the −p option) from the file‐
250           name on the line beginning with "***" (if copied context) or  "−−−"
251           (if unified context), then test for the existence of this file rel‐
252           ative to the current directory (or the directory specified with the
253           −d  option).  If  the file exists, the patch utility shall use this
254           filename.
255
256        2. If the type of diff is context, the patch utility shall delete  the
257           pathname  components (as specified by the −p option) from the file‐
258           name on the line beginning with "−−−" (if copied context) or  "+++"
259           (if unified context), then test for the existence of this file rel‐
260           ative to the current directory (or the directory specified with the
261           −d  option).  If  the file exists, the patch utility shall use this
262           filename.
263
264        3. If the header information contains a line beginning with the string
265           Index:,  the  patch  utility  shall  delete pathname components (as
266           specified by the −p option) from this line, then test for the exis‐
267           tence of this file relative to the current directory (or the direc‐
268           tory specified with the −d option). If the file exists,  the  patch
269           utility shall use this filename.
270
271        4. If  an  SCCS directory exists in the current directory, patch shall
272           attempt to perform a get −e SCCS/s.filename command to retrieve  an
273           editable version of the file. If the file exists, the patch utility
274           shall use this filename.
275
276        5. The patch utility shall write  a  prompt  to  standard  output  and
277           request a filename interactively from the controlling terminal (for
278           example, /dev/tty).
279
280   Patch Application
281       If the −c, −e, −n, or −u option is present,  the  patch  utility  shall
282       interpret  information within each hunk as a copied context difference,
283       an ed difference, a normal difference, or a unified context difference,
284       respectively. In the absence of any of these options, the patch utility
285       shall determine the type of difference based on the format of  informa‐
286       tion within the hunk.
287
288       For each hunk, the patch utility shall begin to search for the place to
289       apply the patch at the line number at the beginning of the  hunk,  plus
290       or minus any offset used in applying the previous hunk. If lines match‐
291       ing the hunk context are not found, patch shall scan both forwards  and
292       backwards  at  least  1000 bytes for a set of lines that match the hunk
293       context.
294
295       If no such place is found and it is a context difference, then  another
296       scan  shall take place, ignoring the first and last line of context. If
297       that fails, the first two and  last  two  lines  of  context  shall  be
298       ignored and another scan shall be made. Implementations may search more
299       extensively for installation locations.
300
301       If no location can be found, the patch utility shall append the hunk to
302       the  reject  file. A rejected hunk that is a copied context difference,
303       an ed difference, or a normal difference shall be  written  in  copied-
304       context-difference  format  regardless of the format of the patch file.
305       It is implementation-defined whether a rejected hunk that is a  unified
306       context difference is written in copied-context-difference format or in
307       unified-context-difference format.  If the input was a  normal  or  ed-
308       style  difference,  the  reject  file may contain differences with zero
309       lines of context. The line numbers on the hunks in the reject file  may
310       be  different  from the line numbers in the patch file since they shall
311       reflect the approximate locations for the failed hunks in the new  file
312       rather than the old one.
313
314       If  the  type of patch is an ed diff, the implementation may accomplish
315       the patching by invoking the ed utility.
316

EXIT STATUS

318       The following exit values shall be returned:
319
320        0    Successful completion.
321
322        1    One or more lines were written to a reject file.
323
324       >1    An error occurred.
325

CONSEQUENCES OF ERRORS

327       Patches that cannot be correctly placed in the file shall be written to
328       a reject file.
329
330       The following sections are informative.
331

APPLICATION USAGE

333       The −R option does not work with ed scripts because there is too little
334       information to reconstruct the reverse operation.
335
336       The −p option makes it possible to customize a patch file to local user
337       directory structures without manually editing the patch file. For exam‐
338       ple, if the filename in the patch file was:
339
340           /curds/whey/src/blurfl/blurfl.c
341
342       Setting −p 0 gives the entire pathname unmodified; −p 1 gives:
343
344           curds/whey/src/blurfl/blurfl.c
345
346       without the leading <slash>, −p 4 gives:
347
348           blurfl/blurfl.c
349
350       and not specifying −p at all gives:
351
352           blurfl.c .
353

EXAMPLES

355       None.
356

RATIONALE

358       Some of the functionality in historical patch implementations  was  not
359       specified. The following documents those features present in historical
360       implementations that have not been specified.
361
362       A deleted piece of functionality was the '+' pseudo-option allowing  an
363       additional  set  of  options and a patch file operand to be given. This
364       was seen as being insufficiently useful to standardize.
365
366       In historical implementations, if the string "Prereq:" appeared in  the
367       header,  the  patch  utility would search for the corresponding version
368       information (the string specified in the header, delimited  by  <blank>
369       characters  or  the beginning or end of a line or the file) anywhere in
370       the original file. This was deleted  as  too  simplistic  and  insuffi‐
371       ciently trustworthy a mechanism to standardize. For example, if:
372
373           Prereq: 1.2
374
375       were  in  the  header,  the presence of a delimited 1.2 anywhere in the
376       file would satisfy the prerequisite.
377
378       The following options were dropped from historical  implementations  of
379       patch as insufficiently useful to standardize:
380
381       −b        The −b option historically provided a method for changing the
382                 name extension of the backup file  from  the  default  .orig.
383                 This  option has been modified and retained in this volume of
384                 POSIX.1‐2008.
385
386       −F        The −F option specified the number of lines of a context diff
387                 to ignore when searching for a place to install a patch.
388
389       −f        The  −f option historically caused patch not to request addi‐
390                 tional information from the user.
391
392       −r        The −r option historically provided a  method  of  overriding
393                 the extension of the reject file from the default .rej.
394
395       −s        The  −s  option  historically  caused  patch to work silently
396                 unless an error occurred.
397
398       −x        The −x option historically set internal debugging flags.
399
400       In some file system implementations, the saving of  a  .orig  file  may
401       produce  unwanted results. In the case of 12, 13, or 14-character file‐
402       names (on file systems supporting 14-character maximum filenames),  the
403       .orig  file  overwrites  the  new file. The reject file may also exceed
404       this filename limit. It was suggested, due to some historical practice,
405       that  a  <tilde>  ('~')  suffix be used instead of .orig and some other
406       character instead of the .rej suffix. This was rejected because  it  is
407       not  obvious  to  the  user which file is which. The suffixes .orig and
408       .rej are clearer and more understandable.
409
410       The −b option has the opposite sense  in  some  historical  implementa‐
411       tions—do  not save the .orig file. The default case here is not to save
412       the files, making patch behave more consistently with the  other  stan‐
413       dard utilities.
414
415       The  −w option in early proposals was changed to −l to match historical
416       practice.
417
418       The −N option was included because without it, a non-interactive appli‐
419       cation cannot reject previously applied patches. For example, if a user
420       is piping the output of diff into the patch utility, and the user  only
421       wants  to  patch  a  file  to a newer version non-interactively, the −N
422       option is required.
423
424       Changes to the −l option description were proposed  to  allow  matching
425       across  <newline>  characters  in  addition to just <blank> characters.
426       Since this is not historical practice, and since some ambiguities could
427       result,  it  is suggested that future developments in this area utilize
428       another option letter, such as −L.
429
430       The −u option of GNU patch has been added, along with support for  uni‐
431       fied context formats.
432

FUTURE DIRECTIONS

434       None.
435

SEE ALSO

437       diff, ed
438
439       The  Base  Definitions  volume  of POSIX.1‐2008, Chapter 8, Environment
440       Variables, Section 12.2, Utility Syntax Guidelines
441
443       Portions of this text are reprinted and reproduced in  electronic  form
444       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
445       -- Portable Operating System Interface (POSIX),  The  Open  Group  Base
446       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
447       cal and Electronics Engineers,  Inc  and  The  Open  Group.   (This  is
448       POSIX.1-2008  with  the  2013  Technical Corrigendum 1 applied.) In the
449       event of any discrepancy between this version and the original IEEE and
450       The  Open Group Standard, the original IEEE and The Open Group Standard
451       is the referee document. The original Standard can be  obtained  online
452       at http://www.unix.org/online.html .
453
454       Any  typographical  or  formatting  errors that appear in this page are
455       most likely to have been introduced during the conversion of the source
456       files  to  man page format. To report such errors, see https://www.ker
457       nel.org/doc/man-pages/reporting_bugs.html .
458
459
460
461IEEE/The Open Group                  2013                            PATCH(1P)
Impressum